@peable.to/shared-types 0.15.0 → 0.16.0

package/dist/cjs/branding.js

@@ -0,0 +1,31 @@
+"use strict";
+// Merchant branding and customer email settings (Orbit Phase 3).
+//
+// Branding is what the hosted checkout, the embedded checkout and Peable's
+// receipts look like for one merchant. Every value is from a CLOSED set or a
+// validated colour, so nothing a merchant stores can inject markup or a remote
+// font into a payer's page or an email.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BRANDING = exports.BRANDING_COLOR_PATTERN = exports.BRANDING_BORDER_STYLES = exports.BRANDING_FONTS = void 0;
+/** The fonts checkout may render in — system stacks only, no remote font is ever loaded. */
+exports.BRANDING_FONTS = [
+    'system',
+    'inter',
+    'roboto',
+    'open_sans',
+    'lato',
+    'source_sans',
+    'noto_sans',
+    'serif',
+    'monospace',
+];
+exports.BRANDING_BORDER_STYLES = ['rounded', 'rectangular', 'pill'];
+/** `#rrggbb`, lowercase — the only colour spelling branding stores. */
+exports.BRANDING_COLOR_PATTERN = /^#[0-9a-f]{6}$/;
+/** Peable's defaults, applied wherever a merchant set nothing. */
+exports.DEFAULT_BRANDING = Object.freeze({
+    primary_color: '#1f6feb',
+    accent_color: '#0b1f33',
+    font: 'system',
+    border_style: 'rounded',
+});

package/dist/cjs/checkoutSession.js

@@ -1,2 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHECKOUT_SESSION_ID_TEMPLATE = exports.CHECKOUT_LIMITS = exports.CHECKOUT_TAX_ID_TYPES = exports.CHECKOUT_CUSTOM_FIELD_TYPES = exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = exports.CHECKOUT_CUSTOMER_CREATIONS = exports.CHECKOUT_SUBMIT_TYPES = exports.CHECKOUT_LOCALES = exports.CHECKOUT_UI_MODES = exports.CHECKOUT_PAYMENT_STATUSES = exports.CHECKOUT_SESSION_STATUSES = exports.CHECKOUT_SESSION_MODES = void 0;
+exports.CHECKOUT_SESSION_MODES = ['payment', 'setup', 'subscription'];
+exports.CHECKOUT_SESSION_STATUSES = ['open', 'complete', 'expired'];
+exports.CHECKOUT_PAYMENT_STATUSES = ['paid', 'unpaid', 'no_payment_required'];
+exports.CHECKOUT_UI_MODES = ['hosted', 'embedded'];
+/** The languages the hosted and embedded checkout speak. */
+exports.CHECKOUT_LOCALES = ['en', 'es', 'fr', 'de', 'it', 'pt'];
+exports.CHECKOUT_SUBMIT_TYPES = ['auto', 'pay', 'book', 'donate'];
+exports.CHECKOUT_CUSTOMER_CREATIONS = ['always', 'if_required'];
+exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = ['auto', 'required'];
+exports.CHECKOUT_CUSTOM_FIELD_TYPES = ['text', 'numeric', 'dropdown'];
+/** Stripe's tax id types Peable collects; `eu_vat` covers every EU member state. */
+exports.CHECKOUT_TAX_ID_TYPES = [
+    'eu_vat',
+    'gb_vat',
+    'ch_vat',
+    'no_vat',
+    'us_ein',
+    'ca_bn',
+];
+/**
+ * Bounds of the session contract, shared by the gateway's validators and the
+ * clients that build requests, so the two cannot drift.
+ */
+exports.CHECKOUT_LIMITS = Object.freeze({
+    lineItemsMax: 20,
+    quantityMax: 999999,
+    customFieldsMax: 3,
+    customFieldKeyMax: 200,
+    customFieldLabelMax: 50,
+    customFieldTextMax: 255,
+    dropdownOptionsMax: 200,
+    dropdownOptionLabelMax: 100,
+    dropdownOptionValueMax: 100,
+    clientReferenceIdMax: 200,
+    /** `expires_at` must be between 30 minutes and 24 hours from creation. */
+    expiresMinSeconds: 30 * 60,
+    expiresMaxSeconds: 24 * 3600,
+    shippingCountriesMax: 250,
+    termsTextMax: 1200,
+});
+/** The template a `success_url` may carry; replaced with the session's `cs_…`. */
+exports.CHECKOUT_SESSION_ID_TEMPLATE = '{CHECKOUT_SESSION_ID}';

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PAYOUT_STATUSES = exports.BALANCE_TRANSACTION_TYPES = exports.BALANCE_TRANSACTION_STATUSES = exports.PAYOUT_WEEKLY_ANCHORS = exports.PAYOUT_INTERVALS = exports.PAYMENT_METHOD_CURRENCIES = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.FILE_TYPES = exports.FILE_STATUSES = exports.FILE_PURPOSE_POLICIES = exports.FILE_PURPOSES = exports.normalizeDisputeReason = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.CATALOG_LIMITS = exports.COUPON_DURATIONS = exports.TRANSFORM_QUANTITY_ROUNDS = exports.PRICE_TAX_BEHAVIORS = exports.RECURRING_USAGE_TYPES = exports.RECURRING_INTERVALS = exports.PRICE_TYPES = exports.PRICE_TIERS_MODES = exports.PRICE_BILLING_SCHEMES = exports.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = exports.WEBHOOK_ENDPOINT_STATUSES = exports.PEABLE_API_VERSION = exports.SETUP_INTENT_STATUSES = exports.isValidStatusTransition = exports.canStillBePaid = exports.canExpire = exports.TERMINAL_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.MERCHANT_CANCELLATION_REASONS = exports.EXPIRABLE_STATUSES = exports.CARD_ONLY_STATUSES = exports.isCurrencyCode = exports.decimalsFor = exports.FIAT_CURRENCY_CODES = 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.SIMULATED_FAIRCOIN_OUTCOMES = exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_METHODS = exports.REFUND_REASONS = exports.RECONCILIATION_MISMATCH_KINDS = 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.DEFAULT_BRANDING = exports.BRANDING_COLOR_PATTERN = exports.BRANDING_BORDER_STYLES = exports.BRANDING_FONTS = exports.CHECKOUT_SESSION_ID_TEMPLATE = exports.CHECKOUT_LIMITS = exports.CHECKOUT_TAX_ID_TYPES = exports.CHECKOUT_CUSTOM_FIELD_TYPES = exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = exports.CHECKOUT_CUSTOMER_CREATIONS = exports.CHECKOUT_SUBMIT_TYPES = exports.CHECKOUT_LOCALES = exports.CHECKOUT_UI_MODES = exports.CHECKOUT_PAYMENT_STATUSES = exports.CHECKOUT_SESSION_STATUSES = exports.CHECKOUT_SESSION_MODES = exports.PAYMENT_LINK_LIMITS = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_METHODS = exports.REFUND_REASONS = exports.RECONCILIATION_MISMATCH_KINDS = 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; } });
@@ -77,6 +77,26 @@ Object.defineProperty(exports, "signWebhook", { enumerable: true, get: function
 Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhookSigner_1.verifyWebhook; } });
 var merchant_1 = require("./merchant");
 Object.defineProperty(exports, "MERCHANT_ENVIRONMENTS", { enumerable: true, get: function () { return merchant_1.MERCHANT_ENVIRONMENTS; } });
+var paymentLink_1 = require("./paymentLink");
+Object.defineProperty(exports, "PAYMENT_LINK_LIMITS", { enumerable: true, get: function () { return paymentLink_1.PAYMENT_LINK_LIMITS; } });
+var checkoutSession_1 = require("./checkoutSession");
+Object.defineProperty(exports, "CHECKOUT_SESSION_MODES", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_SESSION_MODES; } });
+Object.defineProperty(exports, "CHECKOUT_SESSION_STATUSES", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_SESSION_STATUSES; } });
+Object.defineProperty(exports, "CHECKOUT_PAYMENT_STATUSES", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_PAYMENT_STATUSES; } });
+Object.defineProperty(exports, "CHECKOUT_UI_MODES", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_UI_MODES; } });
+Object.defineProperty(exports, "CHECKOUT_LOCALES", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_LOCALES; } });
+Object.defineProperty(exports, "CHECKOUT_SUBMIT_TYPES", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_SUBMIT_TYPES; } });
+Object.defineProperty(exports, "CHECKOUT_CUSTOMER_CREATIONS", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_CUSTOMER_CREATIONS; } });
+Object.defineProperty(exports, "CHECKOUT_BILLING_ADDRESS_COLLECTIONS", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_BILLING_ADDRESS_COLLECTIONS; } });
+Object.defineProperty(exports, "CHECKOUT_CUSTOM_FIELD_TYPES", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_CUSTOM_FIELD_TYPES; } });
+Object.defineProperty(exports, "CHECKOUT_TAX_ID_TYPES", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_TAX_ID_TYPES; } });
+Object.defineProperty(exports, "CHECKOUT_LIMITS", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_LIMITS; } });
+Object.defineProperty(exports, "CHECKOUT_SESSION_ID_TEMPLATE", { enumerable: true, get: function () { return checkoutSession_1.CHECKOUT_SESSION_ID_TEMPLATE; } });
+var branding_1 = require("./branding");
+Object.defineProperty(exports, "BRANDING_FONTS", { enumerable: true, get: function () { return branding_1.BRANDING_FONTS; } });
+Object.defineProperty(exports, "BRANDING_BORDER_STYLES", { enumerable: true, get: function () { return branding_1.BRANDING_BORDER_STYLES; } });
+Object.defineProperty(exports, "BRANDING_COLOR_PATTERN", { enumerable: true, get: function () { return branding_1.BRANDING_COLOR_PATTERN; } });
+Object.defineProperty(exports, "DEFAULT_BRANDING", { enumerable: true, get: function () { return branding_1.DEFAULT_BRANDING; } });
 var social_1 = require("./social");
 Object.defineProperty(exports, "SOCIAL_SOURCE_APP_MAX_LENGTH", { enumerable: true, get: function () { return social_1.SOCIAL_SOURCE_APP_MAX_LENGTH; } });
 Object.defineProperty(exports, "SOCIAL_SOURCE_REF_MAX_LENGTH", { enumerable: true, get: function () { return social_1.SOCIAL_SOURCE_REF_MAX_LENGTH; } });

package/dist/cjs/paymentLink.js

@@ -1,2 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYMENT_LINK_LIMITS = void 0;
+exports.PAYMENT_LINK_LIMITS = Object.freeze({
+    lineItemsMax: 20,
+    customMessageMax: 500,
+});

package/dist/esm/branding.js

@@ -0,0 +1,28 @@
+// Merchant branding and customer email settings (Orbit Phase 3).
+//
+// Branding is what the hosted checkout, the embedded checkout and Peable's
+// receipts look like for one merchant. Every value is from a CLOSED set or a
+// validated colour, so nothing a merchant stores can inject markup or a remote
+// font into a payer's page or an email.
+/** The fonts checkout may render in — system stacks only, no remote font is ever loaded. */
+export const BRANDING_FONTS = [
+    'system',
+    'inter',
+    'roboto',
+    'open_sans',
+    'lato',
+    'source_sans',
+    'noto_sans',
+    'serif',
+    'monospace',
+];
+export const BRANDING_BORDER_STYLES = ['rounded', 'rectangular', 'pill'];
+/** `#rrggbb`, lowercase — the only colour spelling branding stores. */
+export const BRANDING_COLOR_PATTERN = /^#[0-9a-f]{6}$/;
+/** Peable's defaults, applied wherever a merchant set nothing. */
+export const DEFAULT_BRANDING = Object.freeze({
+    primary_color: '#1f6feb',
+    accent_color: '#0b1f33',
+    font: 'system',
+    border_style: 'rounded',
+});

package/dist/esm/checkoutSession.js

@@ -1 +1,42 @@
-export {};
+export const CHECKOUT_SESSION_MODES = ['payment', 'setup', 'subscription'];
+export const CHECKOUT_SESSION_STATUSES = ['open', 'complete', 'expired'];
+export const CHECKOUT_PAYMENT_STATUSES = ['paid', 'unpaid', 'no_payment_required'];
+export const CHECKOUT_UI_MODES = ['hosted', 'embedded'];
+/** The languages the hosted and embedded checkout speak. */
+export const CHECKOUT_LOCALES = ['en', 'es', 'fr', 'de', 'it', 'pt'];
+export const CHECKOUT_SUBMIT_TYPES = ['auto', 'pay', 'book', 'donate'];
+export const CHECKOUT_CUSTOMER_CREATIONS = ['always', 'if_required'];
+export const CHECKOUT_BILLING_ADDRESS_COLLECTIONS = ['auto', 'required'];
+export const CHECKOUT_CUSTOM_FIELD_TYPES = ['text', 'numeric', 'dropdown'];
+/** Stripe's tax id types Peable collects; `eu_vat` covers every EU member state. */
+export const CHECKOUT_TAX_ID_TYPES = [
+    'eu_vat',
+    'gb_vat',
+    'ch_vat',
+    'no_vat',
+    'us_ein',
+    'ca_bn',
+];
+/**
+ * Bounds of the session contract, shared by the gateway's validators and the
+ * clients that build requests, so the two cannot drift.
+ */
+export const CHECKOUT_LIMITS = Object.freeze({
+    lineItemsMax: 20,
+    quantityMax: 999999,
+    customFieldsMax: 3,
+    customFieldKeyMax: 200,
+    customFieldLabelMax: 50,
+    customFieldTextMax: 255,
+    dropdownOptionsMax: 200,
+    dropdownOptionLabelMax: 100,
+    dropdownOptionValueMax: 100,
+    clientReferenceIdMax: 200,
+    /** `expires_at` must be between 30 minutes and 24 hours from creation. */
+    expiresMinSeconds: 30 * 60,
+    expiresMaxSeconds: 24 * 3600,
+    shippingCountriesMax: 250,
+    termsTextMax: 1200,
+});
+/** The template a `success_url` may carry; replaced with the session's `cs_…`. */
+export const CHECKOUT_SESSION_ID_TEMPLATE = '{CHECKOUT_SESSION_ID}';

package/dist/esm/index.js

@@ -15,6 +15,9 @@ export { REQUEST_LOG_METHODS, REQUEST_LOG_RETENTION_DAYS, } from './requestLog.j
 export { SIMULATED_FAIRCOIN_OUTCOMES, } from './testHelpers.js';
 export { signWebhook, verifyWebhook } from './webhookSigner.js';
 export { MERCHANT_ENVIRONMENTS, } from './merchant.js';
+export { PAYMENT_LINK_LIMITS, } from './paymentLink.js';
+export { CHECKOUT_SESSION_MODES, CHECKOUT_SESSION_STATUSES, CHECKOUT_PAYMENT_STATUSES, CHECKOUT_UI_MODES, CHECKOUT_LOCALES, CHECKOUT_SUBMIT_TYPES, CHECKOUT_CUSTOMER_CREATIONS, CHECKOUT_BILLING_ADDRESS_COLLECTIONS, CHECKOUT_CUSTOM_FIELD_TYPES, CHECKOUT_TAX_ID_TYPES, CHECKOUT_LIMITS, CHECKOUT_SESSION_ID_TEMPLATE, } from './checkoutSession.js';
+export { BRANDING_FONTS, BRANDING_BORDER_STYLES, BRANDING_COLOR_PATTERN, DEFAULT_BRANDING, } from './branding.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';

package/dist/esm/paymentLink.js

@@ -1 +1,4 @@
-export {};
+export const PAYMENT_LINK_LIMITS = Object.freeze({
+    lineItemsMax: 20,
+    customMessageMax: 500,
+});

package/dist/types/branding.d.ts

@@ -0,0 +1,88 @@
+/** The fonts checkout may render in — system stacks only, no remote font is ever loaded. */
+export declare const BRANDING_FONTS: readonly ["system", "inter", "roboto", "open_sans", "lato", "source_sans", "noto_sans", "serif", "monospace"];
+export type BrandingFont = (typeof BRANDING_FONTS)[number];
+export declare const BRANDING_BORDER_STYLES: readonly ["rounded", "rectangular", "pill"];
+export type BrandingBorderStyle = (typeof BRANDING_BORDER_STYLES)[number];
+/** `#rrggbb`, lowercase — the only colour spelling branding stores. */
+export declare const BRANDING_COLOR_PATTERN: RegExp;
+/** Peable's defaults, applied wherever a merchant set nothing. */
+export declare const DEFAULT_BRANDING: Readonly<{
+    primary_color: "#1f6feb";
+    accent_color: "#0b1f33";
+    font: BrandingFont;
+    border_style: BrandingBorderStyle;
+}>;
+/**
+ * A merchant's branding settings, as Orbit reads and writes them
+ * (`GET|POST /v1/merchants/me/branding`, and the dashboard's twin).
+ */
+export interface MerchantBranding {
+    object: 'branding_settings';
+    livemode: boolean;
+    /**
+     * The square icon: the merchant's avatar (`avatar_file_id`, an Oxy file
+     * Peable already governs), shown when `use_avatar_as_icon` is on.
+     */
+    use_avatar_as_icon: boolean;
+    /**
+     * The wide logo: the merchant's `business_logo` — a `file_…` of purpose
+     * `business_logo` (Files API) — or `null`. Setting it here and through
+     * `POST /v1/merchants/me {business_logo}` is the same write.
+     */
+    logo: string | null;
+    primary_color: string | null;
+    accent_color: string | null;
+    font: BrandingFont | null;
+    border_style: BrandingBorderStyle | null;
+    /**
+     * Your terms of service (`https://`). Required before a session or link can
+     * ask for terms acceptance (`consent_collection.terms_of_service: required`).
+     */
+    terms_of_service_url: string | null;
+    updated_at: number | null;
+}
+export interface UpdateMerchantBrandingParams {
+    use_avatar_as_icon?: boolean;
+    /** A `file_…` of purpose `business_logo`; `null` removes it. */
+    logo?: string | null;
+    /** `#rrggbb` (any case; stored lowercase), `null` for Peable's default. */
+    primary_color?: string | null;
+    accent_color?: string | null;
+    font?: BrandingFont | null;
+    border_style?: BrandingBorderStyle | null;
+    /** `https://` only; `null` removes it. */
+    terms_of_service_url?: string | null;
+}
+/**
+ * Branding as a payer surface renders it: every field resolved (defaults
+ * filled in), the logo and icon as URLs the gateway built through Oxy's media
+ * chokepoint — a withheld file is `null`, never a broken image.
+ */
+export interface CheckoutBranding {
+    icon_url: string | null;
+    logo_url: string | null;
+    primary_color: string;
+    accent_color: string;
+    font: BrandingFont;
+    border_style: BrandingBorderStyle;
+}
+/** Which customer emails Peable sends for this merchant. */
+export interface MerchantEmailSettings {
+    object: 'email_settings';
+    livemode: boolean;
+    /** A receipt when a payment succeeds and it has a `receipt_email` (or a collected email). */
+    payment_receipts: boolean;
+    /** A notice when a refund succeeds. */
+    refund_notices: boolean;
+    /** A confirmation when a checkout session completes. */
+    checkout_confirmations: boolean;
+    /** The reply-to address shown on emails, or `null` for none. */
+    support_email: string | null;
+    updated_at: number | null;
+}
+export interface UpdateMerchantEmailSettingsParams {
+    payment_receipts?: boolean;
+    refund_notices?: boolean;
+    checkout_confirmations?: boolean;
+    support_email?: string | null;
+}

package/dist/types/checkoutSession.d.ts

@@ -1,73 +1,452 @@
 import type { BillingFaircoinFxQuote } from './billing';
+import type { Price, Product } from './catalog';
+import type { Customer } from './customer';
+import type { CheckoutBranding } from './branding';
 import type { CurrencyCode } from './money';
-import type { NetworkType } from './network';
 import type { MerchantDisplay } from './merchantDisplay';
-import type { PaymentIntent, PaymentIntentRail } from './paymentIntent';
+import type { NetworkType } from './network';
+import type { Address, AddressParams, PaymentIntent, PaymentIntentRail } from './paymentIntent';
 import type { ConnectedAccount } from './settlement';
-/** The merchant/SDK-facing DTO — returned on create and by merchant retrieve. */
-export interface CheckoutSession {
+import type { SetupIntent } from './setupIntent';
+export declare const CHECKOUT_SESSION_MODES: readonly ["payment", "setup", "subscription"];
+export type CheckoutSessionMode = (typeof CHECKOUT_SESSION_MODES)[number];
+export declare const CHECKOUT_SESSION_STATUSES: readonly ["open", "complete", "expired"];
+export type CheckoutSessionStatus = (typeof CHECKOUT_SESSION_STATUSES)[number];
+export declare const CHECKOUT_PAYMENT_STATUSES: readonly ["paid", "unpaid", "no_payment_required"];
+export type CheckoutSessionPaymentStatus = (typeof CHECKOUT_PAYMENT_STATUSES)[number];
+export declare const CHECKOUT_UI_MODES: readonly ["hosted", "embedded"];
+export type CheckoutUiMode = (typeof CHECKOUT_UI_MODES)[number];
+/** The languages the hosted and embedded checkout speak. */
+export declare const CHECKOUT_LOCALES: readonly ["en", "es", "fr", "de", "it", "pt"];
+export type CheckoutLocale = (typeof CHECKOUT_LOCALES)[number];
+export declare const CHECKOUT_SUBMIT_TYPES: readonly ["auto", "pay", "book", "donate"];
+export type CheckoutSubmitType = (typeof CHECKOUT_SUBMIT_TYPES)[number];
+export declare const CHECKOUT_CUSTOMER_CREATIONS: readonly ["always", "if_required"];
+export type CheckoutCustomerCreation = (typeof CHECKOUT_CUSTOMER_CREATIONS)[number];
+export declare const CHECKOUT_BILLING_ADDRESS_COLLECTIONS: readonly ["auto", "required"];
+export type CheckoutBillingAddressCollection = (typeof CHECKOUT_BILLING_ADDRESS_COLLECTIONS)[number];
+export declare const CHECKOUT_CUSTOM_FIELD_TYPES: readonly ["text", "numeric", "dropdown"];
+export type CheckoutCustomFieldType = (typeof CHECKOUT_CUSTOM_FIELD_TYPES)[number];
+/** Stripe's tax id types Peable collects; `eu_vat` covers every EU member state. */
+export declare const CHECKOUT_TAX_ID_TYPES: readonly ["eu_vat", "gb_vat", "ch_vat", "no_vat", "us_ein", "ca_bn"];
+export type CheckoutTaxIdType = (typeof CHECKOUT_TAX_ID_TYPES)[number];
+/**
+ * Bounds of the session contract, shared by the gateway's validators and the
+ * clients that build requests, so the two cannot drift.
+ */
+export declare const CHECKOUT_LIMITS: Readonly<{
+    lineItemsMax: 20;
+    quantityMax: 999999;
+    customFieldsMax: 3;
+    customFieldKeyMax: 200;
+    customFieldLabelMax: 50;
+    customFieldTextMax: 255;
+    dropdownOptionsMax: 200;
+    dropdownOptionLabelMax: 100;
+    dropdownOptionValueMax: 100;
+    clientReferenceIdMax: 200;
+    /** `expires_at` must be between 30 minutes and 24 hours from creation. */
+    expiresMinSeconds: number;
+    expiresMaxSeconds: number;
+    shippingCountriesMax: 250;
+    termsTextMax: 1200;
+}>;
+/** The template a `success_url` may carry; replaced with the session's `cs_…`. */
+export declare const CHECKOUT_SESSION_ID_TEMPLATE = "{CHECKOUT_SESSION_ID}";
+export interface CheckoutAdjustableQuantity {
+    enabled: boolean;
+    /** Default 0 when enabled. */
+    minimum: number | null;
+    /** Default 99 when enabled. */
+    maximum: number | null;
+}
+/** One line of a session — Stripe's `item` (`GET /v1/checkout_sessions/:id/line_items`). */
+export interface CheckoutLineItem {
     id: string;
-    object: 'checkout_session';
+    object: 'item';
+    /** The product's name, or the inline `product_data.name`. */
+    description: string;
     /**
-     * Which of the provider's two worlds this object belongs to (ADR 0017):
-     * `true` for a `production` merchant, `false` for every other environment.
+     * The catalog price (`price_…`, or the object with `expand[]=data.price`), or
+     * `null` for an inline `price_data` line — an inline price is a snapshot on
+     * the line, never a stored `price_…`.
      */
+    price: string | Price | null;
+    /** The catalog product (`prod_…`, expandable), or `null` for `product_data`. */
+    product: string | Product | null;
+    /** Images to show beside the line (the product's, or `product_data.images`). */
+    images: string[];
+    quantity: number;
+    adjustable_quantity: CheckoutAdjustableQuantity | null;
+    currency: CurrencyCode;
+    /** The per-unit amount for a per-unit price; `null` for a tiered one. */
+    unit_amount: string | null;
+    /** Before discount and tax. */
+    amount_subtotal: string;
+    amount_discount: string;
+    amount_tax: string;
+    /** `amount_subtotal - amount_discount + amount_tax` (exclusive tax only). */
+    amount_total: string;
+}
+export interface CheckoutTaxId {
+    type: CheckoutTaxIdType;
+    value: string;
+}
+/** What the payer told checkout about themselves — Stripe's `customer_details`. */
+export interface CheckoutCustomerDetails {
+    email: string | null;
+    name: string | null;
+    phone: string | null;
+    address: Address | null;
+    tax_ids: CheckoutTaxId[];
+}
+export interface CheckoutShippingDetails {
+    name: string;
+    address: Address;
+}
+export interface CheckoutCustomFieldLabel {
+    type: 'custom';
+    custom: string;
+}
+export interface CheckoutCustomFieldDropdownOption {
+    label: string;
+    value: string;
+}
+/** A merchant-defined field the payer fills in; `value`s are what they entered. */
+export interface CheckoutCustomField {
+    key: string;
+    label: CheckoutCustomFieldLabel;
+    type: CheckoutCustomFieldType;
+    optional: boolean;
+    dropdown: {
+        options: CheckoutCustomFieldDropdownOption[];
+        value: string | null;
+    } | null;
+    text: {
+        minimum_length: number | null;
+        maximum_length: number | null;
+        value: string | null;
+    } | null;
+    numeric: {
+        minimum_length: number | null;
+        maximum_length: number | null;
+        value: string | null;
+    } | null;
+}
+export interface CheckoutDiscount {
+    /** The coupon applied (`coupon` id — merchant-chosen or `coupon_…`). */
+    coupon: string;
+    /** The promotion code it was redeemed through (`promo_…`), or `null`. */
+    promotion_code: string | null;
+}
+export interface CheckoutTotalDetails {
+    amount_discount: string;
+    amount_tax: string;
+    amount_shipping: string;
+}
+/**
+ * `automatic_tax` — Peable Tax (ADR 0011). `requires_location_inputs` until
+ * the payer gave an address Peable Tax can locate them with; `failed` when the
+ * sale is covered and could not be priced (checkout refuses to proceed: tax
+ * fails CLOSED, never zero).
+ */
+export interface CheckoutAutomaticTax {
+    enabled: boolean;
+    status: 'complete' | 'requires_location_inputs' | 'failed' | null;
+}
+export interface CheckoutConsentCollection {
+    terms_of_service: 'none' | 'required';
+}
+export interface CheckoutConsent {
+    terms_of_service: 'accepted' | null;
+}
+export interface CheckoutAfterCompletion {
+    type: 'redirect' | 'hosted_confirmation';
+    redirect: {
+        url: string;
+    } | null;
+    hosted_confirmation: {
+        custom_message: string | null;
+    } | null;
+}
+/** The merchant/SDK-facing session — Stripe's Checkout Session. */
+export interface CheckoutSession {
+    id: string;
+    object: 'checkout_session';
+    /** ADR 0017: `true` for a `production` merchant. */
     livemode: boolean;
-    /** 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. */
-    client_secret: string;
-    amount: string;
+    mode: CheckoutSessionMode;
+    status: CheckoutSessionStatus;
+    payment_status: CheckoutSessionPaymentStatus;
+    ui_mode: CheckoutUiMode;
+    /** The language checkout renders in; `null` follows the payer's browser. */
+    locale: CheckoutLocale | null;
+    submit_type: CheckoutSubmitType;
     currency: CurrencyCode;
     rail: PaymentIntentRail;
     /** FairCoin rail only; `null` on a card session. */
     network: NetworkType | null;
+    payment_method_types: string[];
+    amount_subtotal: string;
+    amount_total: string;
+    total_details: CheckoutTotalDetails;
+    discounts: CheckoutDiscount[];
+    allow_promotion_codes: boolean;
+    automatic_tax: CheckoutAutomaticTax;
+    /** `cus_…` (expandable) — given on create, or created at completion. */
+    customer: string | Customer | null;
+    customer_email: string | null;
+    customer_creation: CheckoutCustomerCreation;
+    customer_details: CheckoutCustomerDetails | null;
+    billing_address_collection: CheckoutBillingAddressCollection;
+    shipping_address_collection: {
+        allowed_countries: string[];
+    } | null;
+    shipping_details: CheckoutShippingDetails | null;
+    phone_number_collection: {
+        enabled: boolean;
+    };
+    tax_id_collection: {
+        enabled: boolean;
+    };
+    custom_fields: CheckoutCustomField[];
+    consent_collection: CheckoutConsentCollection | null;
+    consent: CheckoutConsent | null;
     /**
-     * The seller the wrapped payment is made on behalf of (`ca_…`, or the
-     * object with `expand[]=connected_account`), or `null` (ADR 0012 D5).
+     * The payment this session created (`pi_…`, expandable), once the payer
+     * confirmed; `null` before, and always in `setup` mode.
      */
+    payment_intent: string | PaymentIntent | null;
+    /** `setup` mode: the SetupIntent (`seti_…`, expandable) once confirmed. */
+    setup_intent: string | SetupIntent | null;
+    /** The seller an on-behalf payment pays (`ca_…`, expandable). */
     connected_account: string | ConnectedAccount | null;
+    /** The payment link this session was created from (`link_…`), if any. */
+    payment_link: string | null;
+    client_reference_id: string | null;
     metadata: Record<string, string>;
-    success_url?: string;
-    cancel_url?: string;
-    /** Canonical `checkout.peable.to/c/<id>` URL. */
-    url: string;
+    /** With `{CHECKOUT_SESSION_ID}` as given; checkout substitutes it. */
+    success_url: string | null;
+    cancel_url: string | null;
+    /** Hosted mode: the URL to send the payer to. `null` in embedded mode. */
+    url: string | null;
+    /** Embedded mode: what `PeableCheckout.mountCheckout` takes. `null` in hosted mode. */
+    client_secret: string | null;
+    expires_at: number;
     created: number;
-    updated_at: number;
 }
 /**
- * What the checkout page loads at `/c/:id`, authorized by possession of the
- * wrapped intent's `client_secret` (never a service token). `paymentIntent`
- * reuses `toPaymentIntentDTO`'s output unchanged — it already carries
- * `clientSecret`, which the page needs to open the socket and to `submit_tx`.
+ * What the hosted/embedded checkout loads, authorized by the session's
+ * `client_secret` (or, for a session wrapping a payment, that payment's). No
+ * metadata, no client reference, no internal ids.
  */
 export interface CheckoutSessionPublic {
-    /** Frozen commercial USD price and exact FAIR settlement quote; no payer metadata. */
-    billing_quote?: BillingFaircoinFxQuote;
     id: string;
     object: 'checkout_session';
+    livemode: boolean;
+    mode: CheckoutSessionMode;
+    status: CheckoutSessionStatus;
+    payment_status: CheckoutSessionPaymentStatus;
+    ui_mode: CheckoutUiMode;
+    locale: CheckoutLocale | null;
+    submit_type: CheckoutSubmitType;
+    currency: CurrencyCode;
+    rail: PaymentIntentRail;
+    network: NetworkType | null;
+    line_items: CheckoutLineItem[];
+    amount_subtotal: string;
+    amount_total: string;
+    total_details: CheckoutTotalDetails;
     /**
-     * Which of the provider's two worlds this object belongs to (ADR 0017):
-     * `true` for a `production` merchant, `false` for every other environment.
+     * The discount applied, with what the payer sees — the code they typed (or
+     * the coupon's name) and how much it took off.
      */
-    livemode: boolean;
-    success_url?: string;
-    cancel_url?: string;
+    discount: {
+        promotion_code: string | null;
+        coupon_name: string | null;
+        amount_off: string | null;
+        percent_off: number | null;
+    } | null;
+    allow_promotion_codes: boolean;
+    automatic_tax: CheckoutAutomaticTax;
+    /** Prefilled from `customer_email` / the customer; then what the payer entered. */
+    customer_details: CheckoutCustomerDetails;
+    /** Whether the email is fixed by the merchant (a `customer` or `customer_email`). */
+    customer_email_locked: boolean;
+    billing_address_collection: CheckoutBillingAddressCollection;
+    shipping_address_collection: {
+        allowed_countries: string[];
+    } | null;
+    shipping_details: CheckoutShippingDetails | null;
+    phone_number_collection: {
+        enabled: boolean;
+    };
+    tax_id_collection: {
+        enabled: boolean;
+    };
+    custom_fields: CheckoutCustomField[];
+    consent_collection: CheckoutConsentCollection | null;
+    consent: CheckoutConsent | null;
+    /** The merchant's terms URL when `consent_collection.terms_of_service` is required. */
+    terms_of_service_url: string | null;
+    /** The payment the payer confirmed — with its `client_secret`, the payer's capability. */
+    payment_intent: PaymentIntent | null;
+    /** `setup` mode: the SetupIntent id and client secret, once confirmed. */
+    setup_intent: {
+        id: string;
+        client_secret: string;
+        status: SetupIntent['status'];
+    } | null;
+    /** `success_url` with `{CHECKOUT_SESSION_ID}` substituted; only once `complete`. */
+    success_url: string | null;
+    /** Shown as "Back to <merchant>" before payment. */
+    cancel_url: string | null;
+    /** A payment link's hosted confirmation, shown once `complete`. */
+    confirmation_message: string | null;
     merchant: MerchantDisplay;
-    payment_intent: PaymentIntent;
+    branding: CheckoutBranding;
+    /**
+     * The card provider's PUBLIC key for this session's mode (ADR 0017), so the
+     * payment fields can mount before the payment exists. `null` on FairCoin.
+     */
+    publishable_key: string | null;
+    /** FairCoin billing invoices: the frozen USD price and FAIR settlement quote. */
+    billing_quote?: BillingFaircoinFxQuote;
+    expires_at: number;
+}
+/** `POST /v1/checkout_sessions/:id/public` — what the payer changes before confirming. */
+export interface UpdateCheckoutSessionPublicParams {
+    /** Adjust a line's quantity, within its `adjustable_quantity` bounds. */
+    line_items?: {
+        id: string;
+        quantity: number;
+    }[];
+    /** A code to redeem (`allow_promotion_codes`), or `''` to remove the one applied. */
+    promotion_code?: string;
+    customer_details?: {
+        email?: string;
+        name?: string;
+        phone?: string;
+        address?: AddressParams;
+        tax_ids?: CheckoutTaxId[];
+    };
+    shipping_details?: {
+        name: string;
+        address: AddressParams;
+    } | null;
+    /** By `key`: the payer's value for each custom field. */
+    custom_fields?: {
+        key: string;
+        value: string;
+    }[];
+    consent?: {
+        terms_of_service?: 'accepted';
+    };
+}
+/**
+ * `POST /v1/checkout_sessions/:id/public/confirm` — lock the order and create
+ * the payment (or setup). The answer is the session with `payment_intent` /
+ * `setup_intent` set; completing it is the payment's, and `complete` is only
+ * ever what the gateway says.
+ */
+export type ConfirmCheckoutSessionPublicParams = Record<string, never>;
+export interface CheckoutProductDataParams {
+    name: string;
+    description?: string;
+    images?: string[];
+    tax_code?: string;
+}
+export interface CheckoutPriceDataParams {
+    currency: CurrencyCode;
+    unit_amount: string;
+    /** Exactly one of `product` and `product_data`. */
+    product?: string;
+    product_data?: CheckoutProductDataParams;
+    recurring?: {
+        interval: 'day' | 'week' | 'month' | 'year';
+        interval_count?: number;
+    };
+    tax_behavior?: 'inclusive' | 'exclusive' | 'unspecified';
+}
+export interface CheckoutLineItemParams {
+    /** Exactly one of `price` and `price_data`. */
+    price?: string;
+    price_data?: CheckoutPriceDataParams;
+    quantity: number;
+    adjustable_quantity?: {
+        enabled: boolean;
+        minimum?: number;
+        maximum?: number;
+    };
+}
+export interface CheckoutCustomFieldParams {
+    key: string;
+    label: CheckoutCustomFieldLabel;
+    type: CheckoutCustomFieldType;
+    optional?: boolean;
+    dropdown?: {
+        options: CheckoutCustomFieldDropdownOption[];
+    };
+    text?: {
+        minimum_length?: number;
+        maximum_length?: number;
+    };
+    numeric?: {
+        minimum_length?: number;
+        maximum_length?: number;
+    };
 }
 export interface CreateCheckoutSessionParams {
-    amount: string;
-    /** Defaults to `'faircoin'`, so pre-ADR-0001 integrations keep working. */
-    rail?: PaymentIntentRail;
-    /** Required on the faircoin rail; refused on the card rail. */
-    network?: NetworkType;
-    /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
+    /** Default `payment`. `subscription` answers 400 until the billing engine fulfils it. */
+    mode?: CheckoutSessionMode;
+    /** Required in `payment` and `subscription` mode; refused in `setup` mode. */
+    line_items?: CheckoutLineItemParams[];
+    /** `setup` mode: the currency of the method being saved (card rail only). */
     currency?: CurrencyCode;
-    metadata?: Record<string, string>;
+    /** At most one; mutually exclusive with `allow_promotion_codes`. */
+    discounts?: ({
+        coupon: string;
+    } | {
+        promotion_code: string;
+    })[];
+    allow_promotion_codes?: boolean;
+    /** `cus_…`; mutually exclusive with `customer_email`. */
+    customer?: string;
+    customer_email?: string;
+    /** Default `if_required` (a customer is created only when something needs one). */
+    customer_creation?: CheckoutCustomerCreation;
+    billing_address_collection?: CheckoutBillingAddressCollection;
+    shipping_address_collection?: {
+        allowed_countries: string[];
+    };
+    phone_number_collection?: {
+        enabled: boolean;
+    };
+    tax_id_collection?: {
+        enabled: boolean;
+    };
+    /** At most three. */
+    custom_fields?: CheckoutCustomFieldParams[];
+    consent_collection?: {
+        terms_of_service?: 'none' | 'required';
+    };
+    automatic_tax?: {
+        enabled: boolean;
+    };
+    /** `['card']` or `['faircoin']` — the rail the line items' currency allows. */
+    payment_method_types?: string[];
+    locale?: CheckoutLocale | 'auto';
+    ui_mode?: CheckoutUiMode;
+    /** Required in hosted mode; may carry `{CHECKOUT_SESSION_ID}`. */
     success_url?: string;
+    /** Hosted mode only: the "Back to merchant" link. */
     cancel_url?: string;
-    /** Pay this seller (`ca_…`) rather than the merchant — see `CreatePaymentIntentParams.connectedAccount`. */
+    /** Unix seconds, 30 minutes to 24 hours from now. Default 24 hours. */
+    expires_at?: number;
+    client_reference_id?: string;
+    metadata?: Record<string, string>;
+    submit_type?: CheckoutSubmitType;
+    /** Pay this seller (`ca_…`) rather than the merchant (ADR 0012); FairCoin only. */
     connected_account?: string;
 }
 /** `POST /v1/checkout_sessions/:id` — the merchant's `metadata`, as a patch. */

package/dist/types/event.d.ts

@@ -1,10 +1,12 @@
 import type { Account } from './account';
 import type { ApplicationFee, Balance, Payout } from './balance';
 import type { Charge } from './charge';
+import type { CheckoutSession } from './checkoutSession';
 import type { Coupon, Price, Product, PromotionCode } from './catalog';
 import type { Customer } from './customer';
 import type { Dispute } from './dispute';
 import type { PaymentIntent } from './paymentIntent';
+import type { PaymentLink } from './paymentLink';
 import type { PaymentMethod } from './paymentMethod';
 import type { ConnectedAccount, Refund } from './settlement';
 import type { SetupIntent } from './setupIntent';
@@ -101,6 +103,20 @@ export interface WebhookEventPayload {
     'coupon.deleted': Coupon;
     'promotion_code.created': PromotionCode;
     'promotion_code.updated': PromotionCode;
+    /**
+     * Checkout (Orbit Phase 3). `completed` when the payer finished: the payment
+     * succeeded (`payment_status: paid`), was authorized for a manual capture,
+     * or — a FairCoin payment — was broadcast and is confirming (`unpaid`), in
+     * which case `async_payment_succeeded` or `async_payment_failed` follows
+     * when the chain decides. `expired` when it ran out or the merchant expired
+     * it. Each carries the session as `GET /v1/checkout_sessions/:id` returns it.
+     */
+    'checkout.session.completed': CheckoutSession;
+    'checkout.session.expired': CheckoutSession;
+    'checkout.session.async_payment_succeeded': CheckoutSession;
+    'checkout.session.async_payment_failed': CheckoutSession;
+    'payment_link.created': PaymentLink;
+    'payment_link.updated': PaymentLink;
     /**
      * A seller's account changed — their READINESS, in practice. Emitted when the
      * fields a merchant ACTS on change, not on every refresh. It names no payment

package/dist/types/index.d.ts

@@ -23,8 +23,9 @@ 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, UpdatePaymentLinkParams, } from './paymentLink';
-export type { CheckoutSession, CheckoutSessionPublic, CreateCheckoutSessionParams, UpdateCheckoutSessionParams, } from './checkoutSession';
+export { PAYMENT_LINK_LIMITS, type PaymentLink, type PublicPaymentLink, type PaymentLinkLineItemParams, type PaymentLinkAfterCompletionParams, type CreatePaymentLinkParams, type UpdatePaymentLinkParams, type CreatePaymentLinkSessionParams, type PaymentLinkSessionStart, } from './paymentLink';
+export { CHECKOUT_SESSION_MODES, CHECKOUT_SESSION_STATUSES, CHECKOUT_PAYMENT_STATUSES, CHECKOUT_UI_MODES, CHECKOUT_LOCALES, CHECKOUT_SUBMIT_TYPES, CHECKOUT_CUSTOMER_CREATIONS, CHECKOUT_BILLING_ADDRESS_COLLECTIONS, CHECKOUT_CUSTOM_FIELD_TYPES, CHECKOUT_TAX_ID_TYPES, CHECKOUT_LIMITS, CHECKOUT_SESSION_ID_TEMPLATE, type CheckoutSessionMode, type CheckoutSessionStatus, type CheckoutSessionPaymentStatus, type CheckoutUiMode, type CheckoutLocale, type CheckoutSubmitType, type CheckoutCustomerCreation, type CheckoutBillingAddressCollection, type CheckoutCustomFieldType, type CheckoutTaxIdType, type CheckoutAdjustableQuantity, type CheckoutLineItem, type CheckoutTaxId, type CheckoutCustomerDetails, type CheckoutShippingDetails, type CheckoutCustomFieldLabel, type CheckoutCustomFieldDropdownOption, type CheckoutCustomField, type CheckoutDiscount, type CheckoutTotalDetails, type CheckoutAutomaticTax, type CheckoutConsentCollection, type CheckoutConsent, type CheckoutAfterCompletion, type CheckoutSession, type CheckoutSessionPublic, type UpdateCheckoutSessionPublicParams, type ConfirmCheckoutSessionPublicParams, type CheckoutProductDataParams, type CheckoutPriceDataParams, type CheckoutLineItemParams, type CheckoutCustomFieldParams, type CreateCheckoutSessionParams, type UpdateCheckoutSessionParams, } from './checkoutSession';
+export { BRANDING_FONTS, BRANDING_BORDER_STYLES, BRANDING_COLOR_PATTERN, DEFAULT_BRANDING, type BrandingFont, type BrandingBorderStyle, type MerchantBranding, type UpdateMerchantBrandingParams, type CheckoutBranding, type MerchantEmailSettings, type UpdateMerchantEmailSettingsParams, } from './branding';
 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 BillingEmbeddedCheckoutSession, type BillingEmbeddedCheckoutConfiguration, type BillingEmbeddedCheckoutBinding, type BillingEmbeddedCheckoutAction, type BillingEmbeddedCheckoutScope, 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';

package/dist/types/paymentLink.d.ts

@@ -1,72 +1,177 @@
 import type { ContributionDetails } from '@peable.to/contracts';
+import type { CheckoutBranding } from './branding';
+import type { CheckoutAdjustableQuantity, CheckoutAfterCompletion, CheckoutBillingAddressCollection, CheckoutCustomField, CheckoutCustomFieldParams, CheckoutCustomerCreation, CheckoutLineItem, CheckoutLocale, CheckoutSubmitType } from './checkoutSession';
 import type { CurrencyCode } from './money';
-import type { NetworkType } from './network';
 import type { MerchantDisplay } from './merchantDisplay';
+import type { NetworkType } from './network';
 import type { PaymentIntentRail } from './paymentIntent';
-/** The merchant-facing DTO — returned by the merchant-authed CRUD routes. */
+export declare const PAYMENT_LINK_LIMITS: Readonly<{
+    lineItemsMax: 20;
+    customMessageMax: 500;
+}>;
 export interface PaymentLink {
     id: string;
     object: 'payment_link';
-    /**
-     * Which of the provider's two worlds this object belongs to (ADR 0017):
-     * `true` for a `production` merchant, `false` for every other environment.
-     */
     livemode: boolean;
-    contribution?: ContributionDetails;
-    /**
-     * Amount in the currency's smallest unit, as a canonical integer string.
-     * Never a float, and never interpretable without `currency`.
-     */
-    amount: string;
+    active: boolean;
     currency: CurrencyCode;
     rail: PaymentIntentRail;
-    /** FairCoin rail only; `null` on a card link. */
     network: NetworkType | null;
-    active: boolean;
+    /** The link's prices (`GET /v1/payment_links/:id/line_items` lists them in full). */
+    line_items: CheckoutLineItem[];
+    allow_promotion_codes: boolean;
+    billing_address_collection: CheckoutBillingAddressCollection;
+    shipping_address_collection: {
+        allowed_countries: string[];
+    } | null;
+    phone_number_collection: {
+        enabled: boolean;
+    };
+    tax_id_collection: {
+        enabled: boolean;
+    };
+    custom_fields: CheckoutCustomField[];
+    consent_collection: {
+        terms_of_service: 'none' | 'required';
+    } | null;
+    automatic_tax: {
+        enabled: boolean;
+    };
+    customer_creation: CheckoutCustomerCreation;
+    after_completion: CheckoutAfterCompletion;
+    restrictions: {
+        completed_sessions: {
+            limit: number;
+            count: number;
+        };
+    } | null;
+    submit_type: CheckoutSubmitType;
+    locale: CheckoutLocale | null;
+    /** Present on an organization contribution link (FairCoin). */
+    contribution?: ContributionDetails;
     metadata: Record<string, string>;
-    /** Optional post-payment redirect target for the checkout page. */
-    success_url?: string;
-    /** Canonical `checkout.peable.to/l/<id>` URL. */
+    /** `checkout.peable.to/l/<id>` — share it, or render it as a QR code. */
     url: string;
     created: number;
     updated_at: number;
 }
-/** What an unauthenticated checkout-page visitor may see — no secrets, no metadata. */
+/** What an anonymous visitor may see before checkout starts — no metadata, no counts. */
 export interface PublicPaymentLink {
     id: string;
     object: 'payment_link';
-    /**
-     * Which of the provider's two worlds this object belongs to (ADR 0017):
-     * `true` for a `production` merchant, `false` for every other environment.
-     */
     livemode: boolean;
-    contribution?: ContributionDetails;
-    amount: string;
+    active: boolean;
     currency: CurrencyCode;
     rail: PaymentIntentRail;
     network: NetworkType | null;
-    active: boolean;
+    line_items: CheckoutLineItem[];
+    contribution?: ContributionDetails;
+    /** A fixed contribution's amount; `null` when the payer chooses (or for a price link). */
+    contribution_amount: string | null;
     merchant: MerchantDisplay;
+    branding: CheckoutBranding;
+    locale: CheckoutLocale | null;
+}
+export interface PaymentLinkLineItemParams {
+    price: string;
+    quantity: number;
+    adjustable_quantity?: {
+        enabled: boolean;
+        minimum?: number;
+        maximum?: number;
+    };
+}
+export interface PaymentLinkAfterCompletionParams {
+    type: 'redirect' | 'hosted_confirmation';
+    /** `type: redirect` — may carry `{CHECKOUT_SESSION_ID}`. */
+    redirect?: {
+        url: string;
+    };
+    hosted_confirmation?: {
+        custom_message?: string;
+    };
 }
 export interface CreatePaymentLinkParams {
-    amount: string;
-    /** Defaults to `'faircoin'`, so pre-ADR-0001 integrations keep working. */
-    rail?: PaymentIntentRail;
-    /** Required on the faircoin rail; refused on the card rail. */
-    network?: NetworkType;
-    /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
-    currency?: CurrencyCode;
+    /** 1–20 prices of ONE currency, one-time prices only. */
+    line_items: PaymentLinkLineItemParams[];
+    allow_promotion_codes?: boolean;
+    billing_address_collection?: CheckoutBillingAddressCollection;
+    shipping_address_collection?: {
+        allowed_countries: string[];
+    };
+    phone_number_collection?: {
+        enabled: boolean;
+    };
+    tax_id_collection?: {
+        enabled: boolean;
+    };
+    custom_fields?: CheckoutCustomFieldParams[];
+    consent_collection?: {
+        terms_of_service?: 'none' | 'required';
+    };
+    automatic_tax?: {
+        enabled: boolean;
+    };
+    customer_creation?: CheckoutCustomerCreation;
+    after_completion?: PaymentLinkAfterCompletionParams;
+    restrictions?: {
+        completed_sessions: {
+            limit: number;
+        };
+    };
+    submit_type?: CheckoutSubmitType;
+    locale?: CheckoutLocale | 'auto';
     metadata?: Record<string, string>;
-    success_url?: string;
 }
 /**
- * `POST /v1/payment_links/:id`. `amount`/`network` are deliberately absent — a
- * link's price is immutable once shared.
+ * `POST /v1/payment_links/:id`. The line items are fixed once shared (a payer
+ * may hold a session priced from them); everything else may change.
  */
 export interface UpdatePaymentLinkParams {
     active?: boolean;
+    allow_promotion_codes?: boolean;
+    billing_address_collection?: CheckoutBillingAddressCollection;
+    shipping_address_collection?: {
+        allowed_countries: string[];
+    } | '';
+    phone_number_collection?: {
+        enabled: boolean;
+    };
+    tax_id_collection?: {
+        enabled: boolean;
+    };
+    custom_fields?: CheckoutCustomFieldParams[] | '';
+    consent_collection?: {
+        terms_of_service?: 'none' | 'required';
+    };
+    automatic_tax?: {
+        enabled: boolean;
+    };
+    customer_creation?: CheckoutCustomerCreation;
+    after_completion?: PaymentLinkAfterCompletionParams;
+    restrictions?: {
+        completed_sessions: {
+            limit: number;
+        };
+    } | '';
+    submit_type?: CheckoutSubmitType;
+    locale?: CheckoutLocale | 'auto';
     /** A patch: named keys are set, `""` removes a key, others are kept. */
     metadata?: Record<string, string>;
-    /** `null` removes it. */
-    success_url?: string | null;
 }
+/**
+ * `POST /v1/payment_links/:id/checkout_sessions` — a payer starting checkout
+ * (anonymous, rate-limited). A contribution link the payer prices takes
+ * `amount`; nothing else is the payer's to say.
+ */
+export interface CreatePaymentLinkSessionParams {
+    amount?: string;
+}
+/** Its answer: where to go — the hosted session and the secret that opens it. */
+export interface PaymentLinkSessionStart {
+    object: 'checkout_session_start';
+    id: string;
+    client_secret: string;
+    url: string;
+}
+export type { CheckoutAdjustableQuantity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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",