# SCOPE.md

> This document defines **what Binect-JS does and does not cover**, concretely. Where [`INTENT.md`](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](INTENT.md)). |
| 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](docs/adr/001-no-listall-method.md)). |
| 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`](INTENT.md).
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`](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