@encatch/web-sdk 0.0.13

package/src/hooks/useFetchElligibleFeedbackConfiguration.ts

@@ -0,0 +1,330 @@
+import { useState, useEffect, useRef } from "preact/hooks";
+import {
+  FetchConfigurationListRequest,
+  DeviceInfo,
+  FeedbackConfigurationItem,
+  MasterProperties,
+} from "@encatch/schema";
+import { EncatchApiSDK } from "@encatch/api-sdk";
+import { setPendingFeedbacks, getPendingFeedbacks } from "../utils/feedback-storage";
+import {
+  getFrequencyTracking,
+  initializeOrUpdateTracking,
+} from "../utils/feedback-frequency-storage";
+import { isEligibleByFrequency } from "../utils/duration-utils";
+
+/**
+ * Filter feedbacks based on frequency rules
+ */
+const filterByFrequencyRules = (
+  feedbacks: FeedbackConfigurationItem[]
+): FeedbackConfigurationItem[] => {
+  const frequencyTracking = getFrequencyTracking();
+  const currentTime = Date.now();
+
+  const filtered = feedbacks.filter((fb) => {
+    const fbId = fb.feedbackConfigurationId;
+
+    // Check frequency rules
+    const tracking = frequencyTracking[fbId];
+    if (!tracking) {
+      // Never interacted before, always eligible
+      return true;
+    }
+
+    const eligible = isEligibleByFrequency(tracking, currentTime);
+    return eligible;
+  });
+
+  return filtered;
+};
+
+interface StoredConfiguration {
+  feedbackConfiguration: FeedbackConfigurationItem[];
+  expiry: number;
+  feedbackInterval: number;
+  masterProperties: MasterProperties;
+}
+
+// MD5 hash function
+const md5 = (str: string): string => {
+  const crypto = window.crypto || (window as any).msCrypto;
+  if (!crypto) {
+    // Fallback for older browsers
+    return btoa(str)
+      .replace(/[^a-zA-Z0-9]/g, "")
+      .substring(0, 16);
+  }
+
+  // Simple hash implementation for browser compatibility
+  let hash = 0;
+  if (str.length === 0) return hash.toString();
+
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+
+  return Math.abs(hash).toString(16);
+};
+
+// Function to check if device has changed
+const isNewDevice = (deviceInfo: DeviceInfo): boolean => {
+  const deviceHashKey = "encatch_device_hash";
+
+  // Safety check for deviceInfo
+  if (!deviceInfo || typeof deviceInfo !== "object") {
+    console.warn(
+      "isNewDevice: deviceInfo is null, undefined, or not an object:",
+      deviceInfo
+    );
+    return true; // Treat as new device if deviceInfo is invalid
+  }
+
+  // Helper function to create consistent device string with sorted keys
+  const createDeviceString = (device: DeviceInfo): string => {
+    const deviceKeys = [
+      "$deviceType",
+      "$timezone",
+      "$theme",
+      "$os",
+      "$osVersion",
+      "$appVersion",
+      "$app",
+      "$language",
+    ];
+
+    const orderedDevice: Record<string, any> = {};
+    deviceKeys.forEach((key) => {
+      const value = device[key as keyof DeviceInfo];
+      if (value !== undefined && value !== null) {
+        orderedDevice[key] = value;
+      }
+    });
+
+    return JSON.stringify(orderedDevice);
+  };
+
+  // Check if device_hash flag exists in localStorage
+  const storedHash = localStorage.getItem(deviceHashKey);
+  if (!storedHash) {
+    // No hash found, this is a new device
+    const newHash = md5(createDeviceString(deviceInfo));
+    localStorage.setItem(deviceHashKey, newHash);
+    return true;
+  }
+
+  const currentHash = md5(createDeviceString(deviceInfo));
+
+  // Compare hashes
+  if (currentHash !== storedHash) {
+    // Device has changed, update stored hash
+    localStorage.setItem(deviceHashKey, currentHash);
+    return true;
+  }
+
+  // Device is the same
+  return false;
+};
+
+export const useFetchElligibleFeedbackConfiguration = ({
+  apiKey,
+  hostUrl,
+}: {
+  apiKey: string;
+  hostUrl: string;
+}) => {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [data, setData] = useState<any>(null);
+  const [lastFetchParams, setLastFetchParams] =
+    useState<FetchConfigurationListRequest | null>(null);
+  const lastFetchParamsRef = useRef<FetchConfigurationListRequest | null>(null);
+  const [feedbackInterval, setFeedbackInterval] = useState<number>(0);
+  const [configSyncInterval, setConfigSyncInterval] = useState<number>(15 * 60); // Default 15 minutes
+  const intervalIdRef = useRef<number | null>(null);
+
+  const getStoredConfiguration = (): StoredConfiguration | null => {
+    const stored = sessionStorage.getItem("encatch-configuration");
+    if (!stored) return null;
+
+    const config = JSON.parse(stored) as StoredConfiguration;
+    if (Date.now() > config.expiry) {
+      sessionStorage.removeItem("encatch-configuration");
+      return null;
+    }
+
+    // Always use pending feedbacks as the source of truth
+    const pendingFeedbacks = getPendingFeedbacks();
+    // Filter by frequency rules (includes session views and frequency eligibility)
+    const filteredFeedbacks = filterByFrequencyRules(pendingFeedbacks);
+    config.feedbackConfiguration = filteredFeedbacks;
+
+    return config;
+  };
+
+  const storeConfiguration = (config: StoredConfiguration) => {
+    const syncInterval =
+      config?.masterProperties?.configSyncIntervalSeconds || 15 * 60;
+    const expiry = Date.now() + syncInterval * 1000;
+    const disableAllSurvey =
+      config?.masterProperties?.disableAllSurvey || false;
+    const feedbackIntervalConfig =
+      config?.masterProperties?.feedbackIntervalDuration || 1 * 60;
+    const feedbackConfigurations = disableAllSurvey
+      ? []
+      : config?.feedbackConfiguration || [];
+
+    const storedConfig: StoredConfiguration = {
+      feedbackConfiguration: feedbackConfigurations,
+      expiry,
+      feedbackInterval: feedbackIntervalConfig,
+      masterProperties: config?.masterProperties,
+    };
+
+    setFeedbackInterval(feedbackIntervalConfig);
+    setConfigSyncInterval(syncInterval);
+    sessionStorage.setItem(
+      "encatch-configuration",
+      JSON.stringify(storedConfig)
+    );
+
+    setPendingFeedbacks(feedbackConfigurations);
+
+    // Initialize tracking for new feedbacks (only once when fetching from API)
+    feedbackConfigurations.forEach((fb) => {
+      if (fb.frequencyAndScheduling) {
+        initializeOrUpdateTracking(
+          fb.feedbackConfigurationId,
+          fb.frequencyAndScheduling as any
+        );
+      }
+    });
+  };
+
+  const sdk = new EncatchApiSDK({
+    apiKey,
+    hostUrl,
+    appPackageName: window.location.hostname, // Or your app's package name
+    enableLogging: true,
+  });
+  const fetchConfiguration = async (params: FetchConfigurationListRequest) => {
+    setLastFetchParams(params);
+    lastFetchParamsRef.current = params;
+    setLoading(true);
+    setError(null);
+
+    // Check if we should use stored configuration
+    if (!params.force) {
+      const storedConfig = getStoredConfiguration();
+      if (storedConfig) {
+        const pendingFeedbacks = getPendingFeedbacks();
+        const filteredFeedbacks = filterByFrequencyRules(pendingFeedbacks);
+        setData(filteredFeedbacks);
+        setFeedbackInterval(storedConfig.feedbackInterval);
+        const syncInterval = storedConfig.masterProperties?.configSyncIntervalSeconds || 15 * 60;
+        setConfigSyncInterval(syncInterval);
+        setLoading(false);
+        return filteredFeedbacks;
+      }
+    } else {
+      sessionStorage.removeItem("encatch-configuration");
+    }
+
+    try {
+      const isNew = isNewDevice(params.deviceInfo);
+      let result;
+      if (isNew) {
+        result = await sdk.fetchNewDeviceConfiguration(params);
+      } else {
+        result = await sdk.fetchConfiguration(params);
+      }
+
+      storeConfiguration(result);
+
+      const pendingFeedbacks = getPendingFeedbacks();
+      setData(pendingFeedbacks);
+      return result;
+    } catch (err) {
+      const errorMessage =
+        err instanceof Error ? err.message : "An error occurred";
+      setError(errorMessage);
+      throw new Error(errorMessage);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const checkAndRefetchIfNeeded = () => {
+    const storedConfig = getStoredConfiguration();
+    const params = lastFetchParamsRef.current;
+
+    if (!storedConfig && params) {
+      // Configuration has expired, refetch
+      fetchConfiguration({ ...params, force: true });
+    }
+  };
+
+  const refreshPendingFeedbacks = () => {
+    const pendingFeedbacks = getPendingFeedbacks();
+    const filteredFeedbacks = filterByFrequencyRules(pendingFeedbacks);
+    setData(filteredFeedbacks);
+  };
+
+  const startInterval = () => {
+    if (intervalIdRef.current === null && configSyncInterval > 0) {
+      const intervalMs = configSyncInterval * 1000;
+      intervalIdRef.current = window.setInterval(
+        checkAndRefetchIfNeeded,
+        intervalMs
+      );
+    }
+  };
+
+  const stopInterval = () => {
+    if (intervalIdRef.current !== null) {
+      window.clearInterval(intervalIdRef.current);
+      intervalIdRef.current = null;
+    }
+  };
+
+  useEffect(() => {
+    if (document.visibilityState === "visible") {
+      startInterval();
+    }
+
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "visible") {
+        checkAndRefetchIfNeeded();
+        startInterval();
+      } else {
+        stopInterval();
+      }
+    };
+
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+
+    return () => {
+      stopInterval();
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, []);
+
+  // Restart interval when configSyncInterval changes
+  useEffect(() => {
+    if (document.visibilityState === "visible" && configSyncInterval > 0) {
+      stopInterval();
+      startInterval();
+    }
+  }, [configSyncInterval]);
+
+  return {
+    data,
+    loading,
+    error,
+    fetchConfiguration,
+    feedbackInterval,
+    refreshPendingFeedbacks,
+  };
+};

package/src/hooks/useFetchFeedbackConfigurationDetails.ts

@@ -0,0 +1,82 @@
+import { EncatchApiSDK } from "@encatch/api-sdk";
+import { FetchFeedbackDetailsRequest, FetchFeedbackDetailsResponse} from "@encatch/schema";
+import { useState } from "preact/hooks";
+
+export const useFetchFeedbackConfigurationDetails = (
+  {apiKey, hostUrl}:{apiKey: string, hostUrl:string}
+) => {
+  const [loadingFetchDetails, setLoadingFetchDetails] = useState(false);
+  const [errorFetchDetails, setErrorFetchDetails] = useState<string | null>(null);
+  const [successFetchDetails, setSuccessFetchDetails] = useState(false);
+    // Instantiate the SDK once
+  const sdk = new EncatchApiSDK({
+    apiKey,
+    hostUrl,
+    appPackageName: window.location.hostname,
+    enableLogging: true,
+  });
+
+  const fetchDetails = async (params: FetchFeedbackDetailsRequest): Promise<FetchFeedbackDetailsResponse | null> => {
+    setLoadingFetchDetails(true);
+    setErrorFetchDetails(null);
+    setSuccessFetchDetails(false);
+    
+      try {
+      // Prepare request in the shape expected by the SDK
+      const sdkParams: FetchFeedbackDetailsRequest = {
+        formConfig: {
+          feedbackConfigurationId: params.formConfig.feedbackConfigurationId,
+          responseLanguageCode: params.formConfig.responseLanguageCode,
+        },
+        deviceInfo: params.deviceInfo,
+        sessionInfo: {
+          $sessionId: params.sessionInfo.$sessionId,
+        },
+        userInfo: params.userInfo,
+      };
+
+      const result: FetchFeedbackDetailsResponse = await sdk.fetchConfigurationDetails(sdkParams);
+
+      // Validate that response has the required properties of ConfigurationResponse
+      const isValidResponse = result &&
+        typeof result === 'object' &&
+        'feedbackConfigurationId' in result &&
+        'formConfiguration' in result &&
+        'questionnaireFields' in result &&
+        'otherConfigurationProperties' in result &&
+        'welcomeScreenProperties' in result &&
+        'endScreenProperties' in result;
+
+      if (!isValidResponse) {
+        throw new Error('Invalid response format from server');
+      }
+
+      setSuccessFetchDetails(true);
+
+      // Map camelCase SDK response to your expected ConfigurationResponse shape if needed
+      return {
+        feedbackConfigurationId: result.feedbackConfigurationId,
+        feedbackIdentifier: result.feedbackIdentifier,
+        formConfiguration: result.formConfiguration,
+        questionnaireFields: result.questionnaireFields,
+        otherConfigurationProperties: result.otherConfigurationProperties,
+        welcomeScreenProperties: result.welcomeScreenProperties,
+        endScreenProperties: result.endScreenProperties,
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : "An error occurred while fetching configuration details";
+      setErrorFetchDetails(errorMessage);
+      return null;
+    } finally {
+      setLoadingFetchDetails(false);
+    }
+  };
+
+
+  return {
+    loadingFetchDetails,
+    errorFetchDetails,
+    successFetchDetails,
+    fetchDetails,
+  };
+};

package/src/hooks/usePageChangeTracker.ts

@@ -0,0 +1,88 @@
+import { useEffect } from "preact/hooks";
+
+interface LocationChangeProps {
+  eventName?: string;
+  trackEvent: (eventName: string, properties?: Record<string, any>) => void;
+}
+
+// Utility function to extract path from href, handling hash-based routing
+const extractPathFromHref = (href: string): string => {
+  try {
+    const url = new URL(href);
+    // For hash-based routing, we want the hash part as the path
+    if (url.hash && url.hash.length > 1) {
+      // Remove the leading '#' and return the hash path
+      return url.hash.substring(1);
+    }
+    // For regular routing, return the pathname
+    return url.pathname;
+  } catch (error) {
+    // Fallback: try to extract path manually
+    const urlObj = new URL(href, window.location.origin);
+    if (urlObj.hash && urlObj.hash.length > 1) {
+      return urlObj.hash.substring(1);
+    }
+    return urlObj.pathname;
+  }
+};
+
+export const usePageChangeTracker = (props: LocationChangeProps) => {
+  const trackLocationChange = () => {
+    const href = window.location.href;
+    const path = extractPathFromHref(href);
+
+    props.trackEvent(props.eventName || "pageLoad", {
+      url: href,
+      path: path,
+    });
+  };
+
+  useEffect(() => {
+    // Track initial page load
+    trackLocationChange();
+
+    // Track subsequent navigation changes
+    const observer = new MutationObserver(() => {
+      trackLocationChange();
+    });
+
+    // Observe the document title for changes
+    observer.observe(document.querySelector("title") || document.head, {
+      subtree: true,
+      characterData: true,
+      childList: true,
+    });
+
+    // Listen for popstate events (browser back/forward)
+    window.addEventListener("popstate", trackLocationChange);
+
+    // Listen for pushstate events (React Router navigation)
+    const originalPushState = window.history.pushState;
+    window.history.pushState = function (
+      data: any,
+      unused: string,
+      url?: string | URL | null
+    ) {
+      originalPushState.call(this, data, unused, url);
+      trackLocationChange();
+    };
+
+    // Listen for React Router navigation events if available
+    if (window.encatch?.router) {
+      window.encatch.router.subscribe((location: { pathname: string }) => {
+        trackLocationChange();
+      });
+    }
+
+    return () => {
+      observer.disconnect();
+      window.removeEventListener("popstate", trackLocationChange);
+      // Restore original pushState
+      window.history.pushState = originalPushState;
+    };
+  }, []);
+
+  return {
+    trackLocationChange,
+  };
+};

package/src/hooks/usePrepopulatedAnswers.ts

@@ -0,0 +1,123 @@
+// import { QuestionnaireFields } from "src/element/types";
+import { QuestionnaireFieldsResponse } from "@encatch/schema";
+import { PrepopulatedAnswer } from "../feedback-api-types";
+import { updateQuestionResponse } from "../store/formResponses";
+
+// Helper function to extract the actual value from AnswerFormat
+const extractValueFromAnswerFormat = (value: any, questionId: string): any => {
+  // If value is not an object, return it as-is (primitive value)
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+
+  // Define the mapping of answer format properties to their values
+  const answerFormatMap = {
+    nps: value.nps,
+    rating: value.rating,
+    long_text: value.long_text,
+    short_answer: value.short_answer,
+    single_choice: value.single_choice,
+    multiple_choice_multiple: value.multiple_choice_multiple,
+    nested_selection: value.nested_selection,
+    annotation: value.annotation,
+  };
+
+  // Find the first property that exists in the value object
+  for (const [property, propertyValue] of Object.entries(answerFormatMap)) {
+    if (property in value) {
+      return propertyValue;
+    }
+  }
+
+  // If no known property is found, log a warning and return null
+  console.warn(`Unknown answer format for questionId ${questionId}:`, value);
+  return null;
+};
+
+// Function to process prepopulated answers and update the form responses store
+const processPrepopulatedAnswers = (
+  prepopulatedAnswers: PrepopulatedAnswer[],
+  questionnaireFields: QuestionnaireFieldsResponse
+) => {
+  try {
+    const { sections, questions } = questionnaireFields;
+
+    if (!sections || !questions) {
+      console.warn(
+        "Invalid questionnaire fields structure for prepopulated answers"
+      );
+      return;
+    }
+
+    prepopulatedAnswers.forEach((answer) => {
+      try {
+        const { sectionIndex, questionIndex, value } = answer;
+
+        // Validate indices
+        if (sectionIndex < 0 || sectionIndex >= sections.length) {
+          console.warn(
+            `Invalid sectionIndex ${sectionIndex} for prepopulated answer`
+          );
+          return;
+        }
+
+        const section = sections[sectionIndex];
+        if (
+          !section?.questionIds ||
+          questionIndex < 0 ||
+          questionIndex >= section.questionIds.length
+        ) {
+          console.warn(
+            `Invalid questionIndex ${questionIndex} for section ${sectionIndex}`
+          );
+          return;
+        }
+
+        // Get the question ID
+        const questionId = section.questionIds[questionIndex];
+        if (!questionId) {
+          console.warn(
+            `No questionId found at section ${sectionIndex}, question ${questionIndex}`
+          );
+          return;
+        }
+
+        // Get the question details to determine the type
+        const question = questions[questionId];
+        if (!question) {
+          console.warn(
+            `Question details not found for questionId ${questionId}`
+          );
+          return;
+        }
+
+        // Update the form response using the store's helper function
+        // The value is already in AnswerFormat, so we extract the actual value
+        const questionType = question.type;
+        const actualValue = extractValueFromAnswerFormat(value, questionId);
+
+        if (actualValue === null) {
+          return; // Skip if unknown format
+        }
+
+        // Update the question response
+        updateQuestionResponse(questionId, actualValue, questionType);
+      } catch (error) {
+        console.error(
+          "Error processing individual prepopulated answer:",
+          error,
+          answer
+        );
+      }
+    });
+  } catch (error) {
+    console.error("Error processing prepopulated answers:", error);
+  }
+};
+
+export const usePrepopulatedAnswers = () => {
+  return {
+    processPrepopulatedAnswers,
+    extractValueFromAnswerFormat,
+  };
+};

package/src/hooks/useRefineTextForm.ts

@@ -0,0 +1,48 @@
+import { EncatchApiSDK, RefineTextParams, RefineTextResponse } from "@encatch/api-sdk";
+import { useState } from "preact/hooks";
+
+
+export const useRefineTextForm = ({ apiKey, hostUrl }: { apiKey?: string; hostUrl: string }) => {
+  const [loadingRefineText, setLoadingRefineText] = useState(false);
+  const [errorRefineText, setErrorRefineText] = useState<string | null>(null);
+  const [resultRefineText, setResultRefineText] = useState<RefineTextResponse | null>(null);
+  const [successMsg, setSuccessMsg] = useState<string | null>(null);
+
+  // Instantiate the SDK once
+  const sdk = new EncatchApiSDK({
+    apiKey: apiKey || "",
+    hostUrl,
+    appPackageName: window.location.hostname,
+    enableLogging: true,
+  });
+
+  const refineText = async (params: RefineTextParams): Promise<RefineTextResponse | null> => {
+    setLoadingRefineText(true);
+    setErrorRefineText(null);
+    setResultRefineText(null);
+
+    try {
+      // Use the SDK's refineText method
+      const result = await sdk.refineText(params);
+
+      setSuccessMsg(result.message || "Text refined successfully");
+
+      setResultRefineText(result);
+      return result;
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : "An error occurred while refining text";
+      setErrorRefineText(errorMessage);
+      return null;
+    } finally {
+      setLoadingRefineText(false);
+    }
+  };
+
+  return {
+    loadingRefineText,
+    errorRefineText,
+    resultRefineText,
+    refineText,
+    successMsg
+  };
+};