binect-js/architecture/ADR-001-sdk-architecture.md

ADR-001: SDK Architecture

Status

Accepted

Context

The Binect-JS SDK needs to provide a JavaScript/TypeScript wrapper for the Binect REST API. Per the PRD and TSD, the SDK must:

• Be transparent and thin (no semantic reinterpretation)
• Work in both browser and Node.js environments
• Use domain-aligned sub-clients mirroring the API vocabulary
• Separate core API layer from optional convenience helpers
• Handle HTTP Basic Authentication without storing credentials

Decision

1. Client Structure

We adopt a main client with domain-aligned sub-clients pattern:

const client = new BinectClient({ username, password });
client.documents.upload(...)
client.sendings.announce(...)
client.attachments.list(...)
client.accounts.get(...)
client.invoices.list(...)

Each sub-client maps to an API domain and provides 1:1 method mapping to REST endpoints.

2. HTTP Layer

We use the native fetch API for HTTP requests:

• Works in both browser and Node.js (>=18)
• No external dependencies
• Predictable behavior without hidden retries or timeouts

3. Authentication

• Credentials passed at client construction
• Converted to Base64 Basic Auth header per request
• Never stored beyond client instance lifetime
• No automatic credential refresh

4. Error Handling

• Non-2xx responses throw BinectApiError with:
  • HTTP status code
  • Endpoint path
  • Parsed response body (when available)
• Network errors surface as-is (no wrapping)

5. Type Safety

• Full TypeScript types for all API requests/responses
• Enums for document status, envelope types, franking types
• Generic response types preserving API structure

6. Convenience Layer (Optional)

Additive helpers in separate modules:

• Status predicates (isShippable, isErroneous)
• Polling utilities (opt-in, no default behavior)
• Response extractors

These never replace core methods.

Consequences

Positive

• Clear mental model mapping to API documentation
• No hidden behavior or magic
• Works in all JavaScript environments with fetch
• Type-safe development experience

Negative

• Developers must understand API structure
• No automatic retry on transient failures (by design)
• More verbose than heavily abstracted SDKs

References

• PRD: Section 3.1 (Product Intent)
• TSD: Section 3 (SDK Technical Orientation)
• Binect API: https://app.binect.de/index.jsp?id=api