@peable.to/contracts 5.3.0 → 5.5.0

package/dist/cjs/resources/checkout/checkoutSessions.js

@@ -474,6 +474,10 @@ exports.confirmCheckoutSessionPublicParams = zod_1.z
         .enum(['card', 'faircoin'])
         .optional()
         .describe("How the payer pays: one of the session's `payment_method_types`. Default: the rail of the order's currency (`card` on a fiat order). `faircoin` on a fiat order quotes its total in FAIR for 10 minutes; confirming again with the other method replaces a payment that has not started moving money."),
+    locale: zod_1.z
+        .enum(checkout_1.CHECKOUT_LOCALES)
+        .optional()
+        .describe("The language the payer is completing checkout in. Recorded on the session (never on its `locale`) and given to a customer checkout creates as its `preferred_locales`; the session's emails are written in it when the customer has no preferred language."),
 })
     .strict();
 /** `POST /v1/test_helpers/checkout_sessions/{id}/expire` takes nothing. */

package/dist/cjs/resources/checkout/merchants.js

@@ -73,7 +73,12 @@ const merchantDescription = zod_1.z.string().min(1).max(512);
  */
 exports.registerMerchantParams = zod_1.z
     .object({
-    required_confirmations: zod_1.z.number().int().positive().optional(),
+    required_confirmations: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Confirmations a FairCoin payment needs to succeed. Defaults to 6 for a live (mainnet) merchant, 1 on testnet.'),
     display_name: displayName.optional(),
     avatar_file_id: avatarFileId.optional(),
     description: merchantDescription.optional(),

package/dist/cjs/resources/core/customers.js

@@ -8,6 +8,7 @@ const objects_1 = require("../../common/objects");
 const params_1 = require("../../common/params");
 const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
+const checkout_1 = require("../../vocabulary/checkout");
 /**
  * Customers (`cus_…`) — Orbit's own object (ADR 0016). A provider customer is an
  * internal binding created lazily, per mode, when a card payment method is
@@ -24,6 +25,9 @@ exports.customerSchema = (0, objects_1.defineObject)('customer', 'Customer', zod
     description: zod_1.z.string().nullable(),
     address: address_1.addressSchema.nullable(),
     shipping: address_1.shippingSchema.nullable(),
+    preferred_locales: zod_1.z
+        .array(zod_1.z.enum(checkout_1.CHECKOUT_LOCALES))
+        .describe("The customer's preferred languages, most preferred first (Stripe's `preferred_locales`), from the payer locale set. Receipts, invoices and dunning emails are written in the first; empty when none is known. A customer Checkout creates gets the language the payer completed it in."),
     invoice_settings: zod_1.z
         .object({
         default_payment_method: (0, objects_1.expandable)('payment_method', '`pm_…`, or the PaymentMethod with `expand[]=invoice_settings.default_payment_method`.').nullable(),
@@ -52,6 +56,7 @@ exports.customerSchema = (0, objects_1.defineObject)('customer', 'Customer', zod
             description: null,
             address: null,
             shipping: null,
+            preferred_locales: ['fr', 'en'],
             invoice_settings: { default_payment_method: null },
             metadata: { order_id: '6735' },
             balance: '0',
@@ -66,6 +71,11 @@ exports.deletedCustomerSchema = (0, objects_1.defineComponent)('DeletedCustomer'
 const name = zod_1.z.string().max(500);
 const phone = zod_1.z.string().max(40);
 const description = zod_1.z.string().max(1000);
+const preferredLocales = zod_1.z
+    .array(zod_1.z.enum(checkout_1.CHECKOUT_LOCALES))
+    .max(checkout_1.CHECKOUT_LOCALES.length)
+    .refine((locales) => new Set(locales).size === locales.length, 'a language is listed once')
+    .describe('Most preferred first, each once, from the payer locale set (`ar`, `bn`, `ca`, `de`, `en`, `es`, `fr`, `hi`, `id`, `it`, `ja`, `pt`, `ru`, `tr`, `zh`).');
 exports.createCustomerParams = zod_1.z
     .object({
     email: address_1.emailParam.optional(),
@@ -74,6 +84,7 @@ exports.createCustomerParams = zod_1.z
     description: description.optional(),
     address: address_1.addressParams.optional(),
     shipping: address_1.shippingParams.optional(),
+    preferred_locales: preferredLocales.optional(),
     invoice_settings: zod_1.z.object({ default_payment_method: params_1.idParam.optional() }).strict().optional(),
     metadata: params_1.metadataCreateParam.optional(),
     test_clock: params_1.idParam
@@ -91,6 +102,9 @@ exports.updateCustomerParams = zod_1.z
     description: (0, params_1.clearable)(description).optional(),
     address: (0, params_1.clearable)(address_1.addressParams).optional(),
     shipping: (0, params_1.clearable)(address_1.shippingParams).optional(),
+    preferred_locales: (0, params_1.clearable)(preferredLocales)
+        .optional()
+        .describe('Replaces the list; `[]` or `""` clears it.'),
     invoice_settings: zod_1.z
         .object({ default_payment_method: (0, params_1.clearable)(params_1.idParam).optional() })
         .strict()

package/dist/cjs/resources/payments/paymentIntents.js

@@ -318,7 +318,13 @@ exports.createPaymentIntentParams = zod_1.z
     ...exports.railParams,
     ...exports.connectedAccountParam,
     metadata: params_1.metadataCreateParam.optional(),
-    expires_in_seconds: zod_1.z.number().int().positive().optional(),
+    expires_in_seconds: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(payments_1.PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS)
+        .optional()
+        .describe('How long the payment stays payable, in seconds: at most 86400 (24 hours). Defaults to 900 (15 minutes).'),
     payment_method_types: zod_1.z
         .array(zod_1.z.enum(payments_1.PAYMENT_METHOD_TYPES))
         .min(1)

package/dist/cjs/resources/payments/social.js

@@ -77,7 +77,9 @@ exports.socialNextAddressParams = zod_1.z
     .strict();
 exports.socialNextAddressSchema = (0, objects_1.defineComponent)('SocialNextAddress', zod_1.z
     .object({
-    address: zod_1.z.string().describe("A fresh single-use address of the recipient's."),
+    address: zod_1.z
+        .string()
+        .describe("A single-use address of the recipient's: the one this sender already holds and has not paid, or a fresh one."),
     index: zod_1.z.number().int().nonnegative().describe('Its social-receive derivation index.'),
 })
     .strict());

package/dist/cjs/vocabulary/checkout.js

@@ -15,7 +15,8 @@ exports.checkoutLocaleDirection = checkoutLocaleDirection;
  *  - `faircoin_network_closed` — this deployment does not open payments on the
  *    order's FairCoin network yet (ADR 0002's gate);
  *  - `price_unavailable` — no fresh FairCoin price exists to quote a fiat order;
- *  - `temporarily_unavailable` — whether the wallet exists could not be checked.
+ *  - `temporarily_unavailable` — whether the wallet exists could not be checked, or every
+ *    address the recipient can hold open is open (ADR 0021 D9) — try again shortly.
  */
 exports.FAIRCOIN_UNAVAILABLE_REASONS = [
     'faircoin_wallet_missing',

package/dist/cjs/vocabulary/errors.js

@@ -134,6 +134,7 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     faircoin_price_unavailable: 'No fresh FairCoin price exists right now, so this order cannot be quoted in FAIR. The other payment methods still work; try FairCoin again shortly.',
     faircoin_wallet_missing: "The Peable wallet that receives this payment (the merchant owner's, or the seller's) isn't set up yet, so it cannot be paid in FairCoin. The other payment methods still work.",
     faircoin_network_closed: 'FairCoin payments on this network are not open on this deployment yet. The other payment methods still work.',
+    faircoin_capacity_reached: 'Too many FairCoin payments to this recipient are waiting to be paid right now, so no new FairCoin address can be handed out. The other payment methods still work; try FairCoin again shortly.',
     faircoin_amount_too_small: "One seller's share of this order is below the smallest amount the FairCoin network relays, so it cannot be paid in FairCoin. The other payment methods still work.",
     credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.",
     test_clock_unexpected_state: 'The test clock is advancing; wait until it is ready.',

package/dist/cjs/vocabulary/paymentMethodConfigurations.js

@@ -44,7 +44,8 @@ exports.PAYMENT_METHOD_CONFIGURATION_TYPES = [
  *    received (ADR 0021 D5); the owner sets it up in Peable;
  *  - `faircoin_network_closed` — the deployment does not open the merchant's
  *    FairCoin network yet (ADR 0002's gate);
- *  - `temporarily_unavailable` — the wallet could not be checked just now.
+ *  - `temporarily_unavailable` — the wallet could not be checked just now, or every
+ *    address the recipient can hold open is open (ADR 0021 D9) — try again shortly.
  */
 exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = [
     'provider_unsupported',

package/dist/cjs/vocabulary/payments.js

@@ -4,12 +4,19 @@
 // contracts are built from. Zod-free, so the wallet and the shared types read
 // them without bundling a schema.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.ENRICH_MAX_ADDRESSES = exports.ENRICHMENT_KINDS = exports.SOCIAL_PAYMENT_DIRECTIONS = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.SETUP_INTENT_CANCELLATION_REASONS = exports.SETUP_INTENT_USAGES = exports.SETUP_INTENT_STATUSES = exports.DISPUTE_EVIDENCE_TEXT_MAX = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_STATUSES = exports.SETTLEMENT_STATUSES = exports.REFUND_ORIGINS = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.CLIENT_ACTION_KINDS = exports.PAYMENT_ERROR_TYPES = exports.PAYMENT_METHOD_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.MERCHANT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_RAILS = void 0;
+exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.ENRICH_MAX_ADDRESSES = exports.ENRICHMENT_KINDS = exports.SOCIAL_PAYMENT_DIRECTIONS = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.SETUP_INTENT_CANCELLATION_REASONS = exports.SETUP_INTENT_USAGES = exports.SETUP_INTENT_STATUSES = exports.DISPUTE_EVIDENCE_TEXT_MAX = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_STATUSES = exports.SETTLEMENT_STATUSES = exports.REFUND_ORIGINS = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.CLIENT_ACTION_KINDS = exports.PAYMENT_ERROR_TYPES = exports.PAYMENT_METHOD_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.MERCHANT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS = exports.PAYMENT_INTENT_RAILS = void 0;
 /**
  * Which rail moves the money (ADR 0001 D1). On the INTENT, not on the merchant:
  * one merchant takes both, and the rail decides which fields mean anything.
  */
 exports.PAYMENT_INTENT_RAILS = ['faircoin', 'card'];
+/**
+ * The longest a PaymentIntent created through the API may stay payable before
+ * it expires (`expires_in_seconds`): 24 hours. A FairCoin payment holds a
+ * reserved address in the recipient's wallet for as long as it is payable, so
+ * an unbounded expiry is an address nobody can ever recycle (ADR 0021 D9).
+ */
+exports.PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS = 24 * 60 * 60;
 /**
  * Stripe's seven statuses, and no others (ADR 0019). The FairCoin rail walks
  * four of them (`requires_action` → `processing` → `succeeded` | `canceled`); a

package/dist/esm/resources/checkout/checkoutSessions.js

@@ -471,6 +471,10 @@ export const confirmCheckoutSessionPublicParams = z
         .enum(['card', 'faircoin'])
         .optional()
         .describe("How the payer pays: one of the session's `payment_method_types`. Default: the rail of the order's currency (`card` on a fiat order). `faircoin` on a fiat order quotes its total in FAIR for 10 minutes; confirming again with the other method replaces a payment that has not started moving money."),
+    locale: z
+        .enum(CHECKOUT_LOCALES)
+        .optional()
+        .describe("The language the payer is completing checkout in. Recorded on the session (never on its `locale`) and given to a customer checkout creates as its `preferred_locales`; the session's emails are written in it when the customer has no preferred language."),
 })
     .strict();
 /** `POST /v1/test_helpers/checkout_sessions/{id}/expire` takes nothing. */

package/dist/esm/resources/checkout/merchants.js

@@ -70,7 +70,12 @@ const merchantDescription = z.string().min(1).max(512);
  */
 export const registerMerchantParams = z
     .object({
-    required_confirmations: z.number().int().positive().optional(),
+    required_confirmations: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Confirmations a FairCoin payment needs to succeed. Defaults to 6 for a live (mainnet) merchant, 1 on testnet.'),
     display_name: displayName.optional(),
     avatar_file_id: avatarFileId.optional(),
     description: merchantDescription.optional(),

package/dist/esm/resources/core/customers.js

@@ -5,6 +5,7 @@ import { defineComponent, defineObject, expandable } from '../../common/objects.
 import { clearable, expandOnlyQuery, expandParam, idParam, listQuery, metadataCreateParam, metadataUpdateParam, searchQuery, } from '../../common/params.js';
 import { currency, livemode, metadata, signedAmount, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
+import { CHECKOUT_LOCALES } from '../../vocabulary/checkout.js';
 /**
  * Customers (`cus_…`) — Orbit's own object (ADR 0016). A provider customer is an
  * internal binding created lazily, per mode, when a card payment method is
@@ -21,6 +22,9 @@ export const customerSchema = defineObject('customer', 'Customer', z
     description: z.string().nullable(),
     address: addressSchema.nullable(),
     shipping: shippingSchema.nullable(),
+    preferred_locales: z
+        .array(z.enum(CHECKOUT_LOCALES))
+        .describe("The customer's preferred languages, most preferred first (Stripe's `preferred_locales`), from the payer locale set. Receipts, invoices and dunning emails are written in the first; empty when none is known. A customer Checkout creates gets the language the payer completed it in."),
     invoice_settings: z
         .object({
         default_payment_method: expandable('payment_method', '`pm_…`, or the PaymentMethod with `expand[]=invoice_settings.default_payment_method`.').nullable(),
@@ -49,6 +53,7 @@ export const customerSchema = defineObject('customer', 'Customer', z
             description: null,
             address: null,
             shipping: null,
+            preferred_locales: ['fr', 'en'],
             invoice_settings: { default_payment_method: null },
             metadata: { order_id: '6735' },
             balance: '0',
@@ -63,6 +68,11 @@ export const deletedCustomerSchema = defineComponent('DeletedCustomer', deletedO
 const name = z.string().max(500);
 const phone = z.string().max(40);
 const description = z.string().max(1000);
+const preferredLocales = z
+    .array(z.enum(CHECKOUT_LOCALES))
+    .max(CHECKOUT_LOCALES.length)
+    .refine((locales) => new Set(locales).size === locales.length, 'a language is listed once')
+    .describe('Most preferred first, each once, from the payer locale set (`ar`, `bn`, `ca`, `de`, `en`, `es`, `fr`, `hi`, `id`, `it`, `ja`, `pt`, `ru`, `tr`, `zh`).');
 export const createCustomerParams = z
     .object({
     email: emailParam.optional(),
@@ -71,6 +81,7 @@ export const createCustomerParams = z
     description: description.optional(),
     address: addressParams.optional(),
     shipping: shippingParams.optional(),
+    preferred_locales: preferredLocales.optional(),
     invoice_settings: z.object({ default_payment_method: idParam.optional() }).strict().optional(),
     metadata: metadataCreateParam.optional(),
     test_clock: idParam
@@ -88,6 +99,9 @@ export const updateCustomerParams = z
     description: clearable(description).optional(),
     address: clearable(addressParams).optional(),
     shipping: clearable(shippingParams).optional(),
+    preferred_locales: clearable(preferredLocales)
+        .optional()
+        .describe('Replaces the list; `[]` or `""` clears it.'),
     invoice_settings: z
         .object({ default_payment_method: clearable(idParam).optional() })
         .strict()

package/dist/esm/resources/payments/paymentIntents.js

@@ -6,7 +6,7 @@ import { clearable, expandParam, idParam, listQuery, metadataCreateParam, metada
 import { amount, currency, fiatCurrency, livemode, metadata, network, nullableString, unixSeconds, } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
 import { CURRENCY_CODES, isBaseUnitString, NETWORK_TYPES } from '../../vocabulary/money.js';
-import { CARD_RAIL_PAYMENT_METHOD_TYPES, CLIENT_ACTION_KINDS, MERCHANT_CANCELLATION_REASONS, PAYMENT_ERROR_TYPES, PAYMENT_INTENT_CANCELLATION_REASONS, PAYMENT_INTENT_CAPTURE_METHODS, PAYMENT_INTENT_RAILS, PAYMENT_INTENT_SETUP_FUTURE_USAGES, PAYMENT_INTENT_STATUSES, PAYMENT_METHOD_TYPES, } from '../../vocabulary/payments.js';
+import { CARD_RAIL_PAYMENT_METHOD_TYPES, CLIENT_ACTION_KINDS, MERCHANT_CANCELLATION_REASONS, PAYMENT_ERROR_TYPES, PAYMENT_INTENT_CANCELLATION_REASONS, PAYMENT_INTENT_CAPTURE_METHODS, PAYMENT_INTENT_RAILS, PAYMENT_INTENT_SETUP_FUTURE_USAGES, PAYMENT_INTENT_STATUSES, PAYMENT_METHOD_TYPES, PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS, } from '../../vocabulary/payments.js';
 /**
  * PaymentIntents (`pi_…`) — Stripe's PaymentIntent, at the root (ADR 0019):
  * one status vocabulary over two rails, the non-custodial FairCoin lifecycle
@@ -315,7 +315,13 @@ export const createPaymentIntentParams = z
     ...railParams,
     ...connectedAccountParam,
     metadata: metadataCreateParam.optional(),
-    expires_in_seconds: z.number().int().positive().optional(),
+    expires_in_seconds: z
+        .number()
+        .int()
+        .positive()
+        .max(PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS)
+        .optional()
+        .describe('How long the payment stays payable, in seconds: at most 86400 (24 hours). Defaults to 900 (15 minutes).'),
     payment_method_types: z
         .array(z.enum(PAYMENT_METHOD_TYPES))
         .min(1)

package/dist/esm/resources/payments/social.js

@@ -74,7 +74,9 @@ export const socialNextAddressParams = z
     .strict();
 export const socialNextAddressSchema = defineComponent('SocialNextAddress', z
     .object({
-    address: z.string().describe("A fresh single-use address of the recipient's."),
+    address: z
+        .string()
+        .describe("A single-use address of the recipient's: the one this sender already holds and has not paid, or a fresh one."),
     index: z.number().int().nonnegative().describe('Its social-receive derivation index.'),
 })
     .strict());

package/dist/esm/vocabulary/checkout.js

@@ -11,7 +11,8 @@
  *  - `faircoin_network_closed` — this deployment does not open payments on the
  *    order's FairCoin network yet (ADR 0002's gate);
  *  - `price_unavailable` — no fresh FairCoin price exists to quote a fiat order;
- *  - `temporarily_unavailable` — whether the wallet exists could not be checked.
+ *  - `temporarily_unavailable` — whether the wallet exists could not be checked, or every
+ *    address the recipient can hold open is open (ADR 0021 D9) — try again shortly.
  */
 export const FAIRCOIN_UNAVAILABLE_REASONS = [
     'faircoin_wallet_missing',

package/dist/esm/vocabulary/errors.js

@@ -129,6 +129,7 @@ export const ERROR_CODE_DESCRIPTIONS = {
     faircoin_price_unavailable: 'No fresh FairCoin price exists right now, so this order cannot be quoted in FAIR. The other payment methods still work; try FairCoin again shortly.',
     faircoin_wallet_missing: "The Peable wallet that receives this payment (the merchant owner's, or the seller's) isn't set up yet, so it cannot be paid in FairCoin. The other payment methods still work.",
     faircoin_network_closed: 'FairCoin payments on this network are not open on this deployment yet. The other payment methods still work.',
+    faircoin_capacity_reached: 'Too many FairCoin payments to this recipient are waiting to be paid right now, so no new FairCoin address can be handed out. The other payment methods still work; try FairCoin again shortly.',
     faircoin_amount_too_small: "One seller's share of this order is below the smallest amount the FairCoin network relays, so it cannot be paid in FairCoin. The other payment methods still work.",
     credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.",
     test_clock_unexpected_state: 'The test clock is advancing; wait until it is ready.',

package/dist/esm/vocabulary/paymentMethodConfigurations.js

@@ -41,7 +41,8 @@ export const PAYMENT_METHOD_CONFIGURATION_TYPES = [
  *    received (ADR 0021 D5); the owner sets it up in Peable;
  *  - `faircoin_network_closed` — the deployment does not open the merchant's
  *    FairCoin network yet (ADR 0002's gate);
- *  - `temporarily_unavailable` — the wallet could not be checked just now.
+ *  - `temporarily_unavailable` — the wallet could not be checked just now, or every
+ *    address the recipient can hold open is open (ADR 0021 D9) — try again shortly.
  */
 export const PAYMENT_METHOD_UNAVAILABLE_REASONS = [
     'provider_unsupported',

package/dist/esm/vocabulary/payments.js

@@ -7,6 +7,13 @@
  * one merchant takes both, and the rail decides which fields mean anything.
  */
 export const PAYMENT_INTENT_RAILS = ['faircoin', 'card'];
+/**
+ * The longest a PaymentIntent created through the API may stay payable before
+ * it expires (`expires_in_seconds`): 24 hours. A FairCoin payment holds a
+ * reserved address in the recipient's wallet for as long as it is payable, so
+ * an unbounded expiry is an address nobody can ever recycle (ADR 0021 D9).
+ */
+export const PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS = 24 * 60 * 60;
 /**
  * Stripe's seven statuses, and no others (ADR 0019). The FairCoin rail walks
  * four of them (`requires_action` → `processing` → `succeeded` | `canceled`); a

package/dist/types/resources/checkout/checkoutSessions.d.ts

@@ -873,6 +873,23 @@ export declare const confirmCheckoutSessionPublicParams: z.ZodObject<{
         card: "card";
         faircoin: "faircoin";
     }>>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        id: "id";
+        ar: "ar";
+        bn: "bn";
+        ca: "ca";
+        de: "de";
+        en: "en";
+        es: "es";
+        fr: "fr";
+        hi: "hi";
+        it: "it";
+        ja: "ja";
+        pt: "pt";
+        ru: "ru";
+        tr: "tr";
+        zh: "zh";
+    }>>;
 }, z.core.$strict>;
 export type ConfirmCheckoutSessionPublicParams = z.input<typeof confirmCheckoutSessionPublicParams>;
 /** `POST /v1/test_helpers/checkout_sessions/{id}/expire` takes nothing. */
@@ -2856,6 +2873,23 @@ export declare const checkoutSessionRoutes: readonly [{
             card: "card";
             faircoin: "faircoin";
         }>>;
+        locale: z.ZodOptional<z.ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>;
     }, z.core.$strict>;
     readonly response: z.ZodObject<{
         line_items: z.ZodArray<z.ZodObject<{

package/dist/types/resources/checkout/index.d.ts

@@ -1985,6 +1985,23 @@ export declare const checkoutRoutes: readonly [{
             card: "card";
             faircoin: "faircoin";
         }>>;
+        locale: import("zod").ZodOptional<import("zod").ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>;
     }, import("zod/v4/core").$strict>;
     readonly response: import("zod").ZodObject<{
         line_items: import("zod").ZodArray<import("zod").ZodObject<{

package/dist/types/resources/core/customers.d.ts

@@ -35,6 +35,23 @@ export declare const customerSchema: z.ZodObject<{
         carrier: z.ZodNullable<z.ZodString>;
         tracking_number: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
+    preferred_locales: z.ZodArray<z.ZodEnum<{
+        id: "id";
+        ar: "ar";
+        bn: "bn";
+        ca: "ca";
+        de: "de";
+        en: "en";
+        es: "es";
+        fr: "fr";
+        hi: "hi";
+        it: "it";
+        ja: "ja";
+        pt: "pt";
+        ru: "ru";
+        tr: "tr";
+        zh: "zh";
+    }>>;
     invoice_settings: z.ZodObject<{
         default_payment_method: z.ZodNullable<z.ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
     }, z.core.$strict>;
@@ -98,6 +115,23 @@ export declare const createCustomerParams: z.ZodObject<{
         carrier: z.ZodOptional<z.ZodString>;
         tracking_number: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    preferred_locales: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        id: "id";
+        ar: "ar";
+        bn: "bn";
+        ca: "ca";
+        de: "de";
+        en: "en";
+        es: "es";
+        fr: "fr";
+        hi: "hi";
+        it: "it";
+        ja: "ja";
+        pt: "pt";
+        ru: "ru";
+        tr: "tr";
+        zh: "zh";
+    }>>>;
     invoice_settings: z.ZodOptional<z.ZodObject<{
         default_payment_method: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
@@ -134,6 +168,23 @@ export declare const updateCustomerParams: z.ZodObject<{
         carrier: z.ZodOptional<z.ZodString>;
         tracking_number: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodLiteral<"">]>>;
+    preferred_locales: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
+        id: "id";
+        ar: "ar";
+        bn: "bn";
+        ca: "ca";
+        de: "de";
+        en: "en";
+        es: "es";
+        fr: "fr";
+        hi: "hi";
+        it: "it";
+        ja: "ja";
+        pt: "pt";
+        ru: "ru";
+        tr: "tr";
+        zh: "zh";
+    }>>, z.ZodLiteral<"">]>>;
     invoice_settings: z.ZodOptional<z.ZodObject<{
         default_payment_method: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"">]>>;
     }, z.core.$strict>>;
@@ -196,6 +247,23 @@ export declare const customerRoutes: readonly [{
             carrier: z.ZodOptional<z.ZodString>;
             tracking_number: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
+        preferred_locales: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>>;
         invoice_settings: z.ZodOptional<z.ZodObject<{
             default_payment_method: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
@@ -233,6 +301,23 @@ export declare const customerRoutes: readonly [{
             carrier: z.ZodNullable<z.ZodString>;
             tracking_number: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>>;
+        preferred_locales: z.ZodArray<z.ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>;
         invoice_settings: z.ZodObject<{
             default_payment_method: z.ZodNullable<z.ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
         }, z.core.$strict>;
@@ -318,6 +403,23 @@ export declare const customerRoutes: readonly [{
                 carrier: z.ZodNullable<z.ZodString>;
                 tracking_number: z.ZodNullable<z.ZodString>;
             }, z.core.$strict>>;
+            preferred_locales: z.ZodArray<z.ZodEnum<{
+                id: "id";
+                ar: "ar";
+                bn: "bn";
+                ca: "ca";
+                de: "de";
+                en: "en";
+                es: "es";
+                fr: "fr";
+                hi: "hi";
+                it: "it";
+                ja: "ja";
+                pt: "pt";
+                ru: "ru";
+                tr: "tr";
+                zh: "zh";
+            }>>;
             invoice_settings: z.ZodObject<{
                 default_payment_method: z.ZodNullable<z.ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
             }, z.core.$strict>;
@@ -391,6 +493,23 @@ export declare const customerRoutes: readonly [{
             carrier: z.ZodNullable<z.ZodString>;
             tracking_number: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>>;
+        preferred_locales: z.ZodArray<z.ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>;
         invoice_settings: z.ZodObject<{
             default_payment_method: z.ZodNullable<z.ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
         }, z.core.$strict>;
@@ -460,6 +579,23 @@ export declare const customerRoutes: readonly [{
             carrier: z.ZodOptional<z.ZodString>;
             tracking_number: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>, z.ZodLiteral<"">]>>;
+        preferred_locales: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>, z.ZodLiteral<"">]>>;
         invoice_settings: z.ZodOptional<z.ZodObject<{
             default_payment_method: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"">]>>;
         }, z.core.$strict>>;
@@ -496,6 +632,23 @@ export declare const customerRoutes: readonly [{
             carrier: z.ZodNullable<z.ZodString>;
             tracking_number: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>>;
+        preferred_locales: z.ZodArray<z.ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>;
         invoice_settings: z.ZodObject<{
             default_payment_method: z.ZodNullable<z.ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
         }, z.core.$strict>;
@@ -586,6 +739,23 @@ export declare const customerRoutes: readonly [{
                 carrier: z.ZodNullable<z.ZodString>;
                 tracking_number: z.ZodNullable<z.ZodString>;
             }, z.core.$strict>>;
+            preferred_locales: z.ZodArray<z.ZodEnum<{
+                id: "id";
+                ar: "ar";
+                bn: "bn";
+                ca: "ca";
+                de: "de";
+                en: "en";
+                es: "es";
+                fr: "fr";
+                hi: "hi";
+                it: "it";
+                ja: "ja";
+                pt: "pt";
+                ru: "ru";
+                tr: "tr";
+                zh: "zh";
+            }>>;
             invoice_settings: z.ZodObject<{
                 default_payment_method: z.ZodNullable<z.ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
             }, z.core.$strict>;

package/dist/types/resources/core/index.d.ts

@@ -37,6 +37,23 @@ export declare const coreRoutes: readonly [{
             carrier: import("zod").ZodOptional<import("zod").ZodString>;
             tracking_number: import("zod").ZodOptional<import("zod").ZodString>;
         }, import("zod/v4/core").$strict>>;
+        preferred_locales: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>>;
         invoice_settings: import("zod").ZodOptional<import("zod").ZodObject<{
             default_payment_method: import("zod").ZodOptional<import("zod").ZodString>;
         }, import("zod/v4/core").$strict>>;
@@ -74,6 +91,23 @@ export declare const coreRoutes: readonly [{
             carrier: import("zod").ZodNullable<import("zod").ZodString>;
             tracking_number: import("zod").ZodNullable<import("zod").ZodString>;
         }, import("zod/v4/core").$strict>>;
+        preferred_locales: import("zod").ZodArray<import("zod").ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>;
         invoice_settings: import("zod").ZodObject<{
             default_payment_method: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
         }, import("zod/v4/core").$strict>;
@@ -159,6 +193,23 @@ export declare const coreRoutes: readonly [{
                 carrier: import("zod").ZodNullable<import("zod").ZodString>;
                 tracking_number: import("zod").ZodNullable<import("zod").ZodString>;
             }, import("zod/v4/core").$strict>>;
+            preferred_locales: import("zod").ZodArray<import("zod").ZodEnum<{
+                id: "id";
+                ar: "ar";
+                bn: "bn";
+                ca: "ca";
+                de: "de";
+                en: "en";
+                es: "es";
+                fr: "fr";
+                hi: "hi";
+                it: "it";
+                ja: "ja";
+                pt: "pt";
+                ru: "ru";
+                tr: "tr";
+                zh: "zh";
+            }>>;
             invoice_settings: import("zod").ZodObject<{
                 default_payment_method: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
             }, import("zod/v4/core").$strict>;
@@ -232,6 +283,23 @@ export declare const coreRoutes: readonly [{
             carrier: import("zod").ZodNullable<import("zod").ZodString>;
             tracking_number: import("zod").ZodNullable<import("zod").ZodString>;
         }, import("zod/v4/core").$strict>>;
+        preferred_locales: import("zod").ZodArray<import("zod").ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>;
         invoice_settings: import("zod").ZodObject<{
             default_payment_method: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
         }, import("zod/v4/core").$strict>;
@@ -301,6 +369,23 @@ export declare const coreRoutes: readonly [{
             carrier: import("zod").ZodOptional<import("zod").ZodString>;
             tracking_number: import("zod").ZodOptional<import("zod").ZodString>;
         }, import("zod/v4/core").$strict>, import("zod").ZodLiteral<"">]>>;
+        preferred_locales: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodArray<import("zod").ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>, import("zod").ZodLiteral<"">]>>;
         invoice_settings: import("zod").ZodOptional<import("zod").ZodObject<{
             default_payment_method: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodLiteral<"">]>>;
         }, import("zod/v4/core").$strict>>;
@@ -337,6 +422,23 @@ export declare const coreRoutes: readonly [{
             carrier: import("zod").ZodNullable<import("zod").ZodString>;
             tracking_number: import("zod").ZodNullable<import("zod").ZodString>;
         }, import("zod/v4/core").$strict>>;
+        preferred_locales: import("zod").ZodArray<import("zod").ZodEnum<{
+            id: "id";
+            ar: "ar";
+            bn: "bn";
+            ca: "ca";
+            de: "de";
+            en: "en";
+            es: "es";
+            fr: "fr";
+            hi: "hi";
+            it: "it";
+            ja: "ja";
+            pt: "pt";
+            ru: "ru";
+            tr: "tr";
+            zh: "zh";
+        }>>;
         invoice_settings: import("zod").ZodObject<{
             default_payment_method: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
         }, import("zod/v4/core").$strict>;
@@ -427,6 +529,23 @@ export declare const coreRoutes: readonly [{
                 carrier: import("zod").ZodNullable<import("zod").ZodString>;
                 tracking_number: import("zod").ZodNullable<import("zod").ZodString>;
             }, import("zod/v4/core").$strict>>;
+            preferred_locales: import("zod").ZodArray<import("zod").ZodEnum<{
+                id: "id";
+                ar: "ar";
+                bn: "bn";
+                ca: "ca";
+                de: "de";
+                en: "en";
+                es: "es";
+                fr: "fr";
+                hi: "hi";
+                it: "it";
+                ja: "ja";
+                pt: "pt";
+                ru: "ru";
+                tr: "tr";
+                zh: "zh";
+            }>>;
             invoice_settings: import("zod").ZodObject<{
                 default_payment_method: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"payment_method">, string | import("../..").Ref<"payment_method">>>>;
             }, import("zod/v4/core").$strict>;

package/dist/types/vocabulary/checkout.d.ts

@@ -7,7 +7,8 @@
  *  - `faircoin_network_closed` — this deployment does not open payments on the
  *    order's FairCoin network yet (ADR 0002's gate);
  *  - `price_unavailable` — no fresh FairCoin price exists to quote a fiat order;
- *  - `temporarily_unavailable` — whether the wallet exists could not be checked.
+ *  - `temporarily_unavailable` — whether the wallet exists could not be checked, or every
+ *    address the recipient can hold open is open (ADR 0021 D9) — try again shortly.
  */
 export declare const FAIRCOIN_UNAVAILABLE_REASONS: readonly ["faircoin_wallet_missing", "faircoin_network_closed", "price_unavailable", "temporarily_unavailable"];
 export type FaircoinUnavailableReason = (typeof FAIRCOIN_UNAVAILABLE_REASONS)[number];

package/dist/types/vocabulary/errors.d.ts

@@ -108,6 +108,7 @@ export declare const ERROR_CODE_DESCRIPTIONS: {
     readonly faircoin_price_unavailable: "No fresh FairCoin price exists right now, so this order cannot be quoted in FAIR. The other payment methods still work; try FairCoin again shortly.";
     readonly faircoin_wallet_missing: "The Peable wallet that receives this payment (the merchant owner's, or the seller's) isn't set up yet, so it cannot be paid in FairCoin. The other payment methods still work.";
     readonly faircoin_network_closed: "FairCoin payments on this network are not open on this deployment yet. The other payment methods still work.";
+    readonly faircoin_capacity_reached: "Too many FairCoin payments to this recipient are waiting to be paid right now, so no new FairCoin address can be handed out. The other payment methods still work; try FairCoin again shortly.";
     readonly faircoin_amount_too_small: "One seller's share of this order is below the smallest amount the FairCoin network relays, so it cannot be paid in FairCoin. The other payment methods still work.";
     readonly credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.";
     readonly test_clock_unexpected_state: "The test clock is advancing; wait until it is ready.";

package/dist/types/vocabulary/paymentMethodConfigurations.d.ts

@@ -30,7 +30,8 @@ export type PaymentMethodConfigurationType = (typeof PAYMENT_METHOD_CONFIGURATIO
  *    received (ADR 0021 D5); the owner sets it up in Peable;
  *  - `faircoin_network_closed` — the deployment does not open the merchant's
  *    FairCoin network yet (ADR 0002's gate);
- *  - `temporarily_unavailable` — the wallet could not be checked just now.
+ *  - `temporarily_unavailable` — the wallet could not be checked just now, or every
+ *    address the recipient can hold open is open (ADR 0021 D9) — try again shortly.
  */
 export declare const PAYMENT_METHOD_UNAVAILABLE_REASONS: readonly ["provider_unsupported", "requires_card", "faircoin_wallet_missing", "faircoin_network_closed", "temporarily_unavailable"];
 export type PaymentMethodUnavailableReason = (typeof PAYMENT_METHOD_UNAVAILABLE_REASONS)[number];

package/dist/types/vocabulary/payments.d.ts

@@ -4,6 +4,13 @@
  */
 export declare const PAYMENT_INTENT_RAILS: readonly ["faircoin", "card"];
 export type PaymentIntentRail = (typeof PAYMENT_INTENT_RAILS)[number];
+/**
+ * The longest a PaymentIntent created through the API may stay payable before
+ * it expires (`expires_in_seconds`): 24 hours. A FairCoin payment holds a
+ * reserved address in the recipient's wallet for as long as it is payable, so
+ * an unbounded expiry is an address nobody can ever recycle (ADR 0021 D9).
+ */
+export declare const PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS: number;
 /**
  * Stripe's seven statuses, and no others (ADR 0019). The FairCoin rail walks
  * four of them (`requires_action` → `processing` → `succeeded` | `canceled`); a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/contracts",
-  "version": "5.3.0",
+  "version": "5.5.0",
   "description": "The Peable wire, declared once: Zod contracts of every public route, the OpenAPI 3.1 generator and the closed value sets (ADR 0014 D5).",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",