@peable.to/shared-types 0.5.1 → 0.7.0

package/dist/cjs/billing-authority.js

@@ -25,7 +25,7 @@ function encode(value) {
 }
 function canonicalBillingAuthority(authority) {
     return encode({
-        schemaVersion: authority.schemaVersion,
+        schema_version: authority.schema_version,
         source: authority.source,
         invoice: authority.invoice,
         method: authority.method,
@@ -33,7 +33,7 @@ function canonicalBillingAuthority(authority) {
 }
 function canonicalBillingTaxQuote(authority) {
     return encode({
-        schemaVersion: authority.schemaVersion,
+        schema_version: authority.schema_version,
         source: authority.source,
         quote: authority.quote,
     });

package/dist/cjs/dispute.js

@@ -1,17 +1,2 @@
 "use strict";
-/**
- * A dispute — the card network holding a settled payment's money while a
- * cardholder contests it.
- *
- * Published because `payment_intent.disputed` and `payment_intent.dispute_closed`
- * carry it as their `data.object`. It was route-local at first, with the webhook
- * carrying the PaymentIntent and the detail reachable only through
- * `GET /v1/payment_intents/:id/disputes`. That was inconsistent with the reason
- * those two events exist: `disputed` is a DEADLINE, and a merchant who has to
- * make a second call to learn when evidence is due is a merchant who can miss it
- * while their integration is working exactly as documented.
- *
- * It is also what the provider does. Stripe's `charge.dispute.created` carries
- * the dispute, not the charge — the parity was half-applied.
- */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/list.js

@@ -0,0 +1,3 @@
+"use strict";
+// The one list contract (ADR 0014 D1), for every list endpoint.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/tax.js

@@ -1,4 +1,6 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = void 0;
 /**
  * Peable Tax — the wire contract.
  *
@@ -11,8 +13,6 @@
  *
  * 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

package/dist/esm/billing-authority.js

@@ -20,7 +20,7 @@ function encode(value) {
 }
 export function canonicalBillingAuthority(authority) {
     return encode({
-        schemaVersion: authority.schemaVersion,
+        schema_version: authority.schema_version,
         source: authority.source,
         invoice: authority.invoice,
         method: authority.method,
@@ -28,7 +28,7 @@ export function canonicalBillingAuthority(authority) {
 }
 export function canonicalBillingTaxQuote(authority) {
     return encode({
-        schemaVersion: authority.schemaVersion,
+        schema_version: authority.schema_version,
         source: authority.source,
         quote: authority.quote,
     });

package/dist/esm/dispute.js

@@ -1,16 +1 @@
-/**
- * A dispute — the card network holding a settled payment's money while a
- * cardholder contests it.
- *
- * Published because `payment_intent.disputed` and `payment_intent.dispute_closed`
- * carry it as their `data.object`. It was route-local at first, with the webhook
- * carrying the PaymentIntent and the detail reachable only through
- * `GET /v1/payment_intents/:id/disputes`. That was inconsistent with the reason
- * those two events exist: `disputed` is a DEADLINE, and a merchant who has to
- * make a second call to learn when evidence is due is a merchant who can miss it
- * while their integration is working exactly as documented.
- *
- * It is also what the provider does. Stripe's `charge.dispute.created` carries
- * the dispute, not the charge — the parity was half-applied.
- */
 export {};

package/dist/esm/list.js

@@ -0,0 +1,2 @@
+// The one list contract (ADR 0014 D1), for every list endpoint.
+export {};

package/dist/types/billing-authority.d.ts

@@ -1,6 +1,6 @@
 import type { BillingFinalInvoiceAuthority, BillingTaxQuote } from './billing';
-export declare function canonicalBillingAuthority(authority: Pick<BillingFinalInvoiceAuthority, 'schemaVersion' | 'source' | 'invoice' | 'method'>): string;
-export declare function canonicalBillingTaxQuote(authority: Pick<BillingTaxQuote, 'schemaVersion' | 'source' | 'quote'>): string;
+export declare function canonicalBillingAuthority(authority: Pick<BillingFinalInvoiceAuthority, 'schema_version' | 'source' | 'invoice' | 'method'>): string;
+export declare function canonicalBillingTaxQuote(authority: Pick<BillingTaxQuote, 'schema_version' | 'source' | 'quote'>): string;
 /**
  * The PUBLIC halves of the Ed25519 keys production Peable signs billing
  * authority with (signed tax quotes and final invoice authorities), by key id.

package/dist/types/billing.d.ts

@@ -4,7 +4,7 @@ import type { BillingInvoiceTaxLine } from './tax';
 export declare const BILLING_SUBSCRIPTION_STATUSES: readonly ["incomplete", "incomplete_expired", "trialing", "active", "past_due", "canceled", "unpaid", "paused"];
 export type BillingSubscriptionStatus = (typeof BILLING_SUBSCRIPTION_STATUSES)[number];
 export interface BillingCustomer {
-    providerCustomerId: string;
+    provider_customer_id: string;
 }
 /** A settlement rail a merchant's recurring offers can be paid through. `stripe`
  * (and any further fiat provider) settles in fiat; `faircoin` settles natively
@@ -16,12 +16,12 @@ export type BillingRailSettlement = 'fiat' | 'faircoin';
 /** One offer a rail can sell. Fiat provider rails bind their prices from the
  * app's own provider catalogue, so they list `offers: null`. */
 export interface BillingRailOffer {
-    providerPriceId: string;
-    planId: string;
+    provider_price_id: string;
+    plan_id: string;
     interval: 'month' | 'year';
     currency: string;
-    grossMinorUnits: number;
-    taxTreatment: 'inclusive' | 'exclusive';
+    gross_minor_units: number;
+    tax_treatment: 'inclusive' | 'exclusive';
 }
 export interface BillingRailOption {
     rail: BillingRail;
@@ -29,7 +29,7 @@ export interface BillingRailOption {
     /** The rail a request that names none is served by: the first configured. */
     default: boolean;
     /** Whether `createTaxQuote` is answered for this rail. */
-    taxQuotes: boolean;
+    tax_quotes: boolean;
     /** `automatic`: the provider charges each period. `payer_initiated`: each
      * period is an explicit payment through `renewSubscription`. */
     renewal: 'automatic' | 'payer_initiated';
@@ -40,8 +40,8 @@ export interface BillingRailList {
     data: BillingRailOption[];
 }
 export interface EnsureBillingCustomerParams {
-    storeId: string;
-    storeName: string;
+    store_id: string;
+    store_name: string;
     /** The payer's chosen rail. Omitted: the merchant's default rail. A customer
      * belongs to one rail, and its checkouts and subscriptions follow it. */
     rail?: BillingRail;
@@ -51,41 +51,41 @@ export interface CreateBillingCheckoutParams {
     rail?: BillingRail;
     /** Opt-in fiscal checkout. The full signed quote is immutable and single-use.
      * Requires a trusted Peable adapter capable of applying these exact amounts. */
-    taxQuote?: BillingTaxQuote;
-    providerCustomerId: string;
-    providerPriceId: string;
-    trialDays: number;
-    returnUrl: string;
-    storeId: string;
-    planId: string;
+    tax_quote?: BillingTaxQuote;
+    provider_customer_id: string;
+    provider_price_id: string;
+    trial_days: number;
+    return_url: string;
+    store_id: string;
+    plan_id: string;
 }
 export interface CreateBillingPortalParams {
-    providerCustomerId: string;
-    returnUrl: string;
+    provider_customer_id: string;
+    return_url: string;
 }
 /** Sensitive owner-only URL. The gateway refuses replay after expiresAt. */
 export interface BillingHostedSession {
     url: string;
-    expiresAt: string;
+    expires_at: number;
 }
 /** Provider observations only. Consumers own plan/status/entitlement interpretation. */
 export interface BillingSubscription {
-    providerSubscriptionId: string;
+    provider_subscription_id: string;
     /** Discovery only; invoice must still be read and proven paid. */
-    latestInvoiceId?: string | null;
-    providerCustomerId: string;
-    providerPriceId: string;
-    storeId: string;
-    planId: string;
+    latest_invoice_id?: string | null;
+    provider_customer_id: string;
+    provider_price_id: string;
+    store_id: string;
+    plan_id: string;
     livemode: boolean;
     status: BillingSubscriptionStatus;
     interval: 'month' | 'year';
-    cancelAtPeriodEnd: boolean;
-    currentPeriodStart: string;
-    currentPeriodEnd: string;
-    trialEndsAt: string | null;
-    cancelAt: string | null;
-    cancelledAt: string | null;
+    cancel_at_period_end: boolean;
+    current_period_start: number;
+    current_period_end: number;
+    trial_ends_at: number | null;
+    cancel_at: number | null;
+    cancelled_at: number | null;
 }
 /** Owned recurring checkout correlation; completing checkout is not paid evidence. */
 export interface BillingCheckoutSession extends BillingHostedSession {
@@ -93,101 +93,101 @@ export interface BillingCheckoutSession extends BillingHostedSession {
 }
 export interface BillingCheckoutObservation {
     /** Immutable subscription_create invoice proven for this exact checkout. Discovery only, never paid authority. */
-    initialInvoiceId: string | null;
+    initial_invoice_id: string | null;
     id: string;
     status: 'open' | 'complete' | 'expired';
-    storeId: string;
-    planId: string;
-    providerCustomerId: string;
-    providerPriceId: string;
+    store_id: string;
+    plan_id: string;
+    provider_customer_id: string;
+    provider_price_id: string;
     subscription: BillingSubscription | null;
 }
 /** Authenticated authoritative read, one settled full non-prorated line only.
  * Tax figures are provider observations, not a tax quote or seller configuration. */
 export interface BillingInvoiceState extends BillingPaidInvoice {
-    chargeId: string;
-    amountRefunded: string;
+    charge_id: string;
+    amount_refunded: string;
     state: 'paid' | 'fully_refunded' | 'partially_refunded';
 }
 export interface BillingPaidInvoice {
-    invoiceId: string;
-    lineId: string;
-    paymentIntentId: string;
-    providerSubscriptionId: string;
-    providerCustomerId: string;
-    providerPriceId: string;
-    storeId: string;
-    planId: string;
+    invoice_id: string;
+    line_id: string;
+    payment_intent_id: string;
+    provider_subscription_id: string;
+    provider_customer_id: string;
+    provider_price_id: string;
+    store_id: string;
+    plan_id: string;
     livemode: boolean;
     currency: string;
-    amountPaid: string;
-    netAmount: string | null;
-    taxAmount: string | null;
-    periodStart: string;
-    periodEnd: string;
-    paidAt: string;
-    observedAt: string;
+    amount_paid: string;
+    net_amount: string | null;
+    tax_amount: string | null;
+    period_start: number;
+    period_end: number;
+    paid_at: number;
+    observed_at: number;
 }
 /** Provider-independent fiscal evidence. Values come from the configured authority,
  * never from invoice amounts, merchant metadata, or an application tax guess. */
 export interface BillingInvoiceAuthoritySource {
-    invoiceId: string;
-    paymentIntentId: string;
-    customerId: string;
-    subscriptionId: string;
-    priceId: string;
-    planId: string;
-    merchantId: string;
-    appId: string;
+    invoice_id: string;
+    payment_intent_id: string;
+    customer_id: string;
+    subscription_id: string;
+    price_id: string;
+    plan_id: string;
+    merchant_id: string;
+    app_id: string;
     mode: 'test' | 'live';
     environment: 'development' | 'staging' | 'production';
 }
 export interface BillingFinalInvoice {
     platform: 'peable';
     currency: string;
-    grossMinorUnits: number;
-    netMinorUnits: number;
-    taxMinorUnits: number;
-    merchantFeeMinorUnits: number;
-    taxTreatment: 'inclusive' | 'exclusive';
-    sellerId: string;
-    invoiceIssuerId: string;
-    taxQuoteId: string;
-    customerLocationEvidenceId: string;
-    taxRateEvidenceId: string;
+    gross_minor_units: number;
+    net_minor_units: number;
+    tax_minor_units: number;
+    merchant_fee_minor_units: number;
+    tax_treatment: 'inclusive' | 'exclusive';
+    seller_id: string;
+    invoice_issuer_id: string;
+    tax_quote_id: string;
+    customer_location_evidence_id: string;
+    tax_rate_evidence_id: string;
     context: {
-        payerAccountId: string;
-        beneficiaryAccountId: string;
-        providerSubscriptionId: string;
-        offerId: string;
-        offerVersion: number;
-        periodStart: string;
-        periodEnd: string;
+        payer_account_id: string;
+        beneficiary_account_id: string;
+        provider_subscription_id: string;
+        offer_id: string;
+        offer_version: number;
+        period_start: number;
+        period_end: number;
         mode: 'test' | 'live';
         environment: 'development' | 'staging' | 'production';
     };
-    issuedAt: string;
-    expiresAt: string;
-    faircoinQuote?: {
+    issued_at: number;
+    expires_at: number;
+    faircoin_quote?: {
         id: string;
-        amountBaseUnits: string;
-        quotedAt: string;
-        expiresAt: string;
-        roundingEvidenceId: string;
+        amount_base_units: string;
+        quoted_at: number;
+        expires_at: number;
+        rounding_evidence_id: string;
     };
     /** Present only when requested (`include: ['tax_lines']`): the frozen
      * Peable Tax lines behind `taxMinorUnits`, covered by the same signature. */
-    taxLines?: BillingInvoiceTaxLine[];
+    tax_lines?: BillingInvoiceTaxLine[];
 }
 export interface BillingFinalInvoiceAuthority {
-    schemaVersion: 1;
+    schema_version: 2;
     source: BillingInvoiceAuthoritySource;
     invoice: BillingFinalInvoice;
     method: 'card' | 'faircoin';
     /** Versioned canonical payload: source, invoice and method after strict schema parsing. */
     signature: {
         algorithm: 'Ed25519';
-        keyId: string;
+        key_id: string;
         value: string;
     };
 }
@@ -202,87 +202,87 @@ export type BillingFaircoinRenewalChoice = {
     consent: BillingFaircoinRenewalConsent;
 };
 export interface BillingFaircoinRenewalConsent {
-    authorizationId: string;
-    payerAccountId: string;
-    merchantId: string;
-    appId: string;
-    subscriptionId: string;
-    planId: string;
+    authorization_id: string;
+    payer_account_id: string;
+    merchant_id: string;
+    app_id: string;
+    subscription_id: string;
+    plan_id: string;
     mode: 'test' | 'live';
     environment: 'development' | 'staging' | 'production';
-    explicitConsent: true;
-    consentEvidenceId: string;
-    maximumAmountBaseUnits: string;
+    explicit_consent: true;
+    consent_evidence_id: string;
+    maximum_amount_base_units: string;
     interval: 'month';
-    intervalCount: 1;
-    startsAt: string;
-    expiresAt: string;
-    acceptedAt: string;
+    interval_count: 1;
+    starts_at: number;
+    expires_at: number;
+    accepted_at: number;
 }
 export interface BillingFaircoinRenewalRevocation {
-    authorizationId: string;
-    revokedAt: string;
-    revocationEvidenceId: string;
+    authorization_id: string;
+    revoked_at: number;
+    revocation_evidence_id: string;
 }
 /** A merchant asks Peable to quote a registered product. Monetary/fiscal
  * configuration is resolved inside Peable, never supplied by a consumer. */
 export interface CreateBillingTaxQuoteParams {
     /** Omitted: the first of the merchant's rails that answers tax quotes. */
     rail?: BillingRail;
-    storeId: string;
-    planId: string;
+    store_id: string;
+    plan_id: string;
     /** Selects one offer when a plan is sold at several prices. */
-    providerPriceId?: string;
+    provider_price_id?: string;
     /** A `tax.location_evidence` id (`taxloc_…`) recorded for this `storeId`. */
-    customerLocationEvidenceId: string;
+    customer_location_evidence_id: string;
 }
 export interface BillingTaxQuote {
-    schemaVersion: 1;
+    schema_version: 2;
     source: {
-        merchantId: string;
-        appId: string;
-        storeId: string;
-        planId: string;
+        merchant_id: string;
+        app_id: string;
+        store_id: string;
+        plan_id: string;
         mode: 'test' | 'live';
         environment: 'development' | 'staging' | 'production';
     };
     quote: {
         id: string;
         currency: string;
-        grossMinorUnits: number;
-        netMinorUnits: number;
-        taxMinorUnits: number;
-        taxTreatment: 'inclusive' | 'exclusive';
-        sellerId: string;
-        invoiceIssuerId: string;
-        taxRemitterId: string;
-        taxServiceRef: string;
+        gross_minor_units: number;
+        net_minor_units: number;
+        tax_minor_units: number;
+        tax_treatment: 'inclusive' | 'exclusive';
+        seller_id: string;
+        invoice_issuer_id: string;
+        tax_remitter_id: string;
+        tax_service_ref: string;
         country: string;
-        coverageEvidenceId: string;
-        taxRateEvidenceId: string;
-        customerLocationEvidenceId: string;
-        quotedAt: string;
-        expiresAt: string;
+        coverage_evidence_id: string;
+        tax_rate_evidence_id: string;
+        customer_location_evidence_id: string;
+        quoted_at: number;
+        expires_at: number;
     };
     signature: {
         algorithm: 'Ed25519';
-        keyId: string;
+        key_id: string;
         value: string;
     };
 }
 /** Read-only recovery of one previously attempted recurring checkout. Neither
  * absence nor uncertainty permits cancellation or another financial operation. */
 export interface RetrieveBillingCheckoutOperationParams {
-    idempotencyKey: string;
-    providerCustomerId: string;
-    providerPriceId: string;
-    storeId: string;
-    planId: string;
+    idempotency_key: string;
+    provider_customer_id: string;
+    provider_price_id: string;
+    store_id: string;
+    plan_id: string;
 }
 export interface BillingCheckoutOperationSource extends RetrieveBillingCheckoutOperationParams {
-    taxQuoteId: string | null;
-    merchantId: string;
-    appId: string;
+    tax_quote_id: string | null;
+    merchant_id: string;
+    app_id: string;
     mode: 'test' | 'live';
     environment: 'development' | 'staging' | 'production';
 }
@@ -294,19 +294,19 @@ export type BillingCheckoutOperationRecovery = {
     source: BillingCheckoutOperationSource;
     checkout: {
         id: string;
-        expiresAt: string;
+        expires_at: number;
         url?: string;
     };
 };
 export interface BillingFaircoinFxQuote {
     id: string;
     currency: 'USD';
-    grossMinorUnits: number;
-    amountBaseUnits: string;
-    usdPerFair: string;
+    gross_minor_units: number;
+    amount_base_units: string;
+    usd_per_fair: string;
     source: string;
-    observedAt: string;
-    quotedAt: string;
-    expiresAt: string;
+    observed_at: number;
+    quoted_at: number;
+    expires_at: number;
     rounding: 'ceil_to_base_unit';
 }

package/dist/types/checkoutSession.d.ts

@@ -3,30 +3,32 @@ import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
 import type { MerchantDisplay } from './merchantDisplay';
 import type { PaymentIntent, PaymentIntentRail } from './paymentIntent';
+import type { ConnectedAccount } from './settlement';
 /** The merchant/SDK-facing DTO — returned on create and by merchant retrieve. */
 export interface CheckoutSession {
     id: string;
     object: 'checkout_session';
-    paymentIntentId: string;
+    /** The wrapped payment's `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
+    payment_intent: string | PaymentIntent;
     /** The wrapped intent's `client_secret`, returned to the merchant on create. */
-    clientSecret: string;
+    client_secret: string;
     amount: string;
     currency: CurrencyCode;
     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.
+     * The seller the wrapped payment is made on behalf of (`ca_…`, or the
+     * object with `expand[]=connected_account`), or `null` (ADR 0012 D5).
      */
-    connectedAccountId?: string | null;
+    connected_account: string | ConnectedAccount | null;
     metadata: Record<string, string>;
-    successUrl?: string;
-    cancelUrl?: string;
+    success_url?: string;
+    cancel_url?: string;
     /** Canonical `checkout.peable.to/c/<id>` URL. */
     url: string;
-    createdAt: string;
-    updatedAt: string;
+    created: number;
+    updated_at: number;
 }
 /**
  * What the checkout page loads at `/c/:id`, authorized by possession of the
@@ -36,13 +38,13 @@ export interface CheckoutSession {
  */
 export interface CheckoutSessionPublic {
     /** Frozen commercial USD price and exact FAIR settlement quote; no payer metadata. */
-    billingQuote?: BillingFaircoinFxQuote;
+    billing_quote?: BillingFaircoinFxQuote;
     id: string;
     object: 'checkout_session';
-    successUrl?: string;
-    cancelUrl?: string;
+    success_url?: string;
+    cancel_url?: string;
     merchant: MerchantDisplay;
-    paymentIntent: PaymentIntent;
+    payment_intent: PaymentIntent;
 }
 export interface CreateCheckoutSessionParams {
     amount: string;
@@ -53,8 +55,12 @@ export interface CreateCheckoutSessionParams {
     /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
     currency?: CurrencyCode;
     metadata?: Record<string, string>;
-    successUrl?: string;
-    cancelUrl?: string;
+    success_url?: string;
+    cancel_url?: string;
     /** Pay this seller (`ca_…`) rather than the merchant — see `CreatePaymentIntentParams.connectedAccount`. */
-    connectedAccount?: string;
+    connected_account?: string;
+}
+/** `POST /v1/checkout_sessions/:id` — the merchant's `metadata`, as a patch. */
+export interface UpdateCheckoutSessionParams {
+    metadata?: Record<string, string>;
 }

package/dist/types/connect.d.ts

@@ -4,15 +4,15 @@ import type { NetworkType } from './network';
 export interface ConnectOnboarding {
     object: 'connect_onboarding';
     /** The `ca_…` being onboarded. */
-    accountId: string;
+    account_id: 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;
+    expires_at: number;
     /** Where to send the seller once the key is registered. */
-    returnUrl: string;
+    return_url: string;
 }
 /** `POST /v1/connect/onboarding/:token/faircoin` — the seller's watch-only ACCOUNT xpub. */
 export interface RegisterFaircoinKeyParams {
@@ -22,9 +22,9 @@ export interface RegisterFaircoinKeyParams {
 /** The answer to a successful registration. */
 export interface ConnectOnboardingComplete {
     object: 'connect_onboarding';
-    accountId: string;
+    account_id: string;
     status: 'active';
-    returnUrl: string;
+    return_url: string;
 }
 /**
  * A FairCoin onboarding link, as the platform receives it from
@@ -35,5 +35,5 @@ export interface ConnectOnboardingComplete {
 export interface AccountLink {
     object: 'account_link';
     url: string;
-    expiresAt: string;
+    expires_at: number;
 }