@openlup/core 0.0.0 → 0.7.0

package/dist/subscription/cycleHardening.js

@@ -0,0 +1,118 @@
+/**
+ * Subscription cycle hardening helpers — the canonical retry ladder a renewal
+ * payment failure follows.
+ *
+ * This module is the SINGLE authority on the ladder. It answers four questions:
+ *
+ *   - `nextRetryAttemptAt(failedAt, attemptNumber, cadence?, failureClass?)` —
+ *     when the next charge is due, or `null` when no next charge is due.
+ *   - `shouldScheduleRetry(cycleStatus, attemptNumber, cadence?, failureClass?)`
+ *     — whether a failed payment may move into `retry_scheduled`.
+ *   - `ladderTerminatedByClass(failureClass, cadence?)` — whether the REASON for
+ *     the refusal, rather than the rung reached, ends the ladder.
+ *   - `isDunningLadderExhausted(cycle, cadence?)` — whether a refused cycle has
+ *     run past the last rung, the only non-payment reason to pause.
+ *
+ * TERMINATING, not capping. An attempt past the end of the ladder answers
+ * `null`, which is the pause signal; it does not answer "the last slot again".
+ * Callers therefore never need a `attempt <= maxRetryAttempts()` guard of their
+ * own — asking for the next slot IS the decision, and a second copy of the
+ * budget check is exactly how two rails drift apart.
+ *
+ * The cadence is injectable so a deployment can publish its own ladder, and the
+ * default is frozen so nobody can mutate the shipped one in place.
+ *
+ * All helpers are PURE — they never schedule local jobs, never touch payment
+ * adapters, never persist a cycle.
+ */
+import { PAYMENT_FAILURE_CLASSES, failureClassDecision, } from "../payment/paymentFailureTaxonomyContracts.js";
+/** @beta */
+export const DEFAULT_CYCLE_RETRY_CADENCE = Object.freeze({
+    backoffHours: Object.freeze([24, 72, 168]), // 1d, 3d, 7d
+    // ONE member. `hard_do_not_retry` is the taxonomy's statement that the issuer
+    // refused the INSTRUMENT rather than this charge, so no rung below can change
+    // the answer and three more attempts only promise the customer eleven days of
+    // charges that cannot land. Every other class keeps the full cadence. Its SQL
+    // twin is `v_terminating_classes` in the canonical apply body;
+    // scripts/retry-ladder-terminating-classes.test.ts reads that literal out of
+    // the latest declaring migration and fails if the two sets ever differ.
+    terminatingFailureClasses: Object.freeze(["hard_do_not_retry"]),
+});
+/**
+ * Whether the class of a refusal, rather than the rung it reached, ends the
+ * ladder.
+ *
+ * Fails OPEN in three separate ways, because a wrong `true` here withholds a
+ * charge the customer expected while a wrong `false` merely retries as before:
+ * an absent class does not terminate, a class the cadence does not list does not
+ * terminate, and a listed class the taxonomy does not recognise does not
+ * terminate. The last check is why a typo in configuration cannot stop a ladder.
+ *
+ * The final word belongs to {@link failureClassDecision}, not to the list: a
+ * cadence that lists a class the decision table still permits retrying is
+ * incoherent, and the table wins. That keeps the schedule from ever contradicting
+ * the kernel that already ruled on whether the instrument may be charged again.
+ *
+ * @beta
+ */
+export function ladderTerminatedByClass(failureClass, cadence = DEFAULT_CYCLE_RETRY_CADENCE) {
+    if (failureClass === null || failureClass === undefined)
+        return false;
+    if (!(cadence.terminatingFailureClasses ?? []).includes(failureClass))
+        return false;
+    if (!PAYMENT_FAILURE_CLASSES.includes(failureClass))
+        return false;
+    return !failureClassDecision(failureClass).retryAllowed;
+}
+/** @beta */
+export function nextRetryAttemptAt(failedAtIso, attemptNumber, cadence = DEFAULT_CYCLE_RETRY_CADENCE, failureClass) {
+    if (ladderTerminatedByClass(failureClass, cadence))
+        return null;
+    const hours = cadence.backoffHours[attemptNumber - 1];
+    // Covers both ends at once: an attempt below 1 and an attempt past the last
+    // ladder slot are equally "no next charge is due".
+    if (attemptNumber < 1 || hours === undefined)
+        return null;
+    const failedAt = new Date(failedAtIso);
+    if (Number.isNaN(failedAt.getTime()))
+        return null;
+    const next = new Date(failedAt.getTime() + hours * 60 * 60 * 1000);
+    return next.toISOString();
+}
+/** @beta */
+export function shouldScheduleRetry(cycleStatus, attemptNumber, cadence = DEFAULT_CYCLE_RETRY_CADENCE, failureClass) {
+    if (cycleStatus !== "payment_failed")
+        return false;
+    if (attemptNumber < 1)
+        return false;
+    // Asked and answered by the same predicate the schedule uses, so this helper
+    // cannot say "schedule one" about a refusal for which the ladder answers none.
+    if (ladderTerminatedByClass(failureClass, cadence))
+        return false;
+    return attemptNumber <= maxRetryAttempts(cadence);
+}
+/** @beta */
+export function maxRetryAttempts(cadence = DEFAULT_CYCLE_RETRY_CADENCE) {
+    return cadence.backoffHours.length;
+}
+/**
+ * Whether a refused cycle has EXHAUSTED the ladder: it failed, nothing is
+ * scheduled after it, and the attempt that failed sits past the last rung.
+ *
+ * This is the one condition under which the platform may pause a live
+ * subscription for non-payment. Both halves are required. An absent schedule on
+ * its own is not exhaustion: a class-terminated refusal on rung one also leaves
+ * nothing scheduled, and treating it as exhaustion would pause a subscription on
+ * the day of its first refusal. The rung is derived from the cadence, so pass
+ * the same cadence here and to `recordPaymentFailure`. The managed SQL dunning
+ * boundary spells the shipped ladder's rung as a fixed constant
+ * (`v_ladder_exhausted_from`, 4); a deployment that publishes a different
+ * ladder must move that constant with it.
+ *
+ * @beta
+ */
+export function isDunningLadderExhausted(cycle, cadence = DEFAULT_CYCLE_RETRY_CADENCE) {
+    return (cycle.status === "payment_failed" &&
+        cycle.nextRetryAt === null &&
+        cycle.retryAttempt > maxRetryAttempts(cadence));
+}

package/dist/subscription/index.d.ts

@@ -0,0 +1,14 @@
+/** @beta */
+export * from "./cycleHardening.js";
+/** @beta */
+export * from "./subscriptionEngineCore.js";
+/** @beta */
+export * from "./subscriptionEngineLifecycle.js";
+/** @beta */
+export * from "./subscriptionEnginePayment.js";
+/** @beta */
+export * from "./subscriptionEngineTypes.js";
+/** @beta */
+export * from "./subscriptionEngineUtils.js";
+/** @beta */
+export * from "./types.js";

package/dist/subscription/index.js

@@ -0,0 +1,14 @@
+/** @beta */
+export * from "./cycleHardening.js";
+/** @beta */
+export * from "./subscriptionEngineCore.js";
+/** @beta */
+export * from "./subscriptionEngineLifecycle.js";
+/** @beta */
+export * from "./subscriptionEnginePayment.js";
+/** @beta */
+export * from "./subscriptionEngineTypes.js";
+/** @beta */
+export * from "./subscriptionEngineUtils.js";
+/** @beta */
+export * from "./types.js";

package/dist/subscription/subscriptionEngineCore.d.ts

@@ -0,0 +1,13 @@
+import type { CreateInitialSubscriptionCheckoutInput, CycleMutationResult, EngineSubscription, InitialSubscriptionCheckoutModel, PlanCycleInput, SubscriptionEngineResult } from "./subscriptionEngineTypes.js";
+/** @beta */
+export declare function createInitialSubscriptionCheckoutModel(input: CreateInitialSubscriptionCheckoutInput): SubscriptionEngineResult<InitialSubscriptionCheckoutModel>;
+/** @beta */
+export declare function planSubscriptionCycle(input: PlanCycleInput): SubscriptionEngineResult<CycleMutationResult>;
+/** @beta */
+export declare function findDueSubscriptions(subscriptions: EngineSubscription[], nowIso: string): EngineSubscription[];
+/** @beta */
+export declare function isRenewalDue(subscription: EngineSubscription, nowIso: string): boolean;
+/** @beta */
+export declare function editCutoffAt(subscription: EngineSubscription): string | null;
+/** @beta */
+export declare function isEditWindowOpen(subscription: EngineSubscription, nowIso: string): boolean;

package/dist/subscription/subscriptionEngineCore.js

@@ -0,0 +1,145 @@
+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) {
+    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 = {
+        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) {
+    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 = 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, nowIso) {
+    return subscriptions.filter((subscription) => isRenewalDue(subscription, nowIso));
+}
+/** @beta */
+export function isRenewalDue(subscription, nowIso) {
+    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) {
+    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, nowIso) {
+    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/dist/subscription/subscriptionEngineLifecycle.d.ts

@@ -0,0 +1,150 @@
+import type { SubscriptionLineSnapshot, SubscriptionStatus } from "./types.js";
+import { type CycleRetryCadence } from "./cycleHardening.js";
+import type { EngineCycle, EngineSubscription, SubscriptionEngineResult, SubscriptionMutationResult } from "./subscriptionEngineTypes.js";
+/** @beta */
+export declare function swapTemplateLine(input: {
+    subscription: EngineSubscription;
+    fromVariantId: string;
+    toVariantId: string;
+    now: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/** @beta */
+export declare function addPermanentAddon(input: {
+    subscription: EngineSubscription;
+    line: Omit<SubscriptionLineSnapshot, "is_addon" | "sort_order"> & {
+        sort_order?: number;
+    };
+    now: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/** @beta */
+export declare function skipNextCycle(input: {
+    subscription: EngineSubscription;
+    now: string;
+    reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/** @beta */
+export declare function slideNextCycle(input: {
+    subscription: EngineSubscription;
+    newNextCycleAt: string;
+    now: string;
+    reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/** @beta */
+export declare function pauseSubscription(input: {
+    subscription: EngineSubscription;
+    now: string;
+    reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/** @beta */
+export declare function resumeSubscription(input: {
+    subscription: EngineSubscription;
+    now: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/** @beta */
+export declare function cancelSubscription(input: {
+    subscription: EngineSubscription;
+    now: string;
+    reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/** @beta */
+export declare function completeSubscription(input: {
+    subscription: EngineSubscription;
+    now: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/**
+ * 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 declare function reactivateSubscription(input: {
+    subscription: EngineSubscription;
+    now: string;
+    reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/**
+ * 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 declare function pauseSubscriptionForExpiredDunning(input: {
+    subscription: EngineSubscription;
+    cycle: EngineCycle;
+    now: string;
+    cadence?: CycleRetryCadence;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/**
+ * 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 declare function resumeSubscriptionFromExpiredDunning(input: {
+    subscription: EngineSubscription;
+    cycle: EngineCycle;
+    now: string;
+    paymentMethodRef?: string | null;
+    paymentMethodKind?: string | null;
+    cadence?: CycleRetryCadence;
+}): SubscriptionEngineResult<SubscriptionMutationResult & {
+    cycle: EngineCycle;
+}>;
+/**
+ * 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 declare const RESTART_LEAD_DAYS = 2;
+/**
+ * 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 declare const SUBSCRIPTION_STATUS_TRANSITIONS: Readonly<Record<SubscriptionStatus, readonly SubscriptionStatus[]>>;
+/** @beta */
+export declare function canTransitionSubscriptionStatus(from: SubscriptionStatus, to: SubscriptionStatus): boolean;