@incodetech/core 2.0.0-alpha.1 → 2.0.0-alpha.3

package/src/flow/orchestratedFlowManager.ts

@@ -1,231 +0,0 @@
-import {
-  type CreateApiOptions,
-  createActor,
-  createManager,
-  type ManagerSnapshot,
-} from '@incodetech/infra';
-import { getFlow as defaultGetFlow } from './flowServices';
-import type {
-  GetFlowFn,
-  ModuleRegistry,
-  OrchestratedFlowEvent,
-  OrchestratedFlowInput,
-  OrchestratedFlowMachine,
-} from './orchestratedFlowStateMachine';
-import { orchestratedFlowMachine } from './orchestratedFlowStateMachine';
-import type { Flow } from './types';
-
-type OrchestratedFlowSnapshot = ManagerSnapshot<OrchestratedFlowMachine>;
-
-type OrchestratedFlowIdleState = {
-  status: 'idle';
-};
-
-type OrchestratedFlowLoadingState = {
-  status: 'loading';
-};
-
-export type OrchestratedFlowReadyState = {
-  status: 'ready';
-  flow: Flow;
-  steps: string[];
-  currentStepIndex: number;
-  currentStep: string | undefined;
-  config: unknown;
-  moduleState: unknown;
-};
-
-export type OrchestratedFlowFinishedState = {
-  status: 'finished';
-  flow: Flow;
-  finishStatus: {
-    redirectionUrl: string;
-    action: 'approved' | 'rejected' | 'none';
-    scoreStatus:
-      | 'OK'
-      | 'WARN'
-      | 'MANUAL_OK'
-      | 'FAIL'
-      | 'UNKNOWN'
-      | 'MANUAL_FAIL';
-  };
-};
-
-type OrchestratedFlowErrorState = {
-  status: 'error';
-  error: string;
-};
-
-export type OrchestratedFlowState =
-  | OrchestratedFlowIdleState
-  | OrchestratedFlowLoadingState
-  | OrchestratedFlowReadyState
-  | OrchestratedFlowFinishedState
-  | OrchestratedFlowErrorState;
-
-function mapState(snapshot: OrchestratedFlowSnapshot): OrchestratedFlowState {
-  const { value, context } = snapshot;
-
-  switch (value) {
-    case 'idle':
-      return { status: 'idle' };
-    case 'loading':
-      return { status: 'loading' };
-    case 'runningModule': {
-      const childSnapshot = snapshot.children.currentModule?.getSnapshot();
-      return {
-        status: 'ready',
-        flow: context.flow ?? ({} as Flow),
-        steps: context.steps,
-        currentStepIndex: context.currentStepIndex,
-        currentStep: context.currentStep,
-        config: context.config,
-        moduleState: childSnapshot ?? null,
-      };
-    }
-    case 'finished':
-      return {
-        status: 'finished',
-        flow: context.flow ?? ({} as Flow),
-        finishStatus: context.finishStatus ?? {
-          redirectionUrl: '',
-          action: 'none',
-          scoreStatus: 'UNKNOWN',
-        },
-      };
-    case 'error':
-      return {
-        status: 'error',
-        error: context.error ?? 'Unknown error',
-      };
-    default:
-      return { status: 'idle' };
-  }
-}
-
-function createApi({
-  actor,
-  getSnapshot,
-}: CreateApiOptions<OrchestratedFlowMachine>) {
-  function getCanNext(): boolean {
-    const snapshot = getSnapshot();
-    const { currentStepIndex, steps } = snapshot.context;
-    return (
-      snapshot.value === 'runningModule' &&
-      currentStepIndex >= 0 &&
-      currentStepIndex < steps.length - 1
-    );
-  }
-
-  function getModuleConfig<T = unknown>(moduleKey: string): T | undefined {
-    const snapshot = getSnapshot();
-    if (snapshot.value !== 'runningModule') {
-      return undefined;
-    }
-    const mod = snapshot.context.flow?.flowModules.find(
-      (m) => m.key === moduleKey,
-    );
-    return mod?.configuration as T | undefined;
-  }
-
-  function isModuleEnabled(moduleKey: string): boolean {
-    const snapshot = getSnapshot();
-    if (snapshot.value !== 'runningModule') {
-      return false;
-    }
-    return !!snapshot.context.flow?.flowModules.some(
-      (m) => m.key === moduleKey,
-    );
-  }
-
-  return {
-    /**
-     * Start loading the flow configuration from the backend.
-     */
-    load() {
-      actor.send({ type: 'LOAD' });
-    },
-
-    /**
-     * Cancel an in-progress flow load.
-     */
-    cancel() {
-      actor.send({ type: 'CANCEL' });
-    },
-
-    /**
-     * Reset the flow to its initial idle state.
-     */
-    reset() {
-      actor.send({ type: 'RESET' });
-    },
-
-    /**
-     * Signal that the current module has completed successfully.
-     * Call this from your UI component's `onFinish` callback.
-     *
-     * @example
-     * ```tsx
-     * <Phone
-     *   config={config}
-     *   onFinish={() => flowManager.completeModule()}
-     * />
-     * ```
-     */
-    completeModule() {
-      actor.send({ type: 'MODULE_COMPLETE' });
-    },
-
-    /**
-     * Signal that the current module encountered an error.
-     * Call this from your UI component's `onError` callback if you want
-     * the flow to transition to an error state.
-     *
-     * @param error - Error message describing what went wrong
-     */
-    errorModule(error: string) {
-      actor.send({ type: 'MODULE_ERROR', error });
-    },
-
-    /**
-     * Send a raw event to the flow state machine.
-     * Prefer using the typed methods (completeModule, errorModule) when possible.
-     */
-    send(event: OrchestratedFlowEvent) {
-      actor.send(event);
-    },
-
-    get canNext() {
-      return getCanNext();
-    },
-
-    getModuleConfig,
-
-    isModuleEnabled,
-  };
-}
-
-export type CreateOrchestratedFlowActorOptions = {
-  getFlow?: GetFlowFn;
-  modules: ModuleRegistry;
-  getFinishStatus?: OrchestratedFlowInput['getFinishStatus'];
-};
-
-export function createOrchestratedFlowActor(
-  options: CreateOrchestratedFlowActorOptions,
-) {
-  const input: OrchestratedFlowInput = {
-    getFlow: options.getFlow ?? defaultGetFlow,
-    modules: options.modules,
-    getFinishStatus: options.getFinishStatus,
-  };
-
-  return createActor(orchestratedFlowMachine, { input }).start();
-}
-
-export function createOrchestratedFlowManager(
-  options: CreateOrchestratedFlowActorOptions,
-) {
-  const actor = createOrchestratedFlowActor(options);
-  return createManager({ actor, mapState, createApi });
-}

package/src/flow/orchestratedFlowStateMachine.test.ts

@@ -1,199 +0,0 @@
-import { createActor } from '@incodetech/infra';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { mockPhoneConfig } from '../phone/__mocks__/phoneMocks';
-import { phoneMachine } from '../phone/phoneStateMachine';
-import { createMockGetFlow, mockFlow } from './__mocks__/flowMocks';
-import { getFinishStatus } from './flowCompletionService';
-import { orchestratedFlowMachine } from './orchestratedFlowStateMachine';
-import type { FlowModule } from './types';
-
-vi.mock('./flowCompletionService', () => ({
-  getFinishStatus: vi.fn().mockResolvedValue({
-    redirectionUrl: 'https://example.com/success',
-    action: 'approved' as const,
-    scoreStatus: 'OK' as const,
-  }),
-}));
-
-vi.mock('../phone/phoneServices', () => ({
-  fetchPhone: vi.fn().mockResolvedValue({ phone: '+14155551234' }),
-  fetchStartInfo: vi.fn().mockResolvedValue({
-    ipIsoCode: 'US',
-    phonePrefix: '+1',
-    country: 'United States',
-  }),
-  addPhone: vi.fn().mockResolvedValue({ success: true }),
-  addPhoneInstantVerify: vi.fn().mockResolvedValue({ success: true }),
-  sendOtp: vi.fn().mockResolvedValue(undefined),
-  verifyOtp: vi.fn().mockResolvedValue({ success: true }),
-}));
-
-vi.mock('../events/addEvent', () => ({
-  addEvent: vi.fn().mockResolvedValue(undefined),
-}));
-
-describe('orchestratedFlowMachine', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  describe('Initial state', () => {
-    it('should start in idle state', () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(orchestratedFlowMachine, {
-        input: {
-          getFlow,
-          modules: { PHONE: phoneMachine },
-        },
-      }).start();
-
-      expect(actor.getSnapshot().value).toBe('idle');
-      actor.stop();
-    });
-  });
-
-  describe('Loading flow', () => {
-    it('should transition to loading when LOAD event is sent', () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(orchestratedFlowMachine, {
-        input: {
-          getFlow,
-          modules: { PHONE: phoneMachine },
-        },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-      expect(actor.getSnapshot().value).toBe('loading');
-      actor.stop();
-    });
-
-    it('should transition to runningModule when flow is loaded and module is registered', async () => {
-      const flowWithPhone: typeof mockFlow = {
-        ...mockFlow,
-        flowModules: [
-          {
-            key: 'PHONE',
-            configuration: mockPhoneConfig,
-          } as FlowModule,
-        ],
-      };
-      const getFlow = createMockGetFlow(flowWithPhone);
-      const actor = createActor(orchestratedFlowMachine, {
-        input: {
-          getFlow,
-          modules: { PHONE: phoneMachine },
-        },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        const snapshot = actor.getSnapshot();
-        expect(snapshot.value).toBe('runningModule');
-      });
-
-      const snapshot = actor.getSnapshot();
-      expect(snapshot.context.currentStep).toBe('PHONE');
-      actor.stop();
-    });
-
-    it('should transition to error when flow loading fails', async () => {
-      const getFlow = vi.fn().mockRejectedValue(new Error('Network error'));
-      const actor = createActor(orchestratedFlowMachine, {
-        input: {
-          getFlow,
-          modules: { PHONE: phoneMachine },
-        },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      const snapshot = actor.getSnapshot();
-      expect(snapshot.value).toBe('error');
-      expect(snapshot.context.error).toContain('Network error');
-      actor.stop();
-    });
-  });
-
-  describe('Module execution', () => {
-    it('should spawn child module when entering runningModule state', async () => {
-      const flowWithPhone: typeof mockFlow = {
-        ...mockFlow,
-        flowModules: [
-          {
-            key: 'PHONE',
-            configuration: mockPhoneConfig,
-          } as FlowModule,
-        ],
-      };
-      const getFlow = createMockGetFlow(flowWithPhone);
-      const actor = createActor(orchestratedFlowMachine, {
-        input: {
-          getFlow,
-          modules: { PHONE: phoneMachine },
-        },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        const snapshot = actor.getSnapshot();
-        expect(snapshot.value).toBe('runningModule');
-      });
-
-      const snapshot = actor.getSnapshot();
-      // biome-ignore lint/suspicious/noExplicitAny: XState doesn't expose child actor types well
-      const childActor = (snapshot.children as any)?.currentModule;
-      expect(childActor).toBeDefined();
-      actor.stop();
-    });
-
-    // Note: Event forwarding to dynamically spawned child actors is complex in XState v5.
-    // The orchestrated flow uses fromCallback to invoke child machines, which runs them
-    // independently. Direct event forwarding would require a different architecture.
-    // For now, we test that the child module runs and completes successfully.
-  });
-
-  describe('Flow completion', () => {
-    // Note: Testing full flow completion requires event forwarding to child actors,
-    // which is complex with the current fromCallback architecture.
-    // The MODULE_COMPLETE event handling is tested implicitly through integration tests.
-    // For now, we test that the machine correctly handles the MODULE_COMPLETE event.
-    it('should handle MODULE_COMPLETE event correctly', async () => {
-      const flowWithSingleModule: typeof mockFlow = {
-        ...mockFlow,
-        flowModules: [
-          {
-            key: 'PHONE',
-            configuration: mockPhoneConfig,
-          } as FlowModule,
-        ],
-      };
-
-      const getFlow = createMockGetFlow(flowWithSingleModule);
-      const actor = createActor(orchestratedFlowMachine, {
-        input: {
-          getFlow,
-          modules: { PHONE: phoneMachine },
-          getFinishStatus,
-        },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        const snapshot = actor.getSnapshot();
-        expect(snapshot.value).toBe('runningModule');
-      });
-
-      // Verify the machine is in runningModule state with correct context
-      const snapshot = actor.getSnapshot();
-      expect(snapshot.context.currentStep).toBe('PHONE');
-      expect(snapshot.context.currentStepIndex).toBe(0);
-
-      actor.stop();
-    });
-  });
-});