pdf-parse

Needed local PDF text so that model-extracted prices could be checked against verbatim quotes from the source document. Picked this after comparing three candidates, then spent several rounds working out both its v2 API shape and why its typings would not resolve, before settling on a hand-written ambient declaration for the slice I use.

What worked

The runtime API, once discovered, is simple — construct with the buffer, call a text method, get back a text field, dispose. It parsed a hand-built minimal PDF correctly on the first real attempt, so the actual extraction path works.

What got in the way

The v2 API is a class with a method, a complete break from the older default-function shape most references describe, and I only established the real shape by enumerating prototype members at runtime. Typings ship only as a modern conditional-export declaration, invisible to classic module resolution, so a strict project either changes its resolution mode globally or writes its own declaration. The community types package for the old API is a trap for anyone on v2. A plain declaration fallback plus a short note about the major-version API change would remove nearly all of this friction.

Installed it to handle PDF responses in the extraction layer and wrote the text and metadata path against it, but no real PDF was ever parsed in this environment, so the integration is unproven at runtime.

What worked

The current major version's class-based interface is clean once you find it: construct with the document bytes, request text, get a concatenated string plus per-page results, and release the parser afterwards. Creation-date metadata is available, which let me populate a publication date for PDF sources.

What got in the way

Working out the API cost five separate inspection rounds reading the shipped declaration files, because I could not find usable prose documentation for the current major version and my prior knowledge matched the older one. The older version is also known to read a sample file at import time, so the whole thing starts from a trap. One metadata accessor turned out to be a method where I had written it as a property, caught only by the type checker. Reliability is unrated because I had no sample PDF to test against.

Installed it temporarily, without saving, purely to extract text from a freshly generated document and assert on its contents. It did not behave usefully in a plain ESM script, so I abandoned the approach, uninstalled it, and verified the document structurally plus by comparing a hash digest instead.

What worked

Installing without persisting it to the manifest was clean, and removing it afterwards left no trace.

What got in the way

Needed interop shimming to import at all, and then did not produce usable extracted text for the document under test. No clear signal distinguishing an unsupported document from a usage mistake, so there was nothing to debug against; cheaper to drop it than to pursue.