@ram_28/kf-ai-sdk 2.0.14 → 2.0.16

package/sdk/components/hooks/useTable/useTable.ts

@@ -1,10 +1,14 @@
-import { useState, useMemo, useCallback, useRef, useEffect } from "react";
-import { useQuery } from "@tanstack/react-query";
-import { api } from "../../../api";
-import type { ListResponseType, ListOptionsType, FilterType, ConditionType } from "../../../types/common";
-import { toError } from "../../../utils/error-handling";
-import { useFilter } from "../useFilter";
-import type { UseTableOptionsType, UseTableReturnType } from "./types";
+import { useState, useMemo, useCallback, useRef, useEffect } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import type {
+  ListResponseType,
+  ListOptionsType,
+  FilterType,
+  ConditionType,
+} from '../../../types/common';
+import { toError } from '../../../utils/error-handling';
+import { useFilter } from '../useFilter';
+import type { UseTableOptionsType, UseTableReturnType } from './types';
 
 // ============================================================
 // INTERNAL STATE TYPES
@@ -18,7 +22,7 @@ interface SearchState<T> {
 
 interface SortingState<T> {
   field: keyof T | null;
-  direction: "ASC" | "DESC" | null;
+  direction: 'ASC' | 'DESC' | null;
 }
 
 interface PaginationState {
@@ -31,15 +35,15 @@ interface PaginationState {
 // ============================================================
 
 export function useTable<T = any>(
-  options: UseTableOptionsType<T>
+  options: UseTableOptionsType<T>,
 ): UseTableReturnType<T> {
   // ============================================================
   // STATE MANAGEMENT
   // ============================================================
 
   const [search, setSearch] = useState<SearchState<T>>({
-    query: "",
-    debouncedQuery: "",
+    query: '',
+    debouncedQuery: '',
     field: null,
   });
 
@@ -53,8 +57,8 @@ export function useTable<T = any>(
     if (sortConfig && sortConfig.length > 0) {
       const firstSort = sortConfig[0];
       const field = Object.keys(firstSort)[0] as keyof T;
-      const raw = firstSort[field as string]?.toUpperCase() as "ASC" | "DESC";
-      const direction = raw === "ASC" || raw === "DESC" ? raw : "ASC";
+      const raw = firstSort[field as string]?.toUpperCase() as 'ASC' | 'DESC';
+      const direction = raw === 'ASC' || raw === 'DESC' ? raw : 'ASC';
       return { field, direction };
     }
     return { field: null, direction: null };
@@ -73,7 +77,7 @@ export function useTable<T = any>(
 
   const filter = useFilter<T>({
     conditions: options.initialState?.filter?.conditions,
-    operator: options.initialState?.filter?.operator || "And",
+    operator: options.initialState?.filter?.operator || 'And',
   });
 
   // ============================================================
@@ -99,14 +103,14 @@ export function useTable<T = any>(
     if (search.debouncedQuery && search.field) {
       const searchCondition: ConditionType = {
         LHSField: search.field,
-        Operator: "Contains",
+        Operator: 'Contains',
         RHSValue: search.debouncedQuery,
-        RHSType: "Constant",
+        RHSType: 'Constant',
       };
 
       if (combinedFilter) {
         // Merge with existing filter
-        if (combinedFilter.Operator === "And") {
+        if (combinedFilter.Operator === 'And') {
           combinedFilter = {
             ...combinedFilter,
             Condition: [...(combinedFilter.Condition || []), searchCondition],
@@ -114,14 +118,14 @@ export function useTable<T = any>(
         } else {
           // Wrap existing filter in And with search condition
           combinedFilter = {
-            Operator: "And",
+            Operator: 'And',
             Condition: [combinedFilter, searchCondition],
           };
         }
       } else {
         // Create new filter with just the search condition
         combinedFilter = {
-          Operator: "And",
+          Operator: 'And',
           Condition: [searchCondition],
         };
       }
@@ -166,10 +170,10 @@ export function useTable<T = any>(
     error,
     refetch: queryRefetch,
   } = useQuery({
-    queryKey: ["table", options.source, apiOptions],
+    queryKey: [...options.queryKey, apiOptions],
     queryFn: async (): Promise<ListResponseType<T>> => {
       try {
-        const response = await api<T>(options.source).list(apiOptions);
+        const response = await options.listFn(apiOptions);
         if (options.onSuccess) {
           options.onSuccess(response.Data);
         }
@@ -193,10 +197,10 @@ export function useTable<T = any>(
     error: countError,
     refetch: countRefetch,
   } = useQuery({
-    queryKey: ["table-count", options.source, countApiOptions],
+    queryKey: [...options.queryKey, 'count', countApiOptions],
     queryFn: async () => {
       try {
-        return await api<T>(options.source).count(countApiOptions);
+        return await options.countFn(countApiOptions);
       } catch (err) {
         if (options.onError) {
           options.onError(toError(err));
@@ -226,13 +230,13 @@ export function useTable<T = any>(
   const toggleSort = useCallback((field: keyof T) => {
     setSorting((prev) => {
       if (prev.field === field) {
-        if (prev.direction === "ASC") {
-          return { field, direction: "DESC" };
-        } else if (prev.direction === "DESC") {
+        if (prev.direction === 'ASC') {
+          return { field, direction: 'DESC' };
+        } else if (prev.direction === 'DESC') {
           return { field: null, direction: null };
         }
       }
-      return { field, direction: "ASC" };
+      return { field, direction: 'ASC' };
     });
   }, []);
 
@@ -241,44 +245,47 @@ export function useTable<T = any>(
   }, []);
 
   const setSort = useCallback(
-    (field: keyof T | null, direction: "ASC" | "DESC" | null) => {
+    (field: keyof T | null, direction: 'ASC' | 'DESC' | null) => {
       setSorting({ field, direction });
     },
-    []
+    [],
   );
 
   // ============================================================
   // SEARCH OPERATIONS
   // ============================================================
 
-  const setSearchFieldAndQuery = useCallback((field: keyof T, query: string) => {
-    // Validate search query length to prevent DoS
-    if (query.length > 255) {
-      console.warn("Search query exceeds maximum length of 255 characters");
-      return;
-    }
+  const setSearchFieldAndQuery = useCallback(
+    (field: keyof T, query: string) => {
+      // Validate search query length to prevent DoS
+      if (query.length > 255) {
+        console.warn('Search query exceeds maximum length of 255 characters');
+        return;
+      }
 
-    // Update immediate value for UI
-    setSearch((prev) => ({ ...prev, query, field }));
+      // Update immediate value for UI
+      setSearch((prev) => ({ ...prev, query, field }));
 
-    // Clear existing debounce timeout
-    if (searchDebounceRef.current) {
-      clearTimeout(searchDebounceRef.current);
-    }
+      // Clear existing debounce timeout
+      if (searchDebounceRef.current) {
+        clearTimeout(searchDebounceRef.current);
+      }
 
-    // Debounce the actual API query update
-    searchDebounceRef.current = setTimeout(() => {
-      setSearch((prev) => ({ ...prev, debouncedQuery: query }));
-      setPagination((prev) => ({ ...prev, pageNo: 1 }));
-    }, SEARCH_DEBOUNCE_MS);
-  }, []);
+      // Debounce the actual API query update
+      searchDebounceRef.current = setTimeout(() => {
+        setSearch((prev) => ({ ...prev, debouncedQuery: query }));
+        setPagination((prev) => ({ ...prev, pageNo: 1 }));
+      }, SEARCH_DEBOUNCE_MS);
+    },
+    [],
+  );
 
   const clearSearch = useCallback(() => {
     // Clear debounce timeout
     if (searchDebounceRef.current) {
       clearTimeout(searchDebounceRef.current);
     }
-    setSearch({ query: "", debouncedQuery: "", field: null });
+    setSearch({ query: '', debouncedQuery: '', field: null });
     setPagination((prev) => ({ ...prev, pageNo: 1 }));
   }, []);
 
@@ -315,7 +322,7 @@ export function useTable<T = any>(
       const pageNo = Math.max(1, Math.min(page, totalPages));
       setPagination((prev) => ({ ...prev, pageNo }));
     },
-    [totalPages]
+    [totalPages],
   );
 
   const setPageSize = useCallback((size: number) => {

package/sdk/form.ts

@@ -1,7 +1,7 @@
 // ============================================================
 // Form Entry Point
 // ============================================================
-// Exports useForm hook for forms with automatic validation and API operations.
+// Exports useBDOForm hook for forms with automatic validation and API operations.
 
-export { useForm } from "./components/hooks/useForm";
+export { useBDOForm } from "./components/hooks/useBDOForm";
 export { ValidationMode, FormOperation, InteractionMode } from "./types/constants";

package/sdk/form.types.ts

@@ -1,11 +1,11 @@
 // ============================================================
 // Form Types Entry Point
 // ============================================================
-// Type-only exports for useForm hook.
+// Type-only exports for useBDOForm hook.
 
 export type {
-  UseFormOptionsType,
-  UseFormReturnType,
+  UseBDOFormOptionsType,
+  UseBDOFormReturnType,
   FormItemType,
   EditableFormFieldAccessorType,
   ReadonlyFormFieldAccessorType,
@@ -14,4 +14,4 @@ export type {
   ExtractEditableType,
   ExtractReadonlyType,
   AllFieldsType,
-} from "./components/hooks/useForm";
+} from "./components/hooks/useBDOForm";

package/sdk/table.ts

@@ -3,9 +3,12 @@
 // @ram_28/kf-ai-sdk/table
 // ============================================================
 
-// Main hook
+// Base hook
 export { useTable } from './components/hooks/useTable/useTable';
 
+// BDO wrapper hook
+export { useBDOTable } from './components/hooks/useBDOTable/useBDOTable';
+
 // Constants
 export {
   SortDirection,

package/sdk/table.types.ts

@@ -4,13 +4,16 @@
 // ============================================================
 
 export type {
-  // Core hook types
+  // Base hook types
   UseTableOptionsType,
   UseTableReturnType,
 
-  // Column definition
-  ColumnDefinitionType,
-
   // State types
   PaginationStateType,
 } from './components/hooks/useTable/types';
+
+export type {
+  // BDO wrapper types
+  UseBDOTableOptionsType,
+  UseBDOTableReturnType,
+} from './components/hooks/useBDOTable/types';

package/sdk/types/base-fields.ts

@@ -93,16 +93,16 @@ type Second = number;
 
 /**
  * DateTime field (date and time)
- * API Request Format: "YYYY-MM-DD HH:MM:SS"
+ * API Request Format: "YYYY-MM-DDTHH:MM:SSZ"
+ * API Response Format: "YYYY-MM-DDTHH:MM:SSZ" (always UTC)
  * Use this for created_at, updated_at, event timestamps
  *
  * @example
- * // Response from API:
- * "2026-01-23T01:21:33"
+ * "2026-01-23T01:21:33Z"
  */
 
 export type DateTimeFieldType =
-  `${Year}-${Month}-${Day}T${Hour}:${Minute}:${Second}`;
+  `${Year}-${Month}-${Day}T${Hour}:${Minute}:${Second}Z`;
 
 // ============================================================
 // COMPLEX FIELD TYPES

package/sdk/types/constants.ts

@@ -187,7 +187,7 @@ export const QueryType = {
  * @example
  * import { FormOperation } from "@ram_28/kf-ai-sdk/form";
  *
- * const { handleSubmit } = useForm({
+ * const { handleSubmit } = useBDOForm({
  *   source: "products",
  *   operation: FormOperation.Create,
  * });
@@ -206,7 +206,7 @@ export const FormOperation = {
  * @example
  * import { InteractionMode } from "@ram_28/kf-ai-sdk/form";
  *
- * const { handleSubmit } = useForm({
+ * const { handleSubmit } = useBDOForm({
  *   source: "products",
  *   operation: "create",
  *   interactionMode: InteractionMode.Interactive,
@@ -225,7 +225,7 @@ export const InteractionMode = {
  * @example
  * import { ValidationMode } from "@ram_28/kf-ai-sdk/form";
  *
- * const { handleSubmit } = useForm({
+ * const { handleSubmit } = useBDOForm({
  *   source: "products",
  *   operation: "create",
  *   mode: ValidationMode.OnBlur,

package/sdk/workflow/Activity.ts

@@ -12,8 +12,10 @@
 // Methods:
 //   activity.getInProgressList()          // list in-progress activity instances
 //   activity.getCompletedList()           // list completed activity instances
-//   activity.inProgressMetrics()          // get in-progress aggregated metrics
-//   activity.completedMetrics()           // get completed aggregated metrics
+//   activity.inProgressCount()            // get in-progress count (returns number)
+//   activity.completedCount()             // get completed count (returns number)
+//   activity.inProgressMetric(options)    // get in-progress aggregated metrics
+//   activity.completedMetric(options)     // get completed aggregated metrics
 //   activity.getInstance(instanceId)      // get typed ActivityInstance
 
 import { Workflow } from "./client";
@@ -22,6 +24,8 @@ import type { ActivityInstanceType } from "./ActivityInstance";
 import type { ActivityInstanceFieldsType, ActivityOperations } from "./types";
 import type {
   ListResponseType,
+  ListOptionsType,
+  MetricOptionsType,
   MetricResponseType,
 } from "../types/common";
 import { BaseField } from "../bdo/fields/BaseField";
@@ -124,32 +128,52 @@ export abstract class Activity<
 
   /**
    * List in-progress activity instances.
-   * Filtering and pagination are handled server-side.
+   * Accepts optional filter/sort/pagination options.
    */
-  async getInProgressList(): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
-    return this._ops().inProgressList();
+  async getInProgressList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
+    return this._ops().inProgressList(options);
   }
 
   /**
    * List completed activity instances.
-   * Filtering and pagination are handled server-side.
+   * Accepts optional filter/sort/pagination options.
    */
-  async getCompletedList(): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
-    return this._ops().completedList();
+  async getCompletedList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
+    return this._ops().completedList(options);
+  }
+
+  /**
+   * Get count of in-progress activity instances.
+   * Returns a number (same as BDO count()).
+   */
+  async inProgressCount(options?: ListOptionsType): Promise<number> {
+    const response = await this._ops().inProgressCount(options);
+    return response.Count;
+  }
+
+  /**
+   * Get count of completed activity instances.
+   * Returns a number (same as BDO count()).
+   */
+  async completedCount(options?: ListOptionsType): Promise<number> {
+    const response = await this._ops().completedCount(options);
+    return response.Count;
   }
 
   /**
    * Get aggregated metrics for in-progress activity instances.
+   * Accepts MetricOptionsType (without Type) for custom aggregations (Sum, Avg, etc.).
    */
-  async inProgressMetrics(): Promise<MetricResponseType> {
-    return this._ops().inProgressMetric();
+  async inProgressMetric(options: Omit<MetricOptionsType, 'Type'>): Promise<MetricResponseType> {
+    return this._ops().inProgressMetric(options);
   }
 
   /**
    * Get aggregated metrics for completed activity instances.
+   * Accepts MetricOptionsType (without Type) for custom aggregations (Sum, Avg, etc.).
    */
-  async completedMetrics(): Promise<MetricResponseType> {
-    return this._ops().completedMetric();
+  async completedMetric(options: Omit<MetricOptionsType, 'Type'>): Promise<MetricResponseType> {
+    return this._ops().completedMetric(options);
   }
 
   /**

package/sdk/workflow/client.ts

@@ -8,6 +8,9 @@ import {
 } from "../api/client";
 import type {
   ListResponseType,
+  ListOptionsType,
+  CountResponseType,
+  MetricOptionsType,
   MetricResponseType,
   ReadResponseType,
   DraftResponseType,
@@ -42,8 +45,8 @@ import type {
  * // List operations (by status — filtering/pagination handled server-side)
  * await act.inProgressList();
  * await act.completedList();
- * await act.inProgressMetric();
- * await act.completedMetric();
+ * await act.inProgressCount();
+ * await act.completedCount();
  *
  * // Process progress (requires instance_id)
  * const progress = await wf.progress("bp_inst_123");
@@ -109,10 +112,11 @@ export class Workflow<T = any> {
     return {
       // ── List-level ────────────────────────────────────────────
 
-      async inProgressList(): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
+      async inProgressList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
         const response = await fetch(`${getApiBaseUrl()}${base}/inprogress/list`, {
-          method: "GET",
+          method: "POST",
           headers: getDefaultHeaders(),
+          body: options ? JSON.stringify(options) : undefined,
         });
 
         if (!response.ok) {
@@ -122,10 +126,11 @@ export class Workflow<T = any> {
         return response.json();
       },
 
-      async completedList(): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
+      async completedList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
         const response = await fetch(`${getApiBaseUrl()}${base}/completed/list`, {
-          method: "GET",
+          method: "POST",
           headers: getDefaultHeaders(),
+          body: options ? JSON.stringify(options) : undefined,
         });
 
         if (!response.ok) {
@@ -135,27 +140,75 @@ export class Workflow<T = any> {
         return response.json();
       },
 
-      async inProgressMetric(): Promise<MetricResponseType> {
+      async inProgressCount(options?: ListOptionsType): Promise<CountResponseType> {
+        const requestBody = {
+          Type: 'Metric',
+          GroupBy: [],
+          Metric: [{ Field: '_id', Type: 'Count' }],
+          ...(options?.Filter && { Filter: options.Filter }),
+        };
         const response = await fetch(`${getApiBaseUrl()}${base}/inprogress/metric`, {
-          method: "GET",
+          method: 'POST',
+          headers: getDefaultHeaders(),
+          body: JSON.stringify(requestBody),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Failed to get in-progress count: ${response.statusText}`);
+        }
+
+        const result = await response.json();
+        const count = result.Data?.[0]?.count__id ?? 0;
+        return { Count: count };
+      },
+
+      async completedCount(options?: ListOptionsType): Promise<CountResponseType> {
+        const requestBody = {
+          Type: 'Metric',
+          GroupBy: [],
+          Metric: [{ Field: '_id', Type: 'Count' }],
+          ...(options?.Filter && { Filter: options.Filter }),
+        };
+        const response = await fetch(`${getApiBaseUrl()}${base}/completed/metric`, {
+          method: 'POST',
+          headers: getDefaultHeaders(),
+          body: JSON.stringify(requestBody),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Failed to get completed count: ${response.statusText}`);
+        }
+
+        const result = await response.json();
+        const count = result.Data?.[0]?.count__id ?? 0;
+        return { Count: count };
+      },
+
+      async inProgressMetric(options: Omit<MetricOptionsType, 'Type'>): Promise<MetricResponseType> {
+        const requestBody: MetricOptionsType = { Type: 'Metric', ...options };
+        const response = await fetch(`${getApiBaseUrl()}${base}/inprogress/metric`, {
+          method: 'POST',
           headers: getDefaultHeaders(),
+          body: JSON.stringify(requestBody),
         });
 
         if (!response.ok) {
-          throw new Error(`Failed to get in-progress activity metrics: ${response.statusText}`);
+          throw new Error(`Failed to get in-progress metrics: ${response.statusText}`);
         }
 
         return response.json();
       },
 
-      async completedMetric(): Promise<MetricResponseType> {
+      async completedMetric(options: Omit<MetricOptionsType, 'Type'>): Promise<MetricResponseType> {
+        const requestBody: MetricOptionsType = { Type: 'Metric', ...options };
         const response = await fetch(`${getApiBaseUrl()}${base}/completed/metric`, {
-          method: "GET",
+          method: 'POST',
           headers: getDefaultHeaders(),
+          body: JSON.stringify(requestBody),
         });
 
         if (!response.ok) {
-          throw new Error(`Failed to get completed activity metrics: ${response.statusText}`);
+          throw new Error(`Failed to get completed metrics: ${response.statusText}`);
         }
 
         return response.json();

package/sdk/workflow/createFieldFromMeta.ts

@@ -0,0 +1,110 @@
+// ============================================================
+// FIELD FACTORY — Runtime Field Construction from Metadata
+// ============================================================
+// Creates BaseField instances from raw BP activity Input metadata.
+// Used by useActivityForm to dynamically build fields when BP
+// metadata is fetched at runtime.
+
+import { StringField } from '../bdo/fields/StringField';
+import { NumberField } from '../bdo/fields/NumberField';
+import { BooleanField } from '../bdo/fields/BooleanField';
+import { DateField } from '../bdo/fields/DateField';
+import { DateTimeField } from '../bdo/fields/DateTimeField';
+import { TextField } from '../bdo/fields/TextField';
+import { SelectField } from '../bdo/fields/SelectField';
+import { ReferenceField } from '../bdo/fields/ReferenceField';
+import { UserField } from '../bdo/fields/UserField';
+import { FileField } from '../bdo/fields/FileField';
+import type { BaseField } from '../bdo/fields/BaseField';
+
+/**
+ * Create a BaseField instance from raw Input field metadata.
+ * Used by useActivityForm to dynamically construct fields from BP metadata.
+ *
+ * @param fieldId - The field identifier (e.g., "StartDate", "LeaveType")
+ * @param meta - Raw field metadata from BP Activity Input definition
+ * @returns A BaseField instance matching the metadata Type
+ */
+export function createFieldFromMeta(
+  fieldId: string,
+  meta: Record<string, unknown>,
+): BaseField<unknown> {
+  const fullMeta = { _id: fieldId, ...meta };
+  const type = meta.Type as string;
+
+  // String + Enum constraint → SelectField
+  if (
+    type === 'String' &&
+    (meta.Constraint as Record<string, unknown> | undefined)?.Enum
+  ) {
+    return new SelectField(fullMeta as any);
+  }
+
+  switch (type) {
+    case 'String':
+      return new StringField(fullMeta as any);
+    case 'Number':
+      return new NumberField(fullMeta as any);
+    case 'Boolean':
+      return new BooleanField(fullMeta as any);
+    case 'Date':
+      return new DateField(fullMeta as any);
+    case 'DateTime':
+      return new DateTimeField(fullMeta as any);
+    case 'Text':
+      return new TextField(fullMeta as any);
+    case 'Reference':
+      return new ReferenceField(fullMeta as any);
+    case 'User':
+      return new UserField(fullMeta as any);
+    case 'File':
+      return new FileField(fullMeta as any);
+    default:
+      return new StringField(fullMeta as any);
+  }
+}
+
+/**
+ * Build a fields map from an Activity's Input metadata.
+ *
+ * @param input - The Input object from BP Activity definition
+ *                (Record of fieldId → raw field metadata)
+ * @returns Record of fieldId → BaseField instance
+ */
+export function buildFieldsFromInput(
+  input: Record<string, Record<string, unknown>>,
+): Record<string, BaseField<unknown>> {
+  const fields: Record<string, BaseField<unknown>> = {};
+  for (const [fieldId, fieldMeta] of Object.entries(input)) {
+    fields[fieldId] = createFieldFromMeta(fieldId, fieldMeta);
+  }
+  return fields;
+}
+
+/**
+ * Search all activities in a BP blob for a field definition by name.
+ * Used to discover field metadata for Context-derived readonly fields.
+ *
+ * @param currentActivityDef - The current activity definition (to skip)
+ * @param bpSchema - The full BP schema (with BDOBlob)
+ * @param fieldName - The field name to search for
+ * @returns The field metadata or null if not found
+ */
+export function findFieldInBpActivities(
+  currentActivityDef: Record<string, unknown> | null,
+  bpSchema: Record<string, unknown> | null | undefined,
+  fieldName: string,
+): Record<string, unknown> | null {
+  const blob = (bpSchema as any)?.BDOBlob;
+  if (!blob?.Activity) return null;
+
+  const currentId = (currentActivityDef as any)?.Id;
+
+  for (const activity of blob.Activity as any[]) {
+    if (activity.Id === currentId) continue;
+    if (activity.Input?.[fieldName]) {
+      return activity.Input[fieldName];
+    }
+  }
+  return null;
+}