binect-js/CLAUDE.md

# 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