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.4 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

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:

Binect-JS SDK (@binect/js) - A thin API wrapper in src/
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

2.4 KiB Raw Permalink Blame History