chore(davinci-client): refactor and improve polling

Author: ancheetah

e2e/davinci-app/components/polling.ts

@@ -25,6 +25,8 @@ export default function pollingComponent(
   formEl.appendChild(button);
 
   button.onclick = async () => {
+    button.disabled = true;
+
     const p = document.createElement('p');
     p.innerText = 'Polling...';
     formEl?.appendChild(p);
@@ -54,5 +56,7 @@ export default function pollingComponent(
     formEl?.appendChild(resultEl);
 
     await submitForm();
+
+    button.disabled = false;
   };
 }

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

@@ -0,0 +1,256 @@
+/*
+ * 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 { exitIsSuccess, exitIsFail } from 'effect/Micro';
+import { SerializedError } from '@reduxjs/toolkit/react';
+import { FetchBaseQueryError } from '@reduxjs/toolkit/query/react';
+
+import { isGenericError } from '@forgerock/sdk-utilities';
+import type { logger as loggerFn } from '@forgerock/sdk-logger';
+
+import type { ClientStore, RootState } from './client.store.utils.js';
+import type { PollingStatus, InternalErrorResponse } from './client.types.js';
+import type { PollingCollector } from './collector.types.js';
+import type { ContinueNode } from './node.types.js';
+
+import { createInternalError } from './client.store.utils.js';
+import { davinciApi } from './davinci.api.js';
+import { nodeSlice } from './node.slice.js';
+
+/**
+ * Shape returned by RTK Query's dispatch for the poll endpoint.
+ */
+export interface PollDispatchResult {
+  data?: unknown;
+  error?: FetchBaseQueryError | SerializedError;
+}
+
+/**
+ * Validated prerequisites needed to initiate challenge polling.
+ */
+interface PollingPrerequisites {
+  interactionId: string;
+  challengeEndpoint: string;
+}
+
+/**
+ * Type guard: determines if a value is a plain object (Record<string, unknown>).
+ */
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * Selects and validates server is in continue state from root state.
+ * Narrows from the NodeStates server union to ContinueNode['server'].
+ * Throws InternalErrorResponse on validation failure.
+ */
+function selectContinueServer(rootState: RootState): ContinueNode['server'] {
+  const server = nodeSlice.selectors.selectServer(rootState);
+
+  if (server === null) {
+    throw createInternalError('No server info found for poll operation', 'state_error');
+  }
+
+  if (isGenericError(server)) {
+    throw createInternalError(
+      server.message ?? 'Failed to retrieve server info for poll operation',
+    );
+  }
+
+  if (server.status !== 'continue') {
+    throw createInternalError(
+      'Not in a continue node state, must be in a continue node to use poll method',
+      'state_error',
+    );
+  }
+
+  return server;
+}
+
+/**
+ * Extracts the self link href from server links.
+ * Throws InternalErrorResponse if self link is missing.
+ */
+function selectSelfLink(server: ContinueNode['server']): string {
+  const links = server._links;
+  if (!links || !('self' in links) || !('href' in links['self']) || !links['self'].href) {
+    throw createInternalError(
+      'No self link found in server info for challenge polling operation',
+      'state_error',
+    );
+  }
+  return links['self'].href;
+}
+
+/**
+ * Constructs the challenge polling endpoint from a self link URL.
+ * Throws InternalErrorResponse if URL cannot be parsed.
+ */
+function buildChallengeEndpoint(selfHref: string, challenge: string): string {
+  const url = new URL(selfHref);
+  const envId = url.pathname.split('/')[1];
+
+  if (!url.origin || !envId) {
+    throw createInternalError(
+      'Failed to construct challenge polling endpoint. Requires host and environment ID.',
+      'parse_error',
+    );
+  }
+
+  return `${url.origin}/${envId}/davinci/user/credentials/challenge/${challenge}/status`;
+}
+
+/**
+ * Pure function: validates all prerequisites for challenge polling and constructs the endpoint URL.
+ * Composes selectors that each extract and validate a piece of state.
+ * Throws InternalErrorResponse on any validation failure — designed to be caught by Micro.try.
+ */
+export function validatePollingPrerequisites(
+  rootState: RootState,
+  challenge: string,
+): PollingPrerequisites {
+  if (!challenge) {
+    throw createInternalError('No challenge found on collector for poll operation', 'state_error');
+  }
+
+  const server = selectContinueServer(rootState);
+  const selfHref = selectSelfLink(server);
+  const challengeEndpoint = buildChallengeEndpoint(selfHref, challenge);
+
+  if (!server.interactionId) {
+    throw createInternalError(
+      'Missing interactionId in server info for challenge polling',
+      'state_error',
+    );
+  }
+
+  return { interactionId: server.interactionId, challengeEndpoint };
+}
+
+/**
+ * Pure predicate: determines if challenge polling should continue.
+ * Returns true when the challenge has not yet completed and no error occurred.
+ */
+export function isChallengeStillPending(response: PollDispatchResult): boolean {
+  if (response.error) return false;
+
+  const data = isRecord(response.data) ? response.data : undefined;
+  if (data?.['isChallengeComplete']) return false;
+
+  return true;
+}
+
+export function interpretChallengeResponse(
+  response: PollDispatchResult,
+  log: ReturnType<typeof loggerFn>,
+): Micro.Micro<PollingStatus, InternalErrorResponse> {
+  const { data, error } = response;
+
+  if (error) {
+    // FetchBaseQueryError — has status field
+    if ('status' in error) {
+      const errorDetails = isRecord(error.data) ? error.data : undefined;
+      const serviceName = errorDetails?.['serviceName'];
+
+      // Expired challenge is an expected polling outcome, not a failure
+      if (error.status === 400 && serviceName === 'challengeExpired') {
+        log.debug('Challenge expired for polling');
+        return Micro.succeed('expired' as PollingStatus);
+      }
+
+      // Other HTTP errors are also expected outcomes (e.g. bad challenge returning 400 with code 4019)
+      log.debug('Unknown error occurred during polling');
+      return Micro.succeed('error' as PollingStatus);
+    }
+
+    // SerializedError — has message field
+    const message =
+      'message' in error && error.message
+        ? error.message
+        : 'An unknown error occurred while challenge polling';
+
+    return Micro.fail(createInternalError(message, 'unknown_error'));
+  }
+
+  if (!isRecord(data)) {
+    log.debug('Unable to parse polling response');
+    return Micro.succeed('error' as PollingStatus);
+  }
+  const pollResponse = data;
+
+  // Challenge completed — extract status
+  if (pollResponse['isChallengeComplete'] === true) {
+    const pollStatus = pollResponse['status'];
+    return pollStatus
+      ? Micro.succeed(pollStatus as PollingStatus)
+      : Micro.succeed('error' as PollingStatus);
+  }
+
+  // If we reach here, Micro.repeat exhausted its schedule without the challenge completing
+  log.debug('Challenge polling timed out');
+  return Micro.succeed('timedOut' as PollingStatus);
+}
+
+/**
+ * Orchestrates challenge polling using extracted pure functions.
+ * The shell: reads state, dispatches effects, runs the pipeline at the boundary.
+ */
+export async function handleChallengePolling({
+  collector,
+  challenge,
+  store,
+  log,
+}: {
+  collector: PollingCollector;
+  challenge: string;
+  store: ReturnType<ClientStore>;
+  log: ReturnType<typeof loggerFn>;
+}): Promise<PollingStatus | InternalErrorResponse> {
+  const maxRetries = collector.output.config.pollRetries ?? 60;
+  const pollInterval = collector.output.config.pollInterval ?? 2000;
+
+  // validate → query → repeat → interpret
+  const challengePollµ = Micro.try({
+    try: () => validatePollingPrerequisites(store.getState(), challenge),
+    catch: (error) => error as InternalErrorResponse,
+  }).pipe(
+    Micro.flatMap(({ interactionId, challengeEndpoint }) =>
+      Micro.promise(() =>
+        store.dispatch(
+          davinciApi.endpoints.poll.initiate({
+            endpoint: challengeEndpoint,
+            interactionId,
+          }),
+        ),
+      ).pipe(
+        Micro.repeat({
+          while: isChallengeStillPending,
+          // `times` - tracks repetitions automatically and stops when the threshold is reached
+          //         - counts the number of retries after the initial attempt so decrement by one
+          times: maxRetries - 1,
+          schedule: Micro.scheduleSpaced(pollInterval),
+        }),
+      ),
+    ),
+    Micro.flatMap((response) => interpretChallengeResponse(response, log)),
+    Micro.tapError(({ error }) => Micro.sync(() => log.error(error.message))),
+  );
+
+  const result = await Micro.runPromiseExit(challengePollµ);
+
+  if (exitIsSuccess(result)) {
+    return result.value;
+  } else if (exitIsFail(result)) {
+    return result.cause.error;
+  }
+
+  return {
+    error: { message: result.cause.message, type: 'unknown_error' },
+    type: 'internal_error',
+  };
+}

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

@@ -4,8 +4,7 @@
  * 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 { CustomLogger, logger as loggerFn, LogLevel } from '@forgerock/sdk-logger';
+import { type CustomLogger, logger as loggerFn, type LogLevel } from '@forgerock/sdk-logger';
 import { createStorage } from '@forgerock/storage';
 import { isGenericError, createWellknownError } from '@forgerock/sdk-utilities';
 
@@ -14,10 +13,12 @@ import { isGenericError, createWellknownError } from '@forgerock/sdk-utilities';
  */
 import {
   createClientStore,
-  handleChallengePolling,
+  createInternalError,
+  getPollingMode,
   handleUpdateValidateError,
-  RootState,
+  type RootState,
 } from './client.store.utils.js';
+import { handleChallengePolling } from './client.store.effects.js';
 import { nodeSlice } from './node.slice.js';
 import { davinciApi } from './davinci.api.js';
 import { configSlice } from './config.slice.js';
@@ -419,67 +420,47 @@ export async function davinci<ActionType extends ActionTypes = ActionTypes>({
      */
     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 mode = getPollingMode(collector);
 
-        const pollChallengeStatus = collector.output.config.pollChallengeStatus;
-        const challenge = collector.output.config.challenge;
-
-        if (challenge && pollChallengeStatus === true) {
-          // Challenge Polling
+        if (mode._tag === 'challenge') {
+          // Challenge polling mode
           return await handleChallengePolling({
             collector,
-            challenge,
+            challenge: mode.challenge,
             store,
             log,
           });
-        } else if (!challenge && !pollChallengeStatus) {
-          // Continue polling
-          const retriesLeft = collector.output.config.retriesRemaining;
-          const pollInterval = collector.output.config.pollInterval ?? 2000; // miliseconds
+        } else if (mode._tag === 'continue') {
+          // Continue polling mode
 
-          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 {
+          if (mode.retriesRemaining <= 0) {
             // Retries exhausted
-            return 'timedOut' as PollingStatus;
+            return 'timedOut';
           }
+
+          // If there are still retries, wait for the poll interval then return a 'continue' status
+          await new Promise((resolve) => setTimeout(resolve, mode.pollInterval));
+          return 'continue';
         } 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',
-          };
+          // Error if polling mode can't be determined from configuration
+          throw createInternalError('Invalid polling collector configuration', 'argument_error');
         }
       } catch (err) {
-        const errorMessage = err instanceof Error ? err.message : String(err);
+        let errorMessage = '';
+
+        if (err instanceof Error) {
+          errorMessage = err.message;
+        } else if (
+          err !== null &&
+          typeof err === 'object' &&
+          'type' in err &&
+          err.type === 'internal_error'
+        ) {
+          const internalError = err as InternalErrorResponse;
+          log.error(internalError.error.message);
+          return internalError;
+        }
+
         log.error(errorMessage);
         return {
           error: {