@peable.to/contracts 0.4.0 → 1.0.0

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

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import { defineObject } from '../../common/objects.js';
+import { expandOnlyQuery } from '../../common/params.js';
+import { livemode, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { BILLING_SETTINGS_LIMITS, DUNNING_FINAL_ACTIONS, DUNNING_INVOICE_ACTIONS, } from '../../vocabulary/catalog.js';
+/**
+ * The merchant's billing settings (ADR 0018 §5; one per merchant and mode).
+ * Every field has a default, so a merchant that never opens the screen bills
+ * correctly:
+ *
+ *  - `invoice_prefix`: derived from the merchant id; numbers are
+ *    `PREFIX-0001`, gapless per merchant.
+ *  - `dunning.retry_schedule_days`: `[1, 3, 5, 7]` — each retry so many days
+ *    after the previous attempt (16 days, four retries, Stripe's default
+ *    window).
+ *  - `dunning.final_action`: `cancel` — the subscription ends when the last
+ *    retry fails; `dunning.invoice_action`: `mark_uncollectible`.
+ *  - emails on: the payer is told when an invoice is finalized for them
+ *    (`send_invoice`) and when a payment fails.
+ */
+export const billingSettingsSchema = defineObject('billing_settings', 'BillingSettings', z
+    .object({
+    object: z.literal('billing_settings'),
+    livemode,
+    invoice_prefix: z.string().describe('Invoice numbers are `PREFIX-0001`, gapless.'),
+    next_invoice_sequence: z
+        .number()
+        .int()
+        .describe('The next invoice number that will be assigned.'),
+    default_days_until_due: z.number().int(),
+    dunning: z
+        .object({
+        retry_schedule_days: z
+            .array(z.number().int())
+            .describe('Each retry so many days after the previous attempt.'),
+        final_action: z
+            .enum(DUNNING_FINAL_ACTIONS)
+            .describe('What happens to the subscription once the last retry fails.'),
+        invoice_action: z
+            .enum(DUNNING_INVOICE_ACTIONS)
+            .describe('What happens to the invoice once the last retry fails.'),
+    })
+        .strict(),
+    emails: z
+        .object({
+        invoice_finalized: z.boolean(),
+        payment_failed: z.boolean(),
+    })
+        .strict(),
+    updated: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'billing_settings',
+            livemode: false,
+            invoice_prefix: 'MENTION',
+            next_invoice_sequence: 1,
+            default_days_until_due: 30,
+            dunning: {
+                retry_schedule_days: [1, 3, 5, 7],
+                final_action: 'cancel',
+                invoice_action: 'mark_uncollectible',
+            },
+            emails: { invoice_finalized: true, payment_failed: true },
+            updated: 1793750400,
+        },
+    ],
+});
+export const updateBillingSettingsParams = z
+    .object({
+    invoice_prefix: z
+        .string()
+        .regex(new RegExp(BILLING_SETTINGS_LIMITS.invoicePrefixPattern))
+        .optional()
+        .describe('3–12 uppercase letters and digits.'),
+    default_days_until_due: z
+        .number()
+        .int()
+        .min(0)
+        .max(BILLING_SETTINGS_LIMITS.daysUntilDueMax)
+        .optional(),
+    dunning: z
+        .object({
+        retry_schedule_days: z
+            .array(z.number().int().min(1).max(BILLING_SETTINGS_LIMITS.retryDaysMax))
+            .max(BILLING_SETTINGS_LIMITS.retriesMax)
+            .optional(),
+        final_action: z.enum(DUNNING_FINAL_ACTIONS).optional(),
+        invoice_action: z.enum(DUNNING_INVOICE_ACTIONS).optional(),
+    })
+        .strict()
+        .optional(),
+    emails: z
+        .object({ invoice_finalized: z.boolean().optional(), payment_failed: z.boolean().optional() })
+        .strict()
+        .optional(),
+})
+    .strict();
+export const billingSettingsRoutes = [
+    defineRoute({
+        operationId: 'retrieveBillingSettings',
+        method: 'get',
+        path: '/v1/billing_settings',
+        tag: 'Billing settings',
+        summary: 'Retrieve the billing settings',
+        auth: 'service',
+        scope: 'payments:read',
+        query: expandOnlyQuery,
+        response: billingSettingsSchema,
+        sdk: 'billingSettings.retrieve',
+    }),
+    defineRoute({
+        operationId: 'updateBillingSettings',
+        method: 'post',
+        path: '/v1/billing_settings',
+        tag: 'Billing settings',
+        summary: 'Update the billing settings',
+        description: 'Invoice numbering, the default payment term, dunning and the payer emails.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: updateBillingSettingsParams,
+        response: billingSettingsSchema,
+        sdk: 'billingSettings.update',
+    }),
+];

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

@@ -0,0 +1,219 @@
+import { z } from 'zod';
+import { deletedOf, listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, expandParam, 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, COUPON_DURATIONS } from '../../vocabulary/catalog.js';
+import { baseUnitAmountParam, checkAmountBound, clearing, countParam, positiveUnixSecondsParam, } from './shared.js';
+/**
+ * Coupons (ADR 0018) — a discount, by percentage or by a fixed amount in one
+ * currency. Its `id` is the merchant's own (`SUMMER25`) or generated
+ * (`coupon_…`), and names that one coupon forever: a deleted coupon's id is
+ * never reused. Only `name` and `metadata` change; the terms of a discount a
+ * customer already holds cannot.
+ */
+export const couponSchema = defineObject('coupon', 'Coupon', z
+    .object({
+    id: z.string(),
+    object: z.literal('coupon'),
+    livemode,
+    name: z.string().nullable(),
+    percent_off: z
+        .number()
+        .nullable()
+        .describe('0 < x ≤ 100, at most two decimals. Set exactly when `amount_off` is not.'),
+    amount_off: amount.nullable().describe('Base units taken off, in `currency`.'),
+    currency: currency.nullable(),
+    duration: z.enum(COUPON_DURATIONS),
+    duration_in_months: z
+        .number()
+        .int()
+        .nullable()
+        .describe('Months a `repeating` coupon lasts; `null` otherwise.'),
+    max_redemptions: z.number().int().nullable(),
+    redeem_by: unixSeconds.nullable().describe('The last instant it can be redeemed.'),
+    times_redeemed: z.number().int(),
+    valid: z
+        .boolean()
+        .describe('Whether it can still be redeemed: not past `redeem_by` and not used up.'),
+    applies_to: z
+        .object({ products: z.array(z.string()) })
+        .strict()
+        .nullable()
+        .describe('The products (`prod_…`) it is restricted to, or `null` for every product.'),
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'SUMMER25',
+            object: 'coupon',
+            livemode: false,
+            name: 'Summer sale',
+            percent_off: 25,
+            amount_off: null,
+            currency: null,
+            duration: 'repeating',
+            duration_in_months: 3,
+            max_redemptions: 100,
+            redeem_by: null,
+            times_redeemed: 0,
+            valid: true,
+            applies_to: null,
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+/** What `DELETE /v1/coupons/{id}` answers. Existing discounts are not affected. */
+export const deletedCouponSchema = defineComponent('DeletedCoupon', deletedOf('coupon'));
+/**
+ * A percentage with at most two decimals, as basis points (12.5 → 1250). The
+ * check is on the scaled value, so 33.333 is refused rather than rounded.
+ */
+const percentOff = z
+    .number()
+    .gt(0)
+    .max(100)
+    .refine((value) => Math.abs(value * 100 - Math.round(value * 100)) < 1e-9, 'percent_off has at most two decimals')
+    .transform((value) => Math.round(value * 100));
+const couponId = z
+    .string()
+    .regex(new RegExp(`^[A-Za-z0-9_-]{1,${CATALOG_LIMITS.couponIdMax}}$`), `a coupon id is 1–${CATALOG_LIMITS.couponIdMax} letters, digits, '_' or '-'`);
+const name = z.string().min(1).max(CATALOG_LIMITS.couponNameMax);
+export const createCouponParams = z
+    .object({
+    id: couponId
+        .optional()
+        .describe('Your own id (`SUMMER25`); generated (`coupon_…`) when absent.'),
+    name: name.optional(),
+    percent_off: percentOff.optional(),
+    amount_off: baseUnitAmountParam.optional(),
+    currency: currency.optional().describe('Required with `amount_off`.'),
+    duration: z.enum(COUPON_DURATIONS).optional().describe('Default `once`.'),
+    duration_in_months: z
+        .number()
+        .int()
+        .min(1)
+        .max(CATALOG_LIMITS.couponDurationInMonthsMax)
+        .optional()
+        .describe('Required for `repeating`.'),
+    max_redemptions: countParam.optional(),
+    redeem_by: positiveUnixSecondsParam.optional().describe('Unix seconds, in the future.'),
+    applies_to: z
+        .object({
+        products: z
+            .array(z.string().min(1).max(255))
+            .min(1)
+            .max(CATALOG_LIMITS.couponAppliesToProductsMax),
+    })
+        .strict()
+        .optional(),
+    metadata: metadataCreateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict()
+    .superRefine((body, ctx) => {
+    const issue = (path, message) => ctx.addIssue({ code: 'custom', path: [path], message });
+    if ((body.percent_off === undefined) === (body.amount_off === undefined)) {
+        issue('percent_off', 'a coupon takes exactly one of percent_off and amount_off');
+    }
+    if (body.amount_off !== undefined && body.currency === undefined) {
+        issue('currency', 'amount_off needs a currency');
+    }
+    if (body.amount_off === undefined && body.currency !== undefined) {
+        issue('currency', 'currency is only for an amount_off coupon');
+    }
+    if (body.amount_off === '0')
+        issue('amount_off', 'amount_off must be positive');
+    checkAmountBound(ctx, body.amount_off, body.currency, ['amount_off']);
+    const duration = body.duration ?? 'once';
+    if (duration === 'repeating' && body.duration_in_months === undefined) {
+        issue('duration_in_months', 'a repeating coupon needs duration_in_months');
+    }
+    if (duration !== 'repeating' && body.duration_in_months !== undefined) {
+        issue('duration_in_months', 'duration_in_months is only for a repeating coupon');
+    }
+});
+export const updateCouponParams = z
+    .object({
+    name: clearing(name).optional().describe('`""` clears it.'),
+    metadata: metadataUpdateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const listCouponsQuery = listQuery({});
+export const couponRoutes = [
+    defineRoute({
+        operationId: 'createCoupon',
+        method: 'post',
+        path: '/v1/coupons',
+        tag: 'Coupons',
+        summary: 'Create a coupon',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createCouponParams,
+        response: couponSchema,
+        sdk: 'coupons.create',
+        expandable: 'coupon',
+    }),
+    defineRoute({
+        operationId: 'listCoupons',
+        method: 'get',
+        path: '/v1/coupons',
+        tag: 'Coupons',
+        summary: 'List coupons',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listCouponsQuery,
+        response: listOf(couponSchema),
+        sdk: 'coupons.list',
+        expandable: 'coupon',
+    }),
+    defineRoute({
+        operationId: 'retrieveCoupon',
+        method: 'get',
+        path: '/v1/coupons/{id}',
+        tag: 'Coupons',
+        summary: 'Retrieve a coupon',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The coupon (`SUMMER25`, `coupon_…`).' },
+        query: expandOnlyQuery,
+        response: couponSchema,
+        sdk: 'coupons.retrieve',
+        expandable: 'coupon',
+    }),
+    defineRoute({
+        operationId: 'updateCoupon',
+        method: 'post',
+        path: '/v1/coupons/{id}',
+        tag: 'Coupons',
+        summary: 'Update a coupon',
+        description: 'Only `name` and `metadata` change.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The coupon (`SUMMER25`, `coupon_…`).' },
+        body: updateCouponParams,
+        response: couponSchema,
+        sdk: 'coupons.update',
+        expandable: 'coupon',
+    }),
+    defineRoute({
+        operationId: 'deleteCoupon',
+        method: 'delete',
+        path: '/v1/coupons/{id}',
+        tag: 'Coupons',
+        summary: 'Delete a coupon',
+        description: 'Discounts customers already hold are not affected; the id is never reused.',
+        auth: 'service',
+        scope: 'payments:write',
+        params: { id: 'The coupon (`SUMMER25`, `coupon_…`).' },
+        response: deletedCouponSchema,
+        sdk: 'coupons.del',
+    }),
+];

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

@@ -0,0 +1,254 @@
+import { z } from 'zod';
+import { deletedOf, listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, idParam, listQuery, metadataCreateParam, metadataUpdateParam, } from '../../common/params.js';
+import { livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { queryFlag } from './shared.js';
+/**
+ * Entitlements (ADR 0018 §8): features (`feat_…`) a product grants, and what a
+ * customer may access NOW. `lookup_key` is what an app checks access by.
+ */
+/** A feature (`feat_…`) a product grants — `lookup_key` is what an app checks. */
+export const entitlementFeatureSchema = defineObject('entitlements.feature', 'EntitlementFeature', z
+    .object({
+    id: z.string(),
+    object: z.literal('entitlements.feature'),
+    livemode,
+    lookup_key: z.string().describe('What an app checks access by; unique per merchant.'),
+    name: z.string(),
+    active: z
+        .boolean()
+        .describe('`false`: archived, and withdrawn from every customer that held it.'),
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'feat_0193b8f2c1a87d3e9f4f',
+            object: 'entitlements.feature',
+            livemode: false,
+            lookup_key: 'mention_plus',
+            name: 'Mention Plus',
+            active: true,
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+/** A feature attached to a product (`prodft_…`). */
+export const productFeatureSchema = defineObject('product_feature', 'ProductFeature', z
+    .object({
+    id: z.string(),
+    object: z.literal('product_feature'),
+    livemode,
+    product: z.string().describe('The product (`prod_…`) that grants it.'),
+    entitlement_feature: entitlementFeatureSchema,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'prodft_0193b8f2c1a87d3e9f50',
+            object: 'product_feature',
+            livemode: false,
+            product: 'prod_0193b8f2c1a87d3e9f4a',
+            entitlement_feature: {
+                id: 'feat_0193b8f2c1a87d3e9f4f',
+                object: 'entitlements.feature',
+                livemode: false,
+                lookup_key: 'mention_plus',
+                name: 'Mention Plus',
+                active: true,
+                metadata: {},
+                created: 1793750400,
+            },
+        },
+    ],
+});
+/** What `DELETE /v1/products/{id}/features/{feature}` answers. */
+export const deletedProductFeatureSchema = defineComponent('DeletedProductFeature', deletedOf('product_feature'));
+/**
+ * One feature a customer is entitled to right now: some product granting it is
+ * on a `trialing`, `active` or `past_due` subscription of theirs. Several
+ * products granting the same feature give ONE entitlement — Mention Plus
+ * through the Plus product or through Oxy One is the same access.
+ */
+export const activeEntitlementSchema = defineObject('entitlements.active_entitlement', 'ActiveEntitlement', z
+    .object({
+    id: z.string().describe('Stable per customer and feature.'),
+    object: z.literal('entitlements.active_entitlement'),
+    livemode,
+    feature: z.string().describe('The feature (`feat_…`).'),
+    lookup_key: z.string(),
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'ent_5f1c0a9e2b7d4c3a8e6f1b2d',
+            object: 'entitlements.active_entitlement',
+            livemode: false,
+            feature: 'feat_0193b8f2c1a87d3e9f4f',
+            lookup_key: 'mention_plus',
+        },
+    ],
+});
+/** What `entitlements.active_entitlement_summary.updated` carries: a customer's complete set. */
+export const activeEntitlementSummarySchema = defineObject('entitlements.active_entitlement_summary', 'ActiveEntitlementSummary', z
+    .object({
+    object: z.literal('entitlements.active_entitlement_summary'),
+    livemode,
+    customer: z.string().describe('The customer (`cus_…`).'),
+    entitlements: z
+        .object({
+        object: z.literal('list'),
+        data: z.array(activeEntitlementSchema),
+        has_more: z.literal(false),
+        url: z.string(),
+    })
+        .strict()
+        .describe('The complete set: never paged.'),
+})
+    .strict());
+const name = z.string().min(1).max(80);
+export const createEntitlementFeatureParams = z
+    .object({
+    lookup_key: z.string().regex(/^[A-Za-z0-9_.:-]{1,80}$/),
+    name,
+    metadata: metadataCreateParam.optional(),
+})
+    .strict();
+export const updateEntitlementFeatureParams = z
+    .object({
+    name: name.optional(),
+    active: z
+        .boolean()
+        .optional()
+        .describe('`false` archives it and withdraws it from every customer that held it.'),
+    metadata: metadataUpdateParam.optional(),
+})
+    .strict();
+export const listEntitlementFeaturesQuery = listQuery({
+    lookup_key: z.string().min(1).max(80).optional(),
+    archived: queryFlag.optional(),
+});
+export const attachProductFeatureParams = z
+    .object({ entitlement_feature: idParam.describe('The feature (`feat_…`) to grant.') })
+    .strict();
+export const listProductFeaturesQuery = listQuery({});
+export const listActiveEntitlementsQuery = listQuery({
+    customer: idParam.describe('The customer (`cus_…`).'),
+});
+const featureId = { id: 'The feature (`feat_…`).' };
+export const entitlementRoutes = [
+    defineRoute({
+        operationId: 'createEntitlementFeature',
+        method: 'post',
+        path: '/v1/entitlements/features',
+        tag: 'Entitlements',
+        summary: 'Create a feature',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createEntitlementFeatureParams,
+        response: entitlementFeatureSchema,
+        sdk: 'entitlements.features.create',
+    }),
+    defineRoute({
+        operationId: 'listEntitlementFeatures',
+        method: 'get',
+        path: '/v1/entitlements/features',
+        tag: 'Entitlements',
+        summary: 'List features',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listEntitlementFeaturesQuery,
+        response: listOf(entitlementFeatureSchema),
+        sdk: 'entitlements.features.list',
+        expandable: 'entitlements.feature',
+    }),
+    defineRoute({
+        operationId: 'retrieveEntitlementFeature',
+        method: 'get',
+        path: '/v1/entitlements/features/{id}',
+        tag: 'Entitlements',
+        summary: 'Retrieve a feature',
+        auth: 'service',
+        scope: 'payments:read',
+        params: featureId,
+        query: expandOnlyQuery,
+        response: entitlementFeatureSchema,
+        sdk: 'entitlements.features.retrieve',
+    }),
+    defineRoute({
+        operationId: 'updateEntitlementFeature',
+        method: 'post',
+        path: '/v1/entitlements/features/{id}',
+        tag: 'Entitlements',
+        summary: 'Update a feature',
+        description: '`active: false` archives it and withdraws it from every customer that held it.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: featureId,
+        body: updateEntitlementFeatureParams,
+        response: entitlementFeatureSchema,
+        sdk: 'entitlements.features.update',
+    }),
+    defineRoute({
+        operationId: 'attachProductFeature',
+        method: 'post',
+        path: '/v1/products/{id}/features',
+        tag: 'Entitlements',
+        summary: 'Attach a feature to a product',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The product (`prod_…`).' },
+        body: attachProductFeatureParams,
+        response: productFeatureSchema,
+        sdk: 'entitlements.productFeatures.attach',
+    }),
+    defineRoute({
+        operationId: 'listProductFeatures',
+        method: 'get',
+        path: '/v1/products/{id}/features',
+        tag: 'Entitlements',
+        summary: "List a product's features",
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The product (`prod_…`).' },
+        query: listProductFeaturesQuery,
+        response: listOf(productFeatureSchema),
+        sdk: 'entitlements.productFeatures.list',
+        expandable: 'product_feature',
+    }),
+    defineRoute({
+        operationId: 'detachProductFeature',
+        method: 'delete',
+        path: '/v1/products/{id}/features/{feature}',
+        tag: 'Entitlements',
+        summary: 'Detach a feature from a product',
+        auth: 'service',
+        scope: 'payments:write',
+        params: {
+            id: 'The product (`prod_…`).',
+            feature: 'The attachment (`prodft_…`).',
+        },
+        response: deletedProductFeatureSchema,
+        sdk: 'entitlements.productFeatures.detach',
+    }),
+    defineRoute({
+        operationId: 'listActiveEntitlements',
+        method: 'get',
+        path: '/v1/entitlements/active_entitlements',
+        tag: 'Entitlements',
+        summary: "List a customer's active entitlements",
+        description: 'What the customer may access NOW: one entitlement per feature, however many products grant it. A complete set, never paged (`has_more` is always `false`).',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listActiveEntitlementsQuery,
+        response: listOf(activeEntitlementSchema),
+        sdk: 'entitlements.activeEntitlements.list',
+    }),
+];

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

@@ -0,0 +1,38 @@
+// Contracts of this group: one module per resource, re-exported here, and
+// their routes concatenated into `catalogRoutes`.
+import { billingRoutes } from './billing.js';
+import { billingSettingsRoutes } from './billingSettings.js';
+import { couponRoutes } from './coupons.js';
+import { entitlementRoutes } from './entitlements.js';
+import { meterRoutes } from './meters.js';
+import { priceRoutes } from './prices.js';
+import { productRoutes } from './products.js';
+import { promotionCodeRoutes } from './promotionCodes.js';
+import { testClockRoutes } from './testClocks.js';
+export * from './billing.js';
+export * from './billingSettings.js';
+export * from './coupons.js';
+export * from './entitlements.js';
+export * from './meters.js';
+export * from './prices.js';
+export * from './products.js';
+export * from './promotionCodes.js';
+export * from './testClocks.js';
+// The request pieces every body naming an amount, an inline price or a filter reuses.
+export { baseUnitAmountParam, queryFlag, queryIdList } from './shared.js';
+/**
+ * The catalog (products, prices, coupons, promotion codes), entitlements, the
+ * billing engine's platform objects (test clocks, billing settings, meters)
+ * and the recurring billing transport (`/v1/billing/*`).
+ */
+export const catalogRoutes = [
+    ...productRoutes,
+    ...priceRoutes,
+    ...couponRoutes,
+    ...promotionCodeRoutes,
+    ...entitlementRoutes,
+    ...testClockRoutes,
+    ...billingSettingsRoutes,
+    ...meterRoutes,
+    ...billingRoutes,
+];