@amaster.ai/client 1.0.0-alpha.1

package/types/bpm.d.ts

@@ -0,0 +1,621 @@
+/**
+ * ============================================================================
+ * 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";
+
+// ==================== Variable Types ====================
+
+/**
+ * Camunda variable type
+ */
+export type CamundaVariableType =
+  | "String"
+  | "Boolean"
+  | "Integer"
+  | "Long"
+  | "Double"
+  | "Date"
+  | "Json";
+
+/**
+ * Camunda variable value (can be any JSON-serializable type)
+ */
+export type CamundaVariableValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | null
+  | undefined
+  | Record<string, unknown>
+  | unknown[];
+
+/**
+ * Camunda variable with type hint
+ *
+ * @example
+ * ```typescript
+ * const variable: CamundaVariable = {
+ *   value: 1000,
+ *   type: 'Long'
+ * };
+ * ```
+ */
+export interface CamundaVariable {
+  value: CamundaVariableValue;
+  type?: CamundaVariableType;
+}
+
+/**
+ * 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>;
+}
+
+// ==================== Process Types ====================
+
+/**
+ * Process instance information
+ */
+export interface ProcessInstance {
+  /** Process instance ID (UUID) */
+  id: string;
+  /** Process definition ID */
+  definitionId?: string;
+  /** Business key for correlation */
+  businessKey?: string;
+  /** Whether the process has ended */
+  ended?: boolean;
+  /** Whether the process is suspended */
+  suspended?: boolean;
+}
+
+/**
+ * Process instance query parameters
+ */
+export interface ProcessInstanceQueryParams {
+  /** Filter by process definition key */
+  processDefinitionKey?: string;
+  /** Filter active/inactive processes */
+  active?: boolean;
+  /** Pagination: first result index */
+  firstResult?: number;
+  /** Pagination: max results to return */
+  maxResults?: number;
+}
+
+/**
+ * Historical process instance
+ */
+export interface HistoryProcessInstance {
+  /** Process instance ID */
+  id: string;
+  /** Business key */
+  businessKey: string;
+  /** Process definition ID */
+  processDefinitionId: string;
+  /** Process definition key */
+  processDefinitionKey: string;
+  /** Process definition name */
+  processDefinitionName: string;
+  /** Process definition version */
+  processDefinitionVersion: number;
+  /** Start timestamp (ISO 8601) */
+  startTime: string;
+  /** End timestamp (null if still running) */
+  endTime: string | null;
+  /** Duration in milliseconds (null if still running) */
+  durationInMillis: number | null;
+  /** User who started the process */
+  startUserId: string;
+  /** Start activity ID */
+  startActivityId: string;
+  /** Delete reason (if deleted) */
+  deleteReason: string | null;
+  /** Process state */
+  state: string;
+  /** Parent process instance ID (if subprocess) */
+  superProcessInstanceId?: string;
+  /** Parent case instance ID (if CMMN) */
+  superCaseInstanceId?: string;
+}
+
+// ==================== Task Types ====================
+
+/**
+ * User task information
+ */
+export interface Task {
+  /** 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 creation time */
+  created?: string | null;
+  /** Task due date */
+  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;
+  /** 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;
+}
+
+/**
+ * Task query parameters
+ */
+export interface TaskQueryParams {
+  /** Filter by assignee */
+  assignee?: string;
+  /** Filter by process definition key */
+  processDefinitionKey?: string;
+  /** Filter by task definition key */
+  taskDefinitionKey?: string;
+  /** Filter by process instance ID */
+  processInstanceId?: string;
+  /** Pagination: first result index */
+  firstResult?: number;
+  /** Pagination: max results to return */
+  maxResults?: number;
+}
+
+/**
+ * Task count result
+ */
+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.
+ *
+ * @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'
+   * });
+   * ```
+   *
+   * @example
+   * // With business key
+   * const result = await client.bpm.startProcess('order-fulfillment', {
+   *   orderId: 'ORDER-12345',
+   *   items: [{ sku: 'ITEM-1', qty: 2 }]
+   * });
+   * 
+   * @since 1.0.0
+   */
+  startProcess(
+    processKey: string,
+    inputs?: Record<string, CamundaVariableValue> | VariableSubmission
+  ): Promise<ClientResult<ProcessInstance>>;
+
+  /**
+   * 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
+  ): Promise<ClientResult<ProcessInstance[]>>;
+
+  /**
+   * 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>>;
+
+  /**
+   * 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,
+    params?: { skipCustomListeners?: boolean }
+  ): Promise<ClientResult<null>>;
+
+  /**
+   * 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;
+    variableName?: string;
+  }): Promise<ClientResult<ProcessVariable[]>>;
+
+  // ==================== Task Management ====================
+
+  /**
+   * Query user tasks
+   *
+   * @param params - Query parameters
+   * @returns Array of tasks
+   *
+   * @example
+   * 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({
+   *   assignee: 'currentUserId'
+   * });
+   * 
+   * @example
+   * // Get tasks for a process
+   * const result = await client.bpm.getTasks({
+   *   processDefinitionKey: 'approval-process',
+   *   maxResults: 10
+   * });
+   * 
+   * @since 1.0.0
+   */
+  getTasks(params?: TaskQueryParams): Promise<ClientResult<Task[]>>;
+
+  /**
+   * Get task count
+   *
+   * @param params - Query parameters
+   * @returns Task count
+   *
+   * @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) {
+   *   console.log('Task:', result.data.name);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  getTask(taskId: string): Promise<ClientResult<Task>>;
+
+  /**
+   * 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!'
+   * });
+   * ```
+   *
+   * @example
+   * // Complete with rejection
+   * const result = await client.bpm.completeTask('task-456', {
+   *   approved: false,
+   *   reason: 'Missing documentation'
+   * });
+   * 
+   * @since 1.0.0
+   */
+  completeTask(
+    taskId: string,
+    inputs: Record<string, CamundaVariableValue> | VariableSubmission
+  ): Promise<ClientResult<null>>;
+
+  // ==================== History & Reporting ====================
+
+  /**
+   * 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
+  ): Promise<ClientResult<HistoryProcessInstance[]>>;
+
+  /**
+   * 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
+  ): Promise<ClientResult<{ count: number }>>;
+}
+
+/**
+ * Process variable information
+ */
+export interface ProcessVariable {
+  /** Variable ID */
+  id: string;
+  /** Variable name */
+  name: string;
+  /** Variable type */
+  type: string;
+  /** Variable value */
+  value: CamundaVariableValue;
+  /** Process instance ID */
+  processInstanceId: string;
+  /** Creation time */
+  createTime?: string;
+  /** Activity instance ID */
+  activityInstanceId?: string;
+  /** Task ID (if task variable) */
+  taskId?: string;
+  /** Execution ID */
+  executionId?: string;
+  /** Error message (if any) */
+  errorMessage?: string;
+}
+
+/**
+ * Historical process instance query parameters
+ */
+export interface HistoryProcessInstanceQueryParams {
+  /** Filter by user who started the process */
+  startedBy?: string;
+  /** Filter finished/unfinished processes */
+  finished?: boolean;
+  /** Filter by process definition key */
+  processDefinitionKey?: string;
+  /** Sort field */
+  sortBy?: string;
+  /** Sort order */
+  sortOrder?: "asc" | "desc";
+  /** Pagination: first result index */
+  firstResult?: number;
+  /** Pagination: max results to return */
+  maxResults?: number;
+}