@allus-fyi/company-data 0.0.3

package/dist/cjs/crypto.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BinaryHandle = exports.DecryptError = exports.GCM_IV_LEN = exports.GCM_TAG_LEN = void 0;
+exports.loadPrivateKey = loadPrivateKey;
+exports.decrypt = decrypt;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const errors_js_1 = require("./errors.js");
+exports.GCM_TAG_LEN = 16; // bytes — appended to the AES-GCM ciphertext
+exports.GCM_IV_LEN = 12; // bytes
+// Re-export so `crypto.ts` consumers can pull the error alongside the core.
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "DecryptError", { enumerable: true, get: function () { return errors_js_2.DecryptError; } });
+/**
+ * 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.
+ */
+function loadPrivateKey(encryptedPem, passphrase) {
+    try {
+        return (0, node_crypto_1.createPrivateKey)({ key: encryptedPem, passphrase });
+    }
+    catch (exc) {
+        // A wrong passphrase / malformed PEM / unsupported algorithm all land here.
+        throw new errors_js_1.DecryptError(`could not load private key PEM: ${exc.message}`);
+    }
+}
+function b64decode(value, fieldName) {
+    if (typeof value !== 'string') {
+        throw new errors_js_1.DecryptError(`wrapper field '${fieldName}' must be a base64 string`);
+    }
+    // Validate strictly: re-encoding must reproduce the (normalized) input so we
+    // reject genuinely malformed base64 like the Python `validate=True` path does.
+    const buf = Buffer.from(value, 'base64');
+    const normalized = value.replace(/\s+/g, '');
+    if (buf.toString('base64').replace(/=+$/, '') !== normalized.replace(/=+$/, '')) {
+        throw new errors_js_1.DecryptError(`wrapper field '${fieldName}' is not valid base64`);
+    }
+    return buf;
+}
+function parseWrapper(wrapper) {
+    let obj = wrapper;
+    if (typeof wrapper === 'string') {
+        try {
+            obj = JSON.parse(wrapper);
+        }
+        catch {
+            throw new errors_js_1.DecryptError('wrapper string is not valid JSON');
+        }
+    }
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        throw new errors_js_1.DecryptError('wrapper must be an object or a JSON object string');
+    }
+    const rec = obj;
+    for (const fieldName of ['k', 'iv', 'd']) {
+        if (!(fieldName in rec)) {
+            throw new errors_js_1.DecryptError(`wrapper missing required field '${fieldName}'`);
+        }
+    }
+    return rec;
+}
+/**
+ * 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.
+ */
+function decrypt(wrapper, privateKey) {
+    const w = parseWrapper(wrapper);
+    const encKey = b64decode(w.k, 'k');
+    const iv = b64decode(w.iv, 'iv');
+    const ciphertextWithTag = b64decode(w.d, 'd');
+    if (iv.length !== exports.GCM_IV_LEN) {
+        throw new errors_js_1.DecryptError(`iv must be ${exports.GCM_IV_LEN} bytes, got ${iv.length}`);
+    }
+    if (ciphertextWithTag.length < exports.GCM_TAG_LEN) {
+        throw new errors_js_1.DecryptError('ciphertext too short to contain a GCM tag');
+    }
+    // 1) RSA-OAEP(SHA-256, MGF1-SHA256) unwrap the AES key. `oaepHash: 'sha256'`
+    //    MUST be set explicitly — Node defaults to SHA-1 (and setting the OAEP hash
+    //    also pins MGF1 to the same digest), matching Web Crypto RSA-OAEP/SHA-256.
+    let aesKey;
+    try {
+        aesKey = (0, node_crypto_1.privateDecrypt)({
+            key: privateKey,
+            padding: node_crypto_1.constants.RSA_PKCS1_OAEP_PADDING,
+            oaepHash: 'sha256',
+        }, encKey);
+    }
+    catch (exc) {
+        throw new errors_js_1.DecryptError(`RSA-OAEP unwrap failed (wrong key?): ${exc.message}`);
+    }
+    if (aesKey.length !== 32) {
+        throw new errors_js_1.DecryptError(`unwrapped AES key must be 32 bytes (AES-256), got ${aesKey.length}`);
+    }
+    // 2) AES-256-GCM decrypt. The 16-byte tag is the LAST 16 bytes of `d`.
+    const tag = ciphertextWithTag.subarray(ciphertextWithTag.length - exports.GCM_TAG_LEN);
+    const ciphertext = ciphertextWithTag.subarray(0, ciphertextWithTag.length - exports.GCM_TAG_LEN);
+    let plaintext;
+    try {
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', aesKey, iv);
+        decipher.setAuthTag(tag);
+        plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    catch {
+        throw new errors_js_1.DecryptError('AES-GCM tag mismatch (wrong key or corrupt data)');
+    }
+    // utf-8 with strict-ish handling: Node's 'utf8' decode replaces invalid bytes,
+    // so re-encode and compare to catch a non-UTF-8 plaintext (parity with Python's
+    // strict decode → DecryptError).
+    const text = plaintext.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(plaintext)) {
+        throw new errors_js_1.DecryptError('decrypted plaintext is not valid UTF-8');
+    }
+    return text;
+}
+const DATA_URI_KEYS = ['full', 'file'];
+/**
+ * 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).
+ */
+class BinaryHandle {
+    constructor(opts = {}) {
+        this.envelopeJson = opts.envelopeJson ?? null;
+        this._valueUrl = opts.valueUrl ?? null;
+        this.fetch = opts.fetch ?? null;
+        this.decryptWrapper = opts.decrypt ?? null;
+    }
+    /** The slot-keyed file URL this handle fetches from (opaque to callers). */
+    get valueUrl() {
+        return this._valueUrl;
+    }
+    async resolveEnvelope() {
+        if (this.envelopeJson !== null) {
+            return this.envelopeJson;
+        }
+        if (this.fetch === null || this.decryptWrapper === null || this._valueUrl === null) {
+            throw new errors_js_1.DecryptError('BinaryHandle has no envelope and no fetch/decrypt wiring ' +
+                '(build it with envelopeJson, or valueUrl + fetch + decrypt)');
+        }
+        const wrapper = await this.fetch(this._valueUrl);
+        const envelopeJson = this.decryptWrapper(wrapper);
+        // Cache so repeated .bytes()/.save() don't re-fetch.
+        this.envelopeJson = envelopeJson;
+        return envelopeJson;
+    }
+    /**
+     * 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) {
+        let envelope;
+        try {
+            envelope = JSON.parse(envelopeJson);
+        }
+        catch {
+            throw new errors_js_1.DecryptError('binary envelope is not valid JSON');
+        }
+        if (envelope === null || typeof envelope !== 'object' || Array.isArray(envelope)) {
+            throw new errors_js_1.DecryptError('binary envelope must be a JSON object');
+        }
+        const rec = envelope;
+        let dataUri = null;
+        for (const key of DATA_URI_KEYS) {
+            if (typeof rec[key] === 'string') {
+                dataUri = rec[key];
+                break;
+            }
+        }
+        if (dataUri === null) {
+            throw new errors_js_1.DecryptError("binary envelope has no 'full'/'file' data-URI payload");
+        }
+        // data:<mime>;base64,<payload>
+        const marker = 'base64,';
+        const idx = dataUri.indexOf(marker);
+        if (idx === -1) {
+            throw new errors_js_1.DecryptError('binary data URI is not base64-encoded');
+        }
+        const payload = dataUri.slice(idx + marker.length);
+        const buf = Buffer.from(payload, 'base64');
+        if (buf.length === 0 && payload.length !== 0) {
+            throw new errors_js_1.DecryptError('binary data-URI payload is not valid base64');
+        }
+        return buf;
+    }
+    /** Fetch (if needed), decrypt, and return the decoded primary file bytes. */
+    async bytes() {
+        return BinaryHandle.parseEnvelopeBytes(await this.resolveEnvelope());
+    }
+    /**
+     * 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).
+     */
+    async save(path) {
+        const data = await this.bytes();
+        const directory = (0, node_path_1.dirname)((0, node_path_1.resolve)(path));
+        const tmp = (0, node_path_1.join)(directory, `.tmp_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2)}.part`);
+        try {
+            (0, node_fs_1.writeFileSync)(tmp, data);
+            const fd = (0, node_fs_1.openSync)(tmp, 'r');
+            try {
+                (0, node_fs_1.fsyncSync)(fd);
+            }
+            finally {
+                (0, node_fs_1.closeSync)(fd);
+            }
+            (0, node_fs_1.renameSync)(tmp, path); // atomic rename over any existing file
+        }
+        catch (exc) {
+            try {
+                (0, node_fs_1.unlinkSync)(tmp);
+            }
+            catch {
+                // ignore — the temp file may not have been created
+            }
+            throw exc;
+        }
+        return data.length;
+    }
+}
+exports.BinaryHandle = BinaryHandle;

package/dist/cjs/errors.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecryptError = exports.RateLimitError = exports.WebhookError = exports.ApiError = exports.AuthError = exports.ConfigError = exports.AllusError = void 0;
+/** Base class for every SDK error. */
+class AllusError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+        // Restore the prototype chain for `instanceof` across the ES5 transpile target.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.AllusError = AllusError;
+/**
+ * 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.
+ */
+class ConfigError extends AllusError {
+}
+exports.ConfigError = ConfigError;
+/**
+ * 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.
+ */
+class AuthError extends AllusError {
+}
+exports.AuthError = AuthError;
+/**
+ * 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, …)`.
+ */
+class ApiError extends AllusError {
+    constructor(status, errorKey = null, message = null) {
+        const parts = [`HTTP ${status}`];
+        if (errorKey)
+            parts.push(`(${errorKey})`);
+        if (message)
+            parts.push(`: ${message}`);
+        super(parts.join(' '));
+        this.status = status;
+        this.errorKey = errorKey;
+        this.apiMessage = message;
+    }
+}
+exports.ApiError = ApiError;
+/** Signature verification failed, or a webhook envelope couldn't be unwrapped. */
+class WebhookError extends AllusError {
+}
+exports.WebhookError = WebhookError;
+/**
+ * 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).
+ */
+class RateLimitError extends ApiError {
+    constructor(retryAfter = null, errorKey = null, message = null) {
+        super(429, errorKey, message);
+        this.retryAfter = retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * 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.
+ */
+class DecryptError extends AllusError {
+}
+exports.DecryptError = DecryptError;

package/dist/cjs/http.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = exports.FetchTransport = void 0;
+const errors_js_1 = require("./errors.js");
+const xml_js_1 = require("./xml.js");
+// Refresh the token a little before it actually expires so an in-flight call never
+// races the expiry boundary.
+const TOKEN_EXPIRY_SKEW_S = 30.0;
+// 429 backoff policy: bounded retries with a Retry-After-driven (or default) sleep
+// between attempts. Connections endpoints are heavily limited, so after the bounded
+// retries we surface RateLimitError rather than hammering.
+const DEFAULT_MAX_RETRIES_429 = 3;
+const DEFAULT_BACKOFF_S = 1.0;
+const MAX_BACKOFF_S = 60.0;
+const defaultSleep = (seconds) => new Promise((res) => setTimeout(res, Math.max(0, seconds) * 1000));
+const defaultClock = () => Date.now() / 1000;
+/** Default transport over Node's global `fetch`. */
+class FetchTransport {
+    async post(url, form, headers) {
+        const body = new URLSearchParams(form).toString();
+        const resp = await fetch(url, {
+            method: 'POST',
+            headers: { ...headers, 'Content-Type': 'application/x-www-form-urlencoded' },
+            body,
+        });
+        return resp;
+    }
+    async get(url, params, headers) {
+        let full = url;
+        if (params && Object.keys(params).length > 0) {
+            const qs = new URLSearchParams();
+            for (const [k, v] of Object.entries(params))
+                qs.set(k, String(v));
+            full += (url.includes('?') ? '&' : '?') + qs.toString();
+        }
+        const resp = await fetch(full, { method: 'GET', headers });
+        return resp;
+    }
+}
+exports.FetchTransport = FetchTransport;
+/** Authenticated JSON/XML transport for the company-data API. */
+class HttpClient {
+    constructor(config, opts = {}) {
+        this.token = null;
+        this.tokenExpiry = 0; // clock deadline (seconds)
+        this.config = config;
+        this.transport = opts.transport ?? new FetchTransport();
+        this.sleep = opts.sleep ?? defaultSleep;
+        this.clock = opts.clock ?? defaultClock;
+        this.maxRetries429 = opts.maxRetries429 ?? DEFAULT_MAX_RETRIES_429;
+        this.apiUrl = config.apiUrl.replace(/\/+$/, '');
+    }
+    // ── auth ────────────────────────────────────────────────────────────────
+    tokenValid() {
+        return this.token !== null && this.clock() < this.tokenExpiry;
+    }
+    async fetchToken() {
+        const url = `${this.apiUrl}/oauth2/token`;
+        let resp;
+        try {
+            resp = await this.transport.post(url, {
+                grant_type: 'client_credentials',
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+            }, { Accept: 'application/json' });
+        }
+        catch (exc) {
+            throw new errors_js_1.AuthError(`token request failed: ${exc.message}`);
+        }
+        const status = resp.status;
+        if (status < 200 || status >= 300) {
+            const { errorKey, message } = await extractError(resp);
+            throw new errors_js_1.AuthError(`token request rejected (HTTP ${status})` +
+                (errorKey ? ` [${errorKey}]` : '') +
+                (message ? `: ${message}` : ''));
+        }
+        let body;
+        try {
+            body = JSON.parse(await resp.text());
+        }
+        catch {
+            throw new errors_js_1.AuthError('token response was not valid JSON');
+        }
+        const accessToken = body !== null && typeof body === 'object' ? body['access_token'] : null;
+        if (!accessToken) {
+            throw new errors_js_1.AuthError('token response missing access_token');
+        }
+        let expiresIn = 3600;
+        const rawExpires = body['expires_in'];
+        if (rawExpires !== undefined) {
+            const n = Number(rawExpires);
+            if (Number.isFinite(n))
+                expiresIn = n;
+        }
+        this.token = String(accessToken);
+        this.tokenExpiry = this.clock() + Math.max(0, expiresIn - TOKEN_EXPIRY_SKEW_S);
+        return this.token;
+    }
+    async bearer(forceRefresh = false) {
+        if (forceRefresh || !this.tokenValid()) {
+            return this.fetchToken();
+        }
+        return this.token;
+    }
+    // ── requests ──────────────────────────────────────────────────────────
+    /**
+     * 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).
+     */
+    async get(path, params) {
+        const url = this.url(path);
+        const wantsXml = this.config.format === 'xml';
+        const accept = wantsXml ? 'application/xml' : 'application/json';
+        let retries429 = 0;
+        let refreshed401 = false;
+        for (;;) {
+            const token = await this.bearer(false);
+            let resp;
+            try {
+                resp = await this.transport.get(url, params, {
+                    Authorization: `Bearer ${token}`,
+                    Accept: accept,
+                });
+            }
+            catch (exc) {
+                throw new errors_js_1.ApiError(0, null, `request to ${path} failed: ${exc.message}`);
+            }
+            const status = resp.status;
+            if (status >= 200 && status < 300) {
+                return this.parseBody(resp, wantsXml);
+            }
+            if (status === 401) {
+                // One refresh-and-retry, then give up as AuthError.
+                if (!refreshed401) {
+                    refreshed401 = true;
+                    await this.bearer(true);
+                    continue;
+                }
+                const { errorKey, message } = await extractError(resp);
+                throw new errors_js_1.AuthError('unauthorized after token refresh' +
+                    (errorKey ? ` [${errorKey}]` : '') +
+                    (message ? `: ${message}` : ''));
+            }
+            if (status === 429) {
+                const retryAfter = parseRetryAfter(resp);
+                if (retries429 < this.maxRetries429) {
+                    retries429 += 1;
+                    await this.sleep(backoffDelay(retryAfter, retries429));
+                    continue;
+                }
+                const { errorKey, message } = await extractError(resp);
+                throw new errors_js_1.RateLimitError(retryAfter, errorKey, message);
+            }
+            // Any other non-2xx → ApiError with the body's error_key.
+            const { errorKey, message } = await extractError(resp);
+            throw new errors_js_1.ApiError(status, errorKey, message);
+        }
+    }
+    url(path) {
+        if (path.startsWith('http://') || path.startsWith('https://')) {
+            return path;
+        }
+        return this.apiUrl + (path.startsWith('/') ? '' : '/') + path;
+    }
+    async parseBody(resp, wantsXml) {
+        const text = await resp.text();
+        if (text === null || text.trim() === '') {
+            return {};
+        }
+        if (wantsXml) {
+            try {
+                return (0, xml_js_1.parseXml)(text);
+            }
+            catch (exc) {
+                throw new errors_js_1.ApiError(resp.status, null, `response was not valid XML: ${exc.message}`);
+            }
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (exc) {
+            throw new errors_js_1.ApiError(resp.status, null, `response was not valid JSON: ${exc.message}`);
+        }
+    }
+}
+exports.HttpClient = HttpClient;
+// ── module-level helpers ─────────────────────────────────────────────────────
+/** Pull `error_key` + a message out of a non-2xx body (JSON or XML). */
+async function extractError(resp) {
+    let text;
+    try {
+        text = await resp.text();
+    }
+    catch {
+        return { errorKey: null, message: null };
+    }
+    let body = null;
+    const trimmed = text.trim();
+    if (trimmed.startsWith('<')) {
+        try {
+            body = (0, xml_js_1.parseXml)(trimmed);
+        }
+        catch {
+            return { errorKey: null, message: trimmed || null };
+        }
+    }
+    else {
+        try {
+            body = JSON.parse(trimmed);
+        }
+        catch {
+            return { errorKey: null, message: trimmed || null };
+        }
+    }
+    if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+        const rec = body;
+        const errorKey = rec['error_key'];
+        const message = rec['error'] ?? rec['message'];
+        return {
+            errorKey: errorKey != null ? String(errorKey) : null,
+            message: message != null ? String(message) : null,
+        };
+    }
+    return { errorKey: null, message: null };
+}
+/** Parse the `Retry-After` header (delta-seconds form) → number of seconds or null. */
+function parseRetryAfter(resp) {
+    const raw = resp.headers.get('Retry-After');
+    if (raw === null)
+        return null;
+    const n = Number(raw.trim());
+    // The platform sends delta-seconds; an HTTP-date form falls back to null
+    // (default backoff). NaN guards the date case.
+    return Number.isFinite(n) ? n : null;
+}
+/** Sleep duration before the next 429 retry: honor Retry-After, else exponential backoff. */
+function backoffDelay(retryAfter, attempt) {
+    if (retryAfter !== null && retryAfter >= 0) {
+        return Math.min(retryAfter, MAX_BACKOFF_S);
+    }
+    return Math.min(DEFAULT_BACKOFF_S * 2 ** (attempt - 1), MAX_BACKOFF_S);
+}