@ram_28/kf-ai-sdk 1.0.18 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",

package/sdk/api/client.ts

@@ -379,7 +379,13 @@ export function api<T = any>(bo_id: string): ResourceClient<T> {
         );
       }
 
-      return response.json();
+      const json = await response.json();
+      // API returns {"Data":{"_id":"..."},"ValidationFailures":[]}
+      // Extract _id from Data wrapper and return flat structure
+      return {
+        ...json.Data,
+        _id: json.Data._id,
+      };
     },
 
     // ============================================================

package/sdk/components/hooks/useFilter/types.ts

@@ -57,18 +57,21 @@ export interface ConditionGroupBuilder {
 
 /**
  * Hook options (minimal configuration)
+ * Used for initializing useFilter, and also for initialState in useTable/useKanban
+ * @template T - Data type for type-safe field names (defaults to any)
  */
-export interface UseFilterOptionsType {
-  /** Initial filter conditions */
-  initialConditions?: Array<ConditionType | ConditionGroupType>;
-  /** Initial operator for combining conditions (defaults to "And") */
-  initialOperator?: ConditionGroupOperatorType;
+export interface UseFilterOptionsType<T = any> {
+  /** Filter conditions */
+  conditions?: Array<ConditionType<T> | ConditionGroupType<T>>;
+  /** Operator for combining conditions (defaults to "And") */
+  operator?: ConditionGroupOperatorType;
 }
 
 /**
  * Hook return interface with nested filter support
+ * @template T - Data type for type-safe field names (defaults to any)
  */
-export interface UseFilterReturnType {
+export interface UseFilterReturnType<T = any> {
   // ============================================================
   // STATE (read-only)
   // ============================================================
@@ -77,10 +80,10 @@ export interface UseFilterReturnType {
   operator: ConditionGroupOperatorType;
 
   /** Current filter items (with id populated) */
-  items: Array<ConditionType | ConditionGroupType>;
+  items: Array<ConditionType<T> | ConditionGroupType<T>>;
 
   /** Ready-to-use API payload (id stripped, undefined if no conditions) */
-  payload: FilterType | undefined;
+  payload: FilterType<T> | undefined;
 
   /** Whether any conditions exist */
   hasConditions: boolean;
@@ -95,7 +98,7 @@ export interface UseFilterReturnType {
    * @param parentId - Optional id of the parent ConditionGroup. If omitted, adds at root level
    * @returns The id of the created condition
    */
-  addCondition: (condition: Omit<ConditionType, "id">, parentId?: string) => string;
+  addCondition: (condition: Omit<ConditionType<T>, "id">, parentId?: string) => string;
 
   /**
    * Add a condition group at root level or to a specific parent group
@@ -114,7 +117,7 @@ export interface UseFilterReturnType {
    * @param id - The id of the condition to update
    * @param updates - Partial updates to apply
    */
-  updateCondition: (id: string, updates: Partial<Omit<ConditionType, "id">>) => void;
+  updateCondition: (id: string, updates: Partial<Omit<ConditionType<T>, "id">>) => void;
 
   /**
    * Update a condition group's operator by id
@@ -138,7 +141,7 @@ export interface UseFilterReturnType {
    * @param id - The id to look up
    * @returns The item or undefined if not found
    */
-  getCondition: (id: string) => ConditionType | ConditionGroupType | undefined;
+  getCondition: (id: string) => ConditionType<T> | ConditionGroupType<T> | undefined;
 
   // ============================================================
   // UTILITY

package/sdk/components/hooks/useFilter/useFilter.ts

@@ -16,9 +16,11 @@ let idCounter = 0;
 
 /**
  * Generate a unique ID for conditions and groups
+ * Uses timestamp + random component + counter to prevent collisions
  */
 const generateId = (): string => {
-  return `filter_${Date.now()}_${++idCounter}`;
+  const random = Math.random().toString(36).substring(2, 9);
+  return `filter_${Date.now()}_${random}_${++idCounter}`;
 };
 
 /**
@@ -178,22 +180,22 @@ const addToParent = (
 // USE FILTER HOOK - Nested Filter Support
 // ============================================================
 
-export function useFilter(options: UseFilterOptionsType = {}): UseFilterReturnType {
+export function useFilter<T = any>(options: UseFilterOptionsType<T> = {}): UseFilterReturnType<T> {
   // Initialize items with ids
-  const [items, setItems] = useState<Array<ConditionType | ConditionGroupType>>(() =>
-    cloneWithIds(options.initialConditions || [])
+  const [items, setItems] = useState<Array<ConditionType<T> | ConditionGroupType<T>>>(() =>
+    cloneWithIds(options.conditions || []) as Array<ConditionType<T> | ConditionGroupType<T>>
   );
 
   const [operator, setOperatorState] = useState<ConditionGroupOperatorType>(
-    options.initialOperator || "And"
+    options.operator || "And"
   );
 
   // Build payload for API (strip ids)
-  const payload = useMemo((): FilterType | undefined => {
+  const payload = useMemo((): FilterType<T> | undefined => {
     if (items.length === 0) return undefined;
     return {
       Operator: operator,
-      Condition: stripIds(items),
+      Condition: stripIds(items) as Array<ConditionType<T> | ConditionGroupType<T>>,
     };
   }, [items, operator]);
 
@@ -204,11 +206,11 @@ export function useFilter(options: UseFilterOptionsType = {}): UseFilterReturnTy
   // ============================================================
 
   const addCondition = useCallback(
-    (condition: Omit<ConditionType, "id">, parentId?: string): string => {
+    (condition: Omit<ConditionType<T>, "id">, parentId?: string): string => {
       const id = generateId();
-      const newCondition: ConditionType = { ...condition, id };
+      const newCondition = { ...condition, id } as ConditionType<T>;
       if (parentId) {
-        setItems((prev) => addToParent(prev, parentId, newCondition));
+        setItems((prev) => addToParent(prev, parentId, newCondition) as Array<ConditionType<T> | ConditionGroupType<T>>);
       } else {
         setItems((prev) => [...prev, newCondition]);
       }
@@ -220,13 +222,13 @@ export function useFilter(options: UseFilterOptionsType = {}): UseFilterReturnTy
   const addConditionGroup = useCallback(
     (groupOperator: ConditionGroupOperatorType, parentId?: string): string => {
       const id = generateId();
-      const newGroup: ConditionGroupType = {
+      const newGroup: ConditionGroupType<T> = {
         id,
         Operator: groupOperator,
         Condition: [],
       };
       if (parentId) {
-        setItems((prev) => addToParent(prev, parentId, newGroup));
+        setItems((prev) => addToParent(prev, parentId, newGroup) as Array<ConditionType<T> | ConditionGroupType<T>>);
       } else {
         setItems((prev) => [...prev, newGroup]);
       }
@@ -240,14 +242,14 @@ export function useFilter(options: UseFilterOptionsType = {}): UseFilterReturnTy
   // ============================================================
 
   const updateCondition = useCallback(
-    (id: string, updates: Partial<Omit<ConditionType, "id">>): void => {
+    (id: string, updates: Partial<Omit<ConditionType<T>, "id">>): void => {
       setItems((prev) =>
         updateInTree(prev, id, (item) => {
           if (!isConditionGroup(item)) {
             return { ...item, ...updates };
           }
           return item;
-        })
+        }) as Array<ConditionType<T> | ConditionGroupType<T>>
       );
     },
     []
@@ -261,7 +263,7 @@ export function useFilter(options: UseFilterOptionsType = {}): UseFilterReturnTy
             return { ...item, Operator: newOperator };
           }
           return item;
-        })
+        }) as Array<ConditionType<T> | ConditionGroupType<T>>
       );
     },
     []
@@ -272,12 +274,12 @@ export function useFilter(options: UseFilterOptionsType = {}): UseFilterReturnTy
   // ============================================================
 
   const removeCondition = useCallback((id: string): void => {
-    setItems((prev) => removeFromTree(prev, id));
+    setItems((prev) => removeFromTree(prev, id) as Array<ConditionType<T> | ConditionGroupType<T>>);
   }, []);
 
   const getCondition = useCallback(
-    (id: string): ConditionType | ConditionGroupType | undefined => {
-      return findById(items, id);
+    (id: string): ConditionType<T> | ConditionGroupType<T> | undefined => {
+      return findById(items, id) as ConditionType<T> | ConditionGroupType<T> | undefined;
     },
     [items]
   );

package/sdk/components/hooks/useForm/apiClient.ts

@@ -5,6 +5,7 @@
 
 import { api, getBdoSchema } from "../../../api";
 import type { BDOSchemaType, FormOperationType, SubmissionResultType } from "./types";
+import { toError } from "../../../utils/error-handling";
 
 // ============================================================
 // SCHEMA FETCHING
@@ -47,7 +48,7 @@ export async function fetchFormSchemaWithRetry(
     try {
       return await fetchFormSchema(source);
     } catch (error) {
-      lastError = error as Error;
+      lastError = toError(error);
 
       if (attempt < maxRetries) {
         // Wait before retrying (exponential backoff)

package/sdk/components/hooks/useForm/useForm.ts

@@ -29,6 +29,7 @@ import {
 import { api } from "../../../api";
 
 import { validateCrossField } from "./expressionValidator.utils";
+import { toError } from "../../../utils/error-handling";
 import {
   validateFieldOptimized,
   getFieldDependencies,
@@ -81,6 +82,9 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
   // This allows us to detect changes since the last draft, not since form init
   const lastSyncedValuesRef = useRef<Partial<T> | null>(null);
 
+  // Track if draft creation has started (prevents duplicate calls in React strict mode)
+  const draftCreationStartedRef = useRef(false);
+
   // Stable callback ref to prevent dependency loops
   const onSchemaErrorRef = useRef(onSchemaError);
 
@@ -181,11 +185,16 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         if (Object.keys(refFields).length > 0) {
           fetchAllReferenceData(refFields)
             .then(setReferenceData)
-            .catch(console.warn);
+            .catch((err) => {
+              const error = toError(err);
+              console.warn("Failed to fetch reference data:", error);
+              // Notify via callback but don't block form - reference data is non-critical
+              onSchemaErrorRef.current?.(error);
+            });
         }
       } catch (error) {
         console.error("Schema processing failed:", error);
-        onSchemaErrorRef.current?.(error as Error);
+        onSchemaErrorRef.current?.(toError(error));
       }
     }
   }, [schema, userRole]); // Removed onSchemaError - using ref instead
@@ -209,11 +218,18 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       operation !== "create" ||
       !schemaConfig ||
       !enabled ||
-      draftId
+      draftId ||
+      draftCreationStartedRef.current  // Prevent duplicate calls in React strict mode
     ) {
       return;
     }
 
+    // Mark as started immediately to prevent duplicate calls
+    draftCreationStartedRef.current = true;
+
+    // Track if effect is still active (for cleanup/race condition handling)
+    let isActive = true;
+
     const createInitialDraft = async () => {
       setIsCreatingDraft(true);
       setDraftError(null);
@@ -223,6 +239,9 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         // Call PATCH /{bdo_id}/draft with empty payload to get draft ID
         const response = await client.draftInteraction({});
 
+        // Check if effect is still active before setting state
+        if (!isActive) return;
+
         // Store the draft ID
         setDraftId(response._id);
 
@@ -242,15 +261,29 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
           });
         }
       } catch (error) {
+        // Check if effect is still active before setting state
+        if (!isActive) return;
+
         console.error("Failed to create initial draft:", error);
-        setDraftError(error as Error);
+        setDraftError(toError(error));
+        // Reset the ref on error so it can be retried
+        draftCreationStartedRef.current = false;
       } finally {
-        setIsCreatingDraft(false);
+        // Check if effect is still active before setting state
+        if (isActive) {
+          setIsCreatingDraft(false);
+        }
       }
     };
 
     createInitialDraft();
-  }, [isInteractiveMode, operation, schemaConfig, enabled, draftId, source, rhfForm]);
+
+    // Cleanup function to handle unmount during async operation
+    return () => {
+      isActive = false;
+    };
+  }, [isInteractiveMode, operation, schemaConfig, enabled, draftId, source]);
+  // Note: rhfForm removed from deps - we use ref pattern to avoid dependency loops
 
   // ============================================================
   // COMPUTED FIELD DEPENDENCY TRACKING AND OPTIMIZATION
@@ -321,10 +354,11 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       }
 
       // Determine if draft should be triggered based on interaction mode
-      // Interactive mode: Always trigger draft API on blur
+      // For update mode, always behave as non-interactive (only trigger for computed deps)
+      // Interactive mode (create only): Always trigger draft API on blur
       // Non-interactive mode: Only trigger for computed field dependencies
-      const shouldTrigger = isInteractiveMode
-        ? true // Interactive mode: always trigger
+      const shouldTrigger = (isInteractiveMode && operation !== "update")
+        ? true // Interactive mode (create only): always trigger
         : (computedFieldDependencies.length > 0 &&
               computedFieldDependencies.includes(fieldName as Path<T>));
 
@@ -643,8 +677,8 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 } as any);
                 result = { success: true, data: response };
               } else {
-                // Interactive update: POST /{bdo_id}/{id}/draft
-                const response = await client.draftUpdate(recordId!, cleanedData);
+                // Update operation - always use direct update API (non-interactive)
+                const response = await client.update(recordId!, cleanedData);
                 result = { success: true, data: response };
               }
             } else {
@@ -674,7 +708,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
             await onSuccess?.(result.data || data, event);
           } catch (error) {
             // API error - call onError with Error object
-            onError?.(error as Error, event);
+            onError?.(toError(error), event);
           } finally {
             setIsSubmitting(false);
           }
@@ -930,7 +964,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     isCreatingDraft,
 
     // Error handling
-    loadError: loadError as Error | null,
+    loadError: loadError ? toError(loadError) : null,
     hasError,
 
     // Schema information

package/sdk/components/hooks/useKanban/context.ts

@@ -1,13 +1,15 @@
 import { createContext, useContext } from "react";
-import { UseKanbanReturnType } from "./types";
+import type { UseKanbanReturnType } from "./types";
 
-export const KanbanContext = createContext<UseKanbanReturnType<any> | null>(null);
+export const KanbanContext = createContext<UseKanbanReturnType<any> | null>(
+  null,
+);
 
 export function useKanbanContext<T extends Record<string, any> = any>() {
   const context = useContext(KanbanContext);
   if (!context) {
     throw new Error(
-      "Kanban components must be used within a KanbanBoard component"
+      "Kanban components must be used within a KanbanBoard component",
     );
   }
   return context as UseKanbanReturnType<T>;

package/sdk/components/hooks/useKanban/types.ts

@@ -4,8 +4,11 @@
 // Core TypeScript interfaces for the kanban board functionality
 // Following patterns from useTable and useForm
 
-import type { ConditionType, ConditionGroupType, UseFilterReturnType } from "../useFilter";
-import type { ConditionGroupOperatorType } from "../../../types/common";
+import type { UseFilterReturnType, UseFilterOptionsType } from "../useFilter";
+import type { ColumnDefinitionType } from "../../../types/common";
+
+// Re-export ColumnDefinitionType for backwards compatibility
+export type { ColumnDefinitionType };
 
 // ============================================================
 // CORE DATA STRUCTURES
@@ -95,23 +98,6 @@ export interface KanbanColumnType<T = Record<string, any>> {
   _modified_at?: Date;
 }
 
-/**
- * Column definition for display and behavior
- * Similar to ColumnDefinition in useTable
- */
-export interface ColumnDefinitionType<T> {
-  /** Field name from the card type */
-  fieldId: keyof T;
-  /** Display label (optional, defaults to fieldId) */
-  label?: string;
-  /** Enable sorting for this field */
-  enableSorting?: boolean;
-  /** Enable filtering for this field */
-  enableFiltering?: boolean;
-  /** Custom transform function (overrides auto-formatting) */
-  transform?: (value: any, card: T) => React.ReactNode;
-}
-
 // ============================================================
 // DRAG & DROP TYPES
 // ============================================================
@@ -195,10 +181,8 @@ export interface UseKanbanOptionsType<T> {
 
   /** Initial state */
   initialState?: {
-    /** Initial filter conditions */
-    filters?: Array<ConditionType | ConditionGroupType>;
-    /** Initial filter operator for combining filter conditions */
-    filterOperator?: ConditionGroupOperatorType;
+    /** Initial filter configuration: { conditions, operator } */
+    filter?: UseFilterOptionsType;
     /** Initial search query */
     search?: string;
     /** Initial column order */

package/sdk/components/hooks/useKanban/useKanban.ts

@@ -7,6 +7,7 @@ import { useState, useMemo, useCallback, useRef, useEffect } from "react";
 import { useQuery, useMutation, useQueryClient, useQueries, keepPreviousData } from "@tanstack/react-query";
 import { api } from "../../../api";
 import type { ListOptionsType, ListResponseType } from "../../../types/common";
+import { toError } from "../../../utils/error-handling";
 import { useFilter } from "../useFilter";
 
 import type {
@@ -41,8 +42,13 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
 
   const [search, setSearch] = useState({
     query: initialState?.search || "",
+    debouncedQuery: initialState?.search || "",
   });
 
+  // Debounce timeout ref for search
+  const searchDebounceRef = useRef<NodeJS.Timeout | null>(null);
+  const SEARCH_DEBOUNCE_MS = 300;
+
   const [sorting] = useState({
     field: initialState?.sorting?.field || null,
     direction: initialState?.sorting?.direction || null,
@@ -81,8 +87,8 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
   // ============================================================
 
   const filter = useFilter({
-    initialConditions: initialState?.filters,
-    initialOperator: initialState?.filterOperator || "And",
+    conditions: initialState?.filter?.conditions,
+    operator: initialState?.filter?.operator || "And",
   });
 
   // Helper to generate API options for a specific column
@@ -139,13 +145,13 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
         ];
       }
 
-      // Add Search
-      if (search.query) {
-        opts.Search = search.query;
+      // Add Search (debounced)
+      if (search.debouncedQuery) {
+        opts.Search = search.debouncedQuery;
       }
 
       return opts;
-  }, [filter.payload, columnPagination, sorting, search.query]);
+  }, [filter.payload, columnPagination, sorting, search.debouncedQuery]);
 
   // ============================================================
   // COLUMN QUERY GENERATION
@@ -180,10 +186,10 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
   const cardApiOptions = useMemo((): ListOptionsType => {
       // This is for the GLOBAL count (ignoring column split)
       const opts: ListOptionsType = {};
-      if (search.query) opts.Search = search.query;
+      if (search.debouncedQuery) opts.Search = search.debouncedQuery;
       if (filter.payload) opts.Filter = filter.payload;
       return opts;
-  }, [search.query, filter.payload]);
+  }, [search.debouncedQuery, filter.payload]);
 
   const {
     data: countData,
@@ -196,7 +202,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
         return await api<KanbanCardType<T>>(source).count(cardApiOptions);
       } catch (err) {
         if (onErrorRef.current) {
-          onErrorRef.current(err as Error);
+          onErrorRef.current(toError(err));
         }
         throw err;
       }
@@ -258,7 +264,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
       if (context?.previousCards && context?.queryKey) {
         queryClient.setQueryData(context.queryKey, context.previousCards);
       }
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: (_data, _error, variables) => {
        const columnId = variables.columnId;
@@ -280,7 +286,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
       onCardUpdateRef.current?.({ _id: result.id, ...result.updates } as any);
     },
     onError: (error, _variables, _context) => {
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: () => {
        queryClient.invalidateQueries({ queryKey: ["kanban-cards", source] });
@@ -300,7 +306,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
       onCardDeleteRef.current?.(id);
     },
     onError: (error, _id, _context) => {
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: () => {
        queryClient.invalidateQueries({ queryKey: ["kanban-cards", source] });
@@ -374,7 +380,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
       if (context?.previousToData && context?.toQueryKey) {
         queryClient.setQueryData(context.toQueryKey, context.previousToData);
       }
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: (_data, _error, variables) => {
        const fromOpts = getColumnApiOptions(variables.fromColumnId);
@@ -401,7 +407,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
     },
     onSuccess: () => {},
     onError: (error, _variables, _context) => {
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: (_data, _error, variables) => {
        const opts = getColumnApiOptions(variables.columnId);
@@ -513,11 +519,32 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
   // ============================================================
 
   const setSearchQuery = useCallback((value: string) => {
-    setSearch({ query: value });
+    // Validate search query length to prevent DoS
+    if (value.length > 255) {
+      console.warn("Search query exceeds maximum length of 255 characters");
+      return;
+    }
+
+    // Update immediate value for UI
+    setSearch((prev) => ({ ...prev, query: value }));
+
+    // Clear existing debounce timeout
+    if (searchDebounceRef.current) {
+      clearTimeout(searchDebounceRef.current);
+    }
+
+    // Debounce the actual API query update
+    searchDebounceRef.current = setTimeout(() => {
+      setSearch((prev) => ({ ...prev, debouncedQuery: value }));
+    }, SEARCH_DEBOUNCE_MS);
   }, []);
 
   const clearSearch = useCallback(() => {
-    setSearch({ query: "" });
+    // Clear debounce timeout
+    if (searchDebounceRef.current) {
+      clearTimeout(searchDebounceRef.current);
+    }
+    setSearch({ query: "", debouncedQuery: "" });
   }, []);
 
   const totalCards = countData?.Count || 0;
@@ -555,10 +582,19 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
 
   useEffect(() => {
     if (error && onErrorRef.current) {
-      onErrorRef.current(error as Error);
+      onErrorRef.current(toError(error));
     }
   }, [error]);
 
+  // Cleanup debounce timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (searchDebounceRef.current) {
+        clearTimeout(searchDebounceRef.current);
+      }
+    };
+  }, []);
+
   // ============================================================
   // RETURN OBJECT
   // ============================================================
@@ -574,7 +610,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
     isUpdating,
 
     // Error Handling
-    error: error as Error | null,
+    error: error ? toError(error) : null,
 
     // Card Operations (Flat Access)
     createCard: createCardMutation.mutateAsync,