@forgerock/journey-client 0.0.0-beta-20251222204813

package/src/lib/journey.api.ts

@@ -0,0 +1,198 @@
+/*
+ * 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.
+ */
+
+import { initQuery, RequestMiddleware } from '@forgerock/sdk-request-middleware';
+import { REQUESTED_WITH, getEndpointPath, stringify, resolve } from '@forgerock/sdk-utilities';
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query';
+
+import type { ServerConfig, Step } from '@forgerock/sdk-types';
+import type { logger as loggerFn } from '@forgerock/sdk-logger';
+import type {
+  BaseQueryApi,
+  BaseQueryFn,
+  FetchArgs,
+  FetchBaseQueryError,
+  FetchBaseQueryMeta,
+  QueryReturnValue,
+} from '@reduxjs/toolkit/query';
+
+import { JourneyStep } from './step.types.js';
+
+import type { JourneyClientConfig } from './config.types.js';
+import { NextOptions, StartParam } from './interfaces.js';
+
+// Move these functions to the top, before journeyApi definition
+function constructUrl(
+  serverConfig: ServerConfig,
+  realmPath?: string,
+  tree?: string,
+  query?: Record<string, string>,
+): string {
+  const treeParams = tree ? { authIndexType: 'service', authIndexValue: tree } : undefined;
+  const params: Record<string, string | undefined> = { ...query, ...treeParams };
+  const queryString = Object.keys(params).length > 0 ? `?${stringify(params)}` : '';
+  const path = getEndpointPath({
+    endpoint: 'authenticate',
+    realmPath,
+    customPaths: serverConfig.paths,
+  });
+  const url = resolve(serverConfig.baseUrl, `${path}${queryString}`);
+  return url;
+}
+
+function constructSessionsUrl(
+  serverConfig: ServerConfig,
+  realmPath?: string,
+  query?: Record<string, string>,
+): string {
+  const params: Record<string, string | undefined> = { ...query };
+  const queryString = Object.keys(params).length > 0 ? `?${stringify(params)}` : '';
+  const path = getEndpointPath({
+    endpoint: 'sessions',
+    realmPath,
+    customPaths: serverConfig.paths,
+  });
+  const url = resolve(serverConfig.baseUrl, `${path}${queryString}`);
+  return url;
+}
+
+function configureRequest(step?: JourneyStep): RequestInit {
+  const init: RequestInit = {
+    body: step ? JSON.stringify(step.payload) : undefined,
+    credentials: 'include',
+    headers: new Headers({}),
+    method: 'POST',
+  };
+
+  return init;
+}
+
+function configureSessionRequest(): RequestInit {
+  const init: RequestInit = {
+    credentials: 'include',
+    headers: new Headers({}),
+    method: 'POST',
+  };
+
+  return init;
+}
+
+interface Extras {
+  requestMiddleware: RequestMiddleware[];
+  logger: ReturnType<typeof loggerFn>;
+  config: JourneyClientConfig;
+}
+
+export const journeyApi = createApi({
+  reducerPath: 'journeyReducer',
+  baseQuery: fetchBaseQuery({
+    baseUrl: '/',
+    prepareHeaders: (headers: Headers) => {
+      headers.set('Accept', 'application/json');
+      headers.set('Accept-API-Version', 'protocol=1.0,resource=2.1');
+      headers.set('Content-Type', 'application/json');
+      headers.set('X-Requested-With', REQUESTED_WITH);
+
+      return headers;
+    },
+  }),
+  endpoints: (builder) => ({
+    start: builder.mutation<Step, StartParam | undefined>({
+      queryFn: async (
+        options: StartParam | undefined,
+        api: BaseQueryApi,
+        _: unknown,
+        baseQuery: BaseQueryFn,
+      ) => {
+        const { config } = api.extra as Extras;
+        if (!config.serverConfig) {
+          throw new Error('Server configuration is missing.');
+        }
+        const { realmPath, serverConfig } = config;
+
+        const query = options?.query || {};
+
+        const url = constructUrl(serverConfig, realmPath, options?.journey, query);
+        const request = configureRequest();
+
+        const { requestMiddleware } = api.extra as Extras;
+
+        const response = await initQuery({ ...request, url: url }, 'begin', {
+          type: 'service',
+          tree: options?.journey,
+        })
+          .applyMiddleware(requestMiddleware)
+          .applyQuery(async (req: FetchArgs) => {
+            const result = await baseQuery(req, api, api.extra as Extras);
+            return result as QueryReturnValue<unknown, FetchBaseQueryError, FetchBaseQueryMeta>;
+          });
+
+        return response as QueryReturnValue<Step, FetchBaseQueryError, FetchBaseQueryMeta>;
+      },
+    }),
+    next: builder.mutation<Step, { step: JourneyStep; options?: NextOptions }>({
+      queryFn: async (
+        { step, options }: { step: JourneyStep; options?: NextOptions },
+        api: BaseQueryApi,
+        _: unknown,
+        baseQuery: BaseQueryFn,
+      ) => {
+        const { config } = api.extra as Extras;
+        if (!config.serverConfig) {
+          throw new Error('Server configuration is missing.');
+        }
+        const { realmPath, serverConfig } = config;
+        const query = options?.query || {};
+
+        // TODO: Handle the `undefined` argument better
+        const url = constructUrl(serverConfig, realmPath, undefined, query);
+        const request = configureRequest(step);
+
+        const { requestMiddleware } = api.extra as Extras;
+
+        const response = await initQuery({ ...request, url }, 'continue')
+          .applyMiddleware(requestMiddleware)
+          .applyQuery(async (req: FetchArgs) => {
+            const result = await baseQuery(req, api, api.extra as Extras);
+            return result as QueryReturnValue<unknown, FetchBaseQueryError, FetchBaseQueryMeta>;
+          });
+
+        return response as QueryReturnValue<Step, FetchBaseQueryError, FetchBaseQueryMeta>;
+      },
+    }),
+    terminate: builder.mutation<void, { query?: Record<string, string> } | undefined>({
+      queryFn: async (
+        options: { query?: Record<string, string> } | undefined,
+        api: BaseQueryApi,
+        _: unknown,
+        baseQuery: BaseQueryFn,
+      ) => {
+        const { config } = api.extra as Extras;
+        if (!config.serverConfig) {
+          throw new Error('Server configuration is missing.');
+        }
+        const { realmPath, serverConfig } = config;
+
+        const query = { ...options?.query, _action: 'logout' };
+
+        const url = constructSessionsUrl(serverConfig, realmPath, query);
+        const request = configureSessionRequest();
+
+        const { requestMiddleware } = api.extra as Extras;
+
+        const response = await initQuery({ ...request, url }, 'terminate')
+          .applyMiddleware(requestMiddleware)
+          .applyQuery(async (req: FetchArgs) => {
+            const result = await baseQuery(req, api, api.extra as Extras);
+            return result as QueryReturnValue<unknown, FetchBaseQueryError, FetchBaseQueryMeta>;
+          });
+
+        return response as QueryReturnValue<void, FetchBaseQueryError, FetchBaseQueryMeta>;
+      },
+    }),
+  }),
+});

package/src/lib/journey.slice.ts

@@ -0,0 +1,33 @@
+/*
+ * 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 { createSlice, PayloadAction, Slice } from '@reduxjs/toolkit';
+
+import type { Step } from '@forgerock/sdk-types';
+
+import type { JourneyClientConfig } from './config.types.js';
+
+export interface JourneyState {
+  authId?: string;
+  step?: Step;
+  error?: Error;
+  config?: JourneyClientConfig;
+}
+
+const initialState: JourneyState = {};
+
+export const journeySlice: Slice<JourneyState> = createSlice({
+  name: 'journey',
+  initialState,
+  reducers: {
+    setConfig: (state, action: PayloadAction<JourneyClientConfig>) => {
+      state.config = action.payload;
+    },
+  },
+});
+
+export const { setConfig } = journeySlice.actions;

package/src/lib/journey.utils.ts

@@ -0,0 +1,44 @@
+/*
+ * 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 { StepType } from '@forgerock/sdk-types';
+
+import type { Step } from '@forgerock/sdk-types';
+
+import { createJourneyLoginSuccess } from './login-success.utils.js';
+import { createJourneyLoginFailure } from './login-failure.utils.js';
+import { createJourneyStep } from './step.utils.js';
+
+import type { JourneyStep } from './step.utils.js';
+import type { JourneyLoginFailure } from './login-failure.utils.js';
+import type { JourneyLoginSuccess } from './login-success.utils.js';
+
+function createJourneyObject(
+  step: Step,
+): JourneyStep | JourneyLoginSuccess | JourneyLoginFailure | undefined {
+  let type;
+  if (step.authId) {
+    type = StepType.Step;
+  } else if (step.successUrl) {
+    type = StepType.LoginSuccess;
+  } else {
+    type = StepType.LoginFailure;
+  }
+
+  switch (type) {
+    case StepType.LoginSuccess:
+      return createJourneyLoginSuccess(step);
+    case StepType.LoginFailure:
+      return createJourneyLoginFailure(step);
+    case StepType.Step:
+      return createJourneyStep(step);
+    default:
+      return undefined;
+  }
+}
+
+export { createJourneyObject };

package/src/lib/login-failure.utils.test.ts

@@ -0,0 +1,31 @@
+/*
+ * 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.
+ */
+
+import { StepType } from '@forgerock/sdk-types';
+import { describe, expect, it } from 'vitest';
+
+import { createJourneyLoginFailure } from './login-failure.utils.js';
+
+describe('createJourneyLoginFailure', () => {
+  it('should create a JourneyLoginFailure object', () => {
+    const step = {
+      code: 400,
+      detail: { failureUrl: 'failure-url' },
+      message: 'Invalid credentials',
+      reason: 'INVALID_CREDENTIALS',
+    };
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    const journeyLoginFailure = createJourneyLoginFailure(step);
+
+    expect(journeyLoginFailure.type).toBe(StepType.LoginFailure);
+    expect(journeyLoginFailure.payload).toEqual(step);
+    expect(journeyLoginFailure.getCode()).toBe(400);
+    expect(journeyLoginFailure.getDetail()).toEqual({ failureUrl: 'failure-url' });
+    expect(journeyLoginFailure.getMessage()).toBe('Invalid credentials');
+    expect(journeyLoginFailure.getReason()).toBe('INVALID_CREDENTIALS');
+  });
+});

package/src/lib/login-failure.utils.ts

@@ -0,0 +1,62 @@
+/*
+ * 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.
+ */
+import { StepType } from '@forgerock/sdk-types';
+
+import type { Step, AuthResponse, FailureDetail } from '@forgerock/sdk-types';
+
+import { Policy } from './policy/policy.js';
+
+import type { MessageCreator, ProcessedPropertyError } from './policy/interfaces.js';
+
+type JourneyLoginFailure = AuthResponse & {
+  type: StepType.LoginFailure;
+  payload: Step;
+  getCode: () => number;
+  getDetail: () => FailureDetail | undefined;
+  getMessage: () => string | undefined;
+  getProcessedMessage: (messageCreator?: MessageCreator) => ProcessedPropertyError[];
+  getReason: () => string | undefined;
+};
+
+function getCode(payload: Step): number {
+  return Number(payload.code);
+}
+
+function getDetail(payload: Step): FailureDetail | undefined {
+  return payload.detail;
+}
+
+function getMessage(payload: Step): string | undefined {
+  return payload.message;
+}
+
+function getProcessedMessage(
+  payload: Step,
+  messageCreator?: MessageCreator,
+): ProcessedPropertyError[] {
+  return Policy.parseErrors(payload, messageCreator);
+}
+
+function getReason(payload: Step): string | undefined {
+  return payload.reason;
+}
+
+function createJourneyLoginFailure(payload: Step): JourneyLoginFailure {
+  return {
+    payload,
+    type: StepType.LoginFailure,
+    getCode: () => getCode(payload),
+    getDetail: () => getDetail(payload),
+    getMessage: () => getMessage(payload),
+    getProcessedMessage: (messageCreator?: MessageCreator) =>
+      getProcessedMessage(payload, messageCreator),
+    getReason: () => getReason(payload),
+  };
+}
+
+export { createJourneyLoginFailure };
+
+export type { JourneyLoginFailure };

package/src/lib/login-success.utils.test.ts

@@ -0,0 +1,29 @@
+/*
+ * 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.
+ */
+
+import { StepType } from '@forgerock/sdk-types';
+import { describe, expect, it } from 'vitest';
+
+import { createJourneyLoginSuccess } from './login-success.utils.js';
+
+describe('createJourneyLoginSuccess', () => {
+  it('should create a JourneyLoginSuccess object', () => {
+    const step = {
+      realm: 'my-realm',
+      tokenId: 'my-token',
+      successUrl: 'my-success-url',
+    };
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    const journeyLoginSuccess = createJourneyLoginSuccess(step);
+
+    expect(journeyLoginSuccess.type).toBe(StepType.LoginSuccess);
+    expect(journeyLoginSuccess.payload).toEqual(step);
+    expect(journeyLoginSuccess.getRealm()).toBe('my-realm');
+    expect(journeyLoginSuccess.getSessionToken()).toBe('my-token');
+    expect(journeyLoginSuccess.getSuccessUrl()).toBe('my-success-url');
+  });
+});

package/src/lib/login-success.utils.ts

@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+
+import { StepType } from '@forgerock/sdk-types';
+
+import type { Step, AuthResponse } from '@forgerock/sdk-types';
+
+type JourneyLoginSuccess = AuthResponse & {
+  type: StepType.LoginSuccess;
+  payload: Step;
+  getRealm: () => string | undefined;
+  getSessionToken: () => string | undefined;
+  getSuccessUrl: () => string | undefined;
+};
+
+function getRealm(payload: Step): string | undefined {
+  return payload.realm;
+}
+
+function getSessionToken(payload: Step): string | undefined {
+  return payload.tokenId;
+}
+
+function getSuccessUrl(payload: Step): string | undefined {
+  return payload.successUrl;
+}
+
+function createJourneyLoginSuccess(payload: Step): JourneyLoginSuccess {
+  return {
+    payload,
+    type: StepType.LoginSuccess,
+    getRealm: () => getRealm(payload),
+    getSessionToken: () => getSessionToken(payload),
+    getSuccessUrl: () => getSuccessUrl(payload),
+  };
+}
+
+export { createJourneyLoginSuccess, getRealm, getSessionToken, getSuccessUrl };
+
+export type { JourneyLoginSuccess };

package/src/lib/policy/interfaces.ts

@@ -0,0 +1,16 @@
+/*
+ * 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.
+ */
+
+import type { FailedPolicyRequirement } from '@forgerock/sdk-types';
+
+export interface MessageCreator {
+  [key: string]: (propertyName: string, params?: { [key: string]: unknown }) => string;
+}
+
+export interface ProcessedPropertyError {
+  detail: FailedPolicyRequirement;
+  messages: string[];
+}

package/src/lib/policy/message-creator.ts

@@ -0,0 +1,66 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * message-creator.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.
+ */
+
+import { PolicyKey } from '@forgerock/sdk-types';
+import { getProp, plural } from '@forgerock/sdk-utilities';
+
+import type { MessageCreator } from './interfaces.js';
+
+export const defaultMessageCreator: MessageCreator = {
+  [PolicyKey.CannotContainCharacters]: (property: string, params?: { forbiddenChars?: string }) => {
+    const forbiddenChars = getProp<string>(params, 'forbiddenChars', '');
+    return `${property} must not contain following characters: "${forbiddenChars}"`;
+  },
+  [PolicyKey.CannotContainDuplicates]: (property: string, params?: { duplicateValue?: string }) => {
+    const duplicateValue = getProp<string>(params, 'duplicateValue', '');
+    return `${property} must not contain duplicates: "${duplicateValue}"`;
+  },
+  [PolicyKey.CannotContainOthers]: (property: string, params?: { disallowedFields?: string }) => {
+    const disallowedFields = getProp<string>(params, 'disallowedFields', '');
+    return `${property} must not contain: "${disallowedFields}"`;
+  },
+  [PolicyKey.LeastCapitalLetters]: (property: string, params?: { numCaps?: number }) => {
+    const numCaps = getProp<number>(params, 'numCaps', 0);
+    return `${property} must contain at least ${numCaps} capital ${plural(numCaps, 'letter')}`;
+  },
+  [PolicyKey.LeastNumbers]: (property: string, params?: { numNums?: number }) => {
+    const numNums = getProp<number>(params, 'numNums', 0);
+    return `${property} must contain at least ${numNums} numeric ${plural(numNums, 'value')}`;
+  },
+  [PolicyKey.MatchRegexp]: (property: string) => `${property} has failed the "MATCH_REGEXP" policy`,
+  [PolicyKey.MaximumLength]: (property: string, params?: { maxLength?: number }) => {
+    const maxLength = getProp<number>(params, 'maxLength', 0);
+    return `${property} must be at most ${maxLength} ${plural(maxLength, 'character')}`;
+  },
+  [PolicyKey.MaximumNumber]: (property: string) =>
+    `${property} has failed the "MAXIMUM_NUMBER_VALUE" policy`,
+  [PolicyKey.MinimumLength]: (property: string, params?: { minLength?: number }) => {
+    const minLength = getProp<number>(params, 'minLength', 0);
+    return `${property} must be at least ${minLength} ${plural(minLength, 'character')}`;
+  },
+  [PolicyKey.MinimumNumber]: (property: string) =>
+    `${property} has failed the "MINIMUM_NUMBER_VALUE" policy`,
+  [PolicyKey.Required]: (property: string) => `${property} is required`,
+  [PolicyKey.Unique]: (property: string) => `${property} must be unique`,
+  [PolicyKey.UnknownPolicy]: (property: string, params?: { policyRequirement?: string }) => {
+    const policyRequirement = getProp<string>(params, 'policyRequirement', 'Unknown');
+    return `${property}: Unknown policy requirement "${policyRequirement}"`;
+  },
+  [PolicyKey.ValidArrayItems]: (property: string) =>
+    `${property} has failed the "VALID_ARRAY_ITEMS" policy`,
+  [PolicyKey.ValidDate]: (property: string) => `${property} has an invalid date`,
+  [PolicyKey.ValidEmailAddress]: (property: string) => `${property} has an invalid email address`,
+  [PolicyKey.ValidNameFormat]: (property: string) => `${property} has an invalid name format`,
+  [PolicyKey.ValidNumber]: (property: string) => `${property} has an invalid number`,
+  [PolicyKey.ValidPhoneFormat]: (property: string) => `${property} has an invalid phone number`,
+  [PolicyKey.ValidQueryFilter]: (property: string) =>
+    `${property} has failed the "VALID_QUERY_FILTER" policy`,
+  [PolicyKey.ValidType]: (property: string) => `${property} has failed the "VALID_TYPE" policy`,
+};