@forgerock/journey-client 0.0.0-beta-20251222204813

package/src/lib/client.store.test.ts

@@ -0,0 +1,324 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import { callbackType } from '@forgerock/sdk-types';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import type { Step } from '@forgerock/sdk-types';
+
+import { journey } from './client.store.js';
+import { createJourneyStep } from './step.utils.js';
+import { JourneyClientConfig } from './config.types.js';
+
+// Create a singleton mock instance for storage
+const mockStorageInstance = {
+  get: vi.fn(),
+  set: vi.fn(),
+  remove: vi.fn(),
+};
+
+// Mock dependencies with side effects
+vi.mock('@forgerock/storage', () => ({
+  createStorage: vi.fn(() => mockStorageInstance),
+}));
+
+vi.mock('./device/device-profile.js', () => ({
+  default: vi.fn(() => ({
+    getProfile: vi.fn().mockResolvedValue({}),
+  })),
+}));
+
+// Mock the fetch API to control responses
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+const mockConfig: JourneyClientConfig = {
+  serverConfig: {
+    baseUrl: 'https://test.com',
+  },
+  realmPath: 'root',
+};
+
+describe('journey-client', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test('should initialize and return a client object with all methods', async () => {
+    const client = await journey({ config: mockConfig });
+    expect(client).toBeDefined();
+    expect(client.start).toBeInstanceOf(Function);
+    expect(client.next).toBeInstanceOf(Function);
+    expect(client.redirect).toBeInstanceOf(Function);
+    expect(client.resume).toBeInstanceOf(Function);
+    expect(client.terminate).toBeInstanceOf(Function);
+  });
+
+  test('start() should fetch and return the first step', async () => {
+    const mockStepResponse: Step = { authId: 'test-auth-id', callbacks: [] };
+    mockFetch.mockResolvedValue(new Response(JSON.stringify(mockStepResponse)));
+
+    const client = await journey({ config: mockConfig });
+    const step = await client.start();
+    expect(step).toBeDefined();
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const request = mockFetch.mock.calls[0][0] as Request;
+    // TODO: This should be /journeys?_action=start, but the current implementation calls /authenticate
+    expect(request.url).toBe('https://test.com/json/realms/root/authenticate');
+    expect(step).toHaveProperty('type', 'Step');
+    expect(step && step.payload).toEqual(mockStepResponse);
+  });
+
+  test('next() should send the current step and return the next step', async () => {
+    const initialStep = createJourneyStep({
+      authId: 'test-auth-id',
+      callbacks: [
+        {
+          type: callbackType.NameCallback,
+          input: [{ name: 'IDToken1', value: 'test-user' }],
+          output: [],
+        },
+      ],
+    });
+    const nextStepPayload: Step = {
+      authId: 'test-auth-id',
+      callbacks: [
+        {
+          type: callbackType.PasswordCallback,
+          input: [{ name: 'IDToken2', value: 'test-password' }],
+          output: [],
+        },
+      ],
+    };
+
+    mockFetch.mockResolvedValue(new Response(JSON.stringify(nextStepPayload)));
+
+    const client = await journey({ config: mockConfig });
+    const nextStep = await client.next(initialStep, {});
+    expect(nextStep).toBeDefined();
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const request = mockFetch.mock.calls[0][0] as Request;
+    // TODO: This should be /journeys?_action=next, but the current implementation calls /authenticate
+    expect(request.url).toBe('https://test.com/json/realms/root/authenticate');
+    expect(request.method).toBe('POST');
+    expect(await request.json()).toEqual(initialStep.payload);
+    expect(nextStep).toHaveProperty('type', 'Step');
+    expect(nextStep && nextStep.payload).toEqual(nextStepPayload);
+  });
+
+  test('redirect() should store the step and call location.assign', async () => {
+    const mockStepPayload: Step = {
+      callbacks: [
+        {
+          type: callbackType.RedirectCallback,
+          input: [],
+          output: [{ name: 'redirectUrl', value: 'https://sso.com/redirect' }],
+        },
+      ],
+    };
+    const step = createJourneyStep(mockStepPayload);
+
+    const assignMock = vi.fn();
+    const locationSpy = vi.spyOn(window, 'location', 'get').mockReturnValue({
+      ...window.location,
+      assign: assignMock,
+    });
+
+    const client = await journey({ config: mockConfig });
+    await client.redirect(step);
+
+    expect(mockStorageInstance.set).toHaveBeenCalledWith({ step: step.payload });
+    expect(assignMock).toHaveBeenCalledWith('https://sso.com/redirect');
+
+    locationSpy.mockRestore();
+  });
+
+  describe('resume()', () => {
+    test('should call next() with URL params when a previous step is in storage', async () => {
+      const previousStepPayload: Step = {
+        callbacks: [{ type: callbackType.RedirectCallback, input: [], output: [] }],
+      };
+      mockStorageInstance.get.mockResolvedValue({ step: previousStepPayload });
+
+      const nextStepPayload: Step = { authId: 'test-auth-id', callbacks: [] };
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(nextStepPayload)));
+
+      const client = await journey({ config: mockConfig });
+      const resumeUrl = 'https://app.com/callback?code=123&state=abc';
+
+      const step = await client.resume(resumeUrl, {});
+      expect(step).toBeDefined();
+
+      expect(mockStorageInstance.get).toHaveBeenCalledTimes(1);
+      expect(mockStorageInstance.remove).toHaveBeenCalledTimes(1);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      const request = mockFetch.mock.calls[0][0] as Request;
+
+      // TODO: This should be /journeys?_action=next, but the current implementation calls /authenticate
+      const url = new URL(request.url);
+      expect(url.origin + url.pathname).toBe('https://test.com/json/realms/root/authenticate');
+      expect(url.searchParams.get('code')).toBe('123');
+      expect(url.searchParams.get('state')).toBe('abc');
+
+      expect(request.method).toBe('POST');
+      expect(await request.json()).toEqual(previousStepPayload);
+      expect(step).toHaveProperty('type', 'Step');
+      expect(step && step.payload).toEqual(nextStepPayload);
+    });
+
+    test('should correctly resume with a plain Step object from storage', async () => {
+      const plainStepPayload: Step = {
+        callbacks: [
+          { type: callbackType.TextOutputCallback, output: [{ name: 'message', value: 'Hello' }] },
+        ],
+        stage: 'testStage',
+      };
+      mockStorageInstance.get.mockResolvedValue({ step: plainStepPayload });
+
+      const nextStepPayload: Step = { authId: 'test-auth-id', callbacks: [] };
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(nextStepPayload)));
+
+      const client = await journey({ config: mockConfig });
+      const resumeUrl = 'https://app.com/callback?code=123&state=abc';
+
+      const step = await client.resume(resumeUrl, {});
+      expect(step).toBeDefined();
+
+      expect(mockStorageInstance.get).toHaveBeenCalledTimes(1);
+      expect(mockStorageInstance.remove).toHaveBeenCalledTimes(1);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+
+      const request = mockFetch.mock.calls[0][0] as Request;
+      expect(request.method).toBe('POST');
+      expect(await request.json()).toEqual(plainStepPayload); // Expect the plain payload to be sent
+      expect(step).toHaveProperty('type', 'Step'); // The returned step should still be an JourneyStep instance
+      expect(step && step.payload).toEqual(nextStepPayload);
+    });
+
+    test('should throw an error if a previous step is required but not found', async () => {
+      mockStorageInstance.get.mockResolvedValue(undefined);
+
+      const client = await journey({ config: mockConfig });
+      const resumeUrl = 'https://app.com/callback?code=123&state=abc';
+
+      await expect(client.resume(resumeUrl)).rejects.toThrow(
+        'Error: previous step information not found in storage for resume operation.',
+      );
+      expect(mockStorageInstance.get).toHaveBeenCalledTimes(1);
+      expect(mockStorageInstance.remove).toHaveBeenCalledTimes(1);
+    });
+
+    test('should call start() with URL params when no previous step is required', async () => {
+      mockStorageInstance.get.mockResolvedValue(undefined);
+
+      const mockStepResponse: Step = { authId: 'test-auth-id', callbacks: [] };
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockStepResponse)));
+
+      const client = await journey({ config: mockConfig });
+      const resumeUrl = 'https://app.com/callback?foo=bar';
+
+      const step = await client.resume(resumeUrl, {});
+      expect(step).toBeDefined();
+
+      expect(mockStorageInstance.get).not.toHaveBeenCalled();
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      const request = mockFetch.mock.calls[0][0] as Request;
+
+      // TODO: This should be /journeys?_action=start, but the current implementation calls /authenticate
+      const url = new URL(request.url);
+      expect(url.origin + url.pathname).toBe('https://test.com/json/realms/root/authenticate');
+      expect(step).toHaveProperty('type', 'Step');
+      expect(step && step.payload).toEqual(mockStepResponse);
+    });
+  });
+
+  describe('baseUrl normalization', () => {
+    test('should add trailing slash to baseUrl without one', async () => {
+      const configWithoutSlash: JourneyClientConfig = {
+        serverConfig: {
+          baseUrl: 'http://localhost:9443/am',
+        },
+        realmPath: 'root',
+      };
+
+      const mockStepResponse: Step = { authId: 'test-auth-id', callbacks: [] };
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockStepResponse)));
+
+      const client = await journey({ config: configWithoutSlash });
+      await client.start();
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      const request = mockFetch.mock.calls[0][0] as Request;
+      expect(request.url).toBe('http://localhost:9443/am/json/realms/root/authenticate');
+    });
+
+    test('should preserve trailing slash if already present', async () => {
+      const configWithSlash: JourneyClientConfig = {
+        serverConfig: {
+          baseUrl: 'http://localhost:9443/am/',
+        },
+        realmPath: 'root',
+      };
+
+      const mockStepResponse: Step = { authId: 'test-auth-id', callbacks: [] };
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockStepResponse)));
+
+      const client = await journey({ config: configWithSlash });
+      await client.start();
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      const request = mockFetch.mock.calls[0][0] as Request;
+      expect(request.url).toBe('http://localhost:9443/am/json/realms/root/authenticate');
+    });
+
+    test('should work with baseUrl without context path', async () => {
+      const configNoContext: JourneyClientConfig = {
+        serverConfig: {
+          baseUrl: 'http://localhost:9443',
+        },
+        realmPath: 'root',
+      };
+
+      const mockStepResponse: Step = { authId: 'test-auth-id', callbacks: [] };
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockStepResponse)));
+
+      const client = await journey({ config: configNoContext });
+      await client.start();
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      const request = mockFetch.mock.calls[0][0] as Request;
+      expect(request.url).toBe('http://localhost:9443/json/realms/root/authenticate');
+    });
+  });
+
+  // TODO: Add tests for endSession when the test environment AbortSignal issue is resolved
+  // test('endSession() should call the sessions endpoint with DELETE method', async () => {
+  //   mockFetch.mockResolvedValue(new Response('', { status: 200 }));
+  //
+  //   const client = await journey({ config: mockConfig });
+  //   await client.endSession();
+  //
+  //   expect(mockFetch).toHaveBeenCalledTimes(1);
+  //   const request = mockFetch.mock.calls[0][0] as Request;
+  //   expect(request.url).toBe('https://test.com/json/realms/root/sessions/');
+  //   expect(request.method).toBe('DELETE');
+  // });
+  //
+  // test('endSession() should handle query parameters', async () => {
+  //   mockFetch.mockResolvedValue(new Response('', { status: 200 }));
+  //
+  //   const client = await journey({ config: mockConfig });
+  //   await client.endSession({ query: { foo: 'bar' } });
+  //
+  //   expect(mockFetch).toHaveBeenCalledTimes(1);
+  //   const request = mockFetch.mock.calls[0][0] as Request;
+  //   expect(request.url).toBe('https://test.com/json/realms/root/sessions/?foo=bar');
+  //   expect(request.method).toBe('DELETE');
+  // });
+});

package/src/lib/client.store.ts

@@ -0,0 +1,194 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import { logger as loggerFn, LogLevel, CustomLogger } from '@forgerock/sdk-logger';
+import { callbackType } from '@forgerock/sdk-types';
+
+import type { RequestMiddleware } from '@forgerock/sdk-request-middleware';
+import type { GenericError, Step } from '@forgerock/sdk-types';
+
+import { createJourneyStore } from './client.store.utils.js';
+import { journeyApi } from './journey.api.js';
+import { setConfig } from './journey.slice.js';
+import { createStorage } from '@forgerock/storage';
+import { createJourneyObject } from './journey.utils.js';
+
+import type { JourneyStep } from './step.utils.js';
+import type { JourneyClientConfig } from './config.types.js';
+import type { RedirectCallback } from './callbacks/redirect-callback.js';
+import { NextOptions, StartParam, ResumeOptions } from './interfaces.js';
+
+/**
+ * Normalizes the serverConfig to ensure baseUrl has a trailing slash.
+ * This is required for the resolve() function to work correctly with context paths like /am.
+ */
+function normalizeConfig(config: JourneyClientConfig): JourneyClientConfig {
+  if (config.serverConfig?.baseUrl) {
+    const url = config.serverConfig.baseUrl;
+    if (url.charAt(url.length - 1) !== '/') {
+      return {
+        ...config,
+        serverConfig: {
+          ...config.serverConfig,
+          baseUrl: url + '/',
+        },
+      };
+    }
+  }
+  return config;
+}
+
+export async function journey({
+  config,
+  requestMiddleware,
+  logger,
+}: {
+  config: JourneyClientConfig;
+  requestMiddleware?: RequestMiddleware[];
+  logger?: {
+    level: LogLevel;
+    custom?: CustomLogger;
+  };
+}) {
+  const log = loggerFn({ level: logger?.level || 'error', custom: logger?.custom });
+
+  // Normalize config to ensure baseUrl has trailing slash
+  const normalizedConfig = normalizeConfig(config);
+
+  const store = createJourneyStore({ requestMiddleware, logger: log, config: normalizedConfig });
+  store.dispatch(setConfig(normalizedConfig));
+
+  const stepStorage = createStorage<{ step: Step }>({
+    type: 'sessionStorage',
+    name: 'journey-step',
+  });
+
+  const self = {
+    start: async (options?: StartParam) => {
+      const { data } = await store.dispatch(journeyApi.endpoints.start.initiate(options));
+      return data ? createJourneyObject(data) : undefined;
+    },
+
+    /**
+     * Submits the current Step payload to the authentication API and retrieves the next JourneyStep in the journey.
+     * The `step` to be submitted is provided within the `options` object.
+     *
+     * @param options An object containing the current Step payload and optional JourneyClientConfig.
+     * @returns A Promise that resolves to the next JourneyStep in the journey, or undefined if the journey ends.
+     */
+    next: async (step: JourneyStep, options?: NextOptions) => {
+      const { data } = await store.dispatch(journeyApi.endpoints.next.initiate({ step, options }));
+      return data ? createJourneyObject(data) : undefined;
+    },
+
+    // TODO: Remove the actual redirect from this method and just return the URL to the caller
+    redirect: async (step: JourneyStep) => {
+      const cb = step.getCallbackOfType(callbackType.RedirectCallback) as RedirectCallback;
+      if (!cb) {
+        // TODO: Remove throwing errors from SDK and use Result types instead
+        throw new Error('RedirectCallback not found on step');
+      }
+
+      const redirectUrl = cb.getRedirectUrl();
+      if (!redirectUrl || typeof redirectUrl !== 'string') {
+        throw new Error('Redirect URL not found on RedirectCallback');
+      }
+
+      const err = await stepStorage.set({ step: step.payload });
+      if (err && (err as GenericError).error) {
+        log.warn('Failed to persist step before redirect', err);
+      }
+      window.location.assign(redirectUrl);
+    },
+
+    resume: async (
+      url: string,
+      options?: ResumeOptions,
+    ): Promise<ReturnType<typeof createJourneyObject> | undefined> => {
+      const parsedUrl = new URL(url);
+      const code = parsedUrl.searchParams.get('code');
+      const state = parsedUrl.searchParams.get('state');
+      const form_post_entry = parsedUrl.searchParams.get('form_post_entry');
+      const responsekey = parsedUrl.searchParams.get('responsekey');
+
+      let previousStep: JourneyStep | undefined; // Declare previousStep here
+
+      function requiresPreviousStep() {
+        return (code && state) || form_post_entry || responsekey;
+      }
+
+      // Type guard for GenericError (assuming GenericError has 'error' and 'message' properties)
+      function isGenericError(obj: unknown): obj is GenericError {
+        return typeof obj === 'object' && obj !== null && 'error' in obj && 'message' in obj;
+      }
+
+      // Type guard for { step: JourneyStep }
+      function isStoredStep(obj: unknown): obj is { step: Step } {
+        return (
+          typeof obj === 'object' &&
+          obj !== null &&
+          'step' in obj &&
+          typeof (obj as { step: Step }).step === 'object'
+        );
+      }
+
+      if (requiresPreviousStep()) {
+        const stored = await stepStorage.get();
+
+        if (stored) {
+          if (isGenericError(stored)) {
+            // If the stored item is a GenericError, it means something went wrong during storage/retrieval
+            // or the previous step was an error.
+            // TODO: Remove throwing errors from SDK and use Result types instead
+            throw new Error(`Error retrieving previous step: ${stored.message || stored.error}`);
+          } else if (isStoredStep(stored)) {
+            previousStep = createJourneyObject(stored.step) as JourneyStep;
+          }
+        }
+        await stepStorage.remove();
+
+        if (!previousStep) {
+          throw new Error(
+            'Error: previous step information not found in storage for resume operation.',
+          );
+        }
+      }
+
+      const resumeOptions = {
+        ...options,
+        query: {
+          ...(options && options.query), // Spread options.query first
+          ...(code && { code }),
+          ...(state && { state }),
+          ...(form_post_entry && { form_post_entry }),
+          ...(responsekey && { responsekey }),
+        },
+      };
+
+      if (previousStep) {
+        return await self.next(previousStep, resumeOptions);
+      } else {
+        // TODO: We should better handle this type misalignment
+        const startOptions = resumeOptions as StartParam;
+        return await self.start(startOptions);
+      }
+    },
+
+    /**
+     * Ends the current authentication session by calling the `/sessions` endpoint.
+     * This will invalidate the current session and clean up any server-side state.
+     *
+     * @param options Optional StepOptions containing query parameters.
+     * @returns A Promise that resolves when the session is successfully ended.
+     */
+    terminate: async (options?: { query?: Record<string, string> }) => {
+      const { data } = await store.dispatch(journeyApi.endpoints.terminate.initiate(options));
+      return data;
+    },
+  };
+  return self;
+}

package/src/lib/client.store.utils.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import { logger as loggerFn } from '@forgerock/sdk-logger';
+import { RequestMiddleware } from '@forgerock/sdk-request-middleware';
+import { combineReducers, configureStore } from '@reduxjs/toolkit';
+
+import { journeyApi } from './journey.api.js';
+import { journeySlice } from './journey.slice.js';
+import { JourneyClientConfig } from './config.types.js';
+
+const rootReducer = combineReducers({
+  [journeyApi.reducerPath]: journeyApi.reducer,
+  [journeySlice.name]: journeySlice.reducer,
+});
+
+export const createJourneyStore = ({
+  requestMiddleware,
+  logger,
+  config,
+}: {
+  requestMiddleware?: RequestMiddleware[];
+  logger?: ReturnType<typeof loggerFn>;
+  config: JourneyClientConfig;
+}) => {
+  return configureStore({
+    reducer: rootReducer,
+    middleware: (getDefaultMiddleware) =>
+      getDefaultMiddleware({
+        serializableCheck: true,
+        thunk: {
+          extraArgument: {
+            requestMiddleware,
+            logger,
+            config,
+          },
+        },
+      }).concat(journeyApi.middleware),
+  });
+};
+
+export type RootState = ReturnType<typeof rootReducer>;

package/src/lib/config.types.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import type { BaseConfig } from '@forgerock/sdk-types';
+import type { RequestMiddleware } from '@forgerock/sdk-request-middleware';
+
+export interface JourneyClientConfig extends BaseConfig {
+  middleware?: Array<RequestMiddleware>;
+  realmPath?: string;
+  // Add any journey-specific config options here
+}
+
+export type { RequestMiddleware };

package/src/lib/device/defaults.ts

@@ -0,0 +1,79 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * defaults.ts
+ *
+ * Copyright (c) 2020 - 2025 Ping Identity Corporation. All rights reserved.
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+export const browserProps = [
+  'userAgent',
+  'appName',
+  'appCodeName',
+  'appVersion',
+  'appMinorVersion',
+  'buildID',
+  'product',
+  'productSub',
+  'vendor',
+  'vendorSub',
+  'browserLanguage',
+];
+export const configurableCategories = [
+  'fontNames',
+  'displayProps',
+  'browserProps',
+  'hardwareProps',
+  'platformProps',
+];
+export const delay = 30 * 1000;
+export const devicePlatforms = {
+  mac: ['Macintosh', 'MacIntel', 'MacPPC', 'Mac68K'],
+  windows: ['Win32', 'Win64', 'Windows', 'WinCE'],
+  ios: ['iPhone', 'iPad', 'iPod'],
+};
+export const displayProps = ['width', 'height', 'pixelDepth', 'orientation.angle'];
+export const fontNames = [
+  'cursive',
+  'monospace',
+  'serif',
+  'sans-serif',
+  'fantasy',
+  'Arial',
+  'Arial Black',
+  'Arial Narrow',
+  'Arial Rounded MT Bold',
+  'Bookman Old Style',
+  'Bradley Hand ITC',
+  'Century',
+  'Century Gothic',
+  'Comic Sans MS',
+  'Courier',
+  'Courier New',
+  'Georgia',
+  'Gentium',
+  'Impact',
+  'King',
+  'Lucida Console',
+  'Lalit',
+  'Modena',
+  'Monotype Corsiva',
+  'Papyrus',
+  'Tahoma',
+  'TeX',
+  'Times',
+  'Times New Roman',
+  'Trebuchet MS',
+  'Verdana',
+  'Verona',
+];
+export const hardwareProps = [
+  'cpuClass',
+  'deviceMemory',
+  'hardwareConcurrency',
+  'maxTouchPoints',
+  'oscpu',
+];
+export const platformProps = ['language', 'platform', 'userLanguage', 'systemLanguage'];