@peable.to/contracts 0.3.0 → 1.0.0

package/dist/cjs/resources/checkout/shared.js

@@ -0,0 +1,368 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.quantityParam = exports.adjustableQuantityParam = exports.collectionParams = exports.customFieldsParam = exports.checkoutEmailParam = exports.localeParam = exports.redirectUrlParam = exports.amountParam = exports.countryCodeParam = exports.checkoutIdParam = exports.checkoutBrandingSchema = exports.merchantDisplaySchema = exports.collectionResponseFields = exports.checkoutConsentSchema = exports.checkoutConsentCollectionSchema = exports.checkoutAutomaticTaxSchema = exports.checkoutTotalDetailsSchema = exports.checkoutDiscountSchema = exports.checkoutCustomFieldSchema = exports.checkoutCustomFieldDropdownOptionSchema = exports.checkoutCustomFieldLabelSchema = exports.checkoutShippingDetailsSchema = exports.checkoutCustomerDetailsSchema = exports.checkoutTaxIdSchema = exports.checkoutLineItemSchema = exports.checkoutAdjustableQuantitySchema = exports.railSchema = void 0;
+exports.adjustableBoundsOf = adjustableBoundsOf;
+exports.adjustableIssues = adjustableIssues;
+const zod_1 = require("zod");
+const payments_1 = require("../../vocabulary/payments");
+const address_1 = require("../../common/address");
+const objects_1 = require("../../common/objects");
+const primitives_1 = require("../../common/primitives");
+const checkout_1 = require("../../vocabulary/checkout");
+const merchants_1 = require("../../vocabulary/merchants");
+const money_1 = require("../../vocabulary/money");
+/**
+ * What Checkout Sessions and Payment Links share: the `item` a line renders
+ * as, the collection options (address, phone, tax id, terms, custom fields),
+ * the payer-facing merchant and branding, and the request halves of those.
+ * One shape rule is written once, so a link and a session refuse the same
+ * mistake with the same `param`.
+ */
+// ---------------------------------------------------------------------------
+// Response side
+// ---------------------------------------------------------------------------
+/** The payment rail: FairCoin on chain, or a card (and the methods riding on it). */
+exports.railSchema = zod_1.z.enum(payments_1.PAYMENT_INTENT_RAILS);
+exports.checkoutAdjustableQuantitySchema = (0, objects_1.defineComponent)('CheckoutAdjustableQuantity', zod_1.z
+    .object({
+    enabled: zod_1.z.boolean(),
+    minimum: zod_1.z.number().int().nullable().describe('Default 0 when enabled.'),
+    maximum: zod_1.z.number().int().nullable().describe('Default 99 when enabled.'),
+})
+    .strict());
+/** One line of a session or link — Stripe's `item`. */
+exports.checkoutLineItemSchema = (0, objects_1.defineObject)('item', 'CheckoutLineItem', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('item'),
+    description: zod_1.z.string().describe("The product's name, or the inline `product_data.name`."),
+    price: (0, objects_1.expandable)('price', 'The catalog price (`price_…`, or the Price with `expand[]=data.price`); `null` for an inline `price_data` line, which is a snapshot on the line and never a stored price.').nullable(),
+    product: (0, objects_1.expandable)('product', 'The catalog product (`prod_…`, expandable); `null` for `product_data`.').nullable(),
+    images: zod_1.z
+        .array(zod_1.z.string())
+        .describe("Images to show beside the line (the product's, or `product_data.images`)."),
+    quantity: zod_1.z.number().int(),
+    adjustable_quantity: exports.checkoutAdjustableQuantitySchema.nullable(),
+    currency: primitives_1.currency,
+    unit_amount: primitives_1.amount
+        .nullable()
+        .describe('The per-unit amount for a per-unit price; `null` for a tiered one.'),
+    amount_subtotal: primitives_1.amount.describe('Before discount and tax.'),
+    amount_discount: primitives_1.amount,
+    amount_tax: primitives_1.amount,
+    amount_total: primitives_1.amount.describe('`amount_subtotal - amount_discount + amount_tax` (exclusive tax only).'),
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'li_0193b8f2c1a87d3e9f4a',
+            object: 'item',
+            description: 'Pro plan',
+            price: 'price_0193b8f2c1a87d3e9f4b',
+            product: 'prod_0193b8f2c1a87d3e9f4c',
+            images: [],
+            quantity: 1,
+            adjustable_quantity: null,
+            currency: 'EUR',
+            unit_amount: '1999',
+            amount_subtotal: '1999',
+            amount_discount: '0',
+            amount_tax: '0',
+            amount_total: '1999',
+        },
+    ],
+});
+exports.checkoutTaxIdSchema = (0, objects_1.defineComponent)('CheckoutTaxId', zod_1.z.object({ type: zod_1.z.enum(checkout_1.CHECKOUT_TAX_ID_TYPES), value: zod_1.z.string() }).strict());
+/** What the payer told checkout about themselves — Stripe's `customer_details`. */
+exports.checkoutCustomerDetailsSchema = (0, objects_1.defineComponent)('CheckoutCustomerDetails', zod_1.z
+    .object({
+    email: zod_1.z.string().nullable(),
+    name: zod_1.z.string().nullable(),
+    phone: zod_1.z.string().nullable(),
+    address: address_1.addressSchema.nullable(),
+    tax_ids: zod_1.z.array(exports.checkoutTaxIdSchema),
+})
+    .strict());
+exports.checkoutShippingDetailsSchema = (0, objects_1.defineComponent)('CheckoutShippingDetails', zod_1.z.object({ name: zod_1.z.string(), address: address_1.addressSchema }).strict());
+exports.checkoutCustomFieldLabelSchema = zod_1.z
+    .object({ type: zod_1.z.literal('custom'), custom: zod_1.z.string() })
+    .strict();
+exports.checkoutCustomFieldDropdownOptionSchema = zod_1.z
+    .object({ label: zod_1.z.string(), value: zod_1.z.string() })
+    .strict();
+const customFieldBounds = zod_1.z
+    .object({
+    minimum_length: zod_1.z.number().int().nullable(),
+    maximum_length: zod_1.z.number().int().nullable(),
+    value: zod_1.z.string().nullable().describe('What the payer entered.'),
+})
+    .strict();
+/** A merchant-defined field the payer fills in; `value`s are what they entered. */
+exports.checkoutCustomFieldSchema = (0, objects_1.defineComponent)('CheckoutCustomField', zod_1.z
+    .object({
+    key: zod_1.z.string(),
+    label: exports.checkoutCustomFieldLabelSchema,
+    type: zod_1.z.enum(checkout_1.CHECKOUT_CUSTOM_FIELD_TYPES),
+    optional: zod_1.z.boolean(),
+    dropdown: zod_1.z
+        .object({
+        options: zod_1.z.array(exports.checkoutCustomFieldDropdownOptionSchema),
+        value: zod_1.z.string().nullable(),
+    })
+        .strict()
+        .nullable(),
+    text: customFieldBounds.nullable(),
+    numeric: customFieldBounds.nullable(),
+})
+    .strict());
+exports.checkoutDiscountSchema = (0, objects_1.defineComponent)('CheckoutDiscount', zod_1.z
+    .object({
+    coupon: zod_1.z.string().describe('The coupon applied (merchant-chosen id or `coupon_…`).'),
+    promotion_code: zod_1.z
+        .string()
+        .nullable()
+        .describe('The promotion code it was redeemed through (`promo_…`), or `null`.'),
+})
+    .strict());
+exports.checkoutTotalDetailsSchema = (0, objects_1.defineComponent)('CheckoutTotalDetails', zod_1.z.object({ amount_discount: primitives_1.amount, amount_tax: primitives_1.amount, amount_shipping: primitives_1.amount }).strict());
+/**
+ * `automatic_tax` — Peable Tax (ADR 0011). `requires_location_inputs` until
+ * the payer gave an address Peable Tax can locate them with; `failed` when the
+ * sale is covered and could not be priced (checkout refuses to proceed: tax
+ * fails CLOSED, never zero).
+ */
+exports.checkoutAutomaticTaxSchema = (0, objects_1.defineComponent)('CheckoutAutomaticTax', zod_1.z
+    .object({
+    enabled: zod_1.z.boolean(),
+    status: zod_1.z.enum(['complete', 'requires_location_inputs', 'failed']).nullable(),
+})
+    .strict());
+exports.checkoutConsentCollectionSchema = zod_1.z
+    .object({ terms_of_service: zod_1.z.enum(['none', 'required']) })
+    .strict();
+exports.checkoutConsentSchema = zod_1.z
+    .object({ terms_of_service: zod_1.z.literal('accepted').nullable() })
+    .strict();
+/** The collection options, as a session or link reports them. */
+exports.collectionResponseFields = {
+    billing_address_collection: zod_1.z.enum(checkout_1.CHECKOUT_BILLING_ADDRESS_COLLECTIONS),
+    shipping_address_collection: zod_1.z
+        .object({ allowed_countries: zod_1.z.array(zod_1.z.string()) })
+        .strict()
+        .nullable(),
+    phone_number_collection: zod_1.z.object({ enabled: zod_1.z.boolean() }).strict(),
+    tax_id_collection: zod_1.z.object({ enabled: zod_1.z.boolean() }).strict(),
+    custom_fields: zod_1.z.array(exports.checkoutCustomFieldSchema),
+    consent_collection: exports.checkoutConsentCollectionSchema.nullable(),
+};
+/** The public, secret-free merchant identity a payer surface renders. */
+exports.merchantDisplaySchema = (0, objects_1.defineComponent)('MerchantDisplay', zod_1.z
+    .object({
+    name: zod_1.z.string().describe("The merchant's display name, or a neutral fallback when unset."),
+    avatar_url: zod_1.z
+        .string()
+        .nullable()
+        .describe('Resolved server-side; `null` when the merchant has no avatar.'),
+    logo_url: zod_1.z
+        .string()
+        .nullable()
+        .describe("The merchant's `business_logo`, resolved; `null` when unset or not served."),
+    description: zod_1.z.string().nullable(),
+})
+    .strict());
+/**
+ * Branding as a payer surface renders it: every field resolved (defaults
+ * filled in), the logo and icon as URLs the gateway built through Oxy's media
+ * chokepoint — a withheld file is `null`, never a broken image.
+ */
+exports.checkoutBrandingSchema = (0, objects_1.defineComponent)('CheckoutBranding', zod_1.z
+    .object({
+    icon_url: zod_1.z.string().nullable(),
+    logo_url: zod_1.z.string().nullable(),
+    primary_color: zod_1.z.string(),
+    accent_color: zod_1.z.string(),
+    font: zod_1.z.enum(merchants_1.BRANDING_FONTS),
+    border_style: zod_1.z.enum(merchants_1.BRANDING_BORDER_STYLES),
+})
+    .strict());
+// ---------------------------------------------------------------------------
+// Request side
+// ---------------------------------------------------------------------------
+exports.checkoutIdParam = zod_1.z.string().min(1).max(255);
+exports.countryCodeParam = zod_1.z
+    .string()
+    .regex(/^[A-Z]{2}$/, 'must be an ISO 3166-1 alpha-2 country code');
+/** A base-unit amount in a request. */
+exports.amountParam = zod_1.z
+    .string()
+    .regex(money_1.BASE_UNIT_PATTERN, 'must be a non-negative integer string in the smallest currency unit');
+/**
+ * A redirect target. `https` only, except `http://localhost` for development —
+ * a payer is sent there after paying, so an `http` URL elsewhere would leak the
+ * session id in the clear. `{CHECKOUT_SESSION_ID}` may appear anywhere.
+ */
+exports.redirectUrlParam = zod_1.z
+    .string()
+    .max(2048)
+    .refine((value) => {
+    const probe = value.split(checkout_1.CHECKOUT_SESSION_ID_TEMPLATE).join('cs_template');
+    try {
+        const url = new URL(probe);
+        return (url.protocol === 'https:' ||
+            (url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1')));
+    }
+    catch {
+        return false;
+    }
+}, 'must be an https URL (http only on localhost)')
+    .describe('`https` (or `http://localhost`); may carry `{CHECKOUT_SESSION_ID}`.');
+/** `auto` follows the payer's browser: parsed as `null`. */
+exports.localeParam = zod_1.z
+    .enum([...checkout_1.CHECKOUT_LOCALES, 'auto'])
+    .transform((value) => (value === 'auto' ? null : value))
+    .describe("`auto` follows the payer's browser.");
+exports.checkoutEmailParam = zod_1.z.string().trim().max(254).email('must be an email address');
+const customFieldParam = zod_1.z
+    .object({
+    key: zod_1.z
+        .string()
+        .regex(new RegExp(`^[A-Za-z0-9_]{1,${checkout_1.CHECKOUT_LIMITS.customFieldKeyMax}}$`), 'a key is letters, digits and underscores'),
+    label: zod_1.z
+        .object({
+        type: zod_1.z.literal('custom'),
+        custom: zod_1.z.string().trim().min(1).max(checkout_1.CHECKOUT_LIMITS.customFieldLabelMax),
+    })
+        .strict(),
+    type: zod_1.z.enum(checkout_1.CHECKOUT_CUSTOM_FIELD_TYPES),
+    optional: zod_1.z.boolean().optional(),
+    dropdown: zod_1.z
+        .object({
+        options: zod_1.z
+            .array(zod_1.z
+            .object({
+            label: zod_1.z.string().trim().min(1).max(checkout_1.CHECKOUT_LIMITS.dropdownOptionLabelMax),
+            value: zod_1.z
+                .string()
+                .regex(new RegExp(`^[A-Za-z0-9]{1,${checkout_1.CHECKOUT_LIMITS.dropdownOptionValueMax}}$`), 'an option value is letters and digits'),
+        })
+            .strict())
+            .min(1)
+            .max(checkout_1.CHECKOUT_LIMITS.dropdownOptionsMax),
+    })
+        .strict()
+        .optional(),
+    text: zod_1.z
+        .object({
+        minimum_length: zod_1.z.number().int().min(1).max(checkout_1.CHECKOUT_LIMITS.customFieldTextMax).optional(),
+        maximum_length: zod_1.z.number().int().min(1).max(checkout_1.CHECKOUT_LIMITS.customFieldTextMax).optional(),
+    })
+        .strict()
+        .optional(),
+    numeric: zod_1.z
+        .object({
+        minimum_length: zod_1.z.number().int().min(1).max(checkout_1.CHECKOUT_LIMITS.customFieldTextMax).optional(),
+        maximum_length: zod_1.z.number().int().min(1).max(checkout_1.CHECKOUT_LIMITS.customFieldTextMax).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((field, ctx) => {
+    const issue = (path, message) => ctx.addIssue({ code: 'custom', path, message });
+    if (field.type === 'dropdown' && !field.dropdown) {
+        issue(['dropdown'], 'a dropdown field needs dropdown.options');
+    }
+    if (field.type !== 'dropdown' && field.dropdown) {
+        issue(['dropdown'], 'dropdown is only for a dropdown field');
+    }
+    if (field.type !== 'text' && field.text)
+        issue(['text'], 'text is only for a text field');
+    if (field.type !== 'numeric' && field.numeric) {
+        issue(['numeric'], 'numeric is only for a numeric field');
+    }
+    const bounds = field.text ?? field.numeric;
+    if (bounds?.minimum_length !== undefined &&
+        bounds.maximum_length !== undefined &&
+        bounds.minimum_length > bounds.maximum_length) {
+        issue([field.type, 'minimum_length'], 'minimum_length cannot exceed maximum_length');
+    }
+    if (field.dropdown) {
+        const values = field.dropdown.options.map((option) => option.value);
+        if (new Set(values).size !== values.length) {
+            issue(['dropdown', 'options'], 'option values must be unique');
+        }
+    }
+});
+/** At most three, keys unique. */
+exports.customFieldsParam = zod_1.z
+    .array(customFieldParam)
+    .max(checkout_1.CHECKOUT_LIMITS.customFieldsMax)
+    .superRefine((fields, ctx) => {
+    const keys = fields.map((field) => field.key);
+    if (new Set(keys).size !== keys.length) {
+        ctx.addIssue({ code: 'custom', message: 'custom field keys must be unique' });
+    }
+});
+/** The collection options, as a request names them — shared by sessions and links. */
+exports.collectionParams = {
+    billing_address_collection: zod_1.z.enum(checkout_1.CHECKOUT_BILLING_ADDRESS_COLLECTIONS).optional(),
+    shipping_address_collection: zod_1.z
+        .object({
+        allowed_countries: zod_1.z.array(exports.countryCodeParam).min(1).max(checkout_1.CHECKOUT_LIMITS.shippingCountriesMax),
+    })
+        .strict()
+        .optional(),
+    phone_number_collection: zod_1.z.object({ enabled: zod_1.z.boolean() }).strict().optional(),
+    tax_id_collection: zod_1.z.object({ enabled: zod_1.z.boolean() }).strict().optional(),
+    consent_collection: zod_1.z
+        .object({ terms_of_service: zod_1.z.enum(['none', 'required']).optional() })
+        .strict()
+        .optional(),
+    custom_fields: exports.customFieldsParam.optional(),
+};
+exports.adjustableQuantityParam = zod_1.z
+    .object({
+    enabled: zod_1.z.boolean(),
+    minimum: zod_1.z.number().int().min(0).max(checkout_1.CHECKOUT_LIMITS.quantityMax).optional(),
+    maximum: zod_1.z.number().int().min(1).max(checkout_1.CHECKOUT_LIMITS.quantityMax).optional(),
+})
+    .strict();
+exports.quantityParam = zod_1.z.number().int().min(1).max(checkout_1.CHECKOUT_LIMITS.quantityMax);
+/** Stripe's defaults: 0–99 when enabled. */
+function adjustableBoundsOf(adjustable) {
+    if (!adjustable?.enabled)
+        return null;
+    return { minimum: adjustable.minimum ?? 0, maximum: adjustable.maximum ?? 99 };
+}
+/** The refusals of a line's `quantity` against its `adjustable_quantity`. */
+function adjustableIssues(quantity, adjustable, ctx) {
+    if (!adjustable)
+        return;
+    if (!adjustable.enabled) {
+        if (adjustable.minimum !== undefined || adjustable.maximum !== undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['adjustable_quantity', 'enabled'],
+                message: 'minimum and maximum need adjustable_quantity.enabled',
+            });
+        }
+        return;
+    }
+    const bounds = adjustableBoundsOf(adjustable);
+    if (!bounds)
+        return;
+    if (bounds.minimum > bounds.maximum) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['adjustable_quantity', 'minimum'],
+            message: 'minimum cannot exceed maximum',
+        });
+    }
+    else if (quantity < bounds.minimum || quantity > bounds.maximum) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['quantity'],
+            message: `quantity must be between ${bounds.minimum} and ${bounds.maximum}`,
+        });
+    }
+}