@ram_28/kf-ai-sdk 2.0.14 → 2.0.15

package/docs/useBDOTable.md

@@ -0,0 +1,317 @@
+# useBDOTable
+
+Thin wrapper around `useTable` for BDO (Business Data Object) tables. Instead of manually wiring up `queryKey`, `listFn`, and `countFn`, you pass a BDO instance and the hook handles the rest.
+
+## Imports
+
+```typescript
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/table";
+import type { UseBDOTableOptionsType, UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
+```
+
+---
+
+## Common Mistakes (READ FIRST)
+
+### 1. Passing `source` instead of `bdo`
+
+`useBDOTable` takes a `bdo` instance, NOT a `source` string.
+
+```typescript
+// ❌ WRONG — source is not a valid property on useBDOTable
+useBDOTable({ source: product.meta._id });
+
+// ✅ CORRECT — pass the BDO instance
+useBDOTable({ bdo: product });
+```
+
+### 2. Passing a raw object instead of a BDO instance
+
+The `bdo` property expects an object with `meta`, `list()`, and `count()`. A plain object or entity type will not work.
+
+```typescript
+// ❌ WRONG — plain object without list/count methods
+useBDOTable({ bdo: { _id: 'BO_Product', name: 'Product' } });
+
+// ✅ CORRECT — a BDO class instance
+const product = useMemo(() => new BuyerProduct(), []);
+useBDOTable({ bdo: product });
+```
+
+### 3. Recreating the BDO on every render
+
+Constructing the BDO inside the component body without `useMemo` creates a new instance on every render, which destabilizes the query key and causes infinite refetching.
+
+```typescript
+// ❌ WRONG — new instance every render
+function ProductsTable() {
+  const product = new BuyerProduct();
+  const table = useBDOTable({ bdo: product }); // infinite refetch loop
+}
+
+// ✅ CORRECT — memoize the instance
+function ProductsTable() {
+  const product = useMemo(() => new BuyerProduct(), []);
+  const table = useBDOTable({ bdo: product });
+}
+```
+
+### 4. Using `columns` with useBDOTable
+
+`useBDOTable` does not accept a `columns` property. Column definitions are a UI concern handled in your rendering logic, not in the hook options.
+
+```typescript
+// ❌ WRONG — columns is not a hook option
+useBDOTable({
+  bdo: product,
+  columns: [{ fieldId: 'Title', label: 'Title' }],
+});
+
+// ✅ CORRECT — define columns separately for rendering
+const columns = [
+  { fieldId: product.Title.id, label: product.Title.label },
+  { fieldId: product.Price.id, label: product.Price.label },
+];
+const table = useBDOTable({ bdo: product });
+```
+
+### 5. Calling `.get()` on table rows
+
+Table `rows` are plain objects, NOT `ItemType`. The `.get()` accessor is only available on items returned by `bdo.get()`, `bdo.create()`, or the `useForm` item proxy.
+
+```typescript
+// ❌ WRONG — rows are plain objects, not ItemType
+table.rows.map((row) => row.Title.get());
+
+// ✅ CORRECT — access properties directly
+table.rows.map((row) => row.Title);
+```
+
+### 6. Wrong initialState property names
+
+This is not react-table. Do not use react-table naming conventions.
+
+```typescript
+// ❌ WRONG — sorting and pageIndex are react-table names
+useBDOTable({
+  bdo: product,
+  initialState: { sorting: [...], pagination: { pageIndex: 0, pageSize: 10 } },
+});
+
+// ✅ CORRECT — use sort and pageNo (1-indexed)
+useBDOTable({
+  bdo: product,
+  initialState: {
+    sort: [{ [product.Title.id]: 'ASC' }],
+    pagination: { pageNo: 1, pageSize: 10 },
+  },
+});
+```
+
+---
+
+## Complete Example
+
+A product listing page with search, filter, sort, and pagination.
+
+```tsx
+import { useMemo, useState } from "react";
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/table";
+import type { UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
+import { BuyerProduct } from "../bdo/buyer/Product";
+import type { BuyerProductFieldType } from "../bdo/buyer/Product";
+
+function ProductListPage() {
+  const productBdo = useMemo(() => new BuyerProduct(), []);
+  const [selectedCategory, setSelectedCategory] = useState("all");
+
+  const table: UseBDOTableReturnType<BuyerProductFieldType> =
+    useBDOTable<BuyerProductFieldType>({
+      bdo: productBdo,
+      initialState: {
+        sort: [{ [productBdo.Title.id]: "ASC" }],
+        pagination: { pageNo: 1, pageSize: 10 },
+      },
+      onError: (error) => {
+        console.error("Table fetch failed:", error.message);
+      },
+      onSuccess: (data) => {
+        console.log("Loaded", data.length, "rows");
+      },
+    });
+
+  const handleCategoryChange = (category: string) => {
+    setSelectedCategory(category);
+    table.filter.clearAllConditions();
+    if (category !== "all") {
+      table.filter.addCondition({
+        LHSField: productBdo.Category.id,
+        Operator: ConditionOperator.EQ,
+        RHSValue: category,
+        RHSType: RHSType.Constant,
+      });
+    }
+  };
+
+  if (table.isLoading) return <div>Loading...</div>;
+  if (table.error) {
+    return (
+      <div>
+        <p>Error: {table.error.message}</p>
+        <button onClick={() => table.refetch()}>Retry</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {/* Search */}
+      <input
+        type="text"
+        placeholder="Search products..."
+        value={table.search.query}
+        onChange={(e) => table.search.set(productBdo.Title.id, e.target.value)}
+      />
+      {table.search.query && (
+        <button onClick={table.search.clear}>Clear Search</button>
+      )}
+
+      {/* Category Filter */}
+      <select
+        value={selectedCategory}
+        onChange={(e) => handleCategoryChange(e.target.value)}
+      >
+        <option value="all">All Categories</option>
+        <option value="Electronics">Electronics</option>
+        <option value="Books">Books</option>
+      </select>
+
+      {/* Sort */}
+      <select
+        onChange={(e) => {
+          const [field, dir] = e.target.value.split(":");
+          table.sort.set(field, dir as "ASC" | "DESC");
+        }}
+      >
+        <option value={`${productBdo.Title.id}:ASC`}>Name A-Z</option>
+        <option value={`${productBdo.Price.id}:ASC`}>Price: Low to High</option>
+        <option value={`${productBdo.Price.id}:DESC`}>Price: High to Low</option>
+      </select>
+
+      {/* Results */}
+      <p>{table.totalItems} results</p>
+      <div>
+        {table.rows.map((row) => (
+          <div key={row._id}>
+            <h3>{row.Title}</h3>
+            <p>${row.Price}</p>
+            <p>{row.Category}</p>
+          </div>
+        ))}
+      </div>
+
+      {/* Pagination */}
+      <div>
+        <button
+          onClick={table.pagination.goToPrevious}
+          disabled={!table.pagination.canGoPrevious}
+        >
+          Previous
+        </button>
+        <span>
+          Page {table.pagination.pageNo} of {table.pagination.totalPages}
+        </span>
+        <button
+          onClick={table.pagination.goToNext}
+          disabled={!table.pagination.canGoNext}
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Type Definitions
+
+### UseBDOTableOptionsType
+
+```typescript
+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;
+}
+```
+
+### UseBDOTableReturnType
+
+```typescript
+export type UseBDOTableReturnType<T> = UseTableReturnType<T>;
+```
+
+The return type is identical to `UseTableReturnType<T>`. All properties — `rows`, `totalItems`, `isLoading`, `isFetching`, `error`, `search`, `sort`, `filter`, `pagination`, and `refetch` — behave the same.
+
+---
+
+## Search, Sort, Filter, and Pagination
+
+These features are inherited from the base `useTable` hook. `useBDOTable` passes `initialState`, `onError`, and `onSuccess` straight through.
+
+- **Search** — `table.search.set(field, query)`, `table.search.clear()`, 300ms debounce
+- **Sort** — `table.sort.toggle(field)`, `table.sort.set(field, direction)`, `table.sort.clear()`
+- **Filter** — `table.filter.addCondition(...)`, `table.filter.removeCondition(...)`, `table.filter.clearAllConditions()`
+- **Pagination** — `table.pagination.goToNext()`, `table.pagination.goToPrevious()`, `table.pagination.goToPage(n)`, `table.pagination.setPageSize(n)`
+
+---
+
+## Migration Guide: `useTable` to `useBDOTable`
+
+### Before (useTable)
+
+```typescript
+const table = useTable<BuyerProductFieldType>({
+  queryKey: ["table", product.meta._id],
+  listFn: (opts) => product.list(opts),
+  countFn: (opts) => product.count(opts),
+  initialState: { sort: [{ [product.Title.id]: "ASC" }], pagination: { pageNo: 1, pageSize: 10 } },
+});
+```
+
+### After (useBDOTable)
+
+```typescript
+const table = useBDOTable<BuyerProductFieldType>({
+  bdo: product,
+  initialState: { sort: [{ [product.Title.id]: "ASC" }], pagination: { pageNo: 1, pageSize: 10 } },
+});
+```
+
+| Property | `useTable` | `useBDOTable` |
+|----------|-----------|---------------|
+| Data source | `queryKey` + `listFn` + `countFn` | `bdo` (single property) |
+| Query key | Manual: `["table", bdo.meta._id]` | Automatic: derived from `bdo.meta._id` |
+| List function | Manual: `(opts) => bdo.list(opts)` | Automatic: bound from `bdo.list()` |
+| Count function | Manual: `(opts) => bdo.count(opts)` | Automatic: bound from `bdo.count()` |
+| Return type | `UseTableReturnType<T>` | `UseBDOTableReturnType<T>` (alias) |

package/docs/workflow.md

@@ -11,6 +11,8 @@ import {
   Activity,
   ActivityInstance,
   useActivityForm,
+  useActivityTable,
+  ActivityTableStatus,
 } from "@ram_28/kf-ai-sdk/workflow";
 
 // Type-only exports
@@ -20,6 +22,10 @@ import type {
   WorkflowStartResponseType,
   UseActivityFormOptions,
   UseActivityFormReturn,
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityTableStatusType,
+  ActivityRowType,
 } from "@ram_28/kf-ai-sdk/workflow";
 
 // Field classes (for defining Activity fields)
@@ -31,7 +37,7 @@ import {
   DateTimeField,
   SelectField,
   ReferenceField,
-} from "@ram_28/kf-ai-sdk/bdo/fields";
+} from '@ram_28/kf-ai-sdk/bdo/fields';
 
 // Field types (for entity type definitions)
 import type {
@@ -42,7 +48,7 @@ import type {
   DateTimeFieldType,
   SelectFieldType,
   ReferenceFieldType,
-} from "@ram_28/kf-ai-sdk/types";
+} from '@ram_28/kf-ai-sdk/types';
 ```
 
 ---
@@ -82,11 +88,18 @@ System fields present on every activity instance. Returned alongside activity-sp
 type ActivityInstanceFieldsType = {
   _id: StringFieldType;
   Status: SelectFieldType<"InProgress" | "Completed">;
-  AssignedTo: ReferenceFieldType<{ _id: StringFieldType; username: StringFieldType }>;
+  AssignedTo: UserFieldType[];
   CompletedAt: DateTimeFieldType;
 };
 ```
 
+### Activity Table Types
+
+See the dedicated [useActivityTable documentation](./useActivityTable.md) for `ActivityTableStatus`, `ActivityRowType`, `UseActivityTableOptionsType`, and `UseActivityTableReturnType`.
+
+**Key change:** Entity fields are now nested under `ADO` instead of being flattened at the top level. Access entity fields as `row.ADO.FieldName`.
+
+
 ### UseActivityFormOptions\<A\>
 
 ```typescript
@@ -141,6 +154,13 @@ interface UseActivityFormReturn<A extends Activity<any, any, any>> {
 }
 ```
 
+### File & Image Types
+
+Image accessor: `item.field.get()` returns `FileType | null`. Has `upload(file: File)`, `deleteAttachment()`, `getDownloadUrl()`.
+File accessor: `item.field.get()` returns `FileType[]`. Has `upload(files: File[])`, `deleteAttachment(id)`, `getDownloadUrl(id)`.
+
+Activity forms always have an instance ID, so attachment operations work immediately — no draft creation is needed.
+
 ---
 
 ## Generated Workflow SDK
@@ -250,21 +270,30 @@ Each Activity class provides methods to query and access activity instances. Lis
 const activity = wf.employeeInputActivity();
 ```
 
-### getInProgressList()
+### getInProgressList(options?)
 
-List in-progress activity instances. Filtering and pagination are handled server-side automatically.
+List in-progress activity instances. Accepts optional `ListOptionsType` payload for server-side filtering, sorting, and pagination.
 
 ```typescript
+// No options — returns all in-progress items (default pagination)
 const result = await activity.getInProgressList();
 
 for (const item of result.Data) {
   console.log(item._id, item.Status, item.StartDate);
 }
+
+// With options — server-side filter, sort, and pagination
+const filtered = await activity.getInProgressList({
+  Filter: { Operator: 'And', Condition: [{ LHSField: 'Status', Operator: 'EQ', RHSValue: 'InProgress', RHSType: 'Constant' }] },
+  Sort: [{ '_created_at': 'DESC' }],
+  Page: 1,
+  PageSize: 10,
+});
 ```
 
-### getCompletedList()
+### getCompletedList(options?)
 
-List completed activity instances. Filtering and pagination are handled server-side automatically.
+List completed activity instances. Same options as `getInProgressList`.
 
 ```typescript
 const result = await activity.getCompletedList();
@@ -274,20 +303,22 @@ for (const item of result.Data) {
 }
 ```
 
-### inProgressMetrics()
+### inProgressMetrics(options?)
 
-Get aggregated metrics for in-progress activity instances.
+Get count of in-progress activity instances. Returns `CountResponseType` (`{ Count: number }`).
 
 ```typescript
-const metrics = await activity.inProgressMetrics();
+const { Count } = await activity.inProgressMetrics();
+console.log('In-progress count:', Count);
 ```
 
-### completedMetrics()
+### completedMetrics(options?)
 
-Get aggregated metrics for completed activity instances.
+Get count of completed activity instances. Returns `CountResponseType` (`{ Count: number }`).
 
 ```typescript
-const metrics = await activity.completedMetrics();
+const { Count } = await activity.completedMetrics();
+console.log('Completed count:', Count);
 ```
 
 ### getInstance(instanceId)
@@ -382,6 +413,15 @@ User clicks Complete
 
 ---
 
+## useActivityTable Hook
+
+See the dedicated [useActivityTable documentation](./useActivityTable.md) for the full API reference, type definitions, and examples.
+
+`useActivityTable` now wraps the base `useTable` hook, providing the same search, sort, filter, and pagination capabilities as BDO tables. Entity fields are accessed via `row.ADO.FieldName`.
+
+---
+
+
 ## Use Case: Employee Creating Leave
 
 ### Step 1 — Start the workflow
@@ -465,22 +505,22 @@ function LeaveRequestForm({ activityInstanceId, onComplete }: LeaveRequestFormPr
 
       {/* Start Date */}
       <div>
-        <label>{activity.StartDate.meta.label}</label>
-        <input type="date" {...register(activity.StartDate.meta.id)} />
+        <label>{activity.StartDate.label}</label>
+        <input type="date" {...register(activity.StartDate.id)} />
         {errors.StartDate && <span>{errors.StartDate.message}</span>}
       </div>
 
       {/* End Date */}
       <div>
-        <label>{activity.EndDate.meta.label}</label>
-        <input type="date" {...register(activity.EndDate.meta.id)} />
+        <label>{activity.EndDate.label}</label>
+        <input type="date" {...register(activity.EndDate.id)} />
         {errors.EndDate && <span>{errors.EndDate.message}</span>}
       </div>
 
       {/* Leave Type */}
       <div>
-        <label>{activity.LeaveType.meta.label}</label>
-        <select {...register(activity.LeaveType.meta.id)}>
+        <label>{activity.LeaveType.label}</label>
+        <select {...register(activity.LeaveType.id)}>
           <option value="">Select type</option>
           <option value="PTO">PTO</option>
           <option value="Sick">Sick</option>
@@ -491,8 +531,8 @@ function LeaveRequestForm({ activityInstanceId, onComplete }: LeaveRequestFormPr
 
       {/* Leave Days (readonly — auto-disabled, computed by server) */}
       <div>
-        <label>{activity.LeaveDays.meta.label}</label>
-        <input type="number" {...register(activity.LeaveDays.meta.id)} />
+        <label>{activity.LeaveDays.label}</label>
+        <input type="number" {...register(activity.LeaveDays.id)} />
       </div>
 
       {/* Actions */}
@@ -544,16 +584,72 @@ function LeaveRequestPage() {
 
 ### Step 1 — List in-progress items
 
-```typescript
-import { SimpleLeaveProcess } from "@/bdo/workflows/SimpleLeaveProcess";
+```tsx
+import { useMemo, useState } from "react";
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import { SimpleLeaveProcess, ManagerApprovalActivity } from "@/bdo/workflows/SimpleLeaveProcess";
 
 const wf = new SimpleLeaveProcess();
 const activity = wf.managerApprovalActivity();
 
-const result = await activity.getInProgressList();
+  const { rows, totalItems, isLoading, error, pagination, refetch } = useActivityTable(activity, {
+    status: ActivityTableStatus.InProgress,
+    initialState: {
+      pagination: { pageNo: 1, pageSize: 10 },
+    },
+  });
 
-for (const item of result.Data) {
-  console.log(item._id, item.Status, item.AssignedTo.username);
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  if (selectedId) {
+    return (
+      <ApprovalForm
+        activityInstanceId={selectedId}
+        onComplete={() => {
+          setSelectedId(null);
+          refetch();
+        }}
+      />
+    );
+  }
+
+  return (
+    <div>
+      <h2>Pending Approvals ({totalItems})</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>ID</th>
+            <th>Status</th>
+            <th>Assigned To</th>
+            <th>Approved</th>
+            <th>Reason</th>
+            <th>Action</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row._id}>
+              <td>{row._id}</td>
+              <td>{row.Status}</td>
+              <td>{row.AssignedTo.map((u) => u._name).join(", ")}</td>
+              <td>{row.ADO.ManagerApproved ? "Yes" : "No"}</td>
+              <td>{row.ADO.ManagerReason}</td>
+              <td>
+                <button onClick={() => setSelectedId(row._id)}>Review</button>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      <div>
+        <button onClick={pagination.goToPrevious} disabled={!pagination.canGoPrevious}>Previous</button>
+        <span>Page {pagination.pageNo} of {pagination.totalPages}</span>
+        <button onClick={pagination.goToNext} disabled={!pagination.canGoNext}>Next</button>
+      </div>
+    </div>
+  );
 }
 ```
 
@@ -610,14 +706,14 @@ function ApprovalForm({ activityInstanceId, onComplete }: ApprovalFormProps) {
 
       <div>
         <label>
-          <input type="checkbox" {...register(activity.ManagerApproved.meta.id)} />
-          {activity.ManagerApproved.meta.label}
+          <input type="checkbox" {...register(activity.ManagerApproved.id)} />
+          {activity.ManagerApproved.label}
         </label>
       </div>
 
       <div>
-        <label>{activity.ManagerReason.meta.label}</label>
-        <textarea {...register(activity.ManagerReason.meta.id)} rows={4} />
+        <label>{activity.ManagerReason.label}</label>
+        <textarea {...register(activity.ManagerReason.id)} rows={4} />
       </div>
 
       <button type="button" onClick={handleComplete(onSuccess, onError)}>
@@ -653,7 +749,7 @@ instance.StartDate.set("2026-03-01");
 instance.EndDate.set("2026-03-05");
 
 // Field metadata
-console.log(instance.StartDate.meta.label);  // "Start Date"
+console.log(instance.StartDate.label);  // "Start Date"
 
 // Persist changes
 await instance.update({ StartDate: "2026-03-01", EndDate: "2026-03-05" });
@@ -672,18 +768,31 @@ const progress = await instance.progress();
 
 ## Filtering Reference
 
-Status filtering is built into the method names (`getInProgressList` / `getCompletedList`). All filtering (by current user, activity status, and activity ID) and pagination are handled server-side automatically — no client-side options are needed.
+Status filtering is built into the method names (`getInProgressList` / `getCompletedList`). Internal filters (ActivityId, Status, AssignedTo) are **always applied** by the backend. Frontend filters passed via `ListOptionsType` are AND-merged with the internal filters.
+
+All four list/metric endpoints now use **POST** with an optional `ListOptionsType` body (same shape as BDO list API: `{ Filter, Sort, Page, PageSize }`).
 
 ### In-progress items
 
 ```typescript
+// No options — returns all (default pagination)
 const result = await activity.getInProgressList();
+
+// With filter + pagination
+const result = await activity.getInProgressList({
+  Sort: [{ '_created_at': 'DESC' }],
+  Page: 1,
+  PageSize: 25,
+});
 ```
 
 ### Completed items
 
 ```typescript
-const result = await activity.getCompletedList();
+const result = await activity.getCompletedList({
+  Page: 1,
+  PageSize: 25,
+});
 ```
 
 ### Process progress
@@ -703,7 +812,7 @@ const progressList = await wf.progress(BPInstanceId);
 |-------|------|-------------|
 | `_id` | `StringFieldType` | Unique activity instance identifier |
 | `Status` | `SelectFieldType<"InProgress" \| "Completed">` | Current status |
-| `AssignedTo` | `ReferenceFieldType<UserRefType>` | Assigned user (has `._id` and `.username`) |
+| `AssignedTo` | `UserFieldType[]` | Assigned users (each has `._id` and `._name`) |
 | `CompletedAt` | `DateTimeFieldType` | Completion timestamp (`"YYYY-MM-DDTHH:MM:SS"`) |
 
 ---

package/package.json

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

package/sdk/bdo/fields/UserField.ts

@@ -35,7 +35,7 @@ export class UserField extends BaseField<UserFieldType> {
   async fetchOptions(instanceId: string): Promise<UserFieldType[]> {
     if (!this._parentBoId) {
       throw new Error(
-        `Field ${this.id} not bound to a BDO. Cannot fetch options.`
+        `Field ${this.id} not bound to a BDO. Cannot fetch options.`,
       );
     }
     return api(this._parentBoId).fetchField<UserFieldType>(instanceId, this.id);