From 5c1d26afbaa4b7d8bb7d72ff041403246c5ad312 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 14 Jan 2026 16:47:25 +0100 Subject: [PATCH] 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 --- .gitignore | 195 +++-------------- CLAUDE.md | 39 ++++ ProductRequirementsDocument.md | 225 +++++++++++++++++++ README.md | 12 +- TechnicalSpecificationDocument.md | 353 ++++++++++++++++++++++++++++++ 5 files changed, 655 insertions(+), 169 deletions(-) create mode 100644 CLAUDE.md create mode 100644 ProductRequirementsDocument.md create mode 100644 TechnicalSpecificationDocument.md diff --git a/.gitignore b/.gitignore index 36b13f1..91e24b0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,176 +1,37 @@ -# ---> Python -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class +# Dependencies +node_modules/ -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ +# Build output dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST +build/ +*.tsbuildinfo -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -.pybuilder/ -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: -# .python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# UV -# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -#uv.lock - -# poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock - -# pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -#pdm.lock -# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it -# in version control. -# https://pdm.fming.dev/latest/usage/project/#working-with-version-control -.pdm.toml -.pdm-python -.pdm-build/ - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments +# Environment files .env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ +.env.local +.env.*.local -# Spyder project settings -.spyderproject -.spyproject +# IDE +.idea/ +.vscode/ +*.swp +*.swo -# Rope project settings -.ropeproject +# OS files +.DS_Store +Thumbs.db -# mkdocs documentation -/site +# Logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ - -# Ruff stuff: -.ruff_cache/ - -# PyPI configuration file -.pypirc +# Test coverage +coverage/ +.nyc_output/ +# Temporary files +tmp/ +temp/ +*.tmp diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f5cfe75 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,39 @@ +# 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 diff --git a/ProductRequirementsDocument.md b/ProductRequirementsDocument.md new file mode 100644 index 0000000..36727e1 --- /dev/null +++ b/ProductRequirementsDocument.md @@ -0,0 +1,225 @@ +# Product Requirements Document (PRD) + +## Product: **Binect-JS API Wrapper** + +--- + +## 1. Product Overview + +### 1.1 Product Name + +**Binect-JS API Wrapper** +(working title; final package naming is out of scope for this PRD) + +### 1.2 Product Intent + +Binect-JS is a **developer-facing integration product** that enables JavaScript developers to **interact reliably and intuitively with the Binect API** to send PDF documents as physical mail. + +The product’s primary intent is to **lower the cognitive, technical, and experiential barrier** for first-time and recurring users of the Binect API—especially in browser-based and JavaScript-centric environments—without changing the underlying Binect service. + +### 1.3 Problem Statement + +While the Binect API provides comprehensive functionality for physical mail dispatch, it presents several challenges to developers: + +* The API is **low-level and REST-centric**, requiring significant upfront interpretation. +* Developers must manually handle: + + * authentication + * base64 encoding + * document lifecycle states + * error interpretation +* There is no **official JavaScript abstraction** or **exploratory tooling** that supports learning, testing, and safe experimentation. + +As a result, developers face: + +* higher onboarding friction +* increased implementation errors +* duplicated integration effort across projects + +--- + +## 2. Target Users and Stakeholders + +### 2.1 Primary Users + +* JavaScript and TypeScript developers +* Frontend developers integrating physical mail into web applications +* Full-stack developers building document workflows +* Solution engineers evaluating Binect for customer projects + +### 2.2 Secondary Stakeholders + +* Product management (Binect ecosystem) +* Technical sales and pre-sales +* Developer support and onboarding teams +* Partner developers building reusable integrations + +--- + +## 3. Product Goals + +### 3.1 Primary Goals + +* **Reduce integration effort** for JavaScript developers using the Binect API +* **Increase correctness and reliability** of API usage +* **Improve discoverability** of Binect API capabilities +* **Support rapid experimentation** without backend infrastructure + +### 3.2 Secondary Goals + +* Serve as a **reference integration** for good API usage patterns +* Act as a **learning surface** for understanding document validation and sending workflows +* Provide a **shared vocabulary and structure** for downstream tooling and documentation + +--- + +## 4. Scope + +### 4.1 In Scope + +#### Functional Expectations (Conceptual) + +* Enable JavaScript-based interaction with the Binect API for: + + * uploading PDF documents + * inspecting document readiness and validation state + * modifying document-related parameters + * triggering physical mail dispatch + * observing sending status and outcomes +* Provide an **interactive, browser-based explorer** that: + + * allows credential input + * allows safe execution of API calls + * visualizes results in both structured and raw form + * supports reusable, named “use case profiles” + +#### Usage Context + +* Usable as: + + * a **local developer tool** + * a **hosted static web application** +* Applicable to: + + * exploratory usage + * prototyping + * production integration support + +### 4.2 Explicit Non-Scope + +* No redesign or modification of the Binect backend API +* No replacement of backend integrations or enterprise workflows +* No PDF generation, editing, or layout tooling +* No scheduling, batching, or business process orchestration +* No commitment to a specific UI framework or architectural pattern + +--- + +## 5. Assumptions and Constraints + +### 5.1 Assumptions + +* The Binect API is accessible via HTTPS using Basic Authentication +* API access is permitted directly from browser environments (no CORS restriction) +* Users possess valid Binect credentials +* Developers have access to PDFs already prepared for sending + +### 5.2 Constraints + +* The product must operate **without server-side components** +* Sensitive information must not be stored unintentionally +* The wrapper must not obscure or reinterpret business-critical API semantics +* The product must remain compatible with future Binect API evolution + +--- + +## 6. Success Criteria + +### 6.1 Qualitative Success Indicators + +* Developers can complete a “send physical mail” workflow **without consulting raw API documentation** +* First-time users can validate and preview documents before sending +* The Explorer is usable as a **learning tool**, not just a test harness +* API errors are understandable and actionable + +### 6.2 Quantitative / Observable Indicators + +* Reduction in support inquiries related to JavaScript integrations +* Decreased integration time reported by developers +* Reuse of the wrapper across multiple projects or partners +* Adoption of Explorer during onboarding or demos + +--- + +## 7. Non-Functional Expectations + +### 7.1 Usability + +* Clear mental mapping between user actions and API effects +* Safe defaults that prevent accidental mail dispatch +* Transparent presentation of API responses + +### 7.2 Reliability + +* Predictable handling of network and API errors +* Explicit representation of document and sending states + +### 7.3 Security & Trust + +* Credentials handled with care and minimal persistence +* No hidden data transmission or telemetry +* Clear user control over destructive actions (send, cancel, delete) + +### 7.4 Maintainability + +* Product intent remains stable even as API details evolve +* Wrapper serves as a single adaptation layer for API changes + +--- + +## 8. Dependencies and External Interfaces + +### 8.1 External Dependencies + +* Binect REST API +* Browser and JavaScript runtime capabilities (fetch, crypto, storage) + +### 8.2 Downstream Artifacts + +This PRD intentionally precedes and informs: + +* Functional Requirements Specification (FRS) +* Technical Design Documents (TDD) +* Architecture Decision Records (ADR) +* SDK and Explorer implementation plans + +--- + +## 9. Risks and Mitigations + +| Risk | Impact | Mitigation | +| ------------------------ | -------------------- | -------------------------------------------------- | +| API behavior changes | Integration breakage | Wrapper as adaptation layer | +| Over-abstracting API | Loss of control | Keep wrapper thin and transparent | +| Accidental mail dispatch | User trust erosion | Explicit confirmations and preview-first workflows | +| Scope creep | Delayed delivery | Strong adherence to PRD boundaries | + +--- + +## 10. PRD Variant Classification + +This document represents a **Hybrid / Boundary PRD**: + +* Sufficiently precise to anchor engineering decisions +* Flexible enough to accommodate iterative refinement +* Explicitly positioned between product intent and implementation design + +--- + +## 11. Traceability Note + +This PRD acts as the **intent anchor** for all downstream decisions. +Any architectural or technical decision should be explainable as a consequence of: + +> “Enabling safe, intuitive JavaScript access to the Binect API for document-based physical mail workflows.” + diff --git a/README.md b/README.md index fcd7b8f..df62a34 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,11 @@ -# repo-seed +BinectJs -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +*Javascript Binect API wrapper* + +# Binect JS - Send Papermail from your Browser + +An easy to use javascript library to send pdf-documents as papermail using the app.binect.de API. + +For documentation of the API see: https://app.binect.de/index.jsp?id=api + +xxx diff --git a/TechnicalSpecificationDocument.md b/TechnicalSpecificationDocument.md new file mode 100644 index 0000000..ea93f5f --- /dev/null +++ b/TechnicalSpecificationDocument.md @@ -0,0 +1,353 @@ +TechnicalSpecificationDocument + +*Implementation strategy for binect-js* + +# Technical Specification (TSD) + +## Binect-JS API Wrapper & Explorer + +**PRD-aligned / Pre-Implementation Version** + +--- + +## 0. Positioning and Authority + +This Technical Specification derives its authority **exclusively from the PRD** and serves as a **design-orientation document**, not a binding implementation plan. + +It: + +* refines **how the product intent may be realized** +* makes **explicit what is optional, configurable, or deferred** +* avoids encoding decisions that would normally belong in ADRs + +Where uncertainty exists, the TSD **preserves option space**. + +--- + +## 1. Product Composition + +### 1.1 Product Boundary + +The product **Binect-JS** consists of two coordinated but separable artifacts: + +1. **Binect-JS SDK** + A JavaScript / TypeScript wrapper around the Binect REST API. + +2. **Binect Explorer** + A browser-based interactive tool that uses the SDK to support: + + * learning + * experimentation + * evaluation + * integration understanding + +Together they form **one developer-facing product**, but neither depends on the other for correctness. + +--- + +## 2. Design Guardrails (Derived from PRD) + +The following constraints are **non-negotiable** and shape all downstream decisions: + +1. **No backend dependency** + The product must function entirely in browser and JavaScript runtime environments. + +2. **No semantic reinterpretation of the Binect API** + The wrapper must not alter business meaning, rules, or outcomes. + +3. **Transparency over abstraction** + Developers must be able to reason about what API calls occur and why. + +4. **Learning-first, not operations-first** + Especially for the Explorer: this is *not* a production operations console. + +5. **Optionality over prescription** + Features that imply policy (retries, persistence, automation) must be opt-in. + +--- + +## 3. SDK Technical Orientation (`@binect/js`) + +### 3.1 Role of the SDK + +The SDK’s role is to: + +* provide a **stable adaptation layer** +* reduce accidental misuse of the API +* improve readability and discoverability +* centralize API evolution handling + +It is **not** intended to: + +* orchestrate workflows +* enforce sending policies +* optimize delivery behavior + +--- + +### 3.2 API Surface Structure + +The SDK exposes **domain-aligned sub-clients** that mirror the API vocabulary: + +* `documents` +* `attachments` +* `sendings` +* `accounts` +* `invoices` + +This structure is **intentional**: + +* it preserves traceability to API documentation +* it avoids hiding capabilities behind synthetic abstractions + +--- + +### 3.3 Core vs Convenience Layers (Explicit Separation) + +The SDK is conceptually divided into two layers: + +#### A) Core API Layer (authoritative) + +* 1:1 semantic mapping to REST endpoints +* minimal transformation +* predictable behavior +* no embedded policy + +Examples: + +* `documents.uploadPdf` +* `documents.getStatus` +* `sendings.announce` +* `sendings.cancel` + +This layer is **the reference layer**. + +#### B) Optional Convenience Layer (non-authoritative) + +* purely additive helpers +* must be clearly labeled as such +* must not be required for correct usage + +Examples (illustrative, not mandatory): + +* status predicates (`isShippable`) +* error extraction helpers +* polling helpers + +> **Important:** +> Convenience helpers may exist, but **must never be the only way** to perform an action. + +--- + +### 3.4 Authentication Handling + +* Authentication uses **HTTP Basic Auth**, passed transparently. +* The SDK: + + * does not store credentials + * does not cache auth headers beyond request scope + * does not log sensitive values + +Credential lifecycle management is **explicitly out of scope** for the SDK. + +--- + +### 3.5 Upload & Payload Handling + +* The SDK supports base64-encoded PDF uploads as required by the API. +* It may provide: + + * size estimation helpers + * early warnings when payloads approach known limits + +These helpers: + +* are advisory only +* do not block execution unless explicitly configured + +--- + +### 3.6 Error Handling Model + +* All non-success responses are surfaced as structured errors. +* Errors preserve: + + * HTTP status + * endpoint identity + * parsed response payload where available + +The SDK **does not reinterpret business errors**, but may: + +* expose helpers to *extract* or *summarize* validation issues. + +--- + +### 3.7 Retries, Timeouts, and Network Behavior (Revised) + +**Change from previous TSD:** +All default retry semantics have been **removed**. + +Current stance: + +* The SDK **does not imply any retry behavior** +* Network behavior is: + + * explicit + * configurable + * opt-in + +If retry helpers are provided: + +* they must be **disabled by default** +* they must be **clearly documented as potentially unsafe** for send operations + +Timeouts, retries, and backoff strategies are **configuration concerns**, not product guarantees. + +--- + +## 4. Explorer Technical Orientation (`@binect/explorer`) + +### 4.1 Role of the Explorer + +The Explorer exists to: + +* reduce onboarding friction +* make the API *legible* +* allow safe experimentation +* support pre-integration evaluation + +It is **not** intended to: + +* replace backend integrations +* act as an operations dashboard +* support long-running or automated workflows + +--- + +### 4.2 Functional Scope + +The Explorer supports: + +* credential input +* document upload and inspection +* previewing normalized output +* triggering send/cancel actions +* inspecting raw and summarized responses +* storing named **use case profiles** + +All actions are **user-initiated**. + +--- + +### 4.3 Use Case Profiles (Conceptual) + +Profiles represent: + +* a reusable *parameter constellation* +* not a workflow definition +* not a business rule + +Profiles may include: + +* document options +* attributes +* cover page parameters +* attachment references +* sending mode (upload vs send) + +Profiles: + +* are stored locally +* can be exported/imported +* have no implicit execution semantics + +--- + +### 4.4 Credential Handling (Reframed) + +**Change from previous TSD:** +Credential persistence is no longer a default design feature. + +Current stance: + +* Credentials are **ephemeral by default** +* Optional persistence may exist as a **user-initiated UX enhancement** +* No persistence is required to meet product intent + +Cryptographic details and storage mechanisms are **explicitly design-time decisions**, deferred until implementation. + +--- + +### 4.5 Safety and Trust + +The Explorer must: + +* clearly distinguish between *preview* and *send* +* require explicit confirmation for destructive actions +* surface consequences before execution + +Safety is achieved through **interaction design**, not enforcement logic. + +--- + +## 5. Non-Functional Orientation + +### 5.1 Usability + +* API capabilities must be discoverable through interaction. +* Raw API responses must remain accessible. + +### 5.2 Reliability + +* Failures must be visible and explainable. +* Silent retries or hidden corrections are disallowed. + +### 5.3 Maintainability + +* The SDK must tolerate API evolution without breaking product intent. +* The Explorer must remain usable even as API features expand. + +--- + +## 6. Out-of-Scope Reinforcement (Explicit) + +The following are **explicitly excluded** from this TSD: + +* scheduling +* batching +* automation +* background job execution +* business rule enforcement +* policy encoding + +Any future inclusion of these concerns requires: + +* PRD revision **or** +* explicit ADRs + +--- + +## 7. Traceability Note + +This TSD is intentionally **non-binding** with respect to: + +* architectural patterns +* libraries +* UI frameworks +* storage mechanisms + +Its sole purpose is to ensure that **implementation choices remain aligned with product intent as defined in the PRD**. + +--- + +## 8. Status + +* **TSD** is **PRD-aligned** +* Safe to use as: + + * implementation briefing + * review baseline + * pre-ADR reference + + +xxx