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>

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