@ram_28/kf-ai-sdk 2.0.3 → 2.0.5

package/sdk/workflow/Activity.ts

@@ -10,9 +10,11 @@
 //   - Typed field instances as class properties
 //
 // Methods:
-//   activity.getInstanceList(options)  // list activity instances
-//   activity.instanceMetrics(options)  // get aggregated metrics
-//   activity.getInstance(instanceId)   // get typed ActivityInstance
+//   activity.getInProgressList(options)   // list in-progress activity instances
+//   activity.getCompletedList(options)    // list completed activity instances
+//   activity.inProgressMetrics(options)   // get in-progress aggregated metrics
+//   activity.completedMetrics(options)    // get completed aggregated metrics
+//   activity.getInstance(instanceId)      // get typed ActivityInstance
 
 import { Workflow } from "./client";
 import { createActivityInstance } from "./ActivityInstance";
@@ -58,7 +60,8 @@ import { BaseField } from "../bdo/fields/BaseField";
  * }
  *
  * const activity = new EmployeeInputActivity();
- * const items = await activity.getInstanceList({ Page: 1, PageSize: 10 });
+ * const inProgress = await activity.getInProgressList({ Page: 1, PageSize: 10 });
+ * const completed = await activity.getCompletedList({ Page: 1, PageSize: 10 });
  * const instance = await activity.getInstance("inst_123");
  * instance.StartDate.get();  // typed value
  * instance.StartDate.set("2026-03-01");
@@ -122,21 +125,39 @@ export abstract class Activity<
   // ============================================================
 
   /**
-   * List activity instances with optional filtering/pagination.
+   * List in-progress activity instances with optional filtering/pagination.
    */
-  async getInstanceList(
+  async getInProgressList(
     options?: ListOptionsType,
   ): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
-    return this._ops().list(options);
+    return this._ops().inProgressList(options);
   }
 
   /**
-   * Get aggregated metrics for activity instances.
+   * List completed activity instances with optional filtering/pagination.
    */
-  async instanceMetrics(
+  async getCompletedList(
+    options?: ListOptionsType,
+  ): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
+    return this._ops().completedList(options);
+  }
+
+  /**
+   * Get aggregated metrics for in-progress activity instances.
+   */
+  async inProgressMetrics(
+    options: Omit<MetricOptionsType, "Type">,
+  ): Promise<MetricResponseType> {
+    return this._ops().inProgressMetric(options);
+  }
+
+  /**
+   * Get aggregated metrics for completed activity instances.
+   */
+  async completedMetrics(
     options: Omit<MetricOptionsType, "Type">,
   ): Promise<MetricResponseType> {
-    return this._ops().metric(options);
+    return this._ops().completedMetric(options);
   }
 
   /**

package/sdk/workflow/ActivityInstance.ts

@@ -172,7 +172,7 @@ export class ActivityInstance<
   /**
    * Get activity progress — calls ActivityOperations.progress()
    */
-  async progress(): Promise<ActivityProgressType> {
+  async progress(): Promise<ActivityProgressType[]> {
     return this._ops.progress(this._id);
   }
 

package/sdk/workflow/client.ts

@@ -41,9 +41,14 @@ import type {
  * await act.draftEnd("inst_123", data);
  * await act.complete("inst_123");
  *
- * // List operations
- * await act.list({ Page: 1, PageSize: 10 });
- * await act.metric({ Metric: [...] });
+ * // List operations (by status)
+ * await act.inProgressList({ Page: 1, PageSize: 10 });
+ * await act.completedList({ Page: 1, PageSize: 10 });
+ * await act.inProgressMetric({ Metric: [...] });
+ * await act.completedMetric({ Metric: [...] });
+ *
+ * // Global process progress
+ * const progress = await wf.progress();
  * ```
  */
 export class Workflow<T = any> {
@@ -72,6 +77,26 @@ export class Workflow<T = any> {
     return response.json();
   }
 
+  /**
+   * Get global progress across the entire business process.
+   * Returns a list of progress entries for each stage/activity.
+   */
+  async progress(): Promise<ActivityProgressType[]> {
+    const response = await fetch(
+      `${getApiBaseUrl()}/api/app/process/${this.bp_id}/progress`,
+      {
+        method: "GET",
+        headers: getDefaultHeaders(),
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`Failed to get process progress: ${response.statusText}`);
+    }
+
+    return response.json();
+  }
+
   /**
    * Get all operations for a specific activity
    * @param activity_id - Activity identifier
@@ -82,39 +107,77 @@ export class Workflow<T = any> {
     return {
       // ── List-level ────────────────────────────────────────────
 
-      async list(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
+      async inProgressList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
         const requestBody: ListOptionsType = {
           Type: "List",
           ...options,
         };
 
-        const response = await fetch(`${getApiBaseUrl()}${base}/list`, {
+        const response = await fetch(`${getApiBaseUrl()}${base}/inprogress/list`, {
+          method: "POST",
+          headers: getDefaultHeaders(),
+          body: JSON.stringify(requestBody),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Failed to list in-progress activities: ${response.statusText}`);
+        }
+
+        return response.json();
+      },
+
+      async completedList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>> {
+        const requestBody: ListOptionsType = {
+          Type: "List",
+          ...options,
+        };
+
+        const response = await fetch(`${getApiBaseUrl()}${base}/completed/list`, {
+          method: "POST",
+          headers: getDefaultHeaders(),
+          body: JSON.stringify(requestBody),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Failed to list completed activities: ${response.statusText}`);
+        }
+
+        return response.json();
+      },
+
+      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 list activities: ${response.statusText}`);
+          throw new Error(`Failed to get in-progress activity metrics: ${response.statusText}`);
         }
 
         return response.json();
       },
 
-      async metric(options: Omit<MetricOptionsType, "Type">): Promise<MetricResponseType> {
+      async completedMetric(options: Omit<MetricOptionsType, "Type">): Promise<MetricResponseType> {
         const requestBody: MetricOptionsType = {
           Type: "Metric",
           ...options,
         };
 
-        const response = await fetch(`${getApiBaseUrl()}${base}/metric`, {
+        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 activity metrics: ${response.statusText}`);
+          throw new Error(`Failed to get completed activity metrics: ${response.statusText}`);
         }
 
         return response.json();
@@ -191,7 +254,7 @@ export class Workflow<T = any> {
         return response.json();
       },
 
-      async progress(instanceId: string): Promise<ActivityProgressType> {
+      async progress(instanceId: string): Promise<ActivityProgressType[]> {
         const response = await fetch(`${getApiBaseUrl()}${base}/${instanceId}/progress`, {
           method: "GET",
           headers: getDefaultHeaders(),

package/sdk/workflow/components/useActivityForm/createActivityItemProxy.ts

@@ -80,6 +80,8 @@ export function createActivityItemProxy<A extends Activity<any, any, any>>(
             defaultValue: bdoField?.defaultValue,
             meta: fieldMeta,
             get: () => form.getValues(prop as Path<FieldValues>),
+            getOrDefault: (fallback: unknown) =>
+              form.getValues(prop as Path<FieldValues>) ?? fallback,
             set: (value: unknown) => {
               form.setValue(prop as Path<FieldValues>, value as any, {
                 shouldDirty: true,
@@ -99,6 +101,8 @@ export function createActivityItemProxy<A extends Activity<any, any, any>>(
           defaultValue: bdoField?.defaultValue,
           meta: fieldMeta,
           get: () => form.getValues(prop as Path<FieldValues>),
+          getOrDefault: (fallback: unknown) =>
+            form.getValues(prop as Path<FieldValues>) ?? fallback,
           validate,
         };
         return accessor;

package/sdk/workflow/types.ts

@@ -28,12 +28,19 @@ export interface WorkflowStartResponseType {
 }
 
 /**
- * Response from the activity progress endpoint
+ * Response from the activity progress endpoint.
+ * Both global (Workflow.progress()) and instance-level (ActivityInstance.progress())
+ * return ActivityProgressType[].
  */
 export 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;
 }
 
 /**
@@ -56,11 +63,17 @@ export type ActivityInstanceFieldsType = {
 export interface ActivityOperations<T> {
   // ── List-level ──────────────────────────────────────────────
 
-  /** List activity instances (POST .../list) */
-  list(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>>;
+  /** List in-progress activity instances (POST .../inprogress/list) */
+  inProgressList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>>;
 
-  /** Get activity metrics (POST .../metric) */
-  metric(options: Omit<MetricOptionsType, "Type">): Promise<MetricResponseType>;
+  /** List completed activity instances (POST .../completed/list) */
+  completedList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & T>>;
+
+  /** Get in-progress activity metrics (POST .../inprogress/metric) */
+  inProgressMetric(options: Omit<MetricOptionsType, "Type">): Promise<MetricResponseType>;
+
+  /** Get completed activity metrics (POST .../completed/metric) */
+  completedMetric(options: Omit<MetricOptionsType, "Type">): Promise<MetricResponseType>;
 
   // ── Instance-level ──────────────────────────────────────────
 
@@ -80,5 +93,5 @@ export interface ActivityOperations<T> {
   complete(instanceId: string): Promise<CreateUpdateResponseType>;
 
   /** Get activity progress (GET .../progress) */
-  progress(instanceId: string): Promise<ActivityProgressType>;
+  progress(instanceId: string): Promise<ActivityProgressType[]>;
 }

package/dist/components/hooks/useForm/useDraftInteraction.d.ts

@@ -1,26 +0,0 @@
-import type { UseFormReturn, FieldValues } from "react-hook-form";
-import type { BaseField } from "../../../bdo/fields/BaseField";
-import type { InteractiveCreatableBdo } from "./types";
-interface UseDraftInteractionOptions {
-    /** The BDO instance — must expose interactive draft methods */
-    bdo: InteractiveCreatableBdo;
-    /** RHF form instance */
-    form: UseFormReturn<FieldValues>;
-    /** RHF validation mode */
-    mode: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
-    /** BDO field definitions (for determining dirty fields) */
-    fields: Record<string, BaseField<unknown>>;
-    /** Whether interactive mode is enabled */
-    enabled: boolean;
-}
-interface UseDraftInteractionReturn {
-    draftId: string | undefined;
-    isInitializingDraft: boolean;
-    isInteracting: boolean;
-    interactionError: Error | null;
-    triggerInteraction: () => void;
-    commitDraft: (dirtyData: Record<string, unknown>) => Promise<unknown>;
-}
-export declare function useDraftInteraction(options: UseDraftInteractionOptions): UseDraftInteractionReturn;
-export {};
-//# sourceMappingURL=useDraftInteraction.d.ts.map

package/dist/components/hooks/useForm/useDraftInteraction.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useDraftInteraction.d.ts","sourceRoot":"","sources":["../../../../sdk/components/hooks/useForm/useDraftInteraction.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAMvD,UAAU,0BAA0B;IAClC,+DAA+D;IAC/D,GAAG,EAAE,uBAAuB,CAAC;IAC7B,wBAAwB;IACxB,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACjC,0BAA0B;IAC1B,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,CAAC;IAC/D,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3C,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,UAAU,yBAAyB;IACjC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,KAAK,GAAG,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvE;AAYD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,yBAAyB,CA+M3B"}

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

@@ -1,251 +0,0 @@
-import { useState, useEffect, useCallback, useRef } from "react";
-import type { UseFormReturn, FieldValues } from "react-hook-form";
-import type { BaseField } from "../../../bdo/fields/BaseField";
-import type { InteractiveCreatableBdo } from "./types";
-
-// ============================================================
-// TYPES
-// ============================================================
-
-interface UseDraftInteractionOptions {
-  /** The BDO instance — must expose interactive draft methods */
-  bdo: InteractiveCreatableBdo;
-  /** RHF form instance */
-  form: UseFormReturn<FieldValues>;
-  /** RHF validation mode */
-  mode: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
-  /** BDO field definitions (for determining dirty fields) */
-  fields: Record<string, BaseField<unknown>>;
-  /** Whether interactive mode is enabled */
-  enabled: boolean;
-}
-
-interface UseDraftInteractionReturn {
-  draftId: string | undefined;
-  isInitializingDraft: boolean;
-  isInteracting: boolean;
-  interactionError: Error | null;
-  triggerInteraction: () => void;
-  commitDraft: (dirtyData: Record<string, unknown>) => Promise<unknown>;
-}
-
-// ============================================================
-// DEBOUNCE DELAY
-// ============================================================
-
-const DEBOUNCE_MS = 300;
-
-// ============================================================
-// HOOK
-// ============================================================
-
-export function useDraftInteraction(
-  options: UseDraftInteractionOptions,
-): UseDraftInteractionReturn {
-  const { bdo, form, mode, fields, enabled } = options;
-
-  // ============================================================
-  // STATE
-  // ============================================================
-
-  const [draftId, setDraftId] = useState<string | undefined>(undefined);
-  const [isInitializingDraft, setIsInitializingDraft] = useState(false);
-  const [isInteracting, setIsInteracting] = useState(false);
-  const [interactionError, setInteractionError] = useState<Error | null>(null);
-
-  // ============================================================
-  // REFS (for concurrency control & loop prevention)
-  // ============================================================
-
-  /** Tracks the latest interaction call — stale responses are discarded */
-  const interactionCounterRef = useRef(0);
-
-  /** Prevents re-trigger when applying computed values via setValue */
-  const isApplyingComputedRef = useRef(false);
-
-  /** Debounce timer for onChange mode */
-  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  /** AbortController for cleanup on unmount */
-  const abortControllerRef = useRef<AbortController | null>(null);
-
-  // ============================================================
-  // DRAFT INITIALIZATION (Create mode only)
-  // ============================================================
-
-  useEffect(() => {
-    if (!enabled) return;
-
-    let cancelled = false;
-    setIsInitializingDraft(true);
-
-    const controller = new AbortController();
-    abortControllerRef.current = controller;
-
-    bdo
-      .draftInteraction({})
-      .then((response) => {
-        if (cancelled || controller.signal.aborted) return;
-        const id = response._id;
-        setDraftId(id);
-        // Set _id into form without marking dirty
-        form.setValue("_id" as any, id, { shouldDirty: false });
-        setInteractionError(null);
-      })
-      .catch((error) => {
-        if (cancelled || controller.signal.aborted) return;
-        setInteractionError(error instanceof Error ? error : new Error(String(error)));
-      })
-      .finally(() => {
-        if (!cancelled) setIsInitializingDraft(false);
-      });
-
-    return () => {
-      cancelled = true;
-      controller.abort();
-    };
-  }, [enabled, bdo, form]);
-
-  // ============================================================
-  // CORE INTERACTION LOGIC
-  // ============================================================
-
-  const executeInteraction = useCallback(async () => {
-    if (!enabled || !draftId) return;
-    if (isApplyingComputedRef.current) return;
-
-    // Build payload from dirty fields
-    const dirtyFields = form.formState.dirtyFields;
-    const allValues = form.getValues();
-    const payload: Record<string, unknown> = {};
-
-    for (const [key, isDirty] of Object.entries(dirtyFields)) {
-      if (isDirty && fields[key] && !fields[key].readOnly) {
-        payload[key] = allValues[key];
-      }
-    }
-
-    // Skip if nothing changed
-    if (Object.keys(payload).length === 0) return;
-
-    // Increment counter for concurrency control
-    const currentCounter = ++interactionCounterRef.current;
-
-    setIsInteracting(true);
-
-    try {
-      const response = await bdo.draftInteraction({
-        _id: draftId,
-        ...payload,
-      } as any);
-
-      // Only apply if this is still the latest interaction
-      if (currentCounter !== interactionCounterRef.current) return;
-
-      // Apply computed values back to form
-      isApplyingComputedRef.current = true;
-      try {
-        for (const [key, value] of Object.entries(response)) {
-          // Skip _id and fields the user has dirty (don't overwrite user input)
-          if (key === "_id") continue;
-          if (dirtyFields[key]) continue;
-
-          form.setValue(key as any, value, {
-            shouldDirty: false,
-            shouldValidate: false,
-          });
-        }
-      } finally {
-        // Reset flag after React settles
-        // Using setTimeout(0) ensures setValue batch is complete
-        setTimeout(() => {
-          isApplyingComputedRef.current = false;
-        }, 0);
-      }
-
-      setInteractionError(null);
-    } catch (error) {
-      // Only set error if this is still the latest interaction
-      if (currentCounter !== interactionCounterRef.current) return;
-      setInteractionError(error instanceof Error ? error : new Error(String(error)));
-    } finally {
-      if (currentCounter === interactionCounterRef.current) {
-        setIsInteracting(false);
-      }
-    }
-  }, [enabled, draftId, form, fields, bdo]);
-
-  // ============================================================
-  // TRIGGER INTERACTION (with optional debounce)
-  // ============================================================
-
-  const triggerInteraction = useCallback(() => {
-    if (!enabled) return;
-
-    // For onChange/all modes, debounce the interaction
-    if (mode === "onChange" || mode === "all") {
-      if (debounceTimerRef.current) {
-        clearTimeout(debounceTimerRef.current);
-      }
-      debounceTimerRef.current = setTimeout(() => {
-        executeInteraction();
-      }, DEBOUNCE_MS);
-    } else {
-      // For onBlur/onTouched/onSubmit, trigger immediately
-      executeInteraction();
-    }
-  }, [enabled, mode, executeInteraction]);
-
-  // ============================================================
-  // COMMIT DRAFT (for handleSubmit)
-  // ============================================================
-
-  const commitDraft = useCallback(
-    async (dirtyData: Record<string, unknown>): Promise<unknown> => {
-      return bdo.draft({
-        _id: draftId,
-        ...dirtyData,
-      } as any);
-    },
-    [bdo, draftId],
-  );
-
-  // ============================================================
-  // CLEANUP
-  // ============================================================
-
-  useEffect(() => {
-    return () => {
-      if (debounceTimerRef.current) {
-        clearTimeout(debounceTimerRef.current);
-      }
-      abortControllerRef.current?.abort();
-    };
-  }, []);
-
-  // ============================================================
-  // DISABLED MODE (return no-ops)
-  // ============================================================
-
-  if (!enabled) {
-    return {
-      draftId: undefined,
-      isInitializingDraft: false,
-      isInteracting: false,
-      interactionError: null,
-      triggerInteraction: () => {},
-      commitDraft: async () => {
-        throw new Error("Draft interaction is not enabled");
-      },
-    };
-  }
-
-  return {
-    draftId,
-    isInitializingDraft,
-    isInteracting,
-    interactionError,
-    triggerInteraction,
-    commitDraft,
-  };
-}