@allus-fyi/company-data 0.0.3

package/dist/esm/client.js

@@ -0,0 +1,392 @@
+/**
+ * Client facade.
+ *
+ * The one object an integrating company touches. Build it from config (the keys
+ * live there and nowhere else), then call:
+ *
+ *     client.requestFields()              -> Promise<RequestField[]>  (slug -> meta, cached)
+ *     client.connections(limit, offset)   -> AsyncIterable<Connection> (auto-paged, lazy)
+ *     client.connection(id)               -> Promise<Connection>
+ *     client.logs(limit, offset)          -> Promise<LogEntry[]>
+ *     client.processChanges(handler, opts) -> Promise<void>  (the crash-safe pump)
+ *     client.drainBatch(max)              -> Promise<Change[]>  (raw unbuffered drain — advanced)
+ *     client.deadLetters() / client.retryDeadLetters(handler)
+ *
+ * Plus the webhook receiver helpers, exposed as methods that delegate to the
+ * `webhooks` module (all config-driven, no key/secret args):
+ *
+ *     client.verifyWebhook(rawBody, headers) -> bool
+ *     client.parseWebhook(rawBody, headers)  -> Change
+ *     client.handleWebhook(rawBody, headers) -> Change
+ *
+ * How it is wired (everything else the SDK hides):
+ *   - **Auth + transport** — an {@link HttpClient} owns the `client_credentials`
+ *     token, the JSON/XML accept+parse, and the error mapping (incl. 429 backoff).
+ *   - **Decryption** — the service private key is loaded **once** at construction
+ *     from the configured encrypted PEM + passphrase into an in-memory key; a
+ *     `decryptValue` closure over it is handed to every model factory and the pump
+ *     (config-only key handling — the key never appears in a method signature).
+ *   - **Slug catalog** — `requestFields()` is fetched once and cached; its slug→type
+ *     map types every value (so `address` parses to an object, `photo` becomes a
+ *     lazy binary handle, etc.).
+ *   - **Binary** — a value's `BinaryHandle.bytes()` GETs the slot file endpoint,
+ *     unwraps the API's `{"encrypted":true,"value":<wrapper>}` envelope, and runs
+ *     the same service-key decrypt → the file bytes.
+ *   - **Changes feed** — `processChanges` delegates to the {@link Pump}, injecting a
+ *     `fetchChanges` closure (`GET /changes?limit=`, returning the raw ciphertext
+ *     events) and a `decrypt` closure that builds a typed {@link Change}.
+ */
+import { readFileSync } from 'node:fs';
+import { Config } from './config.js';
+import { decrypt as cryptoDecrypt, loadPrivateKey } from './crypto.js';
+import { ConfigError, DecryptError, RateLimitError } from './errors.js';
+import { HttpClient } from './http.js';
+import { Change, Connection, LogEntry, RequestField } from './models.js';
+import { Pump } from './pump.js';
+import { handleWebhook, loadAccountKey, parseWebhook, verifyWebhook } from './webhooks.js';
+// Endpoint paths (the API base comes from Config; HttpClient joins them).
+const BASE = '/api/company-data';
+const CONNECTIONS = `${BASE}/connections`;
+const CHANGES = `${BASE}/changes`;
+const REQUEST_FIELDS = `${BASE}/request-fields`;
+const LOGS = `${BASE}/logs`;
+// Default page size for the connections iterator. The endpoint is heavily
+// rate-limited, so we keep pages reasonably large to minimize the
+// number of requests for a full sync, while the iterator stays lazy.
+const DEFAULT_CONN_PAGE = 100;
+// Bounded extra backoff for the connections iterator on a surfaced 429. The
+// HttpClient already retries a 429 internally; if it still surfaces a
+// RateLimitError we honor Retry-After once more here (the connections endpoints are
+// expensive snapshots, not a poll target) before re-throwing.
+const CONN_MAX_429_BACKOFFS = 5;
+const CONN_DEFAULT_BACKOFF_S = 5.0;
+const CONN_MAX_BACKOFF_S = 120.0;
+const defaultSleep = (seconds) => new Promise((res) => setTimeout(res, Math.max(0, seconds) * 1000));
+/** The company-data SDK client facade. */
+export class Client {
+    constructor(config, opts = {}) {
+        // The slug catalog, fetched once on first requestFields() and cached.
+        this.cachedRequestFields = null;
+        this.typeBySlug = new Map();
+        this.requestFieldsInFlight = null;
+        this._pump = null;
+        // ── decryption wiring (closures over the loaded key — never a method arg) ──
+        this.decryptValue = (wrapper) => cryptoDecrypt(wrapper, this.privateKey);
+        /**
+         * Fetch a slot file endpoint and unwrap its `{"encrypted":true,"value":...}` envelope.
+         *
+         * Returns the inner `{"_enc":1,...}` wrapper, which the {@link BinaryHandle} then
+         * decrypts with the same service key.
+         */
+        this.binaryFetch = async (valueUrl) => {
+            const body = await this.http.get(valueUrl);
+            if (body !== null && typeof body === 'object' && !Array.isArray(body) && 'value' in body) {
+                return body['value'];
+            }
+            // Defensive: some shapes might return the wrapper directly.
+            return body;
+        };
+        /** Resolve a request slug to its field type (loads the catalog once). */
+        this.typeForSlug = (slug) => {
+            return this.typeBySlug.get(slug) ?? null;
+        };
+        this.config = config;
+        this.log = opts.logger ?? {};
+        this.sleep = opts.sleep ?? defaultSleep;
+        // Transport (auth + JSON/XML + error taxonomy). Injectable for tests.
+        this.http = opts.http ?? new HttpClient(config, opts.httpOptions);
+        // Load the service private key ONCE from the configured encrypted PEM +
+        // passphrase (config-only key handling). This is the single place
+        // the key material is read; a closure over it does every decrypt.
+        this.privateKey = loadServiceKey(config);
+        // Load the ACCOUNT private key ONCE too (null unless configured). Reused for
+        // every encrypt_payload webhook so we don't re-read the PEM + re-run PBKDF2
+        // (~100k iters) per request — same one-time-load discipline as the service key.
+        this.accountKey = loadAccountKey(config);
+    }
+    // ── constructors (config-only keys) ────────────────────────────────────────
+    /** Build from a JSON config file (env vars override secrets). */
+    static fromConfig(path, opts = {}) {
+        return new Client(Config.fromFile(path), opts);
+    }
+    /** Build entirely from `ALLUS_*` env vars. */
+    static fromEnv(opts = {}) {
+        return new Client(Config.fromEnv(), opts);
+    }
+    // ── definitions ────────────────────────────────────────────────────────────
+    /**
+     * The cached request-field DEFINITIONS.
+     *
+     * Fetched once from `GET /api/company-data/request-fields` and cached for the life
+     * of the client (it's the company's static config, and it types every value).
+     * Returns YOUR request config — never the person's fields. Concurrent callers
+     * share a single in-flight fetch.
+     */
+    async requestFields() {
+        if (this.cachedRequestFields !== null) {
+            return this.cachedRequestFields;
+        }
+        if (this.requestFieldsInFlight === null) {
+            this.requestFieldsInFlight = (async () => {
+                const body = await this.http.get(REQUEST_FIELDS);
+                const fields = RequestField.listFromApi(body);
+                this.cachedRequestFields = fields;
+                this.typeBySlug = new Map(fields.filter((f) => f.slug).map((f) => [f.slug, f.type]));
+                return fields;
+            })();
+            try {
+                return await this.requestFieldsInFlight;
+            }
+            finally {
+                this.requestFieldsInFlight = null;
+            }
+        }
+        return this.requestFieldsInFlight;
+    }
+    // ── connections (heavily rate-limited — initial sync / reconciliation) ─────
+    /**
+     * A lazy async generator paging the list endpoint, yielding one Connection at a time.
+     *
+     * `limit` is the page size; `offset` the starting offset. The generator auto-pages
+     * `GET /api/company-data/connections?limit&offset` and yields typed
+     * {@link Connection} objects (each `values[slug]` already decrypted / a lazy binary
+     * handle) one at a time — bounded memory for a large book. It honors the response's
+     * `total` (when present) so it never over-fetches a page past the end, and also
+     * stops on a short page as a fallback.
+     *
+     * The connections endpoints are **heavily rate-limited**: use this
+     * for the initial full sync + occasional reconciliation, never as a poll substitute
+     * for the changes feed. On a surfaced {@link RateLimitError} the generator backs off
+     * per `Retry-After` and retries the page a bounded number of times before
+     * re-throwing — so it paces itself within the limit rather than hammering.
+     */
+    async *connections(limit = DEFAULT_CONN_PAGE, offset = 0) {
+        const page = Math.max(1, Math.trunc(limit));
+        let cur = Math.max(0, Math.trunc(offset));
+        // Ensure the slug catalog is loaded so values are typed correctly.
+        await this.requestFields();
+        let total = null;
+        for (;;) {
+            const body = await this.getConnectionsPage(page, cur);
+            total = readTotal(body, total);
+            const items = listItems(body);
+            if (items.length === 0) {
+                return;
+            }
+            for (const obj of items) {
+                if (obj === null || typeof obj !== 'object' || Array.isArray(obj))
+                    continue;
+                yield Connection.fromApi(obj, {
+                    typeForSlug: this.typeForSlug,
+                    decryptValue: this.decryptValue,
+                    binaryFetch: this.binaryFetch,
+                    // The list row carries identity (displayName/connectedAt) AND the values
+                    // map, so the same object is both detail + identity.
+                    identity: obj,
+                });
+            }
+            cur += items.length;
+            // Stop when we've consumed `total` rows (honor the API's total so we don't
+            // over-fetch a final empty/short page), or on a short page as a fallback.
+            if (total !== null && cur >= total) {
+                return;
+            }
+            if (items.length < page) {
+                return;
+            }
+        }
+    }
+    async getConnectionsPage(page, offset) {
+        let attempts = 0;
+        for (;;) {
+            try {
+                return await this.http.get(CONNECTIONS, { limit: page, offset });
+            }
+            catch (exc) {
+                if (!(exc instanceof RateLimitError))
+                    throw exc;
+                attempts += 1;
+                if (attempts > CONN_MAX_429_BACKOFFS)
+                    throw exc;
+                const delay = connBackoff(exc.retryAfter, attempts);
+                this.log.warn?.(`connections rate-limited (offset=${offset}); backoff ${delay}s (attempt ${attempts})`);
+                if (delay)
+                    await this.sleep(delay);
+            }
+        }
+    }
+    /**
+     * Fetch a single connection by id → one {@link Connection}.
+     *
+     * `GET /api/company-data/connections/{id}` returns `{connection_id, user_id,
+     * values}` and no displayName/connectedAt; those identity fields simply stay
+     * `null` (the list endpoint carries them).
+     */
+    async connection(id) {
+        await this.requestFields();
+        let body = await this.http.get(`${CONNECTIONS}/${id}`);
+        if (body !== null &&
+            typeof body === 'object' &&
+            !Array.isArray(body) &&
+            'items' in body &&
+            !('values' in body)) {
+            // Defensive: a single-item list shape.
+            const items = listItems(body);
+            body = items.length > 0 ? items[0] : {};
+        }
+        return Connection.fromApi(body, {
+            typeForSlug: this.typeForSlug,
+            decryptValue: this.decryptValue,
+            binaryFetch: this.binaryFetch,
+        });
+    }
+    // ── logs (moderate rate-limit) ──────────────────────────────────────────────
+    /**
+     * The service's activity log → `LogEntry[]`.
+     *
+     * `GET /api/company-data/logs?limit&offset`. Ops events only (email / purge /
+     * webhook) — never person field data.
+     */
+    async logs(limit = 50, offset = 0) {
+        const body = await this.http.get(LOGS, {
+            limit: Math.max(1, Math.trunc(limit)),
+            offset: Math.max(0, Math.trunc(offset)),
+        });
+        return LogEntry.listFromApi(body);
+    }
+    // ── changes feed — the crash-safe pump ──────────────────────────────────────
+    /** The crash-safe changes {@link Pump} (built lazily). */
+    get pump() {
+        if (this._pump === null) {
+            this._pump = new Pump(this.config, {
+                fetchChanges: (limit) => this.fetchChanges(limit),
+                decrypt: (event) => this.decryptChange(event),
+                logger: this.log,
+                sleep: this.sleep,
+            });
+        }
+        return this._pump;
+    }
+    async fetchChanges(limit) {
+        const body = await this.http.get(CHANGES, { limit: Math.trunc(limit) });
+        let items;
+        if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+            items = body['changes'] ?? [];
+        }
+        else {
+            items = body ?? [];
+        }
+        if (!Array.isArray(items))
+            return [];
+        return items.filter((o) => o !== null && typeof o === 'object' && !Array.isArray(o));
+    }
+    decryptChange(event) {
+        return Change.fromApi(event, {
+            typeForSlug: this.typeForSlug,
+            decryptValue: this.decryptValue,
+            binaryFetch: this.binaryFetch,
+        });
+    }
+    /**
+     * Drain the changes feed through `handler` one at a time, crash-safely.
+     *
+     * Delegates to the {@link Pump}: replay the durable buffer, drain ≤500 at a time,
+     * persist-before-deliver, per-item ack, retry→dead-letter→continue, until the feed
+     * is empty then return (no daemon mode — schedule re-runs yourself). `handler` must
+     * be idempotent (at-least-once; dedup on `Change.id`). Options:
+     * `batchSize` (≤500), `maxRetries`, `onError` (`deadletter`|`halt`), `backoff`.
+     */
+    async processChanges(handler, options = {}) {
+        await this.requestFields(); // ensure the catalog is loaded for value typing
+        await this.pump.processChanges(handler, options);
+    }
+    /** Raw, UNBUFFERED drain → `Change[]` (advanced — you own durability). */
+    async drainBatch(max = DEFAULT_CONN_PAGE) {
+        await this.requestFields();
+        return this.pump.drainBatch(max);
+    }
+    /** The local dead-letter store. */
+    deadLetters() {
+        return this.pump.deadLetters();
+    }
+    /** Re-drive dead-lettered events through `handler`. */
+    async retryDeadLetters(handler, options = {}) {
+        await this.requestFields();
+        return this.pump.retryDeadLetters(handler, options);
+    }
+    // ── webhook receiver helpers (config-driven, no key args) ───────────────────
+    /** Verify a webhook's `X-Allus-Signature` HMAC. */
+    verifyWebhook(rawBody, headers) {
+        return verifyWebhook(rawBody, headers, this.config);
+    }
+    /** Parse a webhook body → a typed {@link Change}. */
+    parseWebhook(rawBody, headers) {
+        return parseWebhook(rawBody, headers, this.config, {
+            typeForSlug: this.typeForSlug,
+            decryptValue: this.decryptValue,
+            binaryFetch: this.binaryFetch,
+            accountKey: this.accountKey, // cached once; no per-webhook PBKDF2
+        });
+    }
+    /** Verify + parse a webhook in one call → {@link Change}. */
+    handleWebhook(rawBody, headers) {
+        return handleWebhook(rawBody, headers, this.config, {
+            typeForSlug: this.typeForSlug,
+            decryptValue: this.decryptValue,
+            binaryFetch: this.binaryFetch,
+            accountKey: this.accountKey, // cached once; no per-webhook PBKDF2
+        });
+    }
+}
+// ── module-level helpers ──────────────────────────────────────────────────────
+/** Read the configured encrypted PEM and decrypt it with the passphrase (once). */
+function loadServiceKey(config) {
+    let pemBytes;
+    try {
+        pemBytes = readFileSync(config.servicePrivateKey);
+    }
+    catch (exc) {
+        throw new ConfigError(`could not read servicePrivateKey PEM: ${config.servicePrivateKey}: ${exc.message}`);
+    }
+    try {
+        return loadPrivateKey(pemBytes, config.keyPassphrase);
+    }
+    catch (exc) {
+        if (exc instanceof DecryptError) {
+            // A bad passphrase / malformed PEM is a configuration problem (fail fast).
+            throw new ConfigError(`could not load service private key: ${exc.message}`);
+        }
+        throw exc;
+    }
+}
+/** Pull the `items` array out of a `{total, items}` list response. */
+function listItems(body) {
+    if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+        const items = body['items'];
+        if (items === undefined || items === null)
+            return [];
+        return Array.isArray(items) ? items : [];
+    }
+    if (Array.isArray(body))
+        return body;
+    return [];
+}
+/** Read the `total` count out of a `{total, items}` list response (or keep the prior). */
+function readTotal(body, prior) {
+    if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+        const t = body['total'];
+        if (t !== undefined && t !== null) {
+            const n = Number(t);
+            if (Number.isFinite(n))
+                return n;
+        }
+    }
+    return prior;
+}
+/** Backoff before retrying a rate-limited connections page. */
+function connBackoff(retryAfter, attempt) {
+    if (retryAfter !== null && retryAfter >= 0) {
+        return Math.min(retryAfter, CONN_MAX_BACKOFF_S);
+    }
+    return Math.min(CONN_DEFAULT_BACKOFF_S * 2 ** (attempt - 1), CONN_MAX_BACKOFF_S);
+}

package/dist/esm/config.js

@@ -0,0 +1,237 @@
+/**
+ * Configuration loading.
+ *
+ * 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. The developer's
+ * only key responsibility is putting the right values here.
+ *
+ * A single JSON file holds everything; any field may be overridden by an `ALLUS_*`
+ * env var, so secrets needn't live in the file.
+ */
+import { readFileSync } from 'node:fs';
+import { ConfigError } from './errors.js';
+/** Mapping from a Config field name to its `ALLUS_*` env-var override. */
+const ENV_MAP = {
+    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',
+};
+// JSON file keys are snake_case (identical across all six SDKs' config files);
+// this maps a Config attribute back to the file key it reads.
+const FILE_KEY = {
+    apiUrl: 'api_url',
+    clientId: 'client_id',
+    clientSecret: 'client_secret',
+    servicePrivateKey: 'service_private_key',
+    keyPassphrase: 'key_passphrase',
+    accountPrivateKey: 'account_private_key',
+    accountPassphrase: 'account_passphrase',
+    cacheDir: 'cache_dir',
+    format: 'format',
+};
+const WEBHOOK_SECRET_ENV = 'ALLUS_WEBHOOK_SECRET';
+const REQUIRED = ['apiUrl', 'clientId', 'clientSecret', 'servicePrivateKey', 'keyPassphrase'];
+const VALID_FORMATS = ['json', 'xml'];
+/** Reserved webhook-map key under which a flat `webhook_secret` is stored. */
+export const SINGLE_WEBHOOK_KEY = '__single__';
+/** The whole SDK configuration. Keys live here and nowhere else. */
+export class Config {
+    constructor(init) {
+        this.apiUrl = init.apiUrl;
+        this.clientId = init.clientId;
+        this.clientSecret = init.clientSecret;
+        this.servicePrivateKey = init.servicePrivateKey;
+        this.keyPassphrase = init.keyPassphrase;
+        this.accountPrivateKey = init.accountPrivateKey ?? null;
+        this.accountPassphrase = init.accountPassphrase ?? null;
+        this.webhooks = init.webhooks ?? {};
+        this.webhookBearerToken = init.webhookBearerToken ?? null;
+        this.webhookBasic = init.webhookBasic ?? null;
+        this.webhookHeader = init.webhookHeader ?? null;
+        this.webhookAuthNone = init.webhookAuthNone ?? false;
+        this.cacheDir = init.cacheDir ?? './allus-cache';
+        this.format = init.format ?? 'json';
+    }
+    /** Load from a JSON file; env vars override file values. */
+    static fromFile(path) {
+        let raw;
+        try {
+            raw = readFileSync(path, 'utf8');
+        }
+        catch (exc) {
+            const e = exc;
+            if (e.code === 'ENOENT') {
+                throw new ConfigError(`config file not found: ${path}`);
+            }
+            throw new ConfigError(`could not read config file: ${path}: ${e.message}`);
+        }
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch (exc) {
+            throw new ConfigError(`config file is not valid JSON: ${path}: ${exc.message}`);
+        }
+        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+            throw new ConfigError(`config file must be a JSON object: ${path}`);
+        }
+        return Config.build(data);
+    }
+    /** Build entirely from `ALLUS_*` env vars. */
+    static fromEnv() {
+        return Config.build({});
+    }
+    /** Merge file values with env overrides, validate, and construct. */
+    static build(data) {
+        const values = {};
+        // Scalar fields: env var (if set) overrides the file value.
+        for (const attr of Object.keys(ENV_MAP)) {
+            const envVal = process.env[ENV_MAP[attr]];
+            const fileKey = FILE_KEY[attr];
+            if (envVal !== undefined) {
+                values[attr] = envVal;
+            }
+            else if (data[fileKey] !== undefined && data[fileKey] !== null) {
+                values[attr] = data[fileKey];
+            }
+        }
+        // Webhook secrets: the "webhooks" map plus the flat "webhook_secret" shortcut
+        // (and its env override), normalized into a single dict.
+        const webhooks = {};
+        const fileWebhooks = data['webhooks'];
+        if (fileWebhooks !== undefined && fileWebhooks !== null) {
+            if (typeof fileWebhooks !== 'object' || Array.isArray(fileWebhooks)) {
+                throw new ConfigError('"webhooks" must be an object mapping webhook id -> secret');
+            }
+            for (const [k, v] of Object.entries(fileWebhooks)) {
+                webhooks[String(k)] = String(v);
+            }
+        }
+        let flatSecret = process.env[WEBHOOK_SECRET_ENV];
+        if (flatSecret === undefined) {
+            flatSecret = data['webhook_secret'];
+        }
+        if (flatSecret !== undefined && flatSecret !== null) {
+            webhooks[SINGLE_WEBHOOK_KEY] = String(flatSecret);
+        }
+        const hasWebhooks = Object.keys(webhooks).length > 0;
+        // Alternative webhook auth methods (file-config only; no env overrides).
+        // Validate object shapes.
+        let webhookBearerToken = null;
+        const bearer = data['webhook_bearer_token'];
+        if (bearer) {
+            webhookBearerToken = String(bearer);
+        }
+        let webhookBasic = null;
+        const basic = data['webhook_basic'];
+        if (basic !== undefined && basic !== null) {
+            const b = basic;
+            if (typeof basic !== 'object' || Array.isArray(basic) || !b['username'] || !b['password']) {
+                throw new ConfigError('"webhook_basic" must be an object with non-empty "username" and "password"');
+            }
+            webhookBasic = { username: String(b['username']), password: String(b['password']) };
+        }
+        let webhookHeader = null;
+        const hdr = data['webhook_header'];
+        if (hdr !== undefined && hdr !== null) {
+            const h = hdr;
+            if (typeof hdr !== 'object' || Array.isArray(hdr) || !h['name'] || !h['value']) {
+                throw new ConfigError('"webhook_header" must be an object with non-empty "name" and "value"');
+            }
+            webhookHeader = { name: String(h['name']), value: String(h['value']) };
+        }
+        const webhookAuthNone = data['webhook_auth_none'] === true;
+        // At most one webhook auth method may be configured.
+        const present = [];
+        if (hasWebhooks)
+            present.push('hmac');
+        if (webhookBearerToken)
+            present.push('bearer');
+        if (webhookBasic)
+            present.push('basic');
+        if (webhookHeader)
+            present.push('header');
+        if (webhookAuthNone)
+            present.push('none');
+        if (present.length > 1) {
+            throw new ConfigError('configure at most one webhook auth method (found: ' + present.join(', ') + ')');
+        }
+        // Required fields (fail fast). Report by the config-file key
+        // (snake_case) so the message is actionable for whoever wrote the file.
+        const missing = REQUIRED.filter((name) => {
+            const v = values[name];
+            return v === undefined || v === null || v === '';
+        }).map((name) => FILE_KEY[name]);
+        if (missing.length > 0) {
+            throw new ConfigError(`missing required config field(s): ${missing.join(', ')}`);
+        }
+        // Validate the wire format if supplied.
+        let format = 'json';
+        if (values['format'] !== undefined) {
+            const fmt = String(values['format']).toLowerCase();
+            if (!VALID_FORMATS.includes(fmt)) {
+                throw new ConfigError(`invalid "format": '${fmt}' (expected one of ${VALID_FORMATS.join(', ')})`);
+            }
+            format = fmt;
+        }
+        return new Config({
+            apiUrl: String(values['apiUrl']),
+            clientId: String(values['clientId']),
+            clientSecret: String(values['clientSecret']),
+            servicePrivateKey: String(values['servicePrivateKey']),
+            keyPassphrase: String(values['keyPassphrase']),
+            accountPrivateKey: values['accountPrivateKey'] !== undefined ? String(values['accountPrivateKey']) : null,
+            accountPassphrase: values['accountPassphrase'] !== undefined ? String(values['accountPassphrase']) : null,
+            webhooks: hasWebhooks ? webhooks : {},
+            webhookBearerToken,
+            webhookBasic,
+            webhookHeader,
+            webhookAuthNone,
+            cacheDir: values['cacheDir'] !== undefined ? String(values['cacheDir']) : './allus-cache',
+            format,
+        });
+    }
+    /**
+     * Resolve the HMAC secret for a webhook id.
+     *
+     * Falls back to the single-webhook shortcut secret when there is no id or no
+     * id-specific match. The webhook helpers read this — application code never
+     * passes a secret in. (This method takes a webhook *id*, never a secret.)
+     */
+    webhookSecret(webhookId) {
+        if (webhookId !== undefined && webhookId !== null && webhookId in this.webhooks) {
+            return this.webhooks[webhookId];
+        }
+        return this.webhooks[SINGLE_WEBHOOK_KEY] ?? null;
+    }
+    /**
+     * The single configured webhook auth method, or `null` if none is set.
+     *
+     * Returns one of `"hmac" | "bearer" | "basic" | "header" | "none"`. Config
+     * loading guarantees at most one is configured, so the order here is only a
+     * tie-break that never triggers.
+     */
+    webhookAuthMethod() {
+        if (this.webhookAuthNone)
+            return 'none';
+        if (this.webhookBearerToken)
+            return 'bearer';
+        if (this.webhookBasic)
+            return 'basic';
+        if (this.webhookHeader)
+            return 'header';
+        if (Object.keys(this.webhooks).length > 0)
+            return 'hmac';
+        return null;
+    }
+}
+/** Reserved webhook-map key under which a flat `webhook_secret` is stored. */
+Config.SINGLE_WEBHOOK_KEY = SINGLE_WEBHOOK_KEY;