@forgerock/journey-client 0.0.0-beta-20251222204813

package/src/lib/callbacks/base-callback.test.ts

@@ -0,0 +1,42 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * fr-auth-callback.test.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 { callbackType } from '@forgerock/sdk-types';
+
+import type { Callback } from '@forgerock/sdk-types';
+
+import { BaseCallback } from './base-callback.js';
+
+describe('BaseCallback', () => {
+  it('reads/writes basic properties', () => {
+    const payload: Callback = {
+      _id: 0,
+      input: [
+        {
+          name: 'userName',
+          value: '',
+        },
+      ],
+      output: [
+        {
+          name: 'prompt',
+          value: 'Username:',
+        },
+      ],
+      type: callbackType.NameCallback,
+    };
+    const cb = new BaseCallback(payload);
+    cb.setInputValue('superman');
+
+    expect(cb.getType()).toBe('NameCallback');
+    expect(cb.getOutputValue('prompt')).toBe('Username:');
+    expect(cb.getInputValue()).toBe('superman');
+  });
+});

package/src/lib/callbacks/base-callback.ts

@@ -0,0 +1,101 @@
+/*
+ * 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 { CallbackType, Callback, NameValue } from '@forgerock/sdk-types';
+
+/**
+ * Base class for authentication tree callback wrappers.
+ */
+export class BaseCallback {
+  /**
+   * @param payload The raw payload returned by OpenAM
+   */
+  constructor(public payload: Callback) {}
+
+  /**
+   * Gets the name of this callback type.
+   */
+  public getType(): CallbackType {
+    return this.payload.type;
+  }
+
+  /**
+   * Gets the value of the specified input element, or the first element if `selector` is not
+   * provided.
+   *
+   * @param selector The index position or name of the desired element
+   */
+  public getInputValue(selector: number | string = 0): unknown {
+    return this.getArrayElement(this.payload.input, selector).value;
+  }
+
+  /**
+   * Sets the value of the specified input element, or the first element if `selector` is not
+   * provided.
+   *
+   * @param selector The index position or name of the desired element
+   */
+  public setInputValue(value: unknown, selector: number | string | RegExp = 0): void {
+    this.getArrayElement(this.payload.input, selector).value = value;
+  }
+
+  /**
+   * Gets the value of the specified output element, or the first element if `selector`
+   * is not provided.
+   *
+   * @param selector The index position or name of the desired element
+   */
+  public getOutputValue(selector: number | string = 0): unknown {
+    return this.getArrayElement(this.payload.output, selector).value;
+  }
+
+  /**
+   * Gets the value of the first output element with the specified name or the
+   * specified default value.
+   *
+   * @param name The name of the desired element
+   */
+  public getOutputByName<T>(name: string, defaultValue: T): T {
+    const output = this.payload.output.find((x: NameValue) => x.name === name);
+    return output ? (output.value as T) : defaultValue;
+  }
+
+  private getArrayElement(
+    array: NameValue[] | undefined,
+    selector: number | string | RegExp = 0,
+  ): NameValue {
+    if (array === undefined) {
+      throw new Error(`No NameValue array was provided to search (selector ${selector})`);
+    }
+
+    if (typeof selector === 'number') {
+      if (selector < 0 || selector > array.length - 1) {
+        throw new Error(`Selector index ${selector} is out of range`);
+      }
+      return array[selector];
+    }
+
+    if (typeof selector === 'string') {
+      const input = array.find((x) => x.name === selector);
+      if (!input) {
+        throw new Error(`Missing callback input entry "${selector}"`);
+      }
+      return input;
+    }
+
+    // Duck typing for RegEx
+    if (typeof selector === 'object' && selector.test && Boolean(selector.exec)) {
+      const input = array.find((x) => selector.test(x.name));
+      if (!input) {
+        throw new Error(`Missing callback input entry "${selector}"`);
+      }
+      return input;
+    }
+
+    throw new Error('Invalid selector value type');
+  }
+}

package/src/lib/callbacks/choice-callback.test.ts

@@ -0,0 +1,77 @@
+/*
+ * 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 { describe, it, expect } from 'vitest';
+
+import type { Callback } from '@forgerock/sdk-types';
+
+import { ChoiceCallback } from './choice-callback.js';
+
+describe('ChoiceCallback', () => {
+  const payload: Callback = {
+    type: callbackType.ChoiceCallback,
+    output: [
+      {
+        name: 'prompt',
+        value: 'Select an option',
+      },
+      {
+        name: 'choices',
+        value: ['one', 'two', 'three'],
+      },
+      {
+        name: 'defaultChoice',
+        value: 1,
+      },
+    ],
+    input: [
+      {
+        name: 'IDToken1',
+        value: 0,
+      },
+    ],
+  };
+
+  it('should allow getting the prompt', () => {
+    const cb = new ChoiceCallback(payload);
+    expect(cb.getPrompt()).toBe('Select an option');
+  });
+
+  it('should allow getting the choices', () => {
+    const cb = new ChoiceCallback(payload);
+    expect(cb.getChoices()).toEqual(['one', 'two', 'three']);
+  });
+
+  it('should allow getting the default choice', () => {
+    const cb = new ChoiceCallback(payload);
+    expect(cb.getDefaultChoice()).toBe(1);
+  });
+
+  it('should allow setting the choice by index', () => {
+    const cb = new ChoiceCallback(payload);
+    cb.setChoiceIndex(2);
+    expect(cb.getInputValue()).toBe(2);
+  });
+
+  it('should throw an error for an out-of-bounds index', () => {
+    const cb = new ChoiceCallback(payload);
+    expect(() => cb.setChoiceIndex(3)).toThrow('3 is out of bounds');
+    expect(() => cb.setChoiceIndex(-1)).toThrow('-1 is out of bounds');
+  });
+
+  it('should allow setting the choice by value', () => {
+    const cb = new ChoiceCallback(payload);
+    cb.setChoiceValue('two');
+    expect(cb.getInputValue()).toBe(1);
+  });
+
+  it('should throw an error for an invalid choice value', () => {
+    const cb = new ChoiceCallback(payload);
+    expect(() => cb.setChoiceValue('four')).toThrow('"four" is not a valid choice');
+  });
+});

package/src/lib/callbacks/choice-callback.ts

@@ -0,0 +1,64 @@
+/*
+ * 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 { Callback } from '@forgerock/sdk-types';
+
+import { BaseCallback } from './base-callback.js';
+
+/**
+ * Represents a callback used to collect an answer to a choice.
+ */
+export class ChoiceCallback extends BaseCallback {
+  /**
+   * @param payload The raw payload returned by OpenAM
+   */
+  constructor(public override payload: Callback) {
+    super(payload);
+  }
+
+  /**
+   * Gets the choice's prompt.
+   */
+  public getPrompt(): string {
+    return this.getOutputByName<string>('prompt', '');
+  }
+
+  /**
+   * Gets the choice's default answer.
+   */
+  public getDefaultChoice(): number {
+    return this.getOutputByName<number>('defaultChoice', 0);
+  }
+
+  /**
+   * Gets the choice's possible answers.
+   */
+  public getChoices(): string[] {
+    return this.getOutputByName<string[]>('choices', []);
+  }
+
+  /**
+   * Sets the choice's answer by index position.
+   */
+  public setChoiceIndex(index: number): void {
+    const length = this.getChoices().length;
+    if (index < 0 || index > length - 1) {
+      throw new Error(`${index} is out of bounds`);
+    }
+    this.setInputValue(index);
+  }
+
+  /**
+   * Sets the choice's answer by value.
+   */
+  public setChoiceValue(value: string): void {
+    const index = this.getChoices().indexOf(value);
+    if (index === -1) {
+      throw new Error(`"${value}" is not a valid choice`);
+    }
+    this.setInputValue(index);
+  }
+}

package/src/lib/callbacks/confirmation-callback.test.ts

@@ -0,0 +1,94 @@
+/*
+ * 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 { describe, it, expect } from 'vitest';
+
+import type { Callback } from '@forgerock/sdk-types';
+
+import { ConfirmationCallback } from './confirmation-callback.js';
+
+describe('ConfirmationCallback', () => {
+  const payload: Callback = {
+    type: callbackType.ConfirmationCallback,
+    output: [
+      {
+        name: 'prompt',
+        value: 'Are you sure?',
+      },
+      {
+        name: 'messageType',
+        value: 0,
+      },
+      {
+        name: 'options',
+        value: ['Yes', 'No'],
+      },
+      {
+        name: 'optionType',
+        value: -1,
+      },
+      {
+        name: 'defaultOption',
+        value: 1,
+      },
+    ],
+    input: [
+      {
+        name: 'IDToken1',
+        value: 0,
+      },
+    ],
+  };
+
+  it('should allow getting the prompt', () => {
+    const cb = new ConfirmationCallback(payload);
+    expect(cb.getPrompt()).toBe('Are you sure?');
+  });
+
+  it('should allow getting the message type', () => {
+    const cb = new ConfirmationCallback(payload);
+    expect(cb.getMessageType()).toBe(0);
+  });
+
+  it('should allow getting the options', () => {
+    const cb = new ConfirmationCallback(payload);
+    expect(cb.getOptions()).toEqual(['Yes', 'No']);
+  });
+
+  it('should allow getting the option type', () => {
+    const cb = new ConfirmationCallback(payload);
+    expect(cb.getOptionType()).toBe(-1);
+  });
+
+  it('should allow getting the default option', () => {
+    const cb = new ConfirmationCallback(payload);
+    expect(cb.getDefaultOption()).toBe(1);
+  });
+
+  it('should allow setting the option by index', () => {
+    const cb = new ConfirmationCallback(payload);
+    cb.setOptionIndex(1);
+    expect(cb.getInputValue()).toBe(1);
+  });
+
+  it('should throw an error for an invalid index', () => {
+    const cb = new ConfirmationCallback(payload);
+    expect(() => cb.setOptionIndex(2)).toThrow('"2" is not a valid choice');
+  });
+
+  it('should allow setting the option by value', () => {
+    const cb = new ConfirmationCallback(payload);
+    cb.setOptionValue('No');
+    expect(cb.getInputValue()).toBe(1);
+  });
+
+  it('should throw an error for an invalid value', () => {
+    const cb = new ConfirmationCallback(payload);
+    expect(() => cb.setOptionValue('Maybe')).toThrow('"Maybe" is not a valid choice');
+  });
+});

package/src/lib/callbacks/confirmation-callback.ts

@@ -0,0 +1,78 @@
+/*
+ * 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 { Callback } from '@forgerock/sdk-types';
+
+import { BaseCallback } from './base-callback.js';
+
+/**
+ * Represents a callback used to collect a confirmation to a message.
+ */
+export class ConfirmationCallback extends BaseCallback {
+  /**
+   * @param payload The raw payload returned by OpenAM
+   */
+  constructor(public override payload: Callback) {
+    super(payload);
+  }
+
+  /**
+   * Gets the index position of the confirmation's default answer.
+   */
+  public getDefaultOption(): number {
+    return Number(this.getOutputByName<number>('defaultOption', 0));
+  }
+
+  /**
+   * Gets the confirmation's message type.
+   */
+  public getMessageType(): number {
+    return Number(this.getOutputByName<number>('messageType', 0));
+  }
+
+  /**
+   * Gets the confirmation's possible answers.
+   */
+  public getOptions(): string[] {
+    return this.getOutputByName<string[]>('options', []);
+  }
+
+  /**
+   * Gets the confirmation's option type.
+   */
+  public getOptionType(): number {
+    return Number(this.getOutputByName<number>('optionType', 0));
+  }
+
+  /**
+   * Gets the confirmation's prompt.
+   */
+  public getPrompt(): string {
+    return this.getOutputByName<string>('prompt', '');
+  }
+
+  /**
+   * Set option index.
+   */
+  public setOptionIndex(index: number): void {
+    const opts = this.getOptions();
+    if (!Number.isInteger(index) || index < 0 || index >= opts.length) {
+      throw new Error(`"${index}" is not a valid choice (0-${Math.max(0, opts.length - 1)})`);
+    }
+    this.setInputValue(index);
+  }
+
+  /**
+   * Set option value.
+   */
+  public setOptionValue(value: string): void {
+    const index = this.getOptions().indexOf(value);
+    if (index === -1) {
+      throw new Error(`"${value}" is not a valid choice`);
+    }
+    this.setInputValue(index);
+  }
+}

package/src/lib/callbacks/device-profile-callback.test.ts

@@ -0,0 +1,68 @@
+/*
+ * 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 { describe, it, expect } from 'vitest';
+
+import type { Callback } from '@forgerock/sdk-types';
+
+import { DeviceProfileCallback } from './device-profile-callback.js';
+
+describe('DeviceProfileCallback', () => {
+  const payload: Callback = {
+    type: callbackType.DeviceProfileCallback,
+    output: [
+      {
+        name: 'message',
+        value: 'Collecting device profile...',
+      },
+      {
+        name: 'metadata',
+        value: true,
+      },
+      {
+        name: 'location',
+        value: false,
+      },
+    ],
+    input: [
+      {
+        name: 'IDToken1',
+        value: '',
+      },
+    ],
+  };
+
+  it('should allow getting the message', () => {
+    const cb = new DeviceProfileCallback(payload);
+    expect(cb.getMessage()).toBe('Collecting device profile...');
+  });
+
+  it('should allow getting the metadata requirement', () => {
+    const cb = new DeviceProfileCallback(payload);
+    expect(cb.isMetadataRequired()).toBe(true);
+  });
+
+  it('should allow getting the location requirement', () => {
+    const cb = new DeviceProfileCallback(payload);
+    expect(cb.isLocationRequired()).toBe(false);
+  });
+
+  it('should allow setting the device profile', () => {
+    const cb = new DeviceProfileCallback(payload);
+    const profile = {
+      identifier: 'test-id',
+      metadata: {
+        hardware: { display: {} },
+        browser: {},
+        platform: {},
+      },
+    };
+    cb.setProfile(profile);
+    expect(cb.getInputValue()).toBe(JSON.stringify(profile));
+  });
+});

package/src/lib/callbacks/device-profile-callback.ts

@@ -0,0 +1,51 @@
+/*
+ * 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 { Callback } from '@forgerock/sdk-types';
+
+import { BaseCallback } from './base-callback.js';
+
+import type { DeviceProfileData } from '../device/interfaces.js';
+
+/**
+ * Represents a callback used to collect device profile data.
+ */
+export class DeviceProfileCallback extends BaseCallback {
+  /**
+   * @param payload The raw payload returned by OpenAM
+   */
+  constructor(public override payload: Callback) {
+    super(payload);
+  }
+
+  /**
+   * Gets the callback's data.
+   */
+  public getMessage(): string {
+    return this.getOutputByName<string>('message', '');
+  }
+
+  /**
+   * Does callback require metadata?
+   */
+  public isMetadataRequired(): boolean {
+    return this.getOutputByName<boolean>('metadata', false);
+  }
+
+  /**
+   * Does callback require location data?
+   */
+  public isLocationRequired(): boolean {
+    return this.getOutputByName<boolean>('location', false);
+  }
+
+  /**
+   * Sets the profile.
+   */
+  public setProfile(profile: DeviceProfileData): void {
+    this.setInputValue(JSON.stringify(profile));
+  }
+}

package/src/lib/callbacks/factory.test.ts

@@ -0,0 +1,89 @@
+/*
+ * 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 { describe, it, expect } from 'vitest';
+
+import type { Callback } from '@forgerock/sdk-types';
+
+import { createCallback } from './factory.js';
+import { BaseCallback } from './base-callback.js';
+
+// Import all callback classes to check against
+import { AttributeInputCallback } from './attribute-input-callback.js';
+import { ChoiceCallback } from './choice-callback.js';
+import { ConfirmationCallback } from './confirmation-callback.js';
+import { DeviceProfileCallback } from './device-profile-callback.js';
+import { HiddenValueCallback } from './hidden-value-callback.js';
+import { KbaCreateCallback } from './kba-create-callback.js';
+import { MetadataCallback } from './metadata-callback.js';
+import { NameCallback } from './name-callback.js';
+import { PasswordCallback } from './password-callback.js';
+import { PingOneProtectEvaluationCallback } from './ping-protect-evaluation-callback.js';
+import { PingOneProtectInitializeCallback } from './ping-protect-initialize-callback.js';
+import { PollingWaitCallback } from './polling-wait-callback.js';
+import { ReCaptchaCallback } from './recaptcha-callback.js';
+import { ReCaptchaEnterpriseCallback } from './recaptcha-enterprise-callback.js';
+import { RedirectCallback } from './redirect-callback.js';
+import { SelectIdPCallback } from './select-idp-callback.js';
+import { SuspendedTextOutputCallback } from './suspended-text-output-callback.js';
+import { TermsAndConditionsCallback } from './terms-and-conditions-callback.js';
+import { TextInputCallback } from './text-input-callback.js';
+import { TextOutputCallback } from './text-output-callback.js';
+import { ValidatedCreatePasswordCallback } from './validated-create-password-callback.js';
+import { ValidatedCreateUsernameCallback } from './validated-create-username-callback.js';
+
+describe('Callback Factory', () => {
+  const testCases = [
+    { type: callbackType.BooleanAttributeInputCallback, class: AttributeInputCallback },
+    { type: callbackType.ChoiceCallback, class: ChoiceCallback },
+    { type: callbackType.ConfirmationCallback, class: ConfirmationCallback },
+    { type: callbackType.DeviceProfileCallback, class: DeviceProfileCallback },
+    { type: callbackType.HiddenValueCallback, class: HiddenValueCallback },
+    { type: callbackType.KbaCreateCallback, class: KbaCreateCallback },
+    { type: callbackType.MetadataCallback, class: MetadataCallback },
+    { type: callbackType.NameCallback, class: NameCallback },
+    { type: callbackType.NumberAttributeInputCallback, class: AttributeInputCallback },
+    { type: callbackType.PasswordCallback, class: PasswordCallback },
+    {
+      type: callbackType.PingOneProtectEvaluationCallback,
+      class: PingOneProtectEvaluationCallback,
+    },
+    {
+      type: callbackType.PingOneProtectInitializeCallback,
+      class: PingOneProtectInitializeCallback,
+    },
+    { type: callbackType.PollingWaitCallback, class: PollingWaitCallback },
+    { type: callbackType.ReCaptchaCallback, class: ReCaptchaCallback },
+    { type: callbackType.ReCaptchaEnterpriseCallback, class: ReCaptchaEnterpriseCallback },
+    { type: callbackType.RedirectCallback, class: RedirectCallback },
+    { type: callbackType.SelectIdPCallback, class: SelectIdPCallback },
+    { type: callbackType.StringAttributeInputCallback, class: AttributeInputCallback },
+    { type: callbackType.SuspendedTextOutputCallback, class: SuspendedTextOutputCallback },
+    { type: callbackType.TermsAndConditionsCallback, class: TermsAndConditionsCallback },
+    { type: callbackType.TextInputCallback, class: TextInputCallback },
+    { type: callbackType.TextOutputCallback, class: TextOutputCallback },
+    { type: callbackType.ValidatedCreatePasswordCallback, class: ValidatedCreatePasswordCallback },
+    { type: callbackType.ValidatedCreateUsernameCallback, class: ValidatedCreateUsernameCallback },
+  ];
+
+  testCases.forEach((testCase) => {
+    it(`should create an instance of ${testCase.class.name} for type ${testCase.type}`, () => {
+      const payload: Callback = { type: testCase.type, input: [], output: [] };
+      const callback = createCallback(payload);
+      expect(callback).toBeInstanceOf(testCase.class);
+    });
+  });
+
+  it('should create a base BaseCallback for an unknown type', () => {
+    const payload: Callback = { type: 'UnknownCallback' as any, input: [], output: [] };
+    const callback = createCallback(payload);
+    expect(callback).toBeInstanceOf(BaseCallback);
+    // Ensure it's not an instance of a more specific class
+    expect(callback).not.toBeInstanceOf(NameCallback);
+  });
+});