binect-js/README.md

# Binect-JS

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.

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

```bash
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.

```typescript
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`:

```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:

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

# In your project
npm link @binect/js
```

### Publishing (maintainers)

Pre-publish checklist:

```bash
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):

```bash
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):

```bash
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](#quick-start) below.

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

```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

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