@peable.to/sdk 0.1.1

package/dist/esm/browser/mount.js

@@ -0,0 +1,298 @@
+// `PeableCheckout.mount(...)` — the embeddable "Pay with Peable" button
+// (Fase 2 SDK plan, Task 6). Plain DOM, no framework, so it embeds on any
+// site. Renders a button into the host element, fetches + subscribes to the
+// payment intent via the Task 5 payer client, drives a typed
+// `settled`/`confirming`/`failed`/`error` event emitter, and on click either
+// opens the `peable://pay` deep link (mobile) or shows a QR of it (desktop).
+//
+// Same `./core/*` boundary as `payerClient.ts`: the only import from `./core`
+// is `core/errors.ts`, a pure status-mapper with no service-token/secret
+// machinery, so it carries none of the merchant-authed code out of bounds for
+// this browser bundle.
+import createQrCode from 'qrcode-generator';
+import { createPeableCheckout } from './payerClient.js';
+import { PeableApiError, PeableError, PeableInvalidRequestError } from '../core/errors.js';
+// ---------------------------------------------------------------------------
+// Intent id derivation (pure, unit-tested independently of the DOM).
+// ---------------------------------------------------------------------------
+/**
+ * `pi_` followed by ≥24 lowercase hex chars — the Gateway's payment-intent id
+ * format. Mirrors `INTENT_ID_PATTERN` in the wallet's
+ * `packages/frontend/src/pay/payment-request.ts` byte-for-byte, and matches
+ * what `newId('pi')` in `packages/backend/src/lib/ids.ts` actually mints (12
+ * random bytes → 24 hex chars).
+ */
+const INTENT_ID_PATTERN = /^pi_[0-9a-f]{24,}$/;
+/**
+ * Derive and validate the payment intent id for `mount()`. When `intentId` is
+ * omitted, the id IS the prefix of `clientSecret` before `_secret_`
+ * (`clientSecretFor` in `packages/backend/src/lib/ids.ts` mints
+ * `${id}_secret_<hex>`, so `clientSecret.split('_secret_')[0]` recovers it).
+ * Either way the result must look like a real Gateway-minted id AND
+ * `clientSecret` must actually belong to it — a malformed or mismatched pair
+ * is a caller integration bug, and `mount()` must never render a button
+ * wired to a bogus id.
+ */
+export function deriveIntentId(clientSecret, intentId) {
+    const id = intentId ?? clientSecret.split('_secret_')[0] ?? '';
+    if (!INTENT_ID_PATTERN.test(id)) {
+        throw new PeableInvalidRequestError(`PeableCheckout.mount: invalid or missing payment intent id ("${id}") — ` +
+            'pass `intentId` explicitly or a well-formed `clientSecret`');
+    }
+    if (!clientSecret.startsWith(`${id}_secret_`)) {
+        throw new PeableInvalidRequestError('PeableCheckout.mount: clientSecret does not belong to the given intentId');
+    }
+    return id;
+}
+// ---------------------------------------------------------------------------
+// Deep link (pure, unit-tested independently of the DOM).
+// ---------------------------------------------------------------------------
+/** The `peable://pay` deep-link scheme + host — mirrors `PAYMENT_REQUEST_PREFIX`
+ * in the wallet's `packages/frontend/src/pay/payment-request.ts`. */
+const PAYMENT_REQUEST_PREFIX = 'peable://pay';
+/**
+ * Build an `peable://pay?...` deep link. Param names AND percent-encoding
+ * must match the wallet's parser byte-for-byte
+ * (`packages/frontend/src/pay/payment-request.ts`'s `parseQuery`, which
+ * splits on `&` then `=` and `decodeURIComponent`s each side raw) —
+ * deliberately built by hand with `encodeURIComponent` rather than
+ * `URLSearchParams`, whose `application/x-www-form-urlencoded` encoding
+ * (e.g. space → `+`) is a different scheme than plain `decodeURIComponent`
+ * expects on the other end.
+ */
+export function buildPayDeepLink(params) {
+    const pairs = [
+        ['intent', params.intentId],
+        ['secret', params.clientSecret],
+        ['address', params.address],
+        ['amount', params.amount],
+        ['network', params.network],
+    ];
+    const query = pairs
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+        .join('&');
+    return `${PAYMENT_REQUEST_PREFIX}?${query}`;
+}
+/** Only a phone can plausibly have the Peable wallet app installed to catch
+ * the `peable://` deep link — desktop gets a QR to scan with it instead. */
+const MOBILE_USER_AGENT_PATTERN = /Android|iPhone|iPad|iPod/i;
+export function isMobileUserAgent(userAgent) {
+    return MOBILE_USER_AGENT_PATTERN.test(userAgent);
+}
+/**
+ * A minimal typed pub/sub. The public `on`/`emit` are fully type-checked per
+ * event; the internal `Map` necessarily erases each handler's specific
+ * payload type (it stores handlers for every event key in one collection),
+ * so the single cast at the storage boundary is intentional, not a type-safety
+ * hole — nothing outside this function ever sees the erased type.
+ */
+export function createEmitter() {
+    const handlers = new Map();
+    return {
+        on(event, handler) {
+            const set = handlers.get(event) ?? new Set();
+            set.add(handler);
+            handlers.set(event, set);
+        },
+        emit(event, payload) {
+            const set = handlers.get(event);
+            if (!set)
+                return;
+            for (const handler of set) {
+                handler(payload);
+            }
+        },
+        removeAll() {
+            handlers.clear();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// DOM rendering — exercised only by the real-browser Step 3 check (deferred;
+// see the Task 6 report), not by the headless unit suite.
+// ---------------------------------------------------------------------------
+const BUTTON_CLASS = 'peable-checkout-button';
+const OVERLAY_CLASS = 'peable-checkout-qr-overlay';
+/** Statuses that still accept a payment — everything else disables the button. */
+const PAYABLE_STATUSES = new Set([
+    'created',
+    'awaiting_approval',
+    'approved',
+]);
+function resolveTarget(target) {
+    const element = typeof target === 'string' ? document.querySelector(target) : target;
+    if (!(element instanceof Element)) {
+        throw new PeableInvalidRequestError(typeof target === 'string'
+            ? `PeableCheckout.mount: no element matches selector "${target}"`
+            : 'PeableCheckout.mount: target is not a DOM Element');
+    }
+    return element;
+}
+function renderButton(container) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = BUTTON_CLASS;
+    button.textContent = 'Pay with Peable';
+    button.disabled = true; // enabled once the initial snapshot loads
+    button.style.cssText =
+        'padding:12px 24px;border-radius:8px;border:none;background:#5b21b6;' +
+            'color:#fff;font:600 15px system-ui,sans-serif;cursor:pointer;';
+    container.replaceChildren(button);
+    return button;
+}
+function updateButton(button, intent) {
+    button.disabled = !PAYABLE_STATUSES.has(intent.status);
+    switch (intent.status) {
+        case 'settled':
+            button.textContent = 'Paid';
+            break;
+        case 'confirming':
+            button.textContent = 'Confirming…';
+            break;
+        case 'broadcast':
+            button.textContent = 'Payment received';
+            break;
+        case 'failed':
+        case 'expired':
+        case 'rejected':
+            button.textContent = 'Payment unavailable';
+            break;
+        default:
+            button.textContent = 'Pay with Peable';
+    }
+}
+/**
+ * Show a QR of the deep link for a desktop payer to scan with the wallet
+ * app. `qr.createSvgTag()` is `qrcode-generator`'s own trusted output — a
+ * grid of `<rect>` "modules" encoding `deepLink` as opaque data, never as
+ * literal SVG text — so assigning it via `innerHTML` carries no injection
+ * risk from `deepLink`'s content.
+ */
+function showQrOverlay(deepLink) {
+    const qr = createQrCode(0, 'M'); // type 0 = auto-sized, level M = 15% error correction
+    qr.addData(deepLink);
+    qr.make();
+    const overlay = document.createElement('div');
+    overlay.className = OVERLAY_CLASS;
+    overlay.style.cssText =
+        'position:fixed;inset:0;z-index:2147483647;display:flex;align-items:center;' +
+            'justify-content:center;background:rgba(0,0,0,0.5);';
+    overlay.addEventListener('click', (event) => {
+        if (event.target === overlay)
+            overlay.remove();
+    });
+    const card = document.createElement('div');
+    card.style.cssText =
+        'background:#fff;border-radius:12px;padding:24px;display:flex;' +
+            'flex-direction:column;align-items:center;gap:12px;';
+    card.innerHTML = qr.createSvgTag({ cellSize: 4, margin: 4, scalable: true });
+    const caption = document.createElement('p');
+    caption.textContent = 'Scan with the Peable app';
+    caption.style.cssText = 'margin:0;font:500 14px system-ui,sans-serif;color:#111;';
+    const closeButton = document.createElement('button');
+    closeButton.type = 'button';
+    closeButton.textContent = 'Close';
+    closeButton.style.cssText =
+        'padding:8px 16px;border-radius:6px;border:1px solid #d1d5db;background:#fff;' +
+            'font:500 14px system-ui,sans-serif;cursor:pointer;';
+    closeButton.addEventListener('click', () => overlay.remove());
+    card.append(caption, closeButton);
+    overlay.appendChild(card);
+    document.body.appendChild(overlay);
+}
+function toPeableError(error) {
+    if (error instanceof PeableError)
+        return error;
+    return new PeableApiError(error instanceof Error ? error.message : String(error));
+}
+/**
+ * Render the "Pay with Peable" button into `target` and start tracking the
+ * payment intent. Returns synchronously — before any network call resolves —
+ * so a caller's `.on(...)` registrations (called immediately after `mount()`
+ * returns, in the same synchronous tick) are always in place before the
+ * first `settled`/`confirming`/`failed`/`error` event can fire on the
+ * following microtask.
+ */
+function mount(target, opts) {
+    const element = resolveTarget(target);
+    const intentId = deriveIntentId(opts.clientSecret, opts.intentId);
+    const clientSecret = opts.clientSecret;
+    const emitter = createEmitter();
+    const payerClient = createPeableCheckout({ gatewayUrl: opts.gatewayUrl });
+    const button = renderButton(element);
+    let latestIntent = null;
+    let subscription = null;
+    let destroyed = false;
+    function handleIntentUpdate(intent) {
+        latestIntent = intent;
+        updateButton(button, intent);
+        if (intent.status === 'settled') {
+            emitter.emit('settled', intent);
+        }
+        else if (intent.status === 'confirming') {
+            emitter.emit('confirming', intent);
+        }
+        else if (intent.status === 'failed' ||
+            intent.status === 'expired' ||
+            intent.status === 'rejected') {
+            emitter.emit('failed', intent);
+        }
+    }
+    button.addEventListener('click', () => {
+        if (!latestIntent)
+            return; // initial snapshot hasn't loaded yet
+        const deepLink = buildPayDeepLink({
+            intentId,
+            clientSecret,
+            address: latestIntent.address,
+            amount: latestIntent.amount,
+            network: latestIntent.network,
+        });
+        if (isMobileUserAgent(navigator.userAgent)) {
+            window.location.href = deepLink;
+        }
+        else {
+            showQrOverlay(deepLink);
+        }
+    });
+    // `destroyed` closes a race a caller CAN legitimately hit: calling
+    // `destroy()` while `getPaymentIntent`/`subscribe` is still in flight (e.g.
+    // the host page unmounts the widget immediately). Without this guard, a
+    // subscription created AFTER `destroy()` ran would overwrite `subscription`
+    // (still `null` at destroy time) and never get torn down — a leaked socket
+    // connection for the rest of the tab's life.
+    void payerClient
+        .getPaymentIntent(intentId, clientSecret)
+        .then((intent) => {
+        if (destroyed)
+            return null;
+        handleIntentUpdate(intent);
+        return payerClient.subscribe(intentId, clientSecret, handleIntentUpdate);
+    })
+        .then((sub) => {
+        if (!sub)
+            return;
+        if (destroyed) {
+            sub.unsubscribe();
+            return;
+        }
+        subscription = sub;
+    })
+        .catch((error) => {
+        if (destroyed)
+            return;
+        emitter.emit('error', toPeableError(error));
+    });
+    return {
+        on(event, handler) {
+            emitter.on(event, handler);
+        },
+        destroy() {
+            destroyed = true;
+            subscription?.unsubscribe();
+            emitter.removeAll();
+            button.remove();
+        },
+    };
+}
+export const PeableCheckout = { mount };

package/dist/esm/browser/payerClient.js

@@ -0,0 +1,132 @@
+// The payer-side REST+socket client core — the "./checkout" entry's payer
+// capability (Fase 2 SDK plan, Task 5). Mirrors the wallet's
+// `gateway-client.ts`/`gateway-socket.ts` but standalone: no
+// `@oxyhq/services`/`@oxyhq/core` — this is a third-party browser bundle, so
+// it talks to the Gateway over bare `fetch` + `socket.io-client`.
+//
+// Holds NO service token and NO private key — only a public `client_secret`,
+// the exact payer capability the wallet's own payer path already uses
+// (non-custody invariant). `core/errors.ts` is the one `./core/*` import: it
+// is a pure status-code→`PeableError` mapper with no service-token/secret
+// machinery, so reusing it here (instead of throwing bare `Error`) does not
+// carry any of the merchant-authed code `checkout.ts` warns against into the
+// browser bundle.
+import { io } from 'socket.io-client';
+import { errorFromResponse, PeableApiError, PeableInvalidRequestError } from '../core/errors.js';
+const DEFAULT_GATEWAY_URL = 'https://api.peable.to';
+async function readJsonBody(response) {
+    const text = await response.text();
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Factory for the payer-side client core.
+ */
+export function createPeableCheckout(opts = {}) {
+    const baseUrl = (opts.gatewayUrl ?? DEFAULT_GATEWAY_URL).replace(/\/$/, '');
+    async function getPaymentIntent(id, clientSecret) {
+        let response;
+        try {
+            response = await fetch(`${baseUrl}/v1/payment_intents/${encodeURIComponent(id)}`, {
+                headers: { 'X-Peable-Client-Secret': clientSecret },
+            });
+        }
+        catch (cause) {
+            throw new PeableApiError(`Failed to reach the Peable Gateway at ${baseUrl}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        const body = await readJsonBody(response);
+        if (!response.ok)
+            throw errorFromResponse(response.status, body);
+        return body;
+    }
+    async function submitTx(id, clientSecret, txid) {
+        let response;
+        try {
+            response = await fetch(`${baseUrl}/v1/payment_intents/${encodeURIComponent(id)}/submit_tx`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ client_secret: clientSecret, txid }),
+            });
+        }
+        catch (cause) {
+            throw new PeableApiError(`Failed to reach the Peable Gateway at ${baseUrl}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        const body = await readJsonBody(response);
+        if (!response.ok)
+            throw errorFromResponse(response.status, body);
+        return body;
+    }
+    /**
+     * Opens its OWN socket per call (never a shared/module-level connection —
+     * this SDK has no session to key a singleton off) and connects with NO
+     * handshake auth token: the Gateway's connection auth is identity-optional
+     * (`optionalSocketAuth`, `packages/backend/src/realtime/socket.ts`) exactly
+     * so an anonymous checkout/embed payer can reach it. `subscribe`'s ack is
+     * the real authorization check — it requires this intent's `client_secret`
+     * — so nothing here needs an Oxy session.
+     */
+    async function subscribe(id, clientSecret, onUpdate) {
+        const socket = io(baseUrl, {
+            transports: ['websocket'],
+        });
+        let ack;
+        try {
+            ack = await socket.emitWithAck('subscribe', { intentId: id, clientSecret });
+        }
+        catch (cause) {
+            socket.disconnect();
+            throw new PeableApiError(`Failed to reach the Peable Gateway realtime layer at ${baseUrl}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        if (!ack.ok) {
+            socket.disconnect();
+            // The Gateway's `subscribe` handler returns this SAME {ok:false} for
+            // an unknown intent AND a wrong client_secret (anti-enumeration — see
+            // `realtime/socket.ts`), so this is deliberately InvalidRequestError,
+            // not PermissionError: there is no signal here to tell the two apart.
+            throw new PeableInvalidRequestError(`Gateway rejected subscription to payment intent ${id} ` +
+                '(unknown payment intent or invalid client_secret)');
+        }
+        // The socket only ever carries this one subscription, but filter by id
+        // anyway — matching the wallet's per-intent filter exactly means a future
+        // change there (e.g. a shared connection) can't silently leak another
+        // intent's updates into this caller's `onUpdate`.
+        const listener = (intent) => {
+            if (intent.id === id) {
+                onUpdate(intent);
+            }
+        };
+        socket.on('intent.updated', listener);
+        // socket.io-client's default reconnection restores the TRANSPORT, but the
+        // server spins up a fresh Socket with no room membership — so every
+        // reconnect (mobile network blip, backgrounded tab, LB cycle) must re-run
+        // the room-join handshake or `intent.updated` silently stops arriving for
+        // the rest of the subscription's life. A hosted checkout tab can sit open
+        // unattended for minutes while a payment settles, with no app-lifecycle
+        // trigger to notice and recover — unlike the wallet, this can't rely on
+        // the user reopening the screen. `reconnect` is a Manager-level event
+        // (`socket.io`, not `socket` itself) in socket.io-client.
+        const onReconnect = () => {
+            void socket.emitWithAck('subscribe', { intentId: id, clientSecret }).catch(() => {
+                // Fire-and-forget: `onUpdate` has no error channel to surface a
+                // failed resubscribe (e.g. the intent expired between drop and
+                // reconnect) — socket.io keeps retrying the transport regardless, so
+                // there is nothing actionable to do with this rejection here.
+            });
+        };
+        socket.io.on('reconnect', onReconnect);
+        return {
+            unsubscribe() {
+                socket.off('intent.updated', listener);
+                socket.io.off('reconnect', onReconnect);
+                socket.disconnect();
+            },
+        };
+    }
+    return { getPaymentIntent, subscribe, submitTx };
+}

package/dist/esm/checkout.js

@@ -0,0 +1,12 @@
+// Browser entry (`@peable.to/sdk/checkout`) — the anonymous payer-side client
+// core (Task 5) plus the embeddable pay-button widget (Task 6). Deliberately
+// imports nothing from `./core/*` beyond `core/errors.ts` (a pure
+// status-mapper with no service-token/secret machinery): the browser bundle
+// must never carry the merchant-authed code or a path to a secret.
+//
+// `packages/checkout` (the hosted checkout page, a separate package) can
+// still consume `createPeableCheckout` directly instead of `PeableCheckout`
+// when it wants to build its own UI over the payer client core (see the
+// checkout+links plan's `intentClient.ts`).
+export { createPeableCheckout, } from './browser/payerClient.js';
+export { PeableCheckout, } from './browser/mount.js';

package/dist/esm/core/client.js

@@ -0,0 +1,74 @@
+// `RestClient` — the thin HTTP layer every resource namespace calls through.
+// Prefixes `baseURL`, attaches the bearer service token, sets
+// `Idempotency-Key` when given, serializes query params, parses JSON, and
+// maps every non-2xx response via `errors.ts`.
+import { errorFromResponse, PeableApiError } from './errors.js';
+const HTTP_UNAUTHORIZED = 401;
+function buildUrl(baseURL, path, query) {
+    const search = new URLSearchParams();
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined)
+                continue;
+            search.set(key, String(value));
+        }
+    }
+    const queryString = search.toString();
+    return `${baseURL}${path}${queryString ? `?${queryString}` : ''}`;
+}
+async function readJsonBody(response) {
+    const text = await response.text();
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createRestClient(config, tokenProvider, deps = {}) {
+    const fetchImpl = deps.fetch ?? fetch;
+    async function performRequest(method, path, opts, allowRetryOn401) {
+        const token = await tokenProvider.getToken();
+        const headers = { Authorization: `Bearer ${token}` };
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        if (opts.idempotencyKey !== undefined)
+            headers['Idempotency-Key'] = opts.idempotencyKey;
+        if (opts.headers)
+            Object.assign(headers, opts.headers);
+        let response;
+        try {
+            response = await fetchImpl(buildUrl(config.baseURL, path, opts.query), {
+                method,
+                headers,
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            });
+        }
+        catch (cause) {
+            throw new PeableApiError(`Failed to reach the Peable Gateway at ${config.baseURL}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        // A 401 here means the cached service token expired or was revoked
+        // mid-flight (it was valid when minted, or a prior request would have
+        // failed at `tokenProvider.getToken()` already). Invalidate the cache and
+        // retry exactly once with a freshly minted token before giving up.
+        if (response.status === HTTP_UNAUTHORIZED && allowRetryOn401) {
+            tokenProvider.invalidate();
+            return performRequest(method, path, opts, false);
+        }
+        // The Gateway echoes a date-based `Peable-Version` response header
+        // (Stripe parity). No SDK behavior depends on it yet, so it is
+        // deliberately not read here — nothing to do with it today.
+        const body = await readJsonBody(response);
+        if (!response.ok) {
+            throw errorFromResponse(response.status, body);
+        }
+        return body;
+    }
+    return {
+        request(method, path, opts = {}) {
+            return performRequest(method, path, opts, true);
+        },
+    };
+}

package/dist/esm/core/config.js

@@ -0,0 +1,34 @@
+// Configuration for the server-side `Peable` client. The SDK is configured
+// with a confidential `ApplicationCredential` (`{publicKey, secret}`, the
+// SAME credential Oxy Console already issues for a `type:'service'`
+// credential) — never a bespoke "Peable API key". See the SDK plan's
+// "Architecture / auth" section.
+/** Default Gateway host (`api.peable.to`) — the SDK never sends a `livemode`
+ * flag; the credential's `environment` rides in the minted service JWT and
+ * the Gateway resolves test/live from it. */
+export const DEFAULT_GATEWAY_BASE_URL = 'https://api.peable.to';
+/** Default oxy-api host used to mint the short-lived service token. */
+export const DEFAULT_OXY_API_URL = 'https://api.oxy.so';
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+/**
+ * Validate and normalize an `PeableConfig`. Throws a plain `Error` for a
+ * missing `publicKey`/`secret` — a programmer error caught at construction
+ * time, not an API-response failure, so it deliberately does not go through
+ * the `PeableError` hierarchy (which models mapped HTTP responses).
+ */
+export function resolveConfig(config) {
+    if (!config.publicKey) {
+        throw new Error('Peable: `publicKey` is required');
+    }
+    if (!config.secret) {
+        throw new Error('Peable: `secret` is required');
+    }
+    return {
+        publicKey: config.publicKey,
+        secret: config.secret,
+        baseURL: stripTrailingSlash(config.baseURL ?? DEFAULT_GATEWAY_BASE_URL),
+        oxyApiUrl: stripTrailingSlash(config.oxyApiUrl ?? DEFAULT_OXY_API_URL),
+    };
+}

package/dist/esm/core/errors.js

@@ -0,0 +1,102 @@
+// The `PeableError` hierarchy — every non-2xx Gateway/oxy-api response is
+// mapped into one of these, never a bare `Error` or a raw `Response`.
+export class PeableError extends Error {
+    constructor(type, message, details = {}) {
+        super(message);
+        this.name = 'PeableError';
+        this.type = type;
+        this.statusCode = details.statusCode;
+        this.code = details.code;
+        Object.setPrototypeOf(this, PeableError.prototype);
+    }
+}
+export class PeableAuthenticationError extends PeableError {
+    constructor(message, details = {}) {
+        super('authentication_error', message, details);
+        this.name = 'PeableAuthenticationError';
+        Object.setPrototypeOf(this, PeableAuthenticationError.prototype);
+    }
+}
+export class PeableInvalidRequestError extends PeableError {
+    constructor(message, details = {}) {
+        super('invalid_request_error', message, details);
+        this.name = 'PeableInvalidRequestError';
+        Object.setPrototypeOf(this, PeableInvalidRequestError.prototype);
+    }
+}
+export class PeablePermissionError extends PeableError {
+    constructor(message, details = {}) {
+        super('permission_error', message, details);
+        this.name = 'PeablePermissionError';
+        Object.setPrototypeOf(this, PeablePermissionError.prototype);
+    }
+}
+export class PeableApiError extends PeableError {
+    constructor(message, details = {}) {
+        super('api_error', message, details);
+        this.name = 'PeableApiError';
+        Object.setPrototypeOf(this, PeableApiError.prototype);
+    }
+}
+/** Thrown by `webhooks.constructEvent` on a bad/stale/tampered signature. */
+export class PeableSignatureVerificationError extends PeableError {
+    constructor(message) {
+        super('signature_verification_error', message);
+        this.name = 'PeableSignatureVerificationError';
+        Object.setPrototypeOf(this, PeableSignatureVerificationError.prototype);
+    }
+}
+function isNestedGatewayErrorBody(body) {
+    if (typeof body !== 'object' || body === null || !('error' in body))
+        return false;
+    const { error } = body;
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const nested = error;
+    return typeof nested.type === 'string' && typeof nested.message === 'string';
+}
+function isFlatGatewayErrorBody(body) {
+    if (typeof body !== 'object' || body === null || !('error' in body))
+        return false;
+    const { error } = body;
+    return typeof error === 'string';
+}
+/**
+ * Map an HTTP status + parsed JSON body into a typed `PeableError`.
+ *
+ * The Oxy ecosystem returns TWO distinct error envelopes depending on WHERE a
+ * request was rejected:
+ * - The Gateway's own route handlers use the Stripe-style nested envelope
+ *   `{ error: { type, message } }` (`lib/http.ts`'s `sendError`).
+ * - `@oxyhq/core`'s Express auth middleware (`oxyClient.serviceAuth()` /
+ *   `requireScope()` — rejecting a missing/expired/insufficiently-scoped
+ *   service token BEFORE a route handler ever runs) and oxy-api's own
+ *   `ApiError.toJSON()` use a FLAT envelope: `{ error: <CODE_STRING>,
+ *   message, code? }`.
+ *
+ * A caller of this SDK hits the flat shape on every auth failure (expired
+ * token, missing scope, bad credentials at mint time), so the HTTP status
+ * code — not `error.type` — is the primary classifier here; the raw
+ * upstream `type`/`code` string is still attached to the resulting error
+ * (`.code`) for callers who want it.
+ */
+export function errorFromResponse(status, body) {
+    let upstreamCode;
+    let message = `Peable request failed with status ${status}`;
+    if (isNestedGatewayErrorBody(body)) {
+        upstreamCode = body.error.type;
+        message = body.error.message;
+    }
+    else if (isFlatGatewayErrorBody(body)) {
+        upstreamCode = body.error;
+        message = body.message || message;
+    }
+    const details = { statusCode: status, code: upstreamCode };
+    if (status === 401)
+        return new PeableAuthenticationError(message, details);
+    if (status === 403)
+        return new PeablePermissionError(message, details);
+    if (status >= 400 && status < 500)
+        return new PeableInvalidRequestError(message, details);
+    return new PeableApiError(message, details);
+}