Skip to main content

Documents From ID — Cursor-safe pagination with multi-proof status

Version: 1.0.0 Date: 2026-03-03

Goal: Allow consumers of GET /documents/from-id to paginate with a cursor that never skips pending documents, filter by required proof types (AND logic), and know how many documents remain.

Solution: Added requiredProofs and limit query params. Status is computed service-side with smart proof checking: a proof type is only required if the doc actually has proofs of that type (backward-compatible with old docs). Documents with external proofs are always confirmed. The response stops at the first non-confirmed document to prevent data loss across paginated calls. Remaining count uses a fast indexed countDocuments.

Features:

  • New requiredProofs query parameter (comma-separated, e.g. chainpoint,ots)
  • Cursor boundary: response stops at the first non-confirmed doc
  • New limit query parameter for batch size control
  • Response returns { documents, remaining } where remaining excludes returned docs
  • Proof collection no longer hardcoded ('ots-proofs' -> configurable via env)
  • external proofs: docs with an external proof are always considered confirmed
  • Backward-compatible: if a doc has no proofs of a required type, that type is skipped

Implementation Details:

  • Pipeline simplified: fetches docs with proofs attached (type + status), sorted by _id
  • Status calculation moved to service (TS): external short-circuit, then per-type check only if proofs of that type exist
  • Boundary logic in TS: findIndex + slice on the first non-confirmed doc
  • remaining via countDocuments on documents collection (indexed _id + jobRef), run in Promise.all with the pipeline
  • getJobIds helper: admin gets all company job IDs via distinct, non-admin uses own jobId

Files Modified:

  • src/domains/document/document.type.ts - DocOptions with requiredProofs + DocumentsFromIdResult
  • src/domains/document/document.controller.ts - requiredProofs and limit query params, JSDoc
  • src/domains/document/document.service.ts - Promise.all, isConfirmed, getJobIds, boundary logic
  • src/domains/document/templates/documentsFromId.ts - Simplified: removed status calc, boundary, facet