@peable.to/sdk 0.1.1

package/dist/cjs/core/errors.js

@@ -0,0 +1,112 @@
+"use strict";
+// The `PeableError` hierarchy — every non-2xx Gateway/oxy-api response is
+// mapped into one of these, never a bare `Error` or a raw `Response`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PeableSignatureVerificationError = exports.PeableApiError = exports.PeablePermissionError = exports.PeableInvalidRequestError = exports.PeableAuthenticationError = exports.PeableError = void 0;
+exports.errorFromResponse = errorFromResponse;
+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);
+    }
+}
+exports.PeableError = PeableError;
+class PeableAuthenticationError extends PeableError {
+    constructor(message, details = {}) {
+        super('authentication_error', message, details);
+        this.name = 'PeableAuthenticationError';
+        Object.setPrototypeOf(this, PeableAuthenticationError.prototype);
+    }
+}
+exports.PeableAuthenticationError = PeableAuthenticationError;
+class PeableInvalidRequestError extends PeableError {
+    constructor(message, details = {}) {
+        super('invalid_request_error', message, details);
+        this.name = 'PeableInvalidRequestError';
+        Object.setPrototypeOf(this, PeableInvalidRequestError.prototype);
+    }
+}
+exports.PeableInvalidRequestError = PeableInvalidRequestError;
+class PeablePermissionError extends PeableError {
+    constructor(message, details = {}) {
+        super('permission_error', message, details);
+        this.name = 'PeablePermissionError';
+        Object.setPrototypeOf(this, PeablePermissionError.prototype);
+    }
+}
+exports.PeablePermissionError = PeablePermissionError;
+class PeableApiError extends PeableError {
+    constructor(message, details = {}) {
+        super('api_error', message, details);
+        this.name = 'PeableApiError';
+        Object.setPrototypeOf(this, PeableApiError.prototype);
+    }
+}
+exports.PeableApiError = PeableApiError;
+/** Thrown by `webhooks.constructEvent` on a bad/stale/tampered signature. */
+class PeableSignatureVerificationError extends PeableError {
+    constructor(message) {
+        super('signature_verification_error', message);
+        this.name = 'PeableSignatureVerificationError';
+        Object.setPrototypeOf(this, PeableSignatureVerificationError.prototype);
+    }
+}
+exports.PeableSignatureVerificationError = PeableSignatureVerificationError;
+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.
+ */
+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);
+}

package/dist/cjs/core/serviceToken.js

@@ -0,0 +1,81 @@
+"use strict";
+// Mints a short-lived Oxy service token from an `ApplicationCredential`
+// (`{publicKey, secret}`) by presenting it to oxy-api's `POST
+// /auth/service-token` — the exact mechanism `oxyClient.serviceAuth()`
+// validates at the Gateway. Caches the token until near expiry and re-mints
+// reactively when `RestClient` sees a 401 (see `client.ts`).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServiceTokenProvider = createServiceTokenProvider;
+const config_1 = require("./config");
+const errors_1 = require("./errors");
+/** Path (relative to `oxyApiUrl`) of oxy-api's service-token mint endpoint. */
+const SERVICE_TOKEN_PATH = '/auth/service-token';
+/** Refresh proactively this long before the minted token's actual expiry. */
+const REFRESH_MARGIN_MS = 60000;
+function isServiceTokenMintEnvelope(body) {
+    if (typeof body !== 'object' || body === null || !('data' in body))
+        return false;
+    const { data } = body;
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const candidate = data;
+    return typeof candidate.token === 'string' && typeof candidate.expiresIn === 'number';
+}
+async function readJsonBody(response) {
+    const text = await response.text();
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function createServiceTokenProvider(cfg, deps = {}) {
+    const resolved = (0, config_1.resolveConfig)(cfg);
+    const fetchImpl = deps.fetch ?? fetch;
+    let cachedToken = null;
+    let cachedExpiresAt = 0;
+    let inflight = null;
+    async function mint() {
+        let response;
+        try {
+            response = await fetchImpl(`${resolved.oxyApiUrl}${SERVICE_TOKEN_PATH}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ apiKey: resolved.publicKey, apiSecret: resolved.secret }),
+            });
+        }
+        catch (cause) {
+            throw new errors_1.PeableApiError(`Failed to reach ${resolved.oxyApiUrl} to mint an Peable service token: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        const body = await readJsonBody(response);
+        if (!response.ok) {
+            throw (0, errors_1.errorFromResponse)(response.status, body);
+        }
+        if (!isServiceTokenMintEnvelope(body)) {
+            throw new errors_1.PeableApiError('Peable: the service-token mint response was missing `data.token`/`data.expiresIn`');
+        }
+        cachedToken = body.data.token;
+        cachedExpiresAt = Date.now() + body.data.expiresIn * 1000;
+        return cachedToken;
+    }
+    return {
+        async getToken() {
+            if (cachedToken !== null && Date.now() < cachedExpiresAt - REFRESH_MARGIN_MS) {
+                return cachedToken;
+            }
+            if (inflight === null) {
+                inflight = mint().finally(() => {
+                    inflight = null;
+                });
+            }
+            return inflight;
+        },
+        invalidate() {
+            cachedToken = null;
+            cachedExpiresAt = 0;
+        },
+    };
+}

package/dist/cjs/index.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_SIGNATURE_HEADER = exports.PeableSignatureVerificationError = exports.PeableApiError = exports.PeablePermissionError = exports.PeableInvalidRequestError = exports.PeableAuthenticationError = exports.PeableError = exports.DEFAULT_OXY_API_URL = exports.DEFAULT_GATEWAY_BASE_URL = exports.Peable = void 0;
+// Server entry (`@peable.to/sdk`) — the merchant-authed SDK. Configured with a
+// confidential `ApplicationCredential` (`{publicKey, secret}`); mints and
+// caches an Oxy service token, and exposes Stripe-ergonomics resource
+// namespaces over the Gateway REST contract.
+//
+// Deliberately never imports `socket.io-client` or `./browser/*` — the
+// server bundle stays lean and holds no browser-only code.
+const config_1 = require("./core/config");
+const serviceToken_1 = require("./core/serviceToken");
+const client_1 = require("./core/client");
+const paymentIntents_1 = require("./resources/paymentIntents");
+const paymentLinks_1 = require("./resources/paymentLinks");
+const checkoutSessions_1 = require("./resources/checkoutSessions");
+const webhooks_1 = require("./resources/webhooks");
+class Peable {
+    constructor(config) {
+        const resolved = (0, config_1.resolveConfig)(config);
+        const tokenProvider = (0, serviceToken_1.createServiceTokenProvider)(config);
+        const client = (0, client_1.createRestClient)({ baseURL: resolved.baseURL }, tokenProvider);
+        this.paymentIntents = new paymentIntents_1.PaymentIntentsResource(client);
+        this.paymentLinks = new paymentLinks_1.PaymentLinksResource(client);
+        this.checkout = new checkoutSessions_1.CheckoutResource(client);
+        this.webhooks = new webhooks_1.WebhooksResource();
+    }
+}
+exports.Peable = Peable;
+var config_2 = require("./core/config");
+Object.defineProperty(exports, "DEFAULT_GATEWAY_BASE_URL", { enumerable: true, get: function () { return config_2.DEFAULT_GATEWAY_BASE_URL; } });
+Object.defineProperty(exports, "DEFAULT_OXY_API_URL", { enumerable: true, get: function () { return config_2.DEFAULT_OXY_API_URL; } });
+var errors_1 = require("./core/errors");
+Object.defineProperty(exports, "PeableError", { enumerable: true, get: function () { return errors_1.PeableError; } });
+Object.defineProperty(exports, "PeableAuthenticationError", { enumerable: true, get: function () { return errors_1.PeableAuthenticationError; } });
+Object.defineProperty(exports, "PeableInvalidRequestError", { enumerable: true, get: function () { return errors_1.PeableInvalidRequestError; } });
+Object.defineProperty(exports, "PeablePermissionError", { enumerable: true, get: function () { return errors_1.PeablePermissionError; } });
+Object.defineProperty(exports, "PeableApiError", { enumerable: true, get: function () { return errors_1.PeableApiError; } });
+Object.defineProperty(exports, "PeableSignatureVerificationError", { enumerable: true, get: function () { return errors_1.PeableSignatureVerificationError; } });
+var webhooks_2 = require("./resources/webhooks");
+Object.defineProperty(exports, "WEBHOOK_SIGNATURE_HEADER", { enumerable: true, get: function () { return webhooks_2.WEBHOOK_SIGNATURE_HEADER; } });

package/dist/cjs/resources/checkoutSessions.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckoutResource = exports.CheckoutSessionsResource = void 0;
+class CheckoutSessionsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    create(params) {
+        return this.client.request('POST', '/v1/checkout_sessions', {
+            body: params,
+        });
+    }
+    retrieve(id) {
+        return this.client.request('GET', `/v1/checkout_sessions/${encodeURIComponent(id)}`);
+    }
+}
+exports.CheckoutSessionsResource = CheckoutSessionsResource;
+/** `peable.checkout.sessions.*` — a thin namespace wrapper so the public API
+ * reads `peable.checkout.sessions.create(...)` (Stripe Checkout Session
+ * parity), leaving room for future `peable.checkout.*` resources. */
+class CheckoutResource {
+    constructor(client) {
+        this.sessions = new CheckoutSessionsResource(client);
+    }
+}
+exports.CheckoutResource = CheckoutResource;

package/dist/cjs/resources/paymentIntents.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentIntentsResource = void 0;
+class PaymentIntentsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    create(params, options) {
+        return this.client.request('POST', '/v1/payment_intents', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
+    }
+    retrieve(id) {
+        return this.client.request('GET', `/v1/payment_intents/${encodeURIComponent(id)}`);
+    }
+    list(params = {}) {
+        return this.client.request('GET', '/v1/payment_intents', {
+            query: {
+                status: params.status,
+                limit: params.limit,
+                starting_after: params.starting_after,
+            },
+        });
+    }
+    reject(id) {
+        return this.client.request('POST', `/v1/payment_intents/${encodeURIComponent(id)}/reject`);
+    }
+}
+exports.PaymentIntentsResource = PaymentIntentsResource;

package/dist/cjs/resources/paymentLinks.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentLinksResource = void 0;
+class PaymentLinksResource {
+    constructor(client) {
+        this.client = client;
+    }
+    create(params) {
+        return this.client.request('POST', '/v1/payment_links', { body: params });
+    }
+    retrieve(id) {
+        return this.client.request('GET', `/v1/payment_links/${encodeURIComponent(id)}`);
+    }
+    list(params = {}) {
+        return this.client.request('GET', '/v1/payment_links', {
+            query: { limit: params.limit, starting_after: params.starting_after },
+        });
+    }
+    update(id, params) {
+        return this.client.request('PATCH', `/v1/payment_links/${encodeURIComponent(id)}`, { body: params });
+    }
+}
+exports.PaymentLinksResource = PaymentLinksResource;

package/dist/cjs/resources/webhooks.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhooksResource = exports.WEBHOOK_SIGNATURE_HEADER = void 0;
+const shared_types_1 = require("@peable.to/shared-types");
+const errors_1 = require("../core/errors");
+/** Header the Gateway's `webhookDispatcher.deliver` signs with (`Peable-Signature`). */
+exports.WEBHOOK_SIGNATURE_HEADER = 'Peable-Signature';
+/** Default replay-tolerance window, matching the backend's own tests/usage. */
+const DEFAULT_TOLERANCE_SEC = 300;
+const WEBHOOK_EVENT_TYPES = [
+    'payment_intent.confirming',
+    'payment_intent.settled',
+    'payment_intent.failed',
+    'payment_intent.rejected',
+    'payment_intent.expired',
+];
+/**
+ * Structural guard for the parsed payload — the signature already proves the
+ * bytes were produced by `signWebhook` on the SAME secret, but a caller could
+ * still pass an unrelated (validly HMAC'd under a shared secret) JSON blob;
+ * this keeps `constructEvent`'s return type honest rather than a blind cast.
+ */
+function isWebhookEventShape(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.id === 'string' &&
+        candidate.object === 'event' &&
+        typeof candidate.type === 'string' &&
+        WEBHOOK_EVENT_TYPES.includes(candidate.type) &&
+        typeof candidate.created === 'string' &&
+        typeof candidate.data === 'object' &&
+        candidate.data !== null &&
+        'object' in candidate.data);
+}
+class WebhooksResource {
+    /**
+     * Verify a webhook delivery and parse it into a typed `WebhookEvent`.
+     * Verifies via the SAME `verifyWebhook` the Gateway signs with
+     * (`@peable.to/shared-types`) so the algorithm can never drift between the two
+     * sides. Throws `PeableSignatureVerificationError` on a bad/stale/tampered
+     * signature or a malformed payload — never returns a partially-trusted
+     * event.
+     */
+    constructEvent(rawBody, signatureHeader, endpointSecret, opts = {}) {
+        const toleranceSec = opts.toleranceSec ?? DEFAULT_TOLERANCE_SEC;
+        const nowSec = Math.floor(Date.now() / 1000);
+        const verified = (0, shared_types_1.verifyWebhook)(endpointSecret, rawBody, signatureHeader, toleranceSec, nowSec);
+        if (!verified) {
+            throw new errors_1.PeableSignatureVerificationError('Webhook signature verification failed — the payload, signature header, or secret do not match, or the timestamp is stale.');
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(rawBody);
+        }
+        catch {
+            throw new errors_1.PeableSignatureVerificationError('Webhook signature verified, but the payload is not valid JSON');
+        }
+        if (!isWebhookEventShape(parsed)) {
+            throw new errors_1.PeableSignatureVerificationError('Webhook signature verified, but the payload does not match the expected event shape');
+        }
+        return parsed;
+    }
+}
+exports.WebhooksResource = WebhooksResource;