@volter/twin-stripe 0.1.1 → 2.0.0

package/src/semantics/subscription-schedules.ts

@@ -0,0 +1,129 @@
+// Subscription schedule semantics: a schedule drives a subscription through phases (items for a
+// duration). One made for a customer starts its subscription at once on the first phase's items. Cancel and
+// release end it, the machine's moves in ../manifest.ts. List and update are the derived core's.
+//
+// Where the documentation stops and the twin decides: the subscription a schedule starts raises no first invoice.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { addBillingInterval, buildSubscriptionItemsList } from '../stripe-twin.ts';
+import { at, created, fail, finder, type Row } from './shared.ts';
+import { storeItems } from './subscriptions.ts';
+
+const SS = 'subscription_schedule';
+const scheduleMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such subscription_schedule: '${id}'`, 404, 'resource_missing');
+
+type Interval = Parameters<typeof addBillingInterval>[1];
+
+/** 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: SemanticsContext, given: Row[], start: number): Row[] {
+  let cursor = start;
+  return given.map((p) => {
+    const items = (Array.isArray(p.items) ? (p.items as Row[]) : []).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 as string) : undefined;
+    const recurring = (price?.recurring as Row | undefined) ?? {};
+    const d = p.duration && typeof p.duration === 'object' ? (p.duration as Row) : undefined;
+    const startDate = cursor;
+    const end = p.end_date !== undefined && p.end_date !== 'now' ? Number(p.end_date)
+      : d ? addBillingInterval(startDate, String(d.interval) as Interval, Math.max(1, Number(d.interval_count) || 1))
+      : addBillingInterval(startDate, String(recurring.interval ?? 'month') as Interval, 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: Semantics = 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 as Row[]) : [], start);
+  const { phases: _p, start_date: _s, default_settings: givenDefaults, ...rest } = params;
+  const defaults = givenDefaults && typeof givenDefaults === 'object' ? (givenDefaults as Row) : {};
+  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 as Row[], subId, now, finder(ctx));
+    await created(ctx, 'subscription', { customer, id: subId }, {
+      status: 'active', livemode: false, currency: 'usd', collection_method: String((params.default_settings as Row | undefined)?.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 as Row[]) ?? []);
+    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 as string) ?? '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: 'cancel' | 'release'): Semantics {
+  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: Semantics = async (ctx) => {
+  const s = ctx.get(SS, at(ctx, 'schedule'));
+  return s ? ctx.reply(s) : scheduleMissing(ctx, at(ctx, 'schedule'));
+};
+
+export const subscriptionSchedules: Record<string, Semantics> = {
+  PostSubscriptionSchedules: create,
+  PostSubscriptionSchedulesScheduleCancel: end('cancel'),
+  PostSubscriptionSchedulesScheduleRelease: end('release'),
+  GetSubscriptionSchedulesSchedule: retrieve,
+};