@peable.to/contracts 0.4.0 → 1.0.0

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

@@ -0,0 +1,242 @@
+import { z } from 'zod';
+import { listOf, searchResultOf } from '../../common/envelopes.js';
+import { defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, idParam, listQuery, metadataCreateParam, metadataUpdateParam, searchQuery, } from '../../common/params.js';
+import { amount, currency, livemode, metadata, nullableString, signedAmount, unixSeconds, } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { isBaseUnitString } from '../../vocabulary/money.js';
+import { REFUND_ORIGINS, REFUND_REASONS, REFUND_STATUSES, SETTLEMENT_STATUSES, } from '../../vocabulary/payments.js';
+/**
+ * Refunds (`re_…`) and a payment's settlement figures. The provider's own
+ * refund id never appears: a merchant integrates against Peable and never
+ * learns which acquirer sat behind it (ADR 0001 D3).
+ */
+export const refundSchema = defineObject('refund', 'Refund', z
+    .object({
+    id: z.string(),
+    object: z.literal('refund'),
+    livemode,
+    external_ref: nullableString.describe("YOUR id for this refund (its idempotency); `null` on a refund imported from the provider (`origin: 'provider'`)."),
+    origin: z
+        .enum(REFUND_ORIGINS)
+        .describe('`provider`: it appeared at the acquirer (a dashboard refund, a dispute resolved) and was imported.'),
+    payment_intent: expandable('payment_intent', 'The refunded payment (`pi_…`), or the PaymentIntent with `expand[]=payment_intent`.'),
+    amount,
+    currency,
+    status: z
+        .enum(REFUND_STATUSES)
+        .describe("The MONEY's own lifecycle: a bank can reject a refund days later (`failed`); `canceled` only through `POST /v1/refunds/{id}/cancel`."),
+    reason: z.enum(REFUND_REASONS).nullable(),
+    failure_code: nullableString.describe("The provider's machine-readable reason, when it failed."),
+    metadata,
+    created: unixSeconds,
+    updated_at: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 're_0193b8f2c1a87d3e9f4a',
+            object: 'refund',
+            livemode: false,
+            external_ref: 'order_6735_refund_1',
+            origin: 'merchant',
+            payment_intent: 'pi_0193b8f2c1a87d3e9f4a',
+            amount: '1000',
+            currency: 'EUR',
+            status: 'succeeded',
+            reason: 'requested_by_customer',
+            failure_code: null,
+            metadata: {},
+            created: 1793750400,
+            updated_at: 1793750460,
+        },
+    ],
+});
+/**
+ * What a payment actually came to, as the PROVIDER reports it. Every figure is
+ * nullable and that is the contract: "the fee was zero" and "the fee is not
+ * known yet" are different facts, and `status` says which produced the nulls.
+ * It reports what the provider took; it attributes that cost to nobody.
+ */
+export const settlementSchema = defineObject('settlement', 'Settlement', z
+    .object({
+    object: z.literal('settlement'),
+    livemode,
+    payment_intent: expandable('payment_intent', 'The `pi_…` this describes, or the PaymentIntent with `expand[]=payment_intent`.'),
+    status: z
+        .enum(SETTLEMENT_STATUSES)
+        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**.'),
+    gross: amount.nullable().describe('Base units of `currency`.'),
+    fee: amount.nullable(),
+    net: signedAmount.nullable(),
+    currency: nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217), which may differ from the payment's."),
+    available_on: unixSeconds.nullable().describe('When the funds become available.'),
+    exchange_rate: z
+        .number()
+        .nullable()
+        .describe('Present only when a conversion happened. `null` is not a rate of 1.'),
+})
+    .strict());
+export const createRefundParams = z
+    .object({
+    payment_intent: z.string().min(1).describe('The `pi_…` being refunded.'),
+    external_ref: z
+        .string()
+        .min(1)
+        .max(255)
+        .describe('YOUR id for this refund. The idempotency: the same ref answers the same refund.'),
+    // A zero refund is refused separately: `'0'` is a canonical integer string,
+    // and a zero refund would consume the merchant's `external_ref` so the REAL
+    // refund for that order could never be created afterwards.
+    amount: z
+        .string()
+        .refine(isBaseUnitString, 'amount must be a canonical integer string in minor units')
+        .refine((value) => value !== '0', 'a refund of 0 is not a refund')
+        .describe('Base units, as a canonical integer string. Zero is refused.'),
+    reason: z.enum(REFUND_REASONS).optional(),
+    metadata: metadataCreateParam.optional(),
+    refund_application_fee: z
+        .boolean()
+        .optional()
+        .describe("Also refund Orbit's application fee, in proportion (a destination charge)."),
+    reverse_transfer: z
+        .boolean()
+        .optional()
+        .describe('Also reverse the transfer to the destination account, in proportion.'),
+})
+    .strict();
+/** The merchant's own bookkeeping on a refund: `metadata`, a patch. */
+export const updateRefundParams = z.object({ metadata: metadataUpdateParam.optional() }).strict();
+export const cancelRefundParams = z.object({}).strict();
+export const listRefundsQuery = listQuery({
+    payment_intent: idParam.optional().describe("Only this payment's refunds (`pi_…`)."),
+});
+/** The per-payment sub-list: the payment is in the path. */
+export const listPaymentIntentRefundsQuery = listQuery({});
+/**
+ * A payment's refunds, with what is still refundable beside the envelope — the
+ * figure every merchant would otherwise compute by summing the list, and get
+ * wrong by counting a `pending` or `failed` refund.
+ */
+export const paymentIntentRefundListSchema = listOf(refundSchema).extend({
+    remaining_refundable: amount.describe('What can still be refunded on this payment, in base units. The same on every page.'),
+});
+const refundId = { id: 'The refund (`re_…`).' };
+const intentId = { intentId: 'The payment intent (`pi_…`).' };
+export const refundRoutes = [
+    defineRoute({
+        operationId: 'createRefund',
+        method: 'post',
+        path: '/v1/refunds',
+        tag: 'Refunds',
+        summary: 'Create a refund',
+        description: '`external_ref` decides whether money moves twice: a retry with the same ref answers the refund it made (200) whatever is still refundable.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createRefundParams,
+        response: refundSchema,
+        status: 201,
+        sdk: 'refunds.create',
+    }),
+    defineRoute({
+        operationId: 'listRefunds',
+        method: 'get',
+        path: '/v1/refunds',
+        tag: 'Refunds',
+        summary: 'List refunds',
+        description: "Every refund of the merchant, or of one payment — including those made outside Peable (`origin: 'provider'`).",
+        auth: 'service',
+        scope: 'payments:read',
+        query: listRefundsQuery,
+        response: listOf(refundSchema),
+        sdk: 'refunds.list',
+        expandable: 'refund',
+    }),
+    defineRoute({
+        operationId: 'retrieveRefund',
+        method: 'get',
+        path: '/v1/refunds/{id}',
+        tag: 'Refunds',
+        summary: 'Retrieve a refund',
+        auth: 'service',
+        scope: 'payments:read',
+        params: refundId,
+        query: expandOnlyQuery,
+        response: refundSchema,
+        sdk: 'refunds.retrieve',
+        expandable: 'refund',
+    }),
+    defineRoute({
+        operationId: 'updateRefund',
+        method: 'post',
+        path: '/v1/refunds/{id}',
+        tag: 'Refunds',
+        summary: 'Update a refund',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: refundId,
+        body: updateRefundParams,
+        response: refundSchema,
+        sdk: 'refunds.update',
+    }),
+    defineRoute({
+        operationId: 'cancelRefund',
+        method: 'post',
+        path: '/v1/refunds/{id}/cancel',
+        tag: 'Refunds',
+        summary: 'Cancel a refund',
+        description: 'Only while the provider still holds it; otherwise 400 `refund_not_cancelable`.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: refundId,
+        body: cancelRefundParams,
+        response: refundSchema,
+        sdk: 'refunds.cancel',
+    }),
+    defineRoute({
+        operationId: 'listPaymentIntentRefunds',
+        method: 'get',
+        path: '/v1/payment_intents/{intentId}/refunds',
+        tag: 'Refunds',
+        summary: "List a payment's refunds",
+        auth: 'service',
+        scope: 'payments:read',
+        params: intentId,
+        query: listPaymentIntentRefundsQuery,
+        response: paymentIntentRefundListSchema,
+        sdk: 'refunds.listForPaymentIntent',
+        expandable: 'refund',
+    }),
+    defineRoute({
+        operationId: 'retrievePaymentIntentSettlement',
+        method: 'get',
+        path: '/v1/payment_intents/{intentId}/settlement',
+        tag: 'Refunds',
+        summary: "Retrieve a payment's settlement",
+        description: 'Gross, fee and net, read live from the provider. A missing figure is `null` with a `status`, never `0`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: intentId,
+        query: expandOnlyQuery,
+        response: settlementSchema,
+        sdk: 'refunds.settlement',
+        expandable: 'settlement',
+    }),
+    defineRoute({
+        operationId: 'searchRefunds',
+        method: 'get',
+        path: '/v1/refunds/search',
+        tag: 'Refunds',
+        summary: 'Search refunds',
+        description: "Stripe's query language over `amount`, `currency`, `status`, `reason`, `payment_intent`, `created` and `metadata['key']`.",
+        auth: 'service',
+        scope: 'payments:read',
+        query: searchQuery,
+        response: searchResultOf(refundSchema),
+        sdk: 'refunds.search',
+        expandable: 'refund',
+    }),
+];

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

@@ -0,0 +1,155 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineObject, expandable } from '../../common/objects.js';
+import { expandParam, idParam, listQuery, metadataCreateParam, retrieveQuery, } from '../../common/params.js';
+import { livemode, metadata, nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { SETUP_INTENT_CANCELLATION_REASONS, SETUP_INTENT_STATUSES, SETUP_INTENT_USAGES, } from '../../vocabulary/payments.js';
+import { clientActionSchema, clientSecretParam, clientSecretQuery, paymentErrorSchema, } from './paymentIntents.js';
+/**
+ * SetupIntents (`seti_…`) — saving a card for later without charging it
+ * (ADR 0016, ADR 0019). The provider SetupIntent is an internal binding; its
+ * success is what creates the Peable `pm_…`, attached to the customer.
+ */
+export const setupIntentSchema = defineObject('setup_intent', 'SetupIntent', z
+    .object({
+    id: z.string(),
+    object: z.literal('setup_intent'),
+    livemode,
+    status: z.enum(SETUP_INTENT_STATUSES),
+    usage: z.enum(SETUP_INTENT_USAGES),
+    payment_method_types: z.tuple([z.literal('card')]),
+    customer: expandable('customer', '`cus_…`, or the Customer with `expand[]=customer`.').nullable(),
+    payment_method: expandable('payment_method', 'The `pm_…` it saved, once `succeeded`, or the PaymentMethod with `expand[]=payment_method`.').nullable(),
+    client_secret: z
+        .string()
+        .describe("Possession of it lets the payer's browser confirm this SetupIntent."),
+    next_action: z
+        .object({ type: z.literal('use_peable_sdk') })
+        .strict()
+        .nullable(),
+    last_setup_error: paymentErrorSchema.nullable(),
+    cancellation_reason: z.enum(SETUP_INTENT_CANCELLATION_REASONS).nullable(),
+    description: nullableString,
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'seti_0193b8f2c1a87d3e9f4a',
+            object: 'setup_intent',
+            livemode: false,
+            status: 'requires_payment_method',
+            usage: 'off_session',
+            payment_method_types: ['card'],
+            customer: 'cus_0193b8f2c1a87d3e9f4a',
+            payment_method: null,
+            client_secret: 'seti_0193b8f2c1a87d3e9f4a_secret_9a1b2c',
+            next_action: null,
+            last_setup_error: null,
+            cancellation_reason: null,
+            description: null,
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+export const createSetupIntentParams = z
+    .object({
+    customer: idParam
+        .optional()
+        .describe('The customer (`cus_…`) the card is saved to. Required: a `pm_…` is born attached.'),
+    usage: z.enum(SETUP_INTENT_USAGES).optional().describe('Defaults to `off_session`.'),
+    payment_method_types: z.tuple([z.literal('card')]).optional(),
+    description: z.string().max(1000).optional(),
+    metadata: metadataCreateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const cancelSetupIntentParams = z
+    .object({
+    cancellation_reason: z.enum(SETUP_INTENT_CANCELLATION_REASONS).optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const listSetupIntentsQuery = listQuery({
+    customer: idParam.optional().describe("Only this customer's setup intents (`cus_…`)."),
+});
+/** A merchant retrieve takes `expand[]`; the payer's takes `client_secret` and nothing to expand. */
+export const retrieveSetupIntentQuery = retrieveQuery({ client_secret: clientSecretParam });
+const setupIntentId = { id: 'The setup intent (`seti_…`).' };
+export const setupIntentRoutes = [
+    defineRoute({
+        operationId: 'createSetupIntent',
+        method: 'post',
+        path: '/v1/setup_intents',
+        tag: 'Setup intents',
+        summary: 'Create a setup intent',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createSetupIntentParams,
+        response: setupIntentSchema,
+        status: 201,
+        sdk: 'setupIntents.create',
+        expandable: 'setup_intent',
+    }),
+    defineRoute({
+        operationId: 'listSetupIntents',
+        method: 'get',
+        path: '/v1/setup_intents',
+        tag: 'Setup intents',
+        summary: 'List setup intents',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listSetupIntentsQuery,
+        response: listOf(setupIntentSchema),
+        sdk: 'setupIntents.list',
+        expandable: 'setup_intent',
+    }),
+    defineRoute({
+        operationId: 'retrieveSetupIntent',
+        method: 'get',
+        path: '/v1/setup_intents/{id}',
+        tag: 'Setup intents',
+        summary: 'Retrieve a setup intent',
+        description: 'With the merchant credential: reconciled with the provider when not terminal, expandable. Without one, the PAYER reads the row as stored with its `client_secret` (the `X-Peable-Client-Secret` header, or the query).',
+        auth: 'service',
+        scope: 'payments:read',
+        params: setupIntentId,
+        query: retrieveSetupIntentQuery,
+        response: setupIntentSchema,
+        sdk: 'setupIntents.retrieve',
+        expandable: 'setup_intent',
+    }),
+    defineRoute({
+        operationId: 'cancelSetupIntent',
+        method: 'post',
+        path: '/v1/setup_intents/{id}/cancel',
+        tag: 'Setup intents',
+        summary: 'Cancel a setup intent',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: setupIntentId,
+        body: cancelSetupIntentParams,
+        response: setupIntentSchema,
+        sdk: 'setupIntents.cancel',
+        expandable: 'setup_intent',
+    }),
+    defineRoute({
+        operationId: 'retrieveSetupIntentClientAction',
+        method: 'post',
+        path: '/v1/setup_intents/{id}/client_action',
+        tag: 'Setup intents',
+        summary: "Retrieve a setup intent's client action",
+        description: "The provider credential the payer's client confirms the SetupIntent with — read fresh, `Cache-Control: no-store`, never on the object. The merchant credential, or the payer's `client_secret` (`X-Peable-Client-Secret`). A succeeded or canceled setup intent answers 409.",
+        auth: 'service',
+        scope: 'payments:read',
+        params: setupIntentId,
+        query: clientSecretQuery,
+        response: clientActionSchema,
+        sdk: 'setupIntents.clientAction',
+    }),
+];

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

@@ -0,0 +1,179 @@
+import { z } from 'zod';
+import { defineComponent } from '../../common/objects.js';
+import { network, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { ENRICH_MAX_ADDRESSES, ENRICHMENT_KINDS, SOCIAL_PAYMENT_DIRECTIONS, SOCIAL_SOURCE_APP_MAX_LENGTH, SOCIAL_SOURCE_REF_MAX_LENGTH, } from '../../vocabulary/payments.js';
+/**
+ * Social payments (pay a person by `@username`) and transaction enrichment —
+ * the wallet's routes, called with the person's own Oxy session. Display-only
+ * context throughout: nothing here decides where money goes; the address comes
+ * from the recipient's identity key and their reservation cursor.
+ */
+/**
+ * Display-only context for one social payment: which app the payer was in, and
+ * that app's own opaque id for what it was for (a Mention post, say). Peable
+ * never parses, resolves or links `ref`; it stores a string and hands the same
+ * string back.
+ */
+export const socialPaymentSourceSchema = defineComponent('SocialPaymentSource', z
+    .object({
+    app: z.string().describe("The calling app's slug, e.g. `mention`."),
+    ref: z
+        .string()
+        .optional()
+        .describe("That app's own opaque id for what the payment was for; absent when it named none."),
+})
+    .strict());
+/**
+ * Display-only counterparty identity for one address, as `POST /v1/enrich`
+ * resolves it. A failed or partial resolution degrades to `{ kind: 'unknown' }`.
+ */
+export const enrichmentResultSchema = defineComponent('EnrichmentResult', z
+    .object({
+    kind: z.enum(ENRICHMENT_KINDS),
+    display_name: z
+        .string()
+        .optional()
+        .describe("The merchant's name, or the user's display name (else handle)."),
+    avatar_file_id: z
+        .string()
+        .optional()
+        .describe('A bare Oxy file id — render through the media chokepoint, never as a URL.'),
+    username: z.string().optional().describe("`kind: 'user'` only."),
+    description: z.string().optional().describe("`kind: 'merchant'` only."),
+})
+    .strict());
+/**
+ * `.strict()` is load-bearing: `{ app, postId }` — the obvious misspelling of
+ * `ref` — would otherwise reserve an address and record a context missing the
+ * only part the recipient cares about, with a 200. `ref` is validated for SHAPE
+ * (printable non-space ASCII) and never for meaning, so it cannot become a
+ * free-text memo the gateway stores on behalf of two users.
+ */
+export const socialPaymentSourceParams = z
+    .object({
+    app: z
+        .string()
+        .min(1)
+        .max(SOCIAL_SOURCE_APP_MAX_LENGTH)
+        .regex(/^[a-z0-9][a-z0-9._-]*$/, 'source.app must be a lowercase app slug'),
+    ref: z
+        .string()
+        .min(1)
+        .max(SOCIAL_SOURCE_REF_MAX_LENGTH)
+        .regex(/^[\x21-\x7e]+$/, 'source.ref must be an opaque id, without spaces')
+        .optional(),
+})
+    .strict();
+/** `source` is OPTIONAL and stays that way: most person-to-person payments are for nothing in particular. */
+export const socialNextAddressParams = z
+    .object({
+    network,
+    source: socialPaymentSourceParams.optional(),
+})
+    .strict();
+export const socialNextAddressSchema = defineComponent('SocialNextAddress', z
+    .object({
+    address: z.string().describe("A fresh single-use address of the recipient's."),
+    index: z.number().int().nonnegative().describe('Its social-receive derivation index.'),
+})
+    .strict());
+const networkQuery = z.object({ network });
+export const socialReceiveCursorQuery = networkQuery;
+/**
+ * Lets the caller's device resync its watch window: every `next_address`
+ * advances a monotonic index whether or not it is ever paid, so a burst of
+ * reservations can outrun a device that widens only on payment. Watch
+ * `0..reserved_through + gap`.
+ */
+export const socialReceiveCursorSchema = defineComponent('SocialReceiveCursor', z
+    .object({
+    reserved_through: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('The highest social-receive index ever reserved for the caller on this network; `0` when none was.'),
+    identity_public_key: z
+        .string()
+        .nullable()
+        .describe('The identity public key (hex) those addresses derive from; `null` exactly when no address was ever reserved.'),
+})
+    .strict());
+export const socialPaymentsQuery = networkQuery;
+/**
+ * One social payment as the CALLER saw it — the address-free view, and the
+ * only history a surface without a key can ask for. Carries NO amount: the
+ * attribution records which address was minted, not what was paid; the amount
+ * is on-chain at `address`.
+ */
+export const socialPaymentSchema = defineComponent('SocialPayment', z
+    .object({
+    address: z
+        .string()
+        .describe('The single-use social-receive address minted for this payment.'),
+    direction: z.enum(SOCIAL_PAYMENT_DIRECTIONS),
+    counterparty: enrichmentResultSchema.describe("The other party; `{ kind: 'unknown' }` when the identity lookup failed."),
+    source: socialPaymentSourceSchema
+        .optional()
+        .describe('What it was for, as the paying app named it; absent when it named nothing.'),
+    created: unixSeconds.describe('When the address was minted.'),
+})
+    .strict());
+export const socialPaymentsSchema = defineComponent('SocialPayments', z.object({ payments: z.array(socialPaymentSchema).describe('Newest first.') }).strict());
+export const enrichParams = z
+    .object({
+    addresses: z.array(z.string().min(1)).min(1).max(ENRICH_MAX_ADDRESSES),
+})
+    .strict();
+export const enrichSchema = defineComponent('Enrichment', z
+    .object({
+    data: z
+        .record(z.string(), enrichmentResultSchema)
+        .describe('Every address asked for → who is behind it.'),
+})
+    .strict());
+export const socialRoutes = [
+    defineRoute({
+        operationId: 'reserveSocialAddress',
+        method: 'post',
+        path: '/v1/social/{username}/next_address',
+        tag: 'Social payments',
+        summary: 'Reserve an address to pay a person',
+        description: "A fresh address of the recipient's, derived from their Oxy identity key. Limited per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`; paying yourself is refused.",
+        auth: 'user',
+        params: { username: 'The recipient’s Oxy username.' },
+        body: socialNextAddressParams,
+        response: socialNextAddressSchema,
+    }),
+    defineRoute({
+        operationId: 'retrieveSocialReceiveCursor',
+        method: 'get',
+        path: '/v1/social/me/cursor',
+        tag: 'Social payments',
+        summary: "Retrieve the caller's receive cursor",
+        auth: 'user',
+        query: socialReceiveCursorQuery,
+        response: socialReceiveCursorSchema,
+    }),
+    defineRoute({
+        operationId: 'listSocialPayments',
+        method: 'get',
+        path: '/v1/social/me/payments',
+        tag: 'Social payments',
+        summary: "List the caller's social payments",
+        auth: 'user',
+        query: socialPaymentsQuery,
+        response: socialPaymentsSchema,
+    }),
+    defineRoute({
+        operationId: 'enrichAddresses',
+        method: 'post',
+        path: '/v1/enrich',
+        tag: 'Social payments',
+        summary: 'Resolve who is behind addresses',
+        description: 'Display-only counterparty identity for the caller’s own payments; never affects custody.',
+        auth: 'user',
+        body: enrichParams,
+        response: enrichSchema,
+    }),
+];

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

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { defineRoute } from '../../route.js';
+import { SIMULATED_FAIRCOIN_OUTCOMES } from '../../vocabulary/payments.js';
+import { paymentIntentSchema } from './paymentIntents.js';
+/**
+ * Test helpers for payment intents — test mode only. They drive a test-mode
+ * payment through the SAME state machine a real one moves through, with the
+ * same events and webhooks, so an integration is exercised end to end without
+ * a wallet.
+ */
+export const simulateFaircoinPaymentParams = z
+    .object({
+    outcome: z
+        .enum(SIMULATED_FAIRCOIN_OUTCOMES)
+        .optional()
+        .describe('`settled` (the default): paid in full, seen and confirmed. `underpaid`: less than the amount arrived.'),
+})
+    .strict();
+export const paymentIntentTestHelperRoutes = [
+    defineRoute({
+        operationId: 'simulateFaircoinPayment',
+        method: 'post',
+        path: '/v1/test_helpers/payment_intents/{id}/simulate_faircoin_payment',
+        tag: 'Test helpers',
+        summary: 'Simulate a FairCoin payment',
+        description: 'Pretend the payer broadcast and the chain confirmed (or underpaid) a FairCoin payment in `requires_action`. A live credential is refused with 403 `test_mode_only`.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        testModeOnly: true,
+        params: { id: 'The payment intent (`pi_…`).' },
+        body: simulateFaircoinPaymentParams,
+        response: paymentIntentSchema,
+        sdk: 'testHelpers.paymentIntents.simulateFaircoinPayment',
+    }),
+];