Add convenience helpers and improve documentation

- Add isInProduction() helper for checking status 3 or 4
- Add getErrorSummary() helper for extracting error messages
- Add fetchAllPages() pagination helper for auto-pagination
- Add comprehensive JSDoc to ListResponse interface
- Create ADR-001 documenting decision not to add listAll() method

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

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

@@ -0,0 +1,112 @@
+# 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:
+
+```typescript
+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:
+
+```typescript
+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()`:
+
+```typescript
+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