@incodetech/core 2.0.0-alpha.1

package/src/flow/orchestratedFlowStateMachine.ts

@@ -0,0 +1,325 @@
+import {
+  type AnyStateMachine,
+  assign,
+  createActor,
+  fromCallback,
+  fromPromise,
+  setup,
+} from '@incodetech/infra';
+import {
+  type GetFinishStatusFn,
+  getFinishStatus,
+} from './flowCompletionService';
+import type { Flow } from './types';
+
+export type GetFlowFn = (signal: AbortSignal) => Promise<Flow>;
+
+export type ModuleRegistry = {
+  PHONE?: AnyStateMachine;
+  EMAIL?: AnyStateMachine;
+  SELFIE?: AnyStateMachine;
+  [key: string]: AnyStateMachine | undefined;
+};
+
+export type OrchestratedFlowInput = {
+  getFlow: GetFlowFn;
+  modules: ModuleRegistry;
+  getFinishStatus?: GetFinishStatusFn;
+};
+
+export type OrchestratedFlowContext = {
+  flow: Flow | undefined;
+  error: string | undefined;
+  steps: string[];
+  currentStepIndex: number;
+  currentStep: string | undefined;
+  config: unknown;
+  getFlow: GetFlowFn;
+  registeredModules: ModuleRegistry;
+  getFinishStatus: GetFinishStatusFn;
+  finishStatus:
+    | {
+        redirectionUrl: string;
+        action: 'approved' | 'rejected' | 'none';
+        scoreStatus:
+          | 'OK'
+          | 'WARN'
+          | 'MANUAL_OK'
+          | 'FAIL'
+          | 'UNKNOWN'
+          | 'MANUAL_FAIL';
+      }
+    | undefined;
+};
+
+export type OrchestratedFlowEvent =
+  | { type: 'LOAD' }
+  | { type: 'CANCEL' }
+  | { type: 'RESET' }
+  | { type: 'MODULE_COMPLETE' }
+  | { type: '*'; [key: string]: unknown }
+  | { type: string; [key: string]: unknown };
+
+export const orchestratedFlowMachine = setup({
+  types: {
+    context: {} as OrchestratedFlowContext,
+    events: {} as OrchestratedFlowEvent,
+    input: {} as OrchestratedFlowInput,
+  },
+  actors: {
+    fetchFlow: fromPromise<Flow, { getFlow: GetFlowFn }>(
+      async ({ input, signal }) => {
+        return input.getFlow(signal);
+      },
+    ),
+    notifyBackend: fromPromise<
+      OrchestratedFlowContext['finishStatus'],
+      { getFinishStatus: GetFinishStatusFn; flowId: string | undefined }
+    >(async ({ input, signal }) => {
+      const result = await input.getFinishStatus(input.flowId, signal);
+      return result;
+    }),
+    runChildModule: fromCallback<
+      { type: 'MODULE_COMPLETE' } | { type: 'MODULE_ERROR'; error: unknown },
+      { machine: AnyStateMachine; config: unknown }
+    >(({ sendBack, input }) => {
+      const { machine, config } = input;
+
+      // Create and start the child actor
+      const actor = createActor(machine, { input: { config } });
+
+      // Subscribe to state changes
+      const subscription = actor.subscribe({
+        complete: () => {
+          sendBack({ type: 'MODULE_COMPLETE' });
+        },
+        error: (err) => {
+          sendBack({ type: 'MODULE_ERROR', error: err });
+        },
+      });
+
+      actor.start();
+
+      // Return cleanup function
+      return () => {
+        subscription.unsubscribe();
+        actor.stop();
+      };
+    }),
+  },
+  actions: {
+    resetContext: assign(({ context }) => ({
+      flow: undefined,
+      error: undefined,
+      steps: [],
+      currentStepIndex: -1,
+      currentStep: undefined,
+      config: undefined,
+      getFlow: context.getFlow,
+      registeredModules: context.registeredModules,
+      getFinishStatus: context.getFinishStatus,
+      finishStatus: undefined,
+    })),
+    setFlowData: assign(({ event }) => {
+      const flow = (event as unknown as { output: Flow }).output;
+      return {
+        flow,
+        steps: (flow.flowModules ?? []).map((m) => m.key),
+        currentStepIndex: (flow.flowModules ?? []).length > 0 ? 0 : -1,
+        currentStep: flow.flowModules?.[0]?.key,
+        config: flow.flowModules?.[0]?.configuration,
+      };
+    }),
+    setError: assign(({ event }) => ({
+      error: String((event as unknown as { error: unknown }).error),
+    })),
+    incrementStep: assign(({ context }) => {
+      const nextIndex = context.currentStepIndex + 1;
+      const module = context.flow?.flowModules?.[nextIndex];
+      return {
+        currentStepIndex: nextIndex,
+        currentStep: module?.key,
+        config: module?.configuration,
+      };
+    }),
+    setFinishStatus: assign(({ event }) => ({
+      finishStatus: (
+        event as unknown as { output: OrchestratedFlowContext['finishStatus'] }
+      ).output,
+    })),
+  },
+  guards: {
+    isLastStep: ({ context }) =>
+      context.currentStepIndex >= 0 &&
+      context.currentStepIndex === context.steps.length - 1,
+    canGoNext: ({ context }) =>
+      context.currentStepIndex >= 0 &&
+      context.currentStepIndex < context.steps.length - 1,
+    hasModule: ({ context, event }) => {
+      // Guard runs before action, so check event output instead of context
+      if (!('output' in event)) return false;
+      const flow = (event as unknown as { output: Flow }).output;
+      const firstModuleKey = flow.flowModules?.[0]?.key;
+      if (!firstModuleKey) return false;
+      return context.registeredModules[firstModuleKey] != null;
+    },
+  },
+}).createMachine({
+  id: 'orchestratedFlow',
+  initial: 'idle',
+  context: ({ input }) => ({
+    flow: undefined,
+    error: undefined,
+    steps: [],
+    currentStepIndex: -1,
+    currentStep: undefined,
+    config: undefined,
+    getFlow: input.getFlow,
+    registeredModules: input.modules,
+    getFinishStatus: input.getFinishStatus ?? getFinishStatus,
+    finishStatus: undefined,
+  }),
+  states: {
+    idle: {
+      on: {
+        LOAD: {
+          target: 'loading',
+          actions: 'resetContext',
+        },
+      },
+    },
+
+    loading: {
+      invoke: {
+        id: 'fetchFlow',
+        src: 'fetchFlow',
+        input: ({ context }) => ({
+          getFlow: context.getFlow,
+        }),
+        onDone: [
+          {
+            target: 'runningModule',
+            guard: 'hasModule',
+            actions: 'setFlowData',
+          },
+          {
+            target: 'error',
+            actions: assign({
+              error: () => 'No registered module found for flow',
+            }),
+          },
+        ],
+        onError: {
+          target: 'error',
+          actions: 'setError',
+        },
+      },
+      on: {
+        CANCEL: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+
+    runningModule: {
+      invoke: {
+        id: 'currentModule',
+        src: 'runChildModule',
+        input: ({ context }: { context: OrchestratedFlowContext }) => {
+          if (!context.currentStep) {
+            throw new Error('No current step');
+          }
+          const machine = context.registeredModules[context.currentStep];
+          if (!machine) {
+            throw new Error(`Module ${context.currentStep} not registered`);
+          }
+          return { machine, config: context.config };
+        },
+        onDone: [
+          {
+            target: 'completing',
+            guard: 'isLastStep',
+          },
+          {
+            target: 'runningModule',
+            actions: 'incrementStep',
+            reenter: true,
+          },
+        ],
+        onError: {
+          target: 'error',
+          actions: 'setError',
+        },
+      },
+      on: {
+        MODULE_COMPLETE: [
+          {
+            target: 'completing',
+            guard: 'isLastStep',
+          },
+          {
+            target: 'runningModule',
+            actions: 'incrementStep',
+            reenter: true,
+          },
+        ],
+        MODULE_ERROR: {
+          target: 'error',
+          actions: assign(({ event }) => ({
+            error: String((event as unknown as { error: unknown }).error),
+          })),
+        },
+        RESET: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+
+    completing: {
+      invoke: {
+        id: 'notifyBackend',
+        src: 'notifyBackend',
+        input: ({ context }) => ({
+          getFinishStatus: context.getFinishStatus,
+          flowId: context.flow?.flowId,
+        }),
+        onDone: {
+          target: 'finished',
+          actions: 'setFinishStatus',
+        },
+        onError: {
+          target: 'error',
+          actions: 'setError',
+        },
+      },
+      on: {
+        RESET: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+
+    finished: {
+      on: {
+        RESET: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+
+    error: {
+      on: {
+        RESET: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+  },
+});
+
+export type OrchestratedFlowMachine = typeof orchestratedFlowMachine;