@ram_28/kf-ai-sdk 2.0.13 → 2.0.15

package/sdk/components/hooks/useActivityTable/useActivityTable.ts

@@ -0,0 +1,71 @@
+import { useMemo } from 'react';
+import { useTable } from '../useTable';
+import type { Activity } from '../../../workflow/Activity';
+import type {
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityRowType,
+} from './types';
+
+const ACTIVITY_SYSTEM_FIELDS = new Set([
+  '_id',
+  'BPInstanceId',
+  'Status',
+  'AssignedTo',
+  'CompletedAt',
+]);
+
+function nestEntityFields(
+  flatRow: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const ado: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(flatRow)) {
+    if (ACTIVITY_SYSTEM_FIELDS.has(key)) {
+      result[key] = value;
+    } else {
+      ado[key] = value;
+    }
+  }
+  result.ADO = ado;
+  return result;
+}
+
+export function useActivityTable<A extends Activity<any, any, any>>(
+  activity: A,
+  options: UseActivityTableOptionsType<A>,
+): UseActivityTableReturnType<A> {
+  const { status, ...rest } = options;
+  const { businessProcessId, activityId } = activity.meta;
+
+  const ops = useMemo(() => activity._getOps(), [activity]);
+
+  const listFn = useMemo(() => {
+    const rawFn =
+      status === 'inprogress'
+        ? (opts: any) => ops.inProgressList(opts)
+        : (opts: any) => ops.completedList(opts);
+    return async (opts: any) => {
+      const result = await rawFn(opts);
+      return {
+        ...result,
+        Data: result.Data.map(nestEntityFields),
+      } as typeof result;
+    };
+  }, [ops, status]);
+
+  const countFn = useMemo(
+    () =>
+      status === 'inprogress'
+        ? (opts: any) => ops.inProgressMetric(opts)
+        : (opts: any) => ops.completedMetric(opts),
+    [ops, status],
+  );
+
+  return useTable<ActivityRowType<A>>({
+    queryKey: ['activity-table', businessProcessId, activityId, status],
+    listFn,
+    countFn,
+    ...rest,
+  });
+}

package/sdk/components/hooks/useBDOTable/index.ts

@@ -0,0 +1,2 @@
+export { useBDOTable } from './useBDOTable';
+export type { UseBDOTableOptionsType, UseBDOTableReturnType } from './types';

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

@@ -0,0 +1,24 @@
+import type { UseTableReturnType, PaginationStateType } from '../useTable/types';
+import type { UseFilterOptionsType } from '../useFilter/types';
+import type { SortType } from '../../../types/common';
+
+export interface UseBDOTableOptionsType<T> {
+  /** BDO instance with list() and count() methods */
+  bdo: {
+    meta: { readonly _id: string; readonly name: string };
+    list(options?: any): Promise<any>;
+    count(options?: any): Promise<any>;
+  };
+  /** Initial state */
+  initialState?: {
+    sort?: SortType;
+    pagination?: PaginationStateType;
+    filter?: UseFilterOptionsType<T>;
+  };
+  /** Error callback */
+  onError?: (error: Error) => void;
+  /** Success callback — receives rows from current page */
+  onSuccess?: (data: T[]) => void;
+}
+
+export type UseBDOTableReturnType<T> = UseTableReturnType<T>;

package/sdk/components/hooks/useBDOTable/useBDOTable.ts

@@ -0,0 +1,15 @@
+import { useTable } from '../useTable';
+import type { UseBDOTableOptionsType, UseBDOTableReturnType } from './types';
+
+export function useBDOTable<T = any>(
+  options: UseBDOTableOptionsType<T>,
+): UseBDOTableReturnType<T> {
+  const { bdo, ...rest } = options;
+
+  return useTable<T>({
+    queryKey: ['table', bdo.meta._id],
+    listFn: (opts) => bdo.list(opts),
+    countFn: (opts) => bdo.count(opts),
+    ...rest,
+  });
+}

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

@@ -1,9 +1,9 @@
 // Main hook
-export { useTable } from "./useTable";
+export { useTable } from './useTable';
 
 // Types
 export type {
-  ColumnDefinitionType,
   UseTableOptionsType,
   UseTableReturnType,
-} from "./types";
+  PaginationStateType,
+} from './types';

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

@@ -1,8 +1,10 @@
-import type { ListResponseType, SortType, ColumnDefinitionType } from "../../../types/common";
-
-// Re-export ColumnDefinitionType for backwards compatibility
-export type { ColumnDefinitionType };
-import type { UseFilterReturnType, UseFilterOptionsType } from "../useFilter";
+import type {
+  ListResponseType,
+  ListOptionsType,
+  CountResponseType,
+  SortType,
+} from '../../../types/common';
+import type { UseFilterReturnType, UseFilterOptionsType } from '../useFilter';
 
 // ============================================================
 // STATE TYPE DEFINITIONS
@@ -23,10 +25,12 @@ export interface PaginationStateType {
 // ============================================================
 
 export interface UseTableOptionsType<T> {
-  /** Data source identifier */
-  source: string;
-  /** Column configurations */
-  columns: ColumnDefinitionType<T>[];
+  /** Unique query key for React Query caching */
+  queryKey: string[];
+  /** Fetch list data (POST with filter/sort/pagination) */
+  listFn: (options: ListOptionsType) => Promise<ListResponseType<T>>;
+  /** Fetch count (POST with filter only) */
+  countFn: (options: ListOptionsType) => Promise<CountResponseType>;
   /** Initial state */
   initialState?: {
     /** Sort configuration: [{ "fieldName": "ASC" }] */
@@ -38,7 +42,7 @@ export interface UseTableOptionsType<T> {
   };
   /** Error callback */
   onError?: (error: Error) => void;
-  /** Success callback */
+  /** Success callback — receives rows from current page */
   onSuccess?: (data: T[]) => void;
 }
 
@@ -65,10 +69,10 @@ export interface UseTableReturnType<T> {
   // Sorting (Flat Access)
   sort: {
     field: keyof T | null;
-    direction: "ASC" | "DESC" | null;
+    direction: 'ASC' | 'DESC' | null;
     toggle: (field: keyof T) => void;
     clear: () => void;
-    set: (field: keyof T, direction: "ASC" | "DESC") => void;
+    set: (field: keyof T | null, direction: 'ASC' | 'DESC' | null) => void;
   };
 
   // Filter (Simplified chainable API)

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/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/workflow/Activity.ts

@@ -22,7 +22,8 @@ import type { ActivityInstanceType } from "./ActivityInstance";
 import type { ActivityInstanceFieldsType, ActivityOperations } from "./types";
 import type {
   ListResponseType,
-  MetricResponseType,
+  ListOptionsType,
+  CountResponseType,
 } from "../types/common";
 import { BaseField } from "../bdo/fields/BaseField";
 
@@ -124,32 +125,32 @@ 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 aggregated metrics for in-progress activity instances.
+   * Get count of in-progress activity instances.
    */
-  async inProgressMetrics(): Promise<MetricResponseType> {
-    return this._ops().inProgressMetric();
+  async inProgressMetrics(options?: ListOptionsType): Promise<CountResponseType> {
+    return this._ops().inProgressMetric(options);
   }
 
   /**
-   * Get aggregated metrics for completed activity instances.
+   * Get count of completed activity instances.
    */
-  async completedMetrics(): Promise<MetricResponseType> {
-    return this._ops().completedMetric();
+  async completedMetrics(options?: ListOptionsType): Promise<CountResponseType> {
+    return this._ops().completedMetric(options);
   }
 
   /**

package/sdk/workflow/client.ts

@@ -8,7 +8,8 @@ import {
 } from "../api/client";
 import type {
   ListResponseType,
-  MetricResponseType,
+  ListOptionsType,
+  CountResponseType,
   ReadResponseType,
   DraftResponseType,
   CreateUpdateResponseType,
@@ -108,8 +109,20 @@ export class Workflow<T = any> {
 
     return {
       // ── List-level ────────────────────────────────────────────
-
-      async inProgressList(): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
+      // TODO: Backend currently only supports GET for list/metric endpoints.
+      // Once backend is updated to accept POST with Filter/Sort/Page body,
+      // switch back to POST so useTable features (search, sort, pagination) work.
+      //
+      // POST version (waiting for backend):
+      // async inProgressList(options?: ListOptionsType) {
+      //   return fetch(url + "/inprogress/list", {
+      //     method: "POST", headers: getDefaultHeaders(),
+      //     body: options ? JSON.stringify(options) : undefined,
+      //   });
+      // }
+      // (same pattern for completedList, inProgressMetric, completedMetric)
+
+      async inProgressList(_options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
         const response = await fetch(`${getApiBaseUrl()}${base}/inprogress/list`, {
           method: "GET",
           headers: getDefaultHeaders(),
@@ -122,7 +135,7 @@ 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",
           headers: getDefaultHeaders(),
@@ -135,27 +148,27 @@ export class Workflow<T = any> {
         return response.json();
       },
 
-      async inProgressMetric(): Promise<MetricResponseType> {
+      async inProgressMetric(_options?: ListOptionsType): Promise<CountResponseType> {
         const response = await fetch(`${getApiBaseUrl()}${base}/inprogress/metric`, {
           method: "GET",
           headers: getDefaultHeaders(),
         });
 
         if (!response.ok) {
-          throw new Error(`Failed to get in-progress activity metrics: ${response.statusText}`);
+          throw new Error(`Failed to get in-progress activity count: ${response.statusText}`);
         }
 
         return response.json();
       },
 
-      async completedMetric(): Promise<MetricResponseType> {
+      async completedMetric(_options?: ListOptionsType): Promise<CountResponseType> {
         const response = await fetch(`${getApiBaseUrl()}${base}/completed/metric`, {
           method: "GET",
           headers: getDefaultHeaders(),
         });
 
         if (!response.ok) {
-          throw new Error(`Failed to get completed activity metrics: ${response.statusText}`);
+          throw new Error(`Failed to get completed activity count: ${response.statusText}`);
         }
 
         return response.json();