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:
49
architecture/ADR-002-no-external-dependencies.md
Normal file
49
architecture/ADR-002-no-external-dependencies.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user