coulomb/binect-js
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
binect-js/TechnicalSpecificationDocument.md
tegwick 5c1d26afba Add project documentation and configure for JavaScript/TypeScript 
- 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>
2026-01-14 16:47:25 +01:00

7.6 KiB
Raw Permalink Blame History

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

Reference in New Issue View Git Blame Copy Permalink