refactor(shared): update utilities, API layer, and types

src/shared/api/queryClient.ts

@@ -1,24 +1,33 @@
 import { QueryClient } from '@tanstack/query-core';
 
 /**
- * Query client instance
+ * TanStack Query client instance
+ *
+ * Configured for optimal caching and refetching behavior.
+ * Used by all font stores for data fetching and caching.
+ *
+ * Cache behavior:
+ * - Data stays fresh for 5 minutes (staleTime)
+ * - Unused data is garbage collected after 10 minutes (gcTime)
+ * - No refetch on window focus (reduces unnecessary network requests)
+ * - 3 retries with exponential backoff on failure
  */
 export const queryClient = new QueryClient({
     defaultOptions: {
         queries: {
-            /**
-             * Default staleTime: 5 minutes
-             */
+            /** Data remains fresh for 5 minutes after fetch */
             staleTime: 5 * 60 * 1000,
-            /**
-             * Default gcTime: 10 minutes
-             */
+            /** Unused cache entries are removed after 10 minutes */
             gcTime: 10 * 60 * 1000,
+            /** Don't refetch when window regains focus */
             refetchOnWindowFocus: false,
+            /** Refetch on mount if data is stale */
             refetchOnMount: true,
+            /** Retry failed requests up to 3 times */
             retry: 3,
             /**
-             * Exponential backoff
+             * Exponential backoff for retries
+             * 1s, 2s, 4s, 8s... capped at 30s
              */
             retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
         },