@allus-fyi/company-data 0.0.3

package/dist/cjs/index.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * allus company-data SDK for TypeScript / Node — one of six language ports that
+ * share an identical API surface.
+ *
+ * This package wraps the allus company-data API: point it at a JSON config file and
+ * it hands back typed, plaintext, your-slug-keyed conclusions with transparent
+ * hybrid decryption.
+ *
+ * Exported: config loading, the decryption core, the full error taxonomy, the
+ * HTTP/auth layer, the output model, the crash-safe changes pump (durable file
+ * buffer + pump), the `Client` facade, and the webhook receiver helpers. `Client`
+ * is the one object an integrating company touches.
+ *
+ * Both ESM (`import { Client } from '@allus/company-data'`) and CommonJS
+ * (`const { Client } = require('@allus/company-data')`) are supported via the
+ * package's `exports` map.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.XmlParseError = exports.parseXml = exports.loadAccountKey = exports.handleWebhook = exports.parseWebhook = exports.verifyWebhook = exports.MAX_BATCH = exports.Pump = exports.FileBuffer = exports.DATE_TYPES = exports.BINARY_TYPES = exports.STRUCTURED_TYPES = exports.LogEntry = exports.Change = exports.Value = exports.Connection = exports.RequestField = exports.FetchTransport = exports.HttpClient = exports.RateLimitError = exports.WebhookError = exports.DecryptError = exports.ApiError = exports.AuthError = exports.ConfigError = exports.AllusError = exports.GCM_TAG_LEN = exports.GCM_IV_LEN = exports.BinaryHandle = exports.decrypt = exports.loadPrivateKey = exports.SINGLE_WEBHOOK_KEY = exports.Config = exports.Client = void 0;
+// client facade — the main entry point
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
+// config
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return config_js_1.Config; } });
+Object.defineProperty(exports, "SINGLE_WEBHOOK_KEY", { enumerable: true, get: function () { return config_js_1.SINGLE_WEBHOOK_KEY; } });
+// crypto
+var crypto_js_1 = require("./crypto.js");
+Object.defineProperty(exports, "loadPrivateKey", { enumerable: true, get: function () { return crypto_js_1.loadPrivateKey; } });
+Object.defineProperty(exports, "decrypt", { enumerable: true, get: function () { return crypto_js_1.decrypt; } });
+Object.defineProperty(exports, "BinaryHandle", { enumerable: true, get: function () { return crypto_js_1.BinaryHandle; } });
+Object.defineProperty(exports, "GCM_IV_LEN", { enumerable: true, get: function () { return crypto_js_1.GCM_IV_LEN; } });
+Object.defineProperty(exports, "GCM_TAG_LEN", { enumerable: true, get: function () { return crypto_js_1.GCM_TAG_LEN; } });
+// errors
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "AllusError", { enumerable: true, get: function () { return errors_js_1.AllusError; } });
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return errors_js_1.ConfigError; } });
+Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_js_1.AuthError; } });
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return errors_js_1.ApiError; } });
+Object.defineProperty(exports, "DecryptError", { enumerable: true, get: function () { return errors_js_1.DecryptError; } });
+Object.defineProperty(exports, "WebhookError", { enumerable: true, get: function () { return errors_js_1.WebhookError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });
+// transport
+var http_js_1 = require("./http.js");
+Object.defineProperty(exports, "HttpClient", { enumerable: true, get: function () { return http_js_1.HttpClient; } });
+Object.defineProperty(exports, "FetchTransport", { enumerable: true, get: function () { return http_js_1.FetchTransport; } });
+// output model
+var models_js_1 = require("./models.js");
+Object.defineProperty(exports, "RequestField", { enumerable: true, get: function () { return models_js_1.RequestField; } });
+Object.defineProperty(exports, "Connection", { enumerable: true, get: function () { return models_js_1.Connection; } });
+Object.defineProperty(exports, "Value", { enumerable: true, get: function () { return models_js_1.Value; } });
+Object.defineProperty(exports, "Change", { enumerable: true, get: function () { return models_js_1.Change; } });
+Object.defineProperty(exports, "LogEntry", { enumerable: true, get: function () { return models_js_1.LogEntry; } });
+Object.defineProperty(exports, "STRUCTURED_TYPES", { enumerable: true, get: function () { return models_js_1.STRUCTURED_TYPES; } });
+Object.defineProperty(exports, "BINARY_TYPES", { enumerable: true, get: function () { return models_js_1.BINARY_TYPES; } });
+Object.defineProperty(exports, "DATE_TYPES", { enumerable: true, get: function () { return models_js_1.DATE_TYPES; } });
+// changes pump
+var buffer_js_1 = require("./buffer.js");
+Object.defineProperty(exports, "FileBuffer", { enumerable: true, get: function () { return buffer_js_1.FileBuffer; } });
+var pump_js_1 = require("./pump.js");
+Object.defineProperty(exports, "Pump", { enumerable: true, get: function () { return pump_js_1.Pump; } });
+Object.defineProperty(exports, "MAX_BATCH", { enumerable: true, get: function () { return pump_js_1.MAX_BATCH; } });
+// webhook receiver helpers
+var webhooks_js_1 = require("./webhooks.js");
+Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhooks_js_1.verifyWebhook; } });
+Object.defineProperty(exports, "parseWebhook", { enumerable: true, get: function () { return webhooks_js_1.parseWebhook; } });
+Object.defineProperty(exports, "handleWebhook", { enumerable: true, get: function () { return webhooks_js_1.handleWebhook; } });
+Object.defineProperty(exports, "loadAccountKey", { enumerable: true, get: function () { return webhooks_js_1.loadAccountKey; } });
+// XML (XXE-safe parser — exported for advanced use / testing)
+var xml_js_1 = require("./xml.js");
+Object.defineProperty(exports, "parseXml", { enumerable: true, get: function () { return xml_js_1.parseXml; } });
+Object.defineProperty(exports, "XmlParseError", { enumerable: true, get: function () { return xml_js_1.XmlParseError; } });
+exports.VERSION = '0.1.0';

package/dist/cjs/models.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogEntry = exports.Change = exports.Connection = exports.Value = exports.RequestField = exports.DATE_TYPES = exports.BINARY_TYPES = exports.STRUCTURED_TYPES = void 0;
+const crypto_js_1 = require("./crypto.js");
+/** Field types whose decrypted plaintext is a JSON object → a parsed object. */
+exports.STRUCTURED_TYPES = ['address', 'bank', 'creditcard'];
+/** Field types whose value is a lazy binary handle (served as a value_url). */
+exports.BINARY_TYPES = ['photo', 'document', 'legal_document'];
+/** Field types whose decrypted plaintext is an ISO date. */
+exports.DATE_TYPES = ['date', 'date_of_birth'];
+function parseIsoDate(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const raw = String(value);
+    const ms = Date.parse(raw);
+    if (Number.isNaN(ms))
+        return null;
+    return new Date(ms);
+}
+function coerceBool(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const low = value.trim().toLowerCase();
+        if (low === 'true' || low === '1')
+            return true;
+        if (low === 'false' || low === '0' || low === '')
+            return false;
+    }
+    return Boolean(value);
+}
+function parseDateOnly(value) {
+    const head = value.trim().slice(0, 10);
+    // Strict YYYY-MM-DD; build a UTC date so there's no timezone drift.
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(head);
+    if (!m)
+        return null;
+    const year = Number(m[1]);
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    const d = new Date(Date.UTC(year, month - 1, day));
+    // Round-trip guard (rejects e.g. 1990-13-40).
+    if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day) {
+        return null;
+    }
+    return d;
+}
+// ── definitions ──────────────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+class RequestField {
+    constructor(slug, label, type, oneTime, mandatory, raw) {
+        this.slug = slug;
+        this.label = label;
+        this.type = type;
+        this.oneTime = oneTime;
+        this.mandatory = mandatory;
+        this.raw = raw;
+    }
+    static fromApi(obj) {
+        return new RequestField(String(obj['slug'] ?? ''), obj['label'] != null ? String(obj['label']) : '', obj['type'] != null ? String(obj['type']) : '', Boolean(coerceBool(obj['one_time'])), Boolean(coerceBool(obj['mandatory_provide']) || coerceBool(obj['mandatory_connected'])), obj);
+    }
+    /** Parse the `/request-fields` response → a list of definitions. */
+    static listFromApi(body) {
+        const items = listOf(body, 'request_fields');
+        return items.map((o) => RequestField.fromApi(o));
+    }
+}
+exports.RequestField = RequestField;
+// ── values ───────────────────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+class Value {
+    constructor(value, live, updatedAt, raw) {
+        this.value = value;
+        this.live = live;
+        this.updatedAt = updatedAt;
+        this.raw = raw;
+    }
+    /** Build a typed Value from one hardened `{value|value_url, live, updatedAt}` entry. */
+    static fromApi(obj, opts) {
+        const live = Boolean(coerceBool(obj['live']));
+        const updatedAt = parseIsoDate(obj['updatedAt'] ?? obj['updated_at']);
+        const typed = typedValue(obj, opts);
+        return new Value(typed, live, updatedAt, obj);
+    }
+}
+exports.Value = Value;
+function typedValue(obj, opts) {
+    const ftype = (opts.fieldType ?? '').toLowerCase();
+    // Binary → a lazy handle over the slot value_url (no eager fetch/decrypt).
+    if (exports.BINARY_TYPES.includes(ftype) || 'value_url' in obj) {
+        const valueUrl = obj['value_url'];
+        if (valueUrl === undefined || valueUrl === null) {
+            // Binary type but no url (e.g. unanswered) → an empty handle.
+            return new crypto_js_1.BinaryHandle({});
+        }
+        return new crypto_js_1.BinaryHandle({
+            valueUrl: String(valueUrl),
+            fetch: opts.binaryFetch ?? null,
+            decrypt: opts.decryptValue,
+        });
+    }
+    // Non-binary → decrypt the ciphertext wrapper to plaintext.
+    const ciphertext = obj['value'];
+    if (ciphertext === undefined || ciphertext === null) {
+        return null;
+    }
+    const plaintext = opts.decryptValue(ciphertext);
+    if (exports.STRUCTURED_TYPES.includes(ftype)) {
+        try {
+            return JSON.parse(plaintext);
+        }
+        catch {
+            throw new crypto_js_1.DecryptError(`structured value for type '${ftype}' is not valid JSON`);
+        }
+    }
+    if (exports.DATE_TYPES.includes(ftype)) {
+        const d = parseDateOnly(plaintext);
+        return d !== null ? d : plaintext;
+    }
+    // text/email/phone/url and anything unknown → the plaintext string.
+    return plaintext;
+}
+// ── connection ─────────────────────────────────────────────────────────────
+/**
+ * A connected person — identity + the slug-keyed value map.
+ *
+ * NO source field anywhere: `values` is keyed by YOUR request slug.
+ */
+class Connection {
+    constructor(id, personId, displayName, connectedAt, values, raw) {
+        this.id = id;
+        this.personId = personId;
+        this.displayName = displayName;
+        this.connectedAt = connectedAt;
+        this.values = values;
+        this.raw = raw;
+    }
+    /**
+     * 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, opts) {
+        const identity = opts.identity ?? {};
+        const connId = String(obj['connection_id'] ?? obj['id'] ?? identity['connection_id'] ?? '');
+        const personId = String(obj['user_id'] ?? obj['person_id'] ?? obj['person_user_id'] ?? identity['user_id'] ?? '');
+        const displayNameRaw = obj['display_name'] ?? identity['display_name'];
+        const displayName = displayNameRaw != null ? String(displayNameRaw) : null;
+        const connectedAt = parseIsoDate(obj['connected_at'] ?? identity['connected_at']);
+        const values = {};
+        const valuesObj = obj['values'];
+        if (valuesObj !== null && typeof valuesObj === 'object' && !Array.isArray(valuesObj)) {
+            for (const [slug, entry] of Object.entries(valuesObj)) {
+                if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+                    continue;
+                values[slug] = Value.fromApi(entry, {
+                    fieldType: opts.typeForSlug(slug),
+                    decryptValue: opts.decryptValue,
+                    binaryFetch: opts.binaryFetch,
+                });
+            }
+        }
+        return new Connection(connId, personId, displayName, connectedAt, values, obj);
+    }
+}
+exports.Connection = Connection;
+// ── change ───────────────────────────────────────────────────────────────────
+/**
+ * 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).
+ */
+class Change {
+    constructor(id, event, personId, 
+    /** The person's profile share code (present on every event; may be null). */
+    shareCode, slug, value, live, at, raw) {
+        this.id = id;
+        this.event = event;
+        this.personId = personId;
+        this.shareCode = shareCode;
+        this.slug = slug;
+        this.value = value;
+        this.live = live;
+        this.at = at;
+        this.raw = raw;
+    }
+    /** Build a Change from one hardened changes-feed / webhook event object. */
+    static fromApi(obj, opts) {
+        const slug = obj['slug'] != null ? String(obj['slug']) : null;
+        const event = obj['event'] != null ? String(obj['event']) : '';
+        const live = 'live' in obj ? coerceBool(obj['live']) : null;
+        let value = null;
+        if (event === 'field_updated' && slug !== null) {
+            // Reuse the Value typing path so feed + connection produce identical typed
+            // values (incl. the same lazy BinaryHandle for binaries).
+            if ('value' in obj || 'value_url' in obj) {
+                value = typedValue(obj, {
+                    fieldType: opts.typeForSlug(slug),
+                    decryptValue: opts.decryptValue,
+                    binaryFetch: opts.binaryFetch,
+                });
+            }
+        }
+        const personIdRaw = obj['person_user_id'] ?? obj['person_id'];
+        const shareCodeRaw = obj['share_code'];
+        return new Change(String(obj['id'] ?? ''), event, personIdRaw != null ? String(personIdRaw) : null, shareCodeRaw != null ? String(shareCodeRaw) : null, slug, value, live, parseIsoDate(obj['at']), obj);
+    }
+    /** Parse the `/changes` response → a list of typed Change events. */
+    static listFromApi(body, opts) {
+        const items = listOf(body, 'changes');
+        return items.map((o) => Change.fromApi(o, opts));
+    }
+}
+exports.Change = Change;
+// ── log ────────────────────────────────────────────────────────────────────
+/** A service activity-log entry — ops events only, never person data. */
+class LogEntry {
+    constructor(type, message, metadata, at, raw) {
+        this.type = type;
+        this.message = message;
+        this.metadata = metadata;
+        this.at = at;
+        this.raw = raw;
+    }
+    static fromApi(obj) {
+        return new LogEntry(obj['type'] != null ? String(obj['type']) : '', obj['message'] != null ? String(obj['message']) : null, obj['metadata'] ?? null, parseIsoDate(obj['at'] ?? obj['created_at']), obj);
+    }
+    /** Parse the `/logs` response → a list of log entries. */
+    static listFromApi(body) {
+        const items = listOf(body, 'items');
+        return items.map((o) => LogEntry.fromApi(o));
+    }
+}
+exports.LogEntry = LogEntry;
+// ── shared list extraction ───────────────────────────────────────────────────
+/**
+ * Pull the named array out of a `{<key>: [...]}` response, or accept a bare array.
+ * Mirrors the Python `body.get(key, []) if dict else (body or [])`.
+ */
+function listOf(body, key) {
+    let items;
+    if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+        items = body[key] ?? [];
+    }
+    else {
+        items = body ?? [];
+    }
+    if (!Array.isArray(items))
+        return [];
+    return items.filter((o) => o !== null && typeof o === 'object' && !Array.isArray(o));
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/pump.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pump = exports.MAX_BATCH = void 0;
+const buffer_js_1 = require("./buffer.js");
+const errors_js_1 = require("./errors.js");
+// The drain-on-fetch queue caps a fetch at 500. The pump clamps any requested
+// batch size to this.
+exports.MAX_BATCH = 500;
+const DEFAULT_BATCH = 100;
+// Default retry/backoff for a failing handler.
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BACKOFF_S = 0.5;
+const MAX_BACKOFF_S = 30.0;
+const defaultSleep = (seconds) => new Promise((res) => setTimeout(res, Math.max(0, seconds) * 1000));
+function defaultBackoff(attempt) {
+    return Math.min(DEFAULT_BACKOFF_S * 2 ** (attempt - 1), MAX_BACKOFF_S);
+}
+function clampBatch(value) {
+    let v = Math.trunc(Number(value));
+    if (!Number.isFinite(v))
+        v = DEFAULT_BATCH;
+    if (v < 1)
+        v = 1;
+    if (v > exports.MAX_BATCH)
+        v = exports.MAX_BATCH;
+    return v;
+}
+/**
+ * The crash-safe changes pump.
+ *
+ * Wires a durable {@link FileBuffer} (under `config.cacheDir`) to an injected drain
+ * source + decrypt callable.
+ */
+class Pump {
+    constructor(config, opts) {
+        this.fetchChanges = opts.fetchChanges;
+        this.decryptChange = opts.decrypt;
+        this.log = opts.logger ?? {};
+        this.sleep = opts.sleep ?? defaultSleep;
+        // The buffer recovers whatever is already on disk — that recovery IS the
+        // replay-on-restart in step 1.
+        this._buffer = new buffer_js_1.FileBuffer(config.cacheDir);
+    }
+    get buffer() {
+        return this._buffer;
+    }
+    // ── the pump ──────────────────────────────────────────────────────────────
+    /**
+     * 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).
+     */
+    async processChanges(handler, options = {}) {
+        const onError = options.onError ?? 'deadletter';
+        if (onError !== 'deadletter' && onError !== 'halt') {
+            throw new TypeError("onError must be 'deadletter' or 'halt'");
+        }
+        const size = clampBatch(options.batchSize ?? DEFAULT_BATCH);
+        const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        const backoff = options.backoff ?? defaultBackoff;
+        for (;;) {
+            // 1. Replay anything already buffered (a previous crashed run), then deliver
+            //    it. If the buffer is empty, drain ONE batch first.
+            let pending = this._buffer.pending();
+            if (pending.length > 0) {
+                this.log.info?.(`pump replay: ${pending.length} buffered event(s)`);
+            }
+            else {
+                const drained = await this.drainIntoBuffer(size);
+                if (drained === 0) {
+                    // A drain returned empty AND the buffer is drained → done.
+                    return;
+                }
+                pending = this._buffer.pending();
+            }
+            // 3+4. Deliver each buffered event oldest-first; ack/retry/dead-letter.
+            for (const event of pending) {
+                await this.deliverOne(event, handler, { maxRetries, onError, backoff });
+            }
+            // Loop: re-check the buffer (now drained) and try another drain.
+        }
+    }
+    async drainIntoBuffer(size) {
+        const batch = (await this.fetchChanges(size)) || [];
+        this.log.info?.(`pump drain: fetched ${batch.length} event(s) (limit=${size})`);
+        if (batch.length === 0) {
+            return 0;
+        }
+        // Persist-before-deliver: the durable backup the API no longer has.
+        this._buffer.append(batch);
+        return batch.length;
+    }
+    async deliverOne(event, handler, opts) {
+        const changeId = event['id'];
+        let attempts = 0;
+        for (;;) {
+            attempts += 1;
+            try {
+                // Decrypt only now — never on disk (ciphertext at rest).
+                // Inside the try so a poison-ciphertext DecryptError is contained.
+                const change = this.decryptChange(event);
+                this.log.debug?.(`pump deliver: id=${String(changeId)} attempt=${attempts}`);
+                await handler(change);
+            }
+            catch (exc) {
+                if (exc instanceof errors_js_1.DecryptError) {
+                    // A poison event: re-decrypting won't help, so don't burn retries.
+                    if (opts.onError === 'halt') {
+                        this.log.error?.(`pump halt: id=${String(changeId)} undecryptable (${exc.message})`);
+                        throw exc;
+                    }
+                    this._buffer.deadLetter(changeId, `DecryptError: ${exc.message}`, attempts);
+                    this.log.error?.(`pump dead-letter (undecryptable): id=${String(changeId)}: ${exc.message}`);
+                    return;
+                }
+                // A handler error.
+                const err = exc;
+                if (attempts <= opts.maxRetries) {
+                    const delay = Math.max(0, opts.backoff(attempts));
+                    this.log.warn?.(`pump retry: id=${String(changeId)} attempt=${attempts} failed (${err.message}); backoff ${delay}s`);
+                    if (delay)
+                        await this.sleep(delay);
+                    continue;
+                }
+                // Retries exhausted.
+                if (opts.onError === 'halt') {
+                    this.log.error?.(`pump halt: id=${String(changeId)} failed after ${attempts} attempt(s)`);
+                    throw err;
+                }
+                this._buffer.deadLetter(changeId, String(err.message ?? err), attempts);
+                this.log.error?.(`pump dead-letter: id=${String(changeId)} after ${attempts} attempt(s): ${err.message}`);
+                return;
+            }
+            // Success → per-item ack (remove from the buffer).
+            this._buffer.ack(changeId);
+            this.log.debug?.(`pump ack: id=${String(changeId)}`);
+            return;
+        }
+    }
+    // ── advanced primitive ─────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async drainBatch(max = DEFAULT_BATCH) {
+        const size = clampBatch(max);
+        const batch = (await this.fetchChanges(size)) || [];
+        this.log.info?.(`drainBatch: fetched ${batch.length} event(s) (limit=${size})`);
+        return batch.map((event) => this.decryptChange(event));
+    }
+    // ── dead-letter inspect / re-drive ─────────────────────────────────────────
+    /** The local dead-letter store (ciphertext + error + attempt count). */
+    deadLetters() {
+        return this._buffer.deadLetters();
+    }
+    /**
+     * 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.
+     */
+    async retryDeadLetters(handler, options = {}) {
+        const onError = options.onError ?? 'deadletter';
+        if (onError !== 'deadletter' && onError !== 'halt') {
+            throw new TypeError("onError must be 'deadletter' or 'halt'");
+        }
+        const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        const backoff = options.backoff ?? defaultBackoff;
+        let redriven = 0;
+        for (const record of this._buffer.deadLetters()) {
+            const changeId = record['id'];
+            // Strip the reserved failure block before re-decrypting the event.
+            const event = {};
+            for (const [k, v] of Object.entries(record)) {
+                if (k === '_deadletter' || k === 'error' || k === 'attempts')
+                    continue;
+                event[k] = v;
+            }
+            let attempts = 0;
+            for (;;) {
+                attempts += 1;
+                try {
+                    // Decrypt inside the loop so an undecryptable dead-letter (the poison
+                    // case) is contained here too — it updates its own record in place
+                    // instead of crashing the re-drive.
+                    const change = this.decryptChange(event);
+                    await handler(change);
+                }
+                catch (exc) {
+                    if (exc instanceof errors_js_1.DecryptError) {
+                        if (onError === 'halt') {
+                            this.log.error?.(`retryDeadLetters halt: id=${String(changeId)} undecryptable (${exc.message})`);
+                            throw exc;
+                        }
+                        this._buffer.updateDeadLetter(changeId, `DecryptError: ${exc.message}`, attempts);
+                        this.log.warn?.(`retryDeadLetters: id=${String(changeId)} still undecryptable (${exc.message})`);
+                        break;
+                    }
+                    const err = exc;
+                    if (attempts <= maxRetries) {
+                        const delay = Math.max(0, backoff(attempts));
+                        if (delay)
+                            await this.sleep(delay);
+                        continue;
+                    }
+                    if (onError === 'halt') {
+                        this.log.error?.(`retryDeadLetters halt: id=${String(changeId)} failed again`);
+                        throw err;
+                    }
+                    // Refresh the stored attempt count + error IN PLACE — the record stays in
+                    // deadletter/ and never re-enters pending/, so there is no crash window
+                    // (between an append and a re-dead-letter) where it could resurrect as a
+                    // live pending event.
+                    this._buffer.updateDeadLetter(changeId, String(err.message ?? err), attempts);
+                    this.log.warn?.(`retryDeadLetters: id=${String(changeId)} still failing (${err.message})`);
+                    break;
+                }
+                // Success.
+                this._buffer.removeDeadLetter(changeId);
+                this.log.info?.(`retryDeadLetters: id=${String(changeId)} re-driven OK`);
+                redriven += 1;
+                break;
+            }
+        }
+        return redriven;
+    }
+}
+exports.Pump = Pump;