binect-js/SCOPE.md

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 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 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).
• 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) 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 (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, then 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

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]

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; add genuine 1:1 API coverage to the relevant sub-client; route aggregating/reinterpreting requests to an ADR instead (as was done for listAll()).