coulomb/binect-js
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add State Hub bootstrap workplan and agent integration files

Browse Source 
Seed workplans/ with bootstrap workplan to satisfy ADR-001 C-01.
Includes regenerated dev-hub session-protocol and agent instruction files.
This commit is contained in:
Bernd Worsch
2026-06-22 21:44:32 +02:00
parent 2691215f62
commit 08c87dead1
14 changed files with 660 additions and 406 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
SCOPE.md
View File

@@ -1,94 +1,124 @@
# SCOPE.md
# SCOPE
> 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.
> 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.
## 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.
## One-liner
## 2. In Scope
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.
### 2.1 SDK — Core API Coverage (`src/`)
---
The SDK provides 1:1 semantic mapping to the Binect REST endpoints, organized into domain sub-clients:
## Core Idea
| 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 |
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.
### 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`
## In Scope
### 2.3 SDK — Cross-cutting
- **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/`).
- 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`)
## Out of Scope
- 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"
- 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.
### 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`)
## Relevant When
## 3. Out of Scope
- 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.
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. |
## Not Relevant When
## 4. Boundary Cases & Known Edges
- 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.
- **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
## Current State
In scope is defined by what the Binect API exposes plus the thin convenience layer. To change scope:
- 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
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
## How It Fits
- [`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
- 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()`).