@ram_28/kf-ai-sdk 2.0.16 → 2.0.18

package/docs/useFilter/api_reference.md

@@ -0,0 +1,228 @@
+# useFilter API Reference
+
+```tsx
+import { useFilter, ConditionOperator, GroupOperator, FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+import { isCondition, isConditionGroup } from "@ram_28/kf-ai-sdk/filter";
+import type {
+  UseFilterOptionsType,
+  UseFilterReturnType,
+  ConditionType,
+  ConditionGroupType,
+  ConditionGroupOperatorType,
+  FilterType,
+  FilterRHSType,
+} from "@ram_28/kf-ai-sdk/filter/types";
+import type { ConditionOperatorType } from "@ram_28/kf-ai-sdk/api/types";
+```
+
+## Signature
+
+```tsx
+const filter: UseFilterReturnType<T> = useFilter<T>(options: UseFilterOptionsType<T>);
+```
+
+## Options
+
+`UseFilterOptionsType<T>`
+
+- `conditions?: Array<ConditionType<T> | ConditionGroupType<T>>`
+  - **Optional**, defaults to `[]`
+  - Initial filter conditions. Each item is cloned and assigned an auto-generated `id`.
+- `operator?: ConditionGroupOperatorType`
+  - **Optional**, defaults to `"And"`
+  - Root operator for combining top-level conditions.
+
+## Return Value
+
+`UseFilterReturnType<T>`
+
+### State
+
+- `operator: ConditionGroupOperatorType`
+  - Current root operator (`"And"` | `"Or"` | `"Not"`).
+- `items: Array<ConditionType<T> | ConditionGroupType<T>>`
+  - Current filter items with `id` populated. This is the stateful tree used for rendering and lookups.
+- `payload: FilterType<T> | undefined`
+  - API-ready filter payload with all `id` fields stripped. Returns `undefined` when there are no conditions.
+- `hasConditions: boolean`
+  - `true` when at least one condition exists. Equivalent to `items.length > 0`.
+
+### Add Operations
+
+Both methods return the `id` (string) of the newly created item.
+
+- `addCondition(condition: Omit<ConditionType<T>, "id">, parentId?: string): string`
+  - Add a leaf condition. When `parentId` is omitted, appended at root level. When provided, added inside the matching group's `Condition` array. Returns the auto-generated `id`.
+- `addConditionGroup(operator: ConditionGroupOperatorType, parentId?: string): string`
+  - Create an empty condition group with the given operator. Same `parentId` behavior as `addCondition`. Returns the group's `id`.
+
+### Update Operations
+
+- `updateCondition(id: string, updates: Partial<Omit<ConditionType<T>, "id">>): void`
+  - Partially update a leaf condition by `id`. Only provided fields are merged. No effect if `id` matches a group.
+- `updateGroupOperator(id: string, operator: ConditionGroupOperatorType): void`
+  - Change the `Operator` of a condition group by `id`. No effect if `id` matches a leaf condition.
+
+### Remove & Access
+
+- `removeCondition(id: string): void`
+  - Remove a condition or group by `id`. Searches recursively. Removing a group removes all its children.
+- `getCondition(id: string): ConditionType<T> | ConditionGroupType<T> | undefined`
+  - Look up a condition or group by `id`. Returns `undefined` if not found. Searches recursively.
+
+### Utility
+
+- `clearAllConditions(): void`
+  - Remove all conditions and groups, resetting `items` to `[]`. After this, `payload` is `undefined` and `hasConditions` is `false`.
+- `setRootOperator(op: ConditionGroupOperatorType): void`
+  - Change the root-level operator that combines all top-level conditions.
+
+## Exported Constants
+
+### ConditionOperator
+
+Import from `@ram_28/kf-ai-sdk/filter`. Used as the `Operator` value on leaf conditions (`ConditionType`).
+
+**Comparison:**
+
+- `EQ` (`"EQ"`) -- Equal. RHSValue: single value.
+- `NE` (`"NE"`) -- Not equal. RHSValue: single value.
+- `GT` (`"GT"`) -- Greater than. RHSValue: single value.
+- `GTE` (`"GTE"`) -- Greater than or equal. RHSValue: single value.
+- `LT` (`"LT"`) -- Less than. RHSValue: single value.
+- `LTE` (`"LTE"`) -- Less than or equal. RHSValue: single value.
+
+**Range:**
+
+- `Between` (`"Between"`) -- Value within range. RHSValue: `[min, max]`.
+- `NotBetween` (`"NotBetween"`) -- Value outside range. RHSValue: `[min, max]`.
+
+**List:**
+
+- `IN` (`"IN"`) -- Value in list. RHSValue: `[value1, value2, ...]`.
+- `NIN` (`"NIN"`) -- Value not in list. RHSValue: `[value1, value2, ...]`.
+
+**Presence:**
+
+- `Empty` (`"Empty"`) -- Field is empty/null. RHSValue: not required.
+- `NotEmpty` (`"NotEmpty"`) -- Field is not empty. RHSValue: not required.
+
+**String:**
+
+- `Contains` (`"Contains"`) -- String contains substring. RHSValue: string.
+- `NotContains` (`"NotContains"`) -- Does not contain. RHSValue: string.
+
+**Length:**
+
+- `MinLength` (`"MinLength"`) -- Minimum length. RHSValue: number.
+- `MaxLength` (`"MaxLength"`) -- Maximum length. RHSValue: number.
+- `Length` (`"Length"`) -- Exact length. RHSValue: number.
+
+### GroupOperator
+
+Import from `@ram_28/kf-ai-sdk/filter`. Used as the `Operator` value on condition groups (`ConditionGroupType`).
+
+- `And` (`"And"`) -- All conditions must match.
+- `Or` (`"Or"`) -- Any condition can match.
+- `Not` (`"Not"`) -- Negate the conditions.
+
+### FilterValueSource
+
+Import from `@ram_28/kf-ai-sdk/filter`. Used as the `RHSType` value on leaf conditions. The import name is `FilterValueSource`; the property name on the condition object is `RHSType`.
+
+- `Constant` (`"Constant"`) -- RHSValue is a literal value (string, number, boolean, array, etc.).
+- `BDOField` (`"BDOField"`) -- RHSValue is another field name (field-to-field comparison).
+- `AppVariable` (`"AppVariable"`) -- RHSValue is an application-level variable.
+
+## Type Guards
+
+Import from `@ram_28/kf-ai-sdk/filter`.
+
+- `isCondition(item): item is ConditionType` -- Returns `true` when the item has an `LHSField` property (leaf condition).
+- `isConditionGroup(item): item is ConditionGroupType` -- Returns `true` when the item has a `Condition` property (group node).
+
+```tsx
+filter.items.forEach((item) => {
+  if (isCondition(item)) {
+    console.log(item.LHSField, item.Operator, item.RHSValue);
+  }
+  if (isConditionGroup(item)) {
+    console.log(item.Operator, "group with", item.Condition.length, "children");
+  }
+});
+```
+
+## Types
+
+```typescript
+// ============================================================
+// Condition types
+// ============================================================
+
+interface ConditionType<T = any> {
+  /** Auto-generated by useFilter for state management. Stripped from payload. */
+  id?: string;
+  /** Comparison operator (use ConditionOperator constants). */
+  Operator: ConditionOperatorType;
+  /** Field name to compare. When T is provided, autocompletes to keyof T. */
+  LHSField: T extends any ? keyof T | string : string;
+  /** Value to compare against. Format depends on the Operator. */
+  RHSValue: any;
+  /** How RHSValue is interpreted. Use FilterValueSource constants. */
+  RHSType?: FilterRHSType;
+}
+
+interface ConditionGroupType<T = any> {
+  /** Auto-generated by useFilter for state management. Stripped from payload. */
+  id?: string;
+  /** Logical operator: "And", "Or", or "Not" (use GroupOperator constants). */
+  Operator: ConditionGroupOperatorType;
+  /** Nested conditions and/or groups. */
+  Condition: Array<ConditionType<T> | ConditionGroupType<T>>;
+}
+
+/** Root filter structure sent to the API. Alias for ConditionGroupType. */
+type FilterType<T = any> = ConditionGroupType<T>;
+
+type ConditionOperatorType = (typeof ConditionOperator)[keyof typeof ConditionOperator];
+// "EQ" | "NE" | "GT" | "GTE" | "LT" | "LTE" | "Between" | "NotBetween"
+// | "IN" | "NIN" | "Empty" | "NotEmpty" | "Contains" | "NotContains"
+// | "MinLength" | "MaxLength" | "Length"
+
+type ConditionGroupOperatorType = (typeof GroupOperator)[keyof typeof GroupOperator];
+// "And" | "Or" | "Not"
+
+type FilterRHSType = (typeof FilterValueSource)[keyof typeof FilterValueSource];
+// "Constant" | "BDOField" | "AppVariable"
+
+interface UseFilterOptionsType<T = any> {
+  /** Initial filter conditions. Each item is cloned and assigned an auto-generated id. */
+  conditions?: Array<ConditionType<T> | ConditionGroupType<T>>;
+  /** Root operator for combining conditions. Defaults to "And". */
+  operator?: ConditionGroupOperatorType;
+}
+
+interface UseFilterReturnType<T = any> {
+  // State
+  operator: ConditionGroupOperatorType;
+  items: Array<ConditionType<T> | ConditionGroupType<T>>;
+  payload: FilterType<T> | undefined;
+  hasConditions: boolean;
+
+  // Add (return id of created item)
+  addCondition: (condition: Omit<ConditionType<T>, "id">, parentId?: string) => string;
+  addConditionGroup: (operator: ConditionGroupOperatorType, parentId?: string) => string;
+
+  // Update
+  updateCondition: (id: string, updates: Partial<Omit<ConditionType<T>, "id">>) => void;
+  updateGroupOperator: (id: string, operator: ConditionGroupOperatorType) => void;
+
+  // Remove and access
+  removeCondition: (id: string) => void;
+  getCondition: (id: string) => ConditionType<T> | ConditionGroupType<T> | undefined;
+
+  // Utility
+  clearAllConditions: () => void;
+  setRootOperator: (op: ConditionGroupOperatorType) => void;
+}
+```

package/docs/workflow/README.md

@@ -0,0 +1,158 @@
+# Workflow
+
+Business process orchestration with typed Activity classes and a Workflow wrapper. Activity classes use the same three-generics pattern as BDO (`Activity<TEntity, TEditable, TReadonly>`), and a Workflow class ties multiple activities into a process.
+
+## Imports
+
+```typescript
+// Page component — import the generated workflow and activity classes, plus hooks
+import { LeaveProcess } from "../workflow/LeaveProcess";
+import { EmployeeInputActivity } from "../workflow/EmployeeInputActivity";
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+```
+
+```typescript
+// Workflow class definition — used by the js_sdk generator
+import { Activity, Workflow } from "@ram_28/kf-ai-sdk/workflow";
+import type { WorkflowStartResponseType, ActivityProgressType } from "@ram_28/kf-ai-sdk/workflow";
+```
+
+Field classes and field value types are imported from `@ram_28/kf-ai-sdk/bdo` and `@ram_28/kf-ai-sdk/types`, same as BDO.
+
+## Common Mistakes (READ FIRST)
+
+1. **`BPInstanceId` vs `_id`** — `start()` returns both. `BPInstanceId` is for `progress()`. `_id` is the first activity instance ID for `getInstance()`.
+2. **`complete()` does not save** — `complete()` only marks the activity done and advances the workflow. Call `update()` first to persist field changes, then `complete()`.
+3. **No single `list()` method** — Use `getInProgressList()` or `getCompletedList()`. The backend filters by status automatically.
+4. **Memoize Activity instances in React** — Wrap in `useMemo` to prevent re-creation on every render:
+   ```typescript
+   const activity = useMemo(() => new EmployeeInputActivity(), []);
+   ```
+
+## Quick Start
+
+```typescript
+const leaveProcess = new LeaveProcess();
+const employeeInput = new EmployeeInputActivity();
+
+// Start workflow — returns { BPInstanceId, ActivityId, _id }
+const { BPInstanceId, _id } = await leaveProcess.start();
+
+// Get the first activity instance
+const instance = await employeeInput.getInstance(_id);
+instance.StartDate.get();  // read field value
+
+// Update fields, then complete
+await instance.update({ StartDate: "2026-04-01", EndDate: "2026-04-05", LeaveType: "PTO" });
+await instance.complete();
+
+// Check workflow progress
+const stages = await leaveProcess.progress(BPInstanceId);
+// [{ ActivityId: "EMPLOYEE_INPUT", Status: "COMPLETED" }, { ActivityId: "MANAGER_APPROVAL", Status: "IN_PROGRESS" }]
+```
+
+## Usage Guide
+
+### Workflow Methods
+
+The Workflow class is a thin wrapper — `start()` and `progress()` only.
+
+```typescript
+const leaveProcess = new LeaveProcess();
+
+// Start a new instance
+const { BPInstanceId, ActivityId, _id } = await leaveProcess.start();
+
+// Get progress for all stages (pass BPInstanceId, not _id)
+const stages = await leaveProcess.progress(BPInstanceId);
+stages.forEach((s) => console.log(s.ActivityId, s.Status));
+```
+
+### Activity Methods
+
+```typescript
+const activity = new EmployeeInputActivity();
+
+// List instances by status
+const inProgress = await activity.getInProgressList({ Page: 1, PageSize: 10 });
+const completed = await activity.getCompletedList({ Page: 1, PageSize: 10 });
+
+// Count
+const pendingCount = await activity.inProgressCount();
+const doneCount = await activity.completedCount();
+
+// Metrics
+const result = await activity.inProgressMetric({
+  GroupBy: ["LeaveType"],
+  Metric: [{ Field: "LeaveDays", Type: "Sum" }],
+});
+
+// Get single instance
+const instance = await activity.getInstance("instance_id");
+```
+
+### ActivityInstance Field Accessors
+
+Same accessor pattern as BDO `ItemType`.
+
+```typescript
+const instance = await activity.getInstance(_id);
+
+// Read values
+instance._id;                        // string (direct)
+instance.StartDate.get();            // DateFieldType | undefined
+instance.LeaveDays.getOrDefault(0);  // number (never undefined)
+
+// Write values (editable fields only)
+instance.StartDate.set("2026-04-01");
+
+// Field metadata
+instance.StartDate.label;     // "Start Date"
+instance.StartDate.required;  // true
+instance.StartDate.readOnly;  // false
+
+// Validation
+instance.StartDate.validate(); // { valid, errors }
+instance.validate();           // validates all fields
+
+// Serialize
+instance.toJSON();             // { StartDate: "2026-04-01", ... }
+```
+
+### Persistence: update, save, complete
+
+```typescript
+const instance = await activity.getInstance(_id);
+
+// update() — persists field changes
+await instance.update({ StartDate: "2026-04-01", EndDate: "2026-04-05" });
+
+// save() — commits a draft (used by useActivityForm internally)
+await instance.save({ StartDate: "2026-04-01" });
+
+// complete() — marks activity done, advances workflow (does NOT auto-save)
+await instance.complete();
+
+// progress() — get workflow progress from this instance
+const stages = await instance.progress();
+```
+
+### Progress Tracking
+
+```typescript
+const stages = await leaveProcess.progress(BPInstanceId);
+
+for (const stage of stages) {
+  console.log(stage.ActivityId);   // "EMPLOYEE_INPUT"
+  console.log(stage.Status);      // "COMPLETED" | "IN_PROGRESS"
+  console.log(stage.CompletedAt); // string | null
+  console.log(stage.CompletedBy); // { _id, _name } | null
+}
+```
+
+## Further Reading
+
+- [API Reference](./api_reference.md) — full method signatures, parameter types, and return types
+- [Start New Workflow](../examples/workflow/start-new-workflow.md) — `workflow.start()` flow
+- [Workflow Progress](../examples/workflow/workflow-progress.md) — progress badges for activity stages

package/docs/workflow/api_reference.md

@@ -0,0 +1,161 @@
+```typescript
+import { Activity, Workflow } from "@ram_28/kf-ai-sdk/workflow";
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import type {
+  WorkflowStartResponseType,
+  ActivityProgressType,
+  ActivityInstanceFieldsType,
+  ActivityTableStatusType,
+} from "@ram_28/kf-ai-sdk/workflow";
+import type {
+  ListOptionsType,
+  CreateUpdateResponseType,
+  MetricOptionsType,
+  MetricResponseType,
+} from "@ram_28/kf-ai-sdk/api/types";
+import type { ValidationResultType } from "@ram_28/kf-ai-sdk/bdo/types";
+```
+
+## Workflow Methods
+
+| Method | Params | Returns |
+|--------|--------|---------|
+| `start()` | — | `Promise<WorkflowStartResponseType>` |
+| `progress(instanceId)` | `instance_id: string` (pass `BPInstanceId`) | `Promise<ActivityProgressType[]>` |
+
+## Activity Methods
+
+| Method | Params | Returns |
+|--------|--------|---------|
+| `getInstance(id)` | `instanceId: string` | `Promise<ActivityInstanceType<TEntity, TEditable, TReadonly>>` |
+| `getInProgressList(options?)` | `options?: ListOptionsType` | `Promise<ActivityInstanceType<...>[]>` |
+| `getCompletedList(options?)` | `options?: ListOptionsType` | `Promise<ActivityInstanceType<...>[]>` |
+| `inProgressCount(options?)` | `options?: ListOptionsType` | `Promise<number>` |
+| `completedCount(options?)` | `options?: ListOptionsType` | `Promise<number>` |
+| `inProgressMetric(options)` | `options: Omit<MetricOptionsType, "Type">` | `Promise<MetricResponseType>` |
+| `completedMetric(options)` | `options: Omit<MetricOptionsType, "Type">` | `Promise<MetricResponseType>` |
+
+## ActivityInstance Methods
+
+| Method | Params | Returns |
+|--------|--------|---------|
+| `update(data)` | `data: Partial<TEditable>` | `Promise<CreateUpdateResponseType>` |
+| `complete()` | — | `Promise<CreateUpdateResponseType>` |
+| `save(data)` | `data: Partial<TEditable>` | `Promise<CreateUpdateResponseType>` |
+| `progress()` | — | `Promise<ActivityProgressType[]>` |
+| `toJSON()` | — | `Partial<TEntity>` |
+| `validate()` | — | `ValidationResultType` |
+
+ActivityInstance field accessors follow the same pattern as BDO `ItemType` — see [BDO API Reference](../bdo/api_reference.md#editablefieldaccessortypet) for `EditableFieldAccessorType` and `ReadonlyFieldAccessorType`.
+
+## Types
+
+### WorkflowStartResponseType
+
+```typescript
+interface WorkflowStartResponseType {
+  BPInstanceId: string;   // business process instance ID — pass to progress()
+  ActivityId: string;     // first activity's ID
+  _id: string;            // first activity instance ID — pass to getInstance()
+}
+```
+
+### ActivityProgressType
+
+```typescript
+interface ActivityProgressType {
+  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;
+}
+```
+
+### ActivityInstanceType\<TEntity, TEditable, TReadonly\>
+
+Proxy-wrapped activity instance. Same accessor pattern as BDO `ItemType`.
+
+```typescript
+type ActivityInstanceType<TEntity, TEditable, TReadonly> = {
+  readonly _id: string;
+
+  // Editable fields → EditableFieldAccessorType<T> (get/set/validate)
+  // Readonly fields → ReadonlyFieldAccessorType<T> (get/validate, no set)
+
+  update(data: Partial<TEditable>): Promise<CreateUpdateResponseType>;
+  complete(): Promise<CreateUpdateResponseType>;
+  save(data: Partial<TEditable>): Promise<CreateUpdateResponseType>;
+  progress(): Promise<ActivityProgressType[]>;
+  toJSON(): Partial<TEntity>;
+  validate(): ValidationResultType;
+};
+```
+
+### ActivityInstanceFieldsType
+
+System fields present on every activity instance record.
+
+```typescript
+type ActivityInstanceFieldsType = {
+  _id: StringFieldType;
+  BPInstanceId: StringFieldType;
+  Status: SelectFieldType<"InProgress" | "Completed">;
+  AssignedTo: UserFieldType[];
+  CompletedAt: DateTimeFieldType;
+};
+```
+
+### ActivityTableStatus
+
+Constants for the `useActivityTable` status parameter.
+
+```typescript
+const ActivityTableStatus = {
+  InProgress: "inprogress",
+  Completed: "completed",
+} as const;
+
+type ActivityTableStatusType =
+  (typeof ActivityTableStatus)[keyof typeof ActivityTableStatus];
+```
+
+### ListOptionsType
+
+Same type as BDO — see [BDO API Reference](../bdo/api_reference.md#listoptionstype).
+
+```typescript
+interface ListOptionsType {
+  Filter?: FilterType;
+  Sort?: SortType;
+  Page?: number;       // 1-indexed
+  PageSize?: number;
+  Search?: string;
+  Field?: string[];
+}
+```
+
+### Generated Type Patterns
+
+The js_sdk generator creates these types per activity:
+
+```typescript
+// workflow/EmployeeInputActivity.ts
+type LeaveEntityType = {
+  StartDate: DateFieldType;
+  EndDate: DateFieldType;
+  LeaveType: StringFieldType;
+  LeaveDays: NumberFieldType;
+};
+type LeaveEditableFieldType = Pick<LeaveEntityType, "StartDate" | "EndDate" | "LeaveType">;
+type LeaveReadonlyFieldType = Pick<LeaveEntityType, "LeaveDays">;
+
+class EmployeeInputActivity extends Activity<LeaveEntityType, LeaveEditableFieldType, LeaveReadonlyFieldType> {
+  readonly meta = { businessProcessId: "SimpleLeaveProcess", activityId: "EMPLOYEE_INPUT" } as const;
+  // ... field declarations
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",

package/sdk/auth/authConfig.ts

@@ -43,7 +43,7 @@ let authConfig: AuthConfigType = { ...defaultAuthConfig };
  *   autoRedirect: true,
  *   providers: {
  *     google: { loginPath: "/api/auth/google/login" },
- *     microsoft: { loginPath: "/api/auth/microsoft/login" },
+ *     azure: { loginPath: "/api/auth/azure/login" },
  *   },
  * });
  * ```

package/sdk/auth/types.ts

@@ -29,7 +29,7 @@ export type AuthStatusType = "loading" | "authenticated" | "unauthenticated";
 /**
  * Authentication provider type (extensible for multiple OAuth providers)
  */
-export type AuthProviderNameType = "google" | "microsoft" | "github" | "custom";
+export type AuthProviderNameType = "google" | "azure" | "github" | "custom";
 
 /**
  * Auth endpoint configuration for a specific provider

package/sdk/bdo/core/Item.ts

@@ -196,18 +196,9 @@ export class Item<T extends Record<string, unknown>> {
     }) as Item<T>;
   }
 
-  /**
-   * Require instanceId or throw.
-   * TODO: Support create flow via draftInteraction to get temp _id
-   */
   private _requireInstanceId(): string {
     const id = this._data._id as string | undefined;
-    if (!id) {
-      throw new Error(
-        "Cannot perform attachment operation: item has no _id. Save the item first.",
-      );
-    }
-    return id;
+    return id || "draft";
   }
 
   /**

package/sdk/bdo/fields/ReferenceField.ts

@@ -71,7 +71,7 @@ export class ReferenceField<TRef = unknown> extends BaseField<
    * Fetch referenced records from the backend via the fetchField API.
    * Requires the field to be bound to a parent BDO.
    */
-  async fetchOptions(instanceId: string): Promise<TRef[]> {
+  async fetchOptions(instanceId: string = "draft"): Promise<TRef[]> {
     if (!this._parentBoId) {
       throw new Error(
         `Field ${this.id} not bound to a BDO. Cannot fetch options.`

package/sdk/bdo/fields/SelectField.ts

@@ -57,7 +57,7 @@ export class SelectField<T extends string | number = string> extends BaseField<T
   /**
    * Fetch dynamic options from the backend, returned as typed SelectOption[]
    */
-  async fetchOptions(instanceId: string): Promise<SelectOptionType<T>[]> {
+  async fetchOptions(instanceId: string = "draft"): Promise<SelectOptionType<T>[]> {
     if (!this._parentBoId) {
       throw new Error(
         `Field ${this.id} not bound to a BDO. Cannot fetch options.`

package/sdk/bdo/fields/UserField.ts

@@ -32,7 +32,7 @@ export class UserField extends BaseField<UserFieldType> {
    * Fetch user records from the backend via the fetchField API.
    * Requires the field to be bound to a parent BDO.
    */
-  async fetchOptions(instanceId: string): Promise<UserFieldType[]> {
+  async fetchOptions(instanceId: string = "draft"): Promise<UserFieldType[]> {
     if (!this._parentBoId) {
       throw new Error(
         `Field ${this.id} not bound to a BDO. Cannot fetch options.`,

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

@@ -15,6 +15,7 @@ import type {
 } from 'react-hook-form';
 
 import type { Activity } from '../../../workflow/Activity';
+import type { CreateUpdateResponseType } from '../../../types/common';
 
 // Reuse shared types from useBDOForm — identical interfaces, no duplication
 import type {
@@ -104,11 +105,8 @@ export interface UseActivityFormReturn<A extends Activity<any, any, any>> {
     ExtractActivityReadonly<A>
   >;
 
-  /** Handle form submission — calls activity.update() */
-  handleSubmit: HandleSubmitType<AllActivityFields<A>>;
-
-  /** Handle form completion — calls activity.update() + activity.complete() */
-  handleComplete: HandleSubmitType<AllActivityFields<A>>;
+  /** Handle form submission — validates, updates dirty fields, then completes the activity */
+  handleSubmit: HandleSubmitType<CreateUpdateResponseType>;
 
   /** Watch field values */
   watch: UseFormWatch<AllActivityFields<A>>;
@@ -141,7 +139,7 @@ export interface UseActivityFormReturn<A extends Activity<any, any, any>> {
   /** Form has been modified */
   isDirty: boolean;
 
-  /** Form is currently submitting (save or complete) */
+  /** Form is currently submitting */
   isSubmitting: boolean;
 
   /** Form submission was successful */