@amaster.ai/client 1.1.0-beta.31 → 1.1.0-beta.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/client",
-  "version": "1.1.0-beta.31",
+  "version": "1.1.0-beta.32",
   "description": "Unified API client for Amaster platform - All services in one package",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -72,17 +72,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@amaster.ai/asr-http-client": "1.1.0-beta.31",
-    "@amaster.ai/copilot-client": "1.1.0-beta.31",
-    "@amaster.ai/auth-client": "1.1.0-beta.31",
-    "@amaster.ai/asr-client": "1.1.0-beta.31",
-    "@amaster.ai/http-client": "1.1.0-beta.31",
-    "@amaster.ai/function-client": "1.1.0-beta.31",
-    "@amaster.ai/bpm-client": "1.1.0-beta.31",
-    "@amaster.ai/s3-client": "1.1.0-beta.31",
-    "@amaster.ai/entity-client": "1.1.0-beta.31",
-    "@amaster.ai/workflow-client": "1.1.0-beta.31",
-    "@amaster.ai/tts-client": "1.1.0-beta.31"
+    "@amaster.ai/bpm-client": "1.1.0-beta.32",
+    "@amaster.ai/entity-client": "1.1.0-beta.32",
+    "@amaster.ai/asr-client": "1.1.0-beta.32",
+    "@amaster.ai/auth-client": "1.1.0-beta.32",
+    "@amaster.ai/http-client": "1.1.0-beta.32",
+    "@amaster.ai/s3-client": "1.1.0-beta.32",
+    "@amaster.ai/workflow-client": "1.1.0-beta.32",
+    "@amaster.ai/function-client": "1.1.0-beta.32",
+    "@amaster.ai/copilot-client": "1.1.0-beta.32",
+    "@amaster.ai/asr-http-client": "1.1.0-beta.32",
+    "@amaster.ai/tts-client": "1.1.0-beta.32"
   },
   "peerDependencies": {
     "axios": "^1.11.0"

package/types/bpm.d.ts

@@ -1,9 +1,22 @@
 /**
- * 
+ * ============================================================================
+ * BPM Module - Type Definitions
+ * ============================================================================
+ *
+ * This module provides Business Process Management (BPM) capabilities
+ * based on Camunda BPMN engine.
+ *
+ * ## Key Features
+ * - Start and manage BPMN processes
+ * - Query and complete user tasks
+ * - Manage process variables
+ * - Query process history
+ * - Handle BPMN flows (approval, business processes, etc.)
+ *
  * @module bpm
  */
 
-import type { ClientResult } from './common';
+import type { ClientResult } from "./common";
 
 // ==================== Variable Types ====================
 
@@ -11,13 +24,13 @@ import type { ClientResult } from './common';
  * Camunda variable type
  */
 export type CamundaVariableType =
-  | 'String'
-  | 'Boolean'
-  | 'Integer'
-  | 'Long'
-  | 'Double'
-  | 'Date'
-  | 'Json';
+  | "String"
+  | "Boolean"
+  | "Integer"
+  | "Long"
+  | "Double"
+  | "Date"
+  | "Json";
 
 /**
  * Camunda variable value (can be any JSON-serializable type)
@@ -35,6 +48,13 @@ export type CamundaVariableValue =
 /**
  * Camunda variable with type hint
  *
+ * @example
+ * ```typescript
+ * const variable: CamundaVariable = {
+ *   value: 1000,
+ *   type: 'Long'
+ * };
+ * ```
  */
 export interface CamundaVariable {
   value: CamundaVariableValue;
@@ -44,6 +64,16 @@ export interface CamundaVariable {
 /**
  * Variable submission format for process/task
  *
+ * @example
+ * ```typescript
+ * const submission: VariableSubmission = {
+ *   variables: {
+ *     amount: { value: 1000, type: 'Long' },
+ *     requester: { value: 'user-123', type: 'String' },
+ *     approved: { value: false, type: 'Boolean' }
+ *   }
+ * };
+ * ```
  */
 export interface VariableSubmission {
   variables: Record<string, CamundaVariable>;
@@ -127,18 +157,50 @@ export interface Task {
   id: string;
   /** Task name */
   name: string;
+  /** Task description */
+  description?: string | null;
   /** Assignee user ID */
-  assignee: string | null;
-  /** Process instance ID */
-  processInstanceId: string;
-  /** Task definition key */
-  taskDefinitionKey: string;
+  assignee?: string | null;
+  /** Task owner */
+  owner?: string | null;
   /** Task creation time */
-  created: string;
+  created?: string | null;
   /** Task due date */
-  due: string | null;
+  due?: string | null;
+  /** Task follow-up date */
+  followUp?: string | null;
+  /** Last update time */
+  lastUpdated?: string | null;
+  /** Delegation state */
+  delegationState?: string | null;
   /** Task priority */
-  priority: number;
+  priority?: number;
+  /** Process instance ID */
+  processInstanceId?: string | null;
+  /** Process definition ID */
+  processDefinitionId?: string | null;
+  /** Execution ID */
+  executionId?: string | null;
+  /** Task definition key */
+  taskDefinitionKey?: string | null;
+  /** Parent task ID */
+  parentTaskId?: string | null;
+  /** Case execution ID */
+  caseExecutionId?: string | null;
+  /** Case instance ID */
+  caseInstanceId?: string | null;
+  /** Case definition ID */
+  caseDefinitionId?: string | null;
+  /** Whether task is suspended */
+  suspended?: boolean;
+  /** Form key */
+  formKey?: string | null;
+  /** Camunda form reference */
+  camundaFormRef?: string | null;
+  /** Tenant ID */
+  tenantId?: string | null;
+  /** Task state */
+  taskState?: string | null;
 }
 
 /**
@@ -166,36 +228,119 @@ export interface TaskCount {
   count: number;
 }
 
+/**
+ * Historical task information
+ */
+export interface HistoryTask {
+  /** Task ID */
+  id: string;
+  /** Task name */
+  name: string;
+  /** Task description */
+  description?: string | null;
+  /** Assignee user ID */
+  assignee?: string | null;
+  /** Task owner */
+  owner?: string | null;
+  /** Task start time */
+  startTime: string;
+  /** Task end time */
+  endTime?: string | null;
+  /** Task duration in milliseconds */
+  duration?: number | null;
+  /** Task due date */
+  due?: string | null;
+  /** Task follow-up date */
+  followUp?: string | null;
+  /** Task priority */
+  priority?: number;
+  /** Task state */
+  taskState?: string | null;
+  /** Delete reason */
+  deleteReason?: string | null;
+  /** Process instance ID */
+  processInstanceId?: string | null;
+  /** Process definition ID */
+  processDefinitionId?: string | null;
+  /** Process definition key */
+  processDefinitionKey?: string | null;
+  /** Execution ID */
+  executionId?: string | null;
+  /** Task definition key */
+  taskDefinitionKey?: string | null;
+  /** Parent task ID */
+  parentTaskId?: string | null;
+  /** Activity instance ID */
+  activityInstanceId?: string | null;
+  /** Case definition key */
+  caseDefinitionKey?: string | null;
+  /** Case definition ID */
+  caseDefinitionId?: string | null;
+  /** Case instance ID */
+  caseInstanceId?: string | null;
+  /** Case execution ID */
+  caseExecutionId?: string | null;
+  /** Tenant ID */
+  tenantId?: string | null;
+  /** Removal time */
+  removalTime?: string | null;
+  /** Root process instance ID */
+  rootProcessInstanceId?: string | null;
+}
+
 // ==================== BPM Client API ====================
 
 /**
  * Business Process Management (BPM) Client API
- * 
+ *
  * Provides methods for managing BPMN processes and tasks.
- * 
- * @since 1.0.0
+ *
+ * @example
+ * Complete BPM flow:
+ * ```typescript
+ * const client = createClient({ baseURL: 'https://api.amaster.ai' });
+ *
+ * // 1. Start a process
+ * const process = await client.bpm.startProcess('approval', {
+ *   amount: { value: 5000, type: 'Long' },
+ *   requester: { value: 'user-123', type: 'String' },
+ *   description: { value: 'Purchase request', type: 'String' }
+ * });
+ *
+ * console.log('Process started:', process.data.id);
+ *
+ * // 2. Get user's tasks
+ * const tasks = await client.bpm.getTasks({
+ *   assignee: 'manager-456',
+ *   processDefinitionKey: 'approval'
+ * });
+ *
+ * // 3. Complete a task
+ * const taskId = tasks.data[0].id;
+ * await client.bpm.completeTask(taskId, {
+ *   approved: { value: true, type: 'Boolean' },
+ *   comment: { value: 'Approved!', type: 'String' }
+ * });
+ * ```
  */
 export interface BpmClientAPI {
   // ==================== Process Management ====================
 
   /**
    * Start a new process instance
-   * 
+   *
    * @param processKey - Process definition key (from BPMN diagram)
    * @param inputs - Process variables (can be simple object or VariableSubmission)
    * @returns New process instance information
-   * 
+   *
    * @example
    * // Simple start
    * const result = await client.bpm.startProcess('approval-process', {
    *   amount: 1000,
    *   requester: 'john@example.com'
    * });
-   * 
-   * if (result.success) {
-   *   console.log('Process started:', result.data.id);
-   * }
-   * 
+   * ```
+   *
    * @example
    * // With business key
    * const result = await client.bpm.startProcess('order-fulfillment', {
@@ -212,10 +357,18 @@ export interface BpmClientAPI {
 
   /**
    * Query process instances
-   * 
+   *
    * @param params - Query parameters
    * @returns Array of process instances
    *
+   * @example
+   * Get all active approval processes:
+   * ```typescript
+   * const result = await client.bpm.getProcessInstances({
+   *   processDefinitionKey: 'approval',
+   *   active: true
+   * });
+   * ```
    */
   getProcessInstances(
     params?: ProcessInstanceQueryParams
@@ -223,22 +376,29 @@ export interface BpmClientAPI {
 
   /**
    * Get a single process instance by ID
-   * 
+   *
    * @param processInstanceId - Process instance ID
    * @returns Process instance information
    *
+   * @example
+   * ```typescript
+   * const result = await client.bpm.getProcessInstance('proc-123-456');
+   * console.log('Process:', result.data);
+   * ```
    */
-  getProcessInstance(
-    processInstanceId: string
-  ): Promise<ClientResult<ProcessInstance>>;
+  getProcessInstance(processInstanceId: string): Promise<ClientResult<ProcessInstance>>;
 
   /**
    * Delete a process instance
-   * 
+   *
    * @param processInstanceId - Process instance ID
    * @param params - Optional parameters
    * @returns null on success
    *
+   * @example
+   * ```typescript
+   * await client.bpm.deleteProcessInstance('proc-123');
+   * ```
    */
   deleteProcessInstance(
     processInstanceId: string,
@@ -247,10 +407,26 @@ export interface BpmClientAPI {
 
   /**
    * Get process variables
-   * 
+   *
    * @param params - Process instance ID and optional variable name
    * @returns Array of process variables
    *
+   * @example
+   * Get all variables:
+   * ```typescript
+   * const result = await client.bpm.getProcessVariables({
+   *   processInstanceId: 'proc-123'
+   * });
+   * ```
+   *
+   * @example
+   * Get specific variable:
+   * ```typescript
+   * const result = await client.bpm.getProcessVariables({
+   *   processInstanceId: 'proc-123',
+   *   variableName: 'amount'
+   * });
+   * ```
    */
   getProcessVariables(params: {
     processInstanceId: string;
@@ -261,14 +437,22 @@ export interface BpmClientAPI {
 
   /**
    * Query user tasks
-   * 
+   *
    * @param params - Query parameters
    * @returns Array of tasks
-   * 
+   *
    * @example
-   * // Get all tasks
-   * const result = await client.bpm.getTasks();
-   * 
+   * Get tasks assigned to current user:
+   * ```typescript
+   * const result = await client.bpm.getTasks({
+   *   assignee: 'user-123'
+   * });
+   *
+   * result.data.forEach(task => {
+   *   console.log(`Task: ${task.name} (${task.id})`);
+   * });
+   * ```
+   *
    * @example
    * // Get tasks for current user
    * const result = await client.bpm.getTasks({
@@ -288,20 +472,26 @@ export interface BpmClientAPI {
 
   /**
    * Get task count
-   * 
+   *
    * @param params - Query parameters
    * @returns Task count
-   * 
-   * @since 1.0.0
+   *
+   * @example
+   * ```typescript
+   * const result = await client.bpm.getTaskCount({
+   *   assignee: 'user-123'
+   * });
+   * console.log(`You have ${result.data.count} tasks`);
+   * ```
    */
   getTaskCount(params?: TaskQueryParams): Promise<ClientResult<TaskCount>>;
 
   /**
    * Get a single task by ID
-   * 
+   *
    * @param taskId - Task ID
    * @returns Task information
-   * 
+   *
    * @example
    * const result = await client.bpm.getTask('task-123');
    * if (result.success) {
@@ -314,22 +504,19 @@ export interface BpmClientAPI {
 
   /**
    * Complete a user task
-   * 
+   *
    * @param taskId - Task ID
    * @param inputs - Task variables (can be simple object or VariableSubmission)
    * @returns null on success
-   * 
+   *
    * @example
    * // Complete with approval
    * const result = await client.bpm.completeTask('task-123', {
    *   approved: true,
    *   comments: 'Looks good!'
    * });
-   * 
-   * if (result.success) {
-   *   console.log('Task completed');
-   * }
-   * 
+   * ```
+   *
    * @example
    * // Complete with rejection
    * const result = await client.bpm.completeTask('task-456', {
@@ -348,10 +535,20 @@ export interface BpmClientAPI {
 
   /**
    * Query historical process instances
-   * 
+   *
    * @param params - Query parameters
    * @returns Array of historical process instances
    *
+   * @example
+   * Get completed processes:
+   * ```typescript
+   * const result = await client.bpm.getHistoryProcessInstances({
+   *   finished: true,
+   *   processDefinitionKey: 'approval',
+   *   sortBy: 'startTime',
+   *   sortOrder: 'desc'
+   * });
+   * ```
    */
   getHistoryProcessInstances(
     params?: HistoryProcessInstanceQueryParams
@@ -359,10 +556,18 @@ export interface BpmClientAPI {
 
   /**
    * Get historical process instance count
-   * 
+   *
    * @param params - Query parameters
    * @returns Process count
    *
+   * @example
+   * ```typescript
+   * const result = await client.bpm.getHistoryProcessInstanceCount({
+   *   startedBy: 'user-123',
+   *   finished: true
+   * });
+   * console.log(`Completed: ${result.data.count} processes`);
+   * ```
    */
   getHistoryProcessInstanceCount(
     params?: HistoryProcessInstanceQueryParams
@@ -408,7 +613,7 @@ export interface HistoryProcessInstanceQueryParams {
   /** Sort field */
   sortBy?: string;
   /** Sort order */
-  sortOrder?: 'asc' | 'desc';
+  sortOrder?: "asc" | "desc";
   /** Pagination: first result index */
   firstResult?: number;
   /** Pagination: max results to return */