generated from coulomb/repo-seed
tegwick
5c1d26afba
- Add PRD and TSD defining SDK and Explorer architecture - Add CLAUDE.md with project guidance for Claude Code - Update README with project description - Replace Python .gitignore with JS/TS configuration Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
40 lines
1.9 KiB
Markdown
40 lines
1.9 KiB
Markdown
# 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
|