@peable.to/sdk 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,14 @@
+
+### HTTP deadlines and existing operation keys
+
+SDK0.2.1 accepts `requestTimeoutMs` on `new Peable(...)`. It bounds each token
+mint and gateway HTTP attempt, including reading its body. Omitting it preserves
+the previous timeout behavior. A consumer replacing a20s HTTP client should
+pass `requestTimeoutMs: 20_000`. A401 may still trigger the existing single token
+refresh/retry; timeouts and interrupted responses never retry a payment POST.
+The remote outcome may be unknown: recover explicitly with the same durable key.
+
+`paymentIntents.reject`, `refunds.create`, and `transfers.create` now accept an
+optional second `{ idempotencyKey }` argument, forwarding the existing header.
+Refund/transfer `externalRef` remains their durable business identity; the option
+neither replaces it nor changes gateway financial semantics.

package/dist/cjs/core/client.js

@@ -5,6 +5,7 @@
 // maps every non-2xx response via `errors.ts`.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRestClient = createRestClient;
+const config_1 = require("./config");
 const errors_1 = require("./errors");
 const HTTP_UNAUTHORIZED = 401;
 function buildUrl(baseURL, path, query) {
@@ -32,6 +33,7 @@ async function readJsonBody(response) {
 }
 function createRestClient(config, tokenProvider, deps = {}) {
     const fetchImpl = deps.fetch ?? fetch;
+    const timeout = (0, config_1.resolveRequestTimeout)(config.requestTimeoutMs);
     async function performRequest(method, path, opts, allowRetryOn401) {
         const token = await tokenProvider.getToken();
         const headers = { Authorization: `Bearer ${token}` };
@@ -46,6 +48,7 @@ function createRestClient(config, tokenProvider, deps = {}) {
             response = await fetchImpl(buildUrl(config.baseURL, path, opts.query), {
                 method,
                 headers,
+                ...(timeout === undefined ? {} : { signal: AbortSignal.timeout(timeout) }),
                 body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
             });
         }

package/dist/cjs/core/config.js

@@ -6,6 +6,7 @@
 // "Architecture / auth" section.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_OXY_API_URL = exports.DEFAULT_GATEWAY_BASE_URL = void 0;
+exports.resolveRequestTimeout = resolveRequestTimeout;
 exports.resolveConfig = resolveConfig;
 /** Default Gateway host (`api.peable.to`) — the SDK never sends a `livemode`
  * flag; the credential's `environment` rides in the minted service JWT and
@@ -13,6 +14,15 @@ exports.resolveConfig = resolveConfig;
 exports.DEFAULT_GATEWAY_BASE_URL = 'https://api.peable.to';
 /** Default oxy-api host used to mint the short-lived service token. */
 exports.DEFAULT_OXY_API_URL = 'https://api.oxy.so';
+function resolveRequestTimeout(value) {
+    if (value === undefined)
+        return undefined;
+    const timeout = value;
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2147483647) {
+        throw new Error('Peable: requestTimeoutMs must be a positive32-bit integer');
+    }
+    return timeout;
+}
 function stripTrailingSlash(url) {
     return url.endsWith('/') ? url.slice(0, -1) : url;
 }
@@ -30,6 +40,7 @@ function resolveConfig(config) {
         throw new Error('Peable: `secret` is required');
     }
     return {
+        requestTimeoutMs: resolveRequestTimeout(config.requestTimeoutMs),
         publicKey: config.publicKey,
         secret: config.secret,
         baseURL: stripTrailingSlash(config.baseURL ?? exports.DEFAULT_GATEWAY_BASE_URL),

package/dist/cjs/core/serviceToken.js

@@ -43,6 +43,7 @@ function createServiceTokenProvider(cfg, deps = {}) {
         try {
             response = await fetchImpl(`${resolved.oxyApiUrl}${SERVICE_TOKEN_PATH}`, {
                 method: 'POST',
+                ...(resolved.requestTimeoutMs === undefined ? {} : { signal: AbortSignal.timeout(resolved.requestTimeoutMs) }),
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ apiKey: resolved.publicKey, apiSecret: resolved.secret }),
             });
@@ -50,7 +51,15 @@ function createServiceTokenProvider(cfg, deps = {}) {
         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);
+        let body;
+        try {
+            body = await readJsonBody(response);
+        }
+        catch {
+            throw new errors_1.PeableApiError('The Oxy service-token response body could not be read', {
+                statusCode: response.status, code: 'invalid_response',
+            });
+        }
         if (!response.ok) {
             throw (0, errors_1.errorFromResponse)(response.status, body);
         }

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "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;
+exports.WebhooksResource = 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;
 const billing_1 = require("./resources/billing");
 // Server entry (`@peable.to/sdk`) — the merchant-authed SDK. Configured with a
 // confidential `ApplicationCredential` (`{publicKey, secret}`); mints and
@@ -40,7 +40,7 @@ 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);
+        const client = (0, client_1.createRestClient)({ baseURL: resolved.baseURL, requestTimeoutMs: resolved.requestTimeoutMs }, tokenProvider);
         this.billing = new billing_1.BillingResource(client);
         this.paymentIntents = new paymentIntents_1.PaymentIntentsResource(client);
         this.paymentLinks = new paymentLinks_1.PaymentLinksResource(client);
@@ -66,3 +66,4 @@ Object.defineProperty(exports, "PeableApiError", { enumerable: true, get: functi
 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; } });
+Object.defineProperty(exports, "WebhooksResource", { enumerable: true, get: function () { return webhooks_2.WebhooksResource; } });

package/dist/cjs/resources/paymentIntents.js

@@ -32,8 +32,8 @@ class PaymentIntentsResource {
      * and nothing was decided. Neither is a failure of the request — both are
      * facts about a payment that is still live.
      */
-    reject(id) {
-        return this.client.request('POST', `/v1/payment_intents/${encodeURIComponent(id)}/reject`);
+    reject(id, options = {}) {
+        return this.client.request('POST', `/v1/payment_intents/${encodeURIComponent(id)}/reject`, { idempotencyKey: options.idempotencyKey });
     }
     /**
      * What the PAYER's client has to do next — the resume operation.

package/dist/cjs/resources/refunds.js

@@ -18,8 +18,8 @@ class RefundsResource {
      * caller does not need a second read whose answer can move on before it
      * arrives.
      */
-    create(params) {
-        return this.client.request('POST', '/v1/refunds', { body: params });
+    create(params, options = {}) {
+        return this.client.request('POST', '/v1/refunds', { body: params, idempotencyKey: options.idempotencyKey });
     }
     /**
      * What this payment actually came to — gross, fee, net.

package/dist/cjs/resources/transfers.js

@@ -17,8 +17,8 @@ class TransfersResource {
      * would come from the platform's general balance, which is other merchants'
      * money in flight.
      */
-    create(params) {
-        return this.client.request('POST', '/v1/transfers', { body: params });
+    create(params, options = {}) {
+        return this.client.request('POST', '/v1/transfers', { body: params, idempotencyKey: options.idempotencyKey });
     }
     /**
      * Take some or all of a settlement back.

package/dist/cjs/resources/webhooks.js

@@ -7,13 +7,21 @@ const errors_1 = require("../core/errors");
 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',
-];
+// Exhaustive against the published union: adding a backend event makes this
+// fail compilation until the SDK accepts it. Own-key lookup excludes prototype
+// names supplied by an untrusted, even correctly signed, payload.
+const WEBHOOK_EVENT_TYPES = {
+    'payment_intent.confirming': true,
+    'payment_intent.settled': true,
+    'payment_intent.failed': true,
+    'payment_intent.rejected': true,
+    'payment_intent.expired': true,
+    'payment_intent.refunded': true,
+    'payment_intent.partially_refunded': true,
+    'payment_intent.disputed': true,
+    'payment_intent.dispute_closed': true,
+    'connected_account.updated': true,
+};
 /**
  * Structural guard for the parsed payload — the signature already proves the
  * bytes were produced by `signWebhook` on the SAME secret, but a caller could
@@ -27,7 +35,7 @@ function isWebhookEventShape(value) {
     return (typeof candidate.id === 'string' &&
         candidate.object === 'event' &&
         typeof candidate.type === 'string' &&
-        WEBHOOK_EVENT_TYPES.includes(candidate.type) &&
+        Object.prototype.hasOwnProperty.call(WEBHOOK_EVENT_TYPES, candidate.type) &&
         typeof candidate.created === 'string' &&
         typeof candidate.data === 'object' &&
         candidate.data !== null &&

package/dist/esm/core/client.js

@@ -2,6 +2,7 @@
 // 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 { resolveRequestTimeout } from './config.js';
 import { errorFromResponse, PeableApiError } from './errors.js';
 const HTTP_UNAUTHORIZED = 401;
 function buildUrl(baseURL, path, query) {
@@ -29,6 +30,7 @@ async function readJsonBody(response) {
 }
 export function createRestClient(config, tokenProvider, deps = {}) {
     const fetchImpl = deps.fetch ?? fetch;
+    const timeout = resolveRequestTimeout(config.requestTimeoutMs);
     async function performRequest(method, path, opts, allowRetryOn401) {
         const token = await tokenProvider.getToken();
         const headers = { Authorization: `Bearer ${token}` };
@@ -43,6 +45,7 @@ export function createRestClient(config, tokenProvider, deps = {}) {
             response = await fetchImpl(buildUrl(config.baseURL, path, opts.query), {
                 method,
                 headers,
+                ...(timeout === undefined ? {} : { signal: AbortSignal.timeout(timeout) }),
                 body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
             });
         }

package/dist/esm/core/config.js

@@ -9,6 +9,15 @@
 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';
+export function resolveRequestTimeout(value) {
+    if (value === undefined)
+        return undefined;
+    const timeout = value;
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2147483647) {
+        throw new Error('Peable: requestTimeoutMs must be a positive32-bit integer');
+    }
+    return timeout;
+}
 function stripTrailingSlash(url) {
     return url.endsWith('/') ? url.slice(0, -1) : url;
 }
@@ -26,6 +35,7 @@ export function resolveConfig(config) {
         throw new Error('Peable: `secret` is required');
     }
     return {
+        requestTimeoutMs: resolveRequestTimeout(config.requestTimeoutMs),
         publicKey: config.publicKey,
         secret: config.secret,
         baseURL: stripTrailingSlash(config.baseURL ?? DEFAULT_GATEWAY_BASE_URL),

package/dist/esm/core/serviceToken.js

@@ -40,6 +40,7 @@ export function createServiceTokenProvider(cfg, deps = {}) {
         try {
             response = await fetchImpl(`${resolved.oxyApiUrl}${SERVICE_TOKEN_PATH}`, {
                 method: 'POST',
+                ...(resolved.requestTimeoutMs === undefined ? {} : { signal: AbortSignal.timeout(resolved.requestTimeoutMs) }),
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ apiKey: resolved.publicKey, apiSecret: resolved.secret }),
             });
@@ -47,7 +48,15 @@ export function createServiceTokenProvider(cfg, deps = {}) {
         catch (cause) {
             throw new PeableApiError(`Failed to reach ${resolved.oxyApiUrl} to mint an Peable service token: ${cause instanceof Error ? cause.message : String(cause)}`);
         }
-        const body = await readJsonBody(response);
+        let body;
+        try {
+            body = await readJsonBody(response);
+        }
+        catch {
+            throw new PeableApiError('The Oxy service-token response body could not be read', {
+                statusCode: response.status, code: 'invalid_response',
+            });
+        }
         if (!response.ok) {
             throw errorFromResponse(response.status, body);
         }

package/dist/esm/index.js

@@ -37,7 +37,7 @@ export class Peable {
     constructor(config) {
         const resolved = resolveConfig(config);
         const tokenProvider = createServiceTokenProvider(config);
-        const client = createRestClient({ baseURL: resolved.baseURL }, tokenProvider);
+        const client = createRestClient({ baseURL: resolved.baseURL, requestTimeoutMs: resolved.requestTimeoutMs }, tokenProvider);
         this.billing = new BillingResource(client);
         this.paymentIntents = new PaymentIntentsResource(client);
         this.paymentLinks = new PaymentLinksResource(client);
@@ -52,4 +52,4 @@ export class Peable {
 }
 export { DEFAULT_GATEWAY_BASE_URL, DEFAULT_OXY_API_URL } from './core/config.js';
 export { PeableError, PeableAuthenticationError, PeableInvalidRequestError, PeablePermissionError, PeableApiError, PeableSignatureVerificationError, } from './core/errors.js';
-export { WEBHOOK_SIGNATURE_HEADER } from './resources/webhooks.js';
+export { WEBHOOK_SIGNATURE_HEADER, WebhooksResource } from './resources/webhooks.js';

package/dist/esm/resources/paymentIntents.js

@@ -29,8 +29,8 @@ export class PaymentIntentsResource {
      * and nothing was decided. Neither is a failure of the request — both are
      * facts about a payment that is still live.
      */
-    reject(id) {
-        return this.client.request('POST', `/v1/payment_intents/${encodeURIComponent(id)}/reject`);
+    reject(id, options = {}) {
+        return this.client.request('POST', `/v1/payment_intents/${encodeURIComponent(id)}/reject`, { idempotencyKey: options.idempotencyKey });
     }
     /**
      * What the PAYER's client has to do next — the resume operation.

package/dist/esm/resources/refunds.js

@@ -15,8 +15,8 @@ export class RefundsResource {
      * caller does not need a second read whose answer can move on before it
      * arrives.
      */
-    create(params) {
-        return this.client.request('POST', '/v1/refunds', { body: params });
+    create(params, options = {}) {
+        return this.client.request('POST', '/v1/refunds', { body: params, idempotencyKey: options.idempotencyKey });
     }
     /**
      * What this payment actually came to — gross, fee, net.

package/dist/esm/resources/transfers.js

@@ -14,8 +14,8 @@ export class TransfersResource {
      * would come from the platform's general balance, which is other merchants'
      * money in flight.
      */
-    create(params) {
-        return this.client.request('POST', '/v1/transfers', { body: params });
+    create(params, options = {}) {
+        return this.client.request('POST', '/v1/transfers', { body: params, idempotencyKey: options.idempotencyKey });
     }
     /**
      * Take some or all of a settlement back.

package/dist/esm/resources/webhooks.js

@@ -4,13 +4,21 @@ import { PeableSignatureVerificationError } from '../core/errors.js';
 export const 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',
-];
+// Exhaustive against the published union: adding a backend event makes this
+// fail compilation until the SDK accepts it. Own-key lookup excludes prototype
+// names supplied by an untrusted, even correctly signed, payload.
+const WEBHOOK_EVENT_TYPES = {
+    'payment_intent.confirming': true,
+    'payment_intent.settled': true,
+    'payment_intent.failed': true,
+    'payment_intent.rejected': true,
+    'payment_intent.expired': true,
+    'payment_intent.refunded': true,
+    'payment_intent.partially_refunded': true,
+    'payment_intent.disputed': true,
+    'payment_intent.dispute_closed': true,
+    'connected_account.updated': true,
+};
 /**
  * Structural guard for the parsed payload — the signature already proves the
  * bytes were produced by `signWebhook` on the SAME secret, but a caller could
@@ -24,7 +32,7 @@ function isWebhookEventShape(value) {
     return (typeof candidate.id === 'string' &&
         candidate.object === 'event' &&
         typeof candidate.type === 'string' &&
-        WEBHOOK_EVENT_TYPES.includes(candidate.type) &&
+        Object.prototype.hasOwnProperty.call(WEBHOOK_EVENT_TYPES, candidate.type) &&
         typeof candidate.created === 'string' &&
         typeof candidate.data === 'object' &&
         candidate.data !== null &&

package/dist/types/core/client.d.ts

@@ -11,6 +11,7 @@ export interface RestClient {
 export interface RestClientConfig {
     /** Gateway base URL, already stripped of a trailing slash. */
     baseURL: string;
+    requestTimeoutMs?: number;
 }
 export declare function createRestClient(config: RestClientConfig, tokenProvider: ServiceTokenProvider, deps?: {
     fetch?: typeof fetch;

package/dist/types/core/config.d.ts

@@ -13,6 +13,8 @@ export interface PeableConfig {
     baseURL?: string;
     /** oxy-api host used to mint the service token. Default `https://api.oxy.so`. */
     oxyApiUrl?: string;
+    /** Optional deadline per HTTP attempt, including body consumption. */
+    requestTimeoutMs?: number;
 }
 /** `PeableConfig` with every optional field defaulted and normalized. */
 export interface ResolvedPeableConfig {
@@ -20,7 +22,9 @@ export interface ResolvedPeableConfig {
     secret: string;
     baseURL: string;
     oxyApiUrl: string;
+    requestTimeoutMs?: number;
 }
+export declare function resolveRequestTimeout(value: number | undefined): number | undefined;
 /**
  * Validate and normalize an `PeableConfig`. Throws a plain `Error` for a
  * missing `publicKey`/`secret` — a programmer error caught at construction

package/dist/types/index.d.ts

@@ -57,5 +57,5 @@ export type { DisputeEvidenceParams, DisputeList, RegisterMerchantParams, Update
 export type { CreateRefundParams, RefundList } from './resources/refunds';
 export type { CreateTransferParams, ReverseTransferParams, TransferList, } from './resources/transfers';
 export type { PaymentLinkListParams, PaymentLinkList, UpdatePaymentLinkParams, } from './resources/paymentLinks';
-export { WEBHOOK_SIGNATURE_HEADER } from './resources/webhooks';
+export { WEBHOOK_SIGNATURE_HEADER, WebhooksResource } from './resources/webhooks';
 export type { ConstructEventOptions } from './resources/webhooks';

package/dist/types/resources/paymentIntents.d.ts

@@ -52,7 +52,9 @@ export declare class PaymentIntentsResource {
      * and nothing was decided. Neither is a failure of the request — both are
      * facts about a payment that is still live.
      */
-    reject(id: string): Promise<PaymentIntent>;
+    reject(id: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<PaymentIntent>;
     /**
      * What the PAYER's client has to do next — the resume operation.
      *

package/dist/types/resources/refunds.d.ts

@@ -46,7 +46,9 @@ export declare class RefundsResource {
      * caller does not need a second read whose answer can move on before it
      * arrives.
      */
-    create(params: CreateRefundParams): Promise<Refund>;
+    create(params: CreateRefundParams, options?: {
+        idempotencyKey?: string;
+    }): Promise<Refund>;
     /**
      * What this payment actually came to — gross, fee, net.
      *

package/dist/types/resources/transfers.d.ts

@@ -57,7 +57,9 @@ export declare class TransfersResource {
      * would come from the platform's general balance, which is other merchants'
      * money in flight.
      */
-    create(params: CreateTransferParams): Promise<Transfer>;
+    create(params: CreateTransferParams, options?: {
+        idempotencyKey?: string;
+    }): Promise<Transfer>;
     /**
      * Take some or all of a settlement back.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Peable SDK — a Stripe-ergonomics TypeScript client over the Peable Gateway REST + realtime contract. Server entry (`@peable.to/sdk`) mints Oxy service tokens from an ApplicationCredential and exposes paymentIntents/paymentLinks/checkout.sessions/webhooks; browser entry (`@peable.to/sdk/checkout`) is the anonymous payer-side client core.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",