Assist_Design/packages/domain/sim/lifecycle.ts

/**
 * SIM Lifecycle Types
 *
 * Shared state definitions keep BFF workflow docs, frontend logic, and tests
 * aligned. Docs reference these exports instead of duplicating string literals.
 */

export const SIM_LIFECYCLE_STAGE = {
  CHECKOUT: "checkout",
  ORDER_PENDING_REVIEW: "order.pendingReview",
  ACTIVATION_PROCESSING: "activation.processing",
  ACTIVATION_FAILED_PAYMENT: "activation.failedPayment",
  ACTIVATION_PROVISIONING: "activation.provisioning",
  SERVICE_ACTIVE: "service.active",
  PLAN_CHANGE_SCHEDULED: "planChange.scheduled",
  PLAN_CHANGE_APPLIED: "planChange.applied",
  CANCELLATION_SCHEDULED: "cancellation.scheduled",
  SERVICE_CANCELLED: "service.cancelled",
} as const;

export type SimLifecycleStage = (typeof SIM_LIFECYCLE_STAGE)[keyof typeof SIM_LIFECYCLE_STAGE];

export const SIM_MANAGEMENT_ACTION = {
  TOP_UP_DATA: "topUpData",
  CHANGE_PLAN: "changePlan",
  UPDATE_FEATURES: "updateFeatures",
  CANCEL_SIM: "cancelSim",
  REISSUE_ESIM: "reissueEsim",
} as const;

export type SimManagementAction =
  (typeof SIM_MANAGEMENT_ACTION)[keyof typeof SIM_MANAGEMENT_ACTION];

export interface SimLifecycleTransition {
  action: string;
  from: SimLifecycleStage;
  to: SimLifecycleStage;
  description: string;
  blocking?: boolean;
}

export const SIM_ORDER_FLOW: SimLifecycleTransition[] = [
  {
    action: "checkout.createOrder",
    from: SIM_LIFECYCLE_STAGE.CHECKOUT,
    to: SIM_LIFECYCLE_STAGE.ORDER_PENDING_REVIEW,
    description: "Customer submits validated cart; Salesforce order enters Pending Review.",
    blocking: true,
  },
  {
    action: "orders.activateSim",
    from: SIM_LIFECYCLE_STAGE.ORDER_PENDING_REVIEW,
    to: SIM_LIFECYCLE_STAGE.ACTIVATION_PROCESSING,
    description: "Activation workflow begins (invoice + idempotent cache lock).",
    blocking: true,
  },
  {
    action: "payments.failure",
    from: SIM_LIFECYCLE_STAGE.ACTIVATION_PROCESSING,
    to: SIM_LIFECYCLE_STAGE.ACTIVATION_FAILED_PAYMENT,
    description: "WHMCS payment capture failed; invoice cancelled and user prompted to retry.",
    blocking: true,
  },
  {
    action: "payments.success",
    from: SIM_LIFECYCLE_STAGE.ACTIVATION_PROCESSING,
    to: SIM_LIFECYCLE_STAGE.ACTIVATION_PROVISIONING,
    description: "Payment succeeded; Freebit provisioning + add-ons run.",
  },
  {
    action: "provisioning.complete",
    from: SIM_LIFECYCLE_STAGE.ACTIVATION_PROVISIONING,
    to: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
    description: "Freebit activation finished; monthly WHMCS order scheduled for next month.",
  },
];

type ManagementFlow = Record<SimManagementAction, SimLifecycleTransition[]>;

export const SIM_MANAGEMENT_FLOW: ManagementFlow = {
  [SIM_MANAGEMENT_ACTION.TOP_UP_DATA]: [
    {
      action: SIM_MANAGEMENT_ACTION.TOP_UP_DATA,
      from: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      to: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      description: "One-time charge + Freebit quota increase; no state change.",
    },
  ],
  [SIM_MANAGEMENT_ACTION.CHANGE_PLAN]: [
    {
      action: SIM_MANAGEMENT_ACTION.CHANGE_PLAN,
      from: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      to: SIM_LIFECYCLE_STAGE.PLAN_CHANGE_SCHEDULED,
      description: "Freebit accepts plan change; SimScheduleService decides run date.",
    },
    {
      action: "planChange.applied",
      from: SIM_LIFECYCLE_STAGE.PLAN_CHANGE_SCHEDULED,
      to: SIM_LIFECYCLE_STAGE.PLAN_CHANGE_APPLIED,
      description: "Scheduled Freebit job applied (typically first day of next month).",
    },
    {
      action: "planChange.returnToActive",
      from: SIM_LIFECYCLE_STAGE.PLAN_CHANGE_APPLIED,
      to: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      description: "Service returns to active steady state with new plan code.",
    },
  ],
  [SIM_MANAGEMENT_ACTION.UPDATE_FEATURES]: [
    {
      action: SIM_MANAGEMENT_ACTION.UPDATE_FEATURES,
      from: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      to: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      description:
        "Immediate feature toggles. If networkType changes, a deferred queue job runs 30 minutes later.",
    },
  ],
  [SIM_MANAGEMENT_ACTION.CANCEL_SIM]: [
    {
      action: SIM_MANAGEMENT_ACTION.CANCEL_SIM,
      from: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      to: SIM_LIFECYCLE_STAGE.CANCELLATION_SCHEDULED,
      description: "Cancellation accepted; SimScheduleService defaults to first day of next month.",
    },
    {
      action: "cancellation.complete",
      from: SIM_LIFECYCLE_STAGE.CANCELLATION_SCHEDULED,
      to: SIM_LIFECYCLE_STAGE.SERVICE_CANCELLED,
      description: "Freebit executes scheduled cancellation; WHMCS/Freebit status synced.",
    },
  ],
  [SIM_MANAGEMENT_ACTION.REISSUE_ESIM]: [
    {
      action: SIM_MANAGEMENT_ACTION.REISSUE_ESIM,
      from: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      to: SIM_LIFECYCLE_STAGE.SERVICE_ACTIVE,
      description: "eSIM profile reissued; lifecycle state does not change.",
    },
  ],
};