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>
50 lines
1.6 KiB
Markdown
50 lines
1.6 KiB
Markdown
# ADR-002: No External Runtime Dependencies
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
The SDK needs to make HTTP requests and handle authentication. Common approaches include using libraries like axios, node-fetch, or got for HTTP, and various utilities for base64 encoding.
|
|
|
|
Per the TSD (Section 2, Design Guardrail #1): "No backend dependency - The product must function entirely in browser and JavaScript runtime environments."
|
|
|
|
## Decision
|
|
|
|
The SDK will have **zero runtime dependencies**:
|
|
|
|
1. **HTTP Requests**: Use native `fetch` API
|
|
- Available in all modern browsers
|
|
- Built into Node.js >= 18
|
|
- No polyfills required for target environments
|
|
|
|
2. **Base64 Encoding**: Use native APIs
|
|
- Browser: `btoa()` / `atob()`
|
|
- Node.js: `Buffer.from().toString('base64')`
|
|
- Provide isomorphic wrapper
|
|
|
|
3. **Type Checking**: TypeScript (dev dependency only)
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- No dependency vulnerabilities to manage
|
|
- Smaller bundle size
|
|
- Predictable behavior (no library-specific quirks)
|
|
- Works identically in browser and Node.js
|
|
- No version conflicts with consumer projects
|
|
|
|
### Negative
|
|
- Must implement utility functions ourselves
|
|
- Cannot leverage library conveniences (interceptors, etc.)
|
|
- Requires Node.js >= 18 (has native fetch)
|
|
|
|
## Alternatives Considered
|
|
|
|
1. **axios**: Popular but adds ~13KB and has had security vulnerabilities
|
|
2. **node-fetch**: Would require different code paths for browser/Node
|
|
3. **ky**: Modern but still an external dependency
|
|
|
|
## References
|
|
- TSD: Section 2 (Design Guardrails)
|
|
- Node.js fetch: https://nodejs.org/docs/latest-v18.x/api/globals.html#fetch
|