AI invoice reader project (TypeScript) · Chapter 8 of 12
The review API
By the end of this chapter you can give Vaishali her review queue as an API: list what waits for her, approve an invoice, correct the fields the model read wrong (keeping every change), and make sure that when two reviewers press a button on the same task at the same moment, only one of them closes it, with SELECT ... FOR UPDATE. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: People and volume
- 3 tasks
- TypeScript
- In the all labs plan
The first 2 chapters of AI invoice reader project (TypeScript) are free. This one comes with the all labs plan.
Why you need this
Chapter 7 stores every invoice and opens a review task for the ones a person must see. But a task can only be read in psql. Vaishali cannot close one, and she certainly cannot fix one.
Two real ones are waiting. swarnim-ssl-2219.pdf prints 08/10/2026, and the model stored 10 August. kavach-kss-1017.pdf prints the GSTIN 29AAHFK7812P1ZK: a typo on the vendor's own bill (Kavach Security's GSTIN on its September invoice is 29AAHFK8812P1ZK). The model copied it as printed, as it should, and the check character rule caught it. That is the September mistake that would have lost the GST input credit on Kavach's ₹13,593.60 of IGST. Vaishali needs to put in the right date and the right GSTIN, and Parda needs to remember that she did: what was stored, what she changed it to, and who.
And at month-end Vaishali is not alone. A colleague from accounts helps with the close, and both open the queue. If both press a button on the same task in the same second, today's code would let both win.
What you build: 3 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
service.ts: the queue, and taking a task
In src/review/service.ts write openTasks(): every open review task joined to its invoice (innerJoin on the invoice's id), oldest first (createdAt, then id), each { taskId, invoiceId, file, venue, reason, createdAt: as an ISO string }. Then take(tx, taskId), inside a transaction the caller made: the task by its id (404 not_found when there is none: throw new AppError(404, 'not_found', ...)); a task whose status is not 'open' throws new AppError(409, 'already_closed', a sentence naming task.closedBy); otherwise return { task, invoice } with its invoice.
The Check reads five invoices with the given pipeline (four need review), compares your list with its own query, then takes a task, task 999 and a closed task.
- Task 2
service.ts: approving and correcting
Write approve(taskId, reviewer): in one db.transaction, take the task; an invoice with no data throws new AppError(422, 'no_data', ...); otherwise close(tx, task, reviewer, 'approved', 'approved') (given) and return { taskId, invoiceId, status: 'approved' }. Then correct(taskId, reviewer, changes): in one transaction, take the task; a key of changes that is not one of FIELDS throws AppError(422, 'bad_correction'); Invoice.safeParse({ ...data, ...changes }) (a failure throws AppError(422, 'bad_correction', a sentence, the issues as "<path>: <message>")); checkInvoice it. For each changed field whose value differs from the stored one (compare JSON.stringify of both): insert a correction (old, new, by: reviewer.email) and upsert its invoice_fields row with the new value, confidence 1 and reasons [
corrected by ${reviewer.name}]. Save the new data and problems. No problems left: close the task ('corrected', 'approved'); otherwise set the task's reason to the problems' messages joined with "; ". Return { taskId, invoiceId, status, problems }.The Check approves deccan-dpb-1152.pdf (its total is printed wrong: Vaishali pays what was billed), tries to approve the scanned bill, corrects swarnim-ssl-2219.pdf's date (read month first) after two bad corrections, then gives kavach-kss-1017.pdf another wrong GSTIN and then the right one.
- Task 3 · interview question
Interview: service.ts, one reviewer per task
Make take read the task with .for('update') at the end of its select (SELECT ... FOR UPDATE): its row stays locked until the transaction ends, and another take of it waits.
The Check holds a task's row locked in a transaction of its own while your approve runs: approve must wait, and once the check closes the task as another reviewer and commits, your approve must throw the 409. Then GET /review/tasks as Omkar (403) and as Vaishali (200).
Nikhil will ask: Vaishali and her colleague open the same task and both press Approve. What happens without FOR UPDATE, and what does it do?
What you will learn
- A join that gives pairs: a task and its invoice in one query, with innerJoin.
- Approve, correct, reject: what each means for the invoice and the task.
- A correction, checked again: the whole invoice validated with the change in it (safeParse), and the rules run again.
- The corrections table: old value, new value, who, when; and onConflictDoUpdate.
- A lost update: two reviewers who both read "open", for real.
- Row locks: SELECT ... FOR UPDATE (.for('update')), who waits, and what they see after.
More in People and volume
Build The review API yourself
Parda's venues get invoices from sound, printing and canteen vendors, typed and messy. You build the pipeline that reads them, checks every rupee, and sends the doubtful ones to a person. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of AI invoice reader project (TypeScript) are free. This one comes with the all labs plan.