generated from coulomb/repo-seed
tegwick
b9aebb42f1
SDK (@binect/js): - BinectClient with domain sub-clients (documents, sendings, accounts, attachments, invoices) - HTTP Basic Auth, native fetch only (no runtime dependencies) - TypeScript types matching Binect API vocabulary - Status predicates and polling helpers in helpers.ts - Structured error handling (BinectApiError, BinectAuthError) Explorer: - Standalone browser-based API explorer (explorer/index.html) - Interactive testing without code Tests: - Unit tests for client, types, errors, helpers, http - E2E tests for upload/delete and send/cancel workflows Also includes: - Architecture Decision Records (ADRs) - Example DIN 5008 letter PDFs for testing - API specification research notes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
# 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:
|
|
|
|
```typescript
|
|
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
|