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

Author: ancheetah

e2e/davinci-app/components/polling.ts

@@ -0,0 +1,42 @@
+/*
+ * 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 {
+//   TextCollector,
+//   ValidatedTextCollector,
+//   Updater,
+// } from '@forgerock/davinci-client/types';
+import {
+  PollingCollector,
+  PollingStatusType,
+  InternalErrorResponse,
+} from '@forgerock/davinci-client/types';
+
+export default function pollingComponent(
+  formEl: HTMLFormElement,
+  collector: PollingCollector,
+  poll: (collector: PollingCollector) => Promise<PollingStatusType | InternalErrorResponse>,
+  // updater: Updater<TextCollector | ValidatedTextCollector>,
+) {
+  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 result = await poll(collector);
+    console.log('Polling result:', result);
+
+    const resultEl = document.createElement('p');
+    resultEl.innerText = 'Polling result: ' + JSON.stringify(result, null, 2);
+    formEl?.appendChild(resultEl);
+  };
+}

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,13 @@ 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, if needed for updating state during polling
+        );
       } 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/index.ts

@@ -6,5 +6,7 @@
  */
 import { davinci } from './lib/client.store.js';
 import { fido } from './lib/fido/fido.js';
+import { PollingStatus } from './lib/client.types.js';
 
 export { davinci, fido };
+export { PollingStatus };

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

@@ -11,7 +11,12 @@ import { CustomLogger, logger as loggerFn, LogLevel } from '@forgerock/sdk-logge
 import { createStorage } from '@forgerock/storage';
 import { isGenericError, createWellknownError } from '@forgerock/sdk-utilities';
 
-import { createClientStore, handleUpdateValidateError, RootState } from './client.store.utils.js';
+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 +39,7 @@ import type {
   ObjectValueCollectors,
   PhoneNumberInputValue,
   AutoCollectors,
+  PollingCollector,
   MultiValueCollectors,
   FidoRegistrationInputValue,
   FidoAuthenticationInputValue,
@@ -44,7 +50,9 @@ import type {
   NodeStates,
   Updater,
   Validator,
+  PollingStatusType,
 } from './client.types.js';
+import { PollingStatus } from './client.types.js';
 import { returnValidator } from './collector.utils.js';
 import type { ContinueNode, StartNode } from './node.types.js';
 
@@ -404,6 +412,51 @@ export async function davinci<ActionType extends ActionTypes = ActionTypes>({
       return returnValidator(collectorToUpdate);
     },
 
+    /**
+     * @method: poll - Poll for updates for a polling collector
+     */
+    poll: async (
+      collector: PollingCollector,
+    ): Promise<PollingStatusType | 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 challenge = collector.output.config.challenge;
+
+        // Challenge Polling
+        if (challenge) {
+          return await handleChallengePolling({
+            collector,
+            challenge,
+            store,
+            log,
+          });
+        } else {
+          // TODO: Handle continue polling
+          return PollingStatus.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

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

@@ -5,16 +5,20 @@
  * of the MIT license. See the LICENSE file for details.
  */
 import { configureStore } from '@reduxjs/toolkit';
+import { Micro } from 'effect';
+import { exitIsSuccess, exitIsFail } from 'effect/Micro';
 
 import type { ActionTypes, RequestMiddleware } from '@forgerock/sdk-request-middleware';
 import type { logger as loggerFn } from '@forgerock/sdk-logger';
+import { isGenericError } from '@forgerock/sdk-utilities';
 
 import { configSlice } from './config.slice.js';
 import { nodeSlice } from './node.slice.js';
 import { davinciApi } from './davinci.api.js';
 import { ErrorNode, ContinueNode, StartNode, SuccessNode } from '../types.js';
 import { wellknownApi } from './wellknown.api.js';
-import { InternalErrorResponse } from './client.types.js';
+import { InternalErrorResponse, PollingStatus, PollingStatusType } from './client.types.js';
+import { PollingCollector } from './collector.types.js';
 
 export function createClientStore<ActionType extends ActionTypes>({
   requestMiddleware,
@@ -75,3 +79,185 @@ export interface RootStateWithNode<T extends ErrorNode | ContinueNode | StartNod
 }
 
 export type AppDispatch = ReturnType<ReturnType<ClientStore>['dispatch']>;
+
+export async function handleChallengePolling({
+  collector,
+  challenge,
+  store,
+  log,
+}: {
+  collector: PollingCollector;
+  challenge: string;
+  store: ReturnType<ClientStore>;
+  log: ReturnType<typeof loggerFn>;
+}): Promise<PollingStatusType | InternalErrorResponse> {
+  if (!challenge) {
+    log.error('No challenge found on collector for poll operation');
+    return {
+      error: {
+        message: 'No challenge found on collector for poll operation',
+        type: 'state_error',
+      },
+      type: 'internal_error',
+    };
+  }
+
+  const rootState: RootState = store.getState();
+  const serverSlice = nodeSlice.selectors.selectServer(rootState);
+
+  if (serverSlice === null) {
+    log.error('No server info found for poll operation');
+    return {
+      error: {
+        message: 'No server info found for poll operation',
+        type: 'state_error',
+      },
+      type: 'internal_error',
+    };
+  }
+
+  if (isGenericError(serverSlice)) {
+    log.error(serverSlice.message ?? serverSlice.error);
+    return {
+      error: {
+        message: serverSlice.message ?? 'Failed to retrieve server info for poll operation',
+        type: 'internal_error',
+      },
+      type: 'internal_error',
+    };
+  }
+
+  if (serverSlice.status !== 'continue') {
+    return {
+      error: {
+        message: 'Not in a continue node state, must be in a continue node to use poll method',
+        type: 'state_error',
+      },
+    } as InternalErrorResponse;
+  }
+
+  // Construct the challenge polling endpoint
+  const links = serverSlice._links;
+  if (!links || !('self' in links) || !('href' in links['self']) || !links['self'].href) {
+    return {
+      error: {
+        message: 'No self link found in server info for challenge polling operation',
+        type: 'internal_error',
+      },
+    } as InternalErrorResponse;
+  }
+
+  const selfUrl = links['self'].href;
+  const url = new URL(selfUrl);
+  const baseUrl = url.origin;
+  const paths = url.pathname.split('/');
+  const envId = paths[1];
+
+  if (!baseUrl || !envId) {
+    return {
+      error: {
+        message:
+          'Failed to construct challenge polling endpoint. Requires host and environment ID.',
+        type: 'parse_error',
+      },
+    } as InternalErrorResponse;
+  }
+
+  const interactionId = serverSlice.interactionId;
+  if (!interactionId) {
+    return {
+      error: {
+        message: 'Missing interactionId in server info for challenge polling',
+        type: 'internal_error',
+      },
+    } as InternalErrorResponse;
+  }
+
+  const challengeEndpoint = `${baseUrl}/${envId}/davinci/user/credentials/challenge/${challenge}/status`;
+
+  // Start challenge polling
+  let retriesLeft = collector.output.config.pollRetries;
+  const pollInterval = collector.output.config.pollInterval;
+
+  const queryµ = Micro.promise(() => {
+    retriesLeft--;
+    console.log('retries left: ', retriesLeft);
+    return store.dispatch(
+      davinciApi.endpoints.poll.initiate({
+        challengeEndpoint,
+        interactionId,
+      }),
+    );
+  });
+
+  const challengePollµ = Micro.repeat(queryµ, {
+    while: ({ data, error }) =>
+      retriesLeft > 0 && !error && !(data as Record<string, unknown>)['isChallengeComplete'],
+    schedule: Micro.scheduleSpaced(pollInterval),
+  }).pipe(
+    Micro.flatMap(({ data, error }) => {
+      const pollResponse = data as Record<string, unknown>;
+
+      // Check for any errors and return the appropriate status
+      if (error) {
+        // SerializedError
+        // let message = 'An error occurred while challenge polling';
+        // if ('message' in error && error.message) {
+        //   message = error.message;
+        // }
+
+        // FetchBaseQueryError
+        let status: number | string = 'unknown';
+        if ('status' in error) {
+          status = error.status;
+
+          const errorDetails = error.data as Record<string, unknown>;
+          const serviceName = errorDetails['serviceName'];
+
+          // Check for an expired challenge
+          if (status === 400 && serviceName && serviceName === 'challengeExpired') {
+            log.debug('Challenge expired for polling');
+            return Micro.succeed(PollingStatus.Expired);
+          } else {
+            // If we're here there is some other type of network error and status != 200
+            // e.g. A bad challenge can return a httpStatus of 400 with code 4019
+            log.debug('Network error occurred during polling');
+            return Micro.succeed(PollingStatus.Error);
+          }
+        }
+      }
+
+      // If a successful response is recieved it can be either a timeout or true success
+      if (pollResponse['isChallengeComplete'] === true) {
+        return Micro.succeed(PollingStatus.Complete);
+      } else if (retriesLeft <= 0 && !pollResponse['isChallengeComplete']) {
+        return Micro.succeed(PollingStatus.TimedOut);
+      }
+
+      // Just in case no polling status was determined
+      return Micro.fail({
+        error: {
+          message: 'Unknown error occurred during polling',
+          type: 'unknown_error',
+        },
+        type: 'internal_error',
+      } as InternalErrorResponse);
+    }),
+  );
+
+  const result = await Micro.runPromiseExit(challengePollµ);
+
+  if (exitIsSuccess(result)) {
+    return result.value;
+  } else if (exitIsFail(result)) {
+    return result.cause.error;
+  } else {
+    return {
+      error: {
+        message: result.cause.message,
+        type: 'unknown_error',
+      },
+      type: 'internal_error',
+    };
+  }
+}

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

@@ -91,3 +91,12 @@ export type Validator = (value: string) =>
     };
 
 export type NodeStates = StartNode | ContinueNode | ErrorNode | SuccessNode | FailureNode;
+
+export const PollingStatus = {
+  Complete: 'complete',
+  Expired: 'expired',
+  TimedOut: 'timedOut',
+  Error: 'error',
+} as const;
+
+export type PollingStatusType = (typeof PollingStatus)[keyof typeof PollingStatus];