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

2.3 KiB

Raw Permalink Blame History

ADR-003: Explorer Architecture

Status

Accepted

Context

The Binect Explorer needs to be a browser-based interactive tool for:

Learning the Binect API
Experimentation and evaluation
Safe testing before production integration

Per the TSD (Section 4), the Explorer:

Must operate without server-side components
Must clearly distinguish between preview and send operations
Must require explicit confirmation for destructive actions
Is a learning tool, not an operations dashboard

Decision

1. Technology Stack

We use a vanilla JavaScript/HTML/CSS approach:

No framework dependencies (React, Vue, etc.)
Single HTML file with embedded CSS and JS
Can use the SDK directly via module import
Easy to host as a static file

Rationale: Per TSD Section 7, the product must remain independent of specific UI frameworks. A vanilla approach ensures maximum portability and simplicity.

2. Architecture Pattern

Component-based with vanilla JS:

Modular JavaScript functions for each feature
Event-driven UI updates
State management via simple objects

3. Feature Organization

The Explorer UI is organized around the API domains:

Credentials Panel: Input and manage API credentials
Documents Panel: Upload, view, manage documents
Sendings Panel: Announce and track mail dispatch
Attachments Panel: Manage attachments
Account Panel: View account info and options

4. Safety Features

Per TSD requirements:

Credentials are ephemeral by default (cleared on page refresh)
Optional local storage for convenience (opt-in)
Send operations require explicit confirmation dialog
Preview available before sending
Clear visual distinction between safe (read) and destructive (send/delete) actions

5. Use Case Profiles

Stored in browser localStorage
Export/import as JSON files
Contain only parameter configurations, not workflows

Consequences

Positive

Zero external dependencies
Works as single HTML file
Easy to understand and modify
Can be hosted anywhere (CDN, local file, etc.)
Aligns with TSD requirement for framework independence

Negative

Less sophisticated UI compared to framework-based apps
Manual DOM manipulation
No virtual DOM or reactive updates

References

TSD: Section 4 (Explorer Technical Orientation)
PRD: Section 4.1 (Functional Expectations)

2.3 KiB Raw Permalink Blame History