@peable.to/contracts 0.3.0 → 1.0.0

package/dist/esm/resources/catalog/products.js

@@ -0,0 +1,225 @@
+import { z } from 'zod';
+import { deletedOf, listOf, searchResultOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, expandParam, listQuery, metadataCreateParam, metadataUpdateParam, searchQuery, } from '../../common/params.js';
+import { livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { CATALOG_LIMITS } from '../../vocabulary/catalog.js';
+import { isKnownTaxCode } from '../../vocabulary/tax.js';
+import { defaultPriceDataParams } from './prices.js';
+import { clearing, queryFlag, queryIdList } from './shared.js';
+/**
+ * Products (`prod_…`, ADR 0018) — what a merchant sells; its prices say how
+ * much. A product with prices cannot be deleted: archive it with
+ * `active: false`.
+ */
+/** A product feature shown on pricing tables and checkout (Stripe's marketing features). */
+export const productMarketingFeatureSchema = defineComponent('ProductMarketingFeature', z.object({ name: z.string() }).strict());
+export const productSchema = defineObject('product', 'Product', z
+    .object({
+    id: z.string(),
+    object: z.literal('product'),
+    livemode,
+    active: z.boolean(),
+    name: z.string(),
+    description: z.string().nullable(),
+    images: z.array(z.string()).describe('Up to 8 image URLs.'),
+    metadata,
+    tax_code: z
+        .string()
+        .nullable()
+        .describe("A Peable Tax code (`txcd_…`), or `null` for the merchant's default."),
+    default_price: expandable('price', "The product's default price: `price_…`, or the Price with `expand[]=default_price`.").nullable(),
+    unit_label: z
+        .string()
+        .nullable()
+        .describe('The unit a quantity counts (`seat`), shown on receipts and invoices.'),
+    url: z.string().nullable(),
+    statement_descriptor: z
+        .string()
+        .nullable()
+        .describe('What appears on a card statement; at most 22 characters.'),
+    marketing_features: z.array(productMarketingFeatureSchema),
+    created: unixSeconds,
+    updated: unixSeconds,
+})
+    .strict(), {
+    description: 'What a merchant sells. Its prices say how much. A product with prices cannot be deleted; set `active: false` to archive it.',
+    examples: [
+        {
+            id: 'prod_0193b8f2c1a87d3e9f4a',
+            object: 'product',
+            livemode: false,
+            active: true,
+            name: 'Mention Plus',
+            description: 'Everything in Mention, plus the Plus features.',
+            images: [],
+            metadata: {},
+            tax_code: 'txcd_10103000',
+            default_price: 'price_0193b8f2c1a87d3e9f4b',
+            unit_label: null,
+            url: null,
+            statement_descriptor: null,
+            marketing_features: [{ name: 'Longer posts' }],
+            created: 1793750400,
+            updated: 1793750400,
+        },
+    ],
+});
+/** What `DELETE /v1/products/{id}` answers. */
+export const deletedProductSchema = defineComponent('DeletedProduct', deletedOf('product'));
+const url = z
+    .string()
+    .max(CATALOG_LIMITS.urlMax)
+    .regex(/^https?:\/\/\S+$/, 'must be an http(s) URL');
+const fields = {
+    name: z.string().min(1).max(CATALOG_LIMITS.productNameMax),
+    description: z.string().min(1).max(CATALOG_LIMITS.productDescriptionMax),
+    images: z.array(url).max(CATALOG_LIMITS.productImagesMax),
+    tax_code: z
+        .string()
+        .refine(isKnownTaxCode, 'is not a Peable Tax code (GET /v1/tax/codes lists them)'),
+    unit_label: z.string().min(1).max(CATALOG_LIMITS.unitLabelMax),
+    url,
+    // Card networks print at most 22 characters, need one letter, and refuse
+    // `< > \ ' " *`.
+    statement_descriptor: z
+        .string()
+        .min(1)
+        .max(CATALOG_LIMITS.statementDescriptorMax)
+        .regex(/[A-Za-z]/, 'must contain at least one letter')
+        .refine((value) => !/[<>\\'"*]/.test(value), 'cannot contain < > \\ \' " or *'),
+    marketing_features: z
+        .array(z.object({ name: z.string().min(1).max(CATALOG_LIMITS.marketingFeatureNameMax) }).strict())
+        .max(CATALOG_LIMITS.marketingFeaturesMax),
+};
+export const createProductParams = z
+    .object({
+    name: fields.name,
+    active: z.boolean().optional(),
+    description: fields.description.optional(),
+    images: fields.images.optional(),
+    metadata: metadataCreateParam.optional(),
+    tax_code: fields.tax_code.optional(),
+    default_price_data: defaultPriceDataParams
+        .optional()
+        .describe("Create the product's default price with it."),
+    unit_label: fields.unit_label.optional(),
+    url: fields.url.optional(),
+    statement_descriptor: fields.statement_descriptor.optional(),
+    marketing_features: fields.marketing_features.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+/** `""` clears an optional text field; `metadata` is a patch. */
+export const updateProductParams = z
+    .object({
+    name: fields.name.optional(),
+    active: z.boolean().optional(),
+    description: clearing(fields.description).optional(),
+    images: fields.images.optional(),
+    metadata: metadataUpdateParam.optional(),
+    tax_code: clearing(fields.tax_code).optional(),
+    default_price: clearing(z.string().min(1).max(255))
+        .optional()
+        .describe('One of this product\'s active prices; `""` clears it.'),
+    unit_label: clearing(fields.unit_label).optional(),
+    url: clearing(fields.url).optional(),
+    statement_descriptor: clearing(fields.statement_descriptor).optional(),
+    marketing_features: fields.marketing_features.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const listProductsQuery = listQuery({
+    active: queryFlag.optional(),
+    ids: queryIdList(CATALOG_LIMITS.idsFilterMax)
+        .optional()
+        .describe('Only these products (at most 100).'),
+});
+export const productRoutes = [
+    defineRoute({
+        operationId: 'createProduct',
+        method: 'post',
+        path: '/v1/products',
+        tag: 'Products',
+        summary: 'Create a product',
+        description: '`default_price_data` creates its default price in the same request.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createProductParams,
+        response: productSchema,
+        sdk: 'products.create',
+        expandable: 'product',
+    }),
+    defineRoute({
+        operationId: 'listProducts',
+        method: 'get',
+        path: '/v1/products',
+        tag: 'Products',
+        summary: 'List products',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listProductsQuery,
+        response: listOf(productSchema),
+        sdk: 'products.list',
+        expandable: 'product',
+    }),
+    defineRoute({
+        operationId: 'retrieveProduct',
+        method: 'get',
+        path: '/v1/products/{id}',
+        tag: 'Products',
+        summary: 'Retrieve a product',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The product (`prod_…`).' },
+        query: expandOnlyQuery,
+        response: productSchema,
+        sdk: 'products.retrieve',
+        expandable: 'product',
+    }),
+    defineRoute({
+        operationId: 'updateProduct',
+        method: 'post',
+        path: '/v1/products/{id}',
+        tag: 'Products',
+        summary: 'Update a product',
+        description: 'A field sent as `""` is cleared; `metadata` is a patch.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The product (`prod_…`).' },
+        body: updateProductParams,
+        response: productSchema,
+        sdk: 'products.update',
+        expandable: 'product',
+    }),
+    defineRoute({
+        operationId: 'deleteProduct',
+        method: 'delete',
+        path: '/v1/products/{id}',
+        tag: 'Products',
+        summary: 'Delete a product',
+        description: 'Only a product nothing names; one with prices is archived with `active: false`.',
+        auth: 'service',
+        scope: 'payments:write',
+        params: { id: 'The product (`prod_…`).' },
+        response: deletedProductSchema,
+        sdk: 'products.del',
+    }),
+    defineRoute({
+        operationId: 'searchProducts',
+        method: 'get',
+        path: '/v1/products/search',
+        tag: 'Products',
+        summary: 'Search products',
+        description: "Stripe's query language over `active`, `name`, `description`, `url`, `created` and `metadata['key']`.",
+        auth: 'service',
+        scope: 'payments:read',
+        query: searchQuery,
+        response: searchResultOf(productSchema),
+        sdk: 'products.search',
+        expandable: 'product',
+    }),
+];

package/dist/esm/resources/catalog/promotionCodes.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, expandParam, idParam, listQuery, metadataCreateParam, metadataUpdateParam, } from '../../common/params.js';
+import { amount, currency, livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { CATALOG_LIMITS } from '../../vocabulary/catalog.js';
+import { baseUnitAmountParam, checkAmountBound, countParam, positiveUnixSecondsParam, queryFlag, } from './shared.js';
+/**
+ * Promotion codes (`promo_…`, ADR 0018) — a customer-facing `code` that
+ * redeems a coupon, with its own limits. Codes are case-insensitive and unique
+ * among a merchant's ACTIVE codes.
+ */
+export const promotionCodeRestrictionsSchema = defineComponent('PromotionCodeRestrictions', z
+    .object({
+    first_time_transaction: z
+        .boolean()
+        .describe("Only a customer's first transaction may redeem it."),
+    minimum_amount: amount
+        .nullable()
+        .describe('The smallest order total it applies to, in `minimum_amount_currency`.'),
+    minimum_amount_currency: currency.nullable(),
+})
+    .strict());
+export const promotionCodeSchema = defineObject('promotion_code', 'PromotionCode', z
+    .object({
+    id: z.string(),
+    object: z.literal('promotion_code'),
+    livemode,
+    code: z.string(),
+    coupon: expandable('coupon', 'The coupon it redeems: its id, or the Coupon with `expand[]=coupon`.'),
+    customer: expandable('customer', 'The one customer who may redeem it (`cus_…`, or the Customer with `expand[]=customer`); `null` for anyone.').nullable(),
+    active: z.boolean(),
+    max_redemptions: z.number().int().nullable(),
+    expires_at: unixSeconds.nullable().describe("Never after the coupon's `redeem_by`."),
+    times_redeemed: z.number().int(),
+    restrictions: promotionCodeRestrictionsSchema,
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'promo_0193b8f2c1a87d3e9f4c',
+            object: 'promotion_code',
+            livemode: false,
+            code: 'SUMMER25',
+            coupon: 'SUMMER25',
+            customer: null,
+            active: true,
+            max_redemptions: null,
+            expires_at: null,
+            times_redeemed: 0,
+            restrictions: {
+                first_time_transaction: true,
+                minimum_amount: null,
+                minimum_amount_currency: null,
+            },
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+const code = z
+    .string()
+    .regex(new RegExp(`^[A-Za-z0-9]{1,${CATALOG_LIMITS.promotionCodeMax}}$`), `a code is 1–${CATALOG_LIMITS.promotionCodeMax} letters and digits`);
+export const createPromotionCodeParams = z
+    .object({
+    coupon: idParam,
+    code: code.optional().describe('Letters and digits; generated when absent.'),
+    customer: idParam.optional().describe('Only this customer (`cus_…`) may redeem it.'),
+    active: z.boolean().optional(),
+    max_redemptions: countParam.optional(),
+    expires_at: positiveUnixSecondsParam.optional(),
+    restrictions: z
+        .object({
+        first_time_transaction: z.boolean().optional(),
+        minimum_amount: baseUnitAmountParam.optional(),
+        minimum_amount_currency: currency.optional(),
+    })
+        .strict()
+        .superRefine((restrictions, ctx) => {
+        if ((restrictions.minimum_amount === undefined) !==
+            (restrictions.minimum_amount_currency === undefined)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['minimum_amount_currency'],
+                message: 'minimum_amount and minimum_amount_currency go together',
+            });
+        }
+        checkAmountBound(ctx, restrictions.minimum_amount, restrictions.minimum_amount_currency, [
+            'minimum_amount',
+        ]);
+    })
+        .optional(),
+    metadata: metadataCreateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const updatePromotionCodeParams = z
+    .object({
+    active: z.boolean().optional(),
+    metadata: metadataUpdateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const listPromotionCodesQuery = listQuery({
+    code: z.string().min(1).max(255).optional().describe('Case-insensitive.'),
+    coupon: idParam.optional(),
+    customer: idParam.optional(),
+    active: queryFlag.optional(),
+});
+export const promotionCodeRoutes = [
+    defineRoute({
+        operationId: 'createPromotionCode',
+        method: 'post',
+        path: '/v1/promotion_codes',
+        tag: 'Promotion codes',
+        summary: 'Create a promotion code',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createPromotionCodeParams,
+        response: promotionCodeSchema,
+        sdk: 'promotionCodes.create',
+        expandable: 'promotion_code',
+    }),
+    defineRoute({
+        operationId: 'listPromotionCodes',
+        method: 'get',
+        path: '/v1/promotion_codes',
+        tag: 'Promotion codes',
+        summary: 'List promotion codes',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listPromotionCodesQuery,
+        response: listOf(promotionCodeSchema),
+        sdk: 'promotionCodes.list',
+        expandable: 'promotion_code',
+    }),
+    defineRoute({
+        operationId: 'retrievePromotionCode',
+        method: 'get',
+        path: '/v1/promotion_codes/{id}',
+        tag: 'Promotion codes',
+        summary: 'Retrieve a promotion code',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The promotion code (`promo_…`).' },
+        query: expandOnlyQuery,
+        response: promotionCodeSchema,
+        sdk: 'promotionCodes.retrieve',
+        expandable: 'promotion_code',
+    }),
+    defineRoute({
+        operationId: 'updatePromotionCode',
+        method: 'post',
+        path: '/v1/promotion_codes/{id}',
+        tag: 'Promotion codes',
+        summary: 'Update a promotion code',
+        description: 'Only `active` and `metadata` change.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The promotion code (`promo_…`).' },
+        body: updatePromotionCodeParams,
+        response: promotionCodeSchema,
+        sdk: 'promotionCodes.update',
+        expandable: 'promotion_code',
+    }),
+];

package/dist/esm/resources/catalog/shared.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { describe } from '../../common/objects.js';
+import { MAX_UNIX_SECONDS, queryBoolean } from '../../common/params.js';
+import { CATALOG_MAX_WHOLE_UNITS, maxBaseUnits } from '../../vocabulary/catalog.js';
+import { isBaseUnitString } from '../../vocabulary/money.js';
+/**
+ * Request pieces the catalog's bodies share — and that every other body naming
+ * an amount, a currency or an inline price reuses (checkout line items,
+ * invoice items), so one shape rule is written once and every caller refuses
+ * the same mistake with the same `param`.
+ */
+/** A canonical base-unit integer string: `"1999"`, never `"19.99"` or `1999`. */
+export const baseUnitAmountParam = z
+    .string()
+    .refine(isBaseUnitString, 'must be a non-negative integer string in the smallest currency unit')
+    .describe('Base units of the currency, as an integer string (`"1999"` is 19.99 EUR).');
+/** A positive count that fits a Postgres `integer`. */
+export const countParam = z.number().int().min(1).max(2147483647);
+/** A future instant in a body (`redeem_by`, `expires_at`): positive Unix seconds. */
+export const positiveUnixSecondsParam = z.number().int().positive().max(MAX_UNIX_SECONDS);
+/**
+ * A boolean filter in a query string. A typed caller passes `true` / `false`
+ * (the SDK spells it for the URL); the URL carries `'true'` / `'false'`,
+ * which the gateway reads the same.
+ */
+export const queryFlag = queryBoolean;
+/** `ids[]=a&ids[]=b` or `ids=a`: one id is a list of one. */
+export function queryIdList(max) {
+    return describe(z
+        .union([z.string(), z.array(z.string())])
+        .transform((value) => (typeof value === 'string' ? [value] : value))
+        .pipe(z.array(z.string().min(1).max(255)).min(1).max(max)), {
+        jsonSchema: {
+            type: 'array',
+            items: { type: 'string', maxLength: 255 },
+            minItems: 1,
+            maxItems: max,
+        },
+    });
+}
+/** `""` on an update clears the field (Stripe's rule): the parsed value is `null`. */
+export const clearing = (schema) => z
+    .union([schema, z.literal('')])
+    .transform((value) => (value === '' ? null : value));
+export function issuer(ctx) {
+    let failed = false;
+    return {
+        issue: (path, message) => {
+            failed = true;
+            ctx.addIssue({ code: 'custom', path, message });
+        },
+        failed: () => failed,
+    };
+}
+/** Refuse an amount above the catalog's bound for `currency`. */
+export function amountWithinBound(issue, amount, currency, path) {
+    if (amount === undefined || !isBaseUnitString(amount))
+        return;
+    if (BigInt(amount) > maxBaseUnits(currency)) {
+        issue(path, `must be at most ${maxBaseUnits(currency)} (${CATALOG_MAX_WHOLE_UNITS} whole ${currency})`);
+    }
+}
+/** Add a bound issue for a coupon or promotion amount in `currency`. */
+export function checkAmountBound(ctx, amount, currency, path) {
+    if (currency !== undefined)
+        amountWithinBound(issuer(ctx).issue, amount, currency, path);
+}

package/dist/esm/resources/catalog/testClocks.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { deletedOf, listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, listQuery, unixSecondsParam } from '../../common/params.js';
+import { unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TEST_CLOCK_STATUSES } from '../../vocabulary/catalog.js';
+/**
+ * Test clocks (`clock_…`, ADR 0018 §3, test mode only). Customers attached to
+ * a clock — and every subscription and invoice of theirs — live at
+ * `frozen_time` instead of the wall clock, so a trial, a renewal or a dunning
+ * schedule runs in seconds. Advancing it runs the engine for everything on the
+ * clock up to the new time.
+ */
+export const testClockSchema = defineObject('test_helpers.test_clock', 'TestClock', z
+    .object({
+    id: z.string(),
+    object: z.literal('test_helpers.test_clock'),
+    livemode: z.literal(false).describe('Always `false`: test clocks exist in test mode only.'),
+    name: z.string().nullable(),
+    frozen_time: unixSeconds.describe('The instant everything on the clock lives at.'),
+    status: z.enum(TEST_CLOCK_STATUSES),
+    deletes_after: unixSeconds.describe('Deleted, with everything on it, after this instant.'),
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'clock_0193b8f2c1a87d3e9f4d',
+            object: 'test_helpers.test_clock',
+            livemode: false,
+            name: 'Annual renewal',
+            frozen_time: 1793750400,
+            status: 'ready',
+            deletes_after: 1796342400,
+            created: 1793750400,
+        },
+    ],
+});
+export const deletedTestClockSchema = defineComponent('DeletedTestClock', deletedOf('test_helpers.test_clock'));
+export const createTestClockParams = z
+    .object({ frozen_time: unixSecondsParam, name: z.string().min(1).max(300).optional() })
+    .strict();
+export const advanceTestClockParams = z
+    .object({
+    frozen_time: unixSecondsParam.describe("Later than the clock's current `frozen_time`, and at most two years after it."),
+})
+    .strict();
+export const listTestClocksQuery = listQuery({});
+const id = { id: 'The test clock (`clock_…`).' };
+export const testClockRoutes = [
+    defineRoute({
+        operationId: 'createTestClock',
+        method: 'post',
+        path: '/v1/test_helpers/test_clocks',
+        tag: 'Test clocks',
+        summary: 'Create a test clock',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        testModeOnly: true,
+        body: createTestClockParams,
+        response: testClockSchema,
+        sdk: 'testHelpers.testClocks.create',
+    }),
+    defineRoute({
+        operationId: 'listTestClocks',
+        method: 'get',
+        path: '/v1/test_helpers/test_clocks',
+        tag: 'Test clocks',
+        summary: 'List test clocks',
+        auth: 'service',
+        scope: 'payments:read',
+        testModeOnly: true,
+        query: listTestClocksQuery,
+        response: listOf(testClockSchema),
+        sdk: 'testHelpers.testClocks.list',
+        expandable: 'test_helpers.test_clock',
+    }),
+    defineRoute({
+        operationId: 'retrieveTestClock',
+        method: 'get',
+        path: '/v1/test_helpers/test_clocks/{id}',
+        tag: 'Test clocks',
+        summary: 'Retrieve a test clock',
+        auth: 'service',
+        scope: 'payments:read',
+        testModeOnly: true,
+        params: id,
+        query: expandOnlyQuery,
+        response: testClockSchema,
+        sdk: 'testHelpers.testClocks.retrieve',
+    }),
+    defineRoute({
+        operationId: 'advanceTestClock',
+        method: 'post',
+        path: '/v1/test_helpers/test_clocks/{id}/advance',
+        tag: 'Test clocks',
+        summary: 'Advance a test clock',
+        description: 'Moves `frozen_time` forward and runs the billing engine for everything on the clock up to it: trials end, subscriptions renew, invoices finalize and dunning retries.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        testModeOnly: true,
+        params: id,
+        body: advanceTestClockParams,
+        response: testClockSchema,
+        sdk: 'testHelpers.testClocks.advance',
+    }),
+    defineRoute({
+        operationId: 'deleteTestClock',
+        method: 'delete',
+        path: '/v1/test_helpers/test_clocks/{id}',
+        tag: 'Test clocks',
+        summary: 'Delete a test clock',
+        description: 'Every live subscription on the clock is cancelled at its frozen time; the clock stays readable to the objects that name it.',
+        auth: 'service',
+        scope: 'payments:write',
+        testModeOnly: true,
+        params: id,
+        response: deletedTestClockSchema,
+        sdk: 'testHelpers.testClocks.del',
+    }),
+];