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>
59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
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 in `src/`
|
|
2. **Binect Explorer** - A browser-based interactive tool in `explorer/`
|
|
|
|
## Architecture
|
|
|
|
The SDK is organized around domain-aligned sub-clients that mirror the API vocabulary:
|
|
- `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.upload`, `documents.get`, `sendings.send`, `sendings.cancel`.
|
|
|
|
**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 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 (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
|