@peable.to/contracts 0.3.0 → 1.0.0

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

@@ -0,0 +1,327 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, expandParam, listQuery, metadataCreateParam, metadataUpdateParam, queryBoolean, } from '../../common/params.js';
+import { currency, livemode, metadata, network, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { CHECKOUT_CUSTOMER_CREATIONS, CHECKOUT_LOCALES, CHECKOUT_SUBMIT_TYPES, PAYMENT_LINK_LIMITS, } from '../../vocabulary/checkout.js';
+import { contributionAmountSchema, contributionDetailsSchema } from './contributions.js';
+import { adjustableIssues, adjustableQuantityParam, checkoutBrandingSchema, checkoutIdParam, checkoutLineItemSchema, collectionParams, collectionResponseFields, localeParam, merchantDisplaySchema, quantityParam, railSchema, redirectUrlParam, } from './shared.js';
+/**
+ * Payment Links (`link_…`, Orbit Phase 3) — Stripe's model: a shareable URL
+ * over catalog PRICES. A payer visiting it creates a Checkout Session with the
+ * link's line items and options; the session creates the payment when the
+ * payer confirms. Nothing about a link mints a payment on its own.
+ *
+ * A contribution link (an Oxy organization's FairCoin collection) is a payment
+ * link whose one line is the contribution itself — a fixed amount, or one the
+ * payer chooses — rather than a price.
+ */
+export const checkoutAfterCompletionSchema = defineComponent('CheckoutAfterCompletion', z
+    .object({
+    type: z.enum(['redirect', 'hosted_confirmation']),
+    redirect: z.object({ url: z.string() }).strict().nullable(),
+    hosted_confirmation: z.object({ custom_message: z.string().nullable() }).strict().nullable(),
+})
+    .strict());
+const linkFields = {
+    id: z.string(),
+    object: z.literal('payment_link'),
+    livemode,
+    active: z.boolean(),
+    currency,
+    rail: railSchema,
+    network: network.nullable(),
+    line_items: z
+        .array(checkoutLineItemSchema)
+        .describe("The link's prices (`GET /v1/payment_links/{id}/line_items` lists them in full)."),
+    contribution: contributionDetailsSchema
+        .optional()
+        .describe('Present on an organization contribution link (FairCoin).'),
+    locale: z.enum(CHECKOUT_LOCALES).nullable(),
+};
+export const paymentLinkSchema = defineObject('payment_link', 'PaymentLink', z
+    .object({
+    ...linkFields,
+    allow_promotion_codes: z.boolean(),
+    ...collectionResponseFields,
+    automatic_tax: z.object({ enabled: z.boolean() }).strict(),
+    customer_creation: z.enum(CHECKOUT_CUSTOMER_CREATIONS),
+    after_completion: checkoutAfterCompletionSchema,
+    restrictions: z
+        .object({
+        completed_sessions: z
+            .object({ limit: z.number().int(), count: z.number().int() })
+            .strict(),
+    })
+        .strict()
+        .nullable(),
+    submit_type: z.enum(CHECKOUT_SUBMIT_TYPES),
+    metadata,
+    url: z
+        .string()
+        .describe('`checkout.peable.to/l/<id>` — share it, or render it as a QR code.'),
+    created: unixSeconds,
+    updated_at: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'link_0193b8f2c1a87d3e9f4a',
+            object: 'payment_link',
+            livemode: false,
+            active: true,
+            currency: 'EUR',
+            rail: 'card',
+            network: null,
+            line_items: [],
+            allow_promotion_codes: false,
+            billing_address_collection: 'auto',
+            shipping_address_collection: null,
+            phone_number_collection: { enabled: false },
+            tax_id_collection: { enabled: false },
+            custom_fields: [],
+            consent_collection: null,
+            automatic_tax: { enabled: false },
+            customer_creation: 'if_required',
+            after_completion: {
+                type: 'hosted_confirmation',
+                redirect: null,
+                hosted_confirmation: { custom_message: null },
+            },
+            restrictions: null,
+            submit_type: 'auto',
+            locale: null,
+            metadata: {},
+            url: 'https://checkout.peable.to/l/link_0193b8f2c1a87d3e9f4a',
+            created: 1793750400,
+            updated_at: 1793750400,
+        },
+    ],
+});
+/** What an anonymous visitor may see before checkout starts — no metadata, no counts. */
+export const publicPaymentLinkSchema = defineComponent('PublicPaymentLink', z
+    .object({
+    ...linkFields,
+    contribution_amount: z
+        .string()
+        .nullable()
+        .describe("A fixed contribution's amount; `null` when the payer chooses (or for a price link)."),
+    merchant: merchantDisplaySchema,
+    branding: checkoutBrandingSchema,
+})
+    .strict());
+/** `POST /v1/payment_links/{id}/checkout_sessions`' answer: the hosted session and the secret that opens it. */
+export const paymentLinkSessionStartSchema = defineComponent('PaymentLinkSessionStart', z
+    .object({
+    object: z.literal('checkout_session_start'),
+    id: z.string().describe('The Checkout Session (`cs_…`).'),
+    client_secret: z.string(),
+    url: z.string().describe('The hosted checkout to send the payer to.'),
+})
+    .strict());
+// ---- Requests --------------------------------------------------------------------
+/** One `line_items[]` entry of a payment link — a catalog price only. */
+export const linkLineItemParams = z
+    .object({
+    price: checkoutIdParam,
+    quantity: quantityParam,
+    adjustable_quantity: adjustableQuantityParam.optional(),
+})
+    .strict()
+    .superRefine((line, ctx) => adjustableIssues(line.quantity, line.adjustable_quantity, ctx));
+const afterCompletionParams = z
+    .object({
+    type: z.enum(['redirect', 'hosted_confirmation']),
+    redirect: z.object({ url: redirectUrlParam }).strict().optional(),
+    hosted_confirmation: z
+        .object({
+        custom_message: z
+            .string()
+            .trim()
+            .min(1)
+            .max(PAYMENT_LINK_LIMITS.customMessageMax)
+            .optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.type === 'redirect' && !value.redirect) {
+        ctx.addIssue({ code: 'custom', path: ['redirect'], message: 'redirect.url is required' });
+    }
+    if (value.type === 'redirect' && value.hosted_confirmation) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['hosted_confirmation'],
+            message: 'hosted_confirmation is for type hosted_confirmation',
+        });
+    }
+    if (value.type === 'hosted_confirmation' && value.redirect) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['redirect'],
+            message: 'redirect is for type redirect',
+        });
+    }
+});
+const restrictionsParams = z
+    .object({
+    completed_sessions: z.object({ limit: z.number().int().min(1).max(1000000) }).strict(),
+})
+    .strict();
+const optionParams = {
+    allow_promotion_codes: z.boolean().optional(),
+    ...collectionParams,
+    automatic_tax: z.object({ enabled: z.boolean() }).strict().optional(),
+    customer_creation: z.enum(CHECKOUT_CUSTOMER_CREATIONS).optional(),
+    after_completion: afterCompletionParams.optional(),
+    submit_type: z.enum(CHECKOUT_SUBMIT_TYPES).optional(),
+    locale: localeParam.optional(),
+};
+/** `POST /v1/payment_links`: 1–20 one-time prices of ONE currency. */
+export const createPaymentLinkParams = z
+    .object({
+    line_items: z.array(linkLineItemParams).min(1).max(PAYMENT_LINK_LIMITS.lineItemsMax),
+    ...optionParams,
+    restrictions: restrictionsParams.optional(),
+    metadata: metadataCreateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+/**
+ * `POST /v1/payment_links/{id}` — everything but the line items, which are
+ * fixed once shared (a payer may hold a session priced from them). `""`
+ * clears; `metadata` is a patch.
+ */
+export const updatePaymentLinkParams = z
+    .object({
+    active: z.boolean().optional(),
+    ...optionParams,
+    shipping_address_collection: z
+        .union([collectionParams.shipping_address_collection.unwrap(), z.literal('')])
+        .optional(),
+    custom_fields: z.union([collectionParams.custom_fields.unwrap(), z.literal('')]).optional(),
+    restrictions: z.union([restrictionsParams, z.literal('')]).optional(),
+    metadata: metadataUpdateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const listPaymentLinksQuery = listQuery({ active: queryBoolean.optional() });
+/** A link's lines: a complete set of at most twenty (`has_more` is `false`). */
+export const listPaymentLinkLineItemsQuery = listQuery({});
+/**
+ * `POST /v1/payment_links/{id}/checkout_sessions` — a payer starting checkout.
+ * A contribution link the payer prices takes `amount`; nothing else is the
+ * payer's to say.
+ */
+export const createPaymentLinkSessionParams = z
+    .object({
+    amount: z
+        .string()
+        .refine((value) => contributionAmountSchema.safeParse(value).success, 'Enter a positive FairCoin base-unit amount within the supported range')
+        .optional()
+        .describe("A free contribution's amount, in FAIR base units."),
+})
+    .strict();
+const linkId = { id: 'The payment link (`link_…`).' };
+export const paymentLinkRoutes = [
+    defineRoute({
+        operationId: 'createPaymentLink',
+        method: 'post',
+        path: '/v1/payment_links',
+        tag: 'Payment Links',
+        summary: 'Create a payment link',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createPaymentLinkParams,
+        response: paymentLinkSchema,
+        status: 201,
+        sdk: 'paymentLinks.create',
+        expandable: 'payment_link',
+    }),
+    defineRoute({
+        operationId: 'listPaymentLinks',
+        method: 'get',
+        path: '/v1/payment_links',
+        tag: 'Payment Links',
+        summary: 'List payment links',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listPaymentLinksQuery,
+        response: listOf(paymentLinkSchema),
+        sdk: 'paymentLinks.list',
+        expandable: 'payment_link',
+    }),
+    defineRoute({
+        operationId: 'retrievePaymentLink',
+        method: 'get',
+        path: '/v1/payment_links/{id}',
+        tag: 'Payment Links',
+        summary: 'Retrieve a payment link',
+        auth: 'service',
+        scope: 'payments:read',
+        params: linkId,
+        query: expandOnlyQuery,
+        response: paymentLinkSchema,
+        sdk: 'paymentLinks.retrieve',
+        expandable: 'payment_link',
+    }),
+    defineRoute({
+        operationId: 'updatePaymentLink',
+        method: 'post',
+        path: '/v1/payment_links/{id}',
+        tag: 'Payment Links',
+        summary: 'Update a payment link',
+        description: 'Everything but the line items. `""` clears a field; `metadata` is a patch.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: linkId,
+        body: updatePaymentLinkParams,
+        response: paymentLinkSchema,
+        sdk: 'paymentLinks.update',
+        expandable: 'payment_link',
+    }),
+    defineRoute({
+        operationId: 'listPaymentLinkLineItems',
+        method: 'get',
+        path: '/v1/payment_links/{id}/line_items',
+        tag: 'Payment Links',
+        summary: "List a payment link's line items",
+        description: 'A complete set of at most twenty lines: `has_more` is always `false`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: linkId,
+        query: listPaymentLinkLineItemsQuery,
+        response: listOf(checkoutLineItemSchema),
+        sdk: 'paymentLinks.listLineItems',
+        expandable: 'item',
+    }),
+    defineRoute({
+        operationId: 'retrievePaymentLinkPublic',
+        method: 'get',
+        path: '/v1/payment_links/{id}/public',
+        tag: 'Payment Links',
+        summary: 'Retrieve a payment link as a visitor',
+        description: 'Anonymous and rate-limited: what a visitor sees before checkout starts. An inactive (or expired contribution) link answers with `active: false`, so the page can say so.',
+        auth: 'public',
+        params: linkId,
+        response: publicPaymentLinkSchema,
+    }),
+    defineRoute({
+        operationId: 'createPaymentLinkCheckoutSession',
+        method: 'post',
+        path: '/v1/payment_links/{id}/checkout_sessions',
+        tag: 'Payment Links',
+        summary: 'Start checkout from a payment link',
+        description: 'Anonymous and rate-limited. Creates a Checkout Session from the STORED link — never a payment. A contribution link requires a UUID `Idempotency-Key` header, written by the page before the request, so a lost answer recovers the same session.',
+        auth: 'public',
+        params: linkId,
+        body: createPaymentLinkSessionParams,
+        response: paymentLinkSessionStartSchema,
+        status: 201,
+    }),
+];

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

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, listQuery, queryBoolean } from '../../common/params.js';
+import { fiatCurrency, livemode, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { PAYMENT_METHOD_CONFIGURATION_TYPES, PAYMENT_METHOD_UNAVAILABLE_REASONS, } from '../../vocabulary/paymentMethodConfigurations.js';
+/**
+ * Payment method breadth on the card rail — which methods a merchant's payers
+ * are offered (`pmc_…`), and the web domains wallets may run on (`pmd_…`).
+ * Both are Orbit's objects; the provider's configuration and domain are
+ * bindings behind them (ADR 0016). Card data and bank credentials are entered
+ * in the provider's hosted fields and never reach Peable (PCI SAQ-A).
+ */
+/** The merchant's choice (`none`: Orbit's default) and what is in effect. */
+export const paymentMethodDisplayPreferenceSchema = z
+    .object({
+    preference: z.enum(['on', 'off', 'none']),
+    value: z.enum(['on', 'off']),
+})
+    .strict();
+export const paymentMethodConfigurationEntrySchema = defineComponent('PaymentMethodConfigurationEntry', z
+    .object({
+    available: z
+        .boolean()
+        .describe('Whether payers can be offered this method: it is on and nothing prevents it.'),
+    display_preference: paymentMethodDisplayPreferenceSchema,
+    unavailable_reason: z
+        .enum(PAYMENT_METHOD_UNAVAILABLE_REASONS)
+        .nullable()
+        .describe('Why it cannot be offered whatever the merchant chooses; `null` when it can.'),
+    currencies: z.array(fiatCurrency).describe('The payment currencies it is offered on.'),
+})
+    .strict());
+const entryFields = Object.fromEntries(PAYMENT_METHOD_CONFIGURATION_TYPES.map((type) => [type, paymentMethodConfigurationEntrySchema]));
+export const paymentMethodConfigurationSchema = defineObject('payment_method_configuration', 'PaymentMethodConfiguration', z
+    .object({
+    id: z.string(),
+    object: z.literal('payment_method_configuration'),
+    livemode,
+    name: z.string(),
+    active: z
+        .boolean()
+        .describe('An inactive configuration cannot be named on a new PaymentIntent. The default is always active.'),
+    is_default: z
+        .boolean()
+        .describe('The configuration a PaymentIntent uses when it names none. One per merchant.'),
+    created: unixSeconds,
+    updated_at: unixSeconds,
+    ...entryFields,
+})
+    .strict());
+/** A wallet's standing on one domain. */
+export const paymentMethodDomainWalletStatusSchema = defineComponent('PaymentMethodDomainWalletStatus', z
+    .object({
+    status: z
+        .enum(['active', 'inactive'])
+        .describe('`active`: the wallet can run on pages served from this domain.'),
+    status_details: z
+        .object({ error_message: z.string() })
+        .strict()
+        .nullable()
+        .describe("Present while `inactive`: what the wallet's verification said."),
+})
+    .strict());
+/**
+ * A web domain the merchant serves payment pages from (`pmd_…`), registered so
+ * Apple Pay and Google Pay run there. Peable's own hosted checkout needs none.
+ */
+export const paymentMethodDomainSchema = defineObject('payment_method_domain', 'PaymentMethodDomain', z
+    .object({
+    id: z.string(),
+    object: z.literal('payment_method_domain'),
+    livemode,
+    domain_name: z.string().describe('Lowercase hostname, no scheme, port or path.'),
+    enabled: z.boolean().describe('Whether wallets may run on it at all.'),
+    apple_pay: paymentMethodDomainWalletStatusSchema,
+    google_pay: paymentMethodDomainWalletStatusSchema,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'pmd_0193b8f2c1a87d3e9f4a',
+            object: 'payment_method_domain',
+            livemode: false,
+            domain_name: 'shop.example.com',
+            enabled: true,
+            apple_pay: { status: 'active', status_details: null },
+            google_pay: { status: 'active', status_details: null },
+            created: 1793750400,
+        },
+    ],
+});
+/** One method's setting in a create or update. `none` returns it to Orbit's default. */
+export const paymentMethodConfigurationEntryParams = z
+    .object({
+    display_preference: z.object({ preference: z.enum(['on', 'off', 'none']) }).strict(),
+})
+    .strict();
+const methodParams = Object.fromEntries(PAYMENT_METHOD_CONFIGURATION_TYPES.map((type) => [
+    type,
+    paymentMethodConfigurationEntryParams.optional(),
+]));
+/** `POST /v1/payment_method_configurations` — an additional, non-default configuration. */
+export const createPaymentMethodConfigurationParams = z
+    .object({ name: z.string().min(1).max(100).optional(), ...methodParams })
+    .strict();
+/** `POST /v1/payment_method_configurations/{id}` — methods (merged), name, active. */
+export const updatePaymentMethodConfigurationParams = z
+    .object({
+    name: z.string().min(1).max(100).optional(),
+    active: z.boolean().optional(),
+    ...methodParams,
+})
+    .strict();
+export const listPaymentMethodConfigurationsQuery = listQuery({});
+export const createPaymentMethodDomainParams = z
+    .object({ domain_name: z.string().min(1).max(300), enabled: z.boolean().optional() })
+    .strict();
+export const updatePaymentMethodDomainParams = z
+    .object({ enabled: z.boolean().optional() })
+    .strict();
+/** The validate body: nothing. */
+export const validatePaymentMethodDomainParams = z.object({}).strict();
+export const listPaymentMethodDomainsQuery = listQuery({
+    domain_name: z.string().min(1).max(253).optional().describe('Exact match, any case.'),
+    enabled: queryBoolean.optional(),
+});
+const pmcId = { id: 'The configuration (`pmc_…`).' };
+const pmdId = { id: 'The domain (`pmd_…`).' };
+export const paymentMethodConfigurationRoutes = [
+    defineRoute({
+        operationId: 'listPaymentMethodConfigurations',
+        method: 'get',
+        path: '/v1/payment_method_configurations',
+        tag: 'Payment method configurations',
+        summary: 'List payment method configurations',
+        description: 'The default configuration is created on first read.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listPaymentMethodConfigurationsQuery,
+        response: listOf(paymentMethodConfigurationSchema),
+        sdk: 'paymentMethodConfigurations.list',
+        expandable: 'payment_method_configuration',
+    }),
+    defineRoute({
+        operationId: 'createPaymentMethodConfiguration',
+        method: 'post',
+        path: '/v1/payment_method_configurations',
+        tag: 'Payment method configurations',
+        summary: 'Create a payment method configuration',
+        description: 'An additional, non-default configuration. Turning `on` a method the processing provider does not offer is refused.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createPaymentMethodConfigurationParams,
+        response: paymentMethodConfigurationSchema,
+        sdk: 'paymentMethodConfigurations.create',
+    }),
+    defineRoute({
+        operationId: 'retrievePaymentMethodConfiguration',
+        method: 'get',
+        path: '/v1/payment_method_configurations/{id}',
+        tag: 'Payment method configurations',
+        summary: 'Retrieve a payment method configuration',
+        auth: 'service',
+        scope: 'payments:read',
+        params: pmcId,
+        query: expandOnlyQuery,
+        response: paymentMethodConfigurationSchema,
+        sdk: 'paymentMethodConfigurations.retrieve',
+        expandable: 'payment_method_configuration',
+    }),
+    defineRoute({
+        operationId: 'updatePaymentMethodConfiguration',
+        method: 'post',
+        path: '/v1/payment_method_configurations/{id}',
+        tag: 'Payment method configurations',
+        summary: 'Update a payment method configuration',
+        description: 'Method settings are merged; the default configuration is always active.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: pmcId,
+        body: updatePaymentMethodConfigurationParams,
+        response: paymentMethodConfigurationSchema,
+        sdk: 'paymentMethodConfigurations.update',
+    }),
+    defineRoute({
+        operationId: 'listPaymentMethodDomains',
+        method: 'get',
+        path: '/v1/payment_method_domains',
+        tag: 'Payment method domains',
+        summary: 'List payment method domains',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listPaymentMethodDomainsQuery,
+        response: listOf(paymentMethodDomainSchema),
+        sdk: 'paymentMethodDomains.list',
+        expandable: 'payment_method_domain',
+    }),
+    defineRoute({
+        operationId: 'createPaymentMethodDomain',
+        method: 'post',
+        path: '/v1/payment_method_domains',
+        tag: 'Payment method domains',
+        summary: 'Register a payment method domain',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createPaymentMethodDomainParams,
+        response: paymentMethodDomainSchema,
+        sdk: 'paymentMethodDomains.create',
+    }),
+    defineRoute({
+        operationId: 'retrievePaymentMethodDomain',
+        method: 'get',
+        path: '/v1/payment_method_domains/{id}',
+        tag: 'Payment method domains',
+        summary: 'Retrieve a payment method domain',
+        auth: 'service',
+        scope: 'payments:read',
+        params: pmdId,
+        query: expandOnlyQuery,
+        response: paymentMethodDomainSchema,
+        sdk: 'paymentMethodDomains.retrieve',
+        expandable: 'payment_method_domain',
+    }),
+    defineRoute({
+        operationId: 'updatePaymentMethodDomain',
+        method: 'post',
+        path: '/v1/payment_method_domains/{id}',
+        tag: 'Payment method domains',
+        summary: 'Update a payment method domain',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: pmdId,
+        body: updatePaymentMethodDomainParams,
+        response: paymentMethodDomainSchema,
+        sdk: 'paymentMethodDomains.update',
+    }),
+    defineRoute({
+        operationId: 'validatePaymentMethodDomain',
+        method: 'post',
+        path: '/v1/payment_method_domains/{id}/validate',
+        tag: 'Payment method domains',
+        summary: 'Validate a payment method domain',
+        description: "Re-runs the wallets' verification of the domain.",
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: pmdId,
+        body: validatePaymentMethodDomainParams,
+        response: paymentMethodDomainSchema,
+        sdk: 'paymentMethodDomains.validate',
+    }),
+];