generated from coulomb/repo-seed
tegwick
08c87dead1
Seed workplans/ with bootstrap workplan to satisfy ADR-001 C-01. Includes regenerated dev-hub session-protocol and agent instruction files.
125 lines
6.7 KiB
Markdown
125 lines
6.7 KiB
Markdown
# 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()`).
|