generated from coulomb/repo-seed
Add Binect SDK implementation, Explorer, and test suite
SDK (@binect/js): - BinectClient with domain sub-clients (documents, sendings, accounts, attachments, invoices) - HTTP Basic Auth, native fetch only (no runtime dependencies) - TypeScript types matching Binect API vocabulary - Status predicates and polling helpers in helpers.ts - Structured error handling (BinectApiError, BinectAuthError) Explorer: - Standalone browser-based API explorer (explorer/index.html) - Interactive testing without code Tests: - Unit tests for client, types, errors, helpers, http - E2E tests for upload/delete and send/cancel workflows Also includes: - Architecture Decision Records (ADRs) - Example DIN 5008 letter PDFs for testing - API specification research notes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
207
README.md
207
README.md
@@ -1,11 +1,206 @@
|
||||
BinectJs
|
||||
# Binect-JS
|
||||
|
||||
*Javascript Binect API wrapper*
|
||||
A JavaScript/TypeScript wrapper for the [Binect API](https://app.binect.de/index.jsp?id=api) to send PDF documents as physical mail via Deutsche Post.
|
||||
|
||||
# Binect JS - Send Papermail from your Browser
|
||||
## Features
|
||||
|
||||
An easy to use javascript library to send pdf-documents as papermail using the app.binect.de API.
|
||||
- **SDK (`@binect/js`)**: Type-safe API wrapper with domain-aligned sub-clients
|
||||
- **Explorer**: Browser-based interactive tool for learning and testing the API
|
||||
- **Zero Dependencies**: Uses native `fetch` API, works in browsers and Node.js >= 18
|
||||
|
||||
For documentation of the API see: https://app.binect.de/index.jsp?id=api
|
||||
## Installation
|
||||
|
||||
xxx
|
||||
```bash
|
||||
npm install @binect/js
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
import { BinectClient, DocumentStatus, isShippable } from '@binect/js';
|
||||
import { readFileSync } from 'fs';
|
||||
|
||||
// Create client with your Binect credentials
|
||||
const client = new BinectClient({
|
||||
username: 'your@email.com',
|
||||
password: 'your-password',
|
||||
});
|
||||
|
||||
// Upload a PDF document
|
||||
const pdfContent = readFileSync('letter.pdf').toString('base64');
|
||||
const document = await client.documents.upload({
|
||||
content: pdfContent,
|
||||
color: false,
|
||||
duplex: true,
|
||||
envelope: 'DINLANG',
|
||||
});
|
||||
|
||||
console.log('Document ID:', document.documentId);
|
||||
console.log('Status:', document.status);
|
||||
|
||||
// Check if ready to send
|
||||
if (isShippable(document)) {
|
||||
// Send the document as physical mail
|
||||
const sending = await client.sendings.send(document.documentId);
|
||||
console.log('Mail dispatched!');
|
||||
}
|
||||
```
|
||||
|
||||
## SDK API Reference
|
||||
|
||||
The SDK provides domain-aligned sub-clients:
|
||||
|
||||
### Documents (`client.documents`)
|
||||
|
||||
- `upload(options)` - Upload a PDF document
|
||||
- `list(pagination?)` - List shippable documents
|
||||
- `listErrors(pagination?)` - List documents with errors
|
||||
- `get(documentId)` - Get document details
|
||||
- `delete(documentId)` - Delete a document
|
||||
- `getPdf(documentId)` - Get PDF preview
|
||||
- `getPng(documentId)` - Get PNG preview
|
||||
- `getAttributes(documentId)` - Get document attributes
|
||||
- `setAttributes(documentId, attributes)` - Set attributes
|
||||
- `applyTransformation(documentId, transformation)` - Apply scaling/offset
|
||||
- `addCoverPage(documentId, options)` - Add cover page
|
||||
|
||||
### Sendings (`client.sendings`)
|
||||
|
||||
- `announce(documentIds)` - Announce documents for delivery
|
||||
- `list(pagination?)` - List all sendings
|
||||
- `send(documentId)` - Trigger single document send
|
||||
- `cancel(documentId)` - Cancel a sending
|
||||
- `getStatus(documentIds)` - Batch status check
|
||||
|
||||
### Attachments (`client.attachments`)
|
||||
|
||||
- `upload(options)` - Upload an attachment
|
||||
- `list(pagination?)` - List all attachments
|
||||
- `get(attachmentId)` - Get attachment details
|
||||
- `delete(attachmentId)` - Delete an attachment
|
||||
- `attachToDocuments(attachmentId, documentIds)` - Attach to documents
|
||||
|
||||
### Accounts (`client.accounts`)
|
||||
|
||||
- `get()` - Get account balance/credit info
|
||||
- `getPersonalData()` - Get personal data
|
||||
- `updatePersonalData(data)` - Update personal data
|
||||
- `getOptions()` - Get default print options
|
||||
- `updateOptions(options)` - Update print options
|
||||
- `getJournal(month)` - Get transaction journal
|
||||
|
||||
### Invoices (`client.invoices`)
|
||||
|
||||
- `list(pagination?)` - List all invoices
|
||||
- `get(invoiceNumber)` - Get invoice details
|
||||
- `getPdf(invoiceNumber)` - Download invoice PDF
|
||||
|
||||
## Convenience Helpers
|
||||
|
||||
```typescript
|
||||
import {
|
||||
isShippable,
|
||||
isErroneous,
|
||||
isSent,
|
||||
isTerminal,
|
||||
isCancelable,
|
||||
hasErrors,
|
||||
hasWarnings,
|
||||
getErrors,
|
||||
getStatusDescription,
|
||||
waitForShippable,
|
||||
fileToBase64,
|
||||
} from '@binect/js';
|
||||
|
||||
// Status predicates
|
||||
if (isShippable(document)) { /* ... */ }
|
||||
if (isErroneous(document)) { /* ... */ }
|
||||
|
||||
// Validation helpers
|
||||
const errors = getErrors(document);
|
||||
if (hasWarnings(document)) {
|
||||
console.log('Document has warnings');
|
||||
}
|
||||
|
||||
// Polling (opt-in)
|
||||
const readyDoc = await waitForShippable(
|
||||
() => client.documents.get(docId),
|
||||
{ intervalMs: 2000, maxAttempts: 30 }
|
||||
);
|
||||
|
||||
// Base64 encoding (browser)
|
||||
const file = document.querySelector('input[type="file"]').files[0];
|
||||
const base64 = await fileToBase64(file);
|
||||
```
|
||||
|
||||
## Explorer
|
||||
|
||||
The Binect Explorer is a browser-based interactive tool for:
|
||||
- Learning the Binect API
|
||||
- Testing document uploads and mail dispatch
|
||||
- Managing use case profiles
|
||||
|
||||
Open `explorer/index.html` in a browser to use it.
|
||||
|
||||
## Document Status Codes
|
||||
|
||||
| Code | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 1 | IN_PREPARATION | Document is being validated |
|
||||
| 2 | SHIPPABLE | Ready to send |
|
||||
| 3 | PRODUCTION_QUEUE | In production queue |
|
||||
| 4 | PRINTING | Currently printing |
|
||||
| 5 | SENT | Mail has been sent |
|
||||
| 6 | CANCELED | Sending was canceled |
|
||||
| 7 | ERRONEOUS | Document has validation errors |
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build
|
||||
npm run build
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Run e2e tests (requires Binect credentials)
|
||||
BINECT_USERNAME=your@email.com BINECT_PASSWORD=yourpass npm run test:e2e
|
||||
|
||||
# Type check
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
binect-js/
|
||||
├── src/ # SDK source code
|
||||
│ ├── client.ts # Main BinectClient
|
||||
│ ├── clients/ # Domain sub-clients
|
||||
│ ├── types.ts # Type definitions
|
||||
│ ├── errors.ts # Error classes
|
||||
│ ├── http.ts # HTTP layer
|
||||
│ └── helpers.ts # Convenience helpers
|
||||
├── explorer/ # Browser-based Explorer UI
|
||||
├── tests/ # Test suite
|
||||
├── architecture/ # Architecture Decision Records
|
||||
└── research/ # API documentation research
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
See [architecture/](./architecture/) for Architecture Decision Records (ADRs):
|
||||
- ADR-001: SDK Architecture
|
||||
- ADR-002: No External Dependencies
|
||||
- ADR-003: Explorer Architecture
|
||||
|
||||
## API Documentation
|
||||
|
||||
Official Binect API documentation: https://app.binect.de/index.jsp?id=api
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user