@peable.to/sdk 0.2.7 → 0.4.0

package/README.md

@@ -22,3 +22,29 @@ The remote outcome may be unknown: recover explicitly with the same durable key.
 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.
+
+### Connect for FairCoin (0.4.0)
+
+Pay a marketplace's sellers in FairCoin straight to their own wallets
+(ADR 0012, guide in `docs/connect-faircoin.md`):
+
+```ts
+const seller = await peable.accounts.create({
+  externalRef: store.id,
+  faircoin: { network: 'testnet', oxyUserId: store.ownerOxyUserId },
+});
+const link = await peable.accountLinks.create({
+  account: seller.id, rail: 'faircoin', returnUrl, refreshUrl,
+});
+// the seller registers their key at link.url, signed in with Oxy;
+// you receive connected_account.updated with faircoin.status === 'active'
+const intent = await peable.paymentIntents.create(
+  { amount: '250000000', rail: 'faircoin', network: 'testnet', connectedAccount: seller.id },
+  { idempotencyKey: `order:${order.id}` },
+);
+```
+
+`peable.accounts` is `peable.connectedAccounts` under its Stripe name. Events for
+an on-behalf payment carry `event.account`; `intent.canExpire` is `false` once a
+payer has broadcast, so never cancel an order on `expiresAt` alone. A seller
+without a registered key is a 409 with `error.code === 'account_not_ready'`.

package/dist/cjs/core/errors.js

@@ -94,7 +94,9 @@ function errorFromResponse(status, body) {
     let upstreamCode;
     let message = `Peable request failed with status ${status}`;
     if (isNestedGatewayErrorBody(body)) {
-        upstreamCode = body.error.type;
+        // The specific reason when the gateway names one (`account_not_ready`),
+        // else the broad `type` — which is all any error carried before.
+        upstreamCode = typeof body.error.code === 'string' ? body.error.code : body.error.type;
         message = body.error.message;
     }
     else if (isFlatGatewayErrorBody(body)) {

package/dist/cjs/index.js

@@ -1,7 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContributionsResource = 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;
+exports.ContributionsResource = exports.WebhooksResource = exports.WEBHOOK_SIGNATURE_HEADER = exports.EXPIRABLE_STATUSES = exports.canExpire = exports.ConnectedAccountsResource = exports.AccountLinksResource = exports.PeableSignatureVerificationError = exports.PeableApiError = exports.PeablePermissionError = exports.PeableInvalidRequestError = exports.PeableAuthenticationError = exports.PeableError = exports.DEFAULT_OXY_API_URL = exports.DEFAULT_GATEWAY_BASE_URL = exports.Peable = exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.TaxResource = void 0;
 const billing_1 = require("./resources/billing");
+const tax_1 = require("./resources/tax");
+var tax_2 = require("./resources/tax");
+Object.defineProperty(exports, "TaxResource", { enumerable: true, get: function () { return tax_2.TaxResource; } });
+/** Production Peable's pinned billing-authority public keys, by key id. */
+var shared_types_1 = require("@peable.to/shared-types");
+Object.defineProperty(exports, "PEABLE_BILLING_AUTHORITY_KEYS", { enumerable: true, get: function () { return shared_types_1.PEABLE_BILLING_AUTHORITY_KEYS; } });
 // Server entry (`@peable.to/sdk`) — the merchant-authed SDK. Configured with a
 // confidential `ApplicationCredential` (`{publicKey, secret}`), from which it
 // mints and caches an Oxy service token, or with a caller-supplied
@@ -45,12 +51,15 @@ class Peable {
             : (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, resolved.invoiceAuthorityKeys, resolved.taxQuoteAuthorityKeys);
+        this.tax = new tax_1.TaxResource(client);
         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();
         this.merchants = new merchants_1.MerchantsResource(client);
         this.connectedAccounts = new connectedAccounts_1.ConnectedAccountsResource(client);
+        this.accounts = this.connectedAccounts;
+        this.accountLinks = new connectedAccounts_1.AccountLinksResource(this.connectedAccounts);
         this.refunds = new refunds_1.RefundsResource(client);
         this.transfers = new transfers_1.TransfersResource(client);
         this.disputes = new merchants_1.DisputesResource(client);
@@ -67,6 +76,13 @@ Object.defineProperty(exports, "PeableInvalidRequestError", { enumerable: true,
 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 connectedAccounts_2 = require("./resources/connectedAccounts");
+Object.defineProperty(exports, "AccountLinksResource", { enumerable: true, get: function () { return connectedAccounts_2.AccountLinksResource; } });
+Object.defineProperty(exports, "ConnectedAccountsResource", { enumerable: true, get: function () { return connectedAccounts_2.ConnectedAccountsResource; } });
+/** Whether an intent can still expire — `false` once a FairCoin payer has broadcast (ADR 0012 D9). */
+var shared_types_2 = require("@peable.to/shared-types");
+Object.defineProperty(exports, "canExpire", { enumerable: true, get: function () { return shared_types_2.canExpire; } });
+Object.defineProperty(exports, "EXPIRABLE_STATUSES", { enumerable: true, get: function () { return shared_types_2.EXPIRABLE_STATUSES; } });
 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/billing.js

@@ -10,6 +10,13 @@ class BillingResource {
         this.invoiceAuthorityKeys = invoiceAuthorityKeys;
         this.taxQuoteAuthorityKeys = taxQuoteAuthorityKeys;
     }
+    /** The rails this merchant's payers can choose between (card and other fiat
+     * providers, FairCoin), default first, with each rail's offers. Pass the
+     * payer's choice as `rail` to `ensureCustomer`; the customer's rail then
+     * carries its checkouts, subscriptions and invoices. */
+    listRails() {
+        return this.client.request('GET', '/v1/billing/rails');
+    }
     ensureCustomer(params, options) {
         return this.client.request('POST', '/v1/billing/customers', {
             body: params,
@@ -77,10 +84,11 @@ class BillingResource {
         }
         return result;
     }
-    async retrieveFinalInvoiceAuthority(subscriptionRef, invoiceRef) {
+    async retrieveFinalInvoiceAuthority(subscriptionRef, invoiceRef, options = {}) {
         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)}`);
+        const withTaxLines = options.include?.includes('tax_lines') === true;
+        const authority = await this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/invoice_authorities/${encodeURIComponent(invoiceRef)}`, withTaxLines ? { query: { include: 'tax_lines' } } : undefined);
         try {
             const pinnedKey = this.invoiceAuthorityKeys[authority.signature.keyId];
             if (authority.schemaVersion !== 1 ||
@@ -94,7 +102,12 @@ class BillingResource {
                 !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())
+                Date.parse(authority.invoice.expiresAt) <= Date.now() ||
+                // Lines are present exactly when asked for, and add up to the tax.
+                withTaxLines !== Array.isArray(authority.invoice.taxLines) ||
+                (authority.invoice.taxLines !== undefined &&
+                    authority.invoice.taxLines.reduce((sum, line) => sum + line.taxMinorUnits, 0) !==
+                        authority.invoice.taxMinorUnits))
                 throw new Error('Invalid authority');
             if (authority.method === 'faircoin') {
                 const quote = authority.invoice.faircoinQuote;

package/dist/cjs/resources/connectedAccounts.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConnectedAccountsResource = void 0;
+exports.AccountLinksResource = exports.ConnectedAccountsResource = void 0;
 class ConnectedAccountsResource {
     constructor(client) {
         this.client = client;
@@ -61,3 +61,19 @@ class ConnectedAccountsResource {
     }
 }
 exports.ConnectedAccountsResource = ConnectedAccountsResource;
+/**
+ * `peable.accountLinks` — onboarding links, Stripe-named.
+ *
+ * The same operation as `connectedAccounts.createAccountLink`, addressed the
+ * way Stripe Connect integrators expect: `accountLinks.create({ account, … })`.
+ */
+class AccountLinksResource {
+    constructor(accounts) {
+        this.accounts = accounts;
+    }
+    create(params) {
+        const { account, ...link } = params;
+        return this.accounts.createAccountLink(account, link);
+    }
+}
+exports.AccountLinksResource = AccountLinksResource;

package/dist/cjs/resources/paymentIntents.js

@@ -5,6 +5,14 @@ class PaymentIntentsResource {
     constructor(client) {
         this.client = client;
     }
+    /**
+     * Create a payment. With `connectedAccount: 'ca_…'` it is made ON BEHALF OF
+     * that seller (ADR 0012): FairCoin only, the address derives from the
+     * seller's own key so the coins go straight to their wallet, and you still
+     * own the payment and receive its webhooks (each tagged `event.account`).
+     * A seller who has not registered their key yet is a 409 with
+     * `code: 'account_not_ready'`.
+     */
     create(params, options) {
         return this.client.request('POST', '/v1/payment_intents', {
             body: params,
@@ -20,6 +28,7 @@ class PaymentIntentsResource {
                 status: params.status,
                 limit: params.limit,
                 starting_after: params.starting_after,
+                connected_account: params.connected_account,
             },
         });
     }

package/dist/cjs/resources/tax.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaxResource = void 0;
+/**
+ * Peable Tax for the merchant's server: what its tax settings and
+ * registrations are, recording where a customer is, calculating, and reading
+ * back what was collected. Registrations and the owner's approval are managed
+ * in the Peable dashboard, never by a service credential.
+ *
+ * At checkout: `locationEvidence.create` with what you know of the customer
+ * (billing address, payment-method or bank country, the IP address and the
+ * country you resolved it to). Language, currency or timezone are not
+ * evidence and are refused. Pass the returned id as `customerLocationEvidenceId`
+ * to `billing.createTaxQuote` or `tax.calculations.create`.
+ */
+class TaxResource {
+    constructor(client) {
+        this.client = client;
+        this.locationEvidence = {
+            create: (params) => client.request('POST', '/v1/tax/location_evidence', { body: params }),
+            retrieve: (id) => client.request('GET', `/v1/tax/location_evidence/${encodeURIComponent(id)}`),
+        };
+        this.calculations = {
+            create: (params) => client.request('POST', '/v1/tax/calculations', { body: params }),
+            retrieve: (id) => client.request('GET', `/v1/tax/calculations/${encodeURIComponent(id)}`),
+        };
+        this.products = {
+            list: () => client.request('GET', '/v1/tax/products'),
+            setTaxCode: (productRef, taxCode) => client.request('PUT', `/v1/tax/products/${encodeURIComponent(productRef)}`, {
+                body: { taxCode },
+            }),
+        };
+        this.transactions = {
+            list: (params) => client.request('GET', '/v1/tax/transactions', {
+                query: {
+                    from: params.from,
+                    to: params.to,
+                    limit: params.limit,
+                    startingAfter: params.startingAfter,
+                },
+            }),
+            createReversal: (id, params) => client.request('POST', `/v1/tax/transactions/${encodeURIComponent(id)}/reversals`, {
+                body: params,
+            }),
+        };
+        this.reports = {
+            summary: (params) => client.request('GET', '/v1/tax/reports/summary', {
+                query: { from: params.from, to: params.to },
+            }),
+        };
+    }
+    /** The merchant's tax settings: status (`active` once the owner approved), head office, defaults. */
+    retrieveSettings() {
+        return this.client.request('GET', '/v1/tax/settings');
+    }
+    listRegistrations() {
+        return this.client.request('GET', '/v1/tax/registrations');
+    }
+    listCodes() {
+        return this.client.request('GET', '/v1/tax/codes');
+    }
+}
+exports.TaxResource = TaxResource;

package/dist/esm/core/errors.js

@@ -84,7 +84,9 @@ export function errorFromResponse(status, body) {
     let upstreamCode;
     let message = `Peable request failed with status ${status}`;
     if (isNestedGatewayErrorBody(body)) {
-        upstreamCode = body.error.type;
+        // The specific reason when the gateway names one (`account_not_ready`),
+        // else the broad `type` — which is all any error carried before.
+        upstreamCode = typeof body.error.code === 'string' ? body.error.code : body.error.type;
         message = body.error.message;
     }
     else if (isFlatGatewayErrorBody(body)) {

package/dist/esm/index.js

@@ -1,4 +1,8 @@
 import { BillingResource } from './resources/billing.js';
+import { TaxResource } from './resources/tax.js';
+export { TaxResource } from './resources/tax.js';
+/** Production Peable's pinned billing-authority public keys, by key id. */
+export { PEABLE_BILLING_AUTHORITY_KEYS } from '@peable.to/shared-types';
 // Server entry (`@peable.to/sdk`) — the merchant-authed SDK. Configured with a
 // confidential `ApplicationCredential` (`{publicKey, secret}`), from which it
 // mints and caches an Oxy service token, or with a caller-supplied
@@ -14,7 +18,7 @@ import { PaymentIntentsResource } from './resources/paymentIntents.js';
 import { PaymentLinksResource } from './resources/paymentLinks.js';
 import { CheckoutResource } from './resources/checkoutSessions.js';
 import { WebhooksResource } from './resources/webhooks.js';
-import { ConnectedAccountsResource } from './resources/connectedAccounts.js';
+import { AccountLinksResource, ConnectedAccountsResource } from './resources/connectedAccounts.js';
 import { DisputesResource, MerchantsResource } from './resources/merchants.js';
 import { RefundsResource } from './resources/refunds.js';
 import { TransfersResource } from './resources/transfers.js';
@@ -42,12 +46,15 @@ export class Peable {
             : createServiceTokenProvider(config);
         const client = createRestClient({ baseURL: resolved.baseURL, requestTimeoutMs: resolved.requestTimeoutMs }, tokenProvider);
         this.billing = new BillingResource(client, resolved.invoiceAuthorityKeys, resolved.taxQuoteAuthorityKeys);
+        this.tax = new TaxResource(client);
         this.paymentIntents = new PaymentIntentsResource(client);
         this.paymentLinks = new PaymentLinksResource(client);
         this.checkout = new CheckoutResource(client);
         this.webhooks = new WebhooksResource();
         this.merchants = new MerchantsResource(client);
         this.connectedAccounts = new ConnectedAccountsResource(client);
+        this.accounts = this.connectedAccounts;
+        this.accountLinks = new AccountLinksResource(this.connectedAccounts);
         this.refunds = new RefundsResource(client);
         this.transfers = new TransfersResource(client);
         this.disputes = new DisputesResource(client);
@@ -55,5 +62,8 @@ 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 { AccountLinksResource, ConnectedAccountsResource } from './resources/connectedAccounts.js';
+/** Whether an intent can still expire — `false` once a FairCoin payer has broadcast (ADR 0012 D9). */
+export { canExpire, EXPIRABLE_STATUSES } from '@peable.to/shared-types';
 export { WEBHOOK_SIGNATURE_HEADER, WebhooksResource } from './resources/webhooks.js';
 export { ContributionsResource } from './resources/contributions.js';

package/dist/esm/resources/billing.js

@@ -7,6 +7,13 @@ export class BillingResource {
         this.invoiceAuthorityKeys = invoiceAuthorityKeys;
         this.taxQuoteAuthorityKeys = taxQuoteAuthorityKeys;
     }
+    /** The rails this merchant's payers can choose between (card and other fiat
+     * providers, FairCoin), default first, with each rail's offers. Pass the
+     * payer's choice as `rail` to `ensureCustomer`; the customer's rail then
+     * carries its checkouts, subscriptions and invoices. */
+    listRails() {
+        return this.client.request('GET', '/v1/billing/rails');
+    }
     ensureCustomer(params, options) {
         return this.client.request('POST', '/v1/billing/customers', {
             body: params,
@@ -74,10 +81,11 @@ export class BillingResource {
         }
         return result;
     }
-    async retrieveFinalInvoiceAuthority(subscriptionRef, invoiceRef) {
+    async retrieveFinalInvoiceAuthority(subscriptionRef, invoiceRef, options = {}) {
         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)}`);
+        const withTaxLines = options.include?.includes('tax_lines') === true;
+        const authority = await this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(subscriptionRef)}/invoice_authorities/${encodeURIComponent(invoiceRef)}`, withTaxLines ? { query: { include: 'tax_lines' } } : undefined);
         try {
             const pinnedKey = this.invoiceAuthorityKeys[authority.signature.keyId];
             if (authority.schemaVersion !== 1 ||
@@ -91,7 +99,12 @@ export class BillingResource {
                 !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())
+                Date.parse(authority.invoice.expiresAt) <= Date.now() ||
+                // Lines are present exactly when asked for, and add up to the tax.
+                withTaxLines !== Array.isArray(authority.invoice.taxLines) ||
+                (authority.invoice.taxLines !== undefined &&
+                    authority.invoice.taxLines.reduce((sum, line) => sum + line.taxMinorUnits, 0) !==
+                        authority.invoice.taxMinorUnits))
                 throw new Error('Invalid authority');
             if (authority.method === 'faircoin') {
                 const quote = authority.invoice.faircoinQuote;

package/dist/esm/resources/connectedAccounts.js

@@ -57,3 +57,18 @@ export class ConnectedAccountsResource {
         return this.client.request('POST', `/v1/connected_accounts/${encodeURIComponent(accountId)}/account_links`, { body: params });
     }
 }
+/**
+ * `peable.accountLinks` — onboarding links, Stripe-named.
+ *
+ * The same operation as `connectedAccounts.createAccountLink`, addressed the
+ * way Stripe Connect integrators expect: `accountLinks.create({ account, … })`.
+ */
+export class AccountLinksResource {
+    constructor(accounts) {
+        this.accounts = accounts;
+    }
+    create(params) {
+        const { account, ...link } = params;
+        return this.accounts.createAccountLink(account, link);
+    }
+}

package/dist/esm/resources/paymentIntents.js

@@ -2,6 +2,14 @@ export class PaymentIntentsResource {
     constructor(client) {
         this.client = client;
     }
+    /**
+     * Create a payment. With `connectedAccount: 'ca_…'` it is made ON BEHALF OF
+     * that seller (ADR 0012): FairCoin only, the address derives from the
+     * seller's own key so the coins go straight to their wallet, and you still
+     * own the payment and receive its webhooks (each tagged `event.account`).
+     * A seller who has not registered their key yet is a 409 with
+     * `code: 'account_not_ready'`.
+     */
     create(params, options) {
         return this.client.request('POST', '/v1/payment_intents', {
             body: params,
@@ -17,6 +25,7 @@ export class PaymentIntentsResource {
                 status: params.status,
                 limit: params.limit,
                 starting_after: params.starting_after,
+                connected_account: params.connected_account,
             },
         });
     }

package/dist/esm/resources/tax.js

@@ -0,0 +1,59 @@
+/**
+ * Peable Tax for the merchant's server: what its tax settings and
+ * registrations are, recording where a customer is, calculating, and reading
+ * back what was collected. Registrations and the owner's approval are managed
+ * in the Peable dashboard, never by a service credential.
+ *
+ * At checkout: `locationEvidence.create` with what you know of the customer
+ * (billing address, payment-method or bank country, the IP address and the
+ * country you resolved it to). Language, currency or timezone are not
+ * evidence and are refused. Pass the returned id as `customerLocationEvidenceId`
+ * to `billing.createTaxQuote` or `tax.calculations.create`.
+ */
+export class TaxResource {
+    constructor(client) {
+        this.client = client;
+        this.locationEvidence = {
+            create: (params) => client.request('POST', '/v1/tax/location_evidence', { body: params }),
+            retrieve: (id) => client.request('GET', `/v1/tax/location_evidence/${encodeURIComponent(id)}`),
+        };
+        this.calculations = {
+            create: (params) => client.request('POST', '/v1/tax/calculations', { body: params }),
+            retrieve: (id) => client.request('GET', `/v1/tax/calculations/${encodeURIComponent(id)}`),
+        };
+        this.products = {
+            list: () => client.request('GET', '/v1/tax/products'),
+            setTaxCode: (productRef, taxCode) => client.request('PUT', `/v1/tax/products/${encodeURIComponent(productRef)}`, {
+                body: { taxCode },
+            }),
+        };
+        this.transactions = {
+            list: (params) => client.request('GET', '/v1/tax/transactions', {
+                query: {
+                    from: params.from,
+                    to: params.to,
+                    limit: params.limit,
+                    startingAfter: params.startingAfter,
+                },
+            }),
+            createReversal: (id, params) => client.request('POST', `/v1/tax/transactions/${encodeURIComponent(id)}/reversals`, {
+                body: params,
+            }),
+        };
+        this.reports = {
+            summary: (params) => client.request('GET', '/v1/tax/reports/summary', {
+                query: { from: params.from, to: params.to },
+            }),
+        };
+    }
+    /** The merchant's tax settings: status (`active` once the owner approved), head office, defaults. */
+    retrieveSettings() {
+        return this.client.request('GET', '/v1/tax/settings');
+    }
+    listRegistrations() {
+        return this.client.request('GET', '/v1/tax/registrations');
+    }
+    listCodes() {
+        return this.client.request('GET', '/v1/tax/codes');
+    }
+}

package/dist/types/index.d.ts

@@ -1,12 +1,16 @@
 import { BillingResource } from './resources/billing';
-export type { BillingRequestOptions } from './resources/billing';
-export type { CreateBillingTaxQuoteParams, BillingTaxQuote, BillingInvoiceAuthoritySource, BillingFinalInvoice, BillingFinalInvoiceAuthority, BillingFaircoinRenewalChoice, BillingFaircoinRenewalConsent, BillingFaircoinRenewalRevocation, BillingObservation, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, RetrieveBillingCheckoutOperationParams, BillingCheckoutOperationSource, BillingCheckoutOperationRecovery, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams, } from '@peable.to/shared-types';
+import { TaxResource } from './resources/tax';
+export { TaxResource } from './resources/tax';
+export type { BillingRequestOptions, RetrieveFinalInvoiceAuthorityOptions, } from './resources/billing';
+export type { CreateBillingTaxQuoteParams, BillingTaxQuote, BillingInvoiceAuthoritySource, BillingFinalInvoice, BillingFinalInvoiceAuthority, BillingFaircoinRenewalChoice, BillingFaircoinRenewalConsent, BillingFaircoinRenewalRevocation, BillingObservation, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, RetrieveBillingCheckoutOperationParams, BillingCheckoutOperationSource, BillingCheckoutOperationRecovery, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams, BillingRail, BillingRailSettlement, BillingRailOffer, BillingRailOption, BillingRailList, BillingInvoiceTaxLine, TaxRegistrationScheme, TaxLocationEvidenceType, TaxBehavior, TaxAddress, TaxCode, TaxCalculationAccount, TaxSettings, TaxRegistration, TaxProductCode, TaxLocationEvidenceItem, CreateTaxLocationEvidenceParams, TaxLocationEvidence, TaxLineItemParams, CreateTaxCalculationParams, TaxBreakdownEntry, TaxCalculationLineItem, TaxCalculation, TaxTransaction, TaxTransactionList, ListTaxTransactionsParams, TaxReportRow, TaxReport, } from '@peable.to/shared-types';
+/** Production Peable's pinned billing-authority public keys, by key id. */
+export { PEABLE_BILLING_AUTHORITY_KEYS } from '@peable.to/shared-types';
 import { type PeableConfig } from './core/config';
 import { PaymentIntentsResource } from './resources/paymentIntents';
 import { PaymentLinksResource } from './resources/paymentLinks';
 import { CheckoutResource } from './resources/checkoutSessions';
 import { WebhooksResource } from './resources/webhooks';
-import { ConnectedAccountsResource } from './resources/connectedAccounts';
+import { AccountLinksResource, ConnectedAccountsResource } from './resources/connectedAccounts';
 import { DisputesResource, MerchantsResource } from './resources/merchants';
 import { RefundsResource } from './resources/refunds';
 import { TransfersResource } from './resources/transfers';
@@ -28,6 +32,8 @@ import { TransfersResource } from './resources/transfers';
  */
 export declare class Peable {
     readonly billing: BillingResource;
+    /** Peable Tax: location evidence, calculations, and what was collected. */
+    readonly tax: TaxResource;
     readonly paymentIntents: PaymentIntentsResource;
     readonly paymentLinks: PaymentLinksResource;
     readonly checkout: CheckoutResource;
@@ -36,6 +42,14 @@ export declare class Peable {
     readonly merchants: MerchantsResource;
     /** Sellers a marketplace onboards, and their readiness. */
     readonly connectedAccounts: ConnectedAccountsResource;
+    /**
+     * The same sellers, Stripe-named: `accounts.create/retrieve/list` is
+     * `connectedAccounts.create/retrieve/list` — one resource, two names, so a
+     * Stripe Connect integration reads the way its authors expect.
+     */
+    readonly accounts: ConnectedAccountsResource;
+    /** Onboarding links, Stripe-named: `accountLinks.create({ account, rail, … })`. */
+    readonly accountLinks: AccountLinksResource;
     /** Money going back to a payer. */
     readonly refunds: RefundsResource;
     /** Money going out to a seller, and coming back from one. */
@@ -52,7 +66,16 @@ export type { RestClient, RestClientRequestOptions } from './core/client';
 export type { ServiceTokenProvider } from './core/serviceToken';
 export type { CreateCheckoutSessionOptions } from './resources/checkoutSessions';
 export type { CreatePaymentIntentOptions, PaymentIntentClientAction, PaymentIntentListParams, PaymentIntentList, } from './resources/paymentIntents';
-export type { AccountLink, AccountLinkParams, ConnectedAccountList, ConnectedAccountListParams, CreateConnectedAccountParams, } from './resources/connectedAccounts';
+export type { AccountLink, AccountLinkParams, ConnectedAccountList, ConnectedAccountListParams, CreateAccountLinkParams, CreateConnectedAccountParams, } from './resources/connectedAccounts';
+export { AccountLinksResource, ConnectedAccountsResource } from './resources/connectedAccounts';
+/**
+ * The wire shapes a platform handles, re-exported so a Connect integration needs
+ * one import: the seller (`ConnectedAccount` and its FairCoin half), the
+ * payment, and the typed webhook event — whose `account` names the seller.
+ */
+export type { ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, CheckoutSession, CreateCheckoutSessionParams, CreatePaymentIntentParams, PaymentIntent, PaymentIntentStatus, WebhookEvent, WebhookEventType, } from '@peable.to/shared-types';
+/** Whether an intent can still expire — `false` once a FairCoin payer has broadcast (ADR 0012 D9). */
+export { canExpire, EXPIRABLE_STATUSES } from '@peable.to/shared-types';
 export type { DisputeEvidenceParams, DisputeList, RegisterMerchantParams, UpdateMerchantParams, } from './resources/merchants';
 export type { CreateRefundParams, RefundList } from './resources/refunds';
 export type { CreateTransferParams, ReverseTransferParams, TransferList, } from './resources/transfers';

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

@@ -1,14 +1,25 @@
-import type { BillingTaxQuote, RetrieveBillingCheckoutOperationParams, BillingCheckoutOperationRecovery, CreateBillingTaxQuoteParams, BillingFinalInvoiceAuthority, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams } from '@peable.to/shared-types';
+import type { BillingTaxQuote, RetrieveBillingCheckoutOperationParams, BillingCheckoutOperationRecovery, CreateBillingTaxQuoteParams, BillingFinalInvoiceAuthority, BillingCustomer, BillingRailList, 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;
 }
+export interface RetrieveFinalInvoiceAuthorityOptions {
+    /** `tax_lines`: include the frozen Peable Tax lines, covered by the signature
+     * (FairCoin and other Peable-signed rails). Omitted: the authority is exactly
+     * the 0.3.x shape. */
+    include?: readonly 'tax_lines'[];
+}
 /** Recurring billing is separate from one-off checkout and marketplace transfers. */
 export declare class BillingResource {
     private readonly client;
     private readonly invoiceAuthorityKeys?;
     private readonly taxQuoteAuthorityKeys?;
     constructor(client: RestClient, invoiceAuthorityKeys?: Readonly<Record<string, string>> | undefined, taxQuoteAuthorityKeys?: Readonly<Record<string, string>> | undefined);
+    /** The rails this merchant's payers can choose between (card and other fiat
+     * providers, FairCoin), default first, with each rail's offers. Pass the
+     * payer's choice as `rail` to `ensureCustomer`; the customer's rail then
+     * carries its checkouts, subscriptions and invoices. */
+    listRails(): Promise<BillingRailList>;
     ensureCustomer(params: EnsureBillingCustomerParams, options: BillingRequestOptions): Promise<BillingCustomer>;
     /** Pass the complete signed taxQuote to opt into fiscal checkout. Peable validates
      * its pinned authority and retains immutable evidence before creating a session.
@@ -22,7 +33,7 @@ export declare class BillingResource {
      * Missing/pending/indeterminate never authorizes another create or cancellation. */
     retrieveCheckoutOperation(params: RetrieveBillingCheckoutOperationParams): Promise<BillingCheckoutOperationRecovery>;
     createTaxQuote(params: CreateBillingTaxQuoteParams): Promise<BillingTaxQuote>;
-    retrieveFinalInvoiceAuthority(subscriptionRef: string, invoiceRef: string): Promise<BillingFinalInvoiceAuthority>;
+    retrieveFinalInvoiceAuthority(subscriptionRef: string, invoiceRef: string, options?: RetrieveFinalInvoiceAuthorityOptions): Promise<BillingFinalInvoiceAuthority>;
     retrievePaidInvoice(subscriptionRef: string, invoiceRef: string): Promise<BillingPaidInvoice>;
     retrieveInvoiceState(subscriptionRef: string, invoiceRef: string): Promise<BillingInvoiceState>;
     retrieveSubscription(ref: string): Promise<BillingSubscription>;

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

@@ -1,4 +1,4 @@
-import type { ConnectedAccount } from '@peable.to/shared-types';
+import type { AccountLink, ConnectedAccount, NetworkType } from '@peable.to/shared-types';
 import type { RestClient } from '../core/client';
 /**
  * Sellers a marketplace onboards through Peable.
@@ -13,13 +13,36 @@ import type { RestClient } from '../core/client';
  * whose response never arrived leaves the merchant without the `ca_…` and still
  * holding the reference they chose.
  */
-export interface CreateConnectedAccountParams {
+/**
+ * Open a seller — on the card rail, the FairCoin rail, or both — under ONE
+ * `ca_…` (ADR 0012 D1). At least one half is required.
+ *
+ * Repeating a create converges on the seller's existing account and ADDS a half
+ * it does not have yet, so a card seller can be given FairCoin later (and the
+ * reverse) without a second id.
+ */
+export type CreateConnectedAccountParams = {
     /** The merchant's own id for this seller. The idempotency, and durable. */
     externalRef: string;
-    /** ISO 3166-1 alpha-2. Case-insensitive; the gateway upper-cases it. */
+    /**
+     * The FairCoin half: the chain the seller is paid on and the seller's Oxy
+     * user id — the ONLY person the onboarding page lets register the key.
+     * There is no key here, by design: the seller registers it themselves, in
+     * their own Oxy session, through `accountLinks.create({ rail: 'faircoin' })`.
+     * A non-production credential can only open `testnet`.
+     */
+    faircoin?: {
+        network: NetworkType;
+        oxyUserId: string;
+    };
+} & ({
+    /** ISO 3166-1 alpha-2. Case-insensitive; the gateway upper-cases it. Opens the CARD half. */
     country: string;
     businessType: 'individual' | 'company';
-}
+} | {
+    country?: undefined;
+    businessType?: undefined;
+});
 export interface ConnectedAccountListParams {
     limit?: number;
     /** A `ca_…` from a previous page — the gateway resolves it, scoped to you. */
@@ -31,15 +54,19 @@ export interface ConnectedAccountList {
     has_more: boolean;
 }
 export interface AccountLinkParams {
-    /** Where the provider sends a seller whose link expired mid-flow. */
+    /** Where an EXPIRED link sends the seller, to ask you for a fresh one. */
     refreshUrl: string;
+    /** Where the seller lands when onboarding is done. Proves nothing — read the account. */
     returnUrl: string;
+    /**
+     * Which half to onboard. `card` (the default) is the provider's hosted KYC;
+     * `faircoin` is Peable's page in the wallet, where the seller — signed in
+     * with Oxy as the account's `oxyUserId` — registers their watch-only key
+     * (ADR 0012 D3). The FairCoin link works for an hour and only for that user.
+     */
+    rail?: 'card' | 'faircoin';
 }
-export interface AccountLink {
-    object: 'account_link';
-    url: string;
-    expiresAt: string;
-}
+export type { AccountLink };
 export declare class ConnectedAccountsResource {
     private readonly client;
     constructor(client: RestClient);
@@ -82,3 +109,19 @@ export declare class ConnectedAccountsResource {
      */
     createAccountLink(accountId: string, params: AccountLinkParams): Promise<AccountLink>;
 }
+/** `accountLinks.create` — Stripe's `AccountLink.create`, naming the account in the body. */
+export interface CreateAccountLinkParams extends AccountLinkParams {
+    /** The seller's `ca_…`. */
+    account: string;
+}
+/**
+ * `peable.accountLinks` — onboarding links, Stripe-named.
+ *
+ * The same operation as `connectedAccounts.createAccountLink`, addressed the
+ * way Stripe Connect integrators expect: `accountLinks.create({ account, … })`.
+ */
+export declare class AccountLinksResource {
+    private readonly accounts;
+    constructor(accounts: ConnectedAccountsResource);
+    create(params: CreateAccountLinkParams): Promise<AccountLink>;
+}

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

@@ -4,6 +4,8 @@ export interface PaymentIntentListParams {
     status?: PaymentIntentStatus;
     limit?: number;
     starting_after?: string;
+    /** Only the payments made on behalf of this seller (`ca_…`, ADR 0012). */
+    connected_account?: string;
 }
 export interface PaymentIntentList {
     object: 'list';
@@ -40,6 +42,14 @@ export interface CreatePaymentIntentOptions {
 export declare class PaymentIntentsResource {
     private readonly client;
     constructor(client: RestClient);
+    /**
+     * Create a payment. With `connectedAccount: 'ca_…'` it is made ON BEHALF OF
+     * that seller (ADR 0012): FairCoin only, the address derives from the
+     * seller's own key so the coins go straight to their wallet, and you still
+     * own the payment and receive its webhooks (each tagged `event.account`).
+     * A seller who has not registered their key yet is a 409 with
+     * `code: 'account_not_ready'`.
+     */
     create(params: CreatePaymentIntentParams, options: CreatePaymentIntentOptions): Promise<PaymentIntent>;
     retrieve(id: string): Promise<PaymentIntent>;
     list(params?: PaymentIntentListParams): Promise<PaymentIntentList>;

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

@@ -0,0 +1,55 @@
+import type { CreateTaxCalculationParams, CreateTaxReversalParams, CreateTaxLocationEvidenceParams, ListTaxTransactionsParams, TaxCalculation, TaxCode, TaxLocationEvidence, TaxProductCode, TaxRegistration, TaxReport, TaxSettings, TaxTransaction, TaxTransactionList } from '@peable.to/shared-types';
+import type { RestClient } from '../core/client';
+interface List<T> {
+    object: 'list';
+    data: T[];
+}
+/**
+ * Peable Tax for the merchant's server: what its tax settings and
+ * registrations are, recording where a customer is, calculating, and reading
+ * back what was collected. Registrations and the owner's approval are managed
+ * in the Peable dashboard, never by a service credential.
+ *
+ * At checkout: `locationEvidence.create` with what you know of the customer
+ * (billing address, payment-method or bank country, the IP address and the
+ * country you resolved it to). Language, currency or timezone are not
+ * evidence and are refused. Pass the returned id as `customerLocationEvidenceId`
+ * to `billing.createTaxQuote` or `tax.calculations.create`.
+ */
+export declare class TaxResource {
+    private readonly client;
+    readonly locationEvidence: {
+        create(params: CreateTaxLocationEvidenceParams): Promise<TaxLocationEvidence>;
+        retrieve(id: string): Promise<TaxLocationEvidence>;
+    };
+    readonly calculations: {
+        create(params: CreateTaxCalculationParams): Promise<TaxCalculation>;
+        retrieve(id: string): Promise<TaxCalculation>;
+    };
+    readonly products: {
+        list(): Promise<List<TaxProductCode>>;
+        /** Set a product's (billing plan's) tax code, e.g. `txcd_10103000` for SaaS. */
+        setTaxCode(productRef: string, taxCode: string): Promise<TaxProductCode>;
+    };
+    readonly transactions: {
+        /** Paid sales and their frozen calculations, oldest first; refunds appear
+         * as `type: "reversal"` rows naming the sale they reverse. */
+        list(params: ListTaxTransactionsParams): Promise<TaxTransactionList>;
+        /** Record a refund made outside Peable (a FairCoin sale refunded from your
+         * own wallet). Card refunds and credit notes are reversed automatically. */
+        createReversal(id: string, params: CreateTaxReversalParams): Promise<TaxTransaction>;
+    };
+    readonly reports: {
+        /** Totals per jurisdiction, registration, tax type and rate, for filings. */
+        summary(params: {
+            from: string;
+            to: string;
+        }): Promise<TaxReport>;
+    };
+    constructor(client: RestClient);
+    /** The merchant's tax settings: status (`active` once the owner approved), head office, defaults. */
+    retrieveSettings(): Promise<TaxSettings>;
+    listRegistrations(): Promise<List<TaxRegistration>>;
+    listCodes(): Promise<List<TaxCode>>;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/sdk",
-  "version": "0.2.7",
+  "version": "0.4.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",
@@ -87,10 +87,10 @@
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "prepublishOnly": "bun run clean && bun run build"
+    "prepublishOnly": "bun run clean && bun run typecheck && bun run test && bun run build"
   },
   "dependencies": {
-    "@peable.to/shared-types": "0.3.4",
+    "@peable.to/shared-types": "0.5.0",
     "qrcode-generator": "^2.0.4",
     "socket.io-client": "^4.8.3",
     "@peable.to/contracts": "0.1.0",