@ram_28/kf-ai-sdk 2.0.20-beta.2 → 2.0.21

package/sdk/components/hooks/useActivityForm/useActivityForm.ts

@@ -10,12 +10,9 @@ import { useForm as useReactHookForm } from 'react-hook-form';
 import { useQuery } from '@tanstack/react-query';
 
 import type { Activity } from '../../../workflow/Activity';
-import type {
-  UseActivityFormOptions,
-  UseActivityFormReturn,
-  AllActivityFields,
-} from './types';
+import type { UseActivityFormOptions, UseActivityFormReturn } from './types';
 
+import type { CreateUpdateResponseType } from '../../../types/common';
 import { createActivityResolver } from './createActivityResolver';
 import { createActivityItemProxy } from './createActivityItemProxy';
 import {
@@ -300,13 +297,13 @@ export function useActivityForm<A extends Activity<any, any, any>>(
   );
 
   // ============================================================
-  // HANDLE SUBMIT — activity.update()
+  // HANDLE SUBMIT — activity.update() + activity.complete()
   // ============================================================
 
   const handleSubmit = useCallback(
     (
       onSuccess?: (
-        data: AllActivityFields<A>,
+        data: CreateUpdateResponseType,
         e?: React.BaseSyntheticEvent,
       ) => void | Promise<void>,
       onError?: (
@@ -319,7 +316,7 @@ export function useActivityForm<A extends Activity<any, any, any>>(
           setIsSubmitting(true);
 
           try {
-            // Only send dirty (changed) fields — matches useBDOForm update behavior
+            // Only send dirty (changed) fields — matches useBDOForm behavior
             // Use getValues() to capture Image/File values set via setValue()
             // that RHF resolver doesn't include in `data`
             const cleanedData: Record<string, unknown> = {};
@@ -339,7 +336,7 @@ export function useActivityForm<A extends Activity<any, any, any>>(
                 : value;
             }
 
-            // Save via activity.update()
+            // Send remaining dirty fields via update
             if (Object.keys(cleanedData).length > 0) {
               await activityRef.update(
                 activity_instance_id,
@@ -347,69 +344,10 @@ export function useActivityForm<A extends Activity<any, any, any>>(
               );
             }
 
-            await onSuccess?.(data as AllActivityFields<A>, event);
-          } catch (error) {
-            onError?.(toError(error), event);
-          } finally {
-            setIsSubmitting(false);
-          }
-        },
-        (errors, event) => {
-          onError?.(errors, event);
-        },
-      );
-    },
-    [rhf, activityRef, readonlyFieldNames, allFields, activity_instance_id],
-  ) as UseActivityFormReturn<A>['handleSubmit'];
-
-  // ============================================================
-  // HANDLE COMPLETE — activity.update() + activity.complete()
-  // ============================================================
-
-  const handleComplete = useCallback(
-    (
-      onSuccess?: (
-        data: AllActivityFields<A>,
-        e?: React.BaseSyntheticEvent,
-      ) => void | Promise<void>,
-      onError?: (
-        error: any,
-        e?: React.BaseSyntheticEvent,
-      ) => void | Promise<void>,
-    ) => {
-      return rhf.handleSubmit(
-        async (data, event) => {
-          setIsSubmitting(true);
-
-          try {
-            // Only send dirty (changed) fields — matches useBDOForm update behavior
-            // Use getValues() to capture Image/File values set via setValue()
-            // that RHF resolver doesn't include in `data`
-            const cleanedData: Record<string, unknown> = {};
-            const readonlySet = new Set(readonlyFieldNames);
-            const dirtyFields = rhf.formState.dirtyFields;
-            const allValues = rhf.getValues() as Record<string, unknown>;
-
-            for (const key of Object.keys(allValues)) {
-              if (readonlySet.has(key) || !dirtyFields[key]) continue;
-              const value =
-                allValues[key] !== undefined
-                  ? allValues[key]
-                  : (data as Record<string, unknown>)[key];
-              const field = allFields[key];
-              cleanedData[key] = field
-                ? coerceFieldValue(field, value)
-                : value;
-            }
+            // Complete the activity — advances the workflow
+            const result = await activityRef.complete(activity_instance_id);
 
-            if (Object.keys(cleanedData).length > 0) {
-              await activityRef.update(
-                activity_instance_id,
-                cleanedData as any,
-              );
-            }
-            await activityRef.complete(activity_instance_id);
-            await onSuccess?.(data as AllActivityFields<A>, event);
+            await onSuccess?.(result, event);
           } catch (error) {
             onError?.(toError(error), event);
           } finally {
@@ -422,7 +360,7 @@ export function useActivityForm<A extends Activity<any, any, any>>(
       );
     },
     [rhf, activityRef, readonlyFieldNames, allFields, activity_instance_id],
-  ) as UseActivityFormReturn<A>['handleComplete'];
+  ) as UseActivityFormReturn<A>['handleSubmit'];
 
   // ============================================================
   // CLEAR ERRORS
@@ -448,7 +386,6 @@ export function useActivityForm<A extends Activity<any, any, any>>(
     // Form methods
     register,
     handleSubmit,
-    handleComplete,
     watch: rhf.watch as any,
     setValue: rhf.setValue as any,
     getValues: rhf.getValues as any,

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

@@ -1,5 +1,4 @@
 import type { Activity } from '../../../workflow/Activity';
-import type { ActivityInstanceFieldsType } from '../../../workflow/types';
 import type { UseTableReturnType, PaginationStateType } from '../useTable/types';
 import type { UseFilterOptionsType } from '../useFilter/types';
 import type { SortType } from '../../../types/common';
@@ -16,12 +15,12 @@ export type ActivityTableStatusType =
   (typeof ActivityTableStatus)[keyof typeof ActivityTableStatus];
 
 /**
- * Row type for activity table data.
- * System fields and entity fields are flat at the top level.
+ * Row type — inferred from Activity's getInProgressList() return type.
+ * Resolves to ActivityInstanceType (proxy with .get()/.set()).
  */
 export type ActivityRowType<A extends Activity<any, any, any>> =
-  A extends Activity<infer E, any, any>
-    ? ActivityInstanceFieldsType & E
+  A extends { getInProgressList(opts?: any): Promise<(infer R)[]> }
+    ? R
     : never;
 
 export interface UseActivityTableOptionsType<

package/sdk/components/hooks/useActivityTable/useActivityTable.ts

@@ -13,22 +13,24 @@ export function useActivityTable<A extends Activity<any, any, any>>(
   const { activity, status, ...rest } = options;
   const { businessProcessId, activityId } = activity.meta;
 
-  const ops = useMemo(() => activity._getOps(), [activity]);
-
   const listFn = useMemo(
     () =>
       status === 'inprogress'
-        ? (opts: any) => ops.inProgressList(opts)
-        : (opts: any) => ops.completedList(opts),
-    [ops, status],
+        ? async (opts: any) => ({
+            Data: (await activity.getInProgressList(opts)) as ActivityRowType<A>[],
+          })
+        : async (opts: any) => ({
+            Data: (await activity.getCompletedList(opts)) as ActivityRowType<A>[],
+          }),
+    [activity, status],
   );
 
   const countFn = useMemo(
     () =>
       status === 'inprogress'
-        ? (opts: any) => ops.inProgressCount(opts)
-        : (opts: any) => ops.completedCount(opts),
-    [ops, status],
+        ? async (opts: any) => ({ Count: await activity.inProgressCount(opts) })
+        : async (opts: any) => ({ Count: await activity.completedCount(opts) }),
+    [activity, status],
   );
 
   return useTable<ActivityRowType<A>>({

package/sdk/components/hooks/useBDOForm/createItemProxy.ts

@@ -21,8 +21,8 @@ import type {
  * Key principle: Item has NO state. It's a view over RHF's state.
  * Editable fields get set(), readonly fields do not.
  *
- * In create mode (no _id), uses "draft" as the instanceId for attachment
- * uploads and fetch operations — no draftInteraction() call needed.
+ * In create mode (no _id), attachment and fetch operations use 'draft' as the
+ * instanceId, which the backend accepts as a placeholder.
  *
  * @param bdo - The BDO instance for field metadata
  * @param form - The RHF useForm return object
@@ -36,6 +36,8 @@ export function createItemProxy<B extends BaseBdo<any, any, any>>(
   const accessorCache = new Map<string, EditableFormFieldAccessorType<unknown> | ReadonlyFormFieldAccessorType<unknown>>();
 
   const boIdShared = bdo.getBoId();
+
+  /** Returns the real _id in edit mode, or 'draft' in create mode */
   const getInstanceId = (): string =>
     (form.getValues("_id" as Path<FieldValues>) as string) || "draft";
 
@@ -148,15 +150,16 @@ export function createItemProxy<B extends BaseBdo<any, any, any>>(
           validate,
         };
 
-        // Enrich Image/File field accessors with attachment methods
+        // Enrich Image/File field accessors with attachment methods (draft-based upload)
         if (fieldMeta.Type === "Image" || fieldMeta.Type === "File") {
           const boId = boIdShared;
 
           if (fieldMeta.Type === "Image") {
-            // Image: single file upload
+            // Image: single file upload — always uploads immediately (draft in create mode)
             (accessor as any).upload = async (file: File): Promise<FileType> => {
               validateFileExtension(file.name, "Image");
               const id = getInstanceId();
+
               const [uploadInfo] = await api(boId).getUploadUrl(id, prop, [
                 { FileName: file.name, Size: file.size, FileExtension: extractFileExtension(file.name) },
               ]);
@@ -192,10 +195,11 @@ export function createItemProxy<B extends BaseBdo<any, any, any>>(
               return api(boId).getDownloadUrl(instanceId, prop, val._id, viewType);
             };
           } else {
-            // File field — multi-file
+            // File field — multi-file, always uploads immediately (draft in create mode)
             (accessor as any).upload = async (files: File[]): Promise<FileType[]> => {
               for (const file of files) validateFileExtension(file.name, "File");
               const id = getInstanceId();
+
               const requests = files.map((file) => ({
                 FileName: file.name,
                 Size: file.size,

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

@@ -1,22 +1,32 @@
+import type { ListOptionsType, SortType } from '../../../types/common';
 import type { UseTableReturnType, PaginationStateType } from '../useTable/types';
 import type { UseFilterOptionsType } from '../useFilter/types';
-import type { SortType } from '../../../types/common';
 
-export interface UseBDOTableOptionsType<T> {
-  /** BDO instance — only meta._id is used (for API routing) */
-  bdo: {
-    meta: { readonly _id: string; readonly name: string };
-  };
+/** Structural constraint — any object with list() and count() */
+export interface BDOTableSourceType {
+  meta: { readonly _id: string; readonly name: string };
+  list(options?: ListOptionsType): Promise<any[]>;
+  count(options?: ListOptionsType): Promise<number>;
+}
+
+/** Infer row type from BDO's list() return type */
+export type BDORowType<B extends BDOTableSourceType> =
+  B extends { list(opts?: any): Promise<(infer R)[]> } ? R : never;
+
+export interface UseBDOTableOptionsType<B extends BDOTableSourceType> {
+  /** BDO instance — list() and count() are called for data */
+  bdo: B;
   /** Initial state */
   initialState?: {
     sort?: SortType;
     pagination?: PaginationStateType;
-    filter?: UseFilterOptionsType<T>;
+    filter?: UseFilterOptionsType<BDORowType<B>>;
   };
   /** Error callback */
   onError?: (error: Error) => void;
-  /** Success callback — receives rows from current page */
-  onSuccess?: (data: T[]) => void;
+  /** Success callback — receives Item rows from current page */
+  onSuccess?: (data: BDORowType<B>[]) => void;
 }
 
-export type UseBDOTableReturnType<T> = UseTableReturnType<T>;
+export type UseBDOTableReturnType<B extends BDOTableSourceType> =
+  UseTableReturnType<BDORowType<B>>;

package/sdk/components/hooks/useBDOTable/useBDOTable.ts

@@ -1,16 +1,20 @@
-import { api } from '../../../api/client';
 import { useTable } from '../useTable';
-import type { UseBDOTableOptionsType, UseBDOTableReturnType } from './types';
+import type {
+  BDOTableSourceType,
+  BDORowType,
+  UseBDOTableOptionsType,
+  UseBDOTableReturnType,
+} from './types';
 
-export function useBDOTable<T = any>(
-  options: UseBDOTableOptionsType<T>,
-): UseBDOTableReturnType<T> {
+export function useBDOTable<B extends BDOTableSourceType>(
+  options: UseBDOTableOptionsType<B>,
+): UseBDOTableReturnType<B> {
   const { bdo, ...rest } = options;
 
-  return useTable<T>({
+  return useTable<BDORowType<B>>({
     queryKey: ['table', bdo.meta._id],
-    listFn: (opts) => api<T>(bdo.meta._id).list(opts),
-    countFn: (opts) => api<T>(bdo.meta._id).count(opts),
+    listFn: async (opts) => ({ Data: await bdo.list(opts) }),
+    countFn: async (opts) => ({ Count: await bdo.count(opts) }),
     ...rest,
   });
 }

package/sdk/table.types.ts

@@ -14,6 +14,8 @@ export type {
 
 export type {
   // BDO wrapper types
+  BDOTableSourceType,
+  BDORowType,
   UseBDOTableOptionsType,
   UseBDOTableReturnType,
 } from './components/hooks/useBDOTable/types';

package/sdk/types/constants.ts

@@ -351,7 +351,7 @@ export const AuthStatus = {
  */
 export const AuthProviderName = {
   Google: "google",
-  Microsoft: "microsoft",
+  Azure: "azure",
   GitHub: "github",
   Custom: "custom",
 } as const;

package/sdk/workflow/Activity.ts

@@ -23,13 +23,15 @@ import { createActivityInstance } from "./ActivityInstance";
 import type { ActivityInstanceType } from "./ActivityInstance";
 import type { ActivityInstanceFieldsType, ActivityOperations } from "./types";
 import type {
-  ListResponseType,
   ListOptionsType,
   MetricOptionsType,
   MetricResponseType,
 } from "../types/common";
 import { BaseField } from "../bdo/fields/BaseField";
 
+/** Activity system fields treated as readonly on list results */
+type ActivitySystemReadonlyType = Omit<ActivityInstanceFieldsType, '_id'>;
+
 // ============================================================
 // ABSTRACT BASE CLASS
 // ============================================================
@@ -128,18 +130,48 @@ export abstract class Activity<
 
   /**
    * List in-progress activity instances.
-   * Accepts optional filter/sort/pagination options.
+   * Each row is wrapped in an ActivityInstance proxy with field accessors.
    */
-  async getInProgressList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
-    return this._ops().inProgressList(options);
+  async getInProgressList(
+    options?: ListOptionsType,
+  ): Promise<ActivityInstanceType<
+    ActivityInstanceFieldsType & TEntity,
+    TEditable,
+    TReadonly & ActivitySystemReadonlyType
+  >[]> {
+    const ops = this._ops();
+    const response = await ops.inProgressList(options);
+    const fields = this._discoverFields();
+    return response.Data.map((data) =>
+      createActivityInstance<
+        ActivityInstanceFieldsType & TEntity,
+        TEditable,
+        TReadonly & ActivitySystemReadonlyType
+      >(ops, (data as any)._id, data as (ActivityInstanceFieldsType & TEntity), fields),
+    );
   }
 
   /**
    * List completed activity instances.
-   * Accepts optional filter/sort/pagination options.
+   * Each row is wrapped in an ActivityInstance proxy with field accessors.
    */
-  async getCompletedList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
-    return this._ops().completedList(options);
+  async getCompletedList(
+    options?: ListOptionsType,
+  ): Promise<ActivityInstanceType<
+    ActivityInstanceFieldsType & TEntity,
+    TEditable,
+    TReadonly & ActivitySystemReadonlyType
+  >[]> {
+    const ops = this._ops();
+    const response = await ops.completedList(options);
+    const fields = this._discoverFields();
+    return response.Data.map((data) =>
+      createActivityInstance<
+        ActivityInstanceFieldsType & TEntity,
+        TEditable,
+        TReadonly & ActivitySystemReadonlyType
+      >(ops, (data as any)._id, data as (ActivityInstanceFieldsType & TEntity), fields),
+    );
   }
 
   /**

package/dist/constants-QX2RX-wu.cjs

@@ -1 +0,0 @@
-"use strict";const t={EQ:"EQ",NE:"NE",GT:"GT",GTE:"GTE",LT:"LT",LTE:"LTE",Between:"Between",NotBetween:"NotBetween",IN:"IN",NIN:"NIN",Empty:"Empty",NotEmpty:"NotEmpty",Contains:"Contains",NotContains:"NotContains",MinLength:"MinLength",MaxLength:"MaxLength",Length:"Length"},e={And:"And",Or:"Or",Not:"Not"},n={Constant:"Constant",BDOField:"BDOField",AppVariable:"AppVariable"},o={ASC:"ASC",DESC:"DESC"},i={Sum:"Sum",Avg:"Avg",Count:"Count",Max:"Max",Min:"Min",DistinctCount:"DistinctCount",BlankCount:"BlankCount",NotBlankCount:"NotBlankCount",Concat:"Concat",DistinctConcat:"DistinctConcat"},a={List:"List",Metric:"Metric",Pivot:"Pivot"},c={Create:"create",Update:"update"},r={Interactive:"interactive",NonInteractive:"non-interactive"},s={OnBlur:"onBlur",OnChange:"onChange",OnSubmit:"onSubmit",OnTouched:"onTouched",All:"all"},d={Loading:"loading",Authenticated:"authenticated",Unauthenticated:"unauthenticated"},u={Google:"google",Microsoft:"microsoft",GitHub:"github",Custom:"custom"},C={Id:"_id",CreatedAt:"_created_at",ModifiedAt:"_modified_at",CreatedBy:"_created_by",ModifiedBy:"_modified_by",Version:"_version",MergeVersion:"_m_version"},E={GET:"GET",POST:"POST",PATCH:"PATCH",DELETE:"DELETE"},p={SEARCH_DEBOUNCE_MS:300,PAGE_SIZE:10,PAGE:1,SEARCH_MAX_LENGTH:255},T={Date:"$__d__",DateTime:"$__dt__"},l={Success:"success"};exports.AuthProviderName=u;exports.AuthStatus=d;exports.ConditionOperator=t;exports.DateEncodingKey=T;exports.Defaults=p;exports.DeleteStatus=l;exports.FormOperation=c;exports.GroupOperator=e;exports.HttpMethod=E;exports.InteractionMode=r;exports.MetricType=i;exports.QueryType=a;exports.RHSType=n;exports.SortDirection=o;exports.SystemField=C;exports.ValidationMode=s;

package/docs/api.md

@@ -1,95 +0,0 @@
-# API Types Reference
-
-Request and response types for BDO methods. For usage patterns, see [bdo.md](bdo.md).
-
-## Imports
-
-```typescript
-import { api } from "@ram_28/kf-ai-sdk/api";
-import type { ListOptionsType, CreateUpdateResponseType, DeleteResponseType, DraftResponseType, MetricOptionsType, MetricResponseType, PivotOptionsType, PivotResponseType } from "@ram_28/kf-ai-sdk/api/types";
-```
-
----
-
-## Common Mistakes (READ FIRST)
-
-### 1. Calling `api` directly instead of as factory
-
-```typescript
-// ❌ WRONG — api is a function, not a client
-api.get(id);  api.delete(id);
-
-// ✅ CORRECT — call api(boId) first
-api(bdo.meta._id).get(id);
-api(bdo.meta._id).delete(id);
-```
-
-### 2. Using `api()` when BDO methods are available
-
-Prefer BDO methods when they're `public` on the role's class. Use `api()` only for `protected` methods.
-
-```typescript
-// ✅ PREFERRED — BDO method
-const items = await bdo.list();
-
-// ✅ USE api() ONLY when BDO method is protected
-await api(bdo.meta._id).delete(id);
-```
-
-### 3. Wrong metric response key format
-
-Key pattern is `{lowercase_type}_{Field}` with single underscore.
-
-```typescript
-// ❌ WRONG
-const count = result.Data[0].count;
-
-// ✅ CORRECT
-const count = result.Data?.[0]?.["count__id"] ?? 0;     // Count of _id
-const total = result.Data?.[0]?.["sum_unit_price"] ?? 0; // Sum of unit_price
-```
-
----
-
-## Response Types
-
-```typescript
-interface CreateUpdateResponseType { _id: string; }
-interface DeleteResponseType { status: "success"; }
-interface DraftResponseType { [fieldName: string]: any; }
-
-interface ListOptionsType {
-  Field?: string[];
-  Filter?: FilterType;
-  Sort?: Record<string, "ASC" | "DESC">[];
-  Page?: number;       // 1-indexed
-  PageSize?: number;   // Default: 10
-}
-
-interface MetricOptionsType {
-  GroupBy: string[];
-  Metric: { Field: string; Type: AggregationType; }[];
-  Filter?: FilterType;
-}
-
-interface MetricResponseType { Data: Record<string, any>[]; }
-
-interface PivotOptionsType {
-  Row: string[];
-  Column: string[];
-  Metric: { Field: string; Type: AggregationType; }[];
-  Filter?: FilterType;
-}
-
-interface PivotResponseType {
-  Data: { RowHeader: { Key: string }[]; ColumnHeader: { Key: string }[]; Value: (number | string | null)[][]; };
-}
-
-type AggregationType = "Sum" | "Avg" | "Count" | "Max" | "Min" | "DistinctCount" | "BlankCount" | "NotBlankCount" | "Concat" | "DistinctConcat";
-
-// Filter type (for bdo.list() Filter parameter)
-interface FilterType { Operator: "And" | "Or" | "Not"; Condition: Array<ConditionType | ConditionGroupType>; }
-interface ConditionType { Operator: string; LHSField: string; RHSValue: any; RHSType?: "Constant" | "BDOField" | "AppVariable"; }
-
-type SortType = Record<string, "ASC" | "DESC">[];
-```