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.
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.
- **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.
- 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.
- 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).
- 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.
description: Backend-free browser tool for learning and testing the Binect API interactively, with preview-first workflows and reusable use-case profiles.
- 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()`).
