SDKS-5067: Standardize SDK Configuration

.changeset/sdks-5067-unified-config.md

@@ -0,0 +1,41 @@
+---
+'@forgerock/sdk-utilities': minor
+'@forgerock/sdk-types': minor
+'@forgerock/sdk-oidc': minor
+'@forgerock/oidc-client': minor
+'@forgerock/journey-client': minor
+'@forgerock/davinci-client': minor
+---
+
+Add unified cross-platform SDK configuration support
+
+All three client factories (`oidc`, `journey`, `davinci`) now accept the cross-platform unified JSON config schema alongside the existing internal config shape. Pass a unified config object and the factory maps, validates, and rejects on invalid input.
+
+**New in `@forgerock/sdk-utilities`:**
+
+- `UnifiedSdkConfig`, `UnifiedOidcConfig`, `UnifiedJourneyConfig` types
+- `validateUnifiedSdkConfig` / `validateUnifiedOidcConfig` — pure validation returning `ConfigValidationResult<T>` (no throws)
+- `unifiedToOidcConfig`, `unifiedToJourneyConfig`, `unifiedToDavinciConfig` — pure mapping functions
+- `isUnifiedSdkConfig` discriminator (`'oidc' in input || 'journey' in input`)
+
+**New in `@forgerock/sdk-types`:**
+
+- `GetAuthorizationUrlOptions` extended with `loginHint`, `nonce`, `display`, `uiLocales`, `acrValues`; `prompt` widened to include `'select_account'`
+
+**New in `@forgerock/sdk-oidc`:**
+
+- `buildAuthorizeParams` forwards all new OIDC authorize params into the URL
+
+**New in `@forgerock/oidc-client`:**
+
+- `oidc()` factory accepts unified JSON config; rejects Promise on validation failure
+- `endSession` appends `post_logout_redirect_uri` when `signOutRedirectUri` is set
+- Authorize URL construction forwards `loginHint`, `state`, `nonce`, `display`, `prompt`, `uiLocales`, `acrValues`, `additionalParameters`
+
+**New in `@forgerock/journey-client`:**
+
+- `journey()` factory accepts unified JSON config; throws on validation failure
+
+**New in `@forgerock/davinci-client`:**
+
+- `davinci()` factory accepts unified JSON config; throws on validation failure

packages/davinci-client/api-report/davinci-client.api.md

@@ -275,7 +275,7 @@ export type CustomPollingStatus = string & {};
 
 // @public
 export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
-    config: DaVinciConfig;
+    config: DaVinciConfig | Record<string, unknown>;
     requestMiddleware?: RequestMiddleware<ActionType>[];
     logger?: {
         level: LogLevel;
@@ -289,11 +289,13 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
     resume: (input: {
         continueToken: string;
     }) => Promise<InternalErrorResponse | NodeStates>;
-    start: <QueryParams extends OutgoingQueryParams = OutgoingQueryParams>(options?: StartOptions<QueryParams> | undefined) => Promise<ContinueNode | ErrorNode | FailureNode | StartNode | SuccessNode>;
+    start: <QueryParams extends OutgoingQueryParams = OutgoingQueryParams>(options?: StartOptions<QueryParams> | undefined) => Promise<ContinueNode | StartNode | ErrorNode | FailureNode | SuccessNode>;
     update: <T extends SingleValueCollectors | MultiSelectCollector | ObjectValueCollectors | AutoCollectors>(collector: T) => Updater<T>;
     validate: (collector: SingleValueCollectors | ObjectValueCollectors | MultiValueCollectors | AutoCollectors) => Validator;
     pollStatus: (collector: PollingCollector) => Poller;
     getClient: () => {
+        status: "start";
+    } | {
         action: string;
         collectors: Collectors[];
         description?: string;
@@ -307,8 +309,6 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         status: "error";
     } | {
         status: "failure";
-    } | {
-        status: "start";
     } | {
         authorization?: {
             code?: string;
@@ -319,7 +319,7 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
     getCollectors: () => Collectors[];
     getError: () => DaVinciError | null;
     getErrorCollectors: () => CollectorErrors[];
-    getNode: () => ContinueNode | ErrorNode | FailureNode | StartNode | SuccessNode;
+    getNode: () => ContinueNode | StartNode | ErrorNode | FailureNode | SuccessNode;
     getServer: () => {
         _links?: Links;
         id?: string;
@@ -328,6 +328,8 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         href?: string;
         eventName?: string;
         status: "continue";
+    } | {
+        status: "start";
     } | {
         _links?: Links;
         eventName?: string;
@@ -343,8 +345,6 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         interactionId?: string;
         interactionToken?: string;
         status: "failure";
-    } | {
-        status: "start";
     } | {
         _links?: Links;
         eventName?: string;
@@ -508,6 +508,8 @@ export type DavinciClient = Awaited<ReturnType<typeof davinci>>;
 
 // @public (undocumented)
 export interface DaVinciConfig extends AsyncLegacyConfigOptions {
+    // (undocumented)
+    log?: LogLevel;
     // (undocumented)
     responseType?: string;
 }

packages/davinci-client/api-report/davinci-client.types.api.md

@@ -275,7 +275,7 @@ export type CustomPollingStatus = string & {};
 
 // @public
 export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
-    config: DaVinciConfig;
+    config: DaVinciConfig | Record<string, unknown>;
     requestMiddleware?: RequestMiddleware<ActionType>[];
     logger?: {
         level: LogLevel;
@@ -289,11 +289,13 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
     resume: (input: {
         continueToken: string;
     }) => Promise<InternalErrorResponse | NodeStates>;
-    start: <QueryParams extends OutgoingQueryParams = OutgoingQueryParams>(options?: StartOptions<QueryParams> | undefined) => Promise<ContinueNode | ErrorNode | FailureNode | StartNode | SuccessNode>;
+    start: <QueryParams extends OutgoingQueryParams = OutgoingQueryParams>(options?: StartOptions<QueryParams> | undefined) => Promise<ContinueNode | StartNode | ErrorNode | FailureNode | SuccessNode>;
     update: <T extends SingleValueCollectors | MultiSelectCollector | ObjectValueCollectors | AutoCollectors>(collector: T) => Updater<T>;
     validate: (collector: SingleValueCollectors | ObjectValueCollectors | MultiValueCollectors | AutoCollectors) => Validator;
     pollStatus: (collector: PollingCollector) => Poller;
     getClient: () => {
+        status: "start";
+    } | {
         action: string;
         collectors: Collectors[];
         description?: string;
@@ -307,8 +309,6 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         status: "error";
     } | {
         status: "failure";
-    } | {
-        status: "start";
     } | {
         authorization?: {
             code?: string;
@@ -319,7 +319,7 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
     getCollectors: () => Collectors[];
     getError: () => DaVinciError | null;
     getErrorCollectors: () => CollectorErrors[];
-    getNode: () => ContinueNode | ErrorNode | FailureNode | StartNode | SuccessNode;
+    getNode: () => ContinueNode | StartNode | ErrorNode | FailureNode | SuccessNode;
     getServer: () => {
         _links?: Links;
         id?: string;
@@ -328,6 +328,8 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         href?: string;
         eventName?: string;
         status: "continue";
+    } | {
+        status: "start";
     } | {
         _links?: Links;
         eventName?: string;
@@ -343,8 +345,6 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         interactionId?: string;
         interactionToken?: string;
         status: "failure";
-    } | {
-        status: "start";
     } | {
         _links?: Links;
         eventName?: string;
@@ -508,6 +508,8 @@ export type DavinciClient = Awaited<ReturnType<typeof davinci>>;
 
 // @public (undocumented)
 export interface DaVinciConfig extends AsyncLegacyConfigOptions {
+    // (undocumented)
+    log?: LogLevel;
     // (undocumented)
     responseType?: string;
 }

packages/davinci-client/src/lib/client.store.test.ts

@@ -181,3 +181,59 @@ describe('davinci client — cache', () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+
+describe('unified JSON config entry', () => {
+  beforeEach(() => {
+    vi.stubGlobal('localStorage', makeStorageStub());
+    vi.stubGlobal('sessionStorage', makeStorageStub());
+    mockFetchImplementation();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('accepts unified JSON config and initializes successfully', async () => {
+    const unifiedConfig = {
+      oidc: {
+        clientId: '123456789',
+        discoveryEndpoint: TEST_WELLKNOWN_URL,
+        scopes: ['openid', 'profile'],
+        redirectUri: 'https://example.com/callback',
+      },
+    } as unknown as DaVinciConfig;
+
+    const client = await davinci({ config: unifiedConfig });
+    expect(client).toHaveProperty('flow');
+    expect(client).toHaveProperty('subscribe');
+  });
+
+  it('throws when unified JSON config has missing required field', async () => {
+    const invalidConfig = {
+      oidc: {
+        // clientId missing
+        discoveryEndpoint: TEST_WELLKNOWN_URL,
+        scopes: ['openid'],
+        redirectUri: 'https://example.com/callback',
+      },
+    } as unknown as DaVinciConfig;
+
+    await expect(davinci({ config: invalidConfig })).rejects.toThrow(/Invalid unified SDK config/);
+  });
+
+  it('throws when unified JSON config has wrong field type', async () => {
+    const invalidConfig = {
+      oidc: {
+        clientId: '123',
+        discoveryEndpoint: TEST_WELLKNOWN_URL,
+        scopes: 'openid', // should be array
+        redirectUri: 'https://example.com/callback',
+      },
+    } as unknown as DaVinciConfig;
+
+    await expect(davinci({ config: invalidConfig })).rejects.toThrow(/Invalid unified SDK config/);
+  });
+});

packages/davinci-client/src/lib/client.store.ts

@@ -8,7 +8,13 @@ import { Micro } from 'effect';
 import { exitIsFail, exitIsSuccess } from 'effect/Micro';
 import { type CustomLogger, logger as loggerFn, type LogLevel } from '@forgerock/sdk-logger';
 import { createStorage } from '@forgerock/storage';
-import { isGenericError, createWellknownError } from '@forgerock/sdk-utilities';
+import {
+  isGenericError,
+  isUnifiedSdkConfig,
+  unifiedToDavinciConfig,
+  validateUnifiedSdkConfig,
+  createWellknownError,
+} from '@forgerock/sdk-utilities';
 
 /**
  * Import RTK slices and api
@@ -66,18 +72,38 @@ import type { ContinueNode, StartNode } from './node.types.js';
  * @returns {Observable} - an observable client for DaVinci flows
  */
 export async function davinci<ActionType extends ActionTypes = ActionTypes>({
-  config,
+  config: rawConfig,
   requestMiddleware,
   logger,
 }: {
-  config: DaVinciConfig;
+  config: DaVinciConfig | Record<string, unknown>;
   requestMiddleware?: RequestMiddleware<ActionType>[];
   logger?: {
     level: LogLevel;
     custom?: CustomLogger;
   };
 }) {
-  const log = loggerFn({ level: logger?.level || 'error', custom: logger?.custom });
+  let config: DaVinciConfig;
+
+  if (isUnifiedSdkConfig(rawConfig)) {
+    const validation = validateUnifiedSdkConfig(rawConfig, true);
+    if (!validation.success) {
+      const messages = validation.errors.map((e) => `${e.field}: ${e.message}`).join(', ');
+      throw new Error(`Invalid unified SDK config: ${messages}`);
+    }
+    const mapped = unifiedToDavinciConfig(validation.data);
+    if (!mapped.success) {
+      throw new Error(`Invalid unified SDK config: ${mapped.error.field}: ${mapped.error.message}`);
+    }
+    config = mapped.data as DaVinciConfig;
+  } else {
+    config = rawConfig as DaVinciConfig;
+  }
+
+  const log = loggerFn({
+    level: logger?.level ?? config.log ?? 'error',
+    custom: logger?.custom,
+  });
   const store = createClientStore({ requestMiddleware, logger: log });
   const serverInfo = createStorage<ContinueNode['server']>({
     type: 'localStorage',

packages/davinci-client/src/lib/config.types.ts

@@ -6,9 +6,11 @@
  */
 
 import type { AsyncLegacyConfigOptions, WellknownResponse } from '@forgerock/sdk-types';
+import type { LogLevel } from '@forgerock/sdk-logger';
 
 export interface DaVinciConfig extends AsyncLegacyConfigOptions {
   responseType?: string;
+  log?: LogLevel;
 }
 
 export interface InternalDaVinciConfig extends DaVinciConfig {

packages/journey-client/api-report/journey-client.api.md

@@ -176,7 +176,7 @@ export { isValidWellknownUrl }
 
 // @public
 export function journey<ActionType extends ActionTypes = ActionTypes>(input: {
-    config: JourneyClientConfig;
+    config: JourneyClientConfig | Record<string, unknown>;
     requestMiddleware?: RequestMiddleware<ActionType>[];
     logger?: {
         level: LogLevel;
@@ -204,6 +204,8 @@ export interface JourneyClient {
 
 // @public
 export interface JourneyClientConfig extends AsyncLegacyConfigOptions {
+    // (undocumented)
+    log?: LogLevel;
     // (undocumented)
     serverConfig: JourneyServerConfig;
 }

packages/journey-client/api-report/journey-client.types.api.md

@@ -191,6 +191,8 @@ export interface JourneyClient {
 
 // @public
 export interface JourneyClientConfig extends AsyncLegacyConfigOptions {
+    // (undocumented)
+    log?: LogLevel;
     // (undocumented)
     serverConfig: JourneyServerConfig;
 }

packages/journey-client/src/lib/client.store.test.ts

@@ -502,4 +502,50 @@ describe('journey-client', () => {
       expect(request.url).toBe('https://test.com/am/json/realms/root/realms/alpha/authenticate');
     });
   });
+
+  describe('unified JSON config entry', () => {
+    test('accepts unified JSON config and initializes successfully', async () => {
+      setupMockFetch();
+
+      const unifiedConfig = {
+        oidc: {
+          clientId: 'ignored-by-journey',
+          discoveryEndpoint: mockWellknownUrl,
+          scopes: ['openid'],
+          redirectUri: 'https://example.com/callback',
+        },
+      } as unknown as JourneyClientConfig;
+
+      const client = await journey({ config: unifiedConfig });
+      expect(client).toHaveProperty('start');
+      expect(client).toHaveProperty('next');
+    });
+
+    test('throws when unified JSON config has missing required field', async () => {
+      const invalidConfig = {
+        oidc: {
+          // discoveryEndpoint missing — required even for journey
+        },
+      } as unknown as JourneyClientConfig;
+
+      await expect(journey({ config: invalidConfig })).rejects.toThrow(
+        /Invalid unified SDK config/,
+      );
+    });
+
+    test('throws when unified JSON config has wrong field type', async () => {
+      const invalidConfig = {
+        oidc: {
+          clientId: '123',
+          discoveryEndpoint: mockWellknownUrl,
+          scopes: 'openid', // should be array
+          redirectUri: 'https://example.com/callback',
+        },
+      } as unknown as JourneyClientConfig;
+
+      await expect(journey({ config: invalidConfig })).rejects.toThrow(
+        /Invalid unified SDK config/,
+      );
+    });
+  });
 });