Merge pull request #563 from ForgeRock/SDKS-4687-polling

feat(davinci-client): add polling support (SDKS-4687)

Author: ancheetah

.changeset/lucky-parts-own.md

@@ -0,0 +1,6 @@
+---
+'@forgerock/sdk-request-middleware': minor
+'@forgerock/davinci-client': minor
+---
+
+Support both challenge polling and continue polling in DaVinci

e2e/davinci-app/components/polling.ts

@@ -0,0 +1,57 @@
+/*
+ * 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 { PollingCollector, Poller, Updater } from '@forgerock/davinci-client/types';
+
+export default function pollingComponent(
+  formEl: HTMLFormElement,
+  collector: PollingCollector,
+  poll: Poller,
+  updater: Updater<PollingCollector>,
+  submitForm: () => Promise<void>,
+) {
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.value = collector.output.key;
+  button.innerHTML = 'Start polling';
+  formEl.appendChild(button);
+
+  button.onclick = async () => {
+    button.disabled = true;
+
+    const p = document.createElement('p');
+    p.innerText = 'Polling...';
+    formEl?.appendChild(p);
+
+    const status = await poll();
+    if (typeof status !== 'string' && 'error' in status) {
+      console.error(status.error?.message);
+
+      const errEl = document.createElement('p');
+      errEl.innerText = 'Polling error: ' + status.error?.message;
+      formEl?.appendChild(errEl);
+      return;
+    }
+
+    const result = updater(status);
+    if (result && 'error' in result) {
+      console.error(result.error.message);
+
+      const errEl = document.createElement('p');
+      errEl.innerText = 'Polling error: ' + result.error.message;
+      formEl?.appendChild(errEl);
+      return;
+    }
+
+    const resultEl = document.createElement('p');
+    resultEl.innerText = 'Polling result: ' + JSON.stringify(status, null, 2);
+    formEl?.appendChild(resultEl);
+
+    await submitForm();
+
+    button.disabled = false;
+  };
+}

e2e/davinci-app/main.ts

@@ -33,6 +33,7 @@ import labelComponent from './components/label.js';
 import objectValueComponent from './components/object-value.js';
 import fidoComponent from './components/fido.js';
 import qrCodeComponent from './components/qr-code.js';
+import pollingComponent from './components/polling.js';
 
 const loggerFn = {
   error: () => {
@@ -265,6 +266,14 @@ const urlParams = new URLSearchParams(window.location.search);
           davinciClient.update(collector), // Returns an update function for this collector
           submitForm,
         );
+      } else if (collector.type === 'PollingCollector') {
+        pollingComponent(
+          formEl, // You can ignore this; it's just for rendering
+          collector, // This is the plain object of the collector
+          davinciClient.poll(collector), // Returns a poll function
+          davinciClient.update(collector), // Returns an update function for this collector
+          submitForm,
+        );
       } else if (collector.type === 'FlowCollector') {
         flowLinkComponent(
           formEl, // You can ignore this; it's just for rendering

package.json

@@ -13,7 +13,7 @@
   },
   "author": "ForgeRock",
   "scripts": {
-    "build": "nx affected --target=build",
+    "build": "nx sync && nx affected --target=build",
     "changeset": "changeset",
     "ci:release": "pnpm nx run-many -t build --no-agents && pnpm publish -r --no-git-checks && changeset tag",
     "ci:version": "changeset version && pnpm install --no-frozen-lockfile && pnpm nx format:write --uncommitted",

packages/davinci-client/package.json

@@ -34,6 +34,7 @@
     "immer": "catalog:"
   },
   "devDependencies": {
+    "@effect/vitest": "catalog:effect",
     "vitest": "catalog:vitest"
   },
   "publishConfig": {

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

@@ -0,0 +1,282 @@
+/*
+ * Copyright (c) 2026 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 { Micro } from 'effect';
+import { describe, expect, vi } from 'vitest';
+import { it } from '@effect/vitest';
+
+import {
+  buildChallengeEndpoint,
+  isChallengeStillPending,
+  interpretChallengeResponse,
+  getPollingModeµ,
+} from './client.store.effects.js';
+import type { PollDispatchResult } from './client.store.effects.js';
+import type { PollingCollector } from './collector.types.js';
+
+const mockLog = {
+  debug: vi.fn(),
+  error: vi.fn(),
+  warn: vi.fn(),
+  info: vi.fn(),
+} as any;
+
+// ---------------------------------------------------------------------------
+// buildChallengeEndpoint
+// ---------------------------------------------------------------------------
+
+describe('buildChallengeEndpoint', () => {
+  it('returns a constructed URL string for a valid self link', () => {
+    const selfHref =
+      'https://auth.pingone.ca/3b2b0d54-99f9-4c28-b57e-d4e66e8e72c2/davinci/orchestrate';
+    const challenge = 'abc123';
+
+    const result = buildChallengeEndpoint(selfHref, challenge);
+
+    expect(result).toBe(
+      'https://auth.pingone.ca/3b2b0d54-99f9-4c28-b57e-d4e66e8e72c2/davinci/user/credentials/challenge/abc123/status',
+    );
+  });
+
+  it('returns InternalErrorResponse when envId is missing from URL path', () => {
+    // pathname is just '/' → split gives ['', ''] → envId is empty string → falsy
+    const selfHref = 'https://auth.pingone.ca/';
+    const challenge = 'abc123';
+
+    const result = buildChallengeEndpoint(selfHref, challenge);
+
+    expect(typeof result).toBe('object');
+    expect((result as any).type).toBe('internal_error');
+  });
+
+  it('returns InternalErrorResponse for a completely invalid URL', () => {
+    const result = buildChallengeEndpoint('not-a-url', 'abc123');
+
+    expect(typeof result).toBe('object');
+    expect((result as any).type).toBe('internal_error');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isChallengeStillPending
+// ---------------------------------------------------------------------------
+
+describe('isChallengeStillPending', () => {
+  it('returns false when response has an error', () => {
+    const response: PollDispatchResult = { error: { status: 400, data: {} } };
+    expect(isChallengeStillPending(response)).toBe(false);
+  });
+
+  it('returns false when isChallengeComplete is true', () => {
+    const response: PollDispatchResult = {
+      data: { isChallengeComplete: true, status: 'approved' },
+    };
+    expect(isChallengeStillPending(response)).toBe(false);
+  });
+
+  it('returns true when challenge is still pending', () => {
+    const response: PollDispatchResult = { data: { isChallengeComplete: false } };
+    expect(isChallengeStillPending(response)).toBe(true);
+  });
+
+  it('returns true when data has no isChallengeComplete field', () => {
+    const response: PollDispatchResult = { data: { someOtherField: 'value' } };
+    expect(isChallengeStillPending(response)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// interpretChallengeResponse
+// ---------------------------------------------------------------------------
+
+describe('interpretChallengeResponse', () => {
+  it("returns 'expired' for a 400 error with serviceName 'challengeExpired'", () => {
+    const response: PollDispatchResult = {
+      error: { status: 400, data: { serviceName: 'challengeExpired' } },
+    };
+
+    const result = interpretChallengeResponse(response, mockLog);
+
+    expect(result).toBe('expired');
+  });
+
+  it("returns 'error' for other HTTP errors (status 500)", () => {
+    const response: PollDispatchResult = {
+      error: { status: 500, data: { message: 'Server Error' } },
+    };
+
+    const result = interpretChallengeResponse(response, mockLog);
+
+    expect(result).toBe('error');
+  });
+
+  it('returns InternalErrorResponse for a SerializedError (has message, no status)', () => {
+    const response: PollDispatchResult = {
+      error: { name: 'SerializedError', message: 'Network failure' },
+    };
+
+    const result = interpretChallengeResponse(response, mockLog);
+
+    expect(typeof result).toBe('object');
+    expect((result as any).type).toBe('internal_error');
+    expect((result as any).error.message).toBe('Network failure');
+  });
+
+  it("returns 'error' for non-object data", () => {
+    const response: PollDispatchResult = { data: 'just a string' };
+
+    const result = interpretChallengeResponse(response, mockLog);
+
+    expect(result).toBe('error');
+  });
+
+  it('returns the status from a completed challenge', () => {
+    const response: PollDispatchResult = {
+      data: { isChallengeComplete: true, status: 'approved' },
+    };
+
+    const result = interpretChallengeResponse(response, mockLog);
+
+    expect(result).toBe('approved');
+  });
+
+  it("returns 'error' when challenge is complete but status is missing", () => {
+    const response: PollDispatchResult = {
+      data: { isChallengeComplete: true },
+    };
+
+    const result = interpretChallengeResponse(response, mockLog);
+
+    expect(result).toBe('error');
+  });
+
+  it("returns 'timedOut' for an incomplete challenge when the schedule is exhausted", () => {
+    const response: PollDispatchResult = {
+      data: { isChallengeComplete: false },
+    };
+
+    const result = interpretChallengeResponse(response, mockLog);
+
+    expect(result).toBe('timedOut');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getPollingModeµ
+// ---------------------------------------------------------------------------
+
+describe('getPollingModeµ', () => {
+  const basePollingCollector: PollingCollector = {
+    category: 'SingleValueAutoCollector',
+    error: null,
+    type: 'PollingCollector',
+    id: 'polling-0',
+    name: 'polling',
+    input: { key: 'polling', value: '', type: 'POLLING' },
+    output: {
+      key: 'polling',
+      type: 'POLLING',
+      config: { pollInterval: 2000, pollRetries: 5, retriesRemaining: 5 },
+    },
+  };
+
+  it.effect('succeeds with challenge mode when challenge and pollChallengeStatus are set', () =>
+    Micro.gen(function* () {
+      const collector: PollingCollector = {
+        ...basePollingCollector,
+        output: {
+          ...basePollingCollector.output,
+          config: {
+            pollInterval: 2000,
+            pollRetries: 5,
+            pollChallengeStatus: true,
+            challenge: 'test-challenge',
+          },
+        },
+      };
+
+      const result = yield* getPollingModeµ(collector);
+
+      expect(result).toStrictEqual({ _tag: 'challenge', challenge: 'test-challenge' });
+    }),
+  );
+
+  it.effect('succeeds with continue mode when no challenge is present', () =>
+    Micro.gen(function* () {
+      const result = yield* getPollingModeµ(basePollingCollector);
+
+      expect(result).toStrictEqual({
+        _tag: 'continue',
+        retriesRemaining: 5,
+        pollInterval: 2000,
+      });
+    }),
+  );
+
+  it.effect('succeeds with unknown mode for ambiguous configuration', () =>
+    Micro.gen(function* () {
+      const collector: PollingCollector = {
+        ...basePollingCollector,
+        output: {
+          ...basePollingCollector.output,
+          config: {
+            pollInterval: 2000,
+            pollRetries: 5,
+            challenge: 'test-challenge',
+            // pollChallengeStatus is absent — ambiguous
+          },
+        },
+      };
+
+      const result = yield* getPollingModeµ(collector);
+
+      expect(result).toStrictEqual({ _tag: 'unknown' });
+    }),
+  );
+
+  it.effect('fails when collector type is not PollingCollector', () =>
+    Micro.gen(function* () {
+      const badCollector = { ...basePollingCollector, type: 'TextCollector' } as any;
+
+      const result = yield* Micro.exit(getPollingModeµ(badCollector));
+
+      expect(result).toStrictEqual(
+        Micro.exitFail({
+          error: {
+            message: 'Collector provided to poll is not a PollingCollector',
+            type: 'argument_error',
+          },
+          type: 'internal_error',
+        }),
+      );
+    }),
+  );
+
+  it.effect('fails when retriesRemaining is undefined in continue mode', () =>
+    Micro.gen(function* () {
+      const collector: PollingCollector = {
+        ...basePollingCollector,
+        output: {
+          ...basePollingCollector.output,
+          config: { pollInterval: 2000, pollRetries: 5 },
+        },
+      };
+
+      const result = yield* Micro.exit(getPollingModeµ(collector));
+
+      expect(result).toStrictEqual(
+        Micro.exitFail({
+          error: {
+            message: 'No retries found on PollingCollector',
+            type: 'argument_error',
+          },
+          type: 'internal_error',
+        }),
+      );
+    }),
+  );
+});