@forgerock/journey-client 0.0.0-beta-20251222204813

package/src/lib/device/device-profile.mock.data.ts

@@ -0,0 +1,120 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * device-profile.mock.data.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 expectedJsdom = {
+  identifier: '',
+  metadata: {
+    hardware: {
+      display: {
+        width: 0,
+        height: 0,
+        pixelDepth: 24,
+        angle: '',
+      },
+      cpuClass: null,
+      deviceMemory: null,
+      hardwareConcurrency: 16,
+      maxTouchPoints: null,
+      oscpu: null,
+    },
+    browser: {
+      appName: 'Netscape',
+      userAgent: 'Mozilla/5.0 (darwin) AppleWebKit/537.36 (KHTML, like Gecko) jsdom/16.2.2',
+      appCodeName: 'Mozilla',
+      appVersion: '4.0',
+      appMinorVersion: null,
+      buildID: null,
+      product: 'Gecko',
+      productSub: '20030107',
+      vendor: 'Apple Computer, Inc.',
+      vendorSub: '',
+      browserLanguage: null,
+      plugins: '',
+    },
+    platform: {
+      deviceName: 'Unknown (Browser)',
+      fonts: '',
+      language: 'en-US',
+      platform: '',
+      userLanguage: null,
+      systemLanguage: null,
+      timezone: 300,
+    },
+  },
+};
+
+export const expectedJsdomWithoutDisplay = {
+  identifier: '',
+  metadata: {
+    hardware: {
+      display: {},
+      cpuClass: null,
+      deviceMemory: null,
+      hardwareConcurrency: 16,
+      maxTouchPoints: null,
+      oscpu: null,
+    },
+    browser: {
+      appName: 'Netscape',
+      userAgent: 'Mozilla/5.0 (darwin) AppleWebKit/537.36 (KHTML, like Gecko) jsdom/16.2.2',
+      appCodeName: 'Mozilla',
+      appVersion: '4.0',
+      appMinorVersion: null,
+      buildID: null,
+      product: 'Gecko',
+      productSub: '20030107',
+      vendor: 'Apple Computer, Inc.',
+      vendorSub: '',
+      browserLanguage: null,
+      plugins: '',
+    },
+    platform: {
+      deviceName: 'Unknown (Browser)',
+      fonts: '',
+      language: 'en-US',
+      platform: '',
+      userLanguage: null,
+      systemLanguage: null,
+      timezone: 300,
+    },
+  },
+};
+
+export const expectedJsdomWithNarrowedBrowserProps = {
+  identifier: '',
+  metadata: {
+    hardware: {
+      display: {
+        width: 0,
+        height: 0,
+        pixelDepth: 24,
+        angle: '',
+      },
+      cpuClass: null,
+      deviceMemory: null,
+      hardwareConcurrency: 16,
+      maxTouchPoints: null,
+      oscpu: null,
+    },
+    browser: {
+      userAgent: 'Mozilla/5.0 (darwin) AppleWebKit/537.36 (KHTML, like Gecko) jsdom/16.2.2',
+      plugins: '',
+    },
+    platform: {
+      deviceName: 'Unknown (Browser)',
+      fonts: '',
+      language: 'en-US',
+      platform: '',
+      userLanguage: null,
+      systemLanguage: null,
+      timezone: 300,
+    },
+  },
+};

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

@@ -0,0 +1,128 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * device-profile.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 { vi, expect, describe, it, afterEach, beforeEach, SpyInstance } from 'vitest';
+
+import { Device } from './device-profile.js';
+
+// Patch window.crypto.getRandomValues to return Uint32Array for compatibility
+Object.defineProperty(window, 'crypto', {
+  writable: true,
+  value: {
+    getRandomValues: vi.fn().mockImplementation((arr: Uint32Array) => {
+      arr[0] = 714524572;
+      arr[1] = 2799534390;
+      arr[2] = 3707617532;
+      return arr;
+    }),
+  },
+});
+
+describe('Test DeviceProfile', () => {
+  it('should return basic metadata', async () => {
+    const device = new Device();
+    const profile = await device.getProfile({
+      location: false,
+      metadata: true,
+    });
+    if (!profile.metadata) throw new Error('Metadata is not defined');
+    const userAgent = profile.metadata.browser.userAgent as string;
+    const appName = profile.metadata.browser.appName as string;
+    const appVersion = profile.metadata.browser.appVersion as string;
+    const vendor = profile.metadata.browser.vendor as string;
+    const display = profile.metadata.hardware.display;
+    const deviceName = profile.metadata.platform.deviceName as string;
+    expect(userAgent.includes('jsdom')).toBeTruthy();
+    expect(appName).toBe('Netscape');
+    expect(appVersion).toBe('4.0');
+    expect(vendor).toBe('Apple Computer, Inc.');
+    expect(display).toHaveProperty('width');
+    expect(display).toHaveProperty('height');
+    expect(deviceName.length).toBeGreaterThan(1);
+  });
+
+  it('should return metadata without any display props', async () => {
+    const device = new Device({ displayProps: [] });
+    const profile = await device.getProfile({
+      location: false,
+      metadata: true,
+    });
+    if (!profile.metadata) throw new Error('Metadata is not defined');
+    const userAgent = profile.metadata.browser.userAgent as string;
+    const display = profile.metadata.hardware.display;
+    const deviceName = profile.metadata.platform.deviceName as string;
+    expect(userAgent.length).toBeGreaterThan(1);
+    expect(display.width).toBeFalsy();
+    expect(display.height).toBeFalsy();
+    expect(deviceName.length).toBeGreaterThan(1);
+  });
+
+  it('should return metadata according to narrowed browser props', async () => {
+    const device = new Device({ browserProps: ['userAgent'] });
+    const profile = await device.getProfile({
+      location: false,
+      metadata: true,
+    });
+    if (!profile.metadata) throw new Error('Metadata is not defined');
+    const userAgent = profile.metadata.browser.userAgent as string;
+    const appName = profile.metadata.browser.appName as string;
+    const appVersion = profile.metadata.browser.appVersion as string;
+    const vendor = profile.metadata.browser.vendor as string;
+    const display = profile.metadata.hardware.display;
+    const deviceName = profile.metadata.platform.deviceName as string;
+    expect(userAgent.includes('jsdom')).toBeTruthy();
+    expect(appName).toBeFalsy();
+    expect(appVersion).toBeFalsy();
+    expect(vendor).toBeFalsy();
+    expect(display).toHaveProperty('width');
+    expect(display).toHaveProperty('height');
+    expect(deviceName.length).toBeGreaterThan(1);
+  });
+
+  describe('logLevel tests', () => {
+    let warnSpy: SpyInstance;
+    const originalNavigator = global.navigator;
+
+    beforeEach(() => {
+      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      delete global.navigator;
+    });
+
+    afterEach(() => {
+      warnSpy.mockRestore();
+      global.navigator = originalNavigator;
+    });
+
+    it('should not log warnings if logLevel is "error"', () => {
+      const device = new Device(undefined, 'error');
+      device.getBrowserMeta();
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should log warnings if logLevel is "warn"', () => {
+      const device = new Device(undefined, 'warn');
+      device.getBrowserMeta();
+      expect(warnSpy).toHaveBeenCalledWith(
+        'Cannot collect browser metadata. navigator is not defined.',
+      );
+    });
+  });
+
+  it('should use custom prefix for device identifier', () => {
+    const setItemSpy = vi.spyOn(Storage.prototype, 'setItem');
+    const device = new Device(undefined, 'info', 'my-custom-prefix');
+    device.getIdentifier();
+
+    expect(setItemSpy).toHaveBeenCalledWith('my-custom-prefix-DeviceID', expect.any(String));
+
+    setItemSpy.mockRestore();
+  });
+});

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

@@ -0,0 +1,287 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * index.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 { reduceToObject, reduceToString } from '@forgerock/sdk-utilities';
+import { logger as loggerFn } from '@forgerock/sdk-logger';
+
+import type { LogLevel } from '@forgerock/sdk-logger';
+
+import {
+  browserProps,
+  configurableCategories,
+  delay,
+  devicePlatforms,
+  displayProps,
+  fontNames,
+  hardwareProps,
+  platformProps,
+} from './defaults.js';
+
+import type {
+  BaseProfileConfig,
+  Category,
+  CollectParameters,
+  DeviceProfileData,
+  Geolocation,
+  ProfileConfigOptions,
+} from './interfaces.js';
+
+type Logger = ReturnType<typeof loggerFn>;
+
+/**
+ * @class JourneyDevice - Collects user device metadata.
+ *
+ * Example:
+ *
+ * ```js
+ * // Instantiate new device object (w/optional config, if needed)
+ * const device = new Device({
+ *   // optional configuration
+ * });
+ *
+ * // Call getProfile with required argument obj of boolean properties
+ * // of location and metadata
+ * const profile = await device.getProfile({
+ *   location: isLocationRequired,
+ *   metadata: isMetadataRequired,
+ * });
+ * ```
+ */
+export class Device {
+  private config: BaseProfileConfig;
+  private logger: Logger;
+  private prefix: string;
+
+  constructor(
+    configOptions?: ProfileConfigOptions,
+    logLevel: LogLevel = 'info',
+    prefix = 'forgerock',
+  ) {
+    this.logger = loggerFn({ level: logLevel });
+    this.prefix = prefix;
+    this.config = {
+      fontNames,
+      devicePlatforms,
+      displayProps,
+      browserProps,
+      hardwareProps,
+      platformProps,
+    };
+
+    if (configOptions) {
+      Object.keys(configOptions).forEach((key: string) => {
+        if (!configurableCategories.includes(key)) {
+          throw new Error('Device profile configuration category does not exist.');
+        }
+        this.config[key as Category] = configOptions[key as Category] as string[];
+      });
+    }
+  }
+
+  public getBrowserMeta(): Record<string, string | number | null> {
+    if (typeof navigator === 'undefined') {
+      this.logger.warn('Cannot collect browser metadata. navigator is not defined.');
+      return {};
+    }
+    return reduceToObject(
+      this.config.browserProps,
+      navigator as unknown as Record<string, unknown>,
+    );
+  }
+
+  public getBrowserPluginsNames(): string {
+    if (!(typeof navigator !== 'undefined' && navigator.plugins)) {
+      this.logger.warn(
+        'Cannot collect browser plugin information. navigator.plugins is not defined.',
+      );
+      return '';
+    }
+    return reduceToString(
+      Object.keys(navigator.plugins),
+      navigator.plugins as unknown as Record<string, { filename: string }>,
+    );
+  }
+
+  public getDeviceName(): string {
+    if (typeof navigator === 'undefined') {
+      this.logger.warn('Cannot collect device name. navigator is not defined.');
+      return '';
+    }
+    const userAgent = navigator.userAgent;
+    const platform = navigator.platform;
+
+    switch (true) {
+      case this.config.devicePlatforms.mac.includes(platform):
+        return 'Mac (Browser)';
+      case this.config.devicePlatforms.ios.includes(platform):
+        return `${platform} (Browser)`;
+      case this.config.devicePlatforms.windows.includes(platform):
+        return 'Windows (Browser)';
+      case /Android/.test(platform) || /Android/.test(userAgent):
+        return 'Android (Browser)';
+      case /CrOS/.test(userAgent) || /Chromebook/.test(userAgent):
+        return 'Chrome OS (Browser)';
+      case /Linux/.test(platform):
+        return 'Linux (Browser)';
+      default:
+        return `${platform || 'Unknown'} (Browser)`;
+    }
+  }
+
+  public getDisplayMeta(): { [key: string]: string | number | null } {
+    if (typeof screen === 'undefined') {
+      this.logger.warn('Cannot collect screen information. screen is not defined.');
+      return {};
+    }
+    return reduceToObject(this.config.displayProps, screen as unknown as Record<string, unknown>);
+  }
+
+  public getHardwareMeta(): Record<string, string | number | null> {
+    if (typeof navigator === 'undefined') {
+      this.logger.warn('Cannot collect OS metadata. Navigator is not defined.');
+      return {};
+    }
+    return reduceToObject(
+      this.config.hardwareProps,
+      navigator as unknown as Record<string, unknown>,
+    );
+  }
+
+  public getIdentifier(): string {
+    const storageKey = `${this.prefix}-DeviceID`;
+
+    if (!(typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues)) {
+      this.logger.warn(
+        'Cannot generate profile ID. Crypto and/or getRandomValues is not supported.',
+      );
+      return '';
+    }
+    if (!localStorage) {
+      this.logger.warn('Cannot store profile ID. localStorage is not supported.');
+      return '';
+    }
+    let id = localStorage.getItem(storageKey);
+    if (!id) {
+      // generate ID, 3 sections of random numbers: "714524572-2799534390-3707617532"
+      id = globalThis.crypto.getRandomValues(new Uint32Array(3)).join('-');
+      localStorage.setItem(storageKey, id);
+    }
+    return id;
+  }
+
+  public getInstalledFonts(): string {
+    if (typeof document === 'undefined') {
+      this.logger.warn('Cannot collect font data. Global document object is undefined.');
+      return '';
+    }
+    const canvas = document.createElement('canvas');
+    if (!canvas) {
+      this.logger.warn('Cannot collect font data. Browser does not support canvas element');
+      return '';
+    }
+    const context = canvas.getContext && canvas.getContext('2d');
+
+    if (!context) {
+      this.logger.warn('Cannot collect font data. Browser does not support 2d canvas context');
+      return '';
+    }
+    const text = 'abcdefghi0123456789';
+    context.font = '72px Comic Sans';
+    const baseWidth = context.measureText(text).width;
+
+    const installedFonts = this.config.fontNames.reduce((prev: string, curr: string) => {
+      context.font = `72px ${curr}, Comic Sans`;
+      const newWidth = context.measureText(text).width;
+
+      if (newWidth !== baseWidth) {
+        prev = `${prev}${curr};`;
+      }
+      return prev;
+    }, '');
+
+    return installedFonts;
+  }
+
+  public async getLocationCoordinates(): Promise<Geolocation | Record<string, unknown>> {
+    if (!(typeof navigator !== 'undefined' && navigator.geolocation)) {
+      this.logger.warn(
+        'Cannot collect geolocation information. navigator.geolocation is not defined.',
+      );
+      return Promise.resolve({});
+    }
+    return new Promise((resolve) => {
+      navigator.geolocation.getCurrentPosition(
+        (position) =>
+          resolve({
+            latitude: position.coords.latitude,
+            longitude: position.coords.longitude,
+          }),
+        () => {
+          this.logger.warn('Cannot collect geolocation information. Geolocation API error.');
+          resolve({});
+        },
+        {
+          enableHighAccuracy: true,
+          timeout: delay,
+          maximumAge: 0,
+        },
+      );
+    });
+  }
+
+  public getOSMeta(): Record<string, string | number | null> {
+    if (typeof navigator === 'undefined') {
+      this.logger.warn('Cannot collect OS metadata. navigator is not defined.');
+      return {};
+    }
+    return reduceToObject(
+      this.config.platformProps,
+      navigator as unknown as Record<string, unknown>,
+    );
+  }
+
+  public getTimezoneOffset(): number | null {
+    try {
+      return new Date().getTimezoneOffset();
+    } catch {
+      this.logger.warn('Cannot collect timezone information. getTimezoneOffset is not defined.');
+      return null;
+    }
+  }
+
+  public async getProfile({ location, metadata }: CollectParameters): Promise<DeviceProfileData> {
+    const profile: DeviceProfileData = {
+      identifier: this.getIdentifier(),
+    };
+
+    if (metadata) {
+      profile.metadata = {
+        hardware: {
+          ...this.getHardwareMeta(),
+          display: this.getDisplayMeta(),
+        },
+        browser: {
+          ...this.getBrowserMeta(),
+          plugins: this.getBrowserPluginsNames(),
+        },
+        platform: {
+          ...this.getOSMeta(),
+          deviceName: this.getDeviceName(),
+          fonts: this.getInstalledFonts(),
+          timezone: this.getTimezoneOffset(),
+        },
+      };
+    }
+    if (location) {
+      profile.location = await this.getLocationCoordinates();
+    }
+    return profile;
+  }
+}

package/src/lib/device/interfaces.ts

@@ -0,0 +1,63 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * interfaces.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 type Category =
+  | 'fontNames'
+  | 'displayProps'
+  | 'browserProps'
+  | 'hardwareProps'
+  | 'platformProps';
+
+export interface CollectParameters {
+  location: boolean;
+  metadata: boolean;
+}
+
+export interface DeviceProfileData {
+  identifier: string;
+  metadata?: {
+    hardware: {
+      display: {
+        [key: string]: string | number | null;
+      };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      [key: string]: any;
+    };
+    browser: {
+      [key: string]: string | number | null;
+    };
+    platform: {
+      [key: string]: string | number | null;
+    };
+  };
+  location?: Geolocation | Record<string, unknown>;
+}
+
+export interface Geolocation {
+  latitude: number;
+  longitude: number;
+}
+
+export interface BaseProfileConfig {
+  fontNames: string[];
+  devicePlatforms: {
+    mac: string[];
+    windows: string[];
+    ios: string[];
+  };
+  displayProps: string[];
+  browserProps: string[];
+  hardwareProps: string[];
+  platformProps: string[];
+}
+
+export interface ProfileConfigOptions {
+  [key: string]: string[];
+}

package/src/lib/device/sample-profile.json

@@ -0,0 +1,45 @@
+{
+  "identifier": "714524572-2799534390-3707617532",
+  "metadata": {
+    "hardware": {
+      "cpuClass": null,
+      "deviceMemory": 8,
+      "hardwareConcurrency": 16,
+      "maxTouchPoints": 0,
+      "oscpu": null,
+      "display": {
+        "width": 1080,
+        "height": 1920,
+        "pixelDepth": 24,
+        "angle": 270
+      }
+    },
+    "browser": {
+      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.163 Safari/537.36 Edg/80.0.361.111",
+      "appName": "Netscape",
+      "appCodeName": "Mozilla",
+      "appVersion": "5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.163 Safari/537.36 Edg/80.0.361.111",
+      "appMinorVersion": null,
+      "buildID": null,
+      "product": "Gecko",
+      "productSub": "20030107",
+      "vendor": "Google Inc.",
+      "vendorSub": "",
+      "browserLanguage": null,
+      "plugins": "internal-pdf-viewer;mhjfbmdgcfjbbpaeojofohoefgiehjai;internal-nacl-plugin;"
+    },
+    "platform": {
+      "deviceName": "Mac (Browser)",
+      "language": "en-US",
+      "platform": "MacIntel",
+      "userLanguage": null,
+      "systemLanguage": null,
+      "fonts": "cursive;monospace;sans-serif;fantasy;Arial;Arial Black;Arial Narrow;Arial Rounded MT Bold;Comic Sans MS;Courier;Courier New;Georgia;Impact;Papyrus;Tahoma;Trebuchet MS;Verdana;",
+      "timezone": 300
+    }
+  },
+  "location": {
+    "latitude": 27.766237,
+    "longitude": -94.889905
+  }
+}

package/src/lib/interfaces.ts

@@ -0,0 +1,25 @@
+/*
+ * 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 { JourneyClientConfig } from './config.types.js';
+import { JourneyStep } from './step.types.js';
+
+export interface StartParam extends JourneyClientConfig {
+  journey: string;
+  query?: Record<string, string>;
+}
+
+export interface ResumeOptions extends JourneyClientConfig {
+  journey?: string;
+  query?: Record<string, string>;
+}
+
+export interface NextOptions extends JourneyClientConfig {
+  query?: Record<string, string>;
+}
+
+export type { JourneyStep };