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 (recommended)

npm install @binect/js

Requires Node.js ≥ 18. The package ships pre-built dist/ output and TypeScript declarations — no build step needed in your project.

import { BinectClient, DocumentStatus, isShippable } from '@binect/js';

Local development (before publish or when hacking on the SDK)

Path reference — add to your consumer package.json:

{
  "dependencies": {
    "@binect/js": "file:../binect-js"
  }
}

Then npm install. Adjust the path to your clone location. The SDK must be built first (npm run build in the binect-js directory).

npm link — for iterative SDK work:

# In the binect-js directory
npm install && npm run build && npm link

# In your project
npm link @binect/js

Publishing (maintainers)

Pre-publish checklist:

npm install
npm run clean && npm run build   # produces dist/ with .js, .d.ts, source maps
npm run typecheck                # strict TS, no emit
npm test                         # unit tests (62); e2e skips without credentials
npm pack --dry-run               # verify tarball contents (dist/, LICENSE, README)

E2E tests against the live Binect API (optional, credential-gated):

BINECT_USERNAME=your@email.com BINECT_PASSWORD=yourpass npm run test:e2e

Publish to the public npm registry (scoped package @binect/js requires --access public on first publish; publishConfig in package.json sets this automatically):

npm login                        # npm account with @binect org access
npm publish                      # runs prepublishOnly → npm run build

After publish, consumers install with npm install @binect/js — see Quick Start below.

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,
  filename: 'letter.pdf',
  color: false,
  simplex: false,  // false = duplex (double-sided)
  envelope: 'DINLANG',
  franking: 'STANDARD_FRANKING',
});

console.log('Document ID:', document.id);
console.log('Status:', document.status.code, document.status.text);

// Check if ready to send
if (isShippable(document)) {
  // Send the document as physical mail
  await client.sendings.send(String(document.id));
  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

Using AI Coding Agents

This library includes an AGENTS.md file with comprehensive instructions for AI coding assistants (Claude, Cursor, Copilot, etc.).

Setup for AI Integration

1. Ensure the binect-js folder is accessible to your project
2. Copy AGENTS.md to your project root, or ensure the agent can read from binect-js

Example Prompts

To integrate the library into your project:

I want to add physical mail sending capability using the Binect API. The @binect/js library is located at ../binect-js. Please:

1. Add it as a dependency to my package.json
2. Create a mail service that can upload PDFs and send them as letters
3. Include proper error handling and status checking

Read AGENTS.md in the binect-js folder for API documentation.

To send a letter:

Using the @binect/js library, create a function that:

1. Takes a PDF file path and sends it as physical mail via Binect
2. Polls until the document is ready, then triggers sending
3. Returns the document ID and final status

Credentials are in environment variables BINECT_USERNAME and BINECT_PASSWORD.

To add mail functionality to an existing service:

Add a sendPhysicalMail(pdfBuffer: Buffer, options?: { color?: boolean }) method to my NotificationService class. Use the @binect/js library from ../binect-js. Handle errors appropriately and log the document status.

License

MIT