@openlup/core 0.0.0 → 0.6.0

package/src/subscription/subscriptionEngineCore.ts

@@ -0,0 +1,181 @@
+import type { SubscriptionCycleStatus } from "./types.js";
+import type {
+  CreateInitialSubscriptionCheckoutInput,
+  CycleMutationResult,
+  EngineSubscription,
+  InitialSubscriptionCheckoutModel,
+  PlanCycleInput,
+  SubscriptionEngineResult,
+} from "./subscriptionEngineTypes.js";
+import { DEFAULT_EDIT_WINDOW_HOURS, DEFAULT_TIMEZONE } from "./subscriptionEngineTypes.js";
+import {
+  cloneRecord,
+  cloneTemplate,
+  failure,
+  makeEvent,
+  parseIso,
+  success,
+  validateTemplate,
+} from "./subscriptionEngineUtils.js";
+
+/** @beta */
+export function createInitialSubscriptionCheckoutModel(
+  input: CreateInitialSubscriptionCheckoutInput,
+): SubscriptionEngineResult<InitialSubscriptionCheckoutModel> {
+  const now = parseIso(input.now);
+  const firstCycleAt = parseIso(input.firstCycleAt);
+  if (!now || !firstCycleAt) {
+    return failure("invalid_timestamp", "now and firstCycleAt must be valid ISO timestamps");
+  }
+
+  const template = cloneTemplate(input.template);
+  const templateError = validateTemplate(template);
+  if (templateError) return templateError;
+
+  const subscription: EngineSubscription = {
+    id: input.subscriptionId,
+    clientRef: input.clientRef,
+    status: "active",
+    template,
+    templateVersion: 1,
+    nextCycleAt: firstCycleAt.toISOString(),
+    paymentMethodRef: input.paymentMethodRef ?? null,
+    paymentMethodKind: input.paymentMethodKind ?? null,
+    timezone: input.timezone ?? DEFAULT_TIMEZONE,
+    createdAt: now.toISOString(),
+    updatedAt: now.toISOString(),
+  };
+
+  const planned = planSubscriptionCycle({
+    subscription,
+    cycleNumber: 1,
+    now: now.toISOString(),
+    pricingSnapshot: input.pricingSnapshot,
+    idempotencyKey: input.idempotencyKey,
+  });
+  if (planned.ok === false) {
+    return failure(planned.error.code, planned.error.message);
+  }
+
+  return success({
+    subscription,
+    cycle: planned.value.cycle,
+    events: [
+      makeEvent({
+        eventType: "subscription.created",
+        subscription,
+        idempotencyKey: `${input.idempotencyKey}:subscription.created`,
+        occurredAt: now.toISOString(),
+        payload: { clientRef: input.clientRef, templateVersion: 1 },
+      }),
+      ...planned.value.events,
+    ],
+  });
+}
+
+/** @beta */
+export function planSubscriptionCycle(
+  input: PlanCycleInput,
+): SubscriptionEngineResult<CycleMutationResult> {
+  const now = parseIso(input.now);
+  const scheduledAt = parseIso(input.subscription.nextCycleAt);
+  if (!now || !scheduledAt) {
+    return failure("invalid_timestamp", "now and subscription.nextCycleAt must be valid ISO timestamps");
+  }
+
+  if (input.subscription.status !== "active") {
+    return failure("inactive_subscription", "only active subscriptions can generate cycles");
+  }
+
+  const templateSnapshot = cloneTemplate(input.subscription.template);
+  const hasPaymentMethod = Boolean(input.subscription.paymentMethodRef);
+  const status: SubscriptionCycleStatus = hasPaymentMethod ? "payment_pending" : "payment_failed";
+  const failureReason = hasPaymentMethod ? null : "missing_payment_method";
+
+  const cycle = {
+    subscriptionId: input.subscription.id,
+    cycleNumber: input.cycleNumber,
+    status,
+    scheduledAt: scheduledAt.toISOString(),
+    paidAt: null,
+    templateVersion: input.subscription.templateVersion,
+    templateSnapshot,
+    pricingSnapshot: cloneRecord(input.pricingSnapshot),
+    paymentMethodRef: input.subscription.paymentMethodRef,
+    retryAttempt: 0,
+    nextRetryAt: null,
+    failureReason,
+    engineIdempotencyKey: input.idempotencyKey,
+  };
+
+  const events = [
+    makeEvent({
+      eventType: "subscription.cycle_planned",
+      subscription: input.subscription,
+      cycleNumber: input.cycleNumber,
+      idempotencyKey: `${input.idempotencyKey}:cycle_planned`,
+      occurredAt: now.toISOString(),
+      payload: {
+        scheduledAt: cycle.scheduledAt,
+        templateVersion: cycle.templateVersion,
+      },
+    }),
+  ];
+
+  events.push(
+    hasPaymentMethod
+      ? makeEvent({
+          eventType: "subscription.payment_requested",
+          subscription: input.subscription,
+          cycleNumber: input.cycleNumber,
+          idempotencyKey: `${input.idempotencyKey}:payment_requested`,
+          occurredAt: now.toISOString(),
+          payload: { paymentMethodRef: input.subscription.paymentMethodRef },
+        })
+      : makeEvent({
+          eventType: "subscription.payment_failed",
+          subscription: input.subscription,
+          cycleNumber: input.cycleNumber,
+          idempotencyKey: `${input.idempotencyKey}:missing_payment_method`,
+          occurredAt: now.toISOString(),
+          payload: { reason: failureReason },
+        }),
+  );
+
+  return success({ cycle, events });
+}
+
+/** @beta */
+export function findDueSubscriptions(
+  subscriptions: EngineSubscription[],
+  nowIso: string,
+): EngineSubscription[] {
+  return subscriptions.filter((subscription) => isRenewalDue(subscription, nowIso));
+}
+
+/** @beta */
+export function isRenewalDue(subscription: EngineSubscription, nowIso: string): boolean {
+  if (subscription.status !== "active") return false;
+  const now = parseIso(nowIso);
+  const nextCycleAt = parseIso(subscription.nextCycleAt);
+  if (!now || !nextCycleAt) return false;
+  return nextCycleAt.getTime() <= now.getTime();
+}
+
+/** @beta */
+export function editCutoffAt(subscription: EngineSubscription): string | null {
+  const nextCycleAt = parseIso(subscription.nextCycleAt);
+  if (!nextCycleAt) return null;
+  const editWindowHours = subscription.template.edit_window_hours ?? DEFAULT_EDIT_WINDOW_HOURS;
+  return new Date(nextCycleAt.getTime() - editWindowHours * 60 * 60 * 1000).toISOString();
+}
+
+/** @beta */
+export function isEditWindowOpen(subscription: EngineSubscription, nowIso: string): boolean {
+  if (subscription.status !== "active") return false;
+  const now = parseIso(nowIso);
+  const cutoff = editCutoffAt(subscription);
+  const cutoffAt = cutoff ? parseIso(cutoff) : null;
+  if (!now || !cutoffAt) return false;
+  return now.getTime() < cutoffAt.getTime();
+}

package/src/subscription/subscriptionEngineLifecycle.ts

@@ -0,0 +1,282 @@
+import type { SubscriptionEngineEventType, SubscriptionLineSnapshot, SubscriptionStatus } from "./types.js";
+import { isEditWindowOpen } from "./subscriptionEngineCore.js";
+import type {
+  EngineSubscription,
+  SubscriptionEngineResult,
+  SubscriptionMutationResult,
+} from "./subscriptionEngineTypes.js";
+import {
+  addCadenceDays,
+  cloneTemplate,
+  failure,
+  makeEvent,
+  parseIso,
+  statusPatch,
+  success,
+  touchSubscription,
+  validateTemplate,
+} from "./subscriptionEngineUtils.js";
+
+/** @beta */
+export function swapTemplateLine(input: {
+  subscription: EngineSubscription;
+  fromVariantId: string;
+  toVariantId: string;
+  now: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  if (!isEditWindowOpen(input.subscription, input.now)) {
+    return failure("edit_window_closed", "template swaps are locked after the edit cutoff");
+  }
+
+  if (input.subscription.template.lines.some((line) => line.variant_id === input.toVariantId)) {
+    return failure("duplicate_line", "target variant is already present in the template");
+  }
+
+  let replaced = false;
+  const lines = input.subscription.template.lines.map((line) => {
+    if (line.variant_id !== input.fromVariantId) return { ...line };
+    replaced = true;
+    return { ...line, variant_id: input.toVariantId };
+  });
+
+  if (!replaced) {
+    return failure("line_not_found", "source variant is not present in the template");
+  }
+
+  return updateTemplate({
+    subscription: input.subscription,
+    template: { ...cloneTemplate(input.subscription.template), lines },
+    now: input.now,
+    eventType: "subscription.template_updated",
+    payload: { operation: "swap", fromVariantId: input.fromVariantId, toVariantId: input.toVariantId },
+  });
+}
+
+/** @beta */
+export function addPermanentAddon(input: {
+  subscription: EngineSubscription;
+  line: Omit<SubscriptionLineSnapshot, "is_addon" | "sort_order"> & { sort_order?: number };
+  now: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  if (!isEditWindowOpen(input.subscription, input.now)) {
+    return failure("edit_window_closed", "template add-ons are locked after the edit cutoff");
+  }
+
+  if (input.subscription.template.lines.some((line) => line.variant_id === input.line.variant_id)) {
+    return failure("duplicate_line", "add-on variant is already present in the template");
+  }
+
+  const nextSortOrder =
+    input.line.sort_order ??
+    Math.max(0, ...input.subscription.template.lines.map((line) => line.sort_order)) + 1;
+  const template = cloneTemplate(input.subscription.template);
+  template.lines = [
+    ...template.lines,
+    {
+      variant_id: input.line.variant_id,
+      qty: input.line.qty,
+      sort_order: nextSortOrder,
+      is_addon: true,
+    },
+  ];
+
+  return updateTemplate({
+    subscription: input.subscription,
+    template,
+    now: input.now,
+    eventType: "subscription.template_updated",
+    payload: { operation: "add_permanent_addon", variantId: input.line.variant_id },
+  });
+}
+
+/** @beta */
+export function skipNextCycle(input: {
+  subscription: EngineSubscription;
+  now: string;
+  reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  const now = parseIso(input.now);
+  if (!now) return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+  if (input.subscription.status !== "active") {
+    return failure("inactive_subscription", "only active subscriptions can skip cycles");
+  }
+
+  const nextCycleAt = addCadenceDays(input.subscription.nextCycleAt, input.subscription.template.cadence_days);
+  if (!nextCycleAt) return failure("invalid_timestamp", "subscription.nextCycleAt must be a valid ISO timestamp");
+
+  const subscription = touchSubscription(input.subscription, input.now, { nextCycleAt });
+
+  return success({
+    subscription,
+    events: [
+      makeEvent({
+        eventType: "subscription.cycle_skipped",
+        subscription: input.subscription,
+        idempotencyKey: `${input.subscription.id}:${input.subscription.nextCycleAt}:cycle_skipped`,
+        occurredAt: now.toISOString(),
+        payload: { skippedScheduledAt: input.subscription.nextCycleAt, reason: input.reason ?? null },
+      }),
+      makeEvent({
+        eventType: "subscription.next_cycle_at_updated",
+        subscription,
+        idempotencyKey: `${subscription.id}:${subscription.nextCycleAt}:next_cycle_at_updated`,
+        occurredAt: now.toISOString(),
+        payload: { nextCycleAt },
+      }),
+    ],
+  });
+}
+
+/** @beta */
+export function slideNextCycle(input: {
+  subscription: EngineSubscription;
+  newNextCycleAt: string;
+  now: string;
+  reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  const now = parseIso(input.now);
+  const newNextCycleAt = parseIso(input.newNextCycleAt);
+  if (!now || !newNextCycleAt) {
+    return failure("invalid_timestamp", "now and newNextCycleAt must be valid ISO timestamps");
+  }
+  if (input.subscription.status !== "active") {
+    return failure("inactive_subscription", "only active subscriptions can slide cycles");
+  }
+  if (newNextCycleAt.getTime() <= now.getTime()) {
+    return failure("invalid_slide_target", "newNextCycleAt must be in the future");
+  }
+
+  const subscription = touchSubscription(input.subscription, now.toISOString(), {
+    nextCycleAt: newNextCycleAt.toISOString(),
+  });
+
+  return success({
+    subscription,
+    events: [
+      makeEvent({
+        eventType: "subscription.next_cycle_at_updated",
+        subscription,
+        idempotencyKey: `${subscription.id}:${subscription.nextCycleAt}:slide`,
+        occurredAt: now.toISOString(),
+        payload: {
+          previousNextCycleAt: input.subscription.nextCycleAt,
+          nextCycleAt: subscription.nextCycleAt,
+          reason: input.reason ?? null,
+        },
+      }),
+    ],
+  });
+}
+
+/** @beta */
+export function pauseSubscription(input: {
+  subscription: EngineSubscription;
+  now: string;
+  reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  return changeSubscriptionStatus(input.subscription, "paused", input.now, "subscription.paused", {
+    reason: input.reason ?? null,
+  });
+}
+
+/** @beta */
+export function resumeSubscription(input: {
+  subscription: EngineSubscription;
+  now: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {});
+}
+
+/** @beta */
+export function cancelSubscription(input: {
+  subscription: EngineSubscription;
+  now: string;
+  reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  return changeSubscriptionStatus(input.subscription, "cancelled", input.now, "subscription.cancelled", {
+    reason: input.reason ?? null,
+  });
+}
+
+/** @beta */
+export function completeSubscription(input: {
+  subscription: EngineSubscription;
+  now: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  return changeSubscriptionStatus(input.subscription, "completed", input.now, "subscription.completed", {});
+}
+
+function updateTemplate(input: {
+  subscription: EngineSubscription;
+  template: EngineSubscription["template"];
+  now: string;
+  eventType: SubscriptionEngineEventType;
+  payload: Record<string, unknown>;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  const now = parseIso(input.now);
+  if (!now) return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+
+  const template = cloneTemplate(input.template);
+  const templateError = validateTemplate(template);
+  if (templateError) return templateError;
+
+  const subscription = touchSubscription(input.subscription, now.toISOString(), {
+    template,
+    templateVersion: input.subscription.templateVersion + 1,
+  });
+
+  return success({
+    subscription,
+    events: [
+      makeEvent({
+        eventType: input.eventType,
+        subscription,
+        idempotencyKey: `${subscription.id}:template:${subscription.templateVersion}`,
+        occurredAt: now.toISOString(),
+        payload: { ...input.payload, templateVersion: subscription.templateVersion },
+      }),
+    ],
+  });
+}
+
+function changeSubscriptionStatus(
+  subscription: EngineSubscription,
+  status: SubscriptionStatus,
+  nowIso: string,
+  eventType: SubscriptionEngineEventType,
+  payload: Record<string, unknown>,
+): SubscriptionEngineResult<SubscriptionMutationResult> {
+  const now = parseIso(nowIso);
+  if (!now) return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+  if (!canTransitionSubscriptionStatus(subscription.status, status)) {
+    return failure(
+      "invalid_transition",
+      `Cannot move subscription from ${subscription.status} to ${status}`,
+    );
+  }
+
+  const next = touchSubscription(subscription, now.toISOString(), statusPatch(status));
+  return success({
+    subscription: next,
+    events: [
+      makeEvent({
+        eventType,
+        subscription: next,
+        idempotencyKey: `${next.id}:${eventType}:${now.toISOString()}`,
+        occurredAt: now.toISOString(),
+        payload,
+      }),
+    ],
+  });
+}
+
+function canTransitionSubscriptionStatus(from: SubscriptionStatus, to: SubscriptionStatus): boolean {
+  const transitions: Record<SubscriptionStatus, readonly SubscriptionStatus[]> = {
+    active: ["paused", "cancelled", "completed"],
+    paused: ["active", "cancelled"],
+    cancelled: [],
+    completed: [],
+  };
+
+  return transitions[from].includes(to);
+}

package/src/subscription/subscriptionEnginePayment.ts

@@ -0,0 +1,174 @@
+import { nextRetryAttemptAt } from "./cycleHardening.js";
+import type { SubscriptionCycleStatus } from "./types.js";
+import type {
+  CycleMutationResult,
+  EngineCycle,
+  EngineEvent,
+  EngineSubscription,
+  SubscriptionEngineResult,
+} from "./subscriptionEngineTypes.js";
+import {
+  addCadenceDays,
+  failure,
+  isTerminalCycle,
+  makeEvent,
+  parseIso,
+  success,
+  touchSubscription,
+} from "./subscriptionEngineUtils.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** @beta */
+export function recordPaymentSuccess(input: {
+  subscription: EngineSubscription;
+  cycle: EngineCycle;
+  paidAt: string;
+  recordedAt: string;
+}): SubscriptionEngineResult<{
+  subscription: EngineSubscription;
+  cycle: EngineCycle;
+  events: EngineEvent[];
+}> {
+  const paidAt = parseIso(input.paidAt);
+  if (!paidAt) return failure("invalid_timestamp", "paidAt must be a valid ISO timestamp");
+  const recordedAt = parseIso(input.recordedAt);
+  if (!recordedAt) return failure("invalid_timestamp", "recordedAt must be a valid ISO timestamp");
+  if (isTerminalCycle(input.cycle)) {
+    return failure("terminal_cycle", "terminal cycles cannot be paid");
+  }
+
+  // The next cycle is one cadence past the CYCLE'S OWN scheduled instant, not past
+  // the moment the money arrived: a late payment must not silently shorten the
+  // interval the customer bought. The whole days the payment was late are then
+  // ADDED, because a delivery that arrives late shifts the whole subscription
+  // later rather than letting the next one stack up behind it.
+  //
+  // Lateness is measured to the EARLIER of the payment instant and the instant we
+  // recorded it, so a provider timestamp from the future cannot inflate the shift
+  // and push the next charge out past what the customer actually owes.
+  //
+  // ⛔ The outer Math.max is the load-bearing part and is NOT an optimisation.
+  // It is a monotonic clamp: `nextCycleAt` may only ever move LATER, never
+  // earlier. Without it, a replayed webhook, an out-of-order settlement, or a
+  // manual correction applied against an older cycle could compute an EARLIER
+  // instant and pull a charge forward into a window the subscriber has already
+  // been billed for — the one failure mode this rail must never have. The same
+  // clamp is spelled `GREATEST` in the SQL delivery-alignment rail for exactly
+  // this reason; the two are one rule with two spellings.
+  //
+  // `Date.parse(...) || 0` is deliberate rather than defensive noise: a
+  // subscription whose stored instant is unreadable clamps against the epoch,
+  // which yields the computed instant, instead of poisoning the whole expression
+  // with NaN and returning an invalid date. Cadence keeps its own call so its own
+  // validity guard still fires and still reports the right error, and `toJSON()`
+  // answers null past the representable range rather than throwing, which is why
+  // the shift is range-checked below instead of trusted.
+  const onTimeNextCycleAt = addCadenceDays(input.cycle.scheduledAt, input.cycle.templateSnapshot.cadence_days);
+  if (!onTimeNextCycleAt) return failure("invalid_timestamp", "cycle.scheduledAt must be a valid ISO timestamp");
+
+  const shiftedByDays = Math.max(0, Math.floor(
+    (Math.min(paidAt.getTime(), recordedAt.getTime()) - Date.parse(input.cycle.scheduledAt)) / DAY_MS,
+  ));
+  const nextCycleAt = new Date(Math.max(
+    Date.parse(input.subscription.nextCycleAt) || 0,
+    Date.parse(onTimeNextCycleAt) + shiftedByDays * DAY_MS,
+  )).toJSON();
+  if (!nextCycleAt) {
+    return failure("invalid_timestamp", "payment shift exceeds the supported timestamp range");
+  }
+  const paidAtIso = paidAt.toISOString();
+
+  const cycle: EngineCycle = {
+    ...input.cycle,
+    status: "paid",
+    paidAt: paidAtIso,
+    retryAttempt: input.cycle.retryAttempt,
+    nextRetryAt: null,
+    failureReason: null,
+  };
+  const subscription = touchSubscription(input.subscription, recordedAt.toISOString(), { nextCycleAt });
+
+  return success({
+    subscription,
+    cycle,
+    events: [
+      makeEvent({
+        eventType: "subscription.cycle_paid",
+        subscription,
+        cycleNumber: cycle.cycleNumber,
+        idempotencyKey: `${cycle.engineIdempotencyKey}:cycle_paid`,
+        occurredAt: paidAtIso,
+        payload: { paidAt: cycle.paidAt, nextCycleAt },
+      }),
+      makeEvent({
+        eventType: "subscription.next_cycle_at_updated",
+        subscription,
+        cycleNumber: cycle.cycleNumber,
+        idempotencyKey: `${cycle.engineIdempotencyKey}:next_cycle_at_updated`,
+        occurredAt: paidAtIso,
+        payload: {
+          nextCycleAt,
+          basedOnScheduledAt: cycle.scheduledAt,
+          basedOnPaidAt: cycle.paidAt,
+          shiftedByDays,
+        },
+      }),
+    ],
+  });
+}
+
+/** @beta */
+export function recordPaymentFailure(input: {
+  cycle: EngineCycle;
+  failedAt: string;
+  reason: string;
+  failureClass?: string | null;
+}): SubscriptionEngineResult<CycleMutationResult> {
+  const failedAt = parseIso(input.failedAt);
+  if (!failedAt) return failure("invalid_timestamp", "failedAt must be a valid ISO timestamp");
+  if (isTerminalCycle(input.cycle)) {
+    return failure("terminal_cycle", "terminal cycles cannot be retried");
+  }
+
+  const retryAttempt = input.cycle.retryAttempt + 1;
+  // The ladder owns its terminal decision.
+  const nextRetryAt = nextRetryAttemptAt(
+    failedAt.toISOString(),
+    retryAttempt,
+    undefined,
+    input.failureClass,
+  );
+  const status: SubscriptionCycleStatus = nextRetryAt ? "retry_scheduled" : "payment_failed";
+  const cycle: EngineCycle = {
+    ...input.cycle,
+    status,
+    retryAttempt,
+    nextRetryAt,
+    failureReason: input.reason,
+  };
+
+  const events: EngineEvent[] = [
+    {
+      eventType: "subscription.payment_failed",
+      subscriptionId: cycle.subscriptionId,
+      cycleNumber: cycle.cycleNumber,
+      idempotencyKey: `${cycle.engineIdempotencyKey}:payment_failed:${retryAttempt}`,
+      occurredAt: failedAt.toISOString(),
+      payload: { reason: input.reason, retryAttempt },
+    },
+  ];
+
+  if (nextRetryAt) {
+    events.push({
+      eventType: "subscription.retry_scheduled",
+      subscriptionId: cycle.subscriptionId,
+      cycleNumber: cycle.cycleNumber,
+      idempotencyKey: `${cycle.engineIdempotencyKey}:retry_scheduled:${retryAttempt}`,
+      occurredAt: failedAt.toISOString(),
+      payload: { nextRetryAt, retryAttempt },
+    });
+  }
+
+  return success({ cycle, events });
+}