@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/semantics/subscription-schedules.js

@@ -0,0 +1,119 @@
+import { addBillingInterval, buildSubscriptionItemsList } from "../stripe-twin.js";
+import { at, created, fail, finder } from "./shared.js";
+import { storeItems } from "./subscriptions.js";
+const SS = 'subscription_schedule';
+const scheduleMissing = (ctx, id) => fail(ctx, `No such subscription_schedule: '${id}'`, 404, 'resource_missing');
+/** A schedule's phases as Stripe answers them (the served spec's subscription_schedule_phase_configuration): each
+ *  starts where the last ended (the first at the schedule's start_date, "now" or a timestamp), and ends at its
+ *  end_date or after its duration ("duration: interval, interval_count", the served spec's phases[] parameter) on the
+ *  calendar; its currency is its first price's, each item carries its price, quantity and (empty) discounts. Where the
+ *  documentation stops and the twin decides: a phase with neither lasts one interval of its first price. */
+function phasesOf(ctx, given, start) {
+    let cursor = start;
+    return given.map((p) => {
+        const items = (Array.isArray(p.items) ? p.items : []).map((it) => ({ price: it.price ?? null, quantity: Math.max(1, Math.trunc(Number(it.quantity) || 1)), discounts: [], metadata: {}, tax_rates: [], billing_thresholds: null }));
+        const price = typeof items[0]?.price === 'string' ? ctx.get('price', items[0].price) : undefined;
+        const recurring = price?.recurring ?? {};
+        const d = p.duration && typeof p.duration === 'object' ? p.duration : undefined;
+        const startDate = cursor;
+        const end = p.end_date !== undefined && p.end_date !== 'now' ? Number(p.end_date)
+            : d ? addBillingInterval(startDate, String(d.interval), Math.max(1, Number(d.interval_count) || 1))
+                : addBillingInterval(startDate, String(recurring.interval ?? 'month'), Math.max(1, Number(recurring.interval_count) || 1));
+        cursor = end;
+        return {
+            add_invoice_items: [], application_fee_percent: null, automatic_tax: { enabled: false, liability: null, disabled_reason: null }, billing_cycle_anchor: null,
+            billing_thresholds: null, collection_method: null, currency: String(price?.currency ?? 'usd'), default_payment_method: null, default_tax_rates: [],
+            description: null, discounts: [], end_date: end, invoice_settings: null, items, metadata: p.metadata && typeof p.metadata === 'object' ? p.metadata : {},
+            on_behalf_of: null, proration_behavior: typeof p.proration_behavior === 'string' ? p.proration_behavior : 'create_prorations', start_date: startDate,
+            transfer_data: null, trial_end: null,
+        };
+    });
+}
+// a schedule starts from a customer or from an existing subscription
+const create = async (ctx) => {
+    const params = ctx.params;
+    const customer = typeof params.customer === 'string' ? params.customer : '';
+    const fromSub = typeof params.from_subscription === 'string' ? params.from_subscription : '';
+    if (!customer && !fromSub)
+        return fail(ctx, 'Missing required param: customer (or from_subscription).', 400, 'parameter_missing');
+    if (customer && !ctx.get('customer', customer))
+        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
+    if (fromSub && !ctx.get('subscription', fromSub))
+        return fail(ctx, `No such subscription: '${fromSub}'`, 404, 'resource_missing');
+    // start_date is an instruction ("now" or when), not a field of the schedule
+    const start = params.start_date !== undefined && params.start_date !== 'now' ? Number(params.start_date) : Number(ctx.now());
+    const phases = phasesOf(ctx, Array.isArray(params.phases) ? params.phases : [], start);
+    const { phases: _p, start_date: _s, default_settings: givenDefaults, ...rest } = params;
+    const defaults = givenDefaults && typeof givenDefaults === 'object' ? givenDefaults : {};
+    const schedId = ctx.mint(SS);
+    // a schedule for a customer whose first phase starts now starts its subscription at once, on that phase's items
+    // (docs.stripe.com/billing/subscriptions/subscription-schedules#managing)
+    let subscription = fromSub || null;
+    if (!fromSub && phases.length) {
+        const now = Number(ctx.now());
+        const subId = ctx.mint('subscription');
+        const items = buildSubscriptionItemsList(phases[0].items, subId, now, finder(ctx));
+        await created(ctx, 'subscription', { customer, id: subId }, {
+            status: 'active', livemode: false, currency: 'usd', collection_method: String(params.default_settings?.collection_method ?? 'charge_automatically'),
+            cancel_at_period_end: false, start_date: now, billing_cycle_anchor: now, metadata: {}, discounts: [], billing_schedules: [],
+            trial_start: null, trial_end: null, current_period_start: now, current_period_end: phases[0].end_date, items, schedule: schedId,
+            automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' }, invoice_settings: { issuer: { type: 'self' } },
+        });
+        await storeItems(ctx, subId, items.data ?? []);
+        subscription = subId;
+    }
+    return ctx.reply(await created(ctx, SS, { ...rest, id: schedId }, {
+        status: 'active', livemode: false, phases, current_phase: phases.length ? { start_date: phases[0].start_date, end_date: phases[0].end_date } : null,
+        subscription, released_subscription: null, released_at: null,
+        canceled_at: null, completed_at: null, end_behavior: params.end_behavior ?? 'release',
+        renewal_interval: null, metadata: {}, billing_mode: { type: 'classic' },
+        // "billing_cycle_anchor: Possible values are phase_start or automatic" and invoice_settings are required (the
+        // served spec's default settings); the rest answer what the request set, else null
+        default_settings: {
+            application_fee_percent: defaults.application_fee_percent ?? null, automatic_tax: { enabled: false, liability: null, disabled_reason: null },
+            billing_cycle_anchor: typeof defaults.billing_cycle_anchor === 'string' ? defaults.billing_cycle_anchor : 'automatic', billing_thresholds: null,
+            collection_method: typeof defaults.collection_method === 'string' ? defaults.collection_method : 'charge_automatically', default_payment_method: defaults.default_payment_method ?? null,
+            description: defaults.description ?? null, invoice_settings: { account_tax_ids: null, days_until_due: null, issuer: { type: 'self' } }, on_behalf_of: null, transfer_data: null,
+        },
+        // a schedule made from a subscription is its customer's
+        customer: customer || String(ctx.get('subscription', fromSub)?.customer ?? ''),
+    }));
+};
+function end(kind) {
+    return async (ctx) => {
+        const id = at(ctx, 'schedule');
+        const sched = ctx.get(SS, id);
+        if (!sched)
+            return scheduleMissing(ctx, id);
+        const refused = ctx.legal(SS, 'status', kind === 'cancel' ? 'PostSubscriptionSchedulesScheduleCancel' : 'PostSubscriptionSchedulesScheduleRelease', sched.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const now = ctx.now();
+        const subId = typeof sched.subscription === 'string' ? sched.subscription : undefined;
+        const sub = subId ? ctx.get('subscription', subId) : undefined;
+        // "Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an
+        // active subscription)" (docs.stripe.com/api/subscription_schedules/cancel); releasing "will remove its subscription
+        // property and set the subscription's ID to the released_subscription property", leaving the subscription in place
+        // (docs.stripe.com/api/subscription_schedules/release)
+        if (kind === 'cancel' && subId && sub && sub.status !== 'canceled') {
+            ctx.legal('subscription', 'status', 'PostSubscriptionSchedulesScheduleCancel', String(sub.status), 'canceled', subId);
+            await ctx.write('subscription', subId, { status: 'canceled', canceled_at: now, ended_at: now }, 'subscription.cancel');
+        }
+        if (kind === 'release' && subId && sub)
+            await ctx.write('subscription', subId, { schedule: null }, 'subscription.update');
+        const fields = kind === 'cancel'
+            ? { status: 'canceled', canceled_at: now, current_phase: null }
+            : { status: 'released', released_at: now, released_subscription: subId ?? null, subscription: null, current_phase: null };
+        return ctx.reply(await ctx.write(SS, id, fields, `subscription_schedule.${kind}`));
+    };
+}
+const retrieve = async (ctx) => {
+    const s = ctx.get(SS, at(ctx, 'schedule'));
+    return s ? ctx.reply(s) : scheduleMissing(ctx, at(ctx, 'schedule'));
+};
+export const subscriptionSchedules = {
+    PostSubscriptionSchedules: create,
+    PostSubscriptionSchedulesScheduleCancel: end('cancel'),
+    PostSubscriptionSchedulesScheduleRelease: end('release'),
+    GetSubscriptionSchedulesSchedule: retrieve,
+};

package/dist/src/semantics/subscriptions.d.ts

@@ -0,0 +1,11 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** A `trial_end` Stripe refuses: the parameter is `"now" | timestamp` (docs.stripe.com/api/subscriptions/update), and a
+ *  timestamp that is not in the future answers "Invalid timestamp: must be an integer Unix timestamp in the future."
+ *  (Stripe's own message, as its SDKs' users report it: github.com/stripe/stripe-dotnet/issues/805,
+ *  github.com/stripe/stripe-ruby/issues/682). Where the documentation stops and the twin decides: a value that is no
+ *  number at all, and one more than two years on, answer that same message. */
+export declare function trialEndRefused(ctx: SemanticsContext, value: unknown, now: number): Response | undefined;
+/** A new subscription's items, each its own subscription_item as Stripe keeps it (/v1/subscription_items/{id}). */
+export declare function storeItems(ctx: SemanticsContext, subId: string, items: Row[]): Promise<void>;
+export declare const subscriptions: Record<string, Semantics>;