binect-js/README.md

Binect-JS

A JavaScript/TypeScript wrapper for the Binect API to send PDF documents as physical mail via Deutsche Post.

Features

• 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

Installation

npm install @binect/js

Quick Start

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

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

# 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/ 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