@allus-fyi/company-data 0.0.3

package/dist/types/models.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Output model — the conclusions.
+ *
+ * The consumer works with these and nothing else. They are produced by factories
+ * that turn a *hardened* API JSON object (slug-keyed `values`; NO person source
+ * field) into typed objects, decrypting ciphertext via the injected crypto closures.
+ *
+ *     RequestField { slug, label, type, oneTime, mandatory }   // YOUR request config
+ *     Connection   { id, personId, displayName, connectedAt, values: {<slug>: Value} }
+ *     Value        { value, live, updatedAt }
+ *     Change       { id, event, personId, shareCode?, slug?, value?, live?, at }   // id = stable dedup key
+ *     LogEntry     { type, message, metadata, at }
+ *
+ * Typed values:
+ *   - `email`/`phone`/`url`/`text` → string
+ *   - `address`/`bank`/`creditcard`  → a parsed object (the decrypted plaintext is a
+ *     JSON object string → parsed)
+ *   - `date`/`date_of_birth`         → a JS `Date` (UTC midnight; falls back to the
+ *     raw string if it can't be parsed)
+ *   - `photo`/`document`/`legal_document` → a lazy {@link BinaryHandle}
+ *     (`.bytes()` fetches the slot file endpoint, decrypts, parses the envelope,
+ *     base64-decodes the `full`/`file` data URI)
+ *
+ * Every model carries `.raw` — the underlying (hardened) API object — for debugging
+ * or an edge case the SDK didn't model. It never contains the person's source field.
+ *
+ * Decryption is config-driven: the factory takes a `decryptValue`
+ * callable (a closure over the loaded service private key) and, for binaries, a
+ * `binaryFetch` callable — never a key/secret argument.
+ */
+import { type BinaryFetch, type DecryptWrapper } from './crypto.js';
+/** Field types whose decrypted plaintext is a JSON object → a parsed object. */
+export declare const STRUCTURED_TYPES: readonly ["address", "bank", "creditcard"];
+/** Field types whose value is a lazy binary handle (served as a value_url). */
+export declare const BINARY_TYPES: readonly ["photo", "document", "legal_document"];
+/** Field types whose decrypted plaintext is an ISO date. */
+export declare const DATE_TYPES: readonly ["date", "date_of_birth"];
+/** A type resolver: slug -> the request field's type (e.g. "email", "photo"). */
+export type TypeForSlug = (slug: string) => string | null | undefined;
+type Json = Record<string, unknown>;
+/**
+ * A request-field DEFINITION — YOUR config, never the person's.
+ *
+ * `mandatory` folds the API's two flags: it is true when the field is mandatory to
+ * provide OR mandatory to stay connected.
+ */
+export declare class RequestField {
+    readonly slug: string;
+    readonly label: string;
+    readonly type: string;
+    readonly oneTime: boolean;
+    readonly mandatory: boolean;
+    readonly raw: Json;
+    constructor(slug: string, label: string, type: string, oneTime: boolean, mandatory: boolean, raw: Json);
+    static fromApi(obj: Json): RequestField;
+    /** Parse the `/request-fields` response → a list of definitions. */
+    static listFromApi(body: unknown): RequestField[];
+}
+/**
+ * A single answer for one of YOUR request slots.
+ *
+ * `value` is the typed plaintext (string / object / Date / lazy BinaryHandle);
+ * `live` = the person chose "keep connected" (auto-updates) vs a one-time snapshot;
+ * `updatedAt` = when this answer last changed. Both ride on the Value (per-answer),
+ * not the definition.
+ */
+export declare class Value {
+    readonly value: unknown;
+    readonly live: boolean;
+    readonly updatedAt: Date | null;
+    readonly raw: Json;
+    constructor(value: unknown, live: boolean, updatedAt: Date | null, raw: Json);
+    /** Build a typed Value from one hardened `{value|value_url, live, updatedAt}` entry. */
+    static fromApi(obj: Json, opts: {
+        fieldType: string | null | undefined;
+        decryptValue: DecryptWrapper;
+        binaryFetch?: BinaryFetch | null;
+    }): Value;
+}
+/**
+ * A connected person — identity + the slug-keyed value map.
+ *
+ * NO source field anywhere: `values` is keyed by YOUR request slug.
+ */
+export declare class Connection {
+    readonly id: string;
+    readonly personId: string;
+    readonly displayName: string | null;
+    readonly connectedAt: Date | null;
+    readonly values: Record<string, Value>;
+    readonly raw: Json;
+    constructor(id: string, personId: string, displayName: string | null, connectedAt: Date | null, values: Record<string, Value>, raw: Json);
+    /**
+     * Build a Connection from a hardened `connectionDetail` (or list) object.
+     *
+     * `connectionDetail` returns `{connection_id, user_id, values}` and no
+     * displayName/connectedAt, so those can be supplied via `identity` (the matching
+     * row from the list endpoint, which carries them).
+     */
+    static fromApi(obj: Json, opts: {
+        typeForSlug: TypeForSlug;
+        decryptValue: DecryptWrapper;
+        binaryFetch?: BinaryFetch | null;
+        identity?: Json;
+    }): Connection;
+}
+/**
+ * A change feed / webhook event.
+ *
+ * `id` is the stable server change-row id (the pump dedupes on it after a
+ * crash/replay); `at` is the change time (there is NO separate
+ * `updatedAt` on a change). `slug`/`value`/`live` are present only on
+ * `field_updated` (connection/consent events carry no slot/value).
+ */
+export declare class Change {
+    readonly id: string;
+    readonly event: string;
+    readonly personId: string | null;
+    /** The person's profile share code (present on every event; may be null). */
+    readonly shareCode: string | null;
+    readonly slug: string | null;
+    readonly value: unknown;
+    readonly live: boolean | null;
+    readonly at: Date | null;
+    readonly raw: Json;
+    constructor(id: string, event: string, personId: string | null, 
+    /** The person's profile share code (present on every event; may be null). */
+    shareCode: string | null, slug: string | null, value: unknown, live: boolean | null, at: Date | null, raw: Json);
+    /** Build a Change from one hardened changes-feed / webhook event object. */
+    static fromApi(obj: Json, opts: {
+        typeForSlug: TypeForSlug;
+        decryptValue: DecryptWrapper;
+        binaryFetch?: BinaryFetch | null;
+    }): Change;
+    /** Parse the `/changes` response → a list of typed Change events. */
+    static listFromApi(body: unknown, opts: {
+        typeForSlug: TypeForSlug;
+        decryptValue: DecryptWrapper;
+        binaryFetch?: BinaryFetch | null;
+    }): Change[];
+}
+/** A service activity-log entry — ops events only, never person data. */
+export declare class LogEntry {
+    readonly type: string;
+    readonly message: string | null;
+    readonly metadata: unknown;
+    readonly at: Date | null;
+    readonly raw: Json;
+    constructor(type: string, message: string | null, metadata: unknown, at: Date | null, raw: Json);
+    static fromApi(obj: Json): LogEntry;
+    /** Parse the `/logs` response → a list of log entries. */
+    static listFromApi(body: unknown): LogEntry[];
+}
+export {};

package/dist/types/pump.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Crash-safe streaming changes pump.
+ *
+ * The changes feed is a server-side **drain-on-fetch queue**: a fetch returns up to
+ * N events (default 100, max 500) and deletes those rows in the same transaction —
+ * the API keeps no copy. So consumption cannot be a plain list: a consumer crash
+ * mid-batch would lose events the API already deleted, and a huge backlog must not
+ * materialize in memory. The pump solves both:
+ *
+ *     processChanges(handler) — one Change at a time, until the feed is empty, then
+ *                               RETURNS. No follow/daemon mode (you schedule re-runs
+ *                               yourself).
+ *
+ * Per cycle:
+ *
+ *   1. **Replay first** — deliver any un-acked events already in the local buffer
+ *      (from a previous crashed run), oldest-first.
+ *   2. **Drain** — when the buffer is empty, fetch ONE batch (≤ batchSize, ≤500) and
+ *      **persist it to the durable buffer (fsync) BEFORE handing anything out**.
+ *   3. **Deliver one-by-one** — for each buffered event oldest-first: decrypt its
+ *      value (at delivery — never on disk), build the typed Change, call the handler.
+ *   4. **Ack / retry / dead-letter** — on success remove the event from the buffer;
+ *      on error retry with backoff up to maxRetries, then (onError "deadletter")
+ *      move it to the dead-letter store and continue (one poison event never wedges
+ *      the stream), or (onError "halt") stop and re-throw.
+ *   5. Repeat until a drain returns empty AND the buffer is drained → return.
+ *
+ * Durability invariants (every port preserves these):
+ *   (1) Decrypt INSIDE the delivery attempt — a DecryptError on a persisted poison
+ *       event is dead-lettered IMMEDIATELY (re-decrypt can't help → it does NOT burn
+ *       the retry budget); it never propagates out and wedges replay.
+ *   (2) A re-failing dead-letter is updated IN PLACE within deadletter/ (never routed
+ *       back through pending/).
+ *   (3) Stored attempt count is monotonic = max(existing, new) (handled by the buffer).
+ *   (4) dead_letter writes the new copy BEFORE unlinking pending (at-least-once safe).
+ *
+ * Injection (so tests + the real Client share one pump): the pump takes a
+ * `fetchChanges(limit) -> Promise<event[]>` source (the raw drain-on-fetch call,
+ * returning ciphertext event objects) and a `decrypt(event) -> Change` callable
+ * (closes over the loaded service private key — config-only key handling). No
+ * key/secret is ever a method argument.
+ */
+import { FileBuffer, type BufferedEvent, type DeadLetterRecord } from './buffer.js';
+import { Config } from './config.js';
+import { Change } from './models.js';
+export declare const MAX_BATCH = 500;
+/** A fetch source: given a limit, drain-and-return up to that many raw event objects. */
+export type FetchChanges = (limit: number) => Promise<BufferedEvent[]> | BufferedEvent[];
+/** A decrypt callable: raw event object -> typed Change (value decrypted at delivery). */
+export type DecryptChange = (event: BufferedEvent) => Change;
+/** The consumer handler: it does the side-effect; success acks, a throw retries. */
+export type Handler = (change: Change) => void | Promise<void>;
+/** A minimal logger sink (console-compatible). */
+export interface Logger {
+    debug?(message: string, ...args: unknown[]): void;
+    info?(message: string, ...args: unknown[]): void;
+    warn?(message: string, ...args: unknown[]): void;
+    error?(message: string, ...args: unknown[]): void;
+}
+export type OnError = 'deadletter' | 'halt';
+export interface ProcessOptions {
+    batchSize?: number;
+    maxRetries?: number;
+    onError?: OnError;
+    backoff?: (attempt: number) => number;
+}
+export interface PumpOptions {
+    fetchChanges: FetchChanges;
+    decrypt: DecryptChange;
+    logger?: Logger;
+    sleep?: (seconds: number) => Promise<void>;
+}
+/**
+ * The crash-safe changes pump.
+ *
+ * Wires a durable {@link FileBuffer} (under `config.cacheDir`) to an injected drain
+ * source + decrypt callable.
+ */
+export declare class Pump {
+    private readonly fetchChanges;
+    private readonly decryptChange;
+    private readonly log;
+    private readonly sleep;
+    private readonly _buffer;
+    constructor(config: Config, opts: PumpOptions);
+    get buffer(): FileBuffer;
+    /**
+     * Stream events through `handler` until the feed is empty, then return.
+     *
+     * `handler` is called with one typed {@link Change} at a time and must be
+     * idempotent (at-least-once delivery; dedup on `Change.id`).
+     *
+     * Options: `batchSize` (clamped ≤500), `maxRetries`, `onError`
+     * (`"deadletter"` — default — or `"halt"`), `backoff` (attempt → seconds).
+     */
+    processChanges(handler: Handler, options?: ProcessOptions): Promise<void>;
+    private drainIntoBuffer;
+    private deliverOne;
+    /**
+     * Raw, UNBUFFERED drain → a list of typed Changes (advanced).
+     *
+     * Fetches one batch (clamped ≤500) and returns the decrypted Changes directly — it
+     * does NOT persist anything to the buffer, so **you own durability** if you use it.
+     * Prefer {@link processChanges} for safe consumption.
+     */
+    drainBatch(max?: number): Promise<Change[]>;
+    /** The local dead-letter store (ciphertext + error + attempt count). */
+    deadLetters(): DeadLetterRecord[];
+    /**
+     * Re-drive every dead-lettered event through `handler`.
+     *
+     * On success the dead-letter record is removed; on repeated failure it is
+     * re-dead-lettered IN PLACE (`"deadletter"`) or the error is re-thrown (`"halt"`).
+     * They are never re-fetched from the API (it already deleted them) — the local
+     * store is their only home. Returns the count successfully re-driven.
+     */
+    retryDeadLetters(handler: Handler, options?: ProcessOptions): Promise<number>;
+}

package/dist/types/webhooks.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Webhook receiver helpers.
+ *
+ * The lower-latency push alternative to polling the changes feed. The platform
+ * delivers each change event to the company's configured webhook URL with:
+ *
+ *   - `X-Allus-Webhook-Id`  — which webhook this is (selects the HMAC secret).
+ *   - `X-Allus-Signature`   — `HMAC-SHA256(rawBody, secret)` as lowercase hex.
+ *   - the body — the same slug-keyed {@link Change} shape as the pull feed,
+ *     JSON or XML. If the webhook has `encrypt_payload` on, the body is REPLACED
+ *     by a `{"_enc":1,...}` envelope encrypted to the company **account** key (and
+ *     the HMAC is then over that envelope — it is the final body that was sent).
+ *
+ * Webhook delivery auth is per-webhook and may be any of five methods (hmac,
+ * bearer, basic, custom header, or none); {@link verifyWebhook} dispatches on the
+ * single method configured in {@link Config} ({@link Config.webhookAuthMethod}).
+ *
+ * All secrets/keys come from {@link Config}. **These helpers take NO key or secret
+ * arguments** — only the raw body, the headers, the config, and (for value typing)
+ * the same decrypt/type closures the {@link Client} already holds.
+ *
+ * The account-key envelope is webhook-specific: the platform wraps it with
+ * OpenSSL's DEFAULT OAEP padding (MGF1-**SHA1**), NOT the SHA-256 wrapper used for
+ * person field values. So unwrapping the envelope uses an OAEP-SHA1 path here
+ * (Node's default `oaepHash`, pinned explicitly to `'sha1'` for clarity), while the
+ * inner field `value` (still a service-key wrapper) decrypts with the normal
+ * SHA-256 {@link decrypt}. HMAC is always computed over the raw bytes, never the
+ * parsed tree.
+ */
+import { type KeyObject } from 'node:crypto';
+import { Config } from './config.js';
+import { type BinaryFetch, type DecryptWrapper } from './crypto.js';
+import { Change, type TypeForSlug } from './models.js';
+/** Headers as a (possibly mixed-case) string map. */
+export type Headers = Record<string, string | string[] | undefined>;
+interface ParseDeps {
+    typeForSlug: TypeForSlug;
+    decryptValue: DecryptWrapper;
+    binaryFetch?: BinaryFetch | null;
+    /** A pre-loaded account private key the Client caches; loaded on demand otherwise. */
+    accountKey?: KeyObject | null;
+}
+/**
+ * Verify a webhook against the SINGLE configured auth method.
+ *
+ * Mirrors the platform's per-webhook delivery auth (one method per webhook):
+ *
+ *   - `hmac`   — recompute `HMAC-SHA256(rawBody, secret)` (secret selected by
+ *     `X-Allus-Webhook-Id`) and constant-time-compare to `X-Allus-Signature`.
+ *   - `bearer` — `Authorization` equals `Bearer <token>`.
+ *   - `basic`  — `Authorization` equals `Basic <base64(user:pass)>`.
+ *   - `header` — the configured custom header equals the configured value.
+ *   - `none`   — always `true` (explicit opt-out).
+ *
+ * All comparisons are constant-time. Returns `false` on a missing/mismatched
+ * credential, or when no method is configured — never throws for a bad credential
+ * (that is {@link handleWebhook}'s job). Which method is used is decided entirely
+ * by config ({@link Config.webhookAuthMethod}); config loading guarantees at most
+ * one is set. The HMAC is over the exact raw bytes.
+ */
+export declare function verifyWebhook(rawBody: Buffer | Uint8Array | string, headers: Headers, config: Config): boolean;
+/**
+ * Parse a webhook body → a typed {@link Change}.
+ *
+ * Does NOT verify the signature (use {@link handleWebhook} for verify+parse).
+ * Handles JSON and XML bodies, and an `encrypt_payload` account-key envelope: if
+ * the (JSON) body is a `{"_enc":1,...}` wrapper, it is first unwrapped with the
+ * account private key (OAEP-SHA1) into the inner serialized payload, which is then
+ * parsed. The inner field `value` (a service-key wrapper) is decrypted by the same
+ * model factory the feed uses, so a webhook `Change` is byte-identical to a feed
+ * `Change`.
+ *
+ * `deps.accountKey` is an optional pre-loaded account private key (the
+ * {@link Client} loads it ONCE and reuses it, so an `encrypt_payload` webhook
+ * doesn't re-read the PEM + re-run PBKDF2 ~100k iters per request). When undefined,
+ * the key is loaded from config on demand — config-only key handling either way.
+ */
+export declare function parseWebhook(rawBody: Buffer | Uint8Array | string, headers: Headers, config: Config, deps: ParseDeps): Change;
+/**
+ * Verify + parse a webhook in one call.
+ *
+ * Throws {@link WebhookError} on a bad/unknown signature; otherwise returns the
+ * typed {@link Change}. The typical one-liner inside a webhook route. `deps.accountKey`
+ * (optional) is a pre-loaded account private key reused for the `encrypt_payload`
+ * envelope (see {@link parseWebhook}).
+ */
+export declare function handleWebhook(rawBody: Buffer | Uint8Array | string, headers: Headers, config: Config, deps: ParseDeps): Change;
+/**
+ * Load the account private key from config ONCE (or `null` if not configured).
+ *
+ * Reused by the {@link Client} so an `encrypt_payload` webhook never re-reads the
+ * PEM + re-runs PBKDF2 (~100k iters) per request — the account key is loaded a
+ * single time at client construction, exactly like the service key. Returns `null`
+ * when no `accountPrivateKey` is configured (the SDK only needs it for
+ * `encrypt_payload` webhooks). Throws {@link WebhookError} on a read / passphrase /
+ * PEM problem.
+ */
+export declare function loadAccountKey(config: Config): KeyObject | null;
+export {};

package/dist/types/xml.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Minimal, XXE-safe XML parser for the platform's wire serialization.
+ *
+ * The company-data API can serve XML (`Accept: application/xml` / `format: "xml"`).
+ * The platform serializer renders:
+ *
+ *   - a `<response>` document root;
+ *   - a list (int keys) as repeated `<item>` children — so an element whose
+ *     every child is `<item>` becomes an array;
+ *   - an associative array as named child tags — an object;
+ *   - scalars as element text (booleans were written as `"true"`/`"false"`).
+ *
+ * **XXE-safe by construction.** This is a hand-written recursive-descent parser
+ * (NOT a general XML library). It supports ONLY elements, text, comments, the XML
+ * declaration, CDATA, and the five built-in entities. It does NOT process a DOCTYPE
+ * / DTD, does NOT define or expand custom/general entities, and never resolves
+ * external entities or system identifiers — the classic XXE / billion-laughs
+ * vectors cannot occur because the machinery for them is simply absent. A DOCTYPE,
+ * a processing instruction other than the XML decl, or an unknown `&entity;`
+ * reference is rejected — entity expansion and external entity resolution don't
+ * exist here at all. HMAC verification is always computed over the raw bytes,
+ * never the parsed tree.
+ *
+ * This is intentionally small — JSON is the default wire format; XML is the opt-in
+ * alternative — and it only needs to invert the company-data payloads (dicts of
+ * lists of dicts of scalars).
+ */
+export declare class XmlParseError extends Error {
+}
+type XmlValue = string | XmlValue[] | {
+    [key: string]: XmlValue;
+};
+/**
+ * Parse the platform's XML serialization back into JS data (XXE-safe).
+ *
+ * Mirrors the platform serializer (see the module doc). Returns the document root
+ * element's value (a `<response>` element → an object). Throws {@link XmlParseError}
+ * on malformed XML, a DOCTYPE/DTD, a processing instruction, or any non-builtin
+ * entity reference.
+ */
+export declare function parseXml(text: string): XmlValue;
+export {};

package/docs/config.md

@@ -0,0 +1,93 @@
+# Config reference
+
+`Config` (`import { Config } from '@allus/company-data'`).
+
+A single JSON file holds the whole SDK configuration. **Config-only key handling is
+a hard rule:** no SDK method ever takes a key, passphrase, or secret as an argument
+— everything cryptographic (decrypting the service PEM, decrypting field values,
+verifying the webhook HMAC, unwrapping the account-key envelope) is driven entirely
+by this config. Your only key responsibility is putting the right values here.
+
+The config-file keys are **snake_case**; the SDK exposes them as **camelCase**
+properties.
+
+## Fields
+
+| File key | Property | Type | Required | Default | Meaning |
+|----------|----------|------|----------|---------|---------|
+| `api_url` | `apiUrl` | string | yes | — | API base, e.g. `https://api.allme.fyi`. |
+| `client_id` | `clientId` | string | yes | — | The `client_credentials` client id (scoped to one service). |
+| `client_secret` | `clientSecret` | string | yes | — | The client secret. |
+| `service_private_key` | `servicePrivateKey` | string | yes | — | Path to the OpenSSL-encrypted PKCS#8 PEM (downloaded from the portal). |
+| `key_passphrase` | `keyPassphrase` | string | yes | — | Decrypts the service PEM in memory at startup. |
+| `account_private_key` | `accountPrivateKey` | string \| null | no | `null` | Path to the company **account** key PEM — only needed to receive `encrypt_payload` webhooks. |
+| `account_passphrase` | `accountPassphrase` | string \| null | no | `null` | Decrypts the account PEM. |
+| `webhooks` | `webhooks` | object | no | `{}` | Per-webhook HMAC secrets, keyed by webhook id (matched via the `X-Allus-Webhook-Id` header). |
+| `cache_dir` | `cacheDir` | string | no | `"./allus-cache"` | Durable local buffer dir for the changes pump. Must be writable + durable. |
+| `format` | `format` | `"json"` \| `"xml"` | no | `"json"` | Wire format. Invisible in the output. |
+
+The PEM is PBES2 (PBKDF2-HMAC-SHA256 + AES-256-CBC, 100k iters); it is decrypted in
+memory at construction (`crypto.createPrivateKey({ key, passphrase })`) and never
+written back to disk in plaintext.
+
+## Constructors
+
+```ts
+Config.fromFile(path: string): Config     // load JSON; ALLUS_* env vars override file values
+Config.fromEnv():              Config      // build entirely from ALLUS_* env vars
+```
+
+In practice you build the client directly:
+
+```ts
+import { Client } from '@allus/company-data';
+const client = Client.fromConfig('allus.json');   // == new Client(Config.fromFile('allus.json'))
+const client2 = Client.fromEnv();                  // == new Client(Config.fromEnv())
+```
+
+## Env overrides
+
+Every scalar field can be overridden by its `ALLUS_*` env var (so secrets needn't
+live in the file). An env value, when set, wins over the file value.
+
+| Property | Env var |
+|----------|---------|
+| `apiUrl` | `ALLUS_API_URL` |
+| `clientId` | `ALLUS_CLIENT_ID` |
+| `clientSecret` | `ALLUS_CLIENT_SECRET` |
+| `servicePrivateKey` | `ALLUS_SERVICE_PRIVATE_KEY` |
+| `keyPassphrase` | `ALLUS_KEY_PASSPHRASE` |
+| `accountPrivateKey` | `ALLUS_ACCOUNT_PRIVATE_KEY` |
+| `accountPassphrase` | `ALLUS_ACCOUNT_PASSPHRASE` |
+| `cacheDir` | `ALLUS_CACHE_DIR` |
+| `format` | `ALLUS_FORMAT` |
+| flat single-webhook secret | `ALLUS_WEBHOOK_SECRET` |
+
+## Webhook secrets
+
+```json
+"webhooks": { "wh_abc123": "secret_a", "wh_def456": "secret_b" }
+```
+
+Keyed by webhook id; the SDK reads `X-Allus-Webhook-Id` off the incoming request
+and looks up the matching secret. A service with a single webhook can use the flat
+shortcut instead of the map:
+
+```json
+"webhook_secret": "the_one_secret"
+```
+
+(stored internally under a reserved key `Config.SINGLE_WEBHOOK_KEY` and used as the
+fallback when there is no id-specific match). `ALLUS_WEBHOOK_SECRET` overrides the
+flat shortcut.
+
+`config.webhookSecret(webhookId?)` resolves the secret for an id (falling back to
+the single-webhook shortcut). The webhook helpers call this for you — you never
+pass a secret in. **The method takes a webhook *id*, never a secret.**
+
+## Validation
+
+* A missing required field (`api_url`, `client_id`, `client_secret`, `service_private_key`, `key_passphrase`) throws `ConfigError` listing the missing **config-file keys**.
+* A `format` other than `json`/`xml` throws `ConfigError`.
+* A malformed/missing config file throws `ConfigError`.
+* An unreadable `service_private_key` PEM, or a wrong `key_passphrase`, throws `ConfigError` at `Client` construction (fail fast — a bad key is a config problem, not a runtime decrypt error).

package/docs/errors.md

@@ -0,0 +1,87 @@
+# Error model
+
+Same taxonomy + names across all six SDKs. All importable from
+`@allus/company-data`. Every error extends a common `AllusError` base.
+
+```ts
+import {
+  AllusError, ConfigError, AuthError, ApiError, DecryptError, WebhookError, RateLimitError,
+} from '@allus/company-data';
+```
+
+| Error | Thrown when |
+|-------|-------------|
+| `ConfigError` | Missing/invalid config, an unreadable key file, or a wrong passphrase — at construction (fail fast). |
+| `AuthError` | The `client_credentials` token fetch/refresh failed (bad `client_id`/`secret`, revoked client); or a mid-flight 401 survived the one automatic refresh-and-retry. |
+| `ApiError` | Any non-2xx from the API. |
+| `DecryptError` | A ciphertext wrapper is malformed, the key is wrong, or the GCM tag mismatches. |
+| `WebhookError` | Signature verification failed, or a webhook envelope couldn't be unwrapped/parsed. |
+| `RateLimitError` | A 429 from a rate-limited endpoint. Subclass of `ApiError`. |
+
+## `AllusError`
+
+The base class. `catch (e) { if (e instanceof AllusError) … }` captures the whole
+taxonomy. `instanceof` works correctly across the transpile target (the prototype
+chain is restored in the constructor).
+
+## `ApiError`
+
+```ts
+class ApiError extends AllusError {
+  status: number;             // the HTTP status
+  errorKey: string | null;    // the platform error_key, when the body provided one
+  apiMessage: string | null;  // a human-readable message
+}
+```
+
+`err.message` is formatted as `"HTTP <status> (<errorKey>): <apiMessage>"`. A
+transport failure (no HTTP response — e.g. a connection error) surfaces as
+`new ApiError(0, null, …)`.
+
+## `RateLimitError`
+
+```ts
+class RateLimitError extends ApiError {   // status is always 429
+  retryAfter: number | null;              // seconds from the Retry-After header, or null
+}
+```
+
+The SDK already retries a 429 with backoff before surfacing this:
+
+* the transport (`HttpClient`) retries a bounded number of times honoring `Retry-After`;
+* the `connections(...)` generator additionally backs off + retries a page a bounded number of times.
+
+For the heavily-limited connections endpoints it surfaces after that backoff so you
+don't accidentally hammer them; on the changes feed it auto-backs-off within reason.
+If you catch it, wait `err.retryAfter` (or a default) before retrying.
+
+## Where each surfaces
+
+| Layer | Common errors |
+|-------|---------------|
+| `Client.fromConfig` / `fromEnv` | `ConfigError` |
+| Token / any call (auth) | `AuthError` |
+| `connections`, `connection`, `requestFields`, `logs`, pump drains | `ApiError`, `RateLimitError` |
+| Value access / `BinaryHandle.bytes()` / pump delivery | `DecryptError` |
+| `verifyWebhook` / `parseWebhook` / `handleWebhook` | `WebhookError` (`verifyWebhook` returns `false` rather than throwing on a bad signature) |
+
+## Example
+
+```ts
+import {
+  Client, ConfigError, AuthError, ApiError,
+  DecryptError, WebhookError, RateLimitError,
+} from '@allus/company-data';
+
+try {
+  const client = Client.fromConfig('allus.json');
+  for await (const conn of client.connections()) process(conn);
+} catch (e) {
+  if (e instanceof ConfigError) { /* fix the config / key file */ }
+  else if (e instanceof AuthError) { /* bad/revoked credentials */ }
+  else if (e instanceof RateLimitError) { await sleep((e.retryAfter ?? 60) * 1000); }
+  else if (e instanceof DecryptError) { /* wrong service key or corrupt data */ }
+  else if (e instanceof ApiError) { log(e.status, e.errorKey, e.apiMessage); }
+  else throw e;
+}
+```