# CLAUDE.md

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

## 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

## Architecture Principles

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

### SDK Layer Separation

**Core API Layer** (authoritative): 1:1 semantic mapping to REST endpoints. Methods like `documents.uploadPdf`, `documents.getStatus`, `sendings.announce`, `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.

## Design Constraints

- **No backend dependency**: Must function entirely in browser/JS runtime
- **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)

## 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