@ram_28/kf-ai-sdk 1.0.20 → 1.0.21

package/sdk/base-types.ts

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

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

@@ -135,7 +135,62 @@ export async function submitFormData<T = any>(
 // ============================================================
 
 /**
- * Fetch reference field data
+ * Fetch reference field data using the fetchField API
+ * This correctly uses instance context for filter evaluation
+ */
+export async function fetchReferenceFieldData(
+  boId: string,
+  instanceId: string,
+  fieldId: string
+): Promise<Array<{ Value: string; Label: string }>> {
+  try {
+    // Calls GET /{boId}/{instanceId}/field/{fieldId}/fetch
+    return await api(boId).fetchField(instanceId, fieldId);
+  } catch (error) {
+    console.error(`Reference data fetch error for ${fieldId}:`, error);
+    return [];
+  }
+}
+
+/**
+ * Fetch all reference data for a form
+ * @param boId - The Business Object ID
+ * @param instanceId - The instance ID (draftId for create, recordId for update)
+ * @param referenceFieldIds - Array of reference field IDs to fetch
+ */
+export async function fetchAllReferenceFieldData(
+  boId: string,
+  instanceId: string,
+  referenceFieldIds: string[]
+): Promise<Record<string, Array<{ Value: string; Label: string }>>> {
+  const referenceData: Record<string, Array<{ Value: string; Label: string }>> = {};
+
+  // Fetch all reference data in parallel
+  const fetchPromises = referenceFieldIds.map(async (fieldId) => {
+    try {
+      const data = await fetchReferenceFieldData(boId, instanceId, fieldId);
+      return [fieldId, data] as const;
+    } catch (error) {
+      console.warn(`Failed to fetch reference data for ${fieldId}:`, error);
+      return [fieldId, []] as const;
+    }
+  });
+
+  const results = await Promise.allSettled(fetchPromises);
+
+  results.forEach((result) => {
+    if (result.status === "fulfilled") {
+      const [fieldId, data] = result.value;
+      referenceData[fieldId] = [...data];
+    }
+  });
+
+  return referenceData;
+}
+
+/**
+ * @deprecated Use fetchReferenceFieldData instead
+ * Legacy function that fetches reference data using list() API
  */
 export async function fetchReferenceData(
   businessObject: string,
@@ -171,7 +226,8 @@ export async function fetchReferenceData(
 }
 
 /**
- * Fetch all reference data for a schema
+ * @deprecated Use fetchAllReferenceFieldData instead
+ * Legacy function that fetches all reference data using list() API
  */
 export async function fetchAllReferenceData(
   referenceFields: Record<string, any>
@@ -239,18 +295,26 @@ export function validateFormData<T>(
  * Clean form data before submission
  * - For create: returns all non-computed, non-undefined fields
  * - For update: returns only fields that changed from originalData
+ * - Transforms Reference fields to JSON format expected by backend
+ *
+ * @param data - Form data to clean
+ * @param computedFields - Array of computed field names to exclude
+ * @param operation - "create" or "update"
+ * @param originalData - Original data for comparison (update only)
+ * @param fieldTypes - Map of field names to their BDO types (e.g., { "SupplierInfo": "Reference" })
  */
 export function cleanFormData<T>(
   data: Partial<T>,
   computedFields: string[],
   operation: FormOperationType = "create",
-  originalData?: Partial<T>
+  originalData?: Partial<T>,
+  fieldTypes?: Record<string, string>
 ): Partial<T> {
   const cleanedData: Partial<T> = {};
 
   Object.keys(data).forEach((key) => {
     const fieldKey = key as keyof T;
-    const value = data[fieldKey];
+    let value = data[fieldKey];
 
     // Skip computed fields
     if (computedFields.includes(key)) {
@@ -262,6 +326,12 @@ export function cleanFormData<T>(
       return;
     }
 
+    // Transform Reference fields to JSON format expected by backend
+    // Backend expects: {"_id": "...", "_name": "..."} or a JSON string that parses to this
+    if (fieldTypes?.[key] === "Reference" && value !== null) {
+      value = transformReferenceValue(value) as any;
+    }
+
     // For create: include all non-computed, non-undefined fields
     if (operation === "create") {
       cleanedData[fieldKey] = value;
@@ -289,6 +359,50 @@ export function cleanFormData<T>(
   return cleanedData;
 }
 
+/**
+ * Transform a Reference/Lookup field value to the format expected by backend
+ *
+ * Backend expects Reference fields as either:
+ * - A dict with at minimum {"_id": "..."}
+ * - For Lookup fields, the full referenced record can be passed
+ * - A JSON string that parses to this format
+ *
+ * This function handles various input formats:
+ * - Plain string ID: "SUPP-001" → {"_id": "SUPP-001"}
+ * - Object with _id: preserves ALL properties (for lookup fields with full data)
+ * - JSON string: '{"_id": "..."}' → parsed and validated
+ */
+export function transformReferenceValue(value: any): Record<string, any> | null {
+  if (value === null || value === undefined || value === "") {
+    return null;
+  }
+
+  // Already an object with _id - preserve ALL properties (for lookup fields with full data)
+  if (typeof value === "object" && value._id) {
+    return { ...value };
+  }
+
+  // String value - could be plain ID or JSON string
+  if (typeof value === "string") {
+    // Try to parse as JSON first
+    try {
+      const parsed = JSON.parse(value);
+      if (typeof parsed === "object" && parsed._id) {
+        return { ...parsed };
+      }
+      // Parsed but not a valid reference object - treat original as ID
+    } catch {
+      // Not valid JSON - treat as plain ID string
+    }
+
+    // Plain string ID
+    return { _id: value };
+  }
+
+  // Unknown format - return as-is (let backend handle/reject it)
+  return value;
+}
+
 // ============================================================
 // ERROR HANDLING
 // ============================================================

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

@@ -16,14 +16,14 @@ import type {
   FormFieldConfigType,
 } from "./types";
 
-import { processSchema, extractReferenceFields } from "./schemaParser.utils";
+import { processSchema } from "./schemaParser.utils";
 
 import {
   fetchFormSchemaWithCache,
   fetchRecord,
   submitFormData,
-  fetchAllReferenceData,
   cleanFormData,
+  transformReferenceValue,
 } from "./apiClient";
 
 import { api } from "../../../api";
@@ -40,7 +40,7 @@ import {
 // ============================================================
 
 export function useForm<T extends Record<string, any> = Record<string, any>>(
-  options: UseFormOptionsType<T>
+  options: UseFormOptionsType<T>,
 ): UseFormReturnType<T> {
   const {
     source,
@@ -63,9 +63,13 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
   // STATE MANAGEMENT
   // ============================================================
 
-  const [schemaConfig, setSchemaConfig] =
-    useState<FormSchemaConfigType | null>(null);
-  const [referenceData, setReferenceData] = useState<Record<string, any[]>>({});
+  const [schemaConfig, setSchemaConfig] = useState<FormSchemaConfigType | null>(
+    null,
+  );
+  // Reference data for cross-field validation - populated lazily by UI components if needed
+  const [referenceData, _setReferenceData] = useState<Record<string, any[]>>(
+    {},
+  );
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [lastFormValues] = useState<Partial<T>>({});
 
@@ -176,22 +180,11 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         const processed = processSchema(
           schema as any,
           {}, // Pass empty object - validation functions get live values from react-hook-form
-          userRole
+          userRole,
         );
         setSchemaConfig(processed);
-
-        // Fetch reference data for reference fields
-        const refFields = extractReferenceFields(processed);
-        if (Object.keys(refFields).length > 0) {
-          fetchAllReferenceData(refFields)
-            .then(setReferenceData)
-            .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);
-            });
-        }
+        // Reference data is fetched lazily by UI components when dropdowns are opened
+        // using the fetchField API with proper instance context (draftId/recordId)
       } catch (error) {
         console.error("Schema processing failed:", error);
         onSchemaErrorRef.current?.(toError(error));
@@ -219,7 +212,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       !schemaConfig ||
       !enabled ||
       draftId ||
-      draftCreationStartedRef.current  // Prevent duplicate calls in React strict mode
+      draftCreationStartedRef.current // Prevent duplicate calls in React strict mode
     ) {
       return;
     }
@@ -321,7 +314,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       const field = schemaConfig.fields[fieldName];
       if (field._bdoField.Formula) {
         const fieldDeps = getFieldDependencies(
-          field._bdoField.Formula.ExpressionTree
+          field._bdoField.Formula.ExpressionTree,
         );
         fieldDeps.forEach((dep) => {
           // Only add non-computed fields as dependencies
@@ -357,10 +350,11 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       // 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 && operation !== "update")
-        ? true // Interactive mode (create only): always trigger
-        : (computedFieldDependencies.length > 0 &&
-              computedFieldDependencies.includes(fieldName as Path<T>));
+      const shouldTrigger =
+        isInteractiveMode && operation !== "update"
+          ? true // Interactive mode (create only): always trigger
+          : computedFieldDependencies.length > 0 &&
+            computedFieldDependencies.includes(fieldName as Path<T>);
 
       if (!shouldTrigger) {
         return;
@@ -422,7 +416,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
 
             // Get computed field names to exclude from payload
             const computedFieldNames = new Set(
-              schemaConfig.computedFields || []
+              schemaConfig.computedFields || [],
             );
 
             // Find fields that changed from baseline (excluding computed fields)
@@ -430,7 +424,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
               // Skip _id and computed fields
               if (key === "_id" || computedFieldNames.has(key)) return;
 
-              const currentValue = (currentValues as any)[key];
+              let currentValue = (currentValues as any)[key];
               const baselineValue = (baseline as any)[key];
 
               // Include if value has changed (using JSON.stringify for deep comparison)
@@ -443,6 +437,11 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 currentValue !== undefined;
 
               if (hasChanged && isNonEmpty) {
+                // Transform Reference fields to format expected by backend
+                const fieldConfig = schemaConfig.fields[key];
+                if (fieldConfig?._bdoField?.Type === "Reference") {
+                  currentValue = transformReferenceValue(currentValue);
+                }
                 (changedFields as any)[key] = currentValue;
               }
             });
@@ -470,7 +469,10 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
             let computedFieldsResponse;
             if (operation === "update" && recordId) {
               // Update mode: use draftPatch (both interactive and non-interactive)
-              computedFieldsResponse = await client.draftPatch(recordId, payload);
+              computedFieldsResponse = await client.draftPatch(
+                recordId,
+                payload,
+              );
             } else if (isInteractiveMode && draftId) {
               // Interactive create: use draftInteraction with _id
               computedFieldsResponse = await client.draftInteraction(payload);
@@ -493,7 +495,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                       shouldValidate: false,
                     });
                   }
-                }
+                },
               );
 
               // Update baseline with computed fields from successful API response
@@ -502,7 +504,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                   if (computedFieldNames.has(fieldName)) {
                     (lastSyncedValuesRef.current as any)[fieldName] = value;
                   }
-                }
+                },
               );
             }
           } catch (error) {
@@ -531,7 +533,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       computedFieldDependencies,
       isInteractiveMode,
       draftId,
-    ]
+    ],
   );
 
   // ============================================================
@@ -553,18 +555,16 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
 
     // Cross-field validation
     // Transform ValidationRule[] to the format expected by validateCrossField
-    const transformedRules = schemaConfig.crossFieldValidation.map(
-      (rule) => ({
-        Id: rule.Id,
-        Condition: { ExpressionTree: rule.ExpressionTree },
-        Message: rule.Message || `Validation failed for ${rule.Name}`,
-      })
-    );
+    const transformedRules = schemaConfig.crossFieldValidation.map((rule) => ({
+      Id: rule.Id,
+      Condition: { ExpressionTree: rule.ExpressionTree },
+      Message: rule.Message || `Validation failed for ${rule.Name}`,
+    }));
 
     const crossFieldErrors = validateCrossField(
       transformedRules,
       values as any,
-      referenceData
+      referenceData,
     );
 
     if (crossFieldErrors.length > 0) {
@@ -603,11 +603,14 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
    */
   const handleSubmit = useCallback(
     (
-      onSuccess?: (data: T, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+      onSuccess?: (
+        data: T,
+        e?: React.BaseSyntheticEvent,
+      ) => void | Promise<void>,
       onError?: (
         error: import("react-hook-form").FieldErrors<T> | Error,
-        e?: React.BaseSyntheticEvent
-      ) => void | Promise<void>
+        e?: React.BaseSyntheticEvent,
+      ) => void | Promise<void>,
     ) => {
       return rhfForm.handleSubmit(
         // RHF onValid handler - validation passed, now do cross-field + API
@@ -627,13 +630,13 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 Id: rule.Id,
                 Condition: { ExpressionTree: rule.ExpressionTree },
                 Message: rule.Message || `Validation failed for ${rule.Name}`,
-              })
+              }),
             );
 
             const crossFieldErrors = validateCrossField(
               transformedRules,
               data as any,
-              referenceData
+              referenceData,
             );
 
             if (crossFieldErrors.length > 0) {
@@ -649,12 +652,21 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
               return;
             }
 
+            // Extract field types from schema for Reference field transformation
+            const fieldTypes: Record<string, string> = {};
+            Object.entries(schemaConfig.fields).forEach(
+              ([fieldName, field]) => {
+                fieldTypes[fieldName] = field._bdoField.Type;
+              },
+            );
+
             // Clean data for submission
             const cleanedData = cleanFormData(
               data as any,
               schemaConfig.computedFields,
               operation,
-              recordData as Partial<T> | undefined
+              recordData as Partial<T> | undefined,
+              fieldTypes,
             );
 
             let result;
@@ -667,7 +679,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 // Interactive create: must have draftId
                 if (!draftId) {
                   throw new Error(
-                    "Interactive create mode requires a draft ID. Draft creation may have failed."
+                    "Interactive create mode requires a draft ID. Draft creation may have failed.",
                   );
                 }
                 // POST /{bdo_id}/draft with _id in payload
@@ -687,7 +699,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 source,
                 operation,
                 cleanedData,
-                recordId
+                recordId,
               );
 
               if (!result.success) {
@@ -716,7 +728,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         // RHF onInvalid handler - validation failed
         (errors, event) => {
           onError?.(errors, event);
-        }
+        },
       );
     },
     [
@@ -729,7 +741,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       recordData,
       isInteractiveMode,
       draftId,
-    ]
+    ],
   );
 
   // ============================================================
@@ -740,7 +752,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     <K extends keyof T>(fieldName: K): FormFieldConfigType | null => {
       return schemaConfig?.fields[fieldName as string] || null;
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const getFields = useCallback((): Record<keyof T, FormFieldConfigType> => {
@@ -758,7 +770,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     <K extends keyof T>(fieldName: K): boolean => {
       return !!schemaConfig?.fields[fieldName as string];
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const isFieldRequired = useCallback(
@@ -767,7 +779,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         schemaConfig?.requiredFields.includes(fieldName as string) || false
       );
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const isFieldComputed = useCallback(
@@ -776,7 +788,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         schemaConfig?.computedFields.includes(fieldName as string) || false
       );
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   // ============================================================
@@ -806,12 +818,12 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
 
   const computedFields = useMemo<Array<keyof T>>(
     () => (schemaConfig?.computedFields as Array<keyof T>) || [],
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const requiredFields = useMemo<Array<keyof T>>(
     () => (schemaConfig?.requiredFields as Array<keyof T>) || [],
-    [schemaConfig]
+    [schemaConfig],
   );
 
   // ============================================================
@@ -864,7 +876,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                   value,
                   [rule],
                   currentValues,
-                  lastFormValues as T | undefined
+                  lastFormValues as T | undefined,
                 );
                 if (!result.isValid) {
                   return result.message || rule.Message || "Invalid value";
@@ -936,7 +948,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         onBlur: enhancedOnBlur,
       });
     },
-    [rhfForm, validationRules, triggerComputationAfterValidation, mode]
+    [rhfForm, validationRules, triggerComputationAfterValidation, mode],
   );
 
   return {

package/sdk/index.ts

@@ -92,6 +92,9 @@ export type {
   LookupFieldType,
   ArrayFieldType,
   JSONFieldType,
+  ReferenceFieldType,
+  ExtractReferenceType,
+  ExtractFetchFieldType,
 } from './types/base-fields';
 
 // ============================================================

package/sdk/types/base-fields.ts

@@ -67,27 +67,47 @@ export type LongFieldType = number;
  */
 export type BooleanFieldType = boolean;
 
+/**
+ * Encoded date format from API response
+ * API returns: { "$__d__": "YYYY-MM-DD" }
+ */
+export interface DateEncodedType {
+  $__d__: string;
+}
+
+/**
+ * Encoded datetime format from API response
+ * API returns: { "$__dt__": unix_timestamp_seconds }
+ */
+export interface DateTimeEncodedType {
+  $__dt__: number;
+}
+
 /**
  * Date field (date only, no time)
- * Resolves to: Date
+ * API Response Format: { "$__d__": "YYYY-MM-DD" }
+ * API Request Format: "YYYY-MM-DD"
  * Storage: DATE in database
  * Use this for birth dates, due dates, calendar events
  *
  * @example
- * DateFieldType // => Date (date only)
+ * // Response from API:
+ * { "$__d__": "2025-03-15" }
  */
-export type DateFieldType = Date;
+export type DateFieldType = DateEncodedType;
 
 /**
  * DateTime field (date and time)
- * Resolves to: Date
+ * API Response Format: { "$__dt__": unix_timestamp_seconds }
+ * API Request Format: "YYYY-MM-DD HH:MM:SS"
  * Storage: DATETIME/TIMESTAMP in database
  * Use this for created_at, updated_at, event timestamps
  *
  * @example
- * DateTimeFieldType // => Date (with time)
+ * // Response from API:
+ * { "$__dt__": 1769110463 }
  */
-export type DateTimeFieldType = Date;
+export type DateTimeFieldType = DateTimeEncodedType;
 
 // ============================================================
 // COMPLEX FIELD TYPES
@@ -124,7 +144,47 @@ export type CurrencyValueType =
  */
 export type JSONFieldType<T = JSONValueType> = T;
 
-export type ReferenceFieldType = string;
+/**
+ * Reference/Lookup field for relationships to other Business Data Objects
+ *
+ * @template TReferencedType - The full type of the referenced BDO record
+ *
+ * Runtime behavior:
+ * - The field stores the full referenced record (e.g., full supplier object)
+ * - API returns the complete record from the referenced BDO
+ * - On save, the full object is sent in the payload
+ *
+ * @example
+ * SupplierInfo: ReferenceFieldType<BaseSupplierType>;
+ * // At runtime: { _id: "...", SupplierId: "...", SupplierName: "...", ... }
+ */
+export type ReferenceFieldType<TReferencedType = unknown> = TReferencedType;
+
+/**
+ * Extract the referenced type from a ReferenceFieldType
+ * Note: Since ReferenceFieldType<T> = T, this just returns T if it has _id
+ */
+export type ExtractReferenceType<T> = T extends { _id: string } ? T : never;
+
+/**
+ * Extract the type that fetchField should return for a given field type
+ * - For Reference fields (objects with _id) → the full referenced record type
+ * - For other field types → { Value: string; Label: string } (static dropdown)
+ *
+ * Detection: All BDO types have _id: string, so we check for that property
+ * to distinguish reference fields from primitive fields like StringFieldType.
+ *
+ * @example
+ * type SupplierOptions = ExtractFetchFieldType<BaseProductType["SupplierInfo"]>;
+ * // Result: BaseSupplierType (has _id)
+ *
+ * type CategoryOptions = ExtractFetchFieldType<BaseProductType["Category"]>;
+ * // Result: { Value: string; Label: string } (string has no _id)
+ */
+export type ExtractFetchFieldType<T> =
+  T extends { _id: string }
+    ? T
+    : { Value: string; Label: string };
 
 /**
  * Valid JSON value types
@@ -156,17 +216,11 @@ export interface JSONArrayType extends Array<JSONValueType> {}
 export type SelectFieldType<T extends string> = T;
 
 /**
- * Lookup field for references to other records
- * @template T - Type of the referenced record ID (defaults to string)
- * Resolves to: T
- * Storage: VARCHAR in database (stores the ID)
- * Use this for foreign keys, relationships, references
- *
- * @example
- * LookupFieldType // => string (referenced record ID)
- * LookupFieldType<IdFieldType> // => string (typed as IdFieldType)
+ * Alias for ReferenceFieldType (Lookup = Reference in the backend)
+ * @template TReferencedType - The full type of the referenced BDO record
+ * @deprecated Use ReferenceFieldType instead
  */
-export type LookupFieldType<T extends string = string> = T;
+export type LookupFieldType<TReferencedType = unknown> = ReferenceFieldType<TReferencedType>;
 
 // ============================================================
 // CONTAINER AND UTILITY TYPES

package/sdk/types/common.ts

@@ -71,19 +71,8 @@ export interface ConditionGroupType<T = any> {
  */
 export type FilterType<T = any> = ConditionGroupType<T>;
 
-/**
- * DateTime encoding format used by the API
- */
-export interface DateTimeEncodedType {
-  $__dt__: number;
-}
-
-/**
- * Date encoding format used by the API
- */
-export interface DateEncodedType {
-  $__d__: string;
-}
+// Note: DateTimeEncodedType and DateEncodedType are now defined in base-fields.ts
+// They are re-exported from api/index.ts for convenience
 
 /**
  * Standard paginated list response