@peable.to/shared-types 0.4.0 → 0.5.1

package/dist/cjs/connect.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.canonicalBillingTaxQuote = exports.canonicalBillingAuthority = exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.CARD_ONLY_STATUSES = exports.CHAIN_ONLY_STATUSES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_STATUSES = exports.POST_SETTLEMENT_STATUSES = exports.reachesSettlementFromPayer = exports.canStillBePaid = exports.isValidStatusTransition = exports.isCurrencyCode = exports.decimalsFor = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
+exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.canonicalBillingTaxQuote = exports.canonicalBillingAuthority = exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.canExpire = exports.EXPIRABLE_STATUSES = exports.CARD_ONLY_STATUSES = exports.CHAIN_ONLY_STATUSES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_STATUSES = exports.POST_SETTLEMENT_STATUSES = exports.reachesSettlementFromPayer = exports.canStillBePaid = exports.isValidStatusTransition = exports.isCurrencyCode = exports.decimalsFor = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
 // @peable.to/shared-types — public API for the Peable Gateway contract.
 var money_1 = require("./money");
 Object.defineProperty(exports, "UNITS_PER_COIN", { enumerable: true, get: function () { return money_1.UNITS_PER_COIN; } });
@@ -18,6 +18,8 @@ Object.defineProperty(exports, "PAYMENT_INTENT_STATUSES", { enumerable: true, ge
 Object.defineProperty(exports, "PAYMENT_INTENT_RAILS", { enumerable: true, get: function () { return paymentIntent_1.PAYMENT_INTENT_RAILS; } });
 Object.defineProperty(exports, "CHAIN_ONLY_STATUSES", { enumerable: true, get: function () { return paymentIntent_1.CHAIN_ONLY_STATUSES; } });
 Object.defineProperty(exports, "CARD_ONLY_STATUSES", { enumerable: true, get: function () { return paymentIntent_1.CARD_ONLY_STATUSES; } });
+Object.defineProperty(exports, "EXPIRABLE_STATUSES", { enumerable: true, get: function () { return paymentIntent_1.EXPIRABLE_STATUSES; } });
+Object.defineProperty(exports, "canExpire", { enumerable: true, get: function () { return paymentIntent_1.canExpire; } });
 var webhookSigner_1 = require("./webhookSigner");
 Object.defineProperty(exports, "signWebhook", { enumerable: true, get: function () { return webhookSigner_1.signWebhook; } });
 Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhookSigner_1.verifyWebhook; } });
@@ -32,3 +34,6 @@ var billing_authority_1 = require("./billing-authority");
 Object.defineProperty(exports, "canonicalBillingAuthority", { enumerable: true, get: function () { return billing_authority_1.canonicalBillingAuthority; } });
 Object.defineProperty(exports, "canonicalBillingTaxQuote", { enumerable: true, get: function () { return billing_authority_1.canonicalBillingTaxQuote; } });
 Object.defineProperty(exports, "PEABLE_BILLING_AUTHORITY_KEYS", { enumerable: true, get: function () { return billing_authority_1.PEABLE_BILLING_AUTHORITY_KEYS; } });
+var tax_1 = require("./tax");
+Object.defineProperty(exports, "TAX_REGISTRATION_SCHEMES", { enumerable: true, get: function () { return tax_1.TAX_REGISTRATION_SCHEMES; } });
+Object.defineProperty(exports, "TAX_LOCATION_EVIDENCE_TYPES", { enumerable: true, get: function () { return tax_1.TAX_LOCATION_EVIDENCE_TYPES; } });

package/dist/cjs/paymentIntent.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.POST_SETTLEMENT_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.CARD_ONLY_STATUSES = exports.CHAIN_ONLY_STATUSES = exports.PAYMENT_INTENT_RAILS = void 0;
+exports.EXPIRABLE_STATUSES = exports.POST_SETTLEMENT_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.CARD_ONLY_STATUSES = exports.CHAIN_ONLY_STATUSES = exports.PAYMENT_INTENT_RAILS = void 0;
 exports.isValidStatusTransition = isValidStatusTransition;
 exports.canStillBePaid = canStillBePaid;
 exports.reachesSettlementFromPayer = reachesSettlementFromPayer;
+exports.canExpire = canExpire;
 /** {@link PaymentIntentRail} as the tuple the database CHECK reads. */
 exports.PAYMENT_INTENT_RAILS = ['faircoin', 'card'];
 /**
@@ -205,3 +206,26 @@ function reachesSettlementFromPayer(status) {
     }
     return false;
 }
+/**
+ * The statuses an intent may still EXPIRE from (ADR 0012 D9).
+ *
+ * Exactly those whose transition list contains `expired`: the gateway is
+ * waiting on a PERSON who has not paid. Once a FairCoin payer has reported a
+ * broadcast (`broadcast`), or the chain is confirming it (`confirming`), the
+ * intent NEVER expires, whatever `expiresAt` says — coins are moving and the
+ * settlement watcher owns the row. A platform must therefore never cancel an
+ * order because `expiresAt` passed: it releases a reservation on
+ * `payment_intent.expired` (or `rejected`), and on nothing else.
+ *
+ * Stated rather than derived, for `PAYABLE_STATUSES`' reason; the gateway's
+ * test suite pins it against the transition table.
+ */
+exports.EXPIRABLE_STATUSES = [
+    'created',
+    'awaiting_approval',
+    'requires_action',
+];
+/** Whether an intent in this status can still expire. See {@link EXPIRABLE_STATUSES}. */
+function canExpire(status) {
+    return exports.EXPIRABLE_STATUSES.includes(status);
+}

package/dist/cjs/tax.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Peable Tax — the wire contract.
+ *
+ * Modelled on Stripe Tax and applied to every settlement rail (card, FairCoin,
+ * any further fiat provider). A merchant declares WHERE it is registered;
+ * Peable decides per sale whether a registration covers the customer's
+ * evidenced location, asks a tax provider for the amount only when one does,
+ * and freezes the answer. Registering with a government is the seller's job,
+ * never this code's.
+ *
+ * Amounts are integers in the currency's minor unit, like the billing quote.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = void 0;
+/** How a registration lets the seller collect. `standard`/`simplified` cover
+ * one country; the EU One-Stop-Shop schemes cover every EU member state from
+ * one identification state; the US is per state; Canadian PST/QST is per
+ * province. */
+exports.TAX_REGISTRATION_SCHEMES = [
+    'standard',
+    'simplified',
+    'eu_oss_union',
+    'eu_oss_non_union',
+    'us_state_sales_tax',
+    'ca_provincial',
+];
+/** Location evidence a jurisdiction accepts. There is deliberately no
+ * language, currency, locale or timezone: none of them is evidence of where a
+ * customer lives, and Peable cannot be told otherwise. */
+exports.TAX_LOCATION_EVIDENCE_TYPES = [
+    'billing_address',
+    'ip_address',
+    'payment_method_country',
+    'bank_country',
+    'sim_country',
+    'landline_country',
+];

package/dist/esm/connect.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.js

@@ -1,8 +1,9 @@
 // @peable.to/shared-types — public API for the Peable Gateway contract.
 export { UNITS_PER_COIN, isBaseUnitString, CURRENCY_CODES, CURRENCY_DECIMALS, decimalsFor, isCurrencyCode, } from './money.js';
-export { isValidStatusTransition, canStillBePaid, reachesSettlementFromPayer, POST_SETTLEMENT_STATUSES, PAYMENT_INTENT_STATUSES, PAYMENT_INTENT_RAILS, CHAIN_ONLY_STATUSES, CARD_ONLY_STATUSES, } from './paymentIntent.js';
+export { isValidStatusTransition, canStillBePaid, reachesSettlementFromPayer, POST_SETTLEMENT_STATUSES, PAYMENT_INTENT_STATUSES, PAYMENT_INTENT_RAILS, CHAIN_ONLY_STATUSES, CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, canExpire, } from './paymentIntent.js';
 export { signWebhook, verifyWebhook } from './webhookSigner.js';
 export { MERCHANT_ENVIRONMENTS, } from './merchant.js';
 export { SOCIAL_SOURCE_APP_MAX_LENGTH, SOCIAL_SOURCE_REF_MAX_LENGTH, } from './social.js';
 export { BILLING_SUBSCRIPTION_STATUSES, } from './billing.js';
 export { canonicalBillingAuthority, canonicalBillingTaxQuote, PEABLE_BILLING_AUTHORITY_KEYS, } from './billing-authority.js';
+export { TAX_REGISTRATION_SCHEMES, TAX_LOCATION_EVIDENCE_TYPES, } from './tax.js';

package/dist/esm/paymentIntent.js

@@ -199,3 +199,26 @@ export function reachesSettlementFromPayer(status) {
     }
     return false;
 }
+/**
+ * The statuses an intent may still EXPIRE from (ADR 0012 D9).
+ *
+ * Exactly those whose transition list contains `expired`: the gateway is
+ * waiting on a PERSON who has not paid. Once a FairCoin payer has reported a
+ * broadcast (`broadcast`), or the chain is confirming it (`confirming`), the
+ * intent NEVER expires, whatever `expiresAt` says — coins are moving and the
+ * settlement watcher owns the row. A platform must therefore never cancel an
+ * order because `expiresAt` passed: it releases a reservation on
+ * `payment_intent.expired` (or `rejected`), and on nothing else.
+ *
+ * Stated rather than derived, for `PAYABLE_STATUSES`' reason; the gateway's
+ * test suite pins it against the transition table.
+ */
+export const EXPIRABLE_STATUSES = [
+    'created',
+    'awaiting_approval',
+    'requires_action',
+];
+/** Whether an intent in this status can still expire. See {@link EXPIRABLE_STATUSES}. */
+export function canExpire(status) {
+    return EXPIRABLE_STATUSES.includes(status);
+}

package/dist/esm/tax.js

@@ -0,0 +1,35 @@
+/**
+ * Peable Tax — the wire contract.
+ *
+ * Modelled on Stripe Tax and applied to every settlement rail (card, FairCoin,
+ * any further fiat provider). A merchant declares WHERE it is registered;
+ * Peable decides per sale whether a registration covers the customer's
+ * evidenced location, asks a tax provider for the amount only when one does,
+ * and freezes the answer. Registering with a government is the seller's job,
+ * never this code's.
+ *
+ * Amounts are integers in the currency's minor unit, like the billing quote.
+ */
+/** How a registration lets the seller collect. `standard`/`simplified` cover
+ * one country; the EU One-Stop-Shop schemes cover every EU member state from
+ * one identification state; the US is per state; Canadian PST/QST is per
+ * province. */
+export const TAX_REGISTRATION_SCHEMES = [
+    'standard',
+    'simplified',
+    'eu_oss_union',
+    'eu_oss_non_union',
+    'us_state_sales_tax',
+    'ca_provincial',
+];
+/** Location evidence a jurisdiction accepts. There is deliberately no
+ * language, currency, locale or timezone: none of them is evidence of where a
+ * customer lives, and Peable cannot be told otherwise. */
+export const TAX_LOCATION_EVIDENCE_TYPES = [
+    'billing_address',
+    'ip_address',
+    'payment_method_country',
+    'bank_country',
+    'sim_country',
+    'landline_country',
+];

package/dist/types/billing.d.ts

@@ -1,3 +1,4 @@
+import type { BillingInvoiceTaxLine } from './tax';
 /** Recurring billing transport. Store/plan references belong to the authenticated app;
  * they do not identify an Oxy payer or convey entitlements. */
 export declare const BILLING_SUBSCRIPTION_STATUSES: readonly ["incomplete", "incomplete_expired", "trialing", "active", "past_due", "canceled", "unpaid", "paused"];
@@ -174,6 +175,9 @@ export interface BillingFinalInvoice {
         expiresAt: string;
         roundingEvidenceId: string;
     };
+    /** Present only when requested (`include: ['tax_lines']`): the frozen
+     * Peable Tax lines behind `taxMinorUnits`, covered by the same signature. */
+    taxLines?: BillingInvoiceTaxLine[];
 }
 export interface BillingFinalInvoiceAuthority {
     schemaVersion: 1;
@@ -227,6 +231,9 @@ export interface CreateBillingTaxQuoteParams {
     rail?: BillingRail;
     storeId: string;
     planId: string;
+    /** Selects one offer when a plan is sold at several prices. */
+    providerPriceId?: string;
+    /** A `tax.location_evidence` id (`taxloc_…`) recorded for this `storeId`. */
     customerLocationEvidenceId: string;
 }
 export interface BillingTaxQuote {

package/dist/types/checkoutSession.d.ts

@@ -15,6 +15,11 @@ export interface CheckoutSession {
     rail: PaymentIntentRail;
     /** FairCoin rail only; `null` on a card session. */
     network: NetworkType | null;
+    /**
+     * The seller the wrapped payment is made on behalf of (`ca_…`), or `null`
+     * (ADR 0012 D5). Optional in the type for older fixtures; always sent.
+     */
+    connectedAccountId?: string | null;
     metadata: Record<string, string>;
     successUrl?: string;
     cancelUrl?: string;
@@ -50,4 +55,6 @@ export interface CreateCheckoutSessionParams {
     metadata?: Record<string, string>;
     successUrl?: string;
     cancelUrl?: string;
+    /** Pay this seller (`ca_…`) rather than the merchant — see `CreatePaymentIntentParams.connectedAccount`. */
+    connectedAccount?: string;
 }

package/dist/types/connect.d.ts

@@ -0,0 +1,39 @@
+import type { MerchantDisplay } from './merchantDisplay';
+import type { NetworkType } from './network';
+/** `GET /v1/connect/onboarding/:token` — what the seller is being asked to do. */
+export interface ConnectOnboarding {
+    object: 'connect_onboarding';
+    /** The `ca_…` being onboarded. */
+    accountId: string;
+    /** Who is asking — the PLATFORM's public display, as a payer would see it. */
+    platform: MerchantDisplay;
+    /** The chain the seller will be paid on. Their key must be for this network. */
+    network: NetworkType;
+    /** When this link stops working. */
+    expiresAt: string;
+    /** Where to send the seller once the key is registered. */
+    returnUrl: string;
+}
+/** `POST /v1/connect/onboarding/:token/faircoin` — the seller's watch-only ACCOUNT xpub. */
+export interface RegisterFaircoinKeyParams {
+    /** A watch-only extended PUBLIC key. A private key is refused and never stored. */
+    xpub: string;
+}
+/** The answer to a successful registration. */
+export interface ConnectOnboardingComplete {
+    object: 'connect_onboarding';
+    accountId: string;
+    status: 'active';
+    returnUrl: string;
+}
+/**
+ * A FairCoin onboarding link, as the platform receives it from
+ * `POST /v1/connected_accounts/:id/account_links` with `rail: 'faircoin'`.
+ * Same shape as the card rail's link. Do not store it: it is single-use and
+ * expires — mint one when the seller is about to open it.
+ */
+export interface AccountLink {
+    object: 'account_link';
+    url: string;
+    expiresAt: string;
+}

package/dist/types/event.d.ts

@@ -117,6 +117,14 @@ export type WebhookEvent<K extends WebhookEventType = WebhookEventType> = {
         object: 'event';
         type: T;
         created: string;
+        /**
+         * The connected account (`ca_…`) this event is about — Stripe's
+         * `event.account` (ADR 0012 D7). Present on every event for an on-behalf
+         * payment and on `connected_account.updated`; absent on events about the
+         * merchant's own payments. Lets a platform route an event to a seller
+         * without opening `data.object`.
+         */
+        account?: string;
         data: {
             object: WebhookEventPayload[T];
         };

package/dist/types/index.d.ts

@@ -1,16 +1,18 @@
 export { UNITS_PER_COIN, isBaseUnitString, type CurrencyCode, CURRENCY_CODES, CURRENCY_DECIMALS, decimalsFor, isCurrencyCode, } from './money';
 export type { NetworkType } from './network';
-export { type PaymentIntentStatus, type PaymentIntentRail, type PaymentIntent, type CreatePaymentIntentParams, isValidStatusTransition, canStillBePaid, reachesSettlementFromPayer, POST_SETTLEMENT_STATUSES, PAYMENT_INTENT_STATUSES, PAYMENT_INTENT_RAILS, CHAIN_ONLY_STATUSES, CARD_ONLY_STATUSES, } from './paymentIntent';
+export { type PaymentIntentStatus, type PaymentIntentRail, type PaymentIntent, type CreatePaymentIntentParams, isValidStatusTransition, canStillBePaid, reachesSettlementFromPayer, POST_SETTLEMENT_STATUSES, PAYMENT_INTENT_STATUSES, PAYMENT_INTENT_RAILS, CHAIN_ONLY_STATUSES, CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, canExpire, } from './paymentIntent';
 export type { WebhookEventType, WebhookEvent, WebhookEventPayload, BillingObservation, } from './event';
 export type { Dispute, DisputeEvidence, DisputeStatus } from './dispute';
-export type { CapabilityStatus, ConnectedAccount, Refund, RefundOrigin, RefundStatus, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
+export type { CapabilityStatus, ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, Refund, RefundOrigin, RefundStatus, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
 export type { WebhookDelivery, WebhookDeliveryStatus, } from './webhookDelivery';
 export { signWebhook, verifyWebhook } from './webhookSigner';
 export { type MerchantEnvironment, type Merchant, MERCHANT_ENVIRONMENTS, } from './merchant';
 export type { MerchantDisplay } from './merchantDisplay';
+export type { AccountLink, ConnectOnboarding, ConnectOnboardingComplete, RegisterFaircoinKeyParams, } from './connect';
 export type { PaymentLink, PublicPaymentLink, CreatePaymentLinkParams, } from './paymentLink';
 export type { CheckoutSession, CheckoutSessionPublic, CreateCheckoutSessionParams, } from './checkoutSession';
 export { SOCIAL_SOURCE_APP_MAX_LENGTH, SOCIAL_SOURCE_REF_MAX_LENGTH, type SocialPaymentSource, type SocialNextAddressRequest, type SocialNextAddressResponse, type SocialReceiveCursorResponse, type SocialPaymentDirection, type SocialPayment, type SocialPaymentsResponse, type EnrichmentKind, type EnrichmentResult, type EnrichRequest, type EnrichResponse, } from './social';
 export { BILLING_SUBSCRIPTION_STATUSES, type BillingSubscriptionStatus, type CreateBillingTaxQuoteParams, type BillingTaxQuote, type BillingInvoiceAuthoritySource, type BillingFinalInvoice, type BillingFinalInvoiceAuthority, type BillingFaircoinRenewalChoice, type BillingFaircoinRenewalConsent, type BillingFaircoinRenewalRevocation, type BillingCheckoutSession, type BillingCheckoutObservation, type RetrieveBillingCheckoutOperationParams, type BillingCheckoutOperationSource, type BillingCheckoutOperationRecovery, type BillingPaidInvoice, type BillingInvoiceState, type BillingCustomer, type BillingRail, type BillingRailSettlement, type BillingRailOffer, type BillingRailOption, type BillingRailList, type EnsureBillingCustomerParams, type CreateBillingCheckoutParams, type CreateBillingPortalParams, type BillingHostedSession, type BillingSubscription, } from './billing';
 export { canonicalBillingAuthority, canonicalBillingTaxQuote, PEABLE_BILLING_AUTHORITY_KEYS, } from './billing-authority';
 export type { BillingFaircoinFxQuote } from './billing';
+export { TAX_REGISTRATION_SCHEMES, TAX_LOCATION_EVIDENCE_TYPES, type TaxRegistrationScheme, type TaxLocationEvidenceType, type TaxBehavior, type TaxAddress, type TaxCode, type TaxCalculationAccount, type TaxSettings, type UpdateTaxSettingsParams, type TaxRegistration, type CreateTaxRegistrationParams, type TaxProductCode, type TaxLocationEvidenceItem, type CreateTaxLocationEvidenceParams, type TaxLocationEvidence, type TaxLineItemParams, type CreateTaxCalculationParams, type TaxBreakdownEntry, type TaxCalculationLineItem, type TaxCalculation, type TaxTransaction, type TaxTransactionList, type TaxTransactionReversal, type CreateTaxReversalParams, type ListTaxTransactionsParams, type TaxReportRow, type TaxReport, type BillingInvoiceTaxLine, } from './tax';

package/dist/types/merchant.d.ts

@@ -26,7 +26,10 @@ export interface Merchant {
      * the raw values the merchant owns.
      */
     displayName?: string;
-    /** Bare Oxy file id, not a URL. `MerchantDisplay.avatarUrl` resolves it. */
+    /**
+     * Bare Oxy file id, not a URL. `MerchantDisplay.avatarUrl` resolves it.
+     * Absent again once Oxy reports the file deleted or taken down.
+     */
     avatarFileId?: string;
     description?: string;
     createdAt: string;

package/dist/types/paymentIntent.d.ts

@@ -52,6 +52,23 @@ export declare const POST_SETTLEMENT_STATUSES: readonly PaymentIntentStatus[];
  * the thing that checks it rather than as the thing that answers it.
  */
 export declare function reachesSettlementFromPayer(status: PaymentIntentStatus): boolean;
+/**
+ * The statuses an intent may still EXPIRE from (ADR 0012 D9).
+ *
+ * Exactly those whose transition list contains `expired`: the gateway is
+ * waiting on a PERSON who has not paid. Once a FairCoin payer has reported a
+ * broadcast (`broadcast`), or the chain is confirming it (`confirming`), the
+ * intent NEVER expires, whatever `expiresAt` says — coins are moving and the
+ * settlement watcher owns the row. A platform must therefore never cancel an
+ * order because `expiresAt` passed: it releases a reservation on
+ * `payment_intent.expired` (or `rejected`), and on nothing else.
+ *
+ * Stated rather than derived, for `PAYABLE_STATUSES`' reason; the gateway's
+ * test suite pins it against the transition table.
+ */
+export declare const EXPIRABLE_STATUSES: readonly PaymentIntentStatus[];
+/** Whether an intent in this status can still expire. See {@link EXPIRABLE_STATUSES}. */
+export declare function canExpire(status: PaymentIntentStatus): boolean;
 export interface PaymentIntent {
     id: string;
     object: 'payment_intent';
@@ -73,12 +90,34 @@ export interface PaymentIntent {
      */
     address: string | null;
     merchantId: string;
+    /**
+     * The seller this payment is made ON BEHALF OF (`ca_…`), or `null` for a
+     * payment to the merchant itself (ADR 0012 D5). On-behalf payments are
+     * FairCoin only, and `address` derives from that seller's own key.
+     *
+     * Optional in the type only so fixtures written against earlier versions
+     * still compile; a gateway at this version always sends it.
+     */
+    connectedAccountId?: string | null;
     txid: string | null;
     /** On-chain confirmations. Structurally `0` for the whole life of a card payment. */
     confirmations: number;
     clientSecret: string;
     metadata: Record<string, string>;
+    /**
+     * When an UNPAID intent expires. Meaningful only while {@link canExpire}
+     * is true for `status` — see `canExpire` below.
+     */
     expiresAt: string;
+    /**
+     * Whether this intent can still expire (ADR 0012 D9). `false` once the payer
+     * has reported a broadcast: a FairCoin payment that is `broadcast` or
+     * `confirming` NEVER expires, so a platform must not cancel the order for it.
+     *
+     * Optional in the type only for fixtures written against earlier versions;
+     * a gateway at this version always sends it.
+     */
+    canExpire?: boolean;
     createdAt: string;
     updatedAt: string;
 }
@@ -96,4 +135,12 @@ export interface CreatePaymentIntentParams {
     currency?: CurrencyCode;
     metadata?: Record<string, string>;
     expiresInSeconds?: number;
+    /**
+     * Create the payment ON BEHALF OF this connected account (`ca_…`) — the
+     * address derives from the seller's own key and the coins go straight to
+     * their wallet (ADR 0012 D5). FairCoin only: combined with `rail: 'card'` it
+     * is refused. The account's FairCoin half must be `active` and `network`
+     * must be the account's network.
+     */
+    connectedAccount?: string;
 }

package/dist/types/settlement.d.ts

@@ -1,20 +1,66 @@
 import type { CurrencyCode } from './money';
+import type { NetworkType } from './network';
 /** How a provider reports one capability on a seller's account. */
 export type CapabilityStatus = 'active' | 'pending' | 'inactive';
 /** Where one settlement stands. */
 export type TransferStatus = 'pending' | 'paid' | 'partially_reversed' | 'reversed' | 'failed';
 /** Where one reversal of a settlement stands. */
 export type TransferReversalStatus = 'pending' | 'succeeded' | 'failed';
+/**
+ * Which rails a seller's account was opened for (ADR 0012 D1).
+ *
+ * One seller is ONE `ca_…`: `card` is the provider account a marketplace
+ * settles to by transfer, `faircoin` is the seller's own watch-only key that
+ * on-behalf FairCoin payments derive their addresses from.
+ */
+export type ConnectedAccountRail = 'card' | 'faircoin';
+/**
+ * Where a seller's FairCoin half stands.
+ *
+ * `pending` — the platform opened it and the seller has not registered a key
+ * yet; an on-behalf payment is refused (`account_not_ready`). `active` — the
+ * seller registered their key; payments derive addresses from it.
+ */
+export type ConnectedAccountFaircoinStatus = 'pending' | 'active';
+/**
+ * The FairCoin half of a seller's account.
+ *
+ * The seller's xpub is deliberately ABSENT (ADR 0012 D6): an account xpub
+ * reveals every address of that account, so a platform holding it would learn
+ * the seller's whole history and balance. Nothing a platform does needs it —
+ * each payment carries its own address.
+ */
+export interface ConnectedAccountFaircoin {
+    /** The chain the seller is paid on. Fixed when the platform opened the half. */
+    network: NetworkType;
+    status: ConnectedAccountFaircoinStatus;
+    /** The Oxy user who may register the key — and, once `active`, who did. */
+    oxyUserId: string;
+    /** When the seller registered their key. `null` while `pending`. */
+    registeredAt: string | null;
+}
 export interface ConnectedAccount {
     id: string;
     object: 'connected_account';
     /** The merchant's OWN id for this seller — how they address it. */
     externalRef: string;
-    /** ISO 3166-1 alpha-2, upper-case. */
-    country: string;
+    /** Which halves this account has. Never empty. */
+    rails: readonly ConnectedAccountRail[];
+    /**
+     * The FairCoin half, or `null` when the platform never opened one.
+     * Readiness for FairCoin is `faircoin?.status === 'active'`; `payable` below
+     * is about the CARD half's settlements and says nothing about FairCoin.
+     */
+    faircoin: ConnectedAccountFaircoin | null;
+    /**
+     * ISO 3166-1 alpha-2, upper-case. `null` on a FairCoin-only seller, which has
+     * no card half and was never asked for one (ADR 0012 D1).
+     */
+    country: string | null;
     defaultCurrency: string | null;
     /**
-     * Whether this seller can receive a settlement right now.
+     * Whether this seller can receive a CARD settlement (a transfer) right now.
+     * Always `false` on a FairCoin-only seller.
      *
      * A CONVENIENCE, not the authority: every field it is derived from is here
      * too, and a marketplace with its own readiness policy reads those instead.

package/dist/types/tax.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Peable Tax — the wire contract.
+ *
+ * Modelled on Stripe Tax and applied to every settlement rail (card, FairCoin,
+ * any further fiat provider). A merchant declares WHERE it is registered;
+ * Peable decides per sale whether a registration covers the customer's
+ * evidenced location, asks a tax provider for the amount only when one does,
+ * and freezes the answer. Registering with a government is the seller's job,
+ * never this code's.
+ *
+ * Amounts are integers in the currency's minor unit, like the billing quote.
+ */
+/** How a registration lets the seller collect. `standard`/`simplified` cover
+ * one country; the EU One-Stop-Shop schemes cover every EU member state from
+ * one identification state; the US is per state; Canadian PST/QST is per
+ * province. */
+export declare const TAX_REGISTRATION_SCHEMES: readonly ["standard", "simplified", "eu_oss_union", "eu_oss_non_union", "us_state_sales_tax", "ca_provincial"];
+export type TaxRegistrationScheme = (typeof TAX_REGISTRATION_SCHEMES)[number];
+/** Location evidence a jurisdiction accepts. There is deliberately no
+ * language, currency, locale or timezone: none of them is evidence of where a
+ * customer lives, and Peable cannot be told otherwise. */
+export declare const TAX_LOCATION_EVIDENCE_TYPES: readonly ["billing_address", "ip_address", "payment_method_country", "bank_country", "sim_country", "landline_country"];
+export type TaxLocationEvidenceType = (typeof TAX_LOCATION_EVIDENCE_TYPES)[number];
+export type TaxBehavior = 'inclusive' | 'exclusive';
+export interface TaxAddress {
+    /** ISO 3166-1 alpha-2. */
+    country: string;
+    /** ISO 3166-2 subdivision without the country prefix (`CA`, `QC`). */
+    state?: string | null;
+    postalCode?: string | null;
+    city?: string | null;
+    line1?: string | null;
+    line2?: string | null;
+}
+export interface TaxCode {
+    id: string;
+    name: string;
+    description: string;
+}
+/** Which provider account calculates for this merchant. `platform`: Peable's
+ * own provider account, available only to official Oxy applications, whose
+ * seller is the platform's legal entity. `none`: no provider; sales in a
+ * registered jurisdiction cannot be calculated and fail closed. */
+export type TaxCalculationAccount = 'platform' | 'none';
+export interface TaxSettings {
+    object: 'tax.settings';
+    merchantId: string;
+    /** `active` once the owner approved; any edit returns it to `draft`. */
+    status: 'draft' | 'active';
+    legalName: string | null;
+    headOffice: TaxAddress | null;
+    defaultTaxCode: string;
+    defaultTaxBehavior: TaxBehavior;
+    calculationAccount: TaxCalculationAccount;
+    /** The provider that calculates registered sales, when one is reachable. */
+    provider: string | null;
+    approvedAt: string | null;
+    approvedBy: string | null;
+    updatedAt: string | null;
+}
+export interface UpdateTaxSettingsParams {
+    legalName?: string | null;
+    headOffice?: TaxAddress | null;
+    defaultTaxCode?: string;
+    defaultTaxBehavior?: TaxBehavior;
+}
+export interface TaxRegistration {
+    object: 'tax.registration';
+    id: string;
+    country: string;
+    state: string | null;
+    scheme: TaxRegistrationScheme;
+    /** The government-issued number (VAT id, state permit), when there is one. */
+    registrationNumber: string | null;
+    activeFrom: string;
+    expiresAt: string | null;
+    /** `pending_approval` until the owner approves; `scheduled` before activeFrom. */
+    status: 'pending_approval' | 'scheduled' | 'active' | 'expired';
+    approvedAt: string | null;
+    /** The mirrored registration at the calculating provider, once synced. */
+    providerRegistrationRef: string | null;
+    createdAt: string;
+}
+export interface CreateTaxRegistrationParams {
+    country: string;
+    state?: string | null;
+    scheme: TaxRegistrationScheme;
+    registrationNumber?: string | null;
+    /** ISO timestamp; omitted means immediately on approval. */
+    activeFrom?: string;
+    expiresAt?: string | null;
+}
+export interface TaxProductCode {
+    object: 'tax.product';
+    /** The merchant's product or plan reference (a billing `planId`). */
+    productRef: string;
+    taxCode: string;
+    updatedAt: string;
+}
+export type TaxLocationEvidenceItem = {
+    type: 'billing_address';
+    address: TaxAddress;
+} | {
+    type: 'ip_address';
+    ipAddress: string;
+    country: string;
+    state?: string | null;
+} | {
+    type: 'payment_method_country' | 'bank_country' | 'sim_country' | 'landline_country';
+    country: string;
+};
+export interface CreateTaxLocationEvidenceParams {
+    /** The customer this evidence is about; for billing, the `storeId`. */
+    customerRef: string;
+    evidence: TaxLocationEvidenceItem[];
+}
+export interface TaxLocationEvidence {
+    object: 'tax.location_evidence';
+    id: string;
+    customerRef: string;
+    /** Only `sufficient` evidence can be calculated against. */
+    status: 'sufficient' | 'insufficient' | 'conflicting';
+    /** The jurisdiction rule applied, e.g. `eu_digital_two_items`. */
+    rule: string;
+    country: string | null;
+    state: string | null;
+    items: {
+        type: TaxLocationEvidenceType;
+        country: string;
+        state: string | null;
+    }[];
+    observedAt: string;
+    expiresAt: string;
+    livemode: boolean;
+}
+export interface TaxLineItemParams {
+    reference: string;
+    /** Unit amount × quantity, minor units. Includes tax when inclusive. */
+    amount: number;
+    quantity?: number;
+    /** Defaults to the product's tax code, then the merchant's default. */
+    taxCode?: string;
+    /** Defaults to the merchant's default tax behavior. */
+    taxBehavior?: TaxBehavior;
+}
+export interface CreateTaxCalculationParams {
+    currency: string;
+    customerLocationEvidenceId: string;
+    lineItems: TaxLineItemParams[];
+}
+export interface TaxBreakdownEntry {
+    country: string;
+    state: string | null;
+    level: string | null;
+    displayName: string | null;
+    taxType: string | null;
+    /** Decimal string, e.g. `"20.0"`; null when no tax is imposed. */
+    ratePercentage: string | null;
+    taxableAmount: number;
+    amount: number;
+    inclusive: boolean;
+    /** Provider reason, or Peable's own `not_registered` / `product_nontaxable`. */
+    taxabilityReason: string;
+}
+export interface TaxCalculationLineItem {
+    reference: string;
+    quantity: number;
+    taxCode: string;
+    taxBehavior: TaxBehavior;
+    /** As given: includes tax when inclusive. */
+    amount: number;
+    amountTax: number;
+    /** Excluding tax. */
+    amountNet: number;
+    breakdown: TaxBreakdownEntry[];
+}
+/** A frozen answer. `collection` says why the tax is what it is:
+ * `collect` (a registration covers the customer and the provider calculated),
+ * `not_registered` (no registration covers them: zero tax, recorded as such),
+ * `nontaxable` (every line used the nontaxable code). */
+export interface TaxCalculation {
+    object: 'tax.calculation';
+    id: string;
+    currency: string;
+    collection: 'collect' | 'not_registered' | 'nontaxable';
+    registrationId: string | null;
+    provider: string | null;
+    providerCalculationRef: string | null;
+    customerLocationEvidenceId: string;
+    country: string;
+    state: string | null;
+    /** What the customer pays. */
+    amountTotal: number;
+    amountNet: number;
+    taxAmountExclusive: number;
+    taxAmountInclusive: number;
+    lineItems: TaxCalculationLineItem[];
+    taxDate: string;
+    createdAt: string;
+    expiresAt: string;
+    livemode: boolean;
+}
+/** What a reversal gave back: the original calculation's amounts, scaled to
+ * the refunded share and NEGATIVE (positive only when it reinstates an earlier
+ * reversal, e.g. a refund the bank later failed). */
+export interface TaxTransactionReversal {
+    amountTotal: number;
+    amountNet: number;
+    taxAmount: number;
+    lineItems: TaxCalculationLineItem[];
+}
+/** A calculation that was paid. Created by Peable when the payment it priced
+ * is accepted on its rail; the report and filings are built from these.
+ *
+ * `type: "reversal"` is a refund (or credit note) of an earlier transaction,
+ * `reversalOf` names it, and `reversal` holds its signed amounts. The report
+ * nets reversals into the rows of the original. */
+export interface TaxTransaction {
+    object: 'tax.transaction';
+    id: string;
+    type: 'transaction' | 'reversal';
+    calculationId: string;
+    /** The rail's own object, e.g. the invoice id. */
+    reference: string;
+    rail: string;
+    committedAt: string;
+    /** The original transaction's id, for a reversal. */
+    reversalOf: string | null;
+    reversal: TaxTransactionReversal | null;
+    calculation: TaxCalculation;
+}
+/** Record a refund made outside Peable (a FairCoin rail payment is refunded
+ * from the seller's own wallet, never by the gateway). Card refunds and credit
+ * notes are observed from the provider instead. */
+export interface CreateTaxReversalParams {
+    /** The refund's own reference; a repeated reference returns the same reversal. */
+    reference: string;
+    /** Gross minor units refunded (what the payer got back). Omitted: everything
+     * that is not yet reversed. */
+    amount?: number;
+}
+export interface TaxTransactionList {
+    object: 'list';
+    data: TaxTransaction[];
+    hasMore: boolean;
+}
+export interface ListTaxTransactionsParams {
+    /** Inclusive ISO timestamp. */
+    from: string;
+    /** Exclusive ISO timestamp. */
+    to: string;
+    limit?: number;
+    startingAfter?: string;
+}
+/** One filing line: totals per jurisdiction, registration, tax type and rate. */
+export interface TaxReportRow {
+    country: string;
+    state: string | null;
+    registrationId: string | null;
+    scheme: TaxRegistrationScheme | null;
+    collection: TaxCalculation['collection'];
+    taxType: string | null;
+    ratePercentage: string | null;
+    currency: string;
+    transactions: number;
+    /** Reversals netted into this row; `taxableAmount` and `taxAmount` are net. */
+    reversals: number;
+    taxableAmount: number;
+    taxAmount: number;
+}
+export interface TaxReport {
+    object: 'tax.report';
+    from: string;
+    to: string;
+    rows: TaxReportRow[];
+}
+/** One tax line on a signed final invoice (`include: ['tax_lines']`). */
+export interface BillingInvoiceTaxLine {
+    calculationId: string;
+    country: string;
+    state: string | null;
+    taxType: string | null;
+    ratePercentage: string | null;
+    taxableMinorUnits: number;
+    taxMinorUnits: number;
+    inclusive: boolean;
+    taxabilityReason: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Shared TypeScript types for the Peable Gateway — the wire contract shared by the backend, SDK, and frontend.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -24,6 +24,18 @@
       },
       "default": "./dist/esm/index.js"
     },
+    "./tax": {
+      "react-native": "./dist/esm/tax.js",
+      "import": {
+        "types": "./dist/types/tax.d.ts",
+        "default": "./dist/esm/tax.js"
+      },
+      "require": {
+        "types": "./dist/types/tax.d.ts",
+        "default": "./dist/cjs/tax.js"
+      },
+      "default": "./dist/esm/tax.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -54,8 +66,7 @@
     "clean": "rm -rf dist",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
-    "test": "bun test",
-    "prepublishOnly": "bun run clean && bun run build"
+    "test": "bun test"
   },
   "devDependencies": {
     "typescript": "~5.9.2",
@@ -63,6 +74,6 @@
     "@types/bun": "latest"
   },
   "dependencies": {
-    "@peable.to/contracts": "0.1.0"
+    "@peable.to/contracts": "0.2.1"
   }
 }