binect-js/INTENT.md

INTENT.md

The purpose of this document is to capture why this project exists and what it must remain, independent of any specific line of code. Where the README explains how to use Binect-JS and the ADRs explain how decisions were made, this file records the intent that all of those serve. If a future change conflicts with what is written here, the change is suspect — not the intent.

1. Core Intent

Enable safe, intuitive JavaScript access to the Binect API for document-based physical mail workflows — without changing, hiding, or reinterpreting what the Binect service actually does.

Binect-JS exists to lower the cognitive, technical, and experiential barrier for developers who need to send PDF documents as physical mail through the Binect REST API. It does this by providing a thin, transparent adaptation layer — never by becoming a framework, a backend, or a reinterpretation of the underlying API.

2. What Problem This Solves

The Binect API is comprehensive but low-level and REST-centric. Developers integrating it directly must manually handle authentication, base64 encoding, document lifecycle states, and error interpretation. There is no official JavaScript abstraction and no exploratory tooling for learning, testing, and safe experimentation.

This causes:

• High onboarding friction
• Frequent implementation errors
• Duplicated integration effort across projects

Binect-JS targets exactly these frictions — and nothing beyond them.

3. The Two Artifacts

1. Binect-JS SDK (@binect/js) — a thin, type-safe API wrapper (src/). Its sub-clients (documents, attachments, sendings, accounts, invoices) mirror the API's own vocabulary with a 1:1 semantic mapping to REST endpoints.
2. Binect Explorer — a standalone, browser-based interactive tool (explorer/index.html) for learning the API, testing uploads and dispatch, and managing reusable use-case profiles. It is a learning surface, not just a test harness.

4. Inviolable Principles

These are the constraints that define the project. They are not preferences; they are the boundary conditions that keep Binect-JS Binect-JS.

Principle	Meaning	Consequence
No semantic reinterpretation	The wrapper must never alter the business meaning or outcome of an API call.	A method that merges, filters, or invents behavior the API doesn't expose does not belong here (see ADR: no listAll()).
Transparency over abstraction	Developers must always be able to reason about the actual API calls being made.	No hidden multi-call methods, no magic.
Thin core, optional convenience	The Core API Layer is authoritative and 1:1 with REST. The Convenience Layer (src/helpers.ts) is additive and never the only way to perform an action.	Helpers like isShippable, waitForShippable, fetchAllPages are conveniences, not requirements.
No runtime dependencies	Native fetch only; works in browsers and Node.js ≥ 18.	No dependency may be added to the SDK runtime.
No default retries / no hidden network behavior	All network behavior is explicit and opt-in.	Polling and pagination helpers exist but must be invoked deliberately.
Ephemeral credentials	HTTP Basic Auth; credentials are passed per client instance and never stored, cached, or transmitted anywhere but to Binect.	No telemetry, no persistence of secrets.
No server-side component	The product must operate without a backend, usable as a local tool or hosted static app.	Explorer runs entirely in the browser.
Safety against accidental dispatch	Sending physical mail costs money and is irreversible.	Preview-first workflows and explicit confirmation for destructive actions (send, cancel, delete).

5. Explicitly Out of Scope

Binect-JS is deliberately not:

• A redesign or modification of the Binect backend API
• A replacement for enterprise backend integrations or workflows
• A PDF generation, editing, or layout tool
• A scheduling, batching, or business-process orchestration engine
• Committed to any specific UI framework or architectural pattern

When a feature request can only be satisfied by crossing one of these lines, the correct answer is to decline and document why — as was done for listAll().

6. Success Looks Like

• A developer completes a "send physical mail" workflow without consulting the raw API documentation.
• A first-time user validates and previews a document before sending.
• API errors are surfaced as structured, understandable, actionable BinectApiError / BinectAuthError.
• The wrapper is reused across multiple projects rather than re-implemented.
• The Explorer is adopted during onboarding and demos.

7. How to Use This Document

• Before adding a feature: confirm it serves Section 1 and violates none of Section 4. If it requires inventing behavior the API doesn't expose, it belongs in user code or not at all.
• When the Binect API evolves: this wrapper is the single adaptation layer. Update the mapping; preserve the intent. Product intent (this file) should remain stable even as API details change.
• When in doubt: any architectural or technical decision must be explainable as a direct consequence of the Core Intent in Section 1.

8. Related Documents

• ProductRequirementsDocument.md — the full PRD this intent distills
• TechnicalSpecificationDocument.md — technical orientation
• architecture/ADR-00{1,2,3}-*.md — SDK architecture, no-dependencies, Explorer architecture
• docs/adr/001-no-listall-method.md — a worked example of intent enforced against a feature request
• CLAUDE.md / AGENTS.md — operating instructions for human and AI contributors
• README.md — usage and API reference