binect-js/docs/adr/001-no-listall-method.md

ADR-001: No listAll() Method in Documents Client

Status: Accepted Date: 2026-01-16 Context: Response to client feature request (REQ-2 in suggested-improvements.md)

Context

A client integration team requested a listAll() method that would:

1. Return all documents regardless of status in a single call
2. Support filtering by status codes
3. Optionally auto-paginate to fetch all pages

The Binect REST API exposes two distinct endpoints for listing documents:

• GET /documents - Returns shippable documents (status 2)
• GET /documents/errors - Returns erroneous documents (status 7)

There is no single API endpoint that returns documents across all statuses.

Decision

We will not implement a listAll() method on the DocumentsClient class.

Rationale

1. Violates Core Design Principle: 1:1 Semantic Mapping

The SDK's architecture mandates a "1:1 semantic mapping to REST endpoints" (CLAUDE.md). A listAll() method would need to:

• Call multiple API endpoints (/documents and /documents/errors)
• Merge and deduplicate results
• Present a unified interface that doesn't exist in the underlying API

This creates abstraction that obscures actual API behavior.

2. Violates Transparency Principle

The design constraint "Transparency over abstraction: Developers must reason about actual API calls" means developers should understand exactly which API calls are being made. A listAll() method hides the fact that multiple calls occur, making it harder to:

• Debug network issues
• Understand rate limiting implications
• Reason about data freshness (documents may change between calls)

3. Incomplete Coverage Cannot Be Fixed

Even if we implemented listAll(), we cannot retrieve documents in all statuses:

• Status 1 (IN_PREPARATION) - No list endpoint
• Status 3 (PRODUCTION_QUEUE) - No list endpoint
• Status 4 (PRINTING) - No list endpoint
• Status 5 (SENT) - No list endpoint
• Status 6 (CANCELED) - No list endpoint

A method named listAll() that doesn't actually list all documents would be misleading.

4. Convenience Layer Alternative Exists

Developers who need to combine results can do so explicitly:

import { fetchAllPages } from '@binect/js';

// Explicit composition - developer knows exactly what's happening
const [shippable, erroneous] = await Promise.all([
  fetchAllPages((limit, offset) => client.documents.list({ limit, offset })),
  fetchAllPages((limit, offset) => client.documents.listErrors({ limit, offset })),
]);

const allAvailable = [...shippable, ...erroneous];

This approach:

• Makes the multiple API calls explicit
• Allows parallel execution for better performance
• Gives developers control over error handling per endpoint
• Doesn't pretend to offer functionality the API doesn't support

Consequences

Positive

• SDK remains a transparent wrapper over the API
• No false promises about "all documents" when API doesn't support it
• Developers understand the actual API limitations
• Easier to maintain as SDK behavior matches API exactly

Negative

• Developers must write slightly more code to combine results
• May be perceived as less convenient than competing SDKs

Alternatives Considered

Alternative 1: Add listAll() to Convenience Layer (helpers.ts)

We considered adding a helper function rather than a method:

export async function listAllDocuments(client: BinectClient): Promise<Document[]>

Rejected because: Even as a helper, the name "listAll" is misleading since it cannot list documents in statuses 1, 3, 4, 5, or 6. A more honest name would be listShippableAndErroneous(), which provides little value over explicit composition.

Alternative 2: Add Status Filter to Existing Methods

We considered adding a status filter parameter to list():

await client.documents.list({ status: [2, 7] });

Rejected because: The API doesn't support this. We would be inventing client-side filtering semantics that don't map to any API capability.

References

• CLAUDE.md - Design Constraints section
• suggested-improvements.md - REQ-2: Add Method to List All Documents