@incodetech/core 2.0.0-alpha.2 → 2.0.0-alpha.4

package/src/flow/flowManager.ts

@@ -1,235 +0,0 @@
-import {
-  type CreateApiOptions,
-  createManager,
-  type ManagerSnapshot,
-} from '@incodetech/infra';
-import { type CreateFlowActorOptions, createFlowActor } from './flowActor';
-import type { FlowMachine } from './flowStateMachine';
-import type { Flow } from './types';
-
-/** Internal snapshot type for the flow state machine */
-type FlowSnapshot = ManagerSnapshot<FlowMachine>;
-
-/** Flow manager is waiting to be started */
-type FlowIdleState = {
-  status: 'idle';
-};
-
-/** Flow is being fetched from the server */
-type FlowLoadingState = {
-  status: 'loading';
-};
-
-/** Flow is loaded and ready for navigation */
-export type FlowReadyState = {
-  status: 'ready';
-  /** The complete flow configuration from the server */
-  flow: Flow;
-  /** Array of module keys in order */
-  steps: string[];
-  /** Zero-based index of the current step */
-  currentStepIndex: number;
-  /** The module key of the current step (e.g., 'SELFIE', 'ID', 'FACE_MATCH') */
-  currentStep: string | undefined;
-  /** The configuration object for the current module. Type varies by module. */
-  config: unknown;
-};
-
-/** All steps have been completed */
-type FlowFinishedState = {
-  status: 'finished';
-  /** The complete flow configuration */
-  flow: Flow;
-};
-
-/** An error occurred while loading or processing the flow */
-type FlowErrorState = {
-  status: 'error';
-  /** The error message */
-  error: string;
-};
-
-/** Union of all possible flow states */
-export type FlowState =
-  | FlowIdleState
-  | FlowLoadingState
-  | FlowReadyState
-  | FlowFinishedState
-  | FlowErrorState;
-
-function mapState(snapshot: FlowSnapshot): FlowState {
-  const { value, context } = snapshot;
-
-  switch (value) {
-    case 'idle':
-      return { status: 'idle' };
-    case 'loading':
-      return { status: 'loading' };
-    case 'ready':
-      return {
-        status: 'ready',
-        flow: context.flow ?? ({} as Flow),
-        steps: context.steps,
-        currentStepIndex: context.currentStepIndex,
-        currentStep: context.currentStep,
-        config: context.config,
-      };
-    case 'finished':
-      return {
-        status: 'finished',
-        flow: context.flow ?? ({} as Flow),
-      };
-    case 'error':
-      return {
-        status: 'error',
-        error: context.error ?? 'Unknown error',
-      };
-    default:
-      return { status: 'idle' };
-  }
-}
-
-function createApi({ actor, getSnapshot }: CreateApiOptions<FlowMachine>) {
-  function getCanNext(): boolean {
-    const snapshot = getSnapshot();
-    const { currentStepIndex, steps } = snapshot.context;
-    return (
-      snapshot.matches('ready') &&
-      currentStepIndex >= 0 &&
-      currentStepIndex < steps.length - 1
-    );
-  }
-
-  function getCanPrev(): boolean {
-    const snapshot = getSnapshot();
-    return snapshot.matches('ready') && snapshot.context.currentStepIndex > 0;
-  }
-
-  function getModuleConfig<T = unknown>(moduleKey: string): T | undefined {
-    const snapshot = getSnapshot();
-    if (!snapshot.matches('ready')) {
-      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.matches('ready')) {
-      return false;
-    }
-    return !!snapshot.context.flow?.flowModules.some(
-      (m) => m.key === moduleKey,
-    );
-  }
-
-  return {
-    /**
-     * Loads the flow from the server.
-     * Transitions the state from `idle` to `loading`, then to `ready` on success or `error` on failure.
-     * Requires setup() to have been called with a token first.
-     */
-    load() {
-      actor.send({ type: 'LOAD' });
-    },
-
-    /**
-     * Cancels the current loading operation and returns to `idle` state.
-     * Only effective when in `loading` state.
-     */
-    cancel() {
-      actor.send({ type: 'CANCEL' });
-    },
-
-    /**
-     * Resets the flow manager to its initial `idle` state.
-     * Can be called from `ready`, `finished`, or `error` states.
-     */
-    reset() {
-      actor.send({ type: 'RESET' });
-    },
-
-    /**
-     * Advances to the next step in the flow.
-     * If on the last step, transitions to `finished` state.
-     * Only effective when in `ready` state.
-     */
-    nextStep() {
-      actor.send({ type: 'NEXT_STEP' });
-    },
-
-    /**
-     * Goes back to the previous step in the flow.
-     * Does nothing if already on the first step.
-     * Only effective when in `ready` state.
-     */
-    prevStep() {
-      actor.send({ type: 'PREV_STEP' });
-    },
-
-    /**
-     * Whether the flow can advance to the next step.
-     * Returns `true` if in `ready` state and not on the last step.
-     */
-    get canNext() {
-      return getCanNext();
-    },
-
-    /**
-     * Whether the flow can go back to the previous step.
-     * Returns `true` if in `ready` state and not on the first step.
-     */
-    get canPrev() {
-      return getCanPrev();
-    },
-
-    /**
-     * Gets the configuration for a specific module by its key.
-     * Useful for accessing config of modules other than the current one.
-     * @param moduleKey - The unique key identifier of the module
-     * @returns The module configuration or `undefined` if not found or not in `ready` state
-     */
-    getModuleConfig,
-
-    /**
-     * Checks if a module is enabled in the current flow.
-     * @param moduleKey - The unique key identifier of the module
-     * @returns `true` if the module exists in the flow, `false` otherwise or if not in `ready` state
-     */
-    isModuleEnabled,
-  };
-}
-
-/**
- * Creates a flow manager instance for managing onboarding flow state and navigation.
- *
- * The flow manager provides:
- * - State management with statuses: `idle`, `loading`, `ready`, `finished`, `error`
- * - Step navigation with `nextStep()` and `prevStep()`
- * - Current step info via `state.currentStep` and `state.config` when in `ready` state
- * - Module configuration lookup via `getModuleConfig()`
- *
- * @param options - Optional configuration for the flow actor
- * @param options.getFlow - Custom function to fetch flow data. Defaults to `getOnboardingFlow`
- * @returns A manager instance with state subscription, API methods, and lifecycle controls
- *
- * @example
- * ```ts
- * const flowManager = createFlowManager();
- *
- * flowManager.subscribe((state) => {
- *   if (state.status === 'ready') {
- *     console.log(state.currentStep, state.config);
- *   }
- * });
- *
- * flowManager.load({ token: 'session-token' });
- * ```
- */
-export function createFlowManager(options?: CreateFlowActorOptions) {
-  const actor = createFlowActor(options);
-  return createManager({ actor, mapState, createApi });
-}

package/src/flow/flowServices.test.ts

@@ -1,109 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import {
-  createMockResponse,
-  mockClient,
-  resetMocks,
-} from '../http/__mocks__/api';
-import { mockFlow } from './__mocks__/flowMocks';
-import { type GetFlow, getFlow } from './flowServices';
-
-vi.mock('../http/api', () => import('../http/__mocks__/api'));
-
-describe('flowServices', () => {
-  beforeEach(() => {
-    resetMocks();
-  });
-
-  describe('getFlow', () => {
-    it('should call api.get with correct URL', async () => {
-      mockClient.get.mockResolvedValue(createMockResponse(mockFlow));
-
-      const abortController = new AbortController();
-
-      await getFlow(abortController.signal);
-
-      expect(mockClient.get).toHaveBeenCalledWith('/omni/onboarding/flow', {
-        signal: abortController.signal,
-      });
-    });
-
-    it('should return flow data on success', async () => {
-      mockClient.get.mockResolvedValue(createMockResponse(mockFlow));
-
-      const abortController = new AbortController();
-
-      const result = await getFlow(abortController.signal);
-
-      expect(result).toEqual(mockFlow);
-    });
-
-    it('should throw error when response is not ok', async () => {
-      mockClient.get.mockResolvedValue({
-        ...createMockResponse(null, false),
-        status: 401,
-        statusText: 'Unauthorized',
-      });
-
-      const abortController = new AbortController();
-
-      await expect(getFlow(abortController.signal)).rejects.toThrow(
-        'GET /flow failed: 401 Unauthorized',
-      );
-    });
-
-    it('should throw error when response is 404', async () => {
-      mockClient.get.mockResolvedValue({
-        ...createMockResponse(null, false),
-        status: 404,
-        statusText: 'Not Found',
-      });
-
-      const abortController = new AbortController();
-
-      await expect(getFlow(abortController.signal)).rejects.toThrow(
-        'GET /flow failed: 404 Not Found',
-      );
-    });
-
-    it('should throw error when response is 500', async () => {
-      mockClient.get.mockResolvedValue({
-        ...createMockResponse(null, false),
-        status: 500,
-        statusText: 'Internal Server Error',
-      });
-
-      const abortController = new AbortController();
-
-      await expect(getFlow(abortController.signal)).rejects.toThrow(
-        'GET /flow failed: 500 Internal Server Error',
-      );
-    });
-
-    it('should pass abort signal to api', async () => {
-      mockClient.get.mockResolvedValue(createMockResponse(mockFlow));
-
-      const abortController = new AbortController();
-
-      await getFlow(abortController.signal);
-
-      const callArgs = mockClient.get.mock.calls[0];
-      expect(callArgs[1]?.signal).toBe(abortController.signal);
-    });
-  });
-
-  describe('GetFlow type', () => {
-    it('should be compatible with custom implementations', async () => {
-      const customGetFlow: GetFlow = async (_signal) => {
-        return {
-          flowId: 'custom-flow',
-          name: 'Custom Flow',
-          flowModules: [],
-        };
-      };
-
-      const result = await customGetFlow(new AbortController().signal);
-
-      expect(result.flowId).toBe('custom-flow');
-    });
-  });
-});

package/src/flow/flowServices.ts

@@ -1,13 +0,0 @@
-import { api } from '../http/api';
-import { endpoints } from '../http/endpoints';
-import type { Flow } from './types';
-
-export type GetFlow = (signal: AbortSignal) => Promise<Flow>;
-
-export const getFlow: GetFlow = async (signal) => {
-  const res = await api.get<Flow>(endpoints.flow, { signal });
-  if (!res.ok) {
-    throw new Error(`GET /flow failed: ${res.status} ${res.statusText}`);
-  }
-  return res.data as Flow;
-};

package/src/flow/flowStateMachine.test.ts

@@ -1,334 +0,0 @@
-import { createActor } from '@incodetech/infra';
-import { describe, expect, it, vi } from 'vitest';
-import {
-  createFailingGetFlow,
-  createMockGetFlow,
-  mockFlow,
-} from './__mocks__/flowMocks';
-import { flowMachine } from './flowStateMachine';
-import type { Flow } from './types';
-
-describe('flowStateMachine', () => {
-  describe('Initial state', () => {
-    it('should start in idle state', () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      expect(actor.getSnapshot().value).toBe('idle');
-      actor.stop();
-    });
-
-    it('should have initial context', () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      const { context } = actor.getSnapshot();
-      expect(context.flow).toBeUndefined();
-      expect(context.error).toBeUndefined();
-      expect(context.steps).toEqual([]);
-      expect(context.currentStepIndex).toBe(-1);
-
-      actor.stop();
-    });
-  });
-
-  describe('LOAD event', () => {
-    it('should transition to loading state', () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      expect(actor.getSnapshot().value).toBe('loading');
-      actor.stop();
-    });
-  });
-
-  describe('Loading flow', () => {
-    it('should call getFlow with signal', async () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(getFlow).toHaveBeenCalledWith(expect.any(AbortSignal));
-      });
-
-      actor.stop();
-    });
-
-    it('should transition to ready on success', async () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('ready');
-      });
-
-      actor.stop();
-    });
-
-    it('should set flow data in context on success', async () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('ready');
-      });
-
-      const { context } = actor.getSnapshot();
-      expect(context.flow).toEqual(mockFlow);
-      expect(context.steps).toEqual(['TUTORIAL_ID', 'SELFIE', 'FACE_MATCH']);
-      expect(context.currentStepIndex).toBe(0);
-
-      actor.stop();
-    });
-
-    it('should transition to error on failure', async () => {
-      const getFlow = createFailingGetFlow('Network error');
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('error');
-      });
-
-      expect(actor.getSnapshot().context.error).toContain('Network error');
-
-      actor.stop();
-    });
-  });
-
-  describe('CANCEL event during loading', () => {
-    it('should transition back to idle', async () => {
-      const getFlow = vi.fn().mockImplementation(() => {
-        return new Promise((resolve) =>
-          setTimeout(() => resolve(mockFlow), 1000),
-        );
-      });
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-      expect(actor.getSnapshot().value).toBe('loading');
-
-      actor.send({ type: 'CANCEL' });
-
-      expect(actor.getSnapshot().value).toBe('idle');
-
-      actor.stop();
-    });
-  });
-
-  describe('Step navigation in ready state', () => {
-    const setupReadyActor = async () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('ready');
-      });
-
-      return actor;
-    };
-
-    it('should increment step on NEXT_STEP', async () => {
-      const actor = await setupReadyActor();
-
-      expect(actor.getSnapshot().context.currentStepIndex).toBe(0);
-
-      actor.send({ type: 'NEXT_STEP' });
-
-      expect(actor.getSnapshot().context.currentStepIndex).toBe(1);
-      expect(actor.getSnapshot().value).toBe('ready');
-
-      actor.stop();
-    });
-
-    it('should decrement step on PREV_STEP', async () => {
-      const actor = await setupReadyActor();
-
-      actor.send({ type: 'NEXT_STEP' });
-      expect(actor.getSnapshot().context.currentStepIndex).toBe(1);
-
-      actor.send({ type: 'PREV_STEP' });
-      expect(actor.getSnapshot().context.currentStepIndex).toBe(0);
-
-      actor.stop();
-    });
-
-    it('should not go below 0 on PREV_STEP', async () => {
-      const actor = await setupReadyActor();
-
-      expect(actor.getSnapshot().context.currentStepIndex).toBe(0);
-
-      actor.send({ type: 'PREV_STEP' });
-
-      expect(actor.getSnapshot().context.currentStepIndex).toBe(0);
-
-      actor.stop();
-    });
-
-    it('should transition to finished on last step', async () => {
-      const actor = await setupReadyActor();
-
-      actor.send({ type: 'NEXT_STEP' });
-      actor.send({ type: 'NEXT_STEP' });
-
-      expect(actor.getSnapshot().context.currentStepIndex).toBe(2);
-      expect(actor.getSnapshot().value).toBe('ready');
-
-      actor.send({ type: 'NEXT_STEP' });
-
-      expect(actor.getSnapshot().value).toBe('finished');
-
-      actor.stop();
-    });
-  });
-
-  describe('RESET event', () => {
-    it('should reset from ready state to idle', async () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('ready');
-      });
-
-      actor.send({ type: 'RESET' });
-
-      expect(actor.getSnapshot().value).toBe('idle');
-      expect(actor.getSnapshot().context.flow).toBeUndefined();
-      expect(actor.getSnapshot().context.steps).toEqual([]);
-
-      actor.stop();
-    });
-
-    it('should reset from error state to idle', async () => {
-      const getFlow = createFailingGetFlow('Error');
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('error');
-      });
-
-      actor.send({ type: 'RESET' });
-
-      expect(actor.getSnapshot().value).toBe('idle');
-      expect(actor.getSnapshot().context.error).toBeUndefined();
-
-      actor.stop();
-    });
-
-    it('should reset from finished state to idle', async () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('ready');
-      });
-
-      actor.send({ type: 'NEXT_STEP' });
-      actor.send({ type: 'NEXT_STEP' });
-      actor.send({ type: 'NEXT_STEP' });
-
-      expect(actor.getSnapshot().value).toBe('finished');
-
-      actor.send({ type: 'RESET' });
-
-      expect(actor.getSnapshot().value).toBe('idle');
-
-      actor.stop();
-    });
-  });
-
-  describe('Empty flow handling', () => {
-    it('should handle flow with no modules', async () => {
-      const emptyFlow: Flow = {
-        flowId: 'empty',
-        name: 'Empty Flow',
-        flowModules: [],
-      };
-      const getFlow = createMockGetFlow(emptyFlow);
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      }).start();
-
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('ready');
-      });
-
-      const { context } = actor.getSnapshot();
-      expect(context.steps).toEqual([]);
-      expect(context.currentStepIndex).toBe(-1);
-
-      actor.stop();
-    });
-  });
-
-  describe('Subscriptions', () => {
-    it('should notify subscribers of state changes', async () => {
-      const getFlow = createMockGetFlow();
-      const actor = createActor(flowMachine, {
-        input: { getFlow },
-      });
-
-      const states: string[] = [];
-      actor.subscribe((snapshot) => {
-        states.push(snapshot.value as string);
-      });
-
-      actor.start();
-      actor.send({ type: 'LOAD' });
-
-      await vi.waitFor(() => {
-        expect(actor.getSnapshot().value).toBe('ready');
-      });
-
-      expect(states).toContain('idle');
-      expect(states).toContain('loading');
-      expect(states).toContain('ready');
-
-      actor.stop();
-    });
-  });
-});