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:
47
CLAUDE.md
47
CLAUDE.md
@@ -2,38 +2,57 @@
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Build Commands
|
||||
|
||||
```bash
|
||||
npm install # Install dependencies
|
||||
npm run build # Build TypeScript to dist/
|
||||
npm test # Run tests with vitest
|
||||
npm run typecheck # Type check without emitting
|
||||
```
|
||||
|
||||
## Project Overview
|
||||
|
||||
Binect-JS is a JavaScript/TypeScript wrapper for the Binect REST API (https://app.binect.de/index.jsp?id=api) that enables sending PDF documents as physical mail. The project consists of two artifacts:
|
||||
|
||||
1. **Binect-JS SDK** (`@binect/js`) - A thin API wrapper
|
||||
2. **Binect Explorer** (`@binect/explorer`) - A browser-based interactive tool for learning and experimentation
|
||||
1. **Binect-JS SDK** (`@binect/js`) - A thin API wrapper in `src/`
|
||||
2. **Binect Explorer** - A browser-based interactive tool in `explorer/`
|
||||
|
||||
## Architecture Principles
|
||||
## Architecture
|
||||
|
||||
The SDK is organized around domain-aligned sub-clients that mirror the API vocabulary:
|
||||
- `documents` - PDF upload, status inspection, parameter modification
|
||||
- `attachments` - Attachment handling
|
||||
- `sendings` - Mail dispatch triggers, cancellation
|
||||
- `accounts` - Account management
|
||||
- `invoices` - Invoice access
|
||||
- `client.documents` - PDF upload, status inspection, parameter modification
|
||||
- `client.attachments` - Attachment handling
|
||||
- `client.sendings` - Mail dispatch triggers, cancellation
|
||||
- `client.accounts` - Account management
|
||||
- `client.invoices` - Invoice access
|
||||
|
||||
### SDK Layer Separation
|
||||
|
||||
**Core API Layer** (authoritative): 1:1 semantic mapping to REST endpoints. Methods like `documents.uploadPdf`, `documents.getStatus`, `sendings.announce`, `sendings.cancel`.
|
||||
**Core API Layer** (authoritative): 1:1 semantic mapping to REST endpoints. Methods like `documents.upload`, `documents.get`, `sendings.send`, `sendings.cancel`.
|
||||
|
||||
**Convenience Layer** (optional, non-authoritative): Additive helpers like status predicates (`isShippable`), error extraction, polling helpers. These must never be the only way to perform an action.
|
||||
**Convenience Layer** (optional, non-authoritative): Additive helpers in `src/helpers.ts` like status predicates (`isShippable`), error extraction, polling helpers. These must never be the only way to perform an action.
|
||||
|
||||
## Design Constraints
|
||||
|
||||
- **No backend dependency**: Must function entirely in browser/JS runtime
|
||||
- **No runtime dependencies**: Uses native `fetch` API only
|
||||
- **No semantic reinterpretation**: Wrapper must not alter business meaning or outcomes
|
||||
- **Transparency over abstraction**: Developers must reason about actual API calls
|
||||
- **No default retries**: Network behavior must be explicit and opt-in
|
||||
- **Authentication**: HTTP Basic Auth, credentials are ephemeral (not stored/cached)
|
||||
|
||||
## Key Files
|
||||
|
||||
- `src/client.ts` - Main BinectClient class
|
||||
- `src/clients/*.ts` - Domain sub-clients
|
||||
- `src/types.ts` - TypeScript type definitions
|
||||
- `src/errors.ts` - BinectApiError and BinectAuthError
|
||||
- `src/http.ts` - Low-level HTTP client
|
||||
- `src/helpers.ts` - Convenience helpers (predicates, polling)
|
||||
- `explorer/index.html` - Standalone Explorer UI
|
||||
|
||||
## API Integration Notes
|
||||
|
||||
- Uploads use base64-encoded PDFs
|
||||
- All non-success responses surface as structured errors preserving HTTP status, endpoint, and parsed response
|
||||
- The wrapper does not reinterpret business errors from the API
|
||||
- Uploads use base64-encoded PDFs (max 12 MB)
|
||||
- All non-success responses surface as structured `BinectApiError`
|
||||
- Document status codes: 1=Preparing, 2=Shippable, 3=Queue, 4=Printing, 5=Sent, 6=Canceled, 7=Error
|
||||
|
||||
Reference in New Issue
Block a user