@openlup/core 0.0.0 → 0.6.0

package/src/subscription/subscriptionEngineTypes.ts

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