@amaster.ai/client 1.1.0-beta.7 → 1.1.0-beta.70

package/types/bpm.d.ts

@@ -2,21 +2,21 @@
  * ============================================================================
  * 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 ====================
 
@@ -24,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)
@@ -47,7 +47,7 @@ export type CamundaVariableValue =
 
 /**
  * Camunda variable with type hint
- * 
+ *
  * @example
  * ```typescript
  * const variable: CamundaVariable = {
@@ -63,7 +63,7 @@ export interface CamundaVariable {
 
 /**
  * Variable submission format for process/task
- * 
+ *
  * @example
  * ```typescript
  * const submission: VariableSubmission = {
@@ -157,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;
 }
 
 /**
@@ -196,33 +228,93 @@ 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, {
@@ -236,32 +328,27 @@ export interface BpmClientAPI {
 
   /**
    * 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', {
+   * // Simple start
+   * const result = await client.bpm.startProcess('approval-process', {
    *   amount: 1000,
-   *   requester: 'user-123',
-   *   urgent: true
+   *   requester: 'john@example.com'
    * });
    * ```
-   * 
+   *
    * @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' }
-   *   }
+   * // 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,
@@ -270,10 +357,10 @@ export interface BpmClientAPI {
 
   /**
    * Query process instances
-   * 
+   *
    * @param params - Query parameters
    * @returns Array of process instances
-   * 
+   *
    * @example
    * Get all active approval processes:
    * ```typescript
@@ -289,27 +376,25 @@ 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');
@@ -322,10 +407,10 @@ 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
@@ -333,7 +418,7 @@ export interface BpmClientAPI {
    *   processInstanceId: 'proc-123'
    * });
    * ```
-   * 
+   *
    * @example
    * Get specific variable:
    * ```typescript
@@ -352,39 +437,45 @@ export interface BpmClientAPI {
 
   /**
    * 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 specific process:
-   * ```typescript
+   * // Get tasks for a process
    * const result = await client.bpm.getTasks({
-   *   processInstanceId: 'proc-456',
-   *   assignee: 'manager-789'
+   *   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({
@@ -397,44 +488,43 @@ export interface BpmClientAPI {
 
   /**
    * 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);
-   * ```
+   * 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 simple variables:
-   * ```typescript
-   * await client.bpm.completeTask('task-123', {
+   * // Complete with approval
+   * const result = await client.bpm.completeTask('task-123', {
    *   approved: true,
-   *   comment: 'Looks good!'
+   *   comments: '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' }
-   *   }
+   * // Complete with rejection
+   * const result = await client.bpm.completeTask('task-456', {
+   *   approved: false,
+   *   reason: 'Missing documentation'
    * });
-   * ```
+   * 
+   * @since 1.0.0
    */
   completeTask(
     taskId: string,
@@ -445,10 +535,10 @@ export interface BpmClientAPI {
 
   /**
    * Query historical process instances
-   * 
+   *
    * @param params - Query parameters
    * @returns Array of historical process instances
-   * 
+   *
    * @example
    * Get completed processes:
    * ```typescript
@@ -466,10 +556,10 @@ export interface BpmClientAPI {
 
   /**
    * Get historical process instance count
-   * 
+   *
    * @param params - Query parameters
    * @returns Process count
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.bpm.getHistoryProcessInstanceCount({
@@ -523,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 */

package/types/common.d.ts

@@ -1,12 +1,38 @@
 /**
- * ============================================================================
- * Common Types - Shared across all modules
- * ============================================================================
+ * Error information structure
  * 
- * This file contains shared type definitions used by all Amaster client modules.
- * 
- * @packageDocumentation
+ * @since 1.1.0
  */
+export interface ClientError {
+  /**
+   * HTTP status code
+   */
+  status: number;
+  
+  /**
+   * Error message
+   */
+  message: string;
+  
+  /**
+   * Application-specific error code (e.g., 'INVALID_TOKEN', 'PERMISSION_DENIED')
+   * 
+   * @since 1.1.0
+   */
+  code?: string;
+  
+  /**
+   * Additional error details (optional)
+   */
+  details?: unknown;
+  
+  /**
+   * Error timestamp (ISO 8601 format)
+   * 
+   * @since 1.1.0
+   */
+  timestamp?: string;
+}
 
 /**
  * Standard API response wrapper
@@ -17,33 +43,21 @@
  * @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);
+ * // Success case
+ * const result = await client.entity.list('default', 'users');
+ * if (result.success) {
+ *   console.log('Data:', result.data);
  * }
- * ```
  * 
  * @example
- * Check by HTTP status:
- * ```typescript
+ * // Error case
  * const result = await client.auth.login({ email, password });
- * if (result.status === 200 && result.data) {
- *   // Success
- * } else if (result.status === 401) {
- *   // Unauthorized
+ * if (!result.success) {
+ *   console.error('Error:', result.error.message);
+ *   console.error('Code:', result.error.code);
  * }
- * ```
+ * 
+ * @since 1.0.0
  */
 export interface ClientResult<T> {
   /**
@@ -54,27 +68,21 @@ export interface ClientResult<T> {
   /**
    * Error information (null if successful)
    */
-  error: {
-    /**
-     * HTTP status code
-     */
-    status: number;
-    
-    /**
-     * Error message
-     */
-    message: string;
-    
-    /**
-     * Additional error details (optional)
-     */
-    details?: unknown;
-  } | null;
+  error: ClientError | null;
   
   /**
    * HTTP response status code
    */
   status: number;
+  
+  /**
+   * Convenience flag for checking if request was successful
+   * 
+   * Equivalent to `error === null`
+   * 
+   * @since 1.1.0
+   */
+  success: boolean;
 }
 
 /**