@ram_28/kf-ai-sdk 2.0.2 → 2.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",
@@ -107,6 +107,26 @@
         "default": "./dist/api.types.cjs"
       }
     },
+    "./workflow": {
+      "import": {
+        "types": "./dist/workflow.d.ts",
+        "default": "./dist/workflow.mjs"
+      },
+      "require": {
+        "types": "./dist/workflow.d.ts",
+        "default": "./dist/workflow.cjs"
+      }
+    },
+    "./workflow/types": {
+      "import": {
+        "types": "./dist/workflow.types.d.ts",
+        "default": "./dist/workflow.types.mjs"
+      },
+      "require": {
+        "types": "./dist/workflow.types.d.ts",
+        "default": "./dist/workflow.types.cjs"
+      }
+    },
     "./utils": {
       "import": {
         "types": "./dist/utils.d.ts",

package/sdk/api/client.ts

@@ -30,7 +30,9 @@ export interface ResourceClientType<T = any> {
   get(id: string): Promise<T>;
 
   /** Create new record */
-  create(data: Partial<T> & { _id?: string }): Promise<CreateUpdateResponseType>;
+  create(
+    data: Partial<T> & { _id?: string },
+  ): Promise<CreateUpdateResponseType>;
 
   /** Update existing record */
   update(id: string, data: Partial<T>): Promise<CreateUpdateResponseType>;
@@ -72,7 +74,7 @@ export interface ResourceClientType<T = any> {
    * Used in interactive mode for create operations
    */
   draftInteraction(
-    data: Partial<T> & { _id?: string }
+    data: Partial<T> & { _id?: string },
   ): Promise<DraftResponseType & { _id: string }>;
 
   // ============================================================
@@ -111,7 +113,7 @@ export interface ResourceClientType<T = any> {
    */
   fetchField<TResult = FetchFieldOptionType>(
     instanceId: string,
-    fieldId: string
+    fieldId: string,
   ): Promise<TResult[]>;
 }
 
@@ -162,30 +164,27 @@ export function getApiBaseUrl(): string {
 }
 
 /**
- * Parse error response body and throw an Error with the server's message.
- */
-async function throwApiError(response: Response, context: string): Promise<never> {
-  let errorBody: any;
-  try { errorBody = await response.json(); } catch {}
-  const message = errorBody?.error || errorBody?.message || response.statusText;
-  throw new Error(`${context}: ${message}`);
-}
-
-/**
- * Create a resource client for the specified Business Object
- * @param bo_id - Business Object identifier (e.g., "user", "leave", "vendor")
+ * Create a resource client for a given base path.
+ * This is the shared implementation used by both `api()` and workflow owner methods.
+ * @param basePath - URL path segment (e.g., "/api/app/user" or "/api/app/process/leave_bp/vendor_ado")
  * @returns Resource client with CRUD operations matching API spec
  */
-export function api<T = any>(bo_id: string): ResourceClientType<T> {
+export function createResourceClient<T = any>(
+  basePath: string,
+): ResourceClientType<T> {
+  const baseUrl = apiConfig.baseUrl;
+
   return {
     async get(id: string): Promise<T> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/read`, {
+      const response = await fetch(`${baseUrl}${basePath}/${id}/read`, {
         method: "GET",
         headers: getDefaultHeaders(),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to get ${bo_id} ${id}`);
+        throw new Error(
+          `Failed to get ${basePath} ${id}: ${response.statusText}`,
+        );
       }
 
       const responseData: ReadResponseType<T> = await response.json();
@@ -193,43 +192,50 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     },
 
     async create(
-      data: Partial<T> & { _id?: string }
+      data: Partial<T> & { _id?: string },
     ): Promise<CreateUpdateResponseType> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/create`, {
+      const response = await fetch(`${baseUrl}${basePath}/create`, {
         method: "POST",
         headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to create ${bo_id}`);
+        throw new Error(`Failed to create ${basePath}: ${response.statusText}`);
       }
 
       return response.json();
     },
 
-    async update(id: string, data: Partial<T>): Promise<CreateUpdateResponseType> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/update`, {
+    async update(
+      id: string,
+      data: Partial<T>,
+    ): Promise<CreateUpdateResponseType> {
+      const response = await fetch(`${baseUrl}${basePath}/${id}/update`, {
         method: "POST",
         headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to update ${bo_id} ${id}`);
+        throw new Error(
+          `Failed to update ${basePath} ${id}: ${response.statusText}`,
+        );
       }
 
       return response.json();
     },
 
     async delete(id: string): Promise<DeleteResponseType> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/delete`, {
+      const response = await fetch(`${baseUrl}${basePath}/${id}/delete`, {
         method: "DELETE",
         headers: getDefaultHeaders(),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to delete ${bo_id} ${id}`);
+        throw new Error(
+          `Failed to delete ${basePath} ${id}: ${response.statusText}`,
+        );
       }
 
       return response.json();
@@ -241,14 +247,14 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
         ...options,
       };
 
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/list`, {
+      const response = await fetch(`${baseUrl}${basePath}/list`, {
         method: "POST",
         headers: getDefaultHeaders(),
         body: JSON.stringify(requestBody),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to list ${bo_id}`);
+        throw new Error(`Failed to list ${basePath}: ${response.statusText}`);
       }
 
       const responseData: ListResponseType<T> = await response.json();
@@ -264,14 +270,14 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
         ...(options?.Filter && { Filter: options.Filter }),
       };
 
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/metric`, {
+      const response = await fetch(`${baseUrl}${basePath}/metric`, {
         method: "POST",
         headers: getDefaultHeaders(),
         body: JSON.stringify(requestBody),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to count ${bo_id}`);
+        throw new Error(`Failed to count ${basePath}: ${response.statusText}`);
       }
 
       const result = await response.json();
@@ -285,14 +291,16 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     // ============================================================
 
     async draft(data: Partial<T>): Promise<DraftResponseType> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/draft`, {
+      const response = await fetch(`${baseUrl}${basePath}/draft`, {
         method: "POST",
         headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to create draft for ${bo_id}`);
+        throw new Error(
+          `Failed to create draft for ${basePath}: ${response.statusText}`,
+        );
       }
 
       return response.json();
@@ -300,46 +308,52 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
 
     async draftUpdate(
       id: string,
-      data: Partial<T>
+      data: Partial<T>,
     ): Promise<CreateUpdateResponseType> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/draft`, {
+      const response = await fetch(`${baseUrl}${basePath}/${id}/draft`, {
         method: "POST",
         headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to update draft for ${bo_id} ${id}`);
+        throw new Error(
+          `Failed to update draft for ${basePath} ${id}: ${response.statusText}`,
+        );
       }
 
       return response.json();
     },
 
     async draftPatch(id: string, data: Partial<T>): Promise<DraftResponseType> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/draft`, {
+      const response = await fetch(`${baseUrl}${basePath}/${id}/draft`, {
         method: "PATCH",
         headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to patch draft for ${bo_id} ${id}`);
+        throw new Error(
+          `Failed to patch draft for ${basePath} ${id}: ${response.statusText}`,
+        );
       }
 
       return response.json();
     },
 
     async draftInteraction(
-      data: Partial<T> & { _id?: string }
+      data: Partial<T> & { _id?: string },
     ): Promise<DraftResponseType & { _id: string }> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/draft`, {
+      const response = await fetch(`${baseUrl}${basePath}/draft`, {
         method: "PATCH",
         headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to create interactive draft for ${bo_id}`);
+        throw new Error(
+          `Failed to create interactive draft for ${basePath}: ${response.statusText}`,
+        );
       }
 
       const json = await response.json();
@@ -356,40 +370,46 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     // ============================================================
 
     async metric(
-      options: Omit<MetricOptionsType, "Type">
+      options: Omit<MetricOptionsType, "Type">,
     ): Promise<MetricResponseType> {
       const requestBody: MetricOptionsType = {
         Type: "Metric",
         ...options,
       };
 
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/metric`, {
+      const response = await fetch(`${baseUrl}${basePath}/metric`, {
         method: "POST",
         headers: getDefaultHeaders(),
         body: JSON.stringify(requestBody),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to get metrics for ${bo_id}`);
+        throw new Error(
+          `Failed to get metrics for ${basePath}: ${response.statusText}`,
+        );
       }
 
       return response.json();
     },
 
-    async pivot(options: Omit<PivotOptionsType, "Type">): Promise<PivotResponseType> {
+    async pivot(
+      options: Omit<PivotOptionsType, "Type">,
+    ): Promise<PivotResponseType> {
       const requestBody: PivotOptionsType = {
         Type: "Pivot",
         ...options,
       };
 
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/pivot`, {
+      const response = await fetch(`${baseUrl}${basePath}/pivot`, {
         method: "POST",
         headers: getDefaultHeaders(),
         body: JSON.stringify(requestBody),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to get pivot data for ${bo_id}`);
+        throw new Error(
+          `Failed to get pivot data for ${basePath}: ${response.statusText}`,
+        );
       }
 
       return response.json();
@@ -400,13 +420,15 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     // ============================================================
 
     async fields(): Promise<FieldsResponseType> {
-      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/fields`, {
+      const response = await fetch(`${baseUrl}${basePath}/fields`, {
         method: "GET",
         headers: getDefaultHeaders(),
       });
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to get fields for ${bo_id}`);
+        throw new Error(
+          `Failed to get fields for ${basePath}: ${response.statusText}`,
+        );
       }
 
       return response.json();
@@ -414,18 +436,20 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
 
     async fetchField<TResult = FetchFieldOptionType>(
       instanceId: string,
-      fieldId: string
+      fieldId: string,
     ): Promise<TResult[]> {
       const response = await fetch(
-        `${getApiBaseUrl()}/api/app/${bo_id}/${instanceId}/field/${fieldId}/fetch`,
+        `${baseUrl}${basePath}/${instanceId}/field/${fieldId}/fetch`,
         {
           method: "GET",
           headers: getDefaultHeaders(),
-        }
+        },
       );
 
       if (!response.ok) {
-        await throwApiError(response, `Failed to fetch field ${fieldId} for ${bo_id}`);
+        throw new Error(
+          `Failed to fetch field ${fieldId} for ${basePath}: ${response.statusText}`,
+        );
       }
 
       const responseData: { Data: TResult[] } = await response.json();
@@ -433,3 +457,12 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     },
   };
 }
+
+/**
+ * Create a resource client for the specified Business Object
+ * @param bo_id - Business Object identifier (e.g., "user", "leave", "vendor")
+ * @returns Resource client with CRUD operations matching API spec
+ */
+export function api<T = any>(bo_id: string): ResourceClientType<T> {
+  return createResourceClient<T>(`/api/app/${bo_id}`);
+}

package/sdk/api/index.ts

@@ -1,6 +1,7 @@
 // Main API client
 export {
   api,
+  createResourceClient,
   setApiBaseUrl,
   setDefaultHeaders,
   getDefaultHeaders,

package/sdk/api/metadata.ts

@@ -43,7 +43,7 @@ export async function getBdoSchema(metaId: string): Promise<BackendSchemaType> {
 
     if (!response.ok) {
       throw new Error(
-        `Failed to fetch schema for ${metaId}: ${response.statusText}`
+        `Failed to fetch schema for ${metaId}: ${response.statusText}`,
       );
     }
 
@@ -58,7 +58,7 @@ export async function getBdoSchema(metaId: string): Promise<BackendSchemaType> {
   } catch (error) {
     console.error(`Schema fetch error for ${metaId}:`, error);
     throw new Error(
-      `Failed to load BDO schema: ${error instanceof Error ? error.message : "Unknown error"}`
+      `Failed to load BDO schema: ${error instanceof Error ? error.message : "Unknown error"}`,
     );
   }
 }
@@ -83,7 +83,7 @@ export interface MetadataItemType {
  * @returns Promise resolving to list of metadata items
  */
 export async function listMetadata(
-  options?: ListOptionsType
+  options?: ListOptionsType,
 ): Promise<ListResponseType<MetadataItemType>> {
   try {
     const baseUrl = getApiBaseUrl();
@@ -111,7 +111,7 @@ export async function listMetadata(
   } catch (error) {
     console.error("Metadata list error:", error);
     throw new Error(
-      `Failed to list metadata: ${error instanceof Error ? error.message : "Unknown error"}`
+      `Failed to list metadata: ${error instanceof Error ? error.message : "Unknown error"}`,
     );
   }
 }

package/sdk/bdo/core/BaseBdo.ts

@@ -258,6 +258,16 @@ export abstract class BaseBdo<
     return new Item<TEditable & TReadonly>(this, (data ?? {}) as Partial<TEditable & TReadonly>) as ItemType<TEditable, TReadonly>;
   }
 
+  /**
+   * Commit an update draft - finalize changes on an existing record
+   */
+  protected async draftUpdate(
+    id: string,
+    data: Partial<TEditable>
+  ): Promise<CreateUpdateResponseType> {
+    return api<TEntity>(this.meta._id).draftUpdate(id, data as Partial<TEntity>);
+  }
+
   /**
    * Patch an existing draft - compute fields during editing
    */

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

@@ -15,4 +15,5 @@ export type {
   CreatableBdo,
   UpdatableBdo,
   FormBdo,
+  InteractiveCreatableBdo,
 } from "./types";

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

@@ -55,6 +55,12 @@ export interface UpdatableBdo<TEditable = any> extends BaseBdoShape {
 /** BDO that supports both create and update */
 export type FormBdo<TEditable = any> = CreatableBdo<TEditable> & UpdatableBdo<TEditable>;
 
+/** BDO that supports interactive create (draft interaction during create) */
+export interface InteractiveCreatableBdo<TEditable = any> extends CreatableBdo<TEditable> {
+  draftInteraction(data: Partial<TEditable>): Promise<any>;
+  draft(data: Partial<TEditable>): Promise<any>;
+}
+
 // ============================================================
 // HANDLE SUBMIT TYPE
 // ============================================================
@@ -92,6 +98,8 @@ interface UseFormCreateOptionsType<B extends BaseBdo<any, any, any>> {
   recordId?: undefined;
   defaultValues?: Partial<ExtractEditableType<B>>;
   mode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
+  interactionMode?: "interactive" | "non-interactive";
+  /** @deprecated Use interactionMode instead */
   enableDraft?: boolean;
   enableConstraintValidation?: boolean;
   enableExpressionValidation?: boolean;
@@ -104,6 +112,8 @@ interface UseFormUpdateOptionsType<B extends BaseBdo<any, any, any>> {
   recordId: string;
   defaultValues?: Partial<ExtractEditableType<B>>;
   mode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
+  interactionMode?: "interactive" | "non-interactive";
+  /** @deprecated Use interactionMode instead */
   enableDraft?: boolean;
   enableConstraintValidation?: boolean;
   enableExpressionValidation?: boolean;
@@ -116,6 +126,8 @@ interface UseFormAutoOptionsType<B extends BaseBdo<any, any, any>> {
   recordId?: string;
   defaultValues?: Partial<ExtractEditableType<B>>;
   mode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
+  interactionMode?: "interactive" | "non-interactive";
+  /** @deprecated Use interactionMode instead */
   enableDraft?: boolean;
   enableConstraintValidation?: boolean;
   enableExpressionValidation?: boolean;
@@ -223,7 +235,9 @@ export interface UseFormReturnType<B extends BaseBdo<any, any, any>> {
   // Error
   loadError: Error | null;
 
-  // Draft (optional)
-  draftId?: string;
-  isCreatingDraft?: boolean;
+  // Draft / Interactive mode
+  draftId: string | undefined;
+  isInitializingDraft: boolean;
+  isInteracting: boolean;
+  interactionError: Error | null;
 }