@explorer02/cfm-survey-sdk 0.0.1

package/src/logger/logger.ts

@@ -0,0 +1,71 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'success' | 'perf' | 'analytics';
+
+let loggingEnabled = false;
+
+// CSS styles for console log level badges
+const BADGE_STYLES: Record<LogLevel, string> = {
+  debug: 'background: #7f8c8d; color: #fff; padding: 2px 5px; border-radius: 3px; font-weight: bold;',
+  info: 'background: #2980b9; color: #fff; padding: 2px 5px; border-radius: 3px; font-weight: bold;',
+  warn: 'background: #f1c40f; color: #000; padding: 2px 5px; border-radius: 3px; font-weight: bold;',
+  error: 'background: #e74c3c; color: #fff; padding: 2px 5px; border-radius: 3px; font-weight: bold;',
+  success: 'background: #2ecc71; color: #fff; padding: 2px 5px; border-radius: 3px; font-weight: bold;',
+  perf: 'background: #9b59b6; color: #fff; padding: 2px 5px; border-radius: 3px; font-weight: bold;',
+  analytics: 'background: #e20074; color: #fff; padding: 2px 5px; border-radius: 3px; font-weight: bold;',
+};
+
+/**
+ * Writes formatted badges and log details into the console if logging is enabled.
+ * Note: analytics level logs are always printed regardless of debug settings.
+ *
+ * @param level Logging categorization level (debug, info, warn, error, success, analytics).
+ * @param message Description message text.
+ * @param meta Optional auxiliary metadata/payload.
+ */
+function writeLog(level: LogLevel, message: string, meta?: any) {
+  if (!loggingEnabled && level !== 'analytics') return;
+
+  const timestamp = new Date().toLocaleTimeString();
+  const badge = `%c[SDK:${level.toUpperCase()}]`;
+  const style = BADGE_STYLES[level];
+
+  if (meta !== undefined) {
+    console.log(`[${timestamp}] ${badge}`, style, message, meta);
+  } else {
+    console.log(`[${timestamp}] ${badge}`, style, message);
+  }
+}
+
+/**
+ * A central namespace containing logging helpers for debugging, warnings, success,
+ * and API monitoring. Output logs are formatted with custom browser styles.
+ */
+export const sdkLogger = {
+  setEnabled: (val: boolean) => {
+    loggingEnabled = val;
+  },
+  isEnabled: () => {
+    return loggingEnabled;
+  },
+  debug: (msg: string, meta?: any) => writeLog('debug', msg, meta),
+  info: (msg: string, meta?: any) => writeLog('info', msg, meta),
+  warn: (msg: string, meta?: any) => writeLog('warn', msg, meta),
+  error: (msg: string, meta?: any) => writeLog('error', msg, meta),
+  success: (msg: string, meta?: any) => writeLog('success', msg, meta),
+  analytics: (msg: string, meta?: any) => writeLog('analytics', msg, meta),
+  perf: (metric: {
+    apiName: string;
+    durationMs: number;
+    status: number | string;
+    url: string;
+    requestSize?: string;
+    responseSize?: string;
+    payloadSize?: string;
+    success: boolean;
+  }) => {
+    writeLog(
+      'perf',
+      `${metric.apiName} completed in ${metric.durationMs.toFixed(2)}ms | Status: ${metric.status}`,
+      metric
+    );
+  },
+};

package/src/queryClient.ts

@@ -0,0 +1,67 @@
+import { QueryClient } from '@tanstack/react-query';
+import { sdkLogger } from './logger/logger';
+
+export const sdkQueryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: Infinity,          // Keep the survey layout cached forever during the session
+      refetchOnWindowFocus: false,  // Prevent layout flashes when switching browser tabs
+      refetchOnReconnect: false,    // Avoid redundant network calls on internet reconnection
+      refetchInterval: false,       // Do not poll (survey metadata is static)
+      retryDelay: 5000, // 5 seconds delay between retries
+      retry: (failureCount, error) => {
+        // Stop retrying after 3 attempts
+        if (failureCount >= 3) {
+          sdkLogger.error(`Query failed permanently after 3 attempts. Stopping retries.`, error);
+          return false;
+        }
+
+        // Do not retry on permanent client errors (400, 401, 403, 404, 422)
+        if (error instanceof Error) {
+          const msg = error.message;
+          if (
+            msg.includes('400') || // 400 Bad Request
+            msg.includes('401') || // 401 Unauthorized
+            msg.includes('403') || // 403 Forbidden
+            msg.includes('404') || // 404 Not Found
+            msg.includes('422')    // 422 Unprocessable Entity
+          ) {
+            sdkLogger.error(`Query failed permanently due to client error (${msg}). Skipping retry.`, error);
+            return false;
+          }
+        }
+
+        sdkLogger.warn(`Query failed. Retrying attempt ${failureCount + 1}/3...`, error);
+        return true;
+      },
+    },
+    mutations: {
+      networkMode: 'always', // Prevent React Query from pausing mutations when offline, forcing immediate retry logging
+      retryDelay: 5000, // 5 seconds delay between retries
+      retry: (failureCount, error) => {
+        // Retry up to 3 times for transient network/server failures
+        if (failureCount >= 3) {
+          sdkLogger.error(`Mutation failed permanently after 3 attempts. Stopping retries.`, error);
+          return false;
+        }
+
+        // Do not retry on permanent validation or client errors (400, 401, 403, 422)
+        if (error instanceof Error) {
+          const msg = error.message;
+          if (
+            msg.includes('400') || // 400 Bad Request (Client syntax / invalid parameters)
+            msg.includes('401') || // 401 Unauthorized (Authentication issues)
+            msg.includes('403') || // 403 Forbidden (Insufficient permissions)
+            msg.includes('422') // 422 Unprocessable Entity (Semantic validation failure)
+          ) {
+            sdkLogger.error(`Mutation failed permanently due to validation/client error. Skipping retry.`, error);
+            return false;
+          }
+        }
+
+        sdkLogger.warn(`Mutation failed. Retrying attempt ${failureCount + 1}/3...`, error);
+        return true;
+      },
+    },
+  },
+});

package/src/submitSurvey/logger/resolutionLogger.ts

@@ -0,0 +1,13 @@
+import { sdkLogger } from '../../logger/logger';
+
+export function logResolvedInputs(resolved: any): void {
+  sdkLogger.debug('Resolved raw inputs to submit schema:', resolved);
+}
+
+export function logRequestBody(body: any): void {
+  sdkLogger.debug('Constructed JSON request body:', body);
+}
+
+export function logExecuteSubmitError(err: any): void {
+  sdkLogger.error('Failed to execute submit callback', err);
+}

package/src/submitSurvey/logger/submitLogger.ts

@@ -0,0 +1,51 @@
+import { sdkLogger } from '../../logger/logger';
+
+export function logSubmitStart(url: string, requestBody: any): void {
+  sdkLogger.info('Starting survey response HTTP POST...', { url, requestBody });
+}
+
+export function logSubmitWarn(msg: string, err: any): void {
+  sdkLogger.warn(msg, err);
+}
+
+export function logSubmitPerfSuccess(
+  durationMs: number,
+  status: number,
+  url: string,
+  requestSize: string,
+  responseSize: string
+): void {
+  sdkLogger.perf({
+    apiName: 'POST Submit Response',
+    durationMs,
+    status,
+    url,
+    requestSize,
+    responseSize,
+    success: true,
+  });
+}
+
+export function logSubmitPerfFailure(
+  durationMs: number,
+  status: number | string,
+  url: string,
+  requestSize: string
+): void {
+  sdkLogger.perf({
+    apiName: 'POST Submit Response',
+    durationMs,
+    status,
+    url,
+    requestSize,
+    success: false,
+  });
+}
+
+export function logSubmitSuccess(responseId: string): void {
+  sdkLogger.success('Survey response submitted successfully', { responseId });
+}
+
+export function logSubmitError(msg: string, err: any): void {
+  sdkLogger.error(msg, err);
+}

package/src/submitSurvey/telemetry/submitTelemetry.ts

@@ -0,0 +1,33 @@
+import { trackEvent } from '../../analytics/analyticsTracker';
+
+export function trackSubmitLatency(
+  durationMs: number,
+  status: number,
+  url: string,
+  requestSize: string,
+  responseSize: string
+): void {
+  trackEvent({
+    eventName: 'survey_submit_latency',
+    metadata: {
+      durationMs,
+      status,
+      success: true,
+      url,
+      requestSize,
+      responseSize,
+    },
+  });
+}
+
+export function trackSubmitError(status: number | string, url: string, errorMessage: string): void {
+  trackEvent({
+    eventName: 'api_error',
+    metadata: {
+      apiName: 'POST Submit Response',
+      status,
+      url,
+      errorMessage,
+    },
+  });
+}

package/src/submitSurvey/types.ts

@@ -0,0 +1,51 @@
+import type { Survey, SurveyQuestion, SurveySession } from '../fetchSurvey/useFetchSurvey';
+
+/**
+ * Key-value mapping of question IDs to their selected answer values (string or number).
+ */
+export type SubmitAnswers = Record<string, string | number>;
+
+/**
+ * Standard input structure accepted by the submit hook.
+ */
+export type SubmitInput = {
+  // Collection of answered questions and values
+  answers: SubmitAnswers;
+  // Unique distribution instance token/identifier
+  instanceId: string;
+  // Localized language code of the submission
+  surveyLanguage?: string;
+  // Full question configuration structure (used to locate parent/child mappings)
+  questions?: SurveyQuestion[];
+};
+
+/**
+ * Formatted JSON payload required by the Sprinklr response endpoint.
+ */
+export type SubmitRequestBody = {
+  // Mapping of final submit ID to an array of selected answer values
+  questionToAnswers: Record<string, string[]>;
+  // Optional file attachment details mapping
+  quesIdVsAttachmentDetails: Record<string, unknown>;
+  // Mapping of parent question ID to an array of selected answer values for matrix grids
+  optionLevelAnswers: Record<string, string[]>;
+  // Conjoint task tracking structures
+  conjointTasks: unknown[];
+};
+
+/**
+ * The final output result resolved after a successful submit response.
+ */
+export type SubmitResult = {
+  // Flag indicating whether submission was successful
+  success: boolean;
+  // Generated submission database ID
+  responseId: string;
+};
+
+/**
+ * Raw response body structure returned by the survey response submit endpoint.
+ */
+export type SubmitApiResponse = {
+  responseId?: string;
+};

package/src/submitSurvey/useSubmitResponse.ts

@@ -0,0 +1,111 @@
+import { useCallback } from 'react';
+import { useMutation } from '@tanstack/react-query';
+import { sdkQueryClient } from '../queryClient';
+import type { Survey, SurveySession } from '../fetchSurvey/useFetchSurvey';
+import type { SubmitAnswers, SubmitInput, SubmitResult, SubmitApiResponse } from './types';
+import {
+  logSubmitStart,
+  logSubmitWarn,
+  logSubmitPerfSuccess,
+  logSubmitPerfFailure,
+  logSubmitSuccess,
+  logSubmitError,
+} from './logger/submitLogger';
+import { logResolvedInputs, logRequestBody, logExecuteSubmitError } from './logger/resolutionLogger';
+import { trackSubmitLatency, trackSubmitError } from './telemetry/submitTelemetry';
+
+// Re-export all type definitions (both parameters and final mapped results)
+export * from './types';
+import { resolveSubmitInput, buildSubmitRequestBody, buildExternalSubmitUrl } from './utils';
+
+/**
+ * Perform the HTTP POST request to submit answers.
+ */
+async function submitSurveyResponse({ url, requestBody }: { url: string; requestBody: any }): Promise<SubmitResult> {
+  const startTime = performance.now();
+  const requestSize = new Blob([JSON.stringify(requestBody)]).size;
+  const requestSizeStr = `${(requestSize / 1024).toFixed(2)} KB`;
+  logSubmitStart(url, requestBody);
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(requestBody),
+    });
+
+    const responseData = (await response.json().catch(err => {
+      logSubmitWarn('Failed to parse JSON response during submission', err);
+      return null;
+    })) as SubmitApiResponse | null;
+
+    const durationMs = performance.now() - startTime;
+    const responseSize = responseData ? new Blob([JSON.stringify(responseData)]).size : 0;
+    const responseSizeStr = `${(responseSize / 1024).toFixed(2)} KB`;
+
+    if (!response.ok) {
+      logSubmitPerfFailure(durationMs, response.status, url, requestSizeStr);
+      trackSubmitError(response.status, url, `Submit failed (${response.status}): ${JSON.stringify(responseData)}`);
+      throw new Error(`Submit failed (${response.status}): ${JSON.stringify(responseData)}`);
+    }
+
+    const responseId = responseData?.responseId ?? '';
+    logSubmitPerfSuccess(durationMs, response.status, url, requestSizeStr, responseSizeStr);
+
+    trackSubmitLatency(durationMs, response.status, url, requestSizeStr, responseSizeStr);
+
+    logSubmitSuccess(responseId);
+    return { success: true, responseId };
+  } catch (err: any) {
+    const durationMs = performance.now() - startTime;
+    logSubmitPerfFailure(durationMs, 'FAILED', url, requestSizeStr);
+    trackSubmitError('FAILED', url, err?.message || String(err));
+    logSubmitError('Failed to submit survey response', err);
+    throw err;
+  }
+}
+
+/**
+ * A custom React hook that manages submitting user answers to the remote survey response service.
+ * Tracks submission data, loading states, and error responses using TanStack Query useMutation.
+ *
+ * @param session Active survey session details containing target instanceId and language.
+ * @param survey Fully mapped survey structure containing questions.
+ * @returns Object holding submit execution, result data, loading state, and error.
+ */
+export function useSubmitResponse(session?: SurveySession | null, survey?: Survey | null) {
+  const mutation = useMutation(
+    {
+      mutationFn: ({ url, requestBody }: { url: string; requestBody: any }) =>
+        submitSurveyResponse({ url, requestBody }),
+    },
+    sdkQueryClient
+  );
+
+  const submit = useCallback(
+    async (input: SubmitAnswers | SubmitInput) => {
+      try {
+        const resolved = resolveSubmitInput(input, session, survey);
+        logResolvedInputs(resolved);
+
+        const surveyLanguage = resolved.surveyLanguage ?? 'en';
+        const requestBody = buildSubmitRequestBody(resolved.answers, resolved.questions ?? []);
+        logRequestBody(requestBody);
+
+        const url = buildExternalSubmitUrl(resolved.instanceId, surveyLanguage);
+
+        return await mutation.mutateAsync({ url, requestBody });
+      } catch (err) {
+        logExecuteSubmitError(err);
+        throw err;
+      }
+    },
+    [session, survey, mutation]
+  );
+
+  return {
+    submit,
+    data: mutation.data ?? null,
+    loading: mutation.isPending,
+    error: mutation.error,
+  };
+}

package/src/submitSurvey/utils/constants.ts

@@ -0,0 +1,4 @@
+/**
+ * The API base URL for submitting survey responses.
+ */
+export const SUBMIT_BASE_URL = 'https://custom-p0.feedbook.me/api/feedback/survey/responseV2';

package/src/submitSurvey/utils/formatters.ts

@@ -0,0 +1,33 @@
+import type { SurveyQuestion } from '../../fetchSurvey/useFetchSurvey';
+import type { SubmitAnswers, SubmitRequestBody } from '../types';
+
+/**
+ * Assembles the full JSON request body structured for response submissions.
+ * Resolves standard vs matrix-level question target mapping.
+ *
+ * @param answers Selected answer map.
+ * @param questions Survey questions list.
+ * @returns Formatted request body matching payload schema.
+ */
+export function buildSubmitRequestBody(
+  answers: SubmitAnswers,
+  questions: SurveyQuestion[]
+): SubmitRequestBody {
+  const questionToAnswers: Record<string, string[]> = {};
+
+  for (const question of questions) {
+    const value = answers[question.id];
+    if (value === undefined || value === null) continue;
+
+    const formatted = String(value);
+    // Submit answer against standard question ID
+    questionToAnswers[question.id] = [formatted];
+  }
+
+  return {
+    questionToAnswers,
+    quesIdVsAttachmentDetails: {},
+    optionLevelAnswers: {},
+    conjointTasks: [],
+  };
+}

package/src/submitSurvey/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './constants';
+export * from './url';
+export * from './formatters';
+export * from './validation';

package/src/submitSurvey/utils/url.ts

@@ -0,0 +1,17 @@
+import { SUBMIT_BASE_URL } from './constants';
+
+/**
+ * Constructs the external URL used to call the remote survey response submit service.
+ *
+ * @param instanceId The active session/instance identifier token.
+ * @param surveyLanguage Optional language locale string (defaults to 'en').
+ * @returns Fully constructed target submit URL.
+ */
+export function buildExternalSubmitUrl(instanceId: string, surveyLanguage = 'en'): string {
+  const params = new URLSearchParams({
+    instanceId,
+    surveySubmitted: 'true',
+    surveyLanguage,
+  });
+  return `${SUBMIT_BASE_URL}?${params.toString()}`;
+}

package/src/submitSurvey/utils/validation.ts

@@ -0,0 +1,48 @@
+import type { Survey, SurveySession } from '../../fetchSurvey/useFetchSurvey';
+import type { SubmitAnswers, SubmitInput } from '../types';
+
+/**
+ * Type guard function validating if input structure is a SubmitInput wrapper.
+ *
+ * @param input The answers map or input object.
+ * @returns Boolean representing validation result.
+ */
+export function isSubmitInput(input: SubmitAnswers | SubmitInput): input is SubmitInput {
+  return typeof input === 'object' && input !== null && 'instanceId' in input && 'answers' in input;
+}
+
+/**
+ * Resolves raw input and session context to a clean, validated SubmitInput model.
+ * Throws errors if session is uninitialized or missing active identifiers.
+ *
+ * @param input Raw selections or input object.
+ * @param session Active survey session details.
+ * @param survey Loaded survey definition.
+ * @returns Resolved input model containing clean parameters.
+ */
+export function resolveSubmitInput(
+  input: SubmitAnswers | SubmitInput,
+  session?: SurveySession | null,
+  survey?: Survey | null
+): SubmitInput {
+  if (isSubmitInput(input)) {
+    return {
+      ...input,
+      surveyLanguage: input.surveyLanguage ?? session?.language ?? 'en',
+      questions: input.questions ?? survey?.pages.flatMap(p => p.questions) ?? [],
+    };
+  }
+
+  // Guard: require session context if not explicitly provided inside input payload
+  if (!session?.instanceId) {
+    throw new Error('Survey session not ready. Fetch survey before submitting.');
+  }
+
+  return {
+    answers: input,
+    instanceId: session.instanceId,
+    surveyLanguage: session.language ?? 'en',
+    questions: survey?.pages.flatMap(p => p.questions) ?? [],
+    //to handle mutliple page strcuture
+  };
+}

package/src/surveyPagination/actions/index.ts

@@ -0,0 +1,4 @@
+export { useOnBack } from './useOnBack';
+export { useOnChange } from './useOnChange';
+export { useOnNext } from './useOnNext';
+export { useOnSubmit } from './useOnSubmit';

package/src/surveyPagination/actions/useOnBack.ts

@@ -0,0 +1,37 @@
+import { useCallback } from 'react';
+import { logBackNavigation } from '../logger/navigationLogger';
+import type { SurveyPaginationContext } from '../types';
+import { scrollToFirstQuestionOfPage } from '../utils';
+
+export function useOnBack(context: SurveyPaginationContext) {
+  const { currentPageIndex, setCurrentPageIndex, trackPageTime, pages, values, paginationRefs } = context;
+
+  return useCallback(() => {
+    if (currentPageIndex > 0) {
+      logBackNavigation(currentPageIndex);
+
+      // Track page time spent
+      trackPageTime(currentPageIndex);
+
+      const refs = paginationRefs.current;
+      // Increment backtrack count
+      refs.backtrackCount += 1;
+
+      // Snapshot the values of the page we are heading back to
+      const targetPageIndex = currentPageIndex - 1;
+      const targetPageQuestions = pages[targetPageIndex]?.questions ?? [];
+      const answersSnapshot: Record<string, any> = {};
+      targetPageQuestions.forEach(q => {
+        answersSnapshot[q.id] = values[q.id];
+      });
+
+      refs.backtrackSnapshots[targetPageIndex] = {
+        fromPageIndex: currentPageIndex,
+        snapshot: answersSnapshot,
+      };
+
+      setCurrentPageIndex(targetPageIndex);
+      scrollToFirstQuestionOfPage(pages, targetPageIndex);
+    }
+  }, [currentPageIndex, setCurrentPageIndex, trackPageTime, pages, values, paginationRefs]);
+}

package/src/surveyPagination/actions/useOnChange.ts

@@ -0,0 +1,16 @@
+import { useCallback } from 'react';
+import { logChangeAnswer } from '../logger/navigationLogger';
+import type { SurveyPaginationContext } from '../types';
+
+export function useOnChange(context: SurveyPaginationContext) {
+  const { setValues, setValidationErrors } = context;
+
+  return useCallback(
+    (questionId: string, value: string | number) => {
+      logChangeAnswer(questionId, value);
+      setValues(prev => ({ ...prev, [questionId]: value }));
+      setValidationErrors(prev => ({ ...prev, [questionId]: '' }));
+    },
+    [setValues, setValidationErrors]
+  );
+}

package/src/surveyPagination/actions/useOnNext.ts

@@ -0,0 +1,99 @@
+import { useCallback } from 'react';
+import { logNextNavigation, logScrollWarning } from '../logger/navigationLogger';
+import { logValidationErrorPage, logValidationFailedSubmit } from '../logger/validationLogger';
+import { trackValidationError } from '../telemetry/pageTelemetry';
+import { validateQuestions, findQuestionElement, scrollToFirstQuestionOfPage } from '../utils';
+import type { SurveyPaginationContext } from '../types';
+
+export function useOnNext(context: SurveyPaginationContext, onSubmit: () => void) {
+  const {
+    survey,
+    pages,
+    values,
+    currentPageIndex,
+    setCurrentPageIndex,
+    setValidationErrors,
+    trackPageTime,
+    trackOptionalSkips,
+    checkBacktrackChanges,
+    paginationRefs,
+  } = context;
+
+  const currentPage = pages[currentPageIndex];
+  const currentQuestions = currentPage?.questions ?? [];
+
+  return useCallback(() => {
+    if (!survey || !currentPage) return;
+
+    let errors: Record<string, string> = {};
+    try {
+      errors = validateQuestions(currentQuestions, values, survey.language);
+    } catch (err) {
+      logValidationFailedSubmit(err);
+    }
+
+    const refs = paginationRefs.current;
+
+    if (Object.keys(errors).length > 0) {
+      logValidationErrorPage(errors);
+
+      // Track validation error attempt
+      const attempt = (refs.validationAttempt[currentPageIndex] || 0) + 1;
+      refs.validationAttempt[currentPageIndex] = attempt;
+      refs.validationErrorsCount += 1;
+      refs.validationHistory.push({
+        pageIndex: currentPageIndex,
+        errors,
+        attemptNumber: attempt,
+      });
+
+      trackValidationError(currentPageIndex, errors, attempt);
+
+      setValidationErrors(errors);
+      const firstErrorId = Object.keys(errors)[0];
+      setTimeout(() => {
+        try {
+          const element = findQuestionElement(firstErrorId);
+          if (element) {
+            element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+          }
+        } catch (err) {
+          logScrollWarning('Failed to scroll validation error element into view', err);
+        }
+      }, 50);
+      return;
+    }
+
+    setValidationErrors({});
+
+    // Clear validation attempt on successful page progression
+    delete refs.validationAttempt[currentPageIndex];
+
+    // Track page duration, optional skips, and backtrack changes
+    trackPageTime(currentPageIndex);
+    trackOptionalSkips(currentPageIndex);
+    checkBacktrackChanges(currentPageIndex);
+
+    if (currentPageIndex < pages.length - 1) {
+      logNextNavigation(currentPageIndex);
+      setCurrentPageIndex(prev => prev + 1);
+      scrollToFirstQuestionOfPage(pages, currentPageIndex + 1);
+    } else {
+      onSubmit();
+    }
+  }, [
+    survey,
+    currentPage,
+    currentQuestions,
+    values,
+    currentPageIndex,
+    setCurrentPageIndex,
+    setValidationErrors,
+    trackPageTime,
+    trackOptionalSkips,
+    checkBacktrackChanges,
+    pages,
+    onSubmit,
+    paginationRefs,
+  ]);
+}