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

.github/actions/setup/action.yml

@@ -31,7 +31,9 @@ runs:
         registry-url: 'https://registry.npmjs.org'
 
     - name: Update npm
-      run: npm install -g npm@latest
+      run: |
+        corepack enable
+        corepack install -g npm@latest
       shell: bash
 
     - name: Install dependencies

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
         with:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-      - run: npx nx-cloud fix-ci
+      - run: pnpm nx fix-ci
         if: always()
 
       - uses: codecov/codecov-action@v5

e2e/davinci-app/components/polling.ts

@@ -0,0 +1,58 @@
+/*
+ * 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,
+  PollingStatus,
+  InternalErrorResponse,
+  Updater,
+} from '@forgerock/davinci-client/types';
+
+export default function pollingComponent(
+  formEl: HTMLFormElement,
+  collector: PollingCollector,
+  poll: (collector: PollingCollector) => Promise<PollingStatus | InternalErrorResponse>,
+  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 () => {
+    const p = document.createElement('p');
+    p.innerText = 'Polling...';
+    formEl?.appendChild(p);
+
+    const status = await poll(collector);
+    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();
+  };
+}

e2e/davinci-app/main.ts

@@ -32,6 +32,7 @@ import multiValueComponent from './components/multi-value.js';
 import labelComponent from './components/label.js';
 import objectValueComponent from './components/object-value.js';
 import fidoComponent from './components/fido.js';
+import pollingComponent from './components/polling.js';
 
 const loggerFn = {
   error: () => {
@@ -262,6 +263,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, // 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/src/lib/client.store.ts

@@ -4,14 +4,20 @@
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
  */
-/**
- * Import RTK slices and api
- */
+import { Micro } from 'effect';
 import { CustomLogger, logger as loggerFn, LogLevel } from '@forgerock/sdk-logger';
 import { createStorage } from '@forgerock/storage';
 import { isGenericError, createWellknownError } from '@forgerock/sdk-utilities';
 
-import { createClientStore, handleUpdateValidateError, RootState } from './client.store.utils.js';
+/**
+ * Import RTK slices and api
+ */
+import {
+  createClientStore,
+  handleChallengePolling,
+  handleUpdateValidateError,
+  RootState,
+} from './client.store.utils.js';
 import { nodeSlice } from './node.slice.js';
 import { davinciApi } from './davinci.api.js';
 import { configSlice } from './config.slice.js';
@@ -34,6 +40,7 @@ import type {
   ObjectValueCollectors,
   PhoneNumberInputValue,
   AutoCollectors,
+  PollingCollector,
   MultiValueCollectors,
   FidoRegistrationInputValue,
   FidoAuthenticationInputValue,
@@ -44,6 +51,7 @@ import type {
   NodeStates,
   Updater,
   Validator,
+  PollingStatus,
 } from './client.types.js';
 import { returnValidator } from './collector.utils.js';
 import type { ContinueNode, StartNode } from './node.types.js';
@@ -404,6 +412,85 @@ export async function davinci<ActionType extends ActionTypes = ActionTypes>({
       return returnValidator(collectorToUpdate);
     },
 
+    /**
+     * @method poll - Perform challenge polling or continue polling
+     * @param {PollingCollector} collector - the polling collector
+     * @returns {Promise<PollingStatus | InternalErrorResponse>} - Returns a promise that resolves to a polling status or error
+     */
+    poll: async (collector: PollingCollector): Promise<PollingStatus | InternalErrorResponse> => {
+      try {
+        if (collector.type !== 'PollingCollector') {
+          log.error('Collector provided to poll is not a PollingCollector');
+          return {
+            error: {
+              message: 'Collector provided to poll is not a PollingCollector',
+              type: 'argument_error',
+            },
+            type: 'internal_error',
+          };
+        }
+
+        const pollChallengeStatus = collector.output.config.pollChallengeStatus;
+        const challenge = collector.output.config.challenge;
+
+        if (challenge && pollChallengeStatus === true) {
+          // Challenge Polling
+          return await handleChallengePolling({
+            collector,
+            challenge,
+            store,
+            log,
+          });
+        } else if (!challenge && !pollChallengeStatus) {
+          // Continue polling
+          const retriesLeft = collector.output.config.retriesRemaining;
+          const pollInterval = collector.output.config.pollInterval ?? 2000; // miliseconds
+
+          if (retriesLeft === undefined) {
+            log.error('No retries found on PollingCollector');
+            return {
+              error: {
+                message: 'No retries found on PollingCollector',
+                type: 'argument_error',
+              },
+              type: 'internal_error',
+            };
+          }
+
+          if (retriesLeft > 0) {
+            const getStatusµ = Micro.sync(() => 'continue' as PollingStatus).pipe(
+              Micro.delay(pollInterval),
+            );
+            const status: PollingStatus = await Micro.runPromise(getStatusµ);
+            return status;
+          } else {
+            // Retries exhausted
+            return 'timedOut' as PollingStatus;
+          }
+        } else {
+          // Error if polling type can't be determined from configuration
+          log.error('Invalid polling collector configuration');
+          return {
+            error: {
+              message: 'Invalid polling collector configuration',
+              type: 'internal_error',
+            },
+            type: 'internal_error',
+          };
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        log.error(errorMessage);
+        return {
+          error: {
+            message: errorMessage || 'An unexpected error occurred during poll operation',
+            type: 'internal_error',
+          },
+          type: 'internal_error',
+        };
+      }
+    },
+
     /**
      * @method client - Selector to get the node.client from state
      * @returns {Node.client} - the client property from the current node