@peable.to/contracts 5.3.0 → 5.4.0

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/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/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/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/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.4.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",