binect-js/SCOPE.md

SCOPE.md

This document defines what Binect-JS does and does not cover, concretely. Where INTENT.md records why the project exists and the principles it must uphold, this file draws the operational boundary: which capabilities are in scope, which are explicitly excluded, and where the edges are. A feature request is answered first by checking it against this document.

1. Scope Statement

Binect-JS covers JavaScript/TypeScript access to the Binect REST API for sending PDF documents as physical mail, plus a browser-based tool for exploring that API. It covers the API surface 1:1 and a small, optional convenience layer on top. It covers nothing on the server, nothing about document creation, and nothing about business process orchestration.

2. In Scope

2.1 SDK — Core API Coverage (src/)

The SDK provides 1:1 semantic mapping to the Binect REST endpoints, organized into domain sub-clients:

Sub-client	In-scope capabilities
client.documents	upload (base64 PDF), get, list (shippable), listErrors, delete, getPdf / getPng preview, get/set attributes, applyTransformation (scaling/offset), addCoverPage
client.sendings	announce, list, send, cancel, getStatus (batch)
client.attachments	upload, list, get, delete, attachToDocuments
client.accounts	get (balance/credit), get/update personal data, get/update default print options, getJournal
client.invoices	list, get, getPdf

2.2 SDK — Convenience Layer (src/helpers.ts, optional, additive)

In scope but never the only way to perform an action:

• Status predicates: isShippable, isErroneous, isSent, isTerminal, isCancelable, hasErrors, hasWarnings
• Extractors / descriptions: getErrors, getStatusDescription
• Opt-in polling: waitForShippable
• Explicit pagination: fetchAllPages
• Encoding: fileToBase64

2.3 SDK — Cross-cutting

• HTTP Basic Authentication (ephemeral, per-client credentials)
• Native fetch transport (src/http.ts), browser + Node.js ≥ 18
• Structured errors: BinectApiError, BinectAuthError
• Full TypeScript types and enums (src/types.ts) for requests, responses, status/envelope/franking values

2.4 Explorer (explorer/index.html)

• Browser-based, no backend, runs from a local file or static host
• Credential input and safe execution of API calls
• Structured and raw presentation of responses
• Preview-first workflows before dispatch
• Reusable, named "use case profiles"

2.5 Supporting Material

• Tests (tests/), including opt-in e2e tests gated on real credentials
• Architecture Decision Records (architecture/, docs/adr/)
• Research notes on the API (research/)
• Example documents (examples/)
• Contributor instructions (CLAUDE.md, AGENTS.md)

3. Out of Scope

These are excluded by design. A request that requires any of them is a request for a different product.

Excluded	Reason
Modifying or redesigning the Binect backend API	Binect-JS is an adaptation layer, not the service.
Server-side components / hosted backend	The product must operate without server infrastructure (INTENT §4).
PDF generation, editing, or layout tooling	Developers bring PDFs already prepared for sending.
Scheduling, batching, or business-process orchestration	Workflow logic belongs in the consuming application.
Methods that aggregate or reinterpret API behavior (e.g. listAll())	Violates 1:1 mapping and transparency (see ADR).
Client-side filtering semantics the API doesn't expose	Would invent behavior with no API backing.
Default retries, timeouts, or hidden network behavior	All network behavior must be explicit and opt-in.
Credential storage, caching, or telemetry	Credentials are ephemeral; no hidden data transmission.
Runtime dependencies	Native fetch only.
Commitment to a specific UI framework	Explorer stays framework-agnostic.

4. Boundary Cases & Known Edges

• Document statuses without list endpoints. The API only lists shippable (status 2) and erroneous (status 7) documents. Statuses 1, 3, 4, 5, 6 (IN_PREPARATION, PRODUCTION_QUEUE, PRINTING, SENT, CANCELED) have no list endpoint — so the SDK cannot and will not offer "list all documents." Retrieval of those statuses is only possible per-document via get.
• Combining shippable + erroneous lists. Supported, but only via explicit composition (fetchAllPages over each endpoint in parallel), never via a single hidden method.
• CORS / direct browser access. Assumed permitted by Binect. If Binect restricts browser-origin requests, that is an upstream constraint, not something the Explorer works around with a proxy (a proxy would be a server-side component — out of scope).
• Large uploads. PDFs are base64-encoded with a 12 MB ceiling per the API; the SDK surfaces the API's response rather than chunking or pre-validating size beyond what the API enforces.

5. Scope Change Process

In scope is defined by what the Binect API exposes plus the thin convenience layer. To change scope:

1. Confirm the change does not violate any principle in INTENT.md §4.
2. If it adds API coverage that Binect actually exposes 1:1 → in scope, add it to the relevant sub-client.
3. If it aggregates, reinterprets, or invents behavior → out of scope; document the decision as an ADR (as was done for listAll()).
4. Update this file and INTENT.md together when the boundary genuinely moves.

6. Related Documents

• INTENT.md — why the project exists and its inviolable principles
• ProductRequirementsDocument.md — full PRD (§4 Scope, §4.2 Non-Scope)
• architecture/ADR-00{1,2,3}-*.md — SDK, no-dependencies, Explorer architecture
• docs/adr/001-no-listall-method.md — a scope boundary enforced against a feature request
• README.md — usage and full API reference