@peable.to/contracts 0.4.0 → 1.0.0

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

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refundRoutes = exports.paymentIntentRefundListSchema = exports.listPaymentIntentRefundsQuery = exports.listRefundsQuery = exports.cancelRefundParams = exports.updateRefundParams = exports.createRefundParams = exports.settlementSchema = exports.refundSchema = void 0;
+const zod_1 = require("zod");
+const envelopes_1 = require("../../common/envelopes");
+const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+const money_1 = require("../../vocabulary/money");
+const payments_1 = require("../../vocabulary/payments");
+/**
+ * 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).
+ */
+exports.refundSchema = (0, objects_1.defineObject)('refund', 'Refund', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('refund'),
+    livemode: primitives_1.livemode,
+    external_ref: primitives_1.nullableString.describe("YOUR id for this refund (its idempotency); `null` on a refund imported from the provider (`origin: 'provider'`)."),
+    origin: zod_1.z
+        .enum(payments_1.REFUND_ORIGINS)
+        .describe('`provider`: it appeared at the acquirer (a dashboard refund, a dispute resolved) and was imported.'),
+    payment_intent: (0, objects_1.expandable)('payment_intent', 'The refunded payment (`pi_…`), or the PaymentIntent with `expand[]=payment_intent`.'),
+    amount: primitives_1.amount,
+    currency: primitives_1.currency,
+    status: zod_1.z
+        .enum(payments_1.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: zod_1.z.enum(payments_1.REFUND_REASONS).nullable(),
+    failure_code: primitives_1.nullableString.describe("The provider's machine-readable reason, when it failed."),
+    metadata: primitives_1.metadata,
+    created: primitives_1.unixSeconds,
+    updated_at: primitives_1.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.
+ */
+exports.settlementSchema = (0, objects_1.defineObject)('settlement', 'Settlement', zod_1.z
+    .object({
+    object: zod_1.z.literal('settlement'),
+    livemode: primitives_1.livemode,
+    payment_intent: (0, objects_1.expandable)('payment_intent', 'The `pi_…` this describes, or the PaymentIntent with `expand[]=payment_intent`.'),
+    status: zod_1.z
+        .enum(payments_1.SETTLEMENT_STATUSES)
+        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**.'),
+    gross: primitives_1.amount.nullable().describe('Base units of `currency`.'),
+    fee: primitives_1.amount.nullable(),
+    net: primitives_1.signedAmount.nullable(),
+    currency: primitives_1.nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217), which may differ from the payment's."),
+    available_on: primitives_1.unixSeconds.nullable().describe('When the funds become available.'),
+    exchange_rate: zod_1.z
+        .number()
+        .nullable()
+        .describe('Present only when a conversion happened. `null` is not a rate of 1.'),
+})
+    .strict());
+exports.createRefundParams = zod_1.z
+    .object({
+    payment_intent: zod_1.z.string().min(1).describe('The `pi_…` being refunded.'),
+    external_ref: zod_1.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: zod_1.z
+        .string()
+        .refine(money_1.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: zod_1.z.enum(payments_1.REFUND_REASONS).optional(),
+    metadata: params_1.metadataCreateParam.optional(),
+    refund_application_fee: zod_1.z
+        .boolean()
+        .optional()
+        .describe("Also refund Orbit's application fee, in proportion (a destination charge)."),
+    reverse_transfer: zod_1.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. */
+exports.updateRefundParams = zod_1.z.object({ metadata: params_1.metadataUpdateParam.optional() }).strict();
+exports.cancelRefundParams = zod_1.z.object({}).strict();
+exports.listRefundsQuery = (0, params_1.listQuery)({
+    payment_intent: params_1.idParam.optional().describe("Only this payment's refunds (`pi_…`)."),
+});
+/** The per-payment sub-list: the payment is in the path. */
+exports.listPaymentIntentRefundsQuery = (0, params_1.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.
+ */
+exports.paymentIntentRefundListSchema = (0, envelopes_1.listOf)(exports.refundSchema).extend({
+    remaining_refundable: primitives_1.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_…`).' };
+exports.refundRoutes = [
+    (0, route_1.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: exports.createRefundParams,
+        response: exports.refundSchema,
+        status: 201,
+        sdk: 'refunds.create',
+    }),
+    (0, route_1.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: exports.listRefundsQuery,
+        response: (0, envelopes_1.listOf)(exports.refundSchema),
+        sdk: 'refunds.list',
+        expandable: 'refund',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveRefund',
+        method: 'get',
+        path: '/v1/refunds/{id}',
+        tag: 'Refunds',
+        summary: 'Retrieve a refund',
+        auth: 'service',
+        scope: 'payments:read',
+        params: refundId,
+        query: params_1.expandOnlyQuery,
+        response: exports.refundSchema,
+        sdk: 'refunds.retrieve',
+        expandable: 'refund',
+    }),
+    (0, route_1.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: exports.updateRefundParams,
+        response: exports.refundSchema,
+        sdk: 'refunds.update',
+    }),
+    (0, route_1.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: exports.cancelRefundParams,
+        response: exports.refundSchema,
+        sdk: 'refunds.cancel',
+    }),
+    (0, route_1.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: exports.listPaymentIntentRefundsQuery,
+        response: exports.paymentIntentRefundListSchema,
+        sdk: 'refunds.listForPaymentIntent',
+        expandable: 'refund',
+    }),
+    (0, route_1.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: params_1.expandOnlyQuery,
+        response: exports.settlementSchema,
+        sdk: 'refunds.settlement',
+        expandable: 'settlement',
+    }),
+    (0, route_1.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: params_1.searchQuery,
+        response: (0, envelopes_1.searchResultOf)(exports.refundSchema),
+        sdk: 'refunds.search',
+        expandable: 'refund',
+    }),
+];

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

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupIntentRoutes = exports.retrieveSetupIntentQuery = exports.listSetupIntentsQuery = exports.cancelSetupIntentParams = exports.createSetupIntentParams = exports.setupIntentSchema = void 0;
+const zod_1 = require("zod");
+const envelopes_1 = require("../../common/envelopes");
+const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+const payments_1 = require("../../vocabulary/payments");
+const paymentIntents_1 = require("./paymentIntents");
+/**
+ * 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.
+ */
+exports.setupIntentSchema = (0, objects_1.defineObject)('setup_intent', 'SetupIntent', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('setup_intent'),
+    livemode: primitives_1.livemode,
+    status: zod_1.z.enum(payments_1.SETUP_INTENT_STATUSES),
+    usage: zod_1.z.enum(payments_1.SETUP_INTENT_USAGES),
+    payment_method_types: zod_1.z.tuple([zod_1.z.literal('card')]),
+    customer: (0, objects_1.expandable)('customer', '`cus_…`, or the Customer with `expand[]=customer`.').nullable(),
+    payment_method: (0, objects_1.expandable)('payment_method', 'The `pm_…` it saved, once `succeeded`, or the PaymentMethod with `expand[]=payment_method`.').nullable(),
+    client_secret: zod_1.z
+        .string()
+        .describe("Possession of it lets the payer's browser confirm this SetupIntent."),
+    next_action: zod_1.z
+        .object({ type: zod_1.z.literal('use_peable_sdk') })
+        .strict()
+        .nullable(),
+    last_setup_error: paymentIntents_1.paymentErrorSchema.nullable(),
+    cancellation_reason: zod_1.z.enum(payments_1.SETUP_INTENT_CANCELLATION_REASONS).nullable(),
+    description: primitives_1.nullableString,
+    metadata: primitives_1.metadata,
+    created: primitives_1.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,
+        },
+    ],
+});
+exports.createSetupIntentParams = zod_1.z
+    .object({
+    customer: params_1.idParam
+        .optional()
+        .describe('The customer (`cus_…`) the card is saved to. Required: a `pm_…` is born attached.'),
+    usage: zod_1.z.enum(payments_1.SETUP_INTENT_USAGES).optional().describe('Defaults to `off_session`.'),
+    payment_method_types: zod_1.z.tuple([zod_1.z.literal('card')]).optional(),
+    description: zod_1.z.string().max(1000).optional(),
+    metadata: params_1.metadataCreateParam.optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+exports.cancelSetupIntentParams = zod_1.z
+    .object({
+    cancellation_reason: zod_1.z.enum(payments_1.SETUP_INTENT_CANCELLATION_REASONS).optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+exports.listSetupIntentsQuery = (0, params_1.listQuery)({
+    customer: params_1.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. */
+exports.retrieveSetupIntentQuery = (0, params_1.retrieveQuery)({ client_secret: paymentIntents_1.clientSecretParam });
+const setupIntentId = { id: 'The setup intent (`seti_…`).' };
+exports.setupIntentRoutes = [
+    (0, route_1.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: exports.createSetupIntentParams,
+        response: exports.setupIntentSchema,
+        status: 201,
+        sdk: 'setupIntents.create',
+        expandable: 'setup_intent',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listSetupIntents',
+        method: 'get',
+        path: '/v1/setup_intents',
+        tag: 'Setup intents',
+        summary: 'List setup intents',
+        auth: 'service',
+        scope: 'payments:read',
+        query: exports.listSetupIntentsQuery,
+        response: (0, envelopes_1.listOf)(exports.setupIntentSchema),
+        sdk: 'setupIntents.list',
+        expandable: 'setup_intent',
+    }),
+    (0, route_1.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: exports.retrieveSetupIntentQuery,
+        response: exports.setupIntentSchema,
+        sdk: 'setupIntents.retrieve',
+        expandable: 'setup_intent',
+    }),
+    (0, route_1.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: exports.cancelSetupIntentParams,
+        response: exports.setupIntentSchema,
+        sdk: 'setupIntents.cancel',
+        expandable: 'setup_intent',
+    }),
+    (0, route_1.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: paymentIntents_1.clientSecretQuery,
+        response: paymentIntents_1.clientActionSchema,
+        sdk: 'setupIntents.clientAction',
+    }),
+];

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

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.socialRoutes = exports.enrichSchema = exports.enrichParams = exports.socialPaymentsSchema = exports.socialPaymentSchema = exports.socialPaymentsQuery = exports.socialReceiveCursorSchema = exports.socialReceiveCursorQuery = exports.socialNextAddressSchema = exports.socialNextAddressParams = exports.socialPaymentSourceParams = exports.enrichmentResultSchema = exports.socialPaymentSourceSchema = void 0;
+const zod_1 = require("zod");
+const objects_1 = require("../../common/objects");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+const payments_1 = require("../../vocabulary/payments");
+/**
+ * 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.
+ */
+exports.socialPaymentSourceSchema = (0, objects_1.defineComponent)('SocialPaymentSource', zod_1.z
+    .object({
+    app: zod_1.z.string().describe("The calling app's slug, e.g. `mention`."),
+    ref: zod_1.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' }`.
+ */
+exports.enrichmentResultSchema = (0, objects_1.defineComponent)('EnrichmentResult', zod_1.z
+    .object({
+    kind: zod_1.z.enum(payments_1.ENRICHMENT_KINDS),
+    display_name: zod_1.z
+        .string()
+        .optional()
+        .describe("The merchant's name, or the user's display name (else handle)."),
+    avatar_file_id: zod_1.z
+        .string()
+        .optional()
+        .describe('A bare Oxy file id — render through the media chokepoint, never as a URL.'),
+    username: zod_1.z.string().optional().describe("`kind: 'user'` only."),
+    description: zod_1.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.
+ */
+exports.socialPaymentSourceParams = zod_1.z
+    .object({
+    app: zod_1.z
+        .string()
+        .min(1)
+        .max(payments_1.SOCIAL_SOURCE_APP_MAX_LENGTH)
+        .regex(/^[a-z0-9][a-z0-9._-]*$/, 'source.app must be a lowercase app slug'),
+    ref: zod_1.z
+        .string()
+        .min(1)
+        .max(payments_1.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. */
+exports.socialNextAddressParams = zod_1.z
+    .object({
+    network: primitives_1.network,
+    source: exports.socialPaymentSourceParams.optional(),
+})
+    .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."),
+    index: zod_1.z.number().int().nonnegative().describe('Its social-receive derivation index.'),
+})
+    .strict());
+const networkQuery = zod_1.z.object({ network: primitives_1.network });
+exports.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`.
+ */
+exports.socialReceiveCursorSchema = (0, objects_1.defineComponent)('SocialReceiveCursor', zod_1.z
+    .object({
+    reserved_through: zod_1.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: zod_1.z
+        .string()
+        .nullable()
+        .describe('The identity public key (hex) those addresses derive from; `null` exactly when no address was ever reserved.'),
+})
+    .strict());
+exports.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`.
+ */
+exports.socialPaymentSchema = (0, objects_1.defineComponent)('SocialPayment', zod_1.z
+    .object({
+    address: zod_1.z
+        .string()
+        .describe('The single-use social-receive address minted for this payment.'),
+    direction: zod_1.z.enum(payments_1.SOCIAL_PAYMENT_DIRECTIONS),
+    counterparty: exports.enrichmentResultSchema.describe("The other party; `{ kind: 'unknown' }` when the identity lookup failed."),
+    source: exports.socialPaymentSourceSchema
+        .optional()
+        .describe('What it was for, as the paying app named it; absent when it named nothing.'),
+    created: primitives_1.unixSeconds.describe('When the address was minted.'),
+})
+    .strict());
+exports.socialPaymentsSchema = (0, objects_1.defineComponent)('SocialPayments', zod_1.z.object({ payments: zod_1.z.array(exports.socialPaymentSchema).describe('Newest first.') }).strict());
+exports.enrichParams = zod_1.z
+    .object({
+    addresses: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(payments_1.ENRICH_MAX_ADDRESSES),
+})
+    .strict();
+exports.enrichSchema = (0, objects_1.defineComponent)('Enrichment', zod_1.z
+    .object({
+    data: zod_1.z
+        .record(zod_1.z.string(), exports.enrichmentResultSchema)
+        .describe('Every address asked for → who is behind it.'),
+})
+    .strict());
+exports.socialRoutes = [
+    (0, route_1.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: exports.socialNextAddressParams,
+        response: exports.socialNextAddressSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveSocialReceiveCursor',
+        method: 'get',
+        path: '/v1/social/me/cursor',
+        tag: 'Social payments',
+        summary: "Retrieve the caller's receive cursor",
+        auth: 'user',
+        query: exports.socialReceiveCursorQuery,
+        response: exports.socialReceiveCursorSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listSocialPayments',
+        method: 'get',
+        path: '/v1/social/me/payments',
+        tag: 'Social payments',
+        summary: "List the caller's social payments",
+        auth: 'user',
+        query: exports.socialPaymentsQuery,
+        response: exports.socialPaymentsSchema,
+    }),
+    (0, route_1.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: exports.enrichParams,
+        response: exports.enrichSchema,
+    }),
+];

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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paymentIntentTestHelperRoutes = exports.simulateFaircoinPaymentParams = void 0;
+const zod_1 = require("zod");
+const route_1 = require("../../route");
+const payments_1 = require("../../vocabulary/payments");
+const paymentIntents_1 = require("./paymentIntents");
+/**
+ * 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.
+ */
+exports.simulateFaircoinPaymentParams = zod_1.z
+    .object({
+    outcome: zod_1.z
+        .enum(payments_1.SIMULATED_FAIRCOIN_OUTCOMES)
+        .optional()
+        .describe('`settled` (the default): paid in full, seen and confirmed. `underpaid`: less than the amount arrived.'),
+})
+    .strict();
+exports.paymentIntentTestHelperRoutes = [
+    (0, route_1.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: exports.simulateFaircoinPaymentParams,
+        response: paymentIntents_1.paymentIntentSchema,
+        sdk: 'testHelpers.paymentIntents.simulateFaircoinPayment',
+    }),
+];