Skip to main content
Version: 1.0.0

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