@allus-fyi/company-data 0.0.3

package/dist/types/client.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 { Config } from './config.js';
+import { HttpClient, type HttpClientOptions } from './http.js';
+import { Change, Connection, LogEntry, RequestField } from './models.js';
+import { Pump, type Handler, type Logger, type ProcessOptions } from './pump.js';
+import type { DeadLetterRecord } from './buffer.js';
+import { type Headers } from './webhooks.js';
+export interface ClientOptions {
+    /** An injected transport/auth layer (for tests). */
+    http?: HttpClient;
+    /** Options forwarded to the default {@link HttpClient} when `http` is not supplied. */
+    httpOptions?: HttpClientOptions;
+    /** A logger sink for the pump (every drain/deliver/ack/retry/dead-letter/replay). */
+    logger?: Logger;
+    /** A sleep callable (seconds → Promise) — injectable for tests. */
+    sleep?: (seconds: number) => Promise<void>;
+}
+/** The company-data SDK client facade. */
+export declare class Client {
+    private readonly config;
+    private readonly log;
+    private readonly sleep;
+    private readonly http;
+    private readonly privateKey;
+    private readonly accountKey;
+    private cachedRequestFields;
+    private typeBySlug;
+    private requestFieldsInFlight;
+    private _pump;
+    constructor(config: Config, opts?: ClientOptions);
+    /** Build from a JSON config file (env vars override secrets). */
+    static fromConfig(path: string, opts?: ClientOptions): Client;
+    /** Build entirely from `ALLUS_*` env vars. */
+    static fromEnv(opts?: ClientOptions): Client;
+    private decryptValue;
+    /**
+     * 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.
+     */
+    private binaryFetch;
+    /** Resolve a request slug to its field type (loads the catalog once). */
+    private typeForSlug;
+    /**
+     * 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.
+     */
+    requestFields(): Promise<RequestField[]>;
+    /**
+     * 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.
+     */
+    connections(limit?: number, offset?: number): AsyncGenerator<Connection>;
+    private getConnectionsPage;
+    /**
+     * 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).
+     */
+    connection(id: string): Promise<Connection>;
+    /**
+     * The service's activity log → `LogEntry[]`.
+     *
+     * `GET /api/company-data/logs?limit&offset`. Ops events only (email / purge /
+     * webhook) — never person field data.
+     */
+    logs(limit?: number, offset?: number): Promise<LogEntry[]>;
+    /** The crash-safe changes {@link Pump} (built lazily). */
+    get pump(): Pump;
+    private fetchChanges;
+    private decryptChange;
+    /**
+     * 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`.
+     */
+    processChanges(handler: Handler, options?: ProcessOptions): Promise<void>;
+    /** Raw, UNBUFFERED drain → `Change[]` (advanced — you own durability). */
+    drainBatch(max?: number): Promise<Change[]>;
+    /** The local dead-letter store. */
+    deadLetters(): DeadLetterRecord[];
+    /** Re-drive dead-lettered events through `handler`. */
+    retryDeadLetters(handler: Handler, options?: ProcessOptions): Promise<number>;
+    /** Verify a webhook's `X-Allus-Signature` HMAC. */
+    verifyWebhook(rawBody: Buffer | Uint8Array | string, headers: Headers): boolean;
+    /** Parse a webhook body → a typed {@link Change}. */
+    parseWebhook(rawBody: Buffer | Uint8Array | string, headers: Headers): Change;
+    /** Verify + parse a webhook in one call → {@link Change}. */
+    handleWebhook(rawBody: Buffer | Uint8Array | string, headers: Headers): Change;
+}

package/dist/types/config.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+export type WireFormat = 'json' | 'xml';
+/** Reserved webhook-map key under which a flat `webhook_secret` is stored. */
+export declare const SINGLE_WEBHOOK_KEY = "__single__";
+/** HTTP Basic webhook-auth credentials ({@link Config.webhookBasic}). */
+export interface WebhookBasic {
+    username: string;
+    password: string;
+}
+/** Custom-header webhook auth ({@link Config.webhookHeader}). */
+export interface WebhookHeader {
+    name: string;
+    value: string;
+}
+/** The single configured webhook auth method, if any. */
+export type WebhookAuthMethod = 'hmac' | 'bearer' | 'basic' | 'header' | 'none';
+interface ConfigInit {
+    apiUrl: string;
+    clientId: string;
+    clientSecret: string;
+    servicePrivateKey: string;
+    keyPassphrase: string;
+    accountPrivateKey?: string | null;
+    accountPassphrase?: string | null;
+    webhooks?: Record<string, string>;
+    webhookBearerToken?: string | null;
+    webhookBasic?: WebhookBasic | null;
+    webhookHeader?: WebhookHeader | null;
+    webhookAuthNone?: boolean;
+    cacheDir?: string;
+    format?: WireFormat;
+}
+/** The whole SDK configuration. Keys live here and nowhere else. */
+export declare class Config {
+    readonly apiUrl: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly servicePrivateKey: string;
+    readonly keyPassphrase: string;
+    readonly accountPrivateKey: string | null;
+    readonly accountPassphrase: string | null;
+    readonly webhooks: Record<string, string>;
+    readonly webhookBearerToken: string | null;
+    readonly webhookBasic: WebhookBasic | null;
+    readonly webhookHeader: WebhookHeader | null;
+    readonly webhookAuthNone: boolean;
+    readonly cacheDir: string;
+    readonly format: WireFormat;
+    /** Reserved webhook-map key under which a flat `webhook_secret` is stored. */
+    static readonly SINGLE_WEBHOOK_KEY = "__single__";
+    constructor(init: ConfigInit);
+    /** Load from a JSON file; env vars override file values. */
+    static fromFile(path: string): Config;
+    /** Build entirely from `ALLUS_*` env vars. */
+    static fromEnv(): Config;
+    /** Merge file values with env overrides, validate, and construct. */
+    private static build;
+    /**
+     * 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?: string | null): string | 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(): WebhookAuthMethod | null;
+}
+export {};

package/dist/types/crypto.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Decryption core — byte-identical across all six SDKs.
+ *
+ * Every person value arrives as a ciphertext wrapper, encrypted **for the service
+ * public key**; the SDK decrypts with the service private key. The algorithm MUST
+ * match the platform's Web Crypto encryption exactly:
+ *
+ *     wrapper = {"_enc":1,
+ *                "k":  base64(rsa_oaep_sha256(aesKey, servicePublicKey)),
+ *                "iv": base64(iv12),
+ *                "d":  base64(aes256gcm_ciphertext_with_tag)}
+ *
+ *     decrypt(wrapper, servicePrivateKey):
+ *       aesKey    = RSA-OAEP(SHA-256, MGF1-SHA256) decrypt wrapper.k   // 32 bytes
+ *       plaintext = AES-256-GCM decrypt wrapper.d with aesKey, iv=wrapper.iv
+ *                   // the 16-byte GCM tag is the LAST 16 bytes of d
+ *       return utf8(plaintext)
+ *
+ * The service private key is the OpenSSL-encrypted PKCS#8 PEM downloaded from the
+ * portal (PBES2 = PBKDF2-HMAC-SHA256 + AES-256-CBC, ~100k iters). Node's
+ * `crypto.createPrivateKey({ key, passphrase })` reads it directly (PBES2 is
+ * handled by OpenSSL under the hood).
+ *
+ * Node specifics (the cross-language gotchas to watch for):
+ *   - `crypto.privateDecrypt({ key, padding: RSA_PKCS1_OAEP_PADDING,
+ *     oaepHash: 'sha256' }, k)` — **`oaepHash: 'sha256'` MUST be set explicitly**;
+ *     Node defaults `oaepHash` to SHA-1, which would mismatch the platform and
+ *     fail to unwrap the AES key. Setting it to sha256 also pins MGF1 to SHA-256.
+ *   - `crypto.createDecipheriv('aes-256-gcm', aesKey, iv)` + `setAuthTag(tag)` —
+ *     the 16-byte tag is the LAST 16 bytes of `d`.
+ */
+import { type KeyObject } from 'node:crypto';
+export declare const GCM_TAG_LEN = 16;
+export declare const GCM_IV_LEN = 12;
+export { DecryptError } from './errors.js';
+/** The platform hybrid wrapper `{"_enc":1,k,iv,d}`. */
+export interface EncWrapper {
+    _enc?: number;
+    k: string;
+    iv: string;
+    d: string;
+}
+/**
+ * Load an OpenSSL-encrypted PKCS#8 PEM into an in-memory private key handle.
+ *
+ * The PEM is PBES2 (PBKDF2-HMAC-SHA256 + AES-256-CBC, ~100k iters). Node's
+ * `createPrivateKey` decrypts it with the passphrase (OpenSSL handles the SHA-256
+ * PRF). The key is never written back to disk in plaintext.
+ *
+ * Config-only key handling: this is the single place a passphrase is used, driven
+ * by `Config.keyPassphrase` — never passed in by application code.
+ */
+export declare function loadPrivateKey(encryptedPem: Buffer | string, passphrase: string): KeyObject;
+/**
+ * Decrypt a platform `{"_enc":1,k,iv,d}` wrapper → a utf-8 plaintext string.
+ *
+ * For a *text* value the plaintext is the value itself. For a *binary* value the
+ * plaintext is a JSON envelope STRING (photo: `{"full":"data:...","thumb":...}`;
+ * document: `{"file":"data:...","original_name":...}`) — NOT raw bytes. The full
+ * binary-handle parse (envelope -> data-URI -> bytes) lives on {@link BinaryHandle};
+ * here we only ever decrypt to that envelope string.
+ *
+ * Throws {@link DecryptError} on a malformed wrapper, the wrong key, or a GCM tag
+ * mismatch.
+ */
+export declare function decrypt(wrapper: EncWrapper | string, privateKey: KeyObject): string;
+/** Fetch a slot file endpoint → the inner `{"_enc":1,...}` wrapper. */
+export type BinaryFetch = (valueUrl: string) => Promise<EncWrapper | string> | EncWrapper | string;
+/** Decrypt a ciphertext wrapper → the envelope string (closes over the service key). */
+export type DecryptWrapper = (wrapper: EncWrapper | string) => string;
+/**
+ * Lazy handle for a binary (photo/document) value.
+ *
+ * A binary answer is stored server-side as a file, exposed in the hardened API as
+ * a slot-keyed `value_url` (never the source field). On `.bytes()` / `.save()` the
+ * handle GETs that URL, receives the `{"_enc":1,...}` wrapper, runs the same
+ * decrypt as text → a JSON envelope STRING (photo: `{"full":"data:...","thumb":...}`;
+ * document: `{"file":"data:...",...}`) — NOT raw bytes — then parses the envelope
+ * and base64-decodes the primary data-URI payload (`full` for photos, `file` for
+ * documents) into the file bytes.
+ *
+ * The fetch + decrypt are supplied by the client as plain callables (config-only
+ * key handling — no key is ever passed to this handle):
+ *   - `valueUrl` + `fetch` — `fetch(valueUrl)` returns the encrypted wrapper (the
+ *     client passes a callback that GETs the slot file endpoint and unwraps the
+ *     `{"encrypted": true, "value": <wrapper>}` envelope to the inner wrapper).
+ *   - `decrypt` — `decrypt(wrapper)` returns the decrypted envelope string (a
+ *     closure over the loaded service private key).
+ *
+ * For the shared crypto test vector the decrypted envelope is already in hand, so
+ * a handle can also be built directly from `envelopeJson` (no fetch).
+ */
+export declare class BinaryHandle {
+    private envelopeJson;
+    private readonly _valueUrl;
+    private readonly fetch;
+    private readonly decryptWrapper;
+    constructor(opts?: {
+        envelopeJson?: string | null;
+        valueUrl?: string | null;
+        fetch?: BinaryFetch | null;
+        decrypt?: DecryptWrapper | null;
+    });
+    /** The slot-keyed file URL this handle fetches from (opaque to callers). */
+    get valueUrl(): string | null;
+    private resolveEnvelope;
+    /**
+     * Turn a decrypted binary envelope STRING into the primary file bytes.
+     *
+     * Photo envelope -> the `full` data-URI payload; document envelope -> the `file`
+     * data-URI payload. Throws {@link DecryptError} on a malformed envelope.
+     */
+    static parseEnvelopeBytes(envelopeJson: string): Buffer;
+    /** Fetch (if needed), decrypt, and return the decoded primary file bytes. */
+    bytes(): Promise<Buffer>;
+    /**
+     * Write the decoded file bytes to `path`; returns the number of bytes written.
+     *
+     * Crash-safe (matching the buffer's atomic-write discipline): the
+     * bytes are written to a temp file in the same directory, fsync'd, and atomically
+     * renamed into place — so a crash mid-write never leaves a truncated output file
+     * (the destination is either the old file or the complete new one).
+     */
+    save(path: string): Promise<number>;
+}

package/dist/types/errors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Error taxonomy — the same names across all six SDKs.
+ *
+ * | Error                          | When                                              |
+ * |--------------------------------|---------------------------------------------------|
+ * | ConfigError                    | Missing/invalid config or key file at construction (fail fast). |
+ * | AuthError                      | Token fetch/refresh failed (bad client_id/secret, revoked client). |
+ * | ApiError(status, errorKey,…)   | Any non-2xx from the API; carries the HTTP status + the platform error_key + message. |
+ * | DecryptError                   | Wrapper malformed, wrong key, or GCM tag mismatch. |
+ * | WebhookError                   | Signature verification failed or an envelope couldn't be unwrapped. |
+ * | RateLimitError(retryAfter)     | A 429 from a rate-limited endpoint (subclass of ApiError); carries Retry-After. |
+ *
+ * All errors extend a common {@link AllusError} base so a single `catch (e) { if (e
+ * instanceof AllusError) … }` captures the whole taxonomy. `DecryptError` is raised
+ * by the decryption core and re-exported here so the full taxonomy lives in one
+ * place.
+ */
+/** Base class for every SDK error. */
+export declare class AllusError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Missing or invalid configuration (or key file) at construction (fail fast).
+ *
+ * Canonical home for the error; the config + client layers throw it for a bad
+ * config file, a missing required field, an unreadable PEM, or a wrong passphrase.
+ */
+export declare class ConfigError extends AllusError {
+}
+/**
+ * The `client_credentials` token fetch or refresh failed.
+ *
+ * Thrown when `/oauth2/token` rejects the credentials, or when a 401 mid-flight
+ * survives the one automatic refresh-and-retry.
+ */
+export declare class AuthError extends AllusError {
+}
+/**
+ * Any non-2xx from the API.
+ *
+ * Carries the HTTP `status`, the platform `errorKey` (when the body provided one),
+ * and a human-readable `message`. A transport failure (no HTTP response — e.g. a
+ * connection error) surfaces as `new ApiError(0, null, …)`.
+ */
+export declare class ApiError extends AllusError {
+    readonly status: number;
+    readonly errorKey: string | null;
+    /** The human-readable message (distinct from the formatted `Error.message`). */
+    readonly apiMessage: string | null;
+    constructor(status: number, errorKey?: string | null, message?: string | null);
+}
+/** Signature verification failed, or a webhook envelope couldn't be unwrapped. */
+export declare class WebhookError extends AllusError {
+}
+/**
+ * A 429 from a rate-limited endpoint.
+ *
+ * Subclass of {@link ApiError} with a fixed status of 429; carries the
+ * `retryAfter` value parsed from the `Retry-After` response header (seconds, or
+ * `null` when absent).
+ */
+export declare class RateLimitError extends ApiError {
+    readonly retryAfter: number | null;
+    constructor(retryAfter?: number | null, errorKey?: string | null, message?: string | null);
+}
+/**
+ * Wrapper malformed, wrong key, or GCM tag mismatch.
+ *
+ * Defined here (rather than in `crypto.ts`) so the whole taxonomy is importable
+ * from one module; the decryption core imports + throws it.
+ */
+export declare class DecryptError extends AllusError {
+}

package/dist/types/http.d.ts

@@ -0,0 +1,80 @@
+/**
+ * OAuth token + HTTP layer.
+ *
+ * The {@link HttpClient} is the thin transport every higher layer goes through. It
+ * owns:
+ *
+ *   - **Auth** — `client_credentials` only. On the first call (or when the cached
+ *     token is near expiry) it POSTs `client_id`/`client_secret` to
+ *     `{api_url}/oauth2/token` and caches the bearer token + its expiry. Refresh is
+ *     automatic and transparent; a 401 mid-flight triggers exactly one
+ *     refresh-and-retry, then surfaces as {@link AuthError}.
+ *   - **Format** — sets `Accept` per `config.format` (`application/json` or
+ *     `application/xml`) and parses the body accordingly. The XML parser is the
+ *     XXE-safe `parseXml` (mirrors the platform serializer).
+ *   - **Errors** — maps non-2xx to the error taxonomy: a 401 → refresh+retry then
+ *     {@link AuthError}; a 429 → read `Retry-After` and back off + retry a bounded
+ *     number of times, then {@link RateLimitError}; any other non-2xx →
+ *     {@link ApiError} carrying the body's `error_key` when present.
+ *
+ * Config-only key handling: the client id/secret come from the {@link Config} —
+ * never a method argument.
+ *
+ * The transport is injectable (`HttpTransport`) so the whole client is testable
+ * without the network; the default uses Node's global `fetch`.
+ */
+import { Config } from './config.js';
+/** A minimal HTTP response shape (a subset of the Fetch API `Response`). */
+export interface HttpResponse {
+    status: number;
+    text(): Promise<string>;
+    /** Case-insensitive header lookup, returning `null` when absent (Fetch `Headers`). */
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/** A pluggable transport (the default wraps Node's global `fetch`). */
+export interface HttpTransport {
+    post(url: string, form: Record<string, string>, headers: Record<string, string>): Promise<HttpResponse>;
+    get(url: string, params: Record<string, string | number> | undefined, headers: Record<string, string>): Promise<HttpResponse>;
+}
+export type Sleep = (seconds: number) => Promise<void>;
+export type Clock = () => number;
+/** Default transport over Node's global `fetch`. */
+export declare class FetchTransport implements HttpTransport {
+    post(url: string, form: Record<string, string>, headers: Record<string, string>): Promise<HttpResponse>;
+    get(url: string, params: Record<string, string | number> | undefined, headers: Record<string, string>): Promise<HttpResponse>;
+}
+export interface HttpClientOptions {
+    transport?: HttpTransport;
+    sleep?: Sleep;
+    clock?: Clock;
+    maxRetries429?: number;
+}
+/** Authenticated JSON/XML transport for the company-data API. */
+export declare class HttpClient {
+    private readonly config;
+    private readonly transport;
+    private readonly sleep;
+    private readonly clock;
+    private readonly maxRetries429;
+    private readonly apiUrl;
+    private token;
+    private tokenExpiry;
+    constructor(config: Config, opts?: HttpClientOptions);
+    private tokenValid;
+    private fetchToken;
+    private bearer;
+    /**
+     * GET `path` (e.g. `/api/company-data/connections`) → parsed body.
+     *
+     * Adds the bearer token + an `Accept` header matching `config.format`, parses
+     * JSON or XML, and maps non-2xx responses to the error taxonomy: 401 → one
+     * refresh-and-retry then {@link AuthError}; 429 → bounded Retry-After backoff
+     * then {@link RateLimitError}; other non-2xx → {@link ApiError} (carrying the
+     * body's `error_key` when present).
+     */
+    get(path: string, params?: Record<string, string | number>): Promise<unknown>;
+    private url;
+    private parseBody;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export { Client } from './client.js';
+export type { ClientOptions } from './client.js';
+export { Config, SINGLE_WEBHOOK_KEY } from './config.js';
+export type { WireFormat, WebhookBasic, WebhookHeader, WebhookAuthMethod } from './config.js';
+export { loadPrivateKey, decrypt, BinaryHandle, GCM_IV_LEN, GCM_TAG_LEN } from './crypto.js';
+export type { EncWrapper, BinaryFetch, DecryptWrapper } from './crypto.js';
+export { AllusError, ConfigError, AuthError, ApiError, DecryptError, WebhookError, RateLimitError, } from './errors.js';
+export { HttpClient, FetchTransport } from './http.js';
+export type { HttpTransport, HttpResponse, HttpClientOptions, Sleep, Clock } from './http.js';
+export { RequestField, Connection, Value, Change, LogEntry, STRUCTURED_TYPES, BINARY_TYPES, DATE_TYPES, } from './models.js';
+export type { TypeForSlug } from './models.js';
+export { FileBuffer } from './buffer.js';
+export type { BufferedEvent, DeadLetterRecord } from './buffer.js';
+export { Pump, MAX_BATCH } from './pump.js';
+export type { FetchChanges, DecryptChange, Handler, Logger, OnError, ProcessOptions, PumpOptions, } from './pump.js';
+export { verifyWebhook, parseWebhook, handleWebhook, loadAccountKey } from './webhooks.js';
+export type { Headers } from './webhooks.js';
+export { parseXml, XmlParseError } from './xml.js';
+export declare const VERSION = "0.1.0";