# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not. It draws the **operational
> boundary**; [`INTENT.md`](INTENT.md) records *why* the project exists and
> the principles it must uphold. A feature request is answered first by
> checking it against this document.

---

## One-liner

Thin, transparent, zero-runtime-dependency JS/TS wrapper (`@binect/js`) for the Binect REST API to send PDF documents as physical mail via Deutsche Post, plus a browser-based Explorer.

---

## Core Idea

The Binect API is comprehensive but low-level and REST-centric: developers must hand-roll auth, base64 encoding, document-lifecycle handling, and error interpretation. Binect-JS lowers that barrier with a 1:1 SDK over the API and an interactive Explorer for learning and testing — **without changing, hiding, or reinterpreting what the Binect service actually does**. See [`INTENT.md`](INTENT.md) for the full intent and inviolable principles.

---

## In Scope

- **SDK core (`src/`)** — 1:1 semantic mapping to Binect REST endpoints via domain sub-clients: `documents` (upload, get, list, listErrors, delete, getPdf/getPng, get/setAttributes, applyTransformation, addCoverPage), `sendings` (announce, list, send, cancel, getStatus), `attachments` (upload, list, get, delete, attachToDocuments), `accounts` (get, get/update personal data, get/update options, getJournal), `invoices` (list, get, getPdf).
- **Convenience layer (`src/helpers.ts`, optional, additive)** — status predicates (`isShippable`, `isErroneous`, …), extractors (`getErrors`, `getStatusDescription`), opt-in polling (`waitForShippable`), explicit pagination (`fetchAllPages`), `fileToBase64`. Never the only way to perform an action.
- **Cross-cutting** — HTTP Basic Auth (ephemeral, per-client), native `fetch` transport (browser + Node ≥ 18), structured errors (`BinectApiError`, `BinectAuthError`), full TypeScript types/enums.
- **Explorer (`explorer/index.html`)** — backend-free browser tool: credential input, safe call execution, structured + raw response views, preview-first workflows, reusable use-case profiles.
- **Supporting material** — tests (`tests/`, incl. opt-in credential-gated e2e), ADRs (`architecture/`, `docs/adr/`), API research (`research/`), example documents (`examples/`).

---

## Out of Scope

- Modifying or redesigning the Binect backend API — this is an adaptation layer, not the service.
- Any server-side / backend component — the product runs without server infrastructure.
- PDF generation, editing, or layout tooling — developers bring prepared PDFs.
- Scheduling, batching, or business-process orchestration — workflow logic belongs in the consuming app.
- Methods that aggregate or reinterpret API behavior (e.g. `listAll()`), client-side filtering the API doesn't expose, default retries/timeouts/hidden network behavior — all violate 1:1 mapping and transparency (see [ADR](docs/adr/001-no-listall-method.md)).
- Credential storage, caching, telemetry, or runtime dependencies.

---

## Relevant When

- You are building a JS/TS application that needs to send PDF documents as physical mail through Binect.
- You want to learn, explore, or test the Binect API interactively without writing integration code first (use the Explorer).
- You need a transparent, auditable wrapper where every method maps to a known REST call.
- You are consuming Binect from a sibling project (e.g. [`binect-chrome`](../binect-chrome)) and want the SDK as a shared dependency.

---

## Not Relevant When

- You need to *create*, render, or transform the PDF itself — that is the source application's job.
- You want a heavily abstracted, "do-it-all" mail orchestration framework with retries, scheduling, and batching baked in.
- You are integrating a non-Binect mail/postal provider.
- You need server-side queueing or persistence — this library is stateless and backend-free by design.

---

## Current State

- Status: active
- Implementation: substantial — full SDK surface, convenience helpers, Explorer, and test suite in place
- Stability: evolving — `@binect/js` is at `0.1.0`, not yet published to a registry (consumed via `file:` / `npm link`)
- Usage: internal — used as a local dependency by sibling Binect tooling

---

## How It Fits

- Upstream dependencies: the Binect REST API (third-party service; see `tpsc.yaml`). No runtime npm dependencies.
- Downstream consumers: [`binect-chrome`](../binect-chrome) (Chrome extension), and any JS/TS project sending physical mail via Binect.
- Often used with: prepared PDF sources; the Explorer for onboarding and demos.

---

## Terminology

- Preferred terms: **document** (an uploaded PDF), **sending** (a dispatch action), **shippable** (status 2, ready to send), **erroneous** (status 7).
- Also known as: "letter" / "mail" / "Brief" for a sent document.
- Potentially confusing terms: *uploaded ≠ sent* — uploading makes a document shippable; dispatch is a separate explicit `send` step. "list" returns only shippable documents, not all documents (no API endpoint lists all statuses).

---

## Related / Overlapping

- `binect-chrome` — Chrome extension that detects PDFs and sends them to Binect; consumes this SDK rather than reimplementing API logic.
- `email-connect` — adjacent communication-domain delivery channel (email vs. physical mail); no code overlap.

---

## Getting Oriented

- Start with: [`INTENT.md`](INTENT.md), then [`README.md`](README.md).
- Key files / directories: `src/client.ts` (main client), `src/clients/*` (sub-clients), `src/types.ts`, `src/errors.ts`, `src/http.ts`, `src/helpers.ts`, `explorer/index.html`.
- Entry points: `BinectClient` (from `src/index.ts`); the Explorer (`explorer/index.html`).

---

## Provided Capabilities

```capability
type: api
title: Binect physical-mail SDK (@binect/js)
description: Transparent JS/TS wrapper over the Binect REST API to upload PDFs, manage document lifecycle, and dispatch physical mail via Deutsche Post. Zero runtime dependencies; browser and Node ≥ 18.
keywords: [binect, physical-mail, pdf, deutsche-post, sdk, typescript, fetch]
```

```capability
type: documentation
title: Binect API Explorer
description: Backend-free browser tool for learning and testing the Binect API interactively, with preview-first workflows and reusable use-case profiles.
keywords: [explorer, binect, api-testing, onboarding, browser]
```

---

## Notes

- Uploads are base64-encoded PDFs with a 12 MB ceiling enforced by the API.
- Document status codes: 1=IN_PREPARATION, 2=SHIPPABLE, 3=PRODUCTION_QUEUE, 4=PRINTING, 5=SENT, 6=CANCELED, 7=ERRONEOUS.
- Scope-change process: confirm against [`INTENT.md` §4](INTENT.md); add genuine 1:1 API coverage to the relevant sub-client; route aggregating/reinterpreting requests to an ADR instead (as was done for `listAll()`).