Documents From ID

Overview

The GET /documents/from-id endpoint provides cursor-safe pagination for document retrieval with multi-proof status checking. It allows consumers to paginate without skipping pending documents, filter by required proof types (AND logic), and know how many documents remain.

How it works

1. Pipeline fetches documents with proofs attached (type + status), sorted by _id
2. Status calculation in service: external proof = always confirmed, then per-type check only if proofs of that type exist
3. Boundary logic: findIndex + slice at the first non-confirmed document to prevent data loss across paginated calls
4. remaining computed via countDocuments (indexed _id + jobRef), run in parallel with the pipeline

Key files

• src/domains/document/document.controller.ts — Route definition, query params, JSDoc
• src/domains/document/document.service.ts — isConfirmed, getJobIds, boundary logic, Promise.all
• src/domains/document/document.type.ts — DocOptions with requiredProofs, DocumentsFromIdResult
• src/domains/document/templates/documentsFromId.ts — MongoDB aggregation pipeline

Technical decisions

• Proof status computed in TS, not in MongoDB: allows backward-compatible logic where a proof type is only required if the document actually has proofs of that type (old docs with only chainpoint still pass when requiredProofs=chainpoint,ots)
• Cursor boundary in TS: stops at the first non-confirmed document rather than filtering them out, preventing data loss when paginating
• external proofs short-circuit: documents with an external proof are always considered confirmed regardless of other proof types
• Proof collection configurable via env: removed hardcoded 'ots-proofs'

Known issues

• None currently

Next steps

• Add support for after cursor parameter for true cursor-based pagination