@openlup/core 0.0.0 → 0.7.0

package/dist/subscription/subscriptionEngineLifecycle.js

@@ -0,0 +1,433 @@
+import { isEditWindowOpen } from "./subscriptionEngineCore.js";
+import { DEFAULT_CYCLE_RETRY_CADENCE, isDunningLadderExhausted, } from "./cycleHardening.js";
+import { addCadenceDays, cloneTemplate, failure, makeEvent, parseIso, statusPatch, success, touchSubscription, validateTemplate, } from "./subscriptionEngineUtils.js";
+/** @beta */
+export function swapTemplateLine(input) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return changeSubscriptionStatus(input.subscription, "paused", input.now, "subscription.paused", {
+        reason: input.reason ?? null,
+    });
+}
+/** @beta */
+export function resumeSubscription(input) {
+    // Resume leaves `paused` only. Leaving `cancelled` is a win-back and goes
+    // through reactivateSubscription, which re-arms the schedule. A subscription
+    // the exhausted ladder paused must resume through
+    // resumeSubscriptionFromExpiredDunning, which skips the uncollected cycle.
+    return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {}, ["paused"]);
+}
+/** @beta */
+export function cancelSubscription(input) {
+    return changeSubscriptionStatus(input.subscription, "cancelled", input.now, "subscription.cancelled", {
+        reason: input.reason ?? null,
+    });
+}
+/** @beta */
+export function completeSubscription(input) {
+    return changeSubscriptionStatus(input.subscription, "completed", input.now, "subscription.completed", {});
+}
+/**
+ * Win-back: the owner reactivates their own cancelled subscription.
+ *
+ * Mirrors the `cancelled -> active` edge of the managed SQL guard
+ * `public.subscription_guard_status_transition` and the customer `reactivate`
+ * action behind it. A reactivation charges again, so it needs a stored payment
+ * method, and it re-arms the next cycle {@link RESTART_LEAD_DAYS} out rather
+ * than leaving a stale instant that would make the renewal due immediately.
+ * The SQL action also clears the end instant and cancellation reason, requires
+ * the customer's confirmation of the charge timing, refuses while a cycle is
+ * locked and bumps the template version; those durable duties stay with the
+ * host.
+ *
+ * @beta
+ */
+export function reactivateSubscription(input) {
+    const now = parseIso(input.now);
+    if (!now)
+        return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+    if (input.subscription.status !== "cancelled") {
+        return failure("invalid_transition", `Cannot reactivate a subscription that is ${input.subscription.status}; only cancelled subscriptions can be won back`);
+    }
+    if (!input.subscription.paymentMethodRef) {
+        return failure("missing_payment_method", "reactivation requires a stored payment method");
+    }
+    const nextCycleAt = restartNextCycleAt(input.subscription, now);
+    if (!nextCycleAt)
+        return failure("invalid_timestamp", "restart exceeds the supported timestamp range");
+    return restart({
+        subscription: input.subscription,
+        now,
+        nextCycleAt,
+        idempotencyPrefix: `${input.subscription.id}:reactivated:${now.toISOString()}`,
+        payload: { reactivatedFrom: "cancelled", reason: input.reason ?? null },
+        leadingEvents: [],
+    });
+}
+/**
+ * The sanctioned non-payment rule: a cycle that exhausted the retry ladder
+ * pauses an ACTIVE subscription.
+ *
+ * This is the only path in the engine that suspends a live subscription for a
+ * reason the owner did not choose, and it fires only when
+ * {@link isDunningLadderExhausted} holds for the refused cycle. A ladder cut
+ * short by a terminating refusal class, or a failure on any rung that still has
+ * a retry after it, is refused as `dunning_not_exhausted` and leaves the
+ * subscription untouched. A subscription that is not active (already paused,
+ * cancelled or completed) is returned unchanged with no event, which is what
+ * the managed SQL dunning boundary does and what makes a replay harmless.
+ *
+ * The schedule is not touched: pausing never moves `nextCycleAt`.
+ *
+ * @beta
+ */
+export function pauseSubscriptionForExpiredDunning(input) {
+    const now = parseIso(input.now);
+    if (!now)
+        return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+    const mismatch = cycleOwnershipError(input.subscription, input.cycle);
+    if (mismatch)
+        return mismatch;
+    if (!isDunningLadderExhausted(input.cycle, input.cadence ?? DEFAULT_CYCLE_RETRY_CADENCE)) {
+        return failure("dunning_not_exhausted", "only a cycle that exhausted the retry ladder may pause a subscription for non-payment");
+    }
+    if (input.subscription.status !== "active") {
+        return success({ subscription: touchSubscription(input.subscription, input.subscription.updatedAt, {}), events: [] });
+    }
+    const subscription = touchSubscription(input.subscription, now.toISOString(), statusPatch("paused"));
+    return success({
+        subscription,
+        events: [
+            makeEvent({
+                eventType: "subscription.paused",
+                subscription,
+                cycleNumber: input.cycle.cycleNumber,
+                idempotencyKey: `${input.cycle.engineIdempotencyKey}:subscription_paused`,
+                occurredAt: now.toISOString(),
+                payload: {
+                    reason: "payment_failed_expired",
+                    retryAttempt: input.cycle.retryAttempt,
+                    failureReason: input.cycle.failureReason,
+                },
+            }),
+        ],
+    });
+}
+/**
+ * Customer-initiated recovery out of the non-payment pause.
+ *
+ * Mirrors the managed SQL `subscription_resume_after_expired_dunning`: the
+ * subscription must be paused and the cycle it passes must be the refused cycle
+ * that exhausted the ladder (the caller passes the LATEST such cycle, as the SQL
+ * boundary reads the latest dunning case). A new payment method, when given,
+ * replaces the stored one; without any method the resume is refused. Whether
+ * the method is chargeable unattended is the host's check, as it is in SQL.
+ * The given cycle becomes `skipped` rather than being charged late; the SQL
+ * boundary skips every uncollected cycle, so a host that holds more than one
+ * must skip the rest itself. The next cycle is re-armed
+ * {@link RESTART_LEAD_DAYS} out.
+ *
+ * @beta
+ */
+export function resumeSubscriptionFromExpiredDunning(input) {
+    const now = parseIso(input.now);
+    if (!now)
+        return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+    if (input.subscription.status !== "paused") {
+        return failure("invalid_transition", `Cannot resume a ${input.subscription.status} subscription from expired dunning; it must be paused`);
+    }
+    const mismatch = cycleOwnershipError(input.subscription, input.cycle);
+    if (mismatch)
+        return mismatch;
+    if (!isDunningLadderExhausted(input.cycle, input.cadence ?? DEFAULT_CYCLE_RETRY_CADENCE)) {
+        return failure("dunning_not_exhausted", "the cycle did not exhaust the retry ladder");
+    }
+    const replacementRef = input.paymentMethodRef?.trim() ? input.paymentMethodRef : null;
+    const method = replacementRef
+        ? {
+            paymentMethodRef: replacementRef,
+            paymentMethodKind: input.paymentMethodKind?.trim() || input.subscription.paymentMethodKind,
+        }
+        : {};
+    const withMethod = { ...input.subscription, ...method };
+    if (!withMethod.paymentMethodRef) {
+        return failure("missing_payment_method", "resuming requires a chargeable payment method");
+    }
+    const nextCycleAt = restartNextCycleAt(withMethod, now);
+    if (!nextCycleAt)
+        return failure("invalid_timestamp", "restart exceeds the supported timestamp range");
+    const cycle = { ...input.cycle, status: "skipped", nextRetryAt: null };
+    const restarted = restart({
+        subscription: withMethod,
+        now,
+        nextCycleAt,
+        idempotencyPrefix: `${input.cycle.engineIdempotencyKey}:resumed_after_expired_dunning`,
+        payload: {
+            resumedAfterExpiredDunning: true,
+            skippedCycleNumber: cycle.cycleNumber,
+        },
+        leadingEvents: [
+            makeEvent({
+                eventType: "subscription.cycle_skipped",
+                subscription: withMethod,
+                cycleNumber: cycle.cycleNumber,
+                idempotencyKey: `${input.cycle.engineIdempotencyKey}:cycle_skipped`,
+                occurredAt: now.toISOString(),
+                payload: {
+                    skippedScheduledAt: cycle.scheduledAt,
+                    reason: "subscription_resumed_after_expired_dunning",
+                },
+            }),
+        ],
+    });
+    if (restarted.ok === false)
+        return restarted;
+    return success({ ...restarted.value, cycle });
+}
+/**
+ * How far out a restarted subscription's next cycle is re-armed, in days. Both
+ * managed SQL restart paths (the customer `reactivate` action and
+ * `subscription_resume_after_expired_dunning`) spell it `interval '2 days'`.
+ *
+ * @beta
+ */
+export const RESTART_LEAD_DAYS = 2;
+function updateTemplate(input) {
+    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, status, nowIso, eventType, payload, allowedFrom) {
+    const now = parseIso(nowIso);
+    if (!now)
+        return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+    if ((allowedFrom !== undefined && !allowedFrom.includes(subscription.status)) ||
+        !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 restart(input) {
+    if (!canTransitionSubscriptionStatus(input.subscription.status, "active")) {
+        return failure("invalid_transition", `Cannot move subscription from ${input.subscription.status} to active`);
+    }
+    const occurredAt = input.now.toISOString();
+    const subscription = touchSubscription(input.subscription, occurredAt, {
+        ...statusPatch("active"),
+        nextCycleAt: input.nextCycleAt,
+    });
+    const events = [
+        ...input.leadingEvents,
+        makeEvent({
+            eventType: "subscription.resumed",
+            subscription,
+            idempotencyKey: `${input.idempotencyPrefix}:resumed`,
+            occurredAt,
+            payload: { ...input.payload, nextCycleAt: input.nextCycleAt },
+        }),
+    ];
+    if (input.nextCycleAt !== input.subscription.nextCycleAt) {
+        events.push(makeEvent({
+            eventType: "subscription.next_cycle_at_updated",
+            subscription,
+            idempotencyKey: `${input.idempotencyPrefix}:next_cycle_at_updated`,
+            occurredAt,
+            payload: { previousNextCycleAt: input.subscription.nextCycleAt, nextCycleAt: input.nextCycleAt },
+        }));
+    }
+    return success({ subscription, events });
+}
+// A restart re-arms the schedule RESTART_LEAD_DAYS out, but never earlier than
+// the instant already stored: the same monotonic clamp recordPaymentSuccess
+// applies, so a restart cannot pull a charge into a window already paid for.
+// The managed SQL restart paths assign `now + 2 days` without the clamp, so
+// the two differ exactly when the stored instant is later than that: a win-back
+// of a subscription paid through a later date, or a schedule skipped or slid
+// while the ladder was still running. There SQL charges earlier; this does not.
+function restartNextCycleAt(subscription, now) {
+    return new Date(Math.max(Date.parse(subscription.nextCycleAt) || 0, now.getTime() + RESTART_LEAD_DAYS * 24 * 60 * 60 * 1000)).toJSON();
+}
+function cycleOwnershipError(subscription, cycle) {
+    if (cycle.subscriptionId === subscription.id)
+        return null;
+    return failure("invalid_transition", "the cycle belongs to a different subscription");
+}
+/**
+ * The engine's subscription status matrix: every edge a status may take, and
+ * nothing else.
+ *
+ * It mirrors the managed SQL guard `public.subscription_guard_status_transition`
+ * over the four statuses the engine manages. The guard's remaining edges belong
+ * to the activation flow the engine never drives (`pending_activation` ->
+ * `active` / `activation_failed` / `cancelled`, and the audited expired-checkout
+ * reopen `cancelled` -> `pending_activation`). `completed` is terminal on both
+ * sides. `cancelled` -> `active` is the owner's win-back.
+ *
+ * Which OPERATION may take an edge is narrower than the matrix: `active` ->
+ * `paused` is the owner's pause or {@link pauseSubscriptionForExpiredDunning},
+ * and `cancelled` -> `active` is only {@link reactivateSubscription}.
+ *
+ * @beta
+ */
+export const SUBSCRIPTION_STATUS_TRANSITIONS = Object.freeze({
+    active: Object.freeze(["paused", "cancelled", "completed"]),
+    paused: Object.freeze(["active", "cancelled"]),
+    cancelled: Object.freeze(["active"]),
+    completed: Object.freeze([]),
+});
+/** @beta */
+export function canTransitionSubscriptionStatus(from, to) {
+    // Own keys only: a status read from storage is an untyped string, and
+    // "constructor" or "__proto__" must answer false rather than throw.
+    return Object.prototype.hasOwnProperty.call(SUBSCRIPTION_STATUS_TRANSITIONS, from) &&
+        SUBSCRIPTION_STATUS_TRANSITIONS[from].includes(to);
+}

package/dist/subscription/subscriptionEnginePayment.d.ts

@@ -0,0 +1,25 @@
+import { type CycleRetryCadence } from "./cycleHardening.js";
+import type { CycleMutationResult, EngineCycle, EngineEvent, EngineSubscription, SubscriptionEngineResult } from "./subscriptionEngineTypes.js";
+/** @beta */
+export declare function recordPaymentSuccess(input: {
+    subscription: EngineSubscription;
+    cycle: EngineCycle;
+    paidAt: string;
+    recordedAt: string;
+}): SubscriptionEngineResult<{
+    subscription: EngineSubscription;
+    cycle: EngineCycle;
+    events: EngineEvent[];
+}>;
+/** @beta */
+export declare function recordPaymentFailure(input: {
+    cycle: EngineCycle;
+    failedAt: string;
+    reason: string;
+    failureClass?: string | null;
+    /**
+     * The deployment's ladder. Pass the same cadence to
+     * `pauseSubscriptionForExpiredDunning` so both agree on exhaustion.
+     */
+    cadence?: CycleRetryCadence;
+}): SubscriptionEngineResult<CycleMutationResult>;

package/dist/subscription/subscriptionEnginePayment.js

@@ -0,0 +1,127 @@
+import { nextRetryAttemptAt } from "./cycleHardening.js";
+import { addCadenceDays, failure, isTerminalCycle, makeEvent, parseIso, success, touchSubscription, } from "./subscriptionEngineUtils.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** @beta */
+export function recordPaymentSuccess(input) {
+    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 = {
+        ...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) {
+    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, input.cadence, input.failureClass);
+    const status = nextRetryAt ? "retry_scheduled" : "payment_failed";
+    const cycle = {
+        ...input.cycle,
+        status,
+        retryAttempt,
+        nextRetryAt,
+        failureReason: input.reason,
+    };
+    const events = [
+        {
+            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 });
+}

package/dist/subscription/subscriptionEngineTypes.d.ts

@@ -0,0 +1,94 @@
+import type { SubscriptionCycleStatus, SubscriptionEngineEventType, SubscriptionStatus, SubscriptionTemplateSnapshot } from "./types.js";
+/** @beta */
+export declare const DEFAULT_EDIT_WINDOW_HOURS = 72;
+/** @beta */
+export declare const DEFAULT_TIMEZONE = "UTC";
+/** @beta */
+export type SubscriptionEngineErrorCode = "invalid_timestamp" | "invalid_template" | "inactive_subscription" | "edit_window_closed" | "line_not_found" | "duplicate_line" | "invalid_slide_target" | "invalid_transition" | "terminal_cycle" | "missing_payment_method" | "dunning_not_exhausted";
+/** @beta */
+export type SubscriptionEngineResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: SubscriptionEngineErrorCode;
+        message: string;
+    };
+};
+/** @beta */
+export interface EngineSubscription {
+    id: string;
+    clientRef: string;
+    status: SubscriptionStatus;
+    template: SubscriptionTemplateSnapshot;
+    templateVersion: number;
+    nextCycleAt: string;
+    paymentMethodRef: string | null;
+    paymentMethodKind: string | null;
+    timezone: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** @beta */
+export interface EngineCycle {
+    subscriptionId: string;
+    cycleNumber: number;
+    status: SubscriptionCycleStatus;
+    scheduledAt: string;
+    paidAt: string | null;
+    templateVersion: number;
+    templateSnapshot: SubscriptionTemplateSnapshot;
+    pricingSnapshot: Record<string, unknown>;
+    paymentMethodRef: string | null;
+    retryAttempt: number;
+    nextRetryAt: string | null;
+    failureReason: string | null;
+    engineIdempotencyKey: string;
+}
+/** @beta */
+export interface EngineEvent {
+    eventType: SubscriptionEngineEventType;
+    subscriptionId: string;
+    cycleNumber?: number;
+    idempotencyKey: string;
+    occurredAt: string;
+    payload: Record<string, unknown>;
+}
+/** @beta */
+export interface CreateInitialSubscriptionCheckoutInput {
+    subscriptionId: string;
+    clientRef: string;
+    template: SubscriptionTemplateSnapshot;
+    paymentMethodRef?: string | null;
+    paymentMethodKind?: string | null;
+    firstCycleAt: string;
+    now: string;
+    pricingSnapshot: Record<string, unknown>;
+    idempotencyKey: string;
+    timezone?: string | null;
+}
+/** @beta */
+export interface PlanCycleInput {
+    subscription: EngineSubscription;
+    cycleNumber: number;
+    now: string;
+    pricingSnapshot: Record<string, unknown>;
+    idempotencyKey: string;
+}
+/** @beta */
+export interface SubscriptionMutationResult {
+    subscription: EngineSubscription;
+    events: EngineEvent[];
+}
+/** @beta */
+export interface CycleMutationResult {
+    cycle: EngineCycle;
+    events: EngineEvent[];
+}
+/** @beta */
+export interface InitialSubscriptionCheckoutModel {
+    subscription: EngineSubscription;
+    cycle: EngineCycle;
+    events: EngineEvent[];
+}

package/dist/subscription/subscriptionEngineTypes.js

@@ -0,0 +1,4 @@
+/** @beta */
+export const DEFAULT_EDIT_WINDOW_HOURS = 72;
+/** @beta */
+export const DEFAULT_TIMEZONE = "UTC";