@peable.to/contracts 5.0.0 → 5.2.0

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

@@ -128,6 +128,9 @@ exports.paymentIntentFaircoinSchema = (0, objects_1.defineComponent)('PaymentInt
     quote: exports.faircoinQuoteSchema
         .nullable()
         .describe('The fiat order this payment pays, as quoted (ADR 0021); `null` on a FAIR-priced payment.'),
+    recipient_key_replaced_at: primitives_1.unixSeconds
+        .nullable()
+        .describe("When Peable found that a recipient's identity key had been replaced after this payment's address was reserved, while the payer had already broadcast (ADR 0002, amended 2026-11-06). The coins are at the address reserved under the PREVIOUS key: spendable only with that key, which the recipient may no longer hold. `null` when every recorded key is still the recipient's `#key-1`, and on a payment written before keys were recorded. A payment nobody had paid yet is never left open under a replaced key: it is canceled with `cancellation_reason: recipient_key_changed`."),
 })
     .strict());
 /** Where a destination charge's funds go (`transfer_data`, ADR 0015 §2). */

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

@@ -99,7 +99,11 @@ exports.socialReceiveCursorSchema = (0, objects_1.defineComponent)('SocialReceiv
     identity_public_key: zod_1.z
         .string()
         .nullable()
-        .describe('The identity public key (hex) those addresses derive from; `null` exactly when no address was ever reserved.'),
+        .describe('The identity public key (hex) those addresses derive from — the key recorded at the LAST reservation; `null` exactly when no address was ever reserved.'),
+    account_identity_public_key: zod_1.z
+        .string()
+        .nullable()
+        .describe("The caller's CURRENT identity public key: their DID's `#key-1`, read from Oxy at request time (never cached), as lowercase hex of the key exactly as the DID publishes it (`publicKeyHex`, the compressed secp256k1 key) — the same encoding as `identity_public_key`. Compare the device's key with THIS, not with `identity_public_key`, which only says what the last reservation used. `null` for a keyless (custodial) account."),
 })
     .strict());
 exports.socialPaymentsQuery = networkQuery;
@@ -154,6 +158,7 @@ exports.socialRoutes = [
         path: '/v1/social/me/cursor',
         tag: 'Social payments',
         summary: "Retrieve the caller's receive cursor",
+        description: "How far the caller's receive tree has been reserved, the key the last reservation used, and the caller's current `#key-1` read fresh from Oxy (ADR 0002). A 503 when Oxy cannot be asked for the current key.",
         auth: 'user',
         query: exports.socialReceiveCursorQuery,
         response: exports.socialReceiveCursorSchema,

package/dist/cjs/vocabulary/index.js

@@ -37,3 +37,4 @@ __exportStar(require("./files"), exports);
 __exportStar(require("./identity"), exports);
 __exportStar(require("./merchants"), exports);
 __exportStar(require("./paymentMethodConfigurations"), exports);
+__exportStar(require("./realtime"), exports);

package/dist/cjs/vocabulary/payments.js

@@ -26,14 +26,19 @@ exports.PAYMENT_INTENT_STATUSES = [
     'canceled',
 ];
 /**
- * Why an intent was cancelled — Stripe's reasons, plus `underpaid` (FairCoin
- * only: a transaction paid less than the amount).
+ * Why an intent was cancelled — Stripe's reasons, plus two FairCoin-only ones:
+ * `underpaid` (a transaction paid less than the amount) and
+ * `recipient_key_changed` (the recipient's identity key was replaced after the
+ * address was reserved, so the address is no longer in the wallet it pays —
+ * ADR 0002, amended 2026-11-06; nothing had been broadcast, and the order stays
+ * open for a fresh address).
  */
 exports.PAYMENT_INTENT_CANCELLATION_REASONS = [
     'abandoned',
     'automatic',
     'duplicate',
     'fraudulent',
+    'recipient_key_changed',
     'requested_by_customer',
     'underpaid',
 ];

package/dist/cjs/vocabulary/realtime.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYER_SOCKET_PATH = void 0;
+/**
+ * The PAYER realtime endpoint: the Socket.IO path a payer's browser opens to
+ * hear its payment move, by the intent's `client_secret` alone.
+ *
+ * It is a SEPARATE Socket.IO server from the gateway's default `/socket.io/`
+ * one, because Socket.IO decides CORS per server (per engine), before it
+ * knows which namespace or token a connection carries. The payer server
+ * answers any origin and takes no credentials — the same rule as the payer
+ * HTTP routes (`lib/payerCors.ts`): a merchant's own site runs Pay with
+ * Peable, and the capability is the secret, never the page. The default
+ * server keeps the Oxy origins (`createOxySocketCors`) for every socket that
+ * carries an Oxy identity.
+ */
+exports.PAYER_SOCKET_PATH = '/payer-socket.io';

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

@@ -125,6 +125,9 @@ export const paymentIntentFaircoinSchema = defineComponent('PaymentIntentFaircoi
     quote: faircoinQuoteSchema
         .nullable()
         .describe('The fiat order this payment pays, as quoted (ADR 0021); `null` on a FAIR-priced payment.'),
+    recipient_key_replaced_at: unixSeconds
+        .nullable()
+        .describe("When Peable found that a recipient's identity key had been replaced after this payment's address was reserved, while the payer had already broadcast (ADR 0002, amended 2026-11-06). The coins are at the address reserved under the PREVIOUS key: spendable only with that key, which the recipient may no longer hold. `null` when every recorded key is still the recipient's `#key-1`, and on a payment written before keys were recorded. A payment nobody had paid yet is never left open under a replaced key: it is canceled with `cancellation_reason: recipient_key_changed`."),
 })
     .strict());
 /** Where a destination charge's funds go (`transfer_data`, ADR 0015 §2). */

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

@@ -96,7 +96,11 @@ export const socialReceiveCursorSchema = defineComponent('SocialReceiveCursor',
     identity_public_key: z
         .string()
         .nullable()
-        .describe('The identity public key (hex) those addresses derive from; `null` exactly when no address was ever reserved.'),
+        .describe('The identity public key (hex) those addresses derive from — the key recorded at the LAST reservation; `null` exactly when no address was ever reserved.'),
+    account_identity_public_key: z
+        .string()
+        .nullable()
+        .describe("The caller's CURRENT identity public key: their DID's `#key-1`, read from Oxy at request time (never cached), as lowercase hex of the key exactly as the DID publishes it (`publicKeyHex`, the compressed secp256k1 key) — the same encoding as `identity_public_key`. Compare the device's key with THIS, not with `identity_public_key`, which only says what the last reservation used. `null` for a keyless (custodial) account."),
 })
     .strict());
 export const socialPaymentsQuery = networkQuery;
@@ -151,6 +155,7 @@ export const socialRoutes = [
         path: '/v1/social/me/cursor',
         tag: 'Social payments',
         summary: "Retrieve the caller's receive cursor",
+        description: "How far the caller's receive tree has been reserved, the key the last reservation used, and the caller's current `#key-1` read fresh from Oxy (ADR 0002). A 503 when Oxy cannot be asked for the current key.",
         auth: 'user',
         query: socialReceiveCursorQuery,
         response: socialReceiveCursorSchema,

package/dist/esm/vocabulary/index.js

@@ -21,3 +21,4 @@ export * from './files.js';
 export * from './identity.js';
 export * from './merchants.js';
 export * from './paymentMethodConfigurations.js';
+export * from './realtime.js';

package/dist/esm/vocabulary/payments.js

@@ -23,14 +23,19 @@ export const PAYMENT_INTENT_STATUSES = [
     'canceled',
 ];
 /**
- * Why an intent was cancelled — Stripe's reasons, plus `underpaid` (FairCoin
- * only: a transaction paid less than the amount).
+ * Why an intent was cancelled — Stripe's reasons, plus two FairCoin-only ones:
+ * `underpaid` (a transaction paid less than the amount) and
+ * `recipient_key_changed` (the recipient's identity key was replaced after the
+ * address was reserved, so the address is no longer in the wallet it pays —
+ * ADR 0002, amended 2026-11-06; nothing had been broadcast, and the order stays
+ * open for a fresh address).
  */
 export const PAYMENT_INTENT_CANCELLATION_REASONS = [
     'abandoned',
     'automatic',
     'duplicate',
     'fraudulent',
+    'recipient_key_changed',
     'requested_by_customer',
     'underpaid',
 ];

package/dist/esm/vocabulary/realtime.js

@@ -0,0 +1,14 @@
+/**
+ * The PAYER realtime endpoint: the Socket.IO path a payer's browser opens to
+ * hear its payment move, by the intent's `client_secret` alone.
+ *
+ * It is a SEPARATE Socket.IO server from the gateway's default `/socket.io/`
+ * one, because Socket.IO decides CORS per server (per engine), before it
+ * knows which namespace or token a connection carries. The payer server
+ * answers any origin and takes no credentials — the same rule as the payer
+ * HTTP routes (`lib/payerCors.ts`): a merchant's own site runs Pay with
+ * Peable, and the capability is the secret, never the page. The default
+ * server keeps the Oxy origins (`createOxySocketCors`) for every socket that
+ * carries an Oxy identity.
+ */
+export const PAYER_SOCKET_PATH = '/payer-socket.io';

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

@@ -182,6 +182,7 @@ export declare const paymentsRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -248,6 +249,7 @@ export declare const paymentsRoutes: readonly [{
                 quoted_at: import("zod").ZodNumber;
                 expires_at: import("zod").ZodNumber;
             }, import("zod/v4/core").$strict>>;
+            recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
         }, import("zod/v4/core").$strict>>;
         merchant_id: import("zod").ZodString;
         connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -404,6 +406,7 @@ export declare const paymentsRoutes: readonly [{
                 fraudulent: "fraudulent";
                 abandoned: "abandoned";
                 automatic: "automatic";
+                recipient_key_changed: "recipient_key_changed";
                 requested_by_customer: "requested_by_customer";
                 underpaid: "underpaid";
             }>>;
@@ -470,6 +473,7 @@ export declare const paymentsRoutes: readonly [{
                     quoted_at: import("zod").ZodNumber;
                     expires_at: import("zod").ZodNumber;
                 }, import("zod/v4/core").$strict>>;
+                recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
             }, import("zod/v4/core").$strict>>;
             merchant_id: import("zod").ZodString;
             connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -607,6 +611,7 @@ export declare const paymentsRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -673,6 +678,7 @@ export declare const paymentsRoutes: readonly [{
                 quoted_at: import("zod").ZodNumber;
                 expires_at: import("zod").ZodNumber;
             }, import("zod/v4/core").$strict>>;
+            recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
         }, import("zod/v4/core").$strict>>;
         merchant_id: import("zod").ZodString;
         connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -824,6 +830,7 @@ export declare const paymentsRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -890,6 +897,7 @@ export declare const paymentsRoutes: readonly [{
                 quoted_at: import("zod").ZodNumber;
                 expires_at: import("zod").ZodNumber;
             }, import("zod/v4/core").$strict>>;
+            recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
         }, import("zod/v4/core").$strict>>;
         merchant_id: import("zod").ZodString;
         connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1071,6 +1079,7 @@ export declare const paymentsRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -1137,6 +1146,7 @@ export declare const paymentsRoutes: readonly [{
                 quoted_at: import("zod").ZodNumber;
                 expires_at: import("zod").ZodNumber;
             }, import("zod/v4/core").$strict>>;
+            recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
         }, import("zod/v4/core").$strict>>;
         merchant_id: import("zod").ZodString;
         connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1272,6 +1282,7 @@ export declare const paymentsRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -1338,6 +1349,7 @@ export declare const paymentsRoutes: readonly [{
                 quoted_at: import("zod").ZodNumber;
                 expires_at: import("zod").ZodNumber;
             }, import("zod/v4/core").$strict>>;
+            recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
         }, import("zod/v4/core").$strict>>;
         merchant_id: import("zod").ZodString;
         connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1478,6 +1490,7 @@ export declare const paymentsRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -1544,6 +1557,7 @@ export declare const paymentsRoutes: readonly [{
                 quoted_at: import("zod").ZodNumber;
                 expires_at: import("zod").ZodNumber;
             }, import("zod/v4/core").$strict>>;
+            recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
         }, import("zod/v4/core").$strict>>;
         merchant_id: import("zod").ZodString;
         connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1677,6 +1691,7 @@ export declare const paymentsRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -1743,6 +1758,7 @@ export declare const paymentsRoutes: readonly [{
                 quoted_at: import("zod").ZodNumber;
                 expires_at: import("zod").ZodNumber;
             }, import("zod/v4/core").$strict>>;
+            recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
         }, import("zod/v4/core").$strict>>;
         merchant_id: import("zod").ZodString;
         connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1876,6 +1892,7 @@ export declare const paymentsRoutes: readonly [{
                 fraudulent: "fraudulent";
                 abandoned: "abandoned";
                 automatic: "automatic";
+                recipient_key_changed: "recipient_key_changed";
                 requested_by_customer: "requested_by_customer";
                 underpaid: "underpaid";
             }>>;
@@ -1942,6 +1959,7 @@ export declare const paymentsRoutes: readonly [{
                     quoted_at: import("zod").ZodNumber;
                     expires_at: import("zod").ZodNumber;
                 }, import("zod/v4/core").$strict>>;
+                recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
             }, import("zod/v4/core").$strict>>;
             merchant_id: import("zod").ZodString;
             connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -3710,6 +3728,7 @@ export declare const paymentsRoutes: readonly [{
     readonly path: "/v1/social/me/cursor";
     readonly tag: "Social payments";
     readonly summary: "Retrieve the caller's receive cursor";
+    readonly description: "How far the caller's receive tree has been reserved, the key the last reservation used, and the caller's current `#key-1` read fresh from Oxy (ADR 0002). A 503 when Oxy cannot be asked for the current key.";
     readonly auth: "user";
     readonly query: import("zod").ZodObject<{
         network: import("zod").ZodEnum<{
@@ -3720,6 +3739,7 @@ export declare const paymentsRoutes: readonly [{
     readonly response: import("zod").ZodObject<{
         reserved_through: import("zod").ZodNumber;
         identity_public_key: import("zod").ZodNullable<import("zod").ZodString>;
+        account_identity_public_key: import("zod").ZodNullable<import("zod").ZodString>;
     }, import("zod/v4/core").$strict>;
 }, {
     readonly operationId: "listSocialPayments";
@@ -3895,6 +3915,7 @@ export declare const paymentsRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -3961,6 +3982,7 @@ export declare const paymentsRoutes: readonly [{
                 quoted_at: import("zod").ZodNumber;
                 expires_at: import("zod").ZodNumber;
             }, import("zod/v4/core").$strict>>;
+            recipient_key_replaced_at: import("zod").ZodNullable<import("zod").ZodNumber>;
         }, import("zod/v4/core").$strict>>;
         merchant_id: import("zod").ZodString;
         connected_account: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;

package/dist/types/resources/payments/paymentIntents.d.ts

@@ -141,6 +141,7 @@ export declare const paymentIntentFaircoinSchema: z.ZodObject<{
         quoted_at: z.ZodNumber;
         expires_at: z.ZodNumber;
     }, z.core.$strict>>;
+    recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strict>;
 export type PaymentIntentFaircoin = z.output<typeof paymentIntentFaircoinSchema>;
 /** Where a destination charge's funds go (`transfer_data`, ADR 0015 §2). */
@@ -265,6 +266,7 @@ export declare const paymentIntentSchema: z.ZodObject<{
         fraudulent: "fraudulent";
         abandoned: "abandoned";
         automatic: "automatic";
+        recipient_key_changed: "recipient_key_changed";
         requested_by_customer: "requested_by_customer";
         underpaid: "underpaid";
     }>>;
@@ -331,6 +333,7 @@ export declare const paymentIntentSchema: z.ZodObject<{
             quoted_at: z.ZodNumber;
             expires_at: z.ZodNumber;
         }, z.core.$strict>>;
+        recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strict>>;
     merchant_id: z.ZodString;
     connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -771,6 +774,7 @@ export declare const paymentIntentRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -837,6 +841,7 @@ export declare const paymentIntentRoutes: readonly [{
                 quoted_at: z.ZodNumber;
                 expires_at: z.ZodNumber;
             }, z.core.$strict>>;
+            recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
         merchant_id: z.ZodString;
         connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -993,6 +998,7 @@ export declare const paymentIntentRoutes: readonly [{
                 fraudulent: "fraudulent";
                 abandoned: "abandoned";
                 automatic: "automatic";
+                recipient_key_changed: "recipient_key_changed";
                 requested_by_customer: "requested_by_customer";
                 underpaid: "underpaid";
             }>>;
@@ -1059,6 +1065,7 @@ export declare const paymentIntentRoutes: readonly [{
                     quoted_at: z.ZodNumber;
                     expires_at: z.ZodNumber;
                 }, z.core.$strict>>;
+                recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
             }, z.core.$strict>>;
             merchant_id: z.ZodString;
             connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1196,6 +1203,7 @@ export declare const paymentIntentRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -1262,6 +1270,7 @@ export declare const paymentIntentRoutes: readonly [{
                 quoted_at: z.ZodNumber;
                 expires_at: z.ZodNumber;
             }, z.core.$strict>>;
+            recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
         merchant_id: z.ZodString;
         connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1413,6 +1422,7 @@ export declare const paymentIntentRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -1479,6 +1489,7 @@ export declare const paymentIntentRoutes: readonly [{
                 quoted_at: z.ZodNumber;
                 expires_at: z.ZodNumber;
             }, z.core.$strict>>;
+            recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
         merchant_id: z.ZodString;
         connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1660,6 +1671,7 @@ export declare const paymentIntentRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -1726,6 +1738,7 @@ export declare const paymentIntentRoutes: readonly [{
                 quoted_at: z.ZodNumber;
                 expires_at: z.ZodNumber;
             }, z.core.$strict>>;
+            recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
         merchant_id: z.ZodString;
         connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -1861,6 +1874,7 @@ export declare const paymentIntentRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -1927,6 +1941,7 @@ export declare const paymentIntentRoutes: readonly [{
                 quoted_at: z.ZodNumber;
                 expires_at: z.ZodNumber;
             }, z.core.$strict>>;
+            recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
         merchant_id: z.ZodString;
         connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -2067,6 +2082,7 @@ export declare const paymentIntentRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -2133,6 +2149,7 @@ export declare const paymentIntentRoutes: readonly [{
                 quoted_at: z.ZodNumber;
                 expires_at: z.ZodNumber;
             }, z.core.$strict>>;
+            recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
         merchant_id: z.ZodString;
         connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -2266,6 +2283,7 @@ export declare const paymentIntentRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -2332,6 +2350,7 @@ export declare const paymentIntentRoutes: readonly [{
                 quoted_at: z.ZodNumber;
                 expires_at: z.ZodNumber;
             }, z.core.$strict>>;
+            recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
         merchant_id: z.ZodString;
         connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;
@@ -2465,6 +2484,7 @@ export declare const paymentIntentRoutes: readonly [{
                 fraudulent: "fraudulent";
                 abandoned: "abandoned";
                 automatic: "automatic";
+                recipient_key_changed: "recipient_key_changed";
                 requested_by_customer: "requested_by_customer";
                 underpaid: "underpaid";
             }>>;
@@ -2531,6 +2551,7 @@ export declare const paymentIntentRoutes: readonly [{
                     quoted_at: z.ZodNumber;
                     expires_at: z.ZodNumber;
                 }, z.core.$strict>>;
+                recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
             }, z.core.$strict>>;
             merchant_id: z.ZodString;
             connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;

package/dist/types/resources/payments/social.d.ts

@@ -76,6 +76,7 @@ export type SocialReceiveCursorParams = z.input<typeof socialReceiveCursorQuery>
 export declare const socialReceiveCursorSchema: z.ZodObject<{
     reserved_through: z.ZodNumber;
     identity_public_key: z.ZodNullable<z.ZodString>;
+    account_identity_public_key: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type SocialReceiveCursorResponse = z.output<typeof socialReceiveCursorSchema>;
 export declare const socialPaymentsQuery: z.ZodObject<{
@@ -190,6 +191,7 @@ export declare const socialRoutes: readonly [{
     readonly path: "/v1/social/me/cursor";
     readonly tag: "Social payments";
     readonly summary: "Retrieve the caller's receive cursor";
+    readonly description: "How far the caller's receive tree has been reserved, the key the last reservation used, and the caller's current `#key-1` read fresh from Oxy (ADR 0002). A 503 when Oxy cannot be asked for the current key.";
     readonly auth: "user";
     readonly query: z.ZodObject<{
         network: z.ZodEnum<{
@@ -200,6 +202,7 @@ export declare const socialRoutes: readonly [{
     readonly response: z.ZodObject<{
         reserved_through: z.ZodNumber;
         identity_public_key: z.ZodNullable<z.ZodString>;
+        account_identity_public_key: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>;
 }, {
     readonly operationId: "listSocialPayments";

package/dist/types/resources/payments/testHelpers.d.ts

@@ -124,6 +124,7 @@ export declare const paymentIntentTestHelperRoutes: readonly [{
             fraudulent: "fraudulent";
             abandoned: "abandoned";
             automatic: "automatic";
+            recipient_key_changed: "recipient_key_changed";
             requested_by_customer: "requested_by_customer";
             underpaid: "underpaid";
         }>>;
@@ -190,6 +191,7 @@ export declare const paymentIntentTestHelperRoutes: readonly [{
                 quoted_at: z.ZodNumber;
                 expires_at: z.ZodNumber;
             }, z.core.$strict>>;
+            recipient_key_replaced_at: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
         merchant_id: z.ZodString;
         connected_account: z.ZodNullable<z.ZodType<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">, z.core.$ZodTypeInternals<string | import("../..").Ref<"connected_account">, string | import("../..").Ref<"connected_account">>>>;

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

@@ -17,3 +17,4 @@ export * from './files';
 export * from './identity';
 export * from './merchants';
 export * from './paymentMethodConfigurations';
+export * from './realtime';

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

@@ -13,10 +13,14 @@ export type PaymentIntentRail = (typeof PAYMENT_INTENT_RAILS)[number];
 export declare const PAYMENT_INTENT_STATUSES: readonly ["requires_payment_method", "requires_confirmation", "requires_action", "processing", "requires_capture", "succeeded", "canceled"];
 export type PaymentIntentStatus = (typeof PAYMENT_INTENT_STATUSES)[number];
 /**
- * Why an intent was cancelled — Stripe's reasons, plus `underpaid` (FairCoin
- * only: a transaction paid less than the amount).
+ * Why an intent was cancelled — Stripe's reasons, plus two FairCoin-only ones:
+ * `underpaid` (a transaction paid less than the amount) and
+ * `recipient_key_changed` (the recipient's identity key was replaced after the
+ * address was reserved, so the address is no longer in the wallet it pays —
+ * ADR 0002, amended 2026-11-06; nothing had been broadcast, and the order stays
+ * open for a fresh address).
  */
-export declare const PAYMENT_INTENT_CANCELLATION_REASONS: readonly ["abandoned", "automatic", "duplicate", "fraudulent", "requested_by_customer", "underpaid"];
+export declare const PAYMENT_INTENT_CANCELLATION_REASONS: readonly ["abandoned", "automatic", "duplicate", "fraudulent", "recipient_key_changed", "requested_by_customer", "underpaid"];
 export type PaymentIntentCancellationReason = (typeof PAYMENT_INTENT_CANCELLATION_REASONS)[number];
 /** The reasons a MERCHANT may give `POST /v1/payment_intents/:id/cancel`. */
 export declare const MERCHANT_CANCELLATION_REASONS: readonly ["abandoned", "duplicate", "fraudulent", "requested_by_customer"];

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

@@ -0,0 +1,14 @@
+/**
+ * The PAYER realtime endpoint: the Socket.IO path a payer's browser opens to
+ * hear its payment move, by the intent's `client_secret` alone.
+ *
+ * It is a SEPARATE Socket.IO server from the gateway's default `/socket.io/`
+ * one, because Socket.IO decides CORS per server (per engine), before it
+ * knows which namespace or token a connection carries. The payer server
+ * answers any origin and takes no credentials — the same rule as the payer
+ * HTTP routes (`lib/payerCors.ts`): a merchant's own site runs Pay with
+ * Peable, and the capability is the secret, never the page. The default
+ * server keeps the Oxy origins (`createOxySocketCors`) for every socket that
+ * carries an Oxy identity.
+ */
+export declare const PAYER_SOCKET_PATH = "/payer-socket.io";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/contracts",
-  "version": "5.0.0",
+  "version": "5.2.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",