@peable.to/contracts 0.3.0 → 1.0.0

package/dist/esm/resources/billingEngine/public.js

@@ -0,0 +1,323 @@
+import { z } from 'zod';
+import { addressParams, addressSchema, emailParam } from '../../common/address.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { idParam } from '../../common/params.js';
+import { amount, currency, livemode, signedAmount, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { PORTAL_PAYMENT_METHOD_UPDATE_STATUSES } from '../../vocabulary/billingPortal.js';
+import { INVOICE_STATUSES, PUBLIC_INVOICE_PAYMENT_METHOD_TYPES } from '../../vocabulary/invoices.js';
+import { COLLECTION_METHODS, SUBSCRIPTION_STATUSES } from '../../vocabulary/subscriptions.js';
+import { billingPortalBusinessProfileSchema, billingPortalFeaturesSchema } from './billingPortal.js';
+import { emptyBody, quantityParam, shortText } from './params.js';
+/**
+ * The payer-facing billing routes (ADR 0018) — anonymous, authorized by an
+ * unguessable bearer token in the path, like a payment link: a finalized
+ * invoice as its payer sees it, and the customer portal. Nothing here reveals
+ * anything but the one invoice or the one customer the token names. Called by
+ * the hosted checkout (`checkout.peable.to`), never by the server SDK.
+ */
+/** The merchant as a payer sees it. */
+const publicMerchantSchema = z
+    .object({ name: z.string().nullable(), avatar_url: z.string().nullable() })
+    .strict();
+/** A finalized invoice as its payer sees it. */
+export const publicInvoiceSchema = defineObject('public_invoice', 'PublicInvoice', z
+    .object({
+    object: z.literal('public_invoice'),
+    livemode,
+    number: z.string().nullable(),
+    status: z.enum(INVOICE_STATUSES),
+    currency,
+    merchant: publicMerchantSchema,
+    customer_name: z.string().nullable(),
+    customer_email: z.string().nullable(),
+    description: z.string().nullable(),
+    lines: z.array(z
+        .object({
+        description: z.string().nullable(),
+        quantity: z.number().int().nullable(),
+        amount: signedAmount,
+        period: z.object({ start: unixSeconds, end: unixSeconds }).strict(),
+        proration: z.boolean(),
+    })
+        .strict()),
+    subtotal: signedAmount,
+    total_discount: signedAmount,
+    tax: signedAmount.nullable(),
+    total: signedAmount,
+    amount_due: amount,
+    amount_paid: amount,
+    amount_remaining: amount,
+    due_date: unixSeconds.nullable(),
+    created: unixSeconds,
+    finalized_at: unixSeconds.nullable(),
+    paid_at: unixSeconds.nullable(),
+    payment_method_types: z
+        .array(z.enum(PUBLIC_INVOICE_PAYMENT_METHOD_TYPES))
+        .describe("Which rail pays it: a card through the provider's fields, FairCoin from the payer's wallet."),
+    invoice_pdf: z.string(),
+})
+    .strict());
+/**
+ * The PaymentIntent the payer completes on the hosted checkout
+ * (`/i/:id#client_secret=…`). The same invoice always answers the same intent
+ * while it can still be paid.
+ */
+export const publicInvoicePaymentSchema = defineObject('public_invoice_payment', 'PublicInvoicePayment', z
+    .object({
+    object: z.literal('public_invoice_payment'),
+    payment_intent: z.string().describe('The PaymentIntent (`pi_…`) that pays the invoice.'),
+    client_secret: z
+        .string()
+        .describe("The intent's payer credential (`pi_…_secret_…`), as a payment link hands out."),
+})
+    .strict());
+/** One subscription as the hosted portal shows it. */
+export const publicPortalSubscriptionSchema = defineComponent('PublicPortalSubscription', z
+    .object({
+    id: z.string(),
+    status: z.enum(SUBSCRIPTION_STATUSES),
+    currency,
+    current_period_end: unixSeconds,
+    cancel_at_period_end: z.boolean(),
+    cancel_at: unixSeconds.nullable(),
+    trial_end: unixSeconds.nullable(),
+    collection_method: z.enum(COLLECTION_METHODS),
+    items: z.array(z
+        .object({
+        id: z.string(),
+        price: z.string(),
+        product: z.string(),
+        product_name: z.string(),
+        quantity: z.number().int().nonnegative(),
+        unit_amount: amount.nullable(),
+        interval: z.string().nullable(),
+    })
+        .strict()),
+})
+    .strict());
+/** The hosted portal's view of its customer. */
+export const publicPortalSessionSchema = defineObject('billing_portal.public_session', 'PublicPortalSession', z
+    .object({
+    object: z.literal('billing_portal.public_session'),
+    livemode,
+    merchant: publicMerchantSchema,
+    business_profile: billingPortalBusinessProfileSchema,
+    features: billingPortalFeaturesSchema,
+    return_url: z.string().nullable(),
+    expires_at: unixSeconds,
+    customer: z
+        .object({
+        id: z.string(),
+        email: z.string().nullable(),
+        name: z.string().nullable(),
+        phone: z.string().nullable(),
+        address: addressSchema.nullable(),
+        default_payment_method: z
+            .object({
+            id: z.string(),
+            card: z
+                .object({
+                brand: z.string(),
+                last4: z.string(),
+                exp_month: z.number().int(),
+                exp_year: z.number().int(),
+            })
+                .strict()
+                .nullable(),
+        })
+            .strict()
+            .nullable(),
+    })
+        .strict(),
+    subscriptions: z.array(publicPortalSubscriptionSchema),
+    invoices: z.array(z
+        .object({
+        id: z.string(),
+        number: z.string().nullable(),
+        status: z.enum(INVOICE_STATUSES),
+        currency,
+        total: signedAmount,
+        amount_due: amount,
+        created: unixSeconds,
+        hosted_invoice_url: z.string().nullable(),
+        invoice_pdf: z.string().nullable(),
+    })
+        .strict()),
+    plans: z
+        .array(z
+        .object({
+        product: z.string(),
+        product_name: z.string(),
+        prices: z.array(z
+            .object({
+            id: z.string(),
+            unit_amount: amount.nullable(),
+            currency,
+            interval: z.string().nullable(),
+            interval_count: z.number().int().nullable(),
+        })
+            .strict()),
+    })
+        .strict())
+        .describe('The plans `subscription_update` allows, priced.'),
+})
+    .strict());
+/** A card update begun: the SetupIntent the portal page confirms with the provider's own fields. */
+export const portalPaymentMethodUpdateSchema = defineComponent('PortalPaymentMethodUpdate', z
+    .object({
+    setup_intent: z.string().describe('The SetupIntent (`seti_…`) to confirm.'),
+    client_secret: z.string().describe('Its payer credential.'),
+})
+    .strict());
+/** A card update finished: `pending` until the SetupIntent succeeded. */
+export const portalPaymentMethodUpdateResultSchema = defineComponent('PortalPaymentMethodUpdateResult', z
+    .object({
+    status: z.enum(PORTAL_PAYMENT_METHOD_UPDATE_STATUSES),
+    session: publicPortalSessionSchema,
+})
+    .strict());
+// ---- Requests ------------------------------------------------------------------------
+export const payPublicInvoiceParams = emptyBody;
+/** A portal action on one of the customer's subscriptions. */
+export const portalSubscriptionParams = z.object({ subscription: idParam }).strict();
+/** Switch a (single-item) subscription to one of the configuration's plans, or change its quantity. */
+export const portalChangePlanParams = z
+    .object({
+    subscription: idParam,
+    price: idParam.optional(),
+    quantity: quantityParam.optional(),
+})
+    .strict();
+/** The fields the configuration's `customer_update.allowed_updates` names. */
+export const portalCustomerParams = z
+    .object({
+    email: emailParam.optional(),
+    name: shortText(500).optional(),
+    phone: shortText(40).optional(),
+    address: addressParams.optional(),
+})
+    .strict();
+export const startPortalPaymentMethodUpdateParams = emptyBody;
+export const completePortalPaymentMethodUpdateParams = z.object({ setup_intent: idParam }).strict();
+// ---- Routes --------------------------------------------------------------------------
+const invoiceToken = { token: 'The hosted invoice token (from `hosted_invoice_url`).' };
+const portalToken = { token: 'The portal session token (from the session `url`).' };
+export const publicBillingRoutes = [
+    defineRoute({
+        operationId: 'retrievePublicInvoice',
+        method: 'get',
+        path: '/v1/invoices/public/{token}',
+        tag: 'Hosted invoices',
+        summary: 'Retrieve a hosted invoice',
+        description: 'A finalized invoice as its payer sees it.',
+        auth: 'public',
+        params: invoiceToken,
+        response: publicInvoiceSchema,
+    }),
+    defineRoute({
+        operationId: 'payPublicInvoice',
+        method: 'post',
+        path: '/v1/invoices/public/{token}/pay',
+        tag: 'Hosted invoices',
+        summary: 'Pay a hosted invoice',
+        description: 'The PaymentIntent the payer completes — a card through the provider’s own fields, FairCoin from the payer’s wallet. The same invoice answers the same intent while it can still be paid.',
+        auth: 'public',
+        params: invoiceToken,
+        body: payPublicInvoiceParams,
+        response: publicInvoicePaymentSchema,
+    }),
+    defineRoute({
+        operationId: 'retrievePublicInvoicePdf',
+        method: 'get',
+        path: '/v1/invoices/public/{token}/pdf',
+        tag: 'Hosted invoices',
+        summary: "Download a hosted invoice's PDF",
+        auth: 'public',
+        params: invoiceToken,
+        response: { kind: 'binary', contentType: 'application/pdf' },
+    }),
+    defineRoute({
+        operationId: 'retrievePublicPortalSession',
+        method: 'get',
+        path: '/v1/billing_portal/public/{token}',
+        tag: 'Hosted portal',
+        summary: 'Retrieve the hosted portal',
+        description: 'The customer, their subscriptions, invoices and the plans they may switch to.',
+        auth: 'public',
+        params: portalToken,
+        response: publicPortalSessionSchema,
+    }),
+    defineRoute({
+        operationId: 'cancelPortalSubscription',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/cancel',
+        tag: 'Hosted portal',
+        summary: 'Cancel a subscription from the portal',
+        description: 'At period end or now, as the configuration says. Answers the portal as it now is.',
+        auth: 'public',
+        params: portalToken,
+        body: portalSubscriptionParams,
+        response: publicPortalSessionSchema,
+    }),
+    defineRoute({
+        operationId: 'renewPortalSubscription',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/renew',
+        tag: 'Hosted portal',
+        summary: 'Undo a cancellation at period end',
+        description: 'Answers the portal as it now is.',
+        auth: 'public',
+        params: portalToken,
+        body: portalSubscriptionParams,
+        response: publicPortalSessionSchema,
+    }),
+    defineRoute({
+        operationId: 'changePortalSubscriptionPlan',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/change_plan',
+        tag: 'Hosted portal',
+        summary: 'Change plan from the portal',
+        description: 'Answers the portal as it now is.',
+        auth: 'public',
+        params: portalToken,
+        body: portalChangePlanParams,
+        response: publicPortalSessionSchema,
+    }),
+    defineRoute({
+        operationId: 'updatePortalCustomer',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/customer',
+        tag: 'Hosted portal',
+        summary: 'Update billing details from the portal',
+        description: 'Answers the portal as it now is.',
+        auth: 'public',
+        params: portalToken,
+        body: portalCustomerParams,
+        response: publicPortalSessionSchema,
+    }),
+    defineRoute({
+        operationId: 'startPortalPaymentMethodUpdate',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/payment_method_update',
+        tag: 'Hosted portal',
+        summary: 'Begin a card update from the portal',
+        description: 'A SetupIntent for the customer; card customers only.',
+        auth: 'public',
+        params: portalToken,
+        body: startPortalPaymentMethodUpdateParams,
+        response: portalPaymentMethodUpdateSchema,
+    }),
+    defineRoute({
+        operationId: 'completePortalPaymentMethodUpdate',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/payment_method_update/complete',
+        tag: 'Hosted portal',
+        summary: 'Finish a card update from the portal',
+        description: "Once the SetupIntent succeeded, its method becomes the customer's default and every live subscription's.",
+        auth: 'public',
+        params: portalToken,
+        body: completePortalPaymentMethodUpdateParams,
+        response: portalPaymentMethodUpdateResultSchema,
+    }),
+];