@openlup/core 0.0.0 → 0.7.0

package/src/subscription/subscriptionEnginePayment.ts

@@ -0,0 +1,179 @@
+import { nextRetryAttemptAt, type CycleRetryCadence } 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;
+  /**
+   * The deployment's ladder. Pass the same cadence to
+   * `pauseSubscriptionForExpiredDunning` so both agree on exhaustion.
+   */
+  cadence?: CycleRetryCadence;
+}): 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,
+    input.cadence,
+    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 });
+}

package/src/subscription/subscriptionEngineTypes.ts

@@ -0,0 +1,114 @@
+import type {
+  SubscriptionCycleStatus,
+  SubscriptionEngineEventType,
+  SubscriptionStatus,
+  SubscriptionTemplateSnapshot,
+} from "./types.js";
+
+/** @beta */
+export const DEFAULT_EDIT_WINDOW_HOURS = 72;
+/** @beta */
+export 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/src/subscription/subscriptionEngineUtils.ts

@@ -0,0 +1,110 @@
+import type { SubscriptionEngineEventType, SubscriptionStatus } from "./types.js";
+import type {
+  EngineCycle,
+  EngineEvent,
+  EngineSubscription,
+  SubscriptionEngineErrorCode,
+  SubscriptionEngineResult,
+} from "./subscriptionEngineTypes.js";
+import type { SubscriptionTemplateSnapshot } from "./types.js";
+
+/** @beta */
+export function touchSubscription(
+  subscription: EngineSubscription,
+  updatedAt: string,
+  patch: Partial<EngineSubscription>,
+): EngineSubscription {
+  return {
+    ...subscription,
+    ...patch,
+    template: patch.template ? cloneTemplate(patch.template) : cloneTemplate(subscription.template),
+    updatedAt,
+  };
+}
+
+/** @beta */
+export function makeEvent(input: {
+  eventType: SubscriptionEngineEventType;
+  subscription: EngineSubscription;
+  cycleNumber?: number;
+  idempotencyKey: string;
+  occurredAt: string;
+  payload: Record<string, unknown>;
+}): EngineEvent {
+  return {
+    eventType: input.eventType,
+    subscriptionId: input.subscription.id,
+    cycleNumber: input.cycleNumber,
+    idempotencyKey: input.idempotencyKey,
+    occurredAt: input.occurredAt,
+    payload: input.payload,
+  };
+}
+
+/** @beta */
+export function addCadenceDays(iso: string, cadenceDays: number): string | null {
+  const date = parseIso(iso);
+  if (!date || cadenceDays < 1) return null;
+  return new Date(date.getTime() + cadenceDays * 24 * 60 * 60 * 1000).toJSON();
+}
+
+/** @beta */
+export function parseIso(iso: string): Date | null {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return null;
+  return date;
+}
+
+/** @beta */
+export function validateTemplate(
+  template: SubscriptionTemplateSnapshot,
+): SubscriptionEngineResult<never> | null {
+  if (template.cadence_days < 1 || template.lines.length === 0) {
+    return failure("invalid_template", "template must have a positive cadence and at least one line");
+  }
+
+  for (const line of template.lines) {
+    if (line.qty < 1) {
+      return failure("invalid_template", "template lines must have positive quantities");
+    }
+  }
+
+  return null;
+}
+
+/** @beta */
+export function isTerminalCycle(cycle: EngineCycle): boolean {
+  return cycle.status === "paid" || cycle.status === "skipped" || cycle.status === "cancelled";
+}
+
+/** @beta */
+export function cloneTemplate(template: SubscriptionTemplateSnapshot): SubscriptionTemplateSnapshot {
+  return {
+    ...template,
+    size_constraint: template.size_constraint ? cloneRecord(template.size_constraint) : null,
+    lines: template.lines.map((line) => ({ ...line })),
+  };
+}
+
+/** @beta */
+export function cloneRecord<T extends Record<string, unknown>>(record: T): T {
+  return JSON.parse(JSON.stringify(record)) as T;
+}
+
+/** @beta */
+export function success<T>(value: T): SubscriptionEngineResult<T> {
+  return { ok: true, value };
+}
+
+/** @beta */
+export function failure(
+  code: SubscriptionEngineErrorCode,
+  message: string,
+): SubscriptionEngineResult<never> {
+  return { ok: false, error: { code, message } };
+}
+
+/** @beta */
+export function statusPatch(status: SubscriptionStatus): Partial<EngineSubscription> {
+  return { status };
+}

package/src/subscription/types.ts

@@ -0,0 +1,104 @@
+/** @beta */
+export const SUBSCRIPTION_STATUSES = ["active", "paused", "cancelled", "completed"] as const;
+/** @beta */
+export type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];
+
+// Full set of `subscriptions.status` values persisted in the DB (see the
+// `subscriptions.status` CHECK constraint). This is a SUPERSET of the
+// engine-managed lifecycle states above: it also includes the activation-flow
+// states (`pending_activation`, `activation_failed`) that the recurring engine
+// never transitions between. Read/display contracts that echo a stored row MUST
+// accept all of these; the engine transition logic stays scoped to
+// SUBSCRIPTION_STATUSES.
+/** @beta */
+export const SUBSCRIPTION_RECORD_STATUSES = [
+  "pending_activation",
+  "active",
+  "paused",
+  "cancelled",
+  "completed",
+  "activation_failed",
+] as const;
+/** @beta */
+export type SubscriptionRecordStatus = (typeof SUBSCRIPTION_RECORD_STATUSES)[number];
+
+/** @beta */
+export const SUBSCRIPTION_CYCLE_STATUSES = [
+  "planned",
+  "payment_pending",
+  "paid",
+  "payment_failed",
+  "retry_scheduled",
+  "skipped",
+  "cancelled",
+] as const;
+/** @beta */
+export type SubscriptionCycleStatus = (typeof SUBSCRIPTION_CYCLE_STATUSES)[number];
+
+/** @beta */
+export const SUBSCRIPTION_ENGINE_EVENT_TYPES = [
+  "subscription.created",
+  "subscription.template_updated",
+  "subscription.edit_window_opened",
+  "subscription.next_cycle_at_updated",
+  "subscription.cycle_planned",
+  "subscription.payment_requested",
+  "subscription.payment_failed",
+  "subscription.retry_scheduled",
+  "subscription.payment_recovered",
+  "subscription.cycle_paid",
+  "subscription.cycle_skipped",
+  "subscription.cycle_cancelled",
+  "subscription.paused",
+  "subscription.resumed",
+  "subscription.cancelled",
+  "subscription.completed",
+] as const;
+/** @beta */
+export type SubscriptionEngineEventType = (typeof SUBSCRIPTION_ENGINE_EVENT_TYPES)[number];
+
+/** @beta */
+export interface SubscriptionLineSnapshot {
+  variant_id: string;
+  qty: number;
+  sort_order: number;
+  is_addon: boolean;
+}
+
+/** @beta */
+export interface SubscriptionTemplateSnapshot {
+  cadence_days: number;
+  size_constraint: Record<string, unknown> | null;
+  currency: string;
+  region_code: string;
+  edit_window_hours?: number | null;
+  lines: SubscriptionLineSnapshot[];
+}
+
+/** @beta */
+export interface SubscriptionEngineEvent {
+  event_id: string;
+  event_type: SubscriptionEngineEventType;
+  subscription_id: string;
+  cycle_number?: number;
+  template?: SubscriptionTemplateSnapshot;
+  next_cycle_at?: string;
+  payment_payload?: {
+    payment_id?: string;
+    amount_minor: number;
+    currency: string;
+    order_lines: Array<{
+      variant_id: string;
+      qty: number;
+      unit_price_minor: number;
+    }>;
+  };
+  raw_payload: Record<string, unknown>;
+}
+
+/** @beta */
+export interface CreateSubscriptionInput {
+  template: SubscriptionTemplateSnapshot;
+  client_ref: string;
+  payment_method_ref: string;
+}

package/src/testing.ts

@@ -0,0 +1,169 @@
+import {
+  PAYMENT_EXECUTION_ATTEMPT_STATUSES,
+  type PaymentExecutionBaseInput,
+  type PaymentExecutionBaseResult,
+} from "./payment/index.js";
+
+/** @internal */
+export type { PaymentExecutionBaseInput } from "./payment/index.js";
+
+/** @internal */
+export const neutralBrandFixture = {
+  displayName: "Example Store",
+  publicOrigin: "https://example.test",
+} as const;
+
+/** @internal */
+export const paymentExecutionBaseContractInput = {
+  idempotencyKey: "checkout-contract:payment-execution",
+  providerIdempotencyKey: "contract:example-pay:payment-intent-contract:checkout-payment-execution",
+  providerRequestFingerprint: "example-pay|payment-intent-contract|4200|USD|one_time|order_contract",
+  paymentIntentId: "11111111-1111-4111-8111-111111111111",
+  amountMinor: 4200,
+  currency: "USD",
+  mode: "one_time",
+} satisfies PaymentExecutionBaseInput;
+
+/** @internal */
+export type PaymentExecutionContractResult = PaymentExecutionBaseResult & {
+  rawProviderPayload?: Record<string, unknown> | null;
+};
+
+/** @internal */
+export type PaymentExecutionContractValidationIssueCode =
+  | "provider_mismatch"
+  | "invalid_provider_attempt_id"
+  | "invalid_provider_session_id"
+  | "invalid_attempt_status"
+  | "invalid_next_action_kind"
+  | "invalid_request_payload"
+  | "invalid_response_payload"
+  | "missing_provider_idempotency_key"
+  | "missing_provider_request_fingerprint"
+  | "sensitive_value_leaked";
+
+/** @internal */
+export interface PaymentExecutionContractValidationIssue {
+  code: PaymentExecutionContractValidationIssueCode;
+  message: string;
+  path: string;
+}
+
+/** @internal */
+export type PaymentExecutionContractValidationResult =
+  | { ok: true; issues: [] }
+  | { ok: false; issues: PaymentExecutionContractValidationIssue[] };
+
+/** @internal */
+export interface PaymentExecutionContractValidationInput<
+  TInput extends PaymentExecutionBaseInput = PaymentExecutionBaseInput,
+  TResult extends PaymentExecutionContractResult = PaymentExecutionContractResult,
+> {
+  input: TInput;
+  result: TResult;
+  expectedProvider: string;
+  allowedNextActionKinds?: readonly string[];
+  sensitiveValues?: readonly string[];
+}
+
+/** @internal */
+export function validatePaymentExecutionContractResult<
+  TInput extends PaymentExecutionBaseInput = PaymentExecutionBaseInput,
+  TResult extends PaymentExecutionContractResult = PaymentExecutionContractResult,
+>(
+  context: PaymentExecutionContractValidationInput<TInput, TResult>,
+): PaymentExecutionContractValidationResult {
+  const issues: PaymentExecutionContractValidationIssue[] = [];
+  const { input, result } = context;
+
+  if (result.provider !== context.expectedProvider) {
+    issues.push({
+      code: "provider_mismatch",
+      path: "provider",
+      message: `Expected provider ${context.expectedProvider}.`,
+    });
+  }
+  if (result.providerAttemptId !== null && typeof result.providerAttemptId !== "string") {
+    issues.push({
+      code: "invalid_provider_attempt_id",
+      path: "providerAttemptId",
+      message: "Expected providerAttemptId to be null or a string.",
+    });
+  }
+  if (result.providerSessionId !== null && typeof result.providerSessionId !== "string") {
+    issues.push({
+      code: "invalid_provider_session_id",
+      path: "providerSessionId",
+      message: "Expected providerSessionId to be null or a string.",
+    });
+  }
+  if (!PAYMENT_EXECUTION_ATTEMPT_STATUSES.includes(result.attemptStatus)) {
+    issues.push({
+      code: "invalid_attempt_status",
+      path: "attemptStatus",
+      message: "Expected attemptStatus to be a provider-execution attempt status.",
+    });
+  }
+  if (
+    result.nextActionKind !== null
+    && !(context.allowedNextActionKinds ?? []).includes(result.nextActionKind)
+  ) {
+    issues.push({
+      code: "invalid_next_action_kind",
+      path: "nextActionKind",
+      message: "Expected nextActionKind to be null or listed in allowedNextActionKinds.",
+    });
+  }
+
+  if (!isRecordPayload(result.requestPayload)) {
+    issues.push({
+      code: "invalid_request_payload",
+      path: "requestPayload",
+      message: "Expected requestPayload to be a non-array object.",
+    });
+  } else {
+    if (result.requestPayload.providerIdempotencyKey !== input.providerIdempotencyKey) {
+      issues.push({
+        code: "missing_provider_idempotency_key",
+        path: "requestPayload.providerIdempotencyKey",
+        message: "Expected requestPayload to persist providerIdempotencyKey.",
+      });
+    }
+    if (result.requestPayload.providerRequestFingerprint !== input.providerRequestFingerprint) {
+      issues.push({
+        code: "missing_provider_request_fingerprint",
+        path: "requestPayload.providerRequestFingerprint",
+        message: "Expected requestPayload to persist providerRequestFingerprint.",
+      });
+    }
+  }
+
+  if (!isRecordPayload(result.responsePayload)) {
+    issues.push({
+      code: "invalid_response_payload",
+      path: "responsePayload",
+      message: "Expected responsePayload to be a non-array object.",
+    });
+  }
+
+  const persistedPayloadJson = JSON.stringify({
+    requestPayload: result.requestPayload,
+    responsePayload: result.responsePayload,
+    rawProviderPayload: result.rawProviderPayload ?? null,
+  });
+  for (const sensitiveValue of context.sensitiveValues ?? []) {
+    if (persistedPayloadJson.includes(sensitiveValue)) {
+      issues.push({
+        code: "sensitive_value_leaked",
+        path: "requestPayload|responsePayload|rawProviderPayload",
+        message: "Expected persisted provider payloads not to contain sensitive values.",
+      });
+    }
+  }
+
+  return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
+}
+
+function isRecordPayload(payload: unknown): payload is Record<string, unknown> {
+  return Boolean(payload) && typeof payload === "object" && !Array.isArray(payload);
+}