@amaster.ai/client 1.1.0-beta.0

package/types/bpm.d.ts

@@ -0,0 +1,531 @@
+/**
+ * ============================================================================
+ * 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;
+  /** Assignee user ID */
+  assignee: string | null;
+  /** Process instance ID */
+  processInstanceId: string;
+  /** Task definition key */
+  taskDefinitionKey: string;
+  /** Task creation time */
+  created: string;
+  /** Task due date */
+  due: string | null;
+  /** Task priority */
+  priority: number;
+}
+
+/**
+ * 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;
+}
+
+// ==================== 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
+   * Start with simple variables (type auto-inferred):
+   * ```typescript
+   * const result = await client.bpm.startProcess('approval', {
+   *   amount: 1000,
+   *   requester: 'user-123',
+   *   urgent: true
+   * });
+   * ```
+   * 
+   * @example
+   * Start with explicit types:
+   * ```typescript
+   * const result = await client.bpm.startProcess('purchase-order', {
+   *   variables: {
+   *     amount: { value: 5000, type: 'Long' },
+   *     supplier: { value: 'ABC Corp', type: 'String' },
+   *     requestDate: { value: new Date(), type: 'Date' }
+   *   }
+   * });
+   * ```
+   */
+  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 specific process:
+   * ```typescript
+   * const result = await client.bpm.getTasks({
+   *   processInstanceId: 'proc-456',
+   *   assignee: 'manager-789'
+   * });
+   * ```
+   */
+  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
+   * ```typescript
+   * const result = await client.bpm.getTask('task-abc-123');
+   * console.log('Task:', result.data.name);
+   * ```
+   */
+  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 simple variables:
+   * ```typescript
+   * await client.bpm.completeTask('task-123', {
+   *   approved: true,
+   *   comment: 'Looks good!'
+   * });
+   * ```
+   * 
+   * @example
+   * Complete with explicit types:
+   * ```typescript
+   * await client.bpm.completeTask('task-456', {
+   *   variables: {
+   *     approved: { value: false, type: 'Boolean' },
+   *     reason: { value: 'Insufficient budget', type: 'String' }
+   *   }
+   * });
+   * ```
+   */
+  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;
+}

package/types/common.d.ts

@@ -0,0 +1,132 @@
+/**
+ * ============================================================================
+ * Common Types - Shared across all modules
+ * ============================================================================
+ * 
+ * This file contains shared type definitions used by all Amaster client modules.
+ * 
+ * @packageDocumentation
+ */
+
+/**
+ * Standard API response wrapper
+ * 
+ * All Amaster API methods return results wrapped in this structure for
+ * consistent error handling and type safety.
+ * 
+ * @template T - The type of the successful response data
+ * 
+ * @example
+ * Success response:
+ * ```typescript
+ * const result: ClientResult<User> = await client.auth.getMe();
+ * if (result.data) {
+ *   console.log('User:', result.data);  // Type: User
+ * }
+ * ```
+ * 
+ * @example
+ * Error handling:
+ * ```typescript
+ * const result = await client.entity.get('default', 'users', '123');
+ * if (result.error) {
+ *   console.error(`Error ${result.error.status}:`, result.error.message);
+ * }
+ * ```
+ * 
+ * @example
+ * Check by HTTP status:
+ * ```typescript
+ * const result = await client.auth.login({ email, password });
+ * if (result.status === 200 && result.data) {
+ *   // Success
+ * } else if (result.status === 401) {
+ *   // Unauthorized
+ * }
+ * ```
+ */
+export interface ClientResult<T> {
+  /**
+   * Response data (null if error occurred)
+   */
+  data: T | null;
+  
+  /**
+   * Error information (null if successful)
+   */
+  error: {
+    /**
+     * HTTP status code
+     */
+    status: number;
+    
+    /**
+     * Error message
+     */
+    message: string;
+    
+    /**
+     * Additional error details (optional)
+     */
+    details?: unknown;
+  } | null;
+  
+  /**
+   * HTTP response status code
+   */
+  status: number;
+}
+
+/**
+ * HTTP request methods
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+
+/**
+ * Pagination parameters for list queries
+ */
+export interface PaginationParams {
+  /**
+   * Page number (1-based)
+   * @default 1
+   */
+  page?: number;
+  
+  /**
+   * Number of items per page
+   * @default 20
+   */
+  perPage?: number;
+}
+
+/**
+ * Paginated response structure
+ * 
+ * @template T - The type of items in the list
+ */
+export interface PaginatedResult<T> {
+  /**
+   * Array of items for current page
+   */
+  items: T[];
+  
+  /**
+   * Total number of items across all pages
+   */
+  total: number;
+  
+  /**
+   * Current page number (1-based)
+   */
+  page: number;
+  
+  /**
+   * Number of items per page
+   */
+  perPage: number;
+  
+  /**
+   * Total number of pages
+   */
+  totalPages?: number;
+}