@peable.to/contracts 0.4.0 → 1.1.0

package/dist/cjs/resources/billingEngine/subscriptions.js

@@ -0,0 +1,476 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subscriptionRoutes = exports.listSubscriptionItemsQuery = exports.deleteSubscriptionItemParams = exports.updateSubscriptionItemParams = exports.createSubscriptionItemParams = exports.listSubscriptionsQuery = exports.resumeSubscriptionParams = exports.cancelSubscriptionParams = exports.updateSubscriptionParams = exports.createSubscriptionParams = exports.subscriptionSchema = exports.deletedSubscriptionItemSchema = exports.subscriptionItemSchema = exports.discountSchema = void 0;
+const zod_1 = require("zod");
+const objects_1 = require("../../common/objects");
+const envelopes_1 = require("../../common/envelopes");
+const objects_2 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+const subscriptions_1 = require("../../vocabulary/subscriptions");
+const params_2 = require("./params");
+/**
+ * Subscriptions (`sub_…`) and their items (`si_…`) — Orbit's native billing
+ * engine (ADR 0018 §1). Stripe's object model on Peable's wire (ADR 0014 D1):
+ * snake_case, Unix seconds, `livemode`, every amount a base-unit string.
+ */
+/** A discount applied to a subscription or an invoice. */
+exports.discountSchema = (0, objects_2.defineComponent)('Discount', zod_1.z
+    .object({
+    object: zod_1.z.literal('discount'),
+    coupon: zod_1.z.string().describe('The coupon applied.'),
+    promotion_code: zod_1.z
+        .string()
+        .nullable()
+        .describe('The promotion code (`promo_…`) it was redeemed through, if any.'),
+    start: primitives_1.unixSeconds.describe('When it started applying.'),
+    end: primitives_1.unixSeconds
+        .nullable()
+        .describe('When it stops (a `repeating` coupon); `null` for `once` and `forever`.'),
+})
+    .strict());
+/** One line of a subscription: a price and a quantity. */
+exports.subscriptionItemSchema = (0, objects_2.defineObject)('subscription_item', 'SubscriptionItem', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('subscription_item'),
+    livemode: primitives_1.livemode,
+    subscription: zod_1.z.string().describe('The subscription (`sub_…`) it belongs to.'),
+    price: (0, objects_1.embedded)('price', 'The Price, always embedded (Stripe’s shape).'),
+    quantity: zod_1.z.number().int().nonnegative(),
+    metadata: primitives_1.metadata,
+    created: primitives_1.unixSeconds,
+})
+    .strict());
+/** What `DELETE /v1/subscription_items/:id` answers. */
+exports.deletedSubscriptionItemSchema = (0, objects_2.defineComponent)('DeletedSubscriptionItem', (0, envelopes_1.deletedOf)('subscription_item'));
+exports.subscriptionSchema = (0, objects_2.defineObject)('subscription', 'Subscription', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('subscription'),
+    livemode: primitives_1.livemode,
+    customer: (0, objects_2.expandable)('customer', '`cus_…`, or the Customer with `expand[]=customer`.'),
+    status: zod_1.z.enum(subscriptions_1.SUBSCRIPTION_STATUSES),
+    currency: primitives_1.currency,
+    items: (0, envelopes_1.listOf)(exports.subscriptionItemSchema).describe('Every live item, on one page.'),
+    collection_method: zod_1.z.enum(subscriptions_1.COLLECTION_METHODS),
+    days_until_due: zod_1.z
+        .number()
+        .int()
+        .nullable()
+        .describe("`send_invoice` only: days from finalization to the invoice's due date."),
+    default_payment_method: (0, objects_2.expandable)('payment_method', '`pm_…`, or the PaymentMethod with `expand[]=default_payment_method`.').nullable(),
+    description: zod_1.z.string().nullable(),
+    billing_cycle_anchor: primitives_1.unixSeconds,
+    current_period_start: primitives_1.unixSeconds,
+    current_period_end: primitives_1.unixSeconds,
+    start_date: primitives_1.unixSeconds,
+    trial_start: primitives_1.unixSeconds.nullable(),
+    trial_end: primitives_1.unixSeconds.nullable(),
+    trial_settings: zod_1.z
+        .object({
+        end_behavior: zod_1.z.object({ missing_payment_method: zod_1.z.enum(subscriptions_1.TRIAL_END_BEHAVIORS) }).strict(),
+    })
+        .strict(),
+    cancel_at_period_end: zod_1.z.boolean(),
+    cancel_at: primitives_1.unixSeconds.nullable(),
+    canceled_at: primitives_1.unixSeconds.nullable(),
+    ended_at: primitives_1.unixSeconds.nullable(),
+    cancellation_details: zod_1.z
+        .object({
+        reason: zod_1.z.enum(subscriptions_1.SUBSCRIPTION_CANCELLATION_REASONS).nullable(),
+        comment: zod_1.z.string().nullable(),
+    })
+        .strict(),
+    pause_collection: zod_1.z
+        .object({
+        behavior: zod_1.z.enum(subscriptions_1.PAUSE_COLLECTION_BEHAVIORS),
+        resumes_at: primitives_1.unixSeconds.nullable(),
+    })
+        .strict()
+        .nullable(),
+    automatic_tax: zod_1.z.object({ enabled: zod_1.z.boolean() }).strict(),
+    discount: exports.discountSchema.nullable(),
+    latest_invoice: (0, objects_2.expandable)('invoice', '`in_…`, or the Invoice with `expand[]=latest_invoice`.').nullable(),
+    test_clock: zod_1.z
+        .string()
+        .nullable()
+        .describe('The test clock (`clock_…`) the customer is attached to; test mode only.'),
+    metadata: primitives_1.metadata,
+    created: primitives_1.unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'sub_0193b8f2c1a87d3e9f4a',
+            object: 'subscription',
+            livemode: false,
+            customer: 'cus_0193b8f2c1a87d3e9f4a',
+            status: 'active',
+            currency: 'EUR',
+            items: {
+                object: 'list',
+                data: [],
+                has_more: false,
+                url: '/v1/subscription_items?subscription=sub_0193b8f2c1a87d3e9f4a',
+            },
+            collection_method: 'charge_automatically',
+            days_until_due: null,
+            default_payment_method: 'pm_0193b8f2c1a87d3e9f4a',
+            description: null,
+            billing_cycle_anchor: 1793750400,
+            current_period_start: 1793750400,
+            current_period_end: 1796428800,
+            start_date: 1793750400,
+            trial_start: null,
+            trial_end: null,
+            trial_settings: { end_behavior: { missing_payment_method: 'create_invoice' } },
+            cancel_at_period_end: false,
+            cancel_at: null,
+            canceled_at: null,
+            ended_at: null,
+            cancellation_details: { reason: null, comment: null },
+            pause_collection: null,
+            automatic_tax: { enabled: false },
+            discount: null,
+            latest_invoice: 'in_0193b8f2c1a87d3e9f4a',
+            test_clock: null,
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+// ---- Requests ------------------------------------------------------------------------
+/** `trial_end`: Unix seconds, or `'now'` to end the trial at once. */
+const trialEndParam = zod_1.z.union([params_1.unixSecondsParam, zod_1.z.literal('now')]);
+/**
+ * An item's metadata in `items[]` of an update and on an item update: the
+ * named keys are set on the item (a merge, never an unset).
+ */
+const itemMetadataParam = zod_1.z.record(zod_1.z.string().max(40), zod_1.z.string().max(500));
+const createSubscriptionItemEntry = zod_1.z
+    .object({
+    price: params_1.idParam,
+    quantity: params_2.quantityParam.optional(),
+    metadata: params_1.metadataCreateParam.optional(),
+})
+    .strict();
+exports.createSubscriptionParams = zod_1.z
+    .object({
+    customer: params_1.idParam,
+    items: zod_1.z.array(createSubscriptionItemEntry).min(1).max(20),
+    default_payment_method: params_1.idParam.optional(),
+    collection_method: zod_1.z.enum(subscriptions_1.COLLECTION_METHODS).optional(),
+    days_until_due: params_2.daysUntilDueParam.optional(),
+    description: (0, params_2.shortText)(500).optional(),
+    trial_period_days: zod_1.z.number().int().min(1).max(730).optional(),
+    trial_end: trialEndParam.optional(),
+    trial_settings: zod_1.z
+        .object({
+        end_behavior: zod_1.z.object({ missing_payment_method: zod_1.z.enum(subscriptions_1.TRIAL_END_BEHAVIORS) }).strict(),
+    })
+        .strict()
+        .optional(),
+    billing_cycle_anchor: params_1.unixSecondsParam.optional(),
+    proration_behavior: zod_1.z.enum(subscriptions_1.CREATE_PRORATION_BEHAVIORS).optional(),
+    cancel_at_period_end: zod_1.z.boolean().optional(),
+    cancel_at: params_1.unixSecondsParam.optional(),
+    coupon: params_1.idParam.optional(),
+    promotion_code: params_1.idParam.optional(),
+    discounts: params_2.discountsParam.optional(),
+    payment_behavior: zod_1.z.enum(subscriptions_1.PAYMENT_BEHAVIORS).optional(),
+    automatic_tax: params_2.automaticTaxParam.optional(),
+    metadata: params_1.metadataCreateParam.optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+/** A subscription item as `items[]` of an update names it. */
+const updateSubscriptionItemEntry = zod_1.z
+    .object({
+    id: params_1.idParam.optional().describe('The `si_…` to change or remove; absent, a new item.'),
+    price: params_1.idParam.optional(),
+    quantity: params_2.quantityParam.optional(),
+    deleted: zod_1.z.boolean().optional().describe('Remove this item.'),
+    metadata: itemMetadataParam.optional(),
+})
+    .strict();
+/** A field sent as `""` is cleared; `metadata` is a patch. */
+exports.updateSubscriptionParams = zod_1.z
+    .object({
+    items: zod_1.z.array(updateSubscriptionItemEntry).min(1).max(20).optional(),
+    proration_behavior: zod_1.z.enum(subscriptions_1.PRORATION_BEHAVIORS).optional(),
+    proration_date: params_1.unixSecondsParam
+        .optional()
+        .describe('The instant prorations are computed at; defaults to now.'),
+    default_payment_method: zod_1.z.union([params_1.idParam, zod_1.z.literal('')]).optional(),
+    collection_method: zod_1.z.enum(subscriptions_1.COLLECTION_METHODS).optional(),
+    days_until_due: params_2.daysUntilDueParam.optional(),
+    description: zod_1.z.union([(0, params_2.shortText)(500), zod_1.z.literal('')]).optional(),
+    cancel_at_period_end: zod_1.z.boolean().optional(),
+    cancel_at: zod_1.z.union([params_1.unixSecondsParam, zod_1.z.literal('')]).optional(),
+    pause_collection: zod_1.z
+        .union([
+        zod_1.z
+            .object({
+            behavior: zod_1.z.enum(subscriptions_1.PAUSE_COLLECTION_BEHAVIORS),
+            resumes_at: params_1.unixSecondsParam.optional(),
+        })
+            .strict(),
+        zod_1.z.literal(''),
+    ])
+        .optional()
+        .describe('`""` resumes collection.'),
+    trial_end: trialEndParam.optional(),
+    coupon: zod_1.z.union([params_1.idParam, zod_1.z.literal('')]).optional(),
+    promotion_code: params_1.idParam.optional(),
+    discounts: zod_1.z.union([params_2.discountsParam, zod_1.z.literal('')]).optional(),
+    payment_behavior: zod_1.z.enum(subscriptions_1.PAYMENT_BEHAVIORS).optional(),
+    automatic_tax: params_2.automaticTaxParam.optional(),
+    metadata: params_1.metadataUpdateParam.optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+/** `DELETE /v1/subscriptions/:id`: cancel now. */
+exports.cancelSubscriptionParams = zod_1.z
+    .object({
+    invoice_now: zod_1.z
+        .boolean()
+        .optional()
+        .describe('Bill pending items and prorations now, in a final invoice.'),
+    prorate: zod_1.z.boolean().optional().describe('Credit the unused time of the current period.'),
+    cancellation_details: zod_1.z
+        .object({ comment: (0, params_2.shortText)(5000).optional() })
+        .strict()
+        .optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+/** `POST /v1/subscriptions/:id/resume` — a `paused` subscription. */
+exports.resumeSubscriptionParams = zod_1.z
+    .object({
+    billing_cycle_anchor: zod_1.z
+        .enum(subscriptions_1.RESUME_BILLING_CYCLE_ANCHORS)
+        .optional()
+        .describe('`now` (default) starts a new period at once; `unchanged` keeps the anchor.'),
+    proration_behavior: zod_1.z.enum(subscriptions_1.PRORATION_BEHAVIORS).optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+exports.listSubscriptionsQuery = (0, params_1.listQuery)({
+    customer: params_1.idParam.optional(),
+    price: params_1.idParam.optional(),
+    status: zod_1.z
+        .enum(subscriptions_1.SUBSCRIPTION_LIST_STATUSES)
+        .optional()
+        .describe('A status, `all` (including canceled), or `ended` (canceled and incomplete_expired).'),
+    test_clock: params_1.idParam.optional(),
+    current_period_end: params_1.rangeParam.optional(),
+});
+exports.createSubscriptionItemParams = zod_1.z
+    .object({
+    subscription: params_1.idParam,
+    price: params_1.idParam,
+    quantity: params_2.quantityParam.optional(),
+    proration_behavior: zod_1.z.enum(subscriptions_1.PRORATION_BEHAVIORS).optional(),
+    proration_date: params_1.unixSecondsParam.optional(),
+    metadata: params_1.metadataCreateParam.optional(),
+})
+    .strict();
+exports.updateSubscriptionItemParams = zod_1.z
+    .object({
+    price: params_1.idParam.optional(),
+    quantity: params_2.quantityParam.optional(),
+    proration_behavior: zod_1.z.enum(subscriptions_1.PRORATION_BEHAVIORS).optional(),
+    proration_date: params_1.unixSecondsParam.optional(),
+    metadata: itemMetadataParam.optional(),
+})
+    .strict();
+exports.deleteSubscriptionItemParams = zod_1.z
+    .object({
+    proration_behavior: zod_1.z.enum(subscriptions_1.PRORATION_BEHAVIORS).optional(),
+    proration_date: params_1.unixSecondsParam.optional(),
+})
+    .strict();
+/** `subscription` is REQUIRED: items are listed per subscription. */
+exports.listSubscriptionItemsQuery = (0, params_1.listQuery)({
+    subscription: params_1.idParam.describe('The subscription (`sub_…`) whose items to list.'),
+});
+// ---- Routes --------------------------------------------------------------------------
+const subscriptionId = { id: 'The subscription (`sub_…`).' };
+const itemId = { id: 'The subscription item (`si_…`).' };
+exports.subscriptionRoutes = [
+    (0, route_1.defineRoute)({
+        operationId: 'createSubscription',
+        method: 'post',
+        path: '/v1/subscriptions',
+        tag: 'Subscriptions',
+        summary: 'Create a subscription',
+        description: '`payment_behavior` decides what happens when the first invoice cannot be paid at once.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.createSubscriptionParams,
+        response: exports.subscriptionSchema,
+        sdk: 'subscriptions.create',
+        expandable: 'subscription',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listSubscriptions',
+        method: 'get',
+        path: '/v1/subscriptions',
+        tag: 'Subscriptions',
+        summary: 'List subscriptions',
+        description: 'Newest first. Without `status`, every subscription but the canceled ones.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: exports.listSubscriptionsQuery,
+        response: (0, envelopes_1.listOf)(exports.subscriptionSchema),
+        sdk: 'subscriptions.list',
+        expandable: 'subscription',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveSubscription',
+        method: 'get',
+        path: '/v1/subscriptions/{id}',
+        tag: 'Subscriptions',
+        summary: 'Retrieve a subscription',
+        auth: 'service',
+        scope: 'payments:read',
+        params: subscriptionId,
+        query: params_1.expandOnlyQuery,
+        response: exports.subscriptionSchema,
+        sdk: 'subscriptions.retrieve',
+        expandable: 'subscription',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'updateSubscription',
+        method: 'post',
+        path: '/v1/subscriptions/{id}',
+        tag: 'Subscriptions',
+        summary: 'Update a subscription',
+        description: 'Items, plan changes (prorated as `proration_behavior` says), collection, trial, cancellation at period end, pausing and discounts. A field sent as `""` is cleared; `metadata` is a patch.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: subscriptionId,
+        body: exports.updateSubscriptionParams,
+        response: exports.subscriptionSchema,
+        sdk: 'subscriptions.update',
+        expandable: 'subscription',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'cancelSubscription',
+        method: 'delete',
+        path: '/v1/subscriptions/{id}',
+        tag: 'Subscriptions',
+        summary: 'Cancel a subscription',
+        description: 'Now, optionally prorating the unused time and invoicing at once. Answers the canceled subscription.',
+        auth: 'service',
+        scope: 'payments:write',
+        params: subscriptionId,
+        body: exports.cancelSubscriptionParams,
+        response: exports.subscriptionSchema,
+        sdk: 'subscriptions.cancel',
+        expandable: 'subscription',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'resumeSubscription',
+        method: 'post',
+        path: '/v1/subscriptions/{id}/resume',
+        tag: 'Subscriptions',
+        summary: 'Resume a paused subscription',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: subscriptionId,
+        body: exports.resumeSubscriptionParams,
+        response: exports.subscriptionSchema,
+        sdk: 'subscriptions.resume',
+        expandable: 'subscription',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'searchSubscriptions',
+        method: 'get',
+        path: '/v1/subscriptions/search',
+        tag: 'Subscriptions',
+        summary: 'Search subscriptions',
+        description: "Stripe's query language over the subscription's fields and `metadata['key']`.",
+        auth: 'service',
+        scope: 'payments:read',
+        query: params_1.searchQuery,
+        response: (0, envelopes_1.searchResultOf)(exports.subscriptionSchema),
+        sdk: 'subscriptions.search',
+        expandable: 'subscription',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'createSubscriptionItem',
+        method: 'post',
+        path: '/v1/subscription_items',
+        tag: 'Subscription items',
+        summary: 'Add an item to a subscription',
+        description: 'Prorated as `proration_behavior` says.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.createSubscriptionItemParams,
+        response: exports.subscriptionItemSchema,
+        sdk: 'subscriptionItems.create',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listSubscriptionItems',
+        method: 'get',
+        path: '/v1/subscription_items',
+        tag: 'Subscription items',
+        summary: "List a subscription's items",
+        auth: 'service',
+        scope: 'payments:read',
+        query: exports.listSubscriptionItemsQuery,
+        response: (0, envelopes_1.listOf)(exports.subscriptionItemSchema),
+        sdk: 'subscriptionItems.list',
+        expandable: 'subscription_item',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveSubscriptionItem',
+        method: 'get',
+        path: '/v1/subscription_items/{id}',
+        tag: 'Subscription items',
+        summary: 'Retrieve a subscription item',
+        auth: 'service',
+        scope: 'payments:read',
+        params: itemId,
+        query: params_1.expandOnlyQuery,
+        response: exports.subscriptionItemSchema,
+        sdk: 'subscriptionItems.retrieve',
+        expandable: 'subscription_item',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'updateSubscriptionItem',
+        method: 'post',
+        path: '/v1/subscription_items/{id}',
+        tag: 'Subscription items',
+        summary: 'Update a subscription item',
+        description: 'Its price or quantity, prorated as `proration_behavior` says.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: itemId,
+        body: exports.updateSubscriptionItemParams,
+        response: exports.subscriptionItemSchema,
+        sdk: 'subscriptionItems.update',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'deleteSubscriptionItem',
+        method: 'delete',
+        path: '/v1/subscription_items/{id}',
+        tag: 'Subscription items',
+        summary: 'Remove an item from a subscription',
+        description: 'Prorated as `proration_behavior` says.',
+        auth: 'service',
+        scope: 'payments:write',
+        params: itemId,
+        body: exports.deleteSubscriptionItemParams,
+        response: exports.deletedSubscriptionItemSchema,
+        sdk: 'subscriptionItems.del',
+    }),
+];