generated from coulomb/repo-seed
tegwick
5c1d26afba
- Add PRD and TSD defining SDK and Explorer architecture - Add CLAUDE.md with project guidance for Claude Code - Update README with project description - Replace Python .gitignore with JS/TS configuration Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
354 lines
7.6 KiB
Markdown
354 lines
7.6 KiB
Markdown
TechnicalSpecificationDocument
|
||
|
||
*Implementation strategy for binect-js*
|
||
|
||
# Technical Specification (TSD)
|
||
|
||
## Binect-JS API Wrapper & Explorer
|
||
|
||
**PRD-aligned / Pre-Implementation Version**
|
||
|
||
---
|
||
|
||
## 0. Positioning and Authority
|
||
|
||
This Technical Specification derives its authority **exclusively from the PRD** and serves as a **design-orientation document**, not a binding implementation plan.
|
||
|
||
It:
|
||
|
||
* refines **how the product intent may be realized**
|
||
* makes **explicit what is optional, configurable, or deferred**
|
||
* avoids encoding decisions that would normally belong in ADRs
|
||
|
||
Where uncertainty exists, the TSD **preserves option space**.
|
||
|
||
---
|
||
|
||
## 1. Product Composition
|
||
|
||
### 1.1 Product Boundary
|
||
|
||
The product **Binect-JS** consists of two coordinated but separable artifacts:
|
||
|
||
1. **Binect-JS SDK**
|
||
A JavaScript / TypeScript wrapper around the Binect REST API.
|
||
|
||
2. **Binect Explorer**
|
||
A browser-based interactive tool that uses the SDK to support:
|
||
|
||
* learning
|
||
* experimentation
|
||
* evaluation
|
||
* integration understanding
|
||
|
||
Together they form **one developer-facing product**, but neither depends on the other for correctness.
|
||
|
||
---
|
||
|
||
## 2. Design Guardrails (Derived from PRD)
|
||
|
||
The following constraints are **non-negotiable** and shape all downstream decisions:
|
||
|
||
1. **No backend dependency**
|
||
The product must function entirely in browser and JavaScript runtime environments.
|
||
|
||
2. **No semantic reinterpretation of the Binect API**
|
||
The wrapper must not alter business meaning, rules, or outcomes.
|
||
|
||
3. **Transparency over abstraction**
|
||
Developers must be able to reason about what API calls occur and why.
|
||
|
||
4. **Learning-first, not operations-first**
|
||
Especially for the Explorer: this is *not* a production operations console.
|
||
|
||
5. **Optionality over prescription**
|
||
Features that imply policy (retries, persistence, automation) must be opt-in.
|
||
|
||
---
|
||
|
||
## 3. SDK Technical Orientation (`@binect/js`)
|
||
|
||
### 3.1 Role of the SDK
|
||
|
||
The SDK’s role is to:
|
||
|
||
* provide a **stable adaptation layer**
|
||
* reduce accidental misuse of the API
|
||
* improve readability and discoverability
|
||
* centralize API evolution handling
|
||
|
||
It is **not** intended to:
|
||
|
||
* orchestrate workflows
|
||
* enforce sending policies
|
||
* optimize delivery behavior
|
||
|
||
---
|
||
|
||
### 3.2 API Surface Structure
|
||
|
||
The SDK exposes **domain-aligned sub-clients** that mirror the API vocabulary:
|
||
|
||
* `documents`
|
||
* `attachments`
|
||
* `sendings`
|
||
* `accounts`
|
||
* `invoices`
|
||
|
||
This structure is **intentional**:
|
||
|
||
* it preserves traceability to API documentation
|
||
* it avoids hiding capabilities behind synthetic abstractions
|
||
|
||
---
|
||
|
||
### 3.3 Core vs Convenience Layers (Explicit Separation)
|
||
|
||
The SDK is conceptually divided into two layers:
|
||
|
||
#### A) Core API Layer (authoritative)
|
||
|
||
* 1:1 semantic mapping to REST endpoints
|
||
* minimal transformation
|
||
* predictable behavior
|
||
* no embedded policy
|
||
|
||
Examples:
|
||
|
||
* `documents.uploadPdf`
|
||
* `documents.getStatus`
|
||
* `sendings.announce`
|
||
* `sendings.cancel`
|
||
|
||
This layer is **the reference layer**.
|
||
|
||
#### B) Optional Convenience Layer (non-authoritative)
|
||
|
||
* purely additive helpers
|
||
* must be clearly labeled as such
|
||
* must not be required for correct usage
|
||
|
||
Examples (illustrative, not mandatory):
|
||
|
||
* status predicates (`isShippable`)
|
||
* error extraction helpers
|
||
* polling helpers
|
||
|
||
> **Important:**
|
||
> Convenience helpers may exist, but **must never be the only way** to perform an action.
|
||
|
||
---
|
||
|
||
### 3.4 Authentication Handling
|
||
|
||
* Authentication uses **HTTP Basic Auth**, passed transparently.
|
||
* The SDK:
|
||
|
||
* does not store credentials
|
||
* does not cache auth headers beyond request scope
|
||
* does not log sensitive values
|
||
|
||
Credential lifecycle management is **explicitly out of scope** for the SDK.
|
||
|
||
---
|
||
|
||
### 3.5 Upload & Payload Handling
|
||
|
||
* The SDK supports base64-encoded PDF uploads as required by the API.
|
||
* It may provide:
|
||
|
||
* size estimation helpers
|
||
* early warnings when payloads approach known limits
|
||
|
||
These helpers:
|
||
|
||
* are advisory only
|
||
* do not block execution unless explicitly configured
|
||
|
||
---
|
||
|
||
### 3.6 Error Handling Model
|
||
|
||
* All non-success responses are surfaced as structured errors.
|
||
* Errors preserve:
|
||
|
||
* HTTP status
|
||
* endpoint identity
|
||
* parsed response payload where available
|
||
|
||
The SDK **does not reinterpret business errors**, but may:
|
||
|
||
* expose helpers to *extract* or *summarize* validation issues.
|
||
|
||
---
|
||
|
||
### 3.7 Retries, Timeouts, and Network Behavior (Revised)
|
||
|
||
**Change from previous TSD:**
|
||
All default retry semantics have been **removed**.
|
||
|
||
Current stance:
|
||
|
||
* The SDK **does not imply any retry behavior**
|
||
* Network behavior is:
|
||
|
||
* explicit
|
||
* configurable
|
||
* opt-in
|
||
|
||
If retry helpers are provided:
|
||
|
||
* they must be **disabled by default**
|
||
* they must be **clearly documented as potentially unsafe** for send operations
|
||
|
||
Timeouts, retries, and backoff strategies are **configuration concerns**, not product guarantees.
|
||
|
||
---
|
||
|
||
## 4. Explorer Technical Orientation (`@binect/explorer`)
|
||
|
||
### 4.1 Role of the Explorer
|
||
|
||
The Explorer exists to:
|
||
|
||
* reduce onboarding friction
|
||
* make the API *legible*
|
||
* allow safe experimentation
|
||
* support pre-integration evaluation
|
||
|
||
It is **not** intended to:
|
||
|
||
* replace backend integrations
|
||
* act as an operations dashboard
|
||
* support long-running or automated workflows
|
||
|
||
---
|
||
|
||
### 4.2 Functional Scope
|
||
|
||
The Explorer supports:
|
||
|
||
* credential input
|
||
* document upload and inspection
|
||
* previewing normalized output
|
||
* triggering send/cancel actions
|
||
* inspecting raw and summarized responses
|
||
* storing named **use case profiles**
|
||
|
||
All actions are **user-initiated**.
|
||
|
||
---
|
||
|
||
### 4.3 Use Case Profiles (Conceptual)
|
||
|
||
Profiles represent:
|
||
|
||
* a reusable *parameter constellation*
|
||
* not a workflow definition
|
||
* not a business rule
|
||
|
||
Profiles may include:
|
||
|
||
* document options
|
||
* attributes
|
||
* cover page parameters
|
||
* attachment references
|
||
* sending mode (upload vs send)
|
||
|
||
Profiles:
|
||
|
||
* are stored locally
|
||
* can be exported/imported
|
||
* have no implicit execution semantics
|
||
|
||
---
|
||
|
||
### 4.4 Credential Handling (Reframed)
|
||
|
||
**Change from previous TSD:**
|
||
Credential persistence is no longer a default design feature.
|
||
|
||
Current stance:
|
||
|
||
* Credentials are **ephemeral by default**
|
||
* Optional persistence may exist as a **user-initiated UX enhancement**
|
||
* No persistence is required to meet product intent
|
||
|
||
Cryptographic details and storage mechanisms are **explicitly design-time decisions**, deferred until implementation.
|
||
|
||
---
|
||
|
||
### 4.5 Safety and Trust
|
||
|
||
The Explorer must:
|
||
|
||
* clearly distinguish between *preview* and *send*
|
||
* require explicit confirmation for destructive actions
|
||
* surface consequences before execution
|
||
|
||
Safety is achieved through **interaction design**, not enforcement logic.
|
||
|
||
---
|
||
|
||
## 5. Non-Functional Orientation
|
||
|
||
### 5.1 Usability
|
||
|
||
* API capabilities must be discoverable through interaction.
|
||
* Raw API responses must remain accessible.
|
||
|
||
### 5.2 Reliability
|
||
|
||
* Failures must be visible and explainable.
|
||
* Silent retries or hidden corrections are disallowed.
|
||
|
||
### 5.3 Maintainability
|
||
|
||
* The SDK must tolerate API evolution without breaking product intent.
|
||
* The Explorer must remain usable even as API features expand.
|
||
|
||
---
|
||
|
||
## 6. Out-of-Scope Reinforcement (Explicit)
|
||
|
||
The following are **explicitly excluded** from this TSD:
|
||
|
||
* scheduling
|
||
* batching
|
||
* automation
|
||
* background job execution
|
||
* business rule enforcement
|
||
* policy encoding
|
||
|
||
Any future inclusion of these concerns requires:
|
||
|
||
* PRD revision **or**
|
||
* explicit ADRs
|
||
|
||
---
|
||
|
||
## 7. Traceability Note
|
||
|
||
This TSD is intentionally **non-binding** with respect to:
|
||
|
||
* architectural patterns
|
||
* libraries
|
||
* UI frameworks
|
||
* storage mechanisms
|
||
|
||
Its sole purpose is to ensure that **implementation choices remain aligned with product intent as defined in the PRD**.
|
||
|
||
---
|
||
|
||
## 8. Status
|
||
|
||
* **TSD** is **PRD-aligned**
|
||
* Safe to use as:
|
||
|
||
* implementation briefing
|
||
* review baseline
|
||
* pre-ADR reference
|
||
|
||
|
||
xxx
|