# 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