@ram_28/kf-ai-sdk 2.0.10 → 2.0.12

package/dist/workflow.types.d.ts

@@ -1,2 +1,3 @@
 export type { ActivityInstanceFieldsType, ActivityOperations, ActivityProgressType, WorkflowStartResponseType, } from './workflow/types';
+export type { UseActivityTableOptionsType, UseActivityTableReturnType, ActivityTableStatusType, ActivityRowType, } from './workflow/components/useActivityTable/types';
 //# sourceMappingURL=workflow.types.d.ts.map

package/dist/workflow.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.types.d.ts","sourceRoot":"","sources":["../sdk/workflow.types.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"workflow.types.d.ts","sourceRoot":"","sources":["../sdk/workflow.types.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,uBAAuB,EACvB,eAAe,GAChB,MAAM,8CAA8C,CAAC"}

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,9 @@ import type {
   WorkflowStartResponseType,
   UseActivityFormOptions,
   UseActivityFormReturn,
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityRowType,
 } from "@ram_28/kf-ai-sdk/workflow";
 
 // Field classes (for defining Activity fields)
@@ -82,11 +87,72 @@ 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;
 };
 ```
 
+### ActivityTableStatus (constant)
+
+```typescript
+const ActivityTableStatus = {
+  InProgress: 'inprogress',
+  Completed: 'completed',
+} as const;
+
+type ActivityTableStatusType =
+  (typeof ActivityTableStatus)[keyof typeof ActivityTableStatus];
+```
+
+### ActivityRowType\<A\>
+
+Row type for activity table data. Combines activity instance system fields with entity-specific fields.
+
+```typescript
+type ActivityRowType<A extends Activity<any, any, any>> =
+  ActivityInstanceFieldsType & ExtractActivityEntity<A>;
+```
+
+Concrete example — for `ManagerApprovalActivity` with `{ ManagerApproved: boolean, ManagerReason: string }`:
+
+```typescript
+// ActivityRowType<ManagerApprovalActivity> resolves to:
+{
+  // System fields (from ActivityInstanceFieldsType)
+  _id: string;
+  Status: "InProgress" | "Completed";
+  AssignedTo: UserFieldType;
+  CompletedAt: string;
+
+  // Entity fields (from ManagerApprovalEntityType)
+  ManagerApproved: boolean;
+  ManagerReason: string;
+}
+```
+
+### UseActivityTableOptionsType\<A\>
+
+```typescript
+interface UseActivityTableOptionsType<A extends Activity<any, any, any>> {
+  status: ActivityTableStatusType;
+  onError?: (error: Error) => void;
+  onSuccess?: (data: ActivityRowType<A>[]) => void;
+}
+```
+
+### UseActivityTableReturnType\<A\>
+
+```typescript
+interface UseActivityTableReturnType<A extends Activity<any, any, any>> {
+  rows: ActivityRowType<A>[];
+  totalItems: number;
+  isLoading: boolean;
+  isFetching: boolean;
+  error: Error | null;
+  refetch: () => Promise<ListResponseType<ActivityRowType<A>>>;
+}
+```
+
 ### UseActivityFormOptions\<A\>
 
 ```typescript
@@ -382,6 +448,40 @@ User clicks Complete
 
 ---
 
+## useActivityTable Hook
+
+React hook for listing workflow activity instances. Fetches data from
+`getInProgressList()` or `getCompletedList()` and the corresponding
+metrics endpoint.
+
+### Signature
+
+```typescript
+useActivityTable(activity: A, options: UseActivityTableOptionsType<A>)
+  : UseActivityTableReturnType<A>
+```
+
+### Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `status` | `ActivityTableStatusType` | *required* | `ActivityTableStatus.InProgress` or `ActivityTableStatus.Completed` |
+| `onError` | `(error: Error) => void` | — | Error callback |
+| `onSuccess` | `(data: ActivityRowType<A>[]) => void` | — | Success callback |
+
+### Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `rows` | `ActivityRowType<A>[]` | Activity instance records (system + entity fields) |
+| `totalItems` | `number` | Total count (from metrics endpoint) |
+| `isLoading` | `boolean` | Initial load in progress |
+| `isFetching` | `boolean` | Any fetch in progress (including refetch) |
+| `error` | `Error \| null` | Fetch error |
+| `refetch` | `() => Promise<...>` | Refetch both list and metrics |
+
+---
+
 ## Use Case: Employee Creating Leave
 
 ### Step 1 — Start the workflow
@@ -542,18 +642,63 @@ function LeaveRequestPage() {
 
 ## Use Case: Manager Approving Leave
 
-### Step 1 — List in-progress items
+### Step 1 — List in-progress items with useActivityTable
 
-```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();
+function ManagerApprovalPage() {
+  const activity = useMemo(() => new SimpleLeaveProcess().managerApprovalActivity(), []);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
 
-const result = await activity.getInProgressList();
+  const { rows, totalItems, isLoading, error, refetch } = useActivityTable(activity, {
+    status: ActivityTableStatus.InProgress,
+  });
 
-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>Action</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row._id}>
+              <td>{row._id}</td>
+              <td>{row.Status}</td>
+              <td>{row.AssignedTo._name}</td>
+              <td>
+                <button onClick={() => setSelectedId(row._id)}>Review</button>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
 }
 ```
 
@@ -703,7 +848,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 user (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.10",
+  "version": "2.0.12",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",

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

@@ -98,6 +98,8 @@ export function useForm<B extends BaseBdo<any, any, any>>(
   useEffect(() => {
     if (schema?.BDOBlob) {
       bdo.loadMetadata(schema.BDOBlob);
+    } else if (schema?.MetaBlob) {
+      bdo.loadMetadata(schema.MetaBlob);
     }
   }, [schema, bdo]);
 

package/sdk/workflow/components/useActivityTable/index.ts

@@ -0,0 +1,8 @@
+export { useActivityTable } from './useActivityTable';
+export { ActivityTableStatus } from './types';
+export type {
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityTableStatusType,
+  ActivityRowType,
+} from './types';

package/sdk/workflow/components/useActivityTable/types.ts

@@ -0,0 +1,67 @@
+// ============================================================
+// TYPE DEFINITIONS FOR useActivityTable HOOK
+// ============================================================
+
+import type { Activity } from '../../Activity';
+import type { ActivityInstanceFieldsType } from '../../types';
+import type { ExtractActivityEntity } from '../useActivityForm/types';
+import type { ListResponseType } from '../../../types/common';
+
+/**
+ * Activity table status — determines which API to call
+ */
+export const ActivityTableStatus = {
+  InProgress: 'inprogress',
+  Completed: 'completed',
+} as const;
+
+export type ActivityTableStatusType =
+  (typeof ActivityTableStatus)[keyof typeof ActivityTableStatus];
+
+/**
+ * Row type for activity table data.
+ * Combines activity instance system fields with entity-specific fields.
+ *
+ * For a ManagerApprovalActivity with { ManagerApproved, ManagerReason }:
+ * ActivityRowType resolves to:
+ *   {
+ *     // System fields (ActivityInstanceFieldsType)
+ *     _id: string;
+ *     Status: "InProgress" | "Completed";
+ *     AssignedTo: UserRefType;
+ *     CompletedAt: string;
+ *     // Entity fields
+ *     ManagerApproved: boolean;
+ *     ManagerReason: string;
+ *   }
+ */
+export type ActivityRowType<A extends Activity<any, any, any>> =
+  ActivityInstanceFieldsType & ExtractActivityEntity<A>;
+
+export interface UseActivityTableOptionsType<
+  A extends Activity<any, any, any>,
+> {
+  /** Which activity instances to fetch */
+  status: ActivityTableStatusType;
+  /** Error callback */
+  onError?: (error: Error) => void;
+  /** Success callback with row data */
+  onSuccess?: (data: ActivityRowType<A>[]) => void;
+}
+
+export interface UseActivityTableReturnType<
+  A extends Activity<any, any, any>,
+> {
+  /** Activity instance records (system fields + entity fields) */
+  rows: ActivityRowType<A>[];
+  /** Total count from metrics endpoint */
+  totalItems: number;
+  /** Initial load in progress */
+  isLoading: boolean;
+  /** Any fetch in progress (including refetch) */
+  isFetching: boolean;
+  /** Fetch error */
+  error: Error | null;
+  /** Refetch both list and metrics */
+  refetch: () => Promise<ListResponseType<ActivityRowType<A>>>;
+}

package/sdk/workflow/components/useActivityTable/useActivityTable.ts

@@ -0,0 +1,145 @@
+// ============================================================
+// USE ACTIVITY TABLE HOOK
+// ============================================================
+// React hook for listing workflow activity instances.
+// Fetches data from getInProgressList() or getCompletedList()
+// and the corresponding metrics endpoint.
+
+import { useMemo, useCallback } from 'react';
+import { useQuery } from '@tanstack/react-query';
+
+import type { Activity } from '../../Activity';
+import type { ListResponseType } from '../../../types/common';
+import { toError } from '../../../utils/error-handling';
+
+import {
+  ActivityTableStatus,
+  type UseActivityTableOptionsType,
+  type UseActivityTableReturnType,
+  type ActivityRowType,
+} from './types';
+
+// ============================================================
+// MAIN HOOK
+// ============================================================
+
+export function useActivityTable<A extends Activity<any, any, any>>(
+  activity: A,
+  options: UseActivityTableOptionsType<A>,
+): UseActivityTableReturnType<A> {
+  const { status, onError, onSuccess } = options;
+
+  const { businessProcessId, activityId } = activity.meta;
+
+  // ============================================================
+  // LIST QUERY
+  // ============================================================
+
+  const {
+    data,
+    isLoading,
+    isFetching,
+    error,
+    refetch: queryRefetch,
+  } = useQuery({
+    queryKey: ['activity-table', businessProcessId, activityId, status],
+    queryFn: async (): Promise<ListResponseType<ActivityRowType<A>>> => {
+      try {
+        const response =
+          status === ActivityTableStatus.InProgress
+            ? await activity.getInProgressList()
+            : await activity.getCompletedList();
+
+        if (onSuccess) {
+          onSuccess(response.Data as ActivityRowType<A>[]);
+        }
+
+        return response as ListResponseType<ActivityRowType<A>>;
+      } catch (err) {
+        if (onError) {
+          onError(toError(err));
+        }
+        throw err;
+      }
+    },
+    staleTime: 0,
+    gcTime: 30 * 1000,
+  });
+
+  // ============================================================
+  // METRICS QUERY (count)
+  // ============================================================
+
+  const {
+    data: metricData,
+    isLoading: isMetricLoading,
+    isFetching: isMetricFetching,
+    error: metricError,
+    refetch: metricRefetch,
+  } = useQuery({
+    queryKey: [
+      'activity-table-count',
+      businessProcessId,
+      activityId,
+      status,
+    ],
+    queryFn: async () => {
+      try {
+        return status === ActivityTableStatus.InProgress
+          ? await activity.inProgressMetrics()
+          : await activity.completedMetrics();
+      } catch (err) {
+        if (onError) {
+          onError(toError(err));
+        }
+        throw err;
+      }
+    },
+    staleTime: 0,
+    gcTime: 30 * 1000,
+  });
+
+  // ============================================================
+  // COMPUTED VALUES
+  // ============================================================
+
+  const rows = useMemo(
+    () => (data?.Data || []) as ActivityRowType<A>[],
+    [data],
+  );
+
+  const totalItems = useMemo(
+    () => metricData?.Data[0]?.count__id ?? 0,
+    [metricData],
+  );
+
+  // ============================================================
+  // REFETCH
+  // ============================================================
+
+  const refetch = useCallback(async (): Promise<
+    ListResponseType<ActivityRowType<A>>
+  > => {
+    const [listResult] = await Promise.all([queryRefetch(), metricRefetch()]);
+    return (listResult.data || { Data: [] }) as ListResponseType<
+      ActivityRowType<A>
+    >;
+  }, [queryRefetch, metricRefetch]);
+
+  // ============================================================
+  // RETURN
+  // ============================================================
+
+  return {
+    rows,
+    totalItems,
+    isLoading: isLoading || isMetricLoading,
+    isFetching: isFetching || isMetricFetching,
+    error: error
+      ? toError(error)
+      : metricError
+        ? toError(metricError)
+        : null,
+    refetch,
+  };
+}

package/sdk/workflow/types.ts

@@ -13,9 +13,8 @@ import type {
   StringFieldType,
   SelectFieldType,
   DateTimeFieldType,
-  ReferenceFieldType,
+  UserFieldType,
 } from "../types/base-fields";
-import type { UserRefType } from "../types/base-fields";
 
 /**
  * Response from Workflow.start()
@@ -49,7 +48,7 @@ export interface ActivityProgressType {
 export type ActivityInstanceFieldsType = {
   _id: StringFieldType;
   Status: SelectFieldType<"InProgress" | "Completed">;
-  AssignedTo: ReferenceFieldType<UserRefType>;
+  AssignedTo: UserFieldType;
   CompletedAt: DateTimeFieldType;
 };
 

package/sdk/workflow.ts

@@ -23,3 +23,10 @@ export type {
   UseActivityFormOptions,
   UseActivityFormReturn,
 } from './workflow/components/useActivityForm';
+
+export { useActivityTable, ActivityTableStatus } from './workflow/components/useActivityTable';
+export type {
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityRowType,
+} from './workflow/components/useActivityTable';

package/sdk/workflow.types.ts

@@ -9,3 +9,10 @@ export type {
   ActivityProgressType,
   WorkflowStartResponseType,
 } from './workflow/types';
+
+export type {
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityTableStatusType,
+  ActivityRowType,
+} from './workflow/components/useActivityTable/types';