Files

tegwick 5c1d26afba Add project documentation and configure for JavaScript/TypeScript

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

2026-01-14 16:47:25 +01:00

1.9 KiB

Raw Blame History

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:

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

1.9 KiB Raw Blame History