generated from coulomb/repo-seed
Add Binect SDK implementation, Explorer, and test suite
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>
This commit is contained in:
78
architecture/ADR-001-sdk-architecture.md
Normal file
78
architecture/ADR-001-sdk-architecture.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user