Files

tegwick b9aebb42f1 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>

2026-01-14 23:10:34 +01:00

1.6 KiB

Raw Blame History

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:

HTTP Requests: Use native fetch API
- Available in all modern browsers
- Built into Node.js >= 18
- No polyfills required for target environments
Base64 Encoding: Use native APIs
- Browser: btoa() / atob()
- Node.js: Buffer.from().toString('base64')
- Provide isomorphic wrapper
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

axios: Popular but adds ~13KB and has had security vulnerabilities
node-fetch: Would require different code paths for browser/Node
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

1.6 KiB Raw Blame History