@openlup/core 0.0.0 → 0.6.0

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,52 @@
+import type { SubscriptionLineSnapshot } from "./types.js";
+import type { 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>;

package/dist/subscription/subscriptionEngineLifecycle.js

@@ -0,0 +1,196 @@
+import { isEditWindowOpen } from "./subscriptionEngineCore.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) {
+    return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {});
+}
+/** @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", {});
+}
+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) {
+    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, to) {
+    const transitions = {
+        active: ["paused", "cancelled", "completed"],
+        paused: ["active", "cancelled"],
+        cancelled: [],
+        completed: [],
+    };
+    return transitions[from].includes(to);
+}

package/dist/subscription/subscriptionEnginePayment.d.ts

@@ -0,0 +1,19 @@
+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;
+}): 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, undefined, 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";
+/** @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";