@ram_28/kf-ai-sdk 1.0.19 → 1.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "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

@@ -9,8 +9,6 @@ import type {
   CreateUpdateResponseType,
   DeleteResponseType,
   CountResponseType,
-  DateTimeEncodedType,
-  DateEncodedType,
   MetricOptionsType,
   MetricResponseType,
   PivotOptionsType,
@@ -157,40 +155,6 @@ export function getApiBaseUrl(): string {
   return apiConfig.baseUrl || "";
 }
 
-/**
- * Recursively process an object to decode datetime fields
- */
-function decodeResponseData<T>(data: any): T {
-  if (data === null || data === undefined) {
-    return data;
-  }
-
-  if (Array.isArray(data)) {
-    return data.map((item) => decodeResponseData(item)) as T;
-  }
-
-  if (typeof data === "object") {
-    // Check for datetime encoding
-    if ("$__dt__" in data) {
-      return new Date((data as DateTimeEncodedType).$__dt__ * 1000) as T;
-    }
-
-    // Check for date encoding
-    if ("$__d__" in data) {
-      return new Date((data as DateEncodedType).$__d__) as T;
-    }
-
-    // Recursively process object properties
-    const result: any = {};
-    for (const [key, value] of Object.entries(data)) {
-      result[key] = decodeResponseData(value);
-    }
-    return result as T;
-  }
-
-  return data as T;
-}
-
 /**
  * Create a resource client for the specified Business Object
  * @param bo_id - Business Object identifier (e.g., "user", "leave", "vendor")
@@ -212,7 +176,7 @@ export function api<T = any>(bo_id: string): ResourceClient<T> {
       }
 
       const responseData: ReadResponseType<T> = await response.json();
-      return decodeResponseData<T>(responseData.Data);
+      return responseData.Data;
     },
 
     async create(
@@ -278,10 +242,8 @@ export function api<T = any>(bo_id: string): ResourceClient<T> {
         throw new Error(`Failed to list ${bo_id}: ${response.statusText}`);
       }
 
-      const responseData: ListResponseType<any> = await response.json();
-      return {
-        Data: responseData.Data.map((item) => decodeResponseData<T>(item)),
-      };
+      const responseData: ListResponseType<T> = await response.json();
+      return responseData;
     },
 
     async count(options?: ListOptionsType): Promise<CountResponseType> {

package/sdk/api/datetime.ts

@@ -1,33 +1,117 @@
-import type { DateTimeEncodedType, DateEncodedType } from '../types/common';
+import type { DateEncodedType, DateTimeEncodedType } from "../types/base-fields";
 
 /**
- * Utility functions for datetime encoding/decoding
+ * Date format constants matching backend DatetimeFormat class
+ * Source: kf-ai-base/core/util/datetime_utils.py
  */
+export const DatetimeFormat = {
+  /** Date format: "YYYY-MM-DD" */
+  DATE: "%Y-%m-%d",
+  /** Time format: "HH:MM:SS" */
+  TIME: "%H:%M:%S",
+  /** DateTime format: "YYYY-MM-DD HH:MM:SS" */
+  DATE_TIME: "%Y-%m-%d %H:%M:%S",
+} as const;
+
+// ============================================================
+// DECODING FUNCTIONS (API Response → Date object)
+// Use these in components to convert API response to Date
+// ============================================================
 
 /**
- * Encode a Date object to API datetime format
+ * Decode API date response to Date object
+ * @param encoded - API response format { "$__d__": "YYYY-MM-DD" }
+ * @returns JavaScript Date object
+ *
+ * @example
+ * const apiResponse = { "$__d__": "2025-03-15" };
+ * const date = decodeDate(apiResponse); // => Date object
  */
-export function encodeDatetime(date: Date): DateTimeEncodedType {
-  return { $__dt__: date.getTime() / 1000 };
+export function decodeDate(encoded: DateEncodedType): Date {
+  const [year, month, day] = encoded.$__d__.split("-").map(Number);
+  return new Date(year, month - 1, day);
 }
 
 /**
- * Decode API datetime format to Date object
+ * Decode API datetime response to Date object
+ * @param encoded - API response format { "$__dt__": unix_timestamp_seconds }
+ * @returns JavaScript Date object
+ *
+ * @example
+ * const apiResponse = { "$__dt__": 1769110463 };
+ * const date = decodeDateTime(apiResponse); // => Date object
  */
-export function decodeDatetime(encoded: DateTimeEncodedType): Date {
+export function decodeDateTime(encoded: DateTimeEncodedType): Date {
   return new Date(encoded.$__dt__ * 1000);
 }
 
+// ============================================================
+// FORMATTING FUNCTIONS (Date object → API Request string)
+// Use these when creating/updating records
+// ============================================================
+
 /**
- * Encode a Date object to API date format (YYYY-MM-DD)
+ * Format a Date object to API request date string
+ * @param date - JavaScript Date object
+ * @returns "YYYY-MM-DD" formatted string for API requests
+ *
+ * @example
+ * formatDate(new Date(2025, 2, 15)) // => "2025-03-15"
  */
-export function encodeDate(date: Date): DateEncodedType {
-  return { $__d__: date.toISOString().split('T')[0] };
+export function formatDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
 }
 
 /**
- * Decode API date format to Date object
+ * Format a Date object to API request datetime string
+ * @param date - JavaScript Date object
+ * @returns "YYYY-MM-DD HH:MM:SS" formatted string for API requests
+ *
+ * @example
+ * formatDateTime(new Date(2025, 2, 15, 10, 30, 45)) // => "2025-03-15 10:30:45"
  */
-export function decodeDate(encoded: DateEncodedType): Date {
-  return new Date(encoded.$__d__);
-}
+export function formatDateTime(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  const seconds = String(date.getSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+// ============================================================
+// PARSING FUNCTIONS (String → Date object)
+// Use these when you have a date string and need a Date object
+// ============================================================
+
+/**
+ * Parse date string to Date object
+ * @param dateStr - "YYYY-MM-DD" formatted string
+ * @returns JavaScript Date object
+ *
+ * @example
+ * parseDate("2025-03-15") // => Date object for March 15, 2025
+ */
+export function parseDate(dateStr: string): Date {
+  const [year, month, day] = dateStr.split("-").map(Number);
+  return new Date(year, month - 1, day);
+}
+
+/**
+ * Parse datetime string to Date object
+ * @param dateTimeStr - "YYYY-MM-DD HH:MM:SS" formatted string
+ * @returns JavaScript Date object
+ *
+ * @example
+ * parseDateTime("2025-03-15 10:30:45") // => Date object
+ */
+export function parseDateTime(dateTimeStr: string): Date {
+  const [datePart, timePart] = dateTimeStr.split(" ");
+  const [year, month, day] = datePart.split("-").map(Number);
+  const [hours, minutes, seconds] = timePart.split(":").map(Number);
+  return new Date(year, month - 1, day, hours, minutes, seconds);
+}

package/sdk/api/index.ts

@@ -10,10 +10,13 @@ export type { ResourceClient } from "./client";
 
 // DateTime utilities
 export {
-  encodeDatetime,
-  decodeDatetime,
-  encodeDate,
+  DatetimeFormat,
   decodeDate,
+  decodeDateTime,
+  formatDate,
+  formatDateTime,
+  parseDate,
+  parseDateTime,
 } from "./datetime";
 
 // Metadata API client
@@ -40,9 +43,6 @@ export type {
   CreateUpdateResponseType,
   DeleteResponseType,
   CountResponseType,
-  // DateTime types
-  DateTimeEncodedType,
-  DateEncodedType,
   // Metric types
   MetricTypeType,
   MetricFieldType,
@@ -58,3 +58,9 @@ export type {
   // Fields types
   FieldsResponseType,
 } from "../types/common";
+
+// Re-export date types from base-fields
+export type {
+  DateEncodedType,
+  DateTimeEncodedType,
+} from "../types/base-fields";

package/sdk/api.ts

@@ -14,10 +14,13 @@ export {
 
 // DateTime utilities
 export {
-  encodeDatetime,
-  decodeDatetime,
-  encodeDate,
+  formatDateTime,
+  decodeDateTime,
+  formatDate,
   decodeDate,
+  parseDate,
+  parseDateTime,
+  DatetimeFormat,
 } from './api/datetime';
 
 // Metadata API client

package/sdk/api.types.ts

@@ -9,6 +9,9 @@ export type { ResourceClient } from './api/client';
 // Metadata types
 export type { BackendSchema, MetadataItem, FieldMetadata } from './api/metadata';
 
+// DateTime types from base-fields
+export type { DateTimeEncodedType, DateEncodedType } from './types/base-fields';
+
 // Common API types
 export type {
   // Sort types
@@ -32,10 +35,6 @@ export type {
   DeleteResponseType,
   CountResponseType,
 
-  // DateTime types
-  DateTimeEncodedType,
-  DateEncodedType,
-
   // Metric types
   MetricTypeType,
   MetricFieldType,

package/sdk/auth/AuthProvider.tsx

@@ -102,7 +102,8 @@ export function AuthProvider({
 
   const status: AuthStatusType = useMemo(() => {
     if (isLoading || isFetching) return "loading";
-    if (sessionData?.userDetails) return "authenticated";
+    if (Object.keys(sessionData?.userDetails || {}).length > 0)
+      return "authenticated";
     return "unauthenticated";
   }, [isLoading, isFetching, sessionData]);
 
@@ -139,11 +140,7 @@ export function AuthProvider({
   }, [queryError]);
 
   useEffect(() => {
-    if (
-      status === "unauthenticated" &&
-      authConfig.autoRedirect &&
-      !isLoading
-    ) {
+    if (status === "unauthenticated" && authConfig.autoRedirect && !isLoading) {
       initiateLogin();
     }
   }, [status, isLoading, authConfig.autoRedirect]);
@@ -156,7 +153,7 @@ export function AuthProvider({
     (provider?: AuthProviderNameType, options?: LoginOptionsType) => {
       initiateLogin(provider, options);
     },
-    []
+    [],
   );
 
   const logout = useCallback(
@@ -164,36 +161,37 @@ export function AuthProvider({
       queryClient.removeQueries({ queryKey: SESSION_QUERY_KEY });
       await performLogout(options);
     },
-    [queryClient]
+    [queryClient],
   );
 
-  const refreshSession = useCallback(async (): Promise<SessionResponseType | null> => {
-    // Prevent concurrent refreshes - return existing data if already fetching
-    if (isFetching) {
-      return sessionData || null;
-    }
+  const refreshSession =
+    useCallback(async (): Promise<SessionResponseType | null> => {
+      // Prevent concurrent refreshes - return existing data if already fetching
+      if (isFetching) {
+        return sessionData || null;
+      }
 
-    try {
-      const result = await refetch();
-      return result.data || null;
-    } catch (err) {
-      setError(err as Error);
-      return null;
-    }
-  }, [refetch, isFetching, sessionData]);
+      try {
+        const result = await refetch();
+        return result.data || null;
+      } catch (err) {
+        setError(err as Error);
+        return null;
+      }
+    }, [refetch, isFetching, sessionData]);
 
   const hasRole = useCallback(
     (role: string): boolean => {
       return user?.Role === role;
     },
-    [user]
+    [user],
   );
 
   const hasAnyRole = useCallback(
     (roles: string[]): boolean => {
       return roles.includes(user?.Role || "");
     },
-    [user]
+    [user],
   );
 
   const clearError = useCallback(() => {
@@ -240,7 +238,7 @@ export function AuthProvider({
       error,
       clearError,
       _forceCheck,
-    ]
+    ],
   );
 
   // ============================================================

package/sdk/base-types.ts

@@ -25,6 +25,8 @@ export type {
   CurrencyValueType,
   JSONFieldType,
   ReferenceFieldType,
+  ExtractReferenceType,
+  ExtractFetchFieldType,
 
   // JSON types
   JSONValueType,

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]
   );