@peable.to/contracts 0.4.0 → 1.1.0

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

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promotionCodeRoutes = exports.listPromotionCodesQuery = exports.updatePromotionCodeParams = exports.createPromotionCodeParams = exports.promotionCodeSchema = exports.promotionCodeRestrictionsSchema = 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 catalog_1 = require("../../vocabulary/catalog");
+const shared_1 = require("./shared");
+/**
+ * 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.
+ */
+exports.promotionCodeRestrictionsSchema = (0, objects_1.defineComponent)('PromotionCodeRestrictions', zod_1.z
+    .object({
+    first_time_transaction: zod_1.z
+        .boolean()
+        .describe("Only a customer's first transaction may redeem it."),
+    minimum_amount: primitives_1.amount
+        .nullable()
+        .describe('The smallest order total it applies to, in `minimum_amount_currency`.'),
+    minimum_amount_currency: primitives_1.currency.nullable(),
+})
+    .strict());
+exports.promotionCodeSchema = (0, objects_1.defineObject)('promotion_code', 'PromotionCode', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('promotion_code'),
+    livemode: primitives_1.livemode,
+    code: zod_1.z.string(),
+    coupon: (0, objects_1.expandable)('coupon', 'The coupon it redeems: its id, or the Coupon with `expand[]=coupon`.'),
+    customer: (0, objects_1.expandable)('customer', 'The one customer who may redeem it (`cus_…`, or the Customer with `expand[]=customer`); `null` for anyone.').nullable(),
+    active: zod_1.z.boolean(),
+    max_redemptions: zod_1.z.number().int().nullable(),
+    expires_at: primitives_1.unixSeconds.nullable().describe("Never after the coupon's `redeem_by`."),
+    times_redeemed: zod_1.z.number().int(),
+    restrictions: exports.promotionCodeRestrictionsSchema,
+    metadata: primitives_1.metadata,
+    created: primitives_1.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 = zod_1.z
+    .string()
+    .regex(new RegExp(`^[A-Za-z0-9]{1,${catalog_1.CATALOG_LIMITS.promotionCodeMax}}$`), `a code is 1–${catalog_1.CATALOG_LIMITS.promotionCodeMax} letters and digits`);
+exports.createPromotionCodeParams = zod_1.z
+    .object({
+    coupon: params_1.idParam,
+    code: code.optional().describe('Letters and digits; generated when absent.'),
+    customer: params_1.idParam.optional().describe('Only this customer (`cus_…`) may redeem it.'),
+    active: zod_1.z.boolean().optional(),
+    max_redemptions: shared_1.countParam.optional(),
+    expires_at: shared_1.positiveUnixSecondsParam.optional(),
+    restrictions: zod_1.z
+        .object({
+        first_time_transaction: zod_1.z.boolean().optional(),
+        minimum_amount: shared_1.baseUnitAmountParam.optional(),
+        minimum_amount_currency: primitives_1.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',
+            });
+        }
+        (0, shared_1.checkAmountBound)(ctx, restrictions.minimum_amount, restrictions.minimum_amount_currency, [
+            'minimum_amount',
+        ]);
+    })
+        .optional(),
+    metadata: params_1.metadataCreateParam.optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+exports.updatePromotionCodeParams = zod_1.z
+    .object({
+    active: zod_1.z.boolean().optional(),
+    metadata: params_1.metadataUpdateParam.optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+exports.listPromotionCodesQuery = (0, params_1.listQuery)({
+    code: zod_1.z.string().min(1).max(255).optional().describe('Case-insensitive.'),
+    coupon: params_1.idParam.optional(),
+    customer: params_1.idParam.optional(),
+    active: shared_1.queryFlag.optional(),
+});
+exports.promotionCodeRoutes = [
+    (0, route_1.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: exports.createPromotionCodeParams,
+        response: exports.promotionCodeSchema,
+        sdk: 'promotionCodes.create',
+        expandable: 'promotion_code',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listPromotionCodes',
+        method: 'get',
+        path: '/v1/promotion_codes',
+        tag: 'Promotion codes',
+        summary: 'List promotion codes',
+        auth: 'service',
+        scope: 'payments:read',
+        query: exports.listPromotionCodesQuery,
+        response: (0, envelopes_1.listOf)(exports.promotionCodeSchema),
+        sdk: 'promotionCodes.list',
+        expandable: 'promotion_code',
+    }),
+    (0, route_1.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: params_1.expandOnlyQuery,
+        response: exports.promotionCodeSchema,
+        sdk: 'promotionCodes.retrieve',
+        expandable: 'promotion_code',
+    }),
+    (0, route_1.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: exports.updatePromotionCodeParams,
+        response: exports.promotionCodeSchema,
+        sdk: 'promotionCodes.update',
+        expandable: 'promotion_code',
+    }),
+];

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

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearing = exports.queryFlag = exports.positiveUnixSecondsParam = exports.countParam = exports.baseUnitAmountParam = void 0;
+exports.queryIdList = queryIdList;
+exports.issuer = issuer;
+exports.amountWithinBound = amountWithinBound;
+exports.checkAmountBound = checkAmountBound;
+const zod_1 = require("zod");
+const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const catalog_1 = require("../../vocabulary/catalog");
+const money_1 = require("../../vocabulary/money");
+/**
+ * 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`. */
+exports.baseUnitAmountParam = zod_1.z
+    .string()
+    .refine(money_1.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`. */
+exports.countParam = zod_1.z.number().int().min(1).max(2147483647);
+/** A future instant in a body (`redeem_by`, `expires_at`): positive Unix seconds. */
+exports.positiveUnixSecondsParam = zod_1.z.number().int().positive().max(params_1.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.
+ */
+exports.queryFlag = params_1.queryBoolean;
+/** `ids[]=a&ids[]=b` or `ids=a`: one id is a list of one. */
+function queryIdList(max) {
+    return (0, objects_1.describe)(zod_1.z
+        .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())])
+        .transform((value) => (typeof value === 'string' ? [value] : value))
+        .pipe(zod_1.z.array(zod_1.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`. */
+const clearing = (schema) => zod_1.z
+    .union([schema, zod_1.z.literal('')])
+    .transform((value) => (value === '' ? null : value));
+exports.clearing = clearing;
+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`. */
+function amountWithinBound(issue, amount, currency, path) {
+    if (amount === undefined || !(0, money_1.isBaseUnitString)(amount))
+        return;
+    if (BigInt(amount) > (0, catalog_1.maxBaseUnits)(currency)) {
+        issue(path, `must be at most ${(0, catalog_1.maxBaseUnits)(currency)} (${catalog_1.CATALOG_MAX_WHOLE_UNITS} whole ${currency})`);
+    }
+}
+/** Add a bound issue for a coupon or promotion amount in `currency`. */
+function checkAmountBound(ctx, amount, currency, path) {
+    if (currency !== undefined)
+        amountWithinBound(issuer(ctx).issue, amount, currency, path);
+}

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

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testClockRoutes = exports.listTestClocksQuery = exports.advanceTestClockParams = exports.createTestClockParams = exports.deletedTestClockSchema = exports.testClockSchema = 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 catalog_1 = require("../../vocabulary/catalog");
+/**
+ * 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.
+ */
+exports.testClockSchema = (0, objects_1.defineObject)('test_helpers.test_clock', 'TestClock', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('test_helpers.test_clock'),
+    livemode: zod_1.z.literal(false).describe('Always `false`: test clocks exist in test mode only.'),
+    name: zod_1.z.string().nullable(),
+    frozen_time: primitives_1.unixSeconds.describe('The instant everything on the clock lives at.'),
+    status: zod_1.z.enum(catalog_1.TEST_CLOCK_STATUSES),
+    deletes_after: primitives_1.unixSeconds.describe('Deleted, with everything on it, after this instant.'),
+    created: primitives_1.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,
+        },
+    ],
+});
+exports.deletedTestClockSchema = (0, objects_1.defineComponent)('DeletedTestClock', (0, envelopes_1.deletedOf)('test_helpers.test_clock'));
+exports.createTestClockParams = zod_1.z
+    .object({ frozen_time: params_1.unixSecondsParam, name: zod_1.z.string().min(1).max(300).optional() })
+    .strict();
+exports.advanceTestClockParams = zod_1.z
+    .object({
+    frozen_time: params_1.unixSecondsParam.describe("Later than the clock's current `frozen_time`, and at most two years after it."),
+})
+    .strict();
+exports.listTestClocksQuery = (0, params_1.listQuery)({});
+const id = { id: 'The test clock (`clock_…`).' };
+exports.testClockRoutes = [
+    (0, route_1.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: exports.createTestClockParams,
+        response: exports.testClockSchema,
+        sdk: 'testHelpers.testClocks.create',
+    }),
+    (0, route_1.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: exports.listTestClocksQuery,
+        response: (0, envelopes_1.listOf)(exports.testClockSchema),
+        sdk: 'testHelpers.testClocks.list',
+        expandable: 'test_helpers.test_clock',
+    }),
+    (0, route_1.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: params_1.expandOnlyQuery,
+        response: exports.testClockSchema,
+        sdk: 'testHelpers.testClocks.retrieve',
+    }),
+    (0, route_1.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: exports.advanceTestClockParams,
+        response: exports.testClockSchema,
+        sdk: 'testHelpers.testClocks.advance',
+    }),
+    (0, route_1.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: exports.deletedTestClockSchema,
+        sdk: 'testHelpers.testClocks.del',
+    }),
+];