generated from coulomb/repo-seed
Add State Hub bootstrap workplan and agent integration files
Seed workplans/ with bootstrap workplan to satisfy ADR-001 C-01. Includes regenerated dev-hub session-protocol and agent instruction files.
This commit is contained in:
70
CLAUDE.md
70
CLAUDE.md
@@ -1,58 +1,18 @@
|
||||
# CLAUDE.md
|
||||
# Binect-JS — Claude Code Instructions
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
@SCOPE.md
|
||||
@.claude/rules/repo-identity.md
|
||||
@.claude/rules/session-protocol.md
|
||||
@.claude/rules/first-session.md
|
||||
@.claude/rules/workplan-convention.md
|
||||
@.claude/rules/stack-and-commands.md
|
||||
@.claude/rules/architecture.md
|
||||
@.claude/rules/repo-boundary.md
|
||||
@.claude/rules/credential-routing.md
|
||||
@.claude/rules/agents.md
|
||||
|
||||
## Build Commands
|
||||
## Kaizen Agents
|
||||
|
||||
```bash
|
||||
npm install # Install dependencies
|
||||
npm run build # Build TypeScript to dist/
|
||||
npm test # Run tests with vitest
|
||||
npm run typecheck # Type check without emitting
|
||||
```
|
||||
|
||||
## 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 in `src/`
|
||||
2. **Binect Explorer** - A browser-based interactive tool in `explorer/`
|
||||
|
||||
## Architecture
|
||||
|
||||
The SDK is organized around domain-aligned sub-clients that mirror the API vocabulary:
|
||||
- `client.documents` - PDF upload, status inspection, parameter modification
|
||||
- `client.attachments` - Attachment handling
|
||||
- `client.sendings` - Mail dispatch triggers, cancellation
|
||||
- `client.accounts` - Account management
|
||||
- `client.invoices` - Invoice access
|
||||
|
||||
### SDK Layer Separation
|
||||
|
||||
**Core API Layer** (authoritative): 1:1 semantic mapping to REST endpoints. Methods like `documents.upload`, `documents.get`, `sendings.send`, `sendings.cancel`.
|
||||
|
||||
**Convenience Layer** (optional, non-authoritative): Additive helpers in `src/helpers.ts` like status predicates (`isShippable`), error extraction, polling helpers. These must never be the only way to perform an action.
|
||||
|
||||
## Design Constraints
|
||||
|
||||
- **No runtime dependencies**: Uses native `fetch` API only
|
||||
- **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)
|
||||
|
||||
## Key Files
|
||||
|
||||
- `src/client.ts` - Main BinectClient class
|
||||
- `src/clients/*.ts` - Domain sub-clients
|
||||
- `src/types.ts` - TypeScript type definitions
|
||||
- `src/errors.ts` - BinectApiError and BinectAuthError
|
||||
- `src/http.ts` - Low-level HTTP client
|
||||
- `src/helpers.ts` - Convenience helpers (predicates, polling)
|
||||
- `explorer/index.html` - Standalone Explorer UI
|
||||
|
||||
## API Integration Notes
|
||||
|
||||
- Uploads use base64-encoded PDFs (max 12 MB)
|
||||
- All non-success responses surface as structured `BinectApiError`
|
||||
- Document status codes: 1=Preparing, 2=Shippable, 3=Queue, 4=Printing, 5=Sent, 6=Canceled, 7=Error
|
||||
Specialized kaizen agent personas are available on demand via the state-hub MCP —
|
||||
discover with `list_kaizen_agents()` and load with `get_kaizen_agent("<name>")`,
|
||||
then read and follow their instructions. Full guidance in `.claude/rules/agents.md`.
|
||||
|
||||
Reference in New Issue
Block a user