@ram_28/kf-ai-sdk 2.0.4 → 2.0.5

package/docs/bdo.md

@@ -740,3 +740,66 @@ suppliers.forEach((sup) => {
   console.log(`${sup._id}: ${sup.SupplierName}`);
 });
 ```
+
+---
+
+## Common Mistakes
+
+### 1. Guessing field names instead of reading BDO files
+
+ALWAYS read the BDO `.ts` files (`src/bdo/{role}/*.ts`) BEFORE writing page code. Use the exact field names from the class — NEVER guess or invent field names.
+
+```typescript
+// ❌ WRONG — guessing field names that don't exist
+bdo.used        // TS2339: Property 'used' does not exist
+bdo.remaining   // TS2339: Property 'remaining' does not exist
+bdo.meta_title  // TS2339: actual field might be 'seo_title'
+bdo.tags        // TS2339: no such field exists
+
+// ✅ CORRECT — read the BDO file first, use exact names
+// Check src/bdo/employee/LeaveBalance.ts for actual fields
+bdo.UsedLeaves     // matches the actual field in the BDO class
+bdo.RemainingDays  // matches the actual field in the BDO class
+```
+
+### 2. Inventing BDO classes that don't exist
+
+Check `src/bdo/{role}/index.ts` to see which BDO classes actually exist before importing.
+
+```typescript
+// ❌ WRONG — ShippingAddress BDO doesn't exist
+import { customerShippingAddress } from "@/bdo/customer/ShippingAddress";
+
+// ✅ CORRECT — check index.ts first. shipping_address might just be a StringField on Order
+import { customerOrder } from "@/bdo/customer/Order";
+```
+
+### 3. Calling protected methods
+
+All `BaseBdo` methods are `protected` by default. Only the methods the role has permission for are re-exposed as `public` in the generated class. Read the BDO file to see which methods are available.
+
+```typescript
+// ❌ WRONG — if delete is not in the role's BDO class
+await bdo.delete(id);  // TS2445: Property 'delete' is protected
+
+// ✅ CORRECT — use api() for methods not exposed on the BDO class
+import { api } from "@ram_28/kf-ai-sdk/api";
+await api(bdo.meta._id).delete(id);
+
+// ✅ CORRECT — for create/update, prefer useForm
+const { handleSubmit } = useForm({ bdo });
+```
+
+### 4. Not handling `.get()` return type
+
+`ItemType` field `.get()` returns `T | undefined`. Always handle the undefined case.
+
+```typescript
+// ❌ WRONG — might be undefined
+const title: string = item.Title.get();
+
+// ✅ CORRECT — provide fallback
+const title = item.Title.get() ?? "";
+const price = item.Price.get() ?? 0;
+const active = item.IsActive.get() ?? false;
+```

package/docs/useAuth.md

@@ -121,3 +121,30 @@ function AppContent() {
 | `hasAnyRole`      | `(roles: string[]) => boolean`               | Check if user has any of the roles                               |
 | `refreshSession`  | `() => Promise<SessionResponseType \| null>` | Manually refresh session                                         |
 | `clearError`      | `() => void`                                 | Clear the current error state                                    |
+
+---
+
+## Common Mistakes
+
+### 1. Wrong user name property
+
+```typescript
+// ❌ WRONG — `name` does not exist on UserDetailsType
+user?.name
+
+// ✅ CORRECT — use _name (underscore prefix)
+user?._name
+```
+
+### 2. Not casting unknown properties
+
+All properties except `_id`, `_name`, and `Role` are typed as `unknown` via the index signature.
+
+```typescript
+// ❌ WRONG — Email is typed as unknown, can't render directly in JSX
+<p>{user?.Email}</p>
+
+// ✅ CORRECT — cast to string when rendering
+<p>{String(user?.Email)}</p>
+<p>{user?.Email as string}</p>
+```

package/docs/useFilter.md

@@ -1320,3 +1320,70 @@ Produces:
 ```
 
 > **Note:** The `RHSType` field defaults to `"Constant"` and is automatically added to the payload. Other possible values are `"BOField"` (reference another field) and `"AppVariable"` (reference an application variable).
+
+---
+
+## Common Mistakes
+
+### 1. Inventing RHSType values
+
+Only three RHSType values exist. Any other string causes TS2322.
+
+```typescript
+// ❌ WRONG — these values don't exist
+{ RHSType: "Value" }
+{ RHSType: "Literal" }
+{ RHSType: "Field" }
+
+// ✅ CORRECT — only these three values
+{ RHSType: RHSType.Constant }    // "Constant"
+{ RHSType: RHSType.BOField }     // "BOField"
+{ RHSType: RHSType.AppVariable } // "AppVariable"
+```
+
+### 2. Accessing `filter.conditions` instead of `filter.items`
+
+`UseFilterReturnType` does NOT have a `conditions` property. The conditions array is called `items`.
+
+```typescript
+// ❌ WRONG — conditions does NOT exist on UseFilterReturnType
+filter.conditions
+filter.conditions.length
+
+// ✅ CORRECT — use items
+filter.items
+filter.items.length
+filter.hasConditions  // boolean shortcut
+```
+
+### 3. Mixing hook init format with API format
+
+`UseFilterOptionsType` (for hook initialization) uses lowercase. `FilterType` (for API calls) uses uppercase. NEVER mix them.
+
+```typescript
+// Hook initialization (UseFilterOptionsType) — lowercase, plural
+useTable({
+  initialState: {
+    filter: { conditions: [...], operator: "And" }
+  }
+});
+
+// API calls (FilterType) — uppercase, singular
+bdo.list({
+  Filter: { Operator: "And", Condition: [...] }
+});
+```
+
+### 4. Using `as const` on Operator values
+
+```typescript
+// ❌ WRONG — as const causes TypeScript narrowing errors in arrays
+const conditions = [
+  { Operator: ConditionOperator.EQ as const, ... }
+];
+
+// ✅ CORRECT — type the array instead
+const conditions: Omit<ConditionType, "id">[] = [
+  { Operator: ConditionOperator.EQ, ... }
+];
+```

package/docs/useForm.md

@@ -736,3 +736,62 @@ ValidationMode.All       // "all"
 FormOperation.Create     // "create"
 FormOperation.Update     // "update"
 ```
+
+---
+
+## Common Mistakes
+
+### 1. Passing FieldType instead of BDO instance
+
+`useForm` takes a BDO class **instance**, NOT a FieldType. The hook infers all types from the BDO class.
+
+```typescript
+// ❌ WRONG — FieldType as generic causes register/watch to return `never`
+useForm<ProductFieldType>({ ... });
+
+// ❌ WRONG — passing FieldType as bdo
+useForm({ bdo: ProductFieldType });
+
+// ✅ CORRECT — pass a BDO class instance
+const product = useMemo(() => new SellerProduct(), []);
+useForm({ bdo: product, mode: ValidationMode.OnBlur });
+```
+
+### 2. Wrong handleSubmit onSuccess type
+
+```typescript
+// ❌ WRONG — these types cause errors
+const onSuccess = (data: unknown) => { ... };
+const onSuccess = (data: Partial<EditableFieldType>) => { ... };
+
+// ✅ CORRECT — CreateUpdateResponseType = { _id: string }
+import type { CreateUpdateResponseType } from "@ram_28/kf-ai-sdk/api/types";
+const onSuccess = (data: CreateUpdateResponseType): void => {
+  console.log("Saved:", data._id);
+};
+```
+
+### 3. Using register() for boolean fields
+
+Boolean fields need watch/setValue pattern because HTML checkboxes don't work with register().
+
+```typescript
+// ❌ WRONG — register doesn't work correctly with checkboxes
+<input type="checkbox" {...register(bdo.IsActive.id)} />
+
+// ✅ CORRECT — use watch + setValue
+<Checkbox
+  checked={Boolean(watch(bdo.IsActive.id))}
+  onCheckedChange={(v) => setValue(bdo.IsActive.id, v as boolean)}
+/>
+```
+
+### 4. Wrong default values for date fields
+
+```typescript
+// ❌ WRONG — empty string causes type errors
+defaultValues: { StartDate: "" }
+
+// ✅ CORRECT — use undefined for date fields
+defaultValues: { StartDate: undefined }
+```

package/docs/useTable.md

@@ -142,17 +142,17 @@ interface UseTableReturnType<T> {
     field: keyof T | null;
 
     // Current sort direction, null if no sort active
-    direction: "asc" | "desc" | null;
+    direction: "ASC" | "DESC" | null;
 
     // Toggle sort on a field (triggers API call)
-    // Cycles: none → asc → desc → none
+    // Cycles: none → ASC → DESC → none
     toggle: (field: keyof T) => void;
 
     // Clear sorting (triggers API call)
     clear: () => void;
 
     // Set explicit sort field and direction (triggers API call)
-    set: (field: keyof T, direction: "asc" | "desc") => void;
+    set: (field: keyof T, direction: "ASC" | "DESC") => void;
   };
 
   // ============================================================
@@ -345,7 +345,7 @@ function MyItemsTable() {
               >
                 {col.label}
                 {table.sort.field === col.fieldId && (
-                  <span>{table.sort.direction === "asc" ? " ↑" : " ↓"}</span>
+                  <span>{table.sort.direction === "ASC" ? " ↑" : " ↓"}</span>
                 )}
               </th>
             ))}
@@ -591,7 +591,7 @@ function SortableTable() {
             >
               {col.label}
               {table.sort.field === col.fieldId && (
-                <span>{table.sort.direction === "asc" ? " ↑" : " ↓"}</span>
+                <span>{table.sort.direction === "ASC" ? " ↑" : " ↓"}</span>
               )}
             </th>
           ))}
@@ -636,17 +636,17 @@ function TableWithSortDropdown() {
     setSelectedSort(value);
     switch (value) {
       case "price-asc":
-        table.sort.set(product.Price.id, "asc");
+        table.sort.set(product.Price.id, "ASC");
         break;
       case "price-desc":
-        table.sort.set(product.Price.id, "desc");
+        table.sort.set(product.Price.id, "DESC");
         break;
       case "newest":
-        table.sort.set("_created_at", "desc");  // System field
+        table.sort.set("_created_at", "DESC");  // System field
         break;
       case "featured":
       default:
-        table.sort.set(product.Title.id, "asc");
+        table.sort.set(product.Title.id, "ASC");
         break;
     }
   };
@@ -1005,16 +1005,16 @@ function ProductListPage() {
     setSelectedSort(value);
     switch (value) {
       case "price-asc":
-        table.sort.set(product.Price.id, "asc");
+        table.sort.set(product.Price.id, "ASC");
         break;
       case "price-desc":
-        table.sort.set(product.Price.id, "desc");
+        table.sort.set(product.Price.id, "DESC");
         break;
       case "newest":
-        table.sort.set("_created_at", "desc");  // System field
+        table.sort.set("_created_at", "DESC");  // System field
         break;
       default:
-        table.sort.set(product.Title.id, "asc");
+        table.sort.set(product.Title.id, "ASC");
         break;
     }
   };
@@ -1115,3 +1115,96 @@ function ProductListPage() {
   );
 }
 ```
+
+---
+
+## Common Mistakes
+
+### 1. Passing `bdo` instead of `source`
+
+`useTable` takes `source` (a BO_ID string), NOT `bdo` (a BDO instance). Don't confuse with `useForm({ bdo })`.
+
+```typescript
+// ❌ WRONG — bdo is NOT a valid property
+useTable({ bdo, columns });
+useTable({ bdo: product, columns });
+
+// ✅ CORRECT — pass the BO_ID string via source
+useTable({ source: product.meta._id, columns });
+```
+
+### 2. Wrong initialState property names
+
+This is NOT react-table. Don't use react-table naming conventions.
+
+```typescript
+// ❌ WRONG — sorting and pageIndex don't exist
+initialState: { sorting: [...], pagination: { pageIndex: 0, pageSize: 10 } }
+
+// ✅ CORRECT — use sort and pageNo
+initialState: { sort: [{ [bdo.Title.id]: "ASC" }], pagination: { pageNo: 1, pageSize: 10 } }
+```
+
+### 3. Wrong sort direction type
+
+Sort direction must be the string literal `"ASC"` or `"DESC"` — nothing else.
+
+```typescript
+// ❌ WRONG — booleans, lowercase, or arbitrary strings
+sort.set(bdo.Title.id, true);
+sort.set(bdo.Title.id, "asc");
+sort.set(bdo.Title.id, "ascending");
+
+// ✅ CORRECT — uppercase string literals only
+sort.set(bdo.Title.id, "ASC");
+sort.set(bdo.Title.id, "DESC");
+```
+
+### 4. Calling `.get()` on table rows
+
+Table `rows` are **plain objects**, NOT `ItemType`. `.get()` is only for `ItemType` returned by `bdo.get()`, `bdo.create()`, or `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);
+table.rows.map(row => row[bdo.Title.id]);
+```
+
+### 5. Using entity-level FieldType as generic
+
+Entity-level types (from `@/bdo/entities/`) exclude `SystemFieldsType`, so `row._id` won't work.
+
+```typescript
+// ❌ WRONG — ProductFieldType excludes _id, _created_at, etc.
+import type { ProductFieldType } from "@/bdo/entities/Product";
+useTable<ProductFieldType>({ ... });
+
+// ✅ CORRECT — role-specific type includes SystemFieldsType
+import type { BuyerProductFieldType } from "@/bdo/buyer/Product";
+useTable<BuyerProductFieldType>({ ... });
+```
+
+### 6. Using `header` instead of `label` in columns
+
+```typescript
+// ❌ WRONG
+{ fieldId: bdo.Title.id, header: "Title" }
+
+// ✅ CORRECT
+{ fieldId: bdo.Title.id, label: "Title" }
+```
+
+### 7. Accessing `data` or `columns` on the return type
+
+```typescript
+// ❌ WRONG — these properties don't exist
+table.data
+table.columns
+
+// ✅ CORRECT
+table.rows       // current page data
+table.totalItems // total matching records
+```

package/docs/workflow.md

@@ -61,15 +61,20 @@ interface WorkflowStartResponseType {
 
 ```typescript
 interface ActivityProgressType {
-  Stage?: string;
-  Progress?: number;
-  [key: string]: any;
+  ActivityId: string;
+  ActivityInstanceId: string;
+  ActivityType: string;
+  AssignedTo: { Type: string; _id: string }[];
+  CompletedAt: string | null;
+  CompletedBy: { _id: string; _name: string } | null;
+  Status: "COMPLETED" | "IN_PROGRESS";
+  _name: string;
 }
 ```
 
 ### ActivityInstanceFieldsType
 
-System fields present on every activity instance. Returned alongside activity-specific fields from `getInstanceList()`.
+System fields present on every activity instance. Returned alongside activity-specific fields from `getInProgressList()` and `getCompletedList()`.
 
 ```typescript
 type ActivityInstanceFieldsType = {
@@ -84,7 +89,7 @@ type ActivityInstanceFieldsType = {
 
 ```typescript
 interface UseActivityFormOptions<A extends Activity<any, any, any>> {
-  /** Activity instance identifier (from wf.start() or getInstanceList()) */
+  /** Activity instance identifier (from wf.start() or getInProgressList()) */
   activity_instance_id: string;
 
   /** Default form values */
@@ -209,28 +214,50 @@ export class SimpleLeaveProcess {
 
 ---
 
+## Workflow Class
+
+### start()
+
+Start a new workflow instance.
+
+```typescript
+const wf = new SimpleLeaveProcess();
+const { activityId, activityInstanceId } = await wf.start();
+```
+
+### progress()
+
+Get global progress across the entire business process. Returns a list of progress entries for each stage/activity.
+
+```typescript
+const wf = new SimpleLeaveProcess();
+const progressList = await wf.progress();
+// progressList: ActivityProgressType[]
+for (const entry of progressList) {
+  console.log(entry._name, entry.Status, entry.CompletedAt);
+}
+```
+
+**Endpoint:** `GET /api/app/process/{bp_id}/progress`
+
+---
+
 ## Activity Class
 
-Each Activity class provides methods to query and access activity instances.
+Each Activity class provides methods to query and access activity instances. List and metric operations are split by status (`inprogress` / `completed`).
 
 ```typescript
 const activity = wf.employeeInputActivity();
 ```
 
-### getInstanceList(options?)
+### getInProgressList(options?)
 
-List activity instances with optional filtering and pagination.
+List in-progress activity instances with optional filtering and pagination.
 
 ```typescript
-const result = await activity.getInstanceList({
+const result = await activity.getInProgressList({
   Page: 1,
   PageSize: 20,
-  Filter: {
-    Operator: "And",
-    Condition: [
-      { LHSField: "Status", Operator: "EQ", RHSValue: "InProgress", RHSType: "Constant" },
-    ],
-  },
 });
 
 for (const item of result.Data) {
@@ -238,12 +265,37 @@ for (const item of result.Data) {
 }
 ```
 
-### instanceMetrics(options)
+### getCompletedList(options?)
+
+List completed activity instances with optional filtering and pagination.
+
+```typescript
+const result = await activity.getCompletedList({
+  Page: 1,
+  PageSize: 20,
+});
+
+for (const item of result.Data) {
+  console.log(item._id, item.CompletedAt, item.StartDate);
+}
+```
+
+### inProgressMetrics(options)
+
+Get aggregated metrics for in-progress activity instances.
+
+```typescript
+const metrics = await activity.inProgressMetrics({
+  Metric: [{ Field: "Status", Function: "Count" }],
+});
+```
+
+### completedMetrics(options)
 
-Get aggregated metrics for activity instances.
+Get aggregated metrics for completed activity instances.
 
 ```typescript
-const metrics = await activity.instanceMetrics({
+const metrics = await activity.completedMetrics({
   Metric: [{ Field: "Status", Function: "Count" }],
 });
 ```
@@ -271,7 +323,7 @@ instance.validate();                   // validate all fields
 await instance.update({ StartDate: "2026-03-01" });  // update fields
 await instance.save({ StartDate: "2026-03-01" });    // save and commit
 await instance.complete();                            // complete the activity
-const progress = await instance.progress();           // get progress
+const progress = await instance.progress();           // get progress (ActivityProgressType[])
 ```
 
 ---
@@ -284,7 +336,7 @@ React hook for building forms bound to workflow activity input fields. Integrate
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `activity_instance_id` | `string` | *required* | Activity instance ID (from `wf.start()` or `getInstanceList()`) |
+| `activity_instance_id` | `string` | *required* | Activity instance ID (from `wf.start()` or `getInProgressList()`) |
 | `defaultValues` | `Partial<Editable>` | `{}` | Initial form values |
 | `mode` | `"onBlur" \| "onChange" \| "onSubmit" \| "onTouched" \| "all"` | `"onBlur"` | Validation timing |
 | `enabled` | `boolean` | `true` | Whether to load activity data on mount |
@@ -350,6 +402,9 @@ import type { WorkflowStartResponseType } from "@ram_28/kf-ai-sdk/workflow";
 
 const wf = new SimpleLeaveProcess();
 const { activityId, activityInstanceId }: WorkflowStartResponseType = await wf.start();
+
+// Check global progress at any time
+const progress = await wf.progress();
 ```
 
 ### Step 2 — React component with useActivityForm
@@ -505,13 +560,7 @@ import { SimpleLeaveProcess } from "@/bdo/workflows/SimpleLeaveProcess";
 const wf = new SimpleLeaveProcess();
 const activity = wf.managerApprovalActivity();
 
-const result = await activity.getInstanceList({
-  Filter: {
-    Operator: "And",
-    Condition: [
-      { LHSField: "Status", Operator: "EQ", RHSValue: "InProgress", RHSType: "Constant" },
-    ],
-  },
+const result = await activity.getInProgressList({
   Page: 1,
   PageSize: 20,
 });
@@ -628,7 +677,7 @@ await instance.save({ StartDate: "2026-03-01", EndDate: "2026-03-05" });
 // Complete activity
 await instance.complete();
 
-// Check progress
+// Check progress (returns ActivityProgressType[])
 const progress = await instance.progress();
 ```
 
@@ -636,36 +685,24 @@ const progress = await instance.progress();
 
 ## Filtering Reference
 
+Status filtering is built into the method names (`getInProgressList` / `getCompletedList`), so you no longer need a Status filter condition.
+
 ### In-progress items
 
 ```typescript
-const result = await activity.getInstanceList({
-  Filter: {
-    Operator: "And",
-    Condition: [
-      { LHSField: "Status", Operator: "EQ", RHSValue: "InProgress", RHSType: "Constant" },
-    ],
-  },
-});
+const result = await activity.getInProgressList();
 ```
 
 ### Completed items
 
 ```typescript
-const result = await activity.getInstanceList({
-  Filter: {
-    Operator: "And",
-    Condition: [
-      { LHSField: "Status", Operator: "EQ", RHSValue: "Completed", RHSType: "Constant" },
-    ],
-  },
-});
+const result = await activity.getCompletedList();
 ```
 
-### Assigned to a specific user
+### Assigned to a specific user (in-progress)
 
 ```typescript
-const result = await activity.getInstanceList({
+const result = await activity.getInProgressList({
   Filter: {
     Operator: "And",
     Condition: [
@@ -675,20 +712,27 @@ const result = await activity.getInstanceList({
 });
 ```
 
-### Combined: In-progress + assigned to user
+### Assigned to a specific user (completed)
 
 ```typescript
-const result = await activity.getInstanceList({
+const result = await activity.getCompletedList({
   Filter: {
     Operator: "And",
     Condition: [
-      { LHSField: "Status", Operator: "EQ", RHSValue: "InProgress", RHSType: "Constant" },
       { LHSField: "AssignedTo._id", Operator: "EQ", RHSValue: userId, RHSType: "Constant" },
     ],
   },
 });
 ```
 
+### Global process progress
+
+```typescript
+const wf = new SimpleLeaveProcess();
+const progressList = await wf.progress();
+// Returns ActivityProgressType[] — one entry per activity in the process
+```
+
 ---
 
 ## ActivityInstance System Fields Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",
@@ -211,7 +211,7 @@
     "test": "vitest",
     "test:watch": "vitest --watch",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.0.0-beta.68",