@peable.to/sdk 0.2.3-oxy-one.0 → 0.2.5-oxy-one.0

package/README.md

@@ -1,3 +1,13 @@
+### Authenticating without a key pair
+
+SDK 0.2.5-oxy-one.0 accepts `tokenProvider: { getToken(), invalidate() }` on
+`new Peable(...)` in place of `publicKey` + `secret`, for a workload that already
+holds an Oxy identity (workload identity, for instance) and so has no
+ApplicationCredential to hand over. The SDK then mints nothing: every Gateway
+request carries `getToken()`'s result as the bearer, and a 401 calls
+`invalidate()` before the one existing retry. Passing both, or neither, throws at
+construction. The credential path is unchanged.
+
 
 ### HTTP deadlines and existing operation keys
 

package/dist/cjs/core/config.js

@@ -1,9 +1,15 @@
 "use strict";
-// 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.
+// Configuration for the server-side `Peable` client. The SDK authenticates with
+// an Oxy service token, obtained one of two ways:
+//
+// - a confidential `ApplicationCredential` (`{publicKey, secret}`, the SAME
+//   credential Oxy Console already issues for a `type:'service'` credential) —
+//   never a bespoke "Peable API key" — from which the SDK mints the token
+//   itself. See the SDK plan's "Architecture / auth" section; or
+// - a caller-supplied `tokenProvider`, for a workload that already holds an Oxy
+//   identity (e.g. an ECS task role attested through workload identity) and
+//   has no key pair to hand over. The Gateway resolves the merchant from the
+//   token's application id and environment, not from how it was minted.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_OXY_API_URL = exports.DEFAULT_GATEWAY_BASE_URL = void 0;
 exports.resolveRequestTimeout = resolveRequestTimeout;
@@ -26,24 +32,47 @@ function resolveRequestTimeout(value) {
 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).
- */
+function isServiceTokenProvider(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.getToken === 'function' && typeof candidate.invalidate === 'function';
+}
 function resolveConfig(config) {
-    if (!config.publicKey) {
-        throw new Error('Peable: `publicKey` is required');
+    // Read loosely: a JavaScript caller is not held to the union, and "both" is
+    // exactly the shape the types forbid.
+    const { tokenProvider, publicKey, secret } = config;
+    if (tokenProvider !== undefined) {
+        if (publicKey !== undefined || secret !== undefined) {
+            throw new Error('Peable: pass either `tokenProvider` or `publicKey` + `secret`, not both');
+        }
+        if (!isServiceTokenProvider(tokenProvider)) {
+            throw new Error('Peable: `tokenProvider` must have `getToken()` and `invalidate()`');
+        }
     }
-    if (!config.secret) {
-        throw new Error('Peable: `secret` is required');
+    else {
+        if (publicKey === undefined && secret === undefined) {
+            throw new Error('Peable: either `publicKey` + `secret` or a `tokenProvider` is required');
+        }
+        if (!config.publicKey) {
+            throw new Error('Peable: `publicKey` is required');
+        }
+        if (!config.secret) {
+            throw new Error('Peable: `secret` is required');
+        }
     }
-    return {
+    const options = {
         requestTimeoutMs: resolveRequestTimeout(config.requestTimeoutMs),
-        publicKey: config.publicKey,
-        secret: config.secret,
+        taxQuoteAuthorityKeys: config.taxQuoteAuthorityKeys
+            ? Object.freeze({ ...config.taxQuoteAuthorityKeys })
+            : undefined,
+        invoiceAuthorityKeys: config.invoiceAuthorityKeys
+            ? Object.freeze({ ...config.invoiceAuthorityKeys })
+            : undefined,
         baseURL: stripTrailingSlash(config.baseURL ?? exports.DEFAULT_GATEWAY_BASE_URL),
         oxyApiUrl: stripTrailingSlash(config.oxyApiUrl ?? exports.DEFAULT_OXY_API_URL),
     };
+    return config.tokenProvider !== undefined
+        ? { ...options, tokenProvider: config.tokenProvider }
+        : { ...options, publicKey: config.publicKey, secret: config.secret };
 }

package/dist/cjs/core/serviceToken.js

@@ -43,7 +43,9 @@ function createServiceTokenProvider(cfg, deps = {}) {
         try {
             response = await fetchImpl(`${resolved.oxyApiUrl}${SERVICE_TOKEN_PATH}`, {
                 method: 'POST',
-                ...(resolved.requestTimeoutMs === undefined ? {} : { signal: AbortSignal.timeout(resolved.requestTimeoutMs) }),
+                ...(resolved.requestTimeoutMs === undefined
+                    ? {}
+                    : { signal: AbortSignal.timeout(resolved.requestTimeoutMs) }),
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ apiKey: resolved.publicKey, apiSecret: resolved.secret }),
             });
@@ -57,7 +59,8 @@ function createServiceTokenProvider(cfg, deps = {}) {
         }
         catch {
             throw new errors_1.PeableApiError('The Oxy service-token response body could not be read', {
-                statusCode: response.status, code: 'invalid_response',
+                statusCode: response.status,
+                code: 'invalid_response',
             });
         }
         if (!response.ok) {

package/dist/cjs/index.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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
-// caches an Oxy service token, and exposes Stripe-ergonomics resource
+// confidential `ApplicationCredential` (`{publicKey, secret}`), from which it
+// mints and caches an Oxy service token, or with a caller-supplied
+// `tokenProvider` that already holds one; exposes Stripe-ergonomics resource
 // namespaces over the Gateway REST contract.
 //
 // Deliberately never imports `socket.io-client` or `./browser/*` — the
@@ -39,9 +40,11 @@ const transfers_1 = require("./resources/transfers");
 class Peable {
     constructor(config) {
         const resolved = (0, config_1.resolveConfig)(config);
-        const tokenProvider = (0, serviceToken_1.createServiceTokenProvider)(config);
+        const tokenProvider = config.tokenProvider !== undefined
+            ? config.tokenProvider
+            : (0, serviceToken_1.createServiceTokenProvider)(config);
         const client = (0, client_1.createRestClient)({ baseURL: resolved.baseURL, requestTimeoutMs: resolved.requestTimeoutMs }, tokenProvider);
-        this.billing = new billing_1.BillingResource(client);
+        this.billing = new billing_1.BillingResource(client, resolved.invoiceAuthorityKeys, resolved.taxQuoteAuthorityKeys);
         this.paymentIntents = new paymentIntents_1.PaymentIntentsResource(client);
         this.paymentLinks = new paymentLinks_1.PaymentLinksResource(client);
         this.checkout = new checkoutSessions_1.CheckoutResource(client);

package/dist/cjs/resources/billing.js

@@ -1,23 +1,112 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BillingResource = void 0;
+const node_crypto_1 = require("node:crypto");
+const shared_types_1 = require("@peable.to/shared-types");
 /** Recurring billing is separate from one-off checkout and marketplace transfers. */
 class BillingResource {
-    constructor(client) {
+    constructor(client, invoiceAuthorityKeys, taxQuoteAuthorityKeys) {
         this.client = client;
+        this.invoiceAuthorityKeys = invoiceAuthorityKeys;
+        this.taxQuoteAuthorityKeys = taxQuoteAuthorityKeys;
     }
     ensureCustomer(params, options) {
-        return this.client.request('POST', '/v1/billing/customers', { body: params, idempotencyKey: options.idempotencyKey });
+        return this.client.request('POST', '/v1/billing/customers', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
     }
     createCheckoutSession(params, options) {
-        return this.client.request('POST', '/v1/billing/checkout_sessions', { body: params, idempotencyKey: options.idempotencyKey });
+        return this.client.request('POST', '/v1/billing/checkout_sessions', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
     }
     createPortalSession(params, options) {
-        return this.client.request('POST', '/v1/billing/portal_sessions', { body: params, idempotencyKey: options.idempotencyKey });
+        return this.client.request('POST', '/v1/billing/portal_sessions', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
+    }
+    retrieveCheckout(ref) {
+        return this.client.request('GET', `/v1/billing/checkout_sessions/${encodeURIComponent(ref)}`);
+    }
+    async createTaxQuote(params) {
+        if (!this.taxQuoteAuthorityKeys || Object.keys(this.taxQuoteAuthorityKeys).length === 0)
+            throw new Error('Peable: tax quote authority verification is unconfigured');
+        const result = await this.client.request('POST', '/v1/billing/tax_quotes', {
+            body: params,
+        });
+        try {
+            const pinned = this.taxQuoteAuthorityKeys[result.signature.keyId];
+            if (!pinned ||
+                result.schemaVersion !== 1 ||
+                result.signature.algorithm !== 'Ed25519' ||
+                !/^[A-Za-z0-9_-]{86}$/.test(result.signature.value) ||
+                result.source.storeId !== params.storeId ||
+                result.source.planId !== params.planId ||
+                result.quote.customerLocationEvidenceId !== params.customerLocationEvidenceId ||
+                !Number.isFinite(Date.parse(result.quote.quotedAt)) ||
+                Date.parse(result.quote.quotedAt) > Date.now() ||
+                !Number.isFinite(Date.parse(result.quote.expiresAt)) ||
+                Date.parse(result.quote.expiresAt) <= Date.now())
+                throw new Error('Invalid quote');
+            const key = (0, node_crypto_1.createPublicKey)(pinned);
+            if (key.asymmetricKeyType !== 'ed25519' ||
+                !(0, node_crypto_1.verify)(null, Buffer.from((0, shared_types_1.canonicalBillingTaxQuote)(result)), key, Buffer.from(result.signature.value, 'base64url')))
+                throw new Error('Invalid signature');
+        }
+        catch {
+            throw new Error('Peable: tax quote authority verification failed');
+        }
+        return result;
+    }
+    async retrieveFinalInvoiceAuthority(subscriptionRef, invoiceRef) {
+        if (!this.invoiceAuthorityKeys || Object.keys(this.invoiceAuthorityKeys).length === 0)
+            throw new Error('Peable: invoice authority verification is unconfigured');
+        const authority = await this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/invoice_authorities/${encodeURIComponent(invoiceRef)}`);
+        try {
+            const pinnedKey = this.invoiceAuthorityKeys[authority.signature.keyId];
+            if (authority.schemaVersion !== 1 ||
+                !pinnedKey ||
+                authority.signature.algorithm !== 'Ed25519' ||
+                !/^[A-Za-z0-9_-]{86}$/.test(authority.signature.value) ||
+                authority.source.invoiceId !== invoiceRef ||
+                authority.source.subscriptionId !== subscriptionRef ||
+                authority.invoice.context.providerSubscriptionId !== subscriptionRef ||
+                !['card', 'faircoin'].includes(authority.method) ||
+                !Number.isFinite(Date.parse(authority.invoice.issuedAt)) ||
+                Date.parse(authority.invoice.issuedAt) > Date.now() ||
+                !Number.isFinite(Date.parse(authority.invoice.expiresAt)) ||
+                Date.parse(authority.invoice.expiresAt) <= Date.now())
+                throw new Error('Invalid authority');
+            if (authority.method === 'faircoin') {
+                const quote = authority.invoice.faircoinQuote;
+                if (!quote ||
+                    !/^[1-9][0-9]*$/.test(quote.amountBaseUnits) ||
+                    !Number.isFinite(Date.parse(quote.quotedAt)) ||
+                    Date.parse(quote.quotedAt) > Date.now() ||
+                    !Number.isFinite(Date.parse(quote.expiresAt)) ||
+                    Date.parse(quote.expiresAt) <= Date.now() ||
+                    Date.parse(quote.expiresAt) > Date.parse(authority.invoice.expiresAt))
+                    throw new Error('Invalid quote');
+            }
+            const key = (0, node_crypto_1.createPublicKey)(pinnedKey);
+            if (key.asymmetricKeyType !== 'ed25519' ||
+                !(0, node_crypto_1.verify)(null, Buffer.from((0, shared_types_1.canonicalBillingAuthority)(authority), 'utf8'), key, Buffer.from(authority.signature.value, 'base64url')))
+                throw new Error('Invalid signature');
+        }
+        catch {
+            throw new Error('Peable: invoice authority verification failed');
+        }
+        return authority;
+    }
+    retrievePaidInvoice(subscriptionRef, invoiceRef) {
+        return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/paid_invoices/${encodeURIComponent(invoiceRef)}`);
+    }
+    retrieveInvoiceState(subscriptionRef, invoiceRef) {
+        return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/invoice_states/${encodeURIComponent(invoiceRef)}`);
     }
-    retrieveCheckout(ref) { return this.client.request('GET', `/v1/billing/checkout_sessions/${encodeURIComponent(ref)}`); }
-    retrievePaidInvoice(subscriptionRef, invoiceRef) { return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/paid_invoices/${encodeURIComponent(invoiceRef)}`); }
-    retrieveInvoiceState(subscriptionRef, invoiceRef) { return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/invoice_states/${encodeURIComponent(invoiceRef)}`); }
     retrieveSubscription(ref) {
         return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(ref)}`);
     }

package/dist/cjs/resources/refunds.js

@@ -19,7 +19,10 @@ class RefundsResource {
      * arrives.
      */
     create(params, options = {}) {
-        return this.client.request('POST', '/v1/refunds', { body: params, idempotencyKey: options.idempotencyKey });
+        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

@@ -18,7 +18,10 @@ class TransfersResource {
      * money in flight.
      */
     create(params, options = {}) {
-        return this.client.request('POST', '/v1/transfers', { body: params, idempotencyKey: options.idempotencyKey });
+        return this.client.request('POST', '/v1/transfers', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
     }
     /**
      * Take some or all of a settlement back.
@@ -36,9 +39,7 @@ class TransfersResource {
         }
         return this.client.request('POST', `/v1/transfers/${encodeURIComponent(transferId)}/reversals`, {
             body: params,
-            ...(options.idempotencyKey === undefined
-                ? {}
-                : { idempotencyKey: options.idempotencyKey }),
+            ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
         });
     }
     /** What one payment settled — the reconciliation read. */

package/dist/cjs/resources/webhooks.js

@@ -33,14 +33,14 @@ function isWebhookEventShape(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const candidate = value;
-    const valid = (typeof candidate.id === 'string' &&
+    const valid = typeof candidate.id === 'string' &&
         candidate.object === 'event' &&
         typeof candidate.type === 'string' &&
         Object.prototype.hasOwnProperty.call(WEBHOOK_EVENT_TYPES, candidate.type) &&
         typeof candidate.created === 'string' &&
         typeof candidate.data === 'object' &&
         candidate.data !== null &&
-        'object' in candidate.data);
+        'object' in candidate.data;
     if (!valid)
         return false;
     if (candidate.type === 'billing.observation.updated') {
@@ -48,7 +48,16 @@ function isWebhookEventShape(value) {
         if (!data || typeof data !== 'object')
             return false;
         const v = data;
-        return v.object === 'billing_observation' && (v.resourceKind === 'subscription' || v.resourceKind === 'invoice') && typeof v.resourceId === 'string' && v.resourceId.length > 0 && typeof v.revision === 'number' && Number.isSafeInteger(v.revision) && v.revision > 0 && typeof v.observedAt === 'string' && Number.isFinite(Date.parse(v.observedAt)) && Object.keys(v).every(k => ['object', 'resourceKind', 'resourceId', 'revision', 'observedAt'].includes(k));
+        return (v.object === 'billing_observation' &&
+            (v.resourceKind === 'subscription' || v.resourceKind === 'invoice') &&
+            typeof v.resourceId === 'string' &&
+            v.resourceId.length > 0 &&
+            typeof v.revision === 'number' &&
+            Number.isSafeInteger(v.revision) &&
+            v.revision > 0 &&
+            typeof v.observedAt === 'string' &&
+            Number.isFinite(Date.parse(v.observedAt)) &&
+            Object.keys(v).every((k) => ['object', 'resourceKind', 'resourceId', 'revision', 'observedAt'].includes(k)));
     }
     return true;
 }

package/dist/esm/core/config.js

@@ -1,8 +1,14 @@
-// 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.
+// Configuration for the server-side `Peable` client. The SDK authenticates with
+// an Oxy service token, obtained one of two ways:
+//
+// - a confidential `ApplicationCredential` (`{publicKey, secret}`, the SAME
+//   credential Oxy Console already issues for a `type:'service'` credential) —
+//   never a bespoke "Peable API key" — from which the SDK mints the token
+//   itself. See the SDK plan's "Architecture / auth" section; or
+// - a caller-supplied `tokenProvider`, for a workload that already holds an Oxy
+//   identity (e.g. an ECS task role attested through workload identity) and
+//   has no key pair to hand over. The Gateway resolves the merchant from the
+//   token's application id and environment, not from how it was minted.
 /** 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. */
@@ -21,24 +27,47 @@ export function resolveRequestTimeout(value) {
 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).
- */
+function isServiceTokenProvider(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.getToken === 'function' && typeof candidate.invalidate === 'function';
+}
 export function resolveConfig(config) {
-    if (!config.publicKey) {
-        throw new Error('Peable: `publicKey` is required');
+    // Read loosely: a JavaScript caller is not held to the union, and "both" is
+    // exactly the shape the types forbid.
+    const { tokenProvider, publicKey, secret } = config;
+    if (tokenProvider !== undefined) {
+        if (publicKey !== undefined || secret !== undefined) {
+            throw new Error('Peable: pass either `tokenProvider` or `publicKey` + `secret`, not both');
+        }
+        if (!isServiceTokenProvider(tokenProvider)) {
+            throw new Error('Peable: `tokenProvider` must have `getToken()` and `invalidate()`');
+        }
     }
-    if (!config.secret) {
-        throw new Error('Peable: `secret` is required');
+    else {
+        if (publicKey === undefined && secret === undefined) {
+            throw new Error('Peable: either `publicKey` + `secret` or a `tokenProvider` is required');
+        }
+        if (!config.publicKey) {
+            throw new Error('Peable: `publicKey` is required');
+        }
+        if (!config.secret) {
+            throw new Error('Peable: `secret` is required');
+        }
     }
-    return {
+    const options = {
         requestTimeoutMs: resolveRequestTimeout(config.requestTimeoutMs),
-        publicKey: config.publicKey,
-        secret: config.secret,
+        taxQuoteAuthorityKeys: config.taxQuoteAuthorityKeys
+            ? Object.freeze({ ...config.taxQuoteAuthorityKeys })
+            : undefined,
+        invoiceAuthorityKeys: config.invoiceAuthorityKeys
+            ? Object.freeze({ ...config.invoiceAuthorityKeys })
+            : undefined,
         baseURL: stripTrailingSlash(config.baseURL ?? DEFAULT_GATEWAY_BASE_URL),
         oxyApiUrl: stripTrailingSlash(config.oxyApiUrl ?? DEFAULT_OXY_API_URL),
     };
+    return config.tokenProvider !== undefined
+        ? { ...options, tokenProvider: config.tokenProvider }
+        : { ...options, publicKey: config.publicKey, secret: config.secret };
 }

package/dist/esm/core/serviceToken.js

@@ -40,7 +40,9 @@ export function createServiceTokenProvider(cfg, deps = {}) {
         try {
             response = await fetchImpl(`${resolved.oxyApiUrl}${SERVICE_TOKEN_PATH}`, {
                 method: 'POST',
-                ...(resolved.requestTimeoutMs === undefined ? {} : { signal: AbortSignal.timeout(resolved.requestTimeoutMs) }),
+                ...(resolved.requestTimeoutMs === undefined
+                    ? {}
+                    : { signal: AbortSignal.timeout(resolved.requestTimeoutMs) }),
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ apiKey: resolved.publicKey, apiSecret: resolved.secret }),
             });
@@ -54,7 +56,8 @@ export function createServiceTokenProvider(cfg, deps = {}) {
         }
         catch {
             throw new PeableApiError('The Oxy service-token response body could not be read', {
-                statusCode: response.status, code: 'invalid_response',
+                statusCode: response.status,
+                code: 'invalid_response',
             });
         }
         if (!response.ok) {

package/dist/esm/index.js

@@ -1,7 +1,8 @@
 import { BillingResource } from './resources/billing.js';
 // 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
+// confidential `ApplicationCredential` (`{publicKey, secret}`), from which it
+// mints and caches an Oxy service token, or with a caller-supplied
+// `tokenProvider` that already holds one; exposes Stripe-ergonomics resource
 // namespaces over the Gateway REST contract.
 //
 // Deliberately never imports `socket.io-client` or `./browser/*` — the
@@ -36,9 +37,11 @@ import { TransfersResource } from './resources/transfers.js';
 export class Peable {
     constructor(config) {
         const resolved = resolveConfig(config);
-        const tokenProvider = createServiceTokenProvider(config);
+        const tokenProvider = config.tokenProvider !== undefined
+            ? config.tokenProvider
+            : createServiceTokenProvider(config);
         const client = createRestClient({ baseURL: resolved.baseURL, requestTimeoutMs: resolved.requestTimeoutMs }, tokenProvider);
-        this.billing = new BillingResource(client);
+        this.billing = new BillingResource(client, resolved.invoiceAuthorityKeys, resolved.taxQuoteAuthorityKeys);
         this.paymentIntents = new PaymentIntentsResource(client);
         this.paymentLinks = new PaymentLinksResource(client);
         this.checkout = new CheckoutResource(client);

package/dist/esm/resources/billing.js

@@ -1,20 +1,109 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { canonicalBillingAuthority, canonicalBillingTaxQuote } from '@peable.to/shared-types';
 /** Recurring billing is separate from one-off checkout and marketplace transfers. */
 export class BillingResource {
-    constructor(client) {
+    constructor(client, invoiceAuthorityKeys, taxQuoteAuthorityKeys) {
         this.client = client;
+        this.invoiceAuthorityKeys = invoiceAuthorityKeys;
+        this.taxQuoteAuthorityKeys = taxQuoteAuthorityKeys;
     }
     ensureCustomer(params, options) {
-        return this.client.request('POST', '/v1/billing/customers', { body: params, idempotencyKey: options.idempotencyKey });
+        return this.client.request('POST', '/v1/billing/customers', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
     }
     createCheckoutSession(params, options) {
-        return this.client.request('POST', '/v1/billing/checkout_sessions', { body: params, idempotencyKey: options.idempotencyKey });
+        return this.client.request('POST', '/v1/billing/checkout_sessions', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
     }
     createPortalSession(params, options) {
-        return this.client.request('POST', '/v1/billing/portal_sessions', { body: params, idempotencyKey: options.idempotencyKey });
+        return this.client.request('POST', '/v1/billing/portal_sessions', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
+    }
+    retrieveCheckout(ref) {
+        return this.client.request('GET', `/v1/billing/checkout_sessions/${encodeURIComponent(ref)}`);
+    }
+    async createTaxQuote(params) {
+        if (!this.taxQuoteAuthorityKeys || Object.keys(this.taxQuoteAuthorityKeys).length === 0)
+            throw new Error('Peable: tax quote authority verification is unconfigured');
+        const result = await this.client.request('POST', '/v1/billing/tax_quotes', {
+            body: params,
+        });
+        try {
+            const pinned = this.taxQuoteAuthorityKeys[result.signature.keyId];
+            if (!pinned ||
+                result.schemaVersion !== 1 ||
+                result.signature.algorithm !== 'Ed25519' ||
+                !/^[A-Za-z0-9_-]{86}$/.test(result.signature.value) ||
+                result.source.storeId !== params.storeId ||
+                result.source.planId !== params.planId ||
+                result.quote.customerLocationEvidenceId !== params.customerLocationEvidenceId ||
+                !Number.isFinite(Date.parse(result.quote.quotedAt)) ||
+                Date.parse(result.quote.quotedAt) > Date.now() ||
+                !Number.isFinite(Date.parse(result.quote.expiresAt)) ||
+                Date.parse(result.quote.expiresAt) <= Date.now())
+                throw new Error('Invalid quote');
+            const key = createPublicKey(pinned);
+            if (key.asymmetricKeyType !== 'ed25519' ||
+                !verify(null, Buffer.from(canonicalBillingTaxQuote(result)), key, Buffer.from(result.signature.value, 'base64url')))
+                throw new Error('Invalid signature');
+        }
+        catch {
+            throw new Error('Peable: tax quote authority verification failed');
+        }
+        return result;
+    }
+    async retrieveFinalInvoiceAuthority(subscriptionRef, invoiceRef) {
+        if (!this.invoiceAuthorityKeys || Object.keys(this.invoiceAuthorityKeys).length === 0)
+            throw new Error('Peable: invoice authority verification is unconfigured');
+        const authority = await this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/invoice_authorities/${encodeURIComponent(invoiceRef)}`);
+        try {
+            const pinnedKey = this.invoiceAuthorityKeys[authority.signature.keyId];
+            if (authority.schemaVersion !== 1 ||
+                !pinnedKey ||
+                authority.signature.algorithm !== 'Ed25519' ||
+                !/^[A-Za-z0-9_-]{86}$/.test(authority.signature.value) ||
+                authority.source.invoiceId !== invoiceRef ||
+                authority.source.subscriptionId !== subscriptionRef ||
+                authority.invoice.context.providerSubscriptionId !== subscriptionRef ||
+                !['card', 'faircoin'].includes(authority.method) ||
+                !Number.isFinite(Date.parse(authority.invoice.issuedAt)) ||
+                Date.parse(authority.invoice.issuedAt) > Date.now() ||
+                !Number.isFinite(Date.parse(authority.invoice.expiresAt)) ||
+                Date.parse(authority.invoice.expiresAt) <= Date.now())
+                throw new Error('Invalid authority');
+            if (authority.method === 'faircoin') {
+                const quote = authority.invoice.faircoinQuote;
+                if (!quote ||
+                    !/^[1-9][0-9]*$/.test(quote.amountBaseUnits) ||
+                    !Number.isFinite(Date.parse(quote.quotedAt)) ||
+                    Date.parse(quote.quotedAt) > Date.now() ||
+                    !Number.isFinite(Date.parse(quote.expiresAt)) ||
+                    Date.parse(quote.expiresAt) <= Date.now() ||
+                    Date.parse(quote.expiresAt) > Date.parse(authority.invoice.expiresAt))
+                    throw new Error('Invalid quote');
+            }
+            const key = createPublicKey(pinnedKey);
+            if (key.asymmetricKeyType !== 'ed25519' ||
+                !verify(null, Buffer.from(canonicalBillingAuthority(authority), 'utf8'), key, Buffer.from(authority.signature.value, 'base64url')))
+                throw new Error('Invalid signature');
+        }
+        catch {
+            throw new Error('Peable: invoice authority verification failed');
+        }
+        return authority;
+    }
+    retrievePaidInvoice(subscriptionRef, invoiceRef) {
+        return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/paid_invoices/${encodeURIComponent(invoiceRef)}`);
+    }
+    retrieveInvoiceState(subscriptionRef, invoiceRef) {
+        return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/invoice_states/${encodeURIComponent(invoiceRef)}`);
     }
-    retrieveCheckout(ref) { return this.client.request('GET', `/v1/billing/checkout_sessions/${encodeURIComponent(ref)}`); }
-    retrievePaidInvoice(subscriptionRef, invoiceRef) { return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/paid_invoices/${encodeURIComponent(invoiceRef)}`); }
-    retrieveInvoiceState(subscriptionRef, invoiceRef) { return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/invoice_states/${encodeURIComponent(invoiceRef)}`); }
     retrieveSubscription(ref) {
         return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(ref)}`);
     }

package/dist/esm/resources/refunds.js

@@ -16,7 +16,10 @@ export class RefundsResource {
      * arrives.
      */
     create(params, options = {}) {
-        return this.client.request('POST', '/v1/refunds', { body: params, idempotencyKey: options.idempotencyKey });
+        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

@@ -15,7 +15,10 @@ export class TransfersResource {
      * money in flight.
      */
     create(params, options = {}) {
-        return this.client.request('POST', '/v1/transfers', { body: params, idempotencyKey: options.idempotencyKey });
+        return this.client.request('POST', '/v1/transfers', {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
     }
     /**
      * Take some or all of a settlement back.
@@ -33,9 +36,7 @@ export class TransfersResource {
         }
         return this.client.request('POST', `/v1/transfers/${encodeURIComponent(transferId)}/reversals`, {
             body: params,
-            ...(options.idempotencyKey === undefined
-                ? {}
-                : { idempotencyKey: options.idempotencyKey }),
+            ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
         });
     }
     /** What one payment settled — the reconciliation read. */

package/dist/esm/resources/webhooks.js

@@ -30,14 +30,14 @@ function isWebhookEventShape(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const candidate = value;
-    const valid = (typeof candidate.id === 'string' &&
+    const valid = typeof candidate.id === 'string' &&
         candidate.object === 'event' &&
         typeof candidate.type === 'string' &&
         Object.prototype.hasOwnProperty.call(WEBHOOK_EVENT_TYPES, candidate.type) &&
         typeof candidate.created === 'string' &&
         typeof candidate.data === 'object' &&
         candidate.data !== null &&
-        'object' in candidate.data);
+        'object' in candidate.data;
     if (!valid)
         return false;
     if (candidate.type === 'billing.observation.updated') {
@@ -45,7 +45,16 @@ function isWebhookEventShape(value) {
         if (!data || typeof data !== 'object')
             return false;
         const v = data;
-        return v.object === 'billing_observation' && (v.resourceKind === 'subscription' || v.resourceKind === 'invoice') && typeof v.resourceId === 'string' && v.resourceId.length > 0 && typeof v.revision === 'number' && Number.isSafeInteger(v.revision) && v.revision > 0 && typeof v.observedAt === 'string' && Number.isFinite(Date.parse(v.observedAt)) && Object.keys(v).every(k => ['object', 'resourceKind', 'resourceId', 'revision', 'observedAt'].includes(k));
+        return (v.object === 'billing_observation' &&
+            (v.resourceKind === 'subscription' || v.resourceKind === 'invoice') &&
+            typeof v.resourceId === 'string' &&
+            v.resourceId.length > 0 &&
+            typeof v.revision === 'number' &&
+            Number.isSafeInteger(v.revision) &&
+            v.revision > 0 &&
+            typeof v.observedAt === 'string' &&
+            Number.isFinite(Date.parse(v.observedAt)) &&
+            Object.keys(v).every((k) => ['object', 'resourceKind', 'resourceId', 'revision', 'observedAt'].includes(k)));
     }
     return true;
 }

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

@@ -1,34 +1,71 @@
+import type { ServiceTokenProvider } from './serviceToken';
 /** 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 declare const DEFAULT_GATEWAY_BASE_URL = "https://api.peable.to";
 /** Default oxy-api host used to mint the short-lived service token. */
 export declare const DEFAULT_OXY_API_URL = "https://api.oxy.so";
-export interface PeableConfig {
-    /** ApplicationCredential publicKey (e.g. `oxy_dk_...`). */
-    publicKey: string;
-    /** ApplicationCredential plaintext secret. */
-    secret: string;
+/** Options shared by both ways of authenticating. */
+interface PeableConfigOptions {
     /** Gateway base URL. Default `https://api.peable.to`. */
     baseURL?: string;
-    /** oxy-api host used to mint the service token. Default `https://api.oxy.so`. */
+    /** oxy-api host used to mint the service token. Default `https://api.oxy.so`.
+     * Unused with `tokenProvider`, which mints its own. */
     oxyApiUrl?: string;
     /** Optional deadline per HTTP attempt, including body consumption. */
     requestTimeoutMs?: number;
+    /** Pinned Ed25519 authority keys, obtained from trusted deployment configuration. */
+    invoiceAuthorityKeys?: Readonly<Record<string, string>>;
+    taxQuoteAuthorityKeys?: Readonly<Record<string, string>>;
 }
-/** `PeableConfig` with every optional field defaulted and normalized. */
-export interface ResolvedPeableConfig {
+/** Authenticate with an `ApplicationCredential`; the SDK mints the token. */
+export interface PeableCredentialConfig extends PeableConfigOptions {
+    /** ApplicationCredential publicKey (e.g. `oxy_dk_...`). */
     publicKey: string;
+    /** ApplicationCredential plaintext secret. */
     secret: string;
+    tokenProvider?: undefined;
+}
+/** Authenticate with Oxy service tokens the caller already knows how to obtain. */
+export interface PeableTokenProviderConfig extends PeableConfigOptions {
+    /** Supplies the bearer for every Gateway request. `invalidate()` is called
+     * when the Gateway answers 401, before the single retry; the next
+     * `getToken()` must then return a freshly minted token. */
+    tokenProvider: ServiceTokenProvider;
+    publicKey?: undefined;
+    secret?: undefined;
+}
+export type PeableConfig = PeableCredentialConfig | PeableTokenProviderConfig;
+interface ResolvedPeableConfigOptions {
     baseURL: string;
     oxyApiUrl: string;
     requestTimeoutMs?: number;
+    invoiceAuthorityKeys?: Readonly<Record<string, string>>;
+    taxQuoteAuthorityKeys?: Readonly<Record<string, string>>;
 }
+/** `PeableCredentialConfig` with every optional field defaulted and normalized. */
+export interface ResolvedPeableCredentialConfig extends ResolvedPeableConfigOptions {
+    publicKey: string;
+    secret: string;
+    tokenProvider?: undefined;
+}
+/** `PeableTokenProviderConfig` with every optional field defaulted and normalized. */
+export interface ResolvedPeableTokenProviderConfig extends ResolvedPeableConfigOptions {
+    tokenProvider: ServiceTokenProvider;
+    publicKey?: undefined;
+    secret?: undefined;
+}
+/** `PeableConfig` with every optional field defaulted and normalized. */
+export type ResolvedPeableConfig = ResolvedPeableCredentialConfig | ResolvedPeableTokenProviderConfig;
 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
- * time, not an API-response failure, so it deliberately does not go through
- * the `PeableError` hierarchy (which models mapped HTTP responses).
+ * missing `publicKey`/`secret`, for a `tokenProvider` passed alongside either
+ * of them or for neither being passed — 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 declare function resolveConfig(config: PeableCredentialConfig): ResolvedPeableCredentialConfig;
+export declare function resolveConfig(config: PeableTokenProviderConfig): ResolvedPeableTokenProviderConfig;
 export declare function resolveConfig(config: PeableConfig): ResolvedPeableConfig;
+export {};

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

@@ -1,4 +1,4 @@
-import { type PeableConfig } from './config';
+import { type PeableCredentialConfig } from './config';
 export interface ServiceTokenProvider {
     /** Mints once, caches until near expiry, re-mints on expiry/401. */
     getToken(): Promise<string>;
@@ -6,6 +6,6 @@ export interface ServiceTokenProvider {
      * `RestClient` after a Gateway request comes back 401. */
     invalidate(): void;
 }
-export declare function createServiceTokenProvider(cfg: PeableConfig, deps?: {
+export declare function createServiceTokenProvider(cfg: PeableCredentialConfig, deps?: {
     fetch?: typeof fetch;
 }): ServiceTokenProvider;

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import { BillingResource } from './resources/billing';
 export type { BillingRequestOptions } from './resources/billing';
-export type { BillingObservation, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams } from '@peable.to/shared-types';
+export type { CreateBillingTaxQuoteParams, BillingTaxQuote, BillingInvoiceAuthoritySource, BillingFinalInvoice, BillingFinalInvoiceAuthority, BillingFaircoinRenewalChoice, BillingFaircoinRenewalConsent, BillingFaircoinRenewalRevocation, BillingObservation, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams, } from '@peable.to/shared-types';
 import { type PeableConfig } from './core/config';
 import { PaymentIntentsResource } from './resources/paymentIntents';
 import { PaymentLinksResource } from './resources/paymentLinks';
@@ -44,7 +44,7 @@ export declare class Peable {
     readonly disputes: DisputesResource;
     constructor(config: PeableConfig);
 }
-export type { PeableConfig, ResolvedPeableConfig } from './core/config';
+export type { PeableConfig, PeableCredentialConfig, PeableTokenProviderConfig, ResolvedPeableConfig, } from './core/config';
 export { DEFAULT_GATEWAY_BASE_URL, DEFAULT_OXY_API_URL } from './core/config';
 export { PeableError, PeableAuthenticationError, PeableInvalidRequestError, PeablePermissionError, PeableApiError, PeableSignatureVerificationError, } from './core/errors';
 export type { PeableErrorType, PeableErrorDetails } from './core/errors';

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

@@ -1,4 +1,4 @@
-import type { BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams } from '@peable.to/shared-types';
+import type { BillingTaxQuote, CreateBillingTaxQuoteParams, BillingFinalInvoiceAuthority, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams } from '@peable.to/shared-types';
 import type { RestClient } from '../core/client';
 export interface BillingRequestOptions {
     idempotencyKey: string;
@@ -6,11 +6,15 @@ export interface BillingRequestOptions {
 /** Recurring billing is separate from one-off checkout and marketplace transfers. */
 export declare class BillingResource {
     private readonly client;
-    constructor(client: RestClient);
+    private readonly invoiceAuthorityKeys?;
+    private readonly taxQuoteAuthorityKeys?;
+    constructor(client: RestClient, invoiceAuthorityKeys?: Readonly<Record<string, string>> | undefined, taxQuoteAuthorityKeys?: Readonly<Record<string, string>> | undefined);
     ensureCustomer(params: EnsureBillingCustomerParams, options: BillingRequestOptions): Promise<BillingCustomer>;
     createCheckoutSession(params: CreateBillingCheckoutParams, options: BillingRequestOptions): Promise<BillingCheckoutSession>;
     createPortalSession(params: CreateBillingPortalParams, options: BillingRequestOptions): Promise<BillingHostedSession>;
     retrieveCheckout(ref: string): Promise<BillingCheckoutObservation>;
+    createTaxQuote(params: CreateBillingTaxQuoteParams): Promise<BillingTaxQuote>;
+    retrieveFinalInvoiceAuthority(subscriptionRef: string, invoiceRef: string): Promise<BillingFinalInvoiceAuthority>;
     retrievePaidInvoice(subscriptionRef: string, invoiceRef: string): Promise<BillingPaidInvoice>;
     retrieveInvoiceState(subscriptionRef: string, invoiceRef: string): Promise<BillingInvoiceState>;
     retrieveSubscription(ref: string): Promise<BillingSubscription>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/sdk",
-  "version": "0.2.3-oxy-one.0",
+  "version": "0.2.5-oxy-one.0",
   "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",
@@ -67,13 +67,12 @@
     "build:types": "tsc -p tsconfig.types.json",
     "clean": "rm -rf dist",
     "dev": "tsc --watch",
-    "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {
-    "@peable.to/shared-types": "0.3.1-oxy-one.0",
+    "@peable.to/shared-types": "0.3.2-oxy-one.0",
     "qrcode-generator": "^2.0.4",
     "socket.io-client": "^4.8.3"
   },