generated from coulomb/repo-seed
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>
This commit is contained in:
195
.gitignore
vendored
195
.gitignore
vendored
@@ -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
|
||||
|
||||
39
CLAUDE.md
Normal file
39
CLAUDE.md
Normal file
@@ -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
|
||||
225
ProductRequirementsDocument.md
Normal file
225
ProductRequirementsDocument.md
Normal file
@@ -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.”
|
||||
|
||||
12
README.md
12
README.md
@@ -1,3 +1,11 @@
|
||||
# repo-seed
|
||||
BinectJs
|
||||
|
||||
A git repository template to bootstrap coulomb projects from.
|
||||
*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
|
||||
|
||||
353
TechnicalSpecificationDocument.md
Normal file
353
TechnicalSpecificationDocument.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user