AI invoice reader project (TypeScript) · Chapter 2 of 12

Reading PDFs

By the end of this chapter you know what a PDF holds inside, you can turn the pieces of text on each page back into lines that keep their columns, refuse a file that is too big, too long or not a PDF at all, and tell a PDF with text from a photo of a paper bill. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: From PDF to data
  • 3 tasks
  • TypeScript
  • Free chapter

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.

Why you need this

From chapter 4 on, a model reads Parda's invoices. A model reads text, so the text you hand it is all it will ever know about the invoice. If the text runs two columns together, mixes up which number belongs to which line, or is empty, no model can put it right.

Chapter 1's quickText was good enough for two regexes. Look at what it made of Swarnim's invoice:

GSTIN: 27ABFPS4418K1ZB Phone: +91 98220 47135
TAX INVOICEInvoice No: SSL/2207
Date: 01/10/2026
...
1 Line Array Speaker Set (per day) 2 set 6,500.00 13,000.00

The invoice prints "TAX INVOICE" at the right and "Invoice No: SSL/2207" at the left, a little lower. Quick reading glued them into one word, in the order they were drawn, and every table row lost its columns: is 2 the quantity or part of the name? For Mauli Bakery's paper bill, which Omkar photographed and sent as a PDF, it gave "": nothing at all. The reader must keep each line's columns apart, say which page a line came from (Mudran Press's 24-line order runs over two pages), refuse a 40 MB forward or a text file renamed .pdf before wasting work on it, and notice the photo, so that Vaishali looks at it instead of a model guessing.

The lesson

Tour of the codebase

New or changed since chapter 1:

src/pdf/reader.ts                    yours: TextPiece, the three constants and pagePieces (given),
                                     layoutPage (Task 1), readPdf (Task 2), PdfText's getters (Task 3)
src/modules/reading/reading.routes.ts   given: POST /invoices/text {"file"}
src/modules/files.ts                 given: FileIn, and invoiceText (chapter 4 uses it:
                                     the text, or 422 needs_ocr)
src/app.ts                           changed: uses the reading router
src/inbox.ts, src/baseline.ts        now given: chapter 1's code

POST /invoices/text takes {"file": "joshi-jfb-4410.pdf"}, finds the file with chapter 1's inboxPath (which refuses a name outside the inbox), and answers with the page count, the number of characters, needsOcr and the text. Before you write anything it answers 500, and the log says:

Error: Task 2: readPdf is not written yet
...

What a PDF holds

A PDF is not a picture of a page and not a text file. It is a list of drawing commands. Parda's invoices are plain ASCII on purpose, so you can look inside one with head:

$ head -c 600 data/inbox/mauli-mb-212.pdf
%PDF-1.4
1 0 obj
<< /Type /Catalog /Pages 2 0 R >>
endobj
2 0 obj
<< /Type /Pages /Kids [7 0 R] /Count 1 >>
endobj
3 0 obj
<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>
endobj
...
6 0 obj
<< /Length 1090 >>
stream
BT /F2 15 Tf 1 0 0 1 40.0 790.0 Tm (Mauli Bakery) Tj ET

Numbered objects: a catalog, a list of pages, the fonts. Then the page's content stream draws the invoice:

BT /F2 11 Tf 1 0 0 1 40.0 726.0 Tm (Bill No. MB-212) Tj ET
BT /F1 11 Tf 1 0 0 1 300.0 726.0 Tm (Dt. 3.10.26) Tj ET
BT /F1 10 Tf 1 0 0 1 50.0 682.0 Tm (1\) Pav - 60 ladi x 30 = 1,800) Tj ET

Each line says: use font F2 at size 11 (Tf), move to x 40, y 726 (Tm, in points, 1/72 of an inch, from the bottom left of the page), and draw this text (Tj). There are no lines, columns or tables in a PDF, only pieces of text placed at points. "Bill No. MB-212" and "Dt. 3.10.26" are two separate pieces at the same height, x 40 and x 300. A reader that wants lines has to rebuild them from the positions.

The photographed bill is different. Its page draws one thing:

q 595 0 0 842 0 0 cm /Im1 Do Q

"Paint image Im1 over the whole page." The image is 200 by 283 grey pixels. No characters anywhere: "Pav" and "Total" exist only as shapes in those pixels. Reading them needs OCR (optical character recognition), which this project does not do.

What unpdf gives

unpdf reads PDFs in Node (it wraps pdf.js, the reader inside Firefox). await getDocumentProxy(bytes) opens a document from a Uint8Array of the file's bytes. pdf.numPages counts the pages, and await pdf.getPage(i) gives one, numbered from 1. page.getTextContent() lists its pieces, each with str (the text), width and transform, whose last two numbers are x and y. The given pagePieces(page) turns them into TextPieces, { text, x, y, width }. The top of Swarnim's invoice:

{"text":"GSTIN: 27ABFPS4418K1ZB","x":40,"y":772,"width":101.82400000000003}
{"text":" ","x":141.82400000000004,"y":772,"width":8.895999999999958}
{"text":"Phone: +91 98220 47135","x":150.72,"y":772,"width":90.072}
{"text":"","x":400,"y":750,"width":0}
{"text":"TAX INVOICE","x":400,"y":750,"width":76.68}
{"text":"Invoice No: SSL/2207","x":40,"y":744,"width":91.03500000000003}

"TAX INVOICE" sits at y 750, x 400; "Invoice No" at y 744, x 40. They come in drawing order, which is why unpdf's own extractText glued them. Notice the empty pieces and the pieces of only spaces: they carry no text and only get in the way.

Monospaced receipts add a twist. Joshi Farsan's billing program draws a whole line in one command, (Batata Wada \(Potato Fritter\) 400 pcs ...), and pdf.js splits it at spaces:

{"text":"Batata Wada (Potato","x":40,"y":674,"width":91.19999999999996}
{"text":" ","x":131.19999999999996,"y":674,"width":4.800000000000011}
{"text":"Fritter)","x":135.99999999999997,"y":674,"width":38.4}
{"text":" ","x":174.40000000000006,"y":674,"width":28.800000000000068}
{"text":"400","x":203.20000000000013,"y":674,"width":14.399999999999999}

"Fritter)" starts 4.8 points after "Batata Wada (Potato" ends: that is a space inside one name. "400" starts 28.8 points after "Fritter)" ends: that is the next column.

Rebuilding the lines

layoutPage turns a page's pieces into text, in four ideas.

1. Top to bottom, then left to right. A PDF's y grows upwards, so the top line has the largest y. sort takes a compare function: a negative result puts a first. Two keys chain with ||: when the first difference is 0, the second decides. On seats:

> [{ row: 'B', n: 4 }, { row: 'A', n: 7 }, { row: 'B', n: 1 }, { row: 'A', n: 2 }].sort((a, b) => a.row.localeCompare(b.row) || a.n - b.n)
[
  { row: 'A', n: 2 },
  { row: 'A', n: 7 },
  { row: 'B', n: 1 },
  { row: 'B', n: 4 }
]

Never sort numbers without a compare function: the default compares them as text.

> [700, 680, 90].sort()
[ 680, 700, 90 ]
> [700, 680, 90].sort((a, b) => b - a)
[ 700, 680, 90 ]

2. One line per height. Pieces of one printed line can differ in y by a point or so (a bold heading drawn a little higher). A piece within SAME_LINE (2 points) of the first piece of the current line joins it; anything further starts a new line. With "TAX INVOICE" 6 points above "Invoice No", they stay two lines.

3. A small gap is a space, a big gap is a column. Inside a line, sorted by x: a piece that starts less than JOIN_GAP (6 points) after the previous one ends (x + width) is the next word, added after one space. Any other piece goes to its column: about 4 points a character, so Math.round(x / PT_PER_CHAR) characters from the left. ' '.repeat(n) makes n spaces, and Math.max(2, n) keeps at least two, so two columns never run together even when a long name reaches past the next column's start.

4. Tidy. Leave out pieces of only spaces first, trimEnd() each line, and join the lines with "\n".

Here are made-up pieces of a delivery challan, drawn out of order, the second line a little higher on purpose, given to the finished layoutPage:

const pieces = [
  { text: 'Cola Syrup (5 L can)', x: 40, y: 680, width: 80 },
  { text: '8', x: 200, y: 680, width: 4.5 },
  { text: 'Challan RC-77', x: 40, y: 700.8, width: 60 },
  { text: 'Date:', x: 300, y: 700, width: 22 },
  { text: '03/10/2026', x: 325, y: 700, width: 45 },
  { text: '   ', x: 150, y: 680, width: 13.5 },
];
console.log(layoutPage(pieces));
          Challan RC-77                                                    Date: 03/10/2026
          Cola Syrup (5 L can)                    8

"Date:" and "03/10/2026" are 3 points apart, so one space; "8" sits at column 50, under where a quantity would be. On Joshi Farsan's receipt the columns come back:

          ITEM                                     QTY UNIT            RATE         AMOUNT
          Batata Wada (Potato Fritter)             400 pcs            14.00       5,600.00
          Kanda Bhaji (Onion Fritters)              12 kg            260.00       3,120.00

Pad every piece to its column, ignoring the join gap, and the Check shows what that does to a name:

layoutPage on a receipt line split into words a space apart (close pieces): line 1 is "          Batata  Wada  (Potato   Fritter)                      400"; the task wants "          Batata Wada (Potato Fritter)                          400"

Refusing early

Three files should never reach the model, and each has an error code the API sends back.

  1. Too big (413 too_large). A venue manager forwards a 40 MB scanned catalogue. statSync(path).size asks the file system without reading a byte, so check it first: config.maxBytes is 5,000,000.
  2. Not a PDF (422 not_a_pdf). On a text file named .pdf, getDocumentProxy prints Warning: Indexing all PDF objects and throws InvalidPDFException: Invalid PDF structure. Wrap the call in try/catch and throw your own AppError instead. Without it, Express turns the plain error into a 500, and the Check says: readPdf on a text file named notes.pdf threw a plain error: Invalid PDF structure.; the task wants an AppError 422 with code not_a_pdf.
  3. Too long (422 too_many_pages). config.maxPages is 10: an invoice is a page or two, and a 300-page PDF is something else.

Each AppError carries a sentence a person can read. From the finished chapter, with smaller limits so the real invoices trip them:

Warning: Indexing all PDF objects
422 not_a_pdf notes.pdf is not a PDF unpdf can read: Invalid PDF structure.
413 too_large mauli-mb-212.pdf is 2076 bytes; the most is 1000
422 too_many_pages mudran-mp-0614.pdf has 2 pages; the most is 1

That is each error's status, code and message, printed by a short script: a text file saved as notes.pdf, Mauli's 2,076-byte bill with config.maxBytes set to 1,000, and Mudran's 2-page order with config.maxPages set to 1.

Then read the pages in turn, from 1 to numPages, each one's pieces laid out with your Task 1.

Pages and scans

PdfText holds one string per page. Its two other values are getters: a method written get name() is read like a field, with no brackets, and computed each time. On a made-up hall:

> class Hall { constructor(seats) { this.seats = seats } get free() { return this.seats.filter((s) => s === 0).length } }
undefined
> new Hall([0, 1, 0, 1, 1]).free
2
  • text puts a marker line before every page, --- page 1 of 2 ---, and a blank line between pages. When Mudran's order runs onto a second page, the model (and Vaishali, later) can see where page 2 begins. map gives each item its index from 0, so add 1 to count the way people do (the REPL below).
  • needsOcr is true when no page has any text. Careful: a page of only spaces is not empty, so ['', ' \n '].some((p) => p) is true. Trim each page first: ['', ' \n '].some((p) => p.trim()) is false.
> ['Kala Talkies', 'Rangdeep', 'The Attic'].map((v, i) => `${i}: ${v}`)
[ '0: Kala Talkies', '1: Rangdeep', '2: The Attic' ]

The finished route, as Omkar:

{"file":"mauli-mb-scan-0928.pdf","pages":1,"chars":20,"needsOcr":true,"text":"--- page 1 of 1 ---\n"}
status 200
{"file":"joshi-jfb-4410.pdf","pages":1,"chars":1571,"needsOcr":false,"text":"--- page 1 of 1 ---\n          JOSHI FARSAN BHANDAR\n          Shop 3, Tulshibaug, Budhwar Peth, Pune 411002\n ..."}
status 200
{"error":{"code":"bad_file","message":"\"../../src/config.ts\" is not a PDF in the inbox"}}
status 400

And the 2-page order, where the first page ends and the second begins:

          13   Menu Card A4 (laminated)                             4911             60   pcs                45.00              2,700.00
          Carried forward to page 2

--- page 2 of 2 ---
                                                                                                                               Page 2 of 2
          Mudran Press

The given invoiceText in src/modules/files.ts is what chapter 4 sends the model: it throws 422 needs_ocr for a scan, so a photo never reaches the model at all.

Your turn

  • Task 1, layoutPage: drop space-only pieces, sort (y down, then x), group by SAME_LINE from the line's first piece, join close pieces with a space, pad far ones to their column with at least two spaces, trimEnd. The trap: padding every piece, which splits a name apart.
  • Task 2, readPdf: the size first, then getDocumentProxy inside a try, the page count, then each page laid out. The trap: letting unpdf's error escape as a 500.
  • Task 3, PdfText: text with markers, needsOcr. Nikhil will ask: the scanned bill gives you no text at all. Why not send it to the model anyway, and what happens to it instead?

Start the app with npm run dev and send "The text of a farsan bill", "A 2-page invoice" (find the second marker), "The scanned bill" and "A file outside the inbox" (400). Try head -c 600 on a PDF in data/inbox, then press Check.

What you build: 3 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    reader.ts: pieces of text into lines

    In src/pdf/reader.ts write layoutPage(pieces). Leave out every piece whose text is only spaces. Sort the rest top to bottom (a larger y first: a PDF's y grows upwards), then left to right (a smaller x first). Group them into lines: a piece whose y is within SAME_LINE (2) points of the first piece of the current line joins that line; otherwise it starts a new one. Build each line's text from its pieces sorted by x: a piece that starts less than JOIN_GAP (6) points after the previous piece ends (x + width) is added after one space; any other piece is added after as many spaces as it takes to reach its column, Math.round(x / PT_PER_CHAR), but at least two when the line already has text (the first piece of a line gets no minimum). Trim each line's end and join the lines with "\n".

    The Check lays out four sets of pieces of its own (drawn out of order, two y's 1.5 points apart, a piece of spaces, words split into close pieces, a column that would overlap) and the first page of joshi-jfb-4410.pdf, and compares each line with its own.

  2. Task 2

    reader.ts: read a PDF, page by page

    Write readPdf(path). A file bigger than config.maxBytes: throw new AppError(413, 'too_large', ...). Open it with getDocumentProxy(new Uint8Array(readFileSync(path))); if that throws, throw new AppError(422, 'not_a_pdf', ...). More pages (pdf.numPages) than config.maxPages: throw new AppError(422, 'too_many_pages', ...). Return a new PdfText of each page's text: for page 1 to numPages, layoutPage(await pagePieces(await pdf.getPage(i))).

    The Check reads a 2-page invoice and compares each page with its own reading, then reads a text file named .pdf, a PDF over a smaller config.maxBytes and the 2-page PDF with config.maxPages 1.

  3. Task 3 · interview question

    Interview: reader.ts, page markers and scans

    Write PdfText's two getters. text: every page after a marker line "--- page 1 of 2 ---" and a newline, the pages joined with a blank line between them ("\n\n"). needsOcr: true when no page has any text that is not spaces, false otherwise.

    The Check builds PdfText objects of its own, then calls POST /invoices/text for the scanned bill (mauli-mb-scan-0928.pdf, needsOcr true) and for swarnim-ssl-2207.pdf (its text starts with the marker, then the vendor's name).

    Nikhil will ask: the scanned bill gives you no text at all. Why not send it to the model anyway, and what happens to it instead?

What you will learn

  • What a PDF holds: drawing commands that place pieces of text at x and y, and why a scan holds only pixels.
  • unpdf: a document, its pages, and each page's pieces of text with their positions.
  • Rebuilding lines: sorting by position, grouping by height, joining words and padding columns.
  • Refusing early: a size limit before reading, and unpdf's errors turned into the API's errors.
  • Getters on a class: values computed from its fields.
  • Text or no text: how the app knows a PDF needs OCR.

More in From PDF to data

Build "Reading PDFs" 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.

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.