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