@amaster.ai/client 1.1.3 → 1.1.4

package/types/bpm.d.ts

@@ -338,7 +338,7 @@ export interface HistoryTask {
  * @example
  * Complete BPM flow:
  * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
+* const client = createClient();
  *
  * // 1. Start a process
  * const process = await client.bpm.startProcess('approval', {
@@ -534,7 +534,7 @@ export interface BpmClientAPI {
    *
    * @example
    * const result = await client.bpm.getTask('task-123');
-   * if (result.success) {
+   * if (result.data) {
    *   console.log('Task:', result.data.name);
    * }
    * 
@@ -640,12 +640,137 @@ export interface BpmClientAPI {
     params?: HistoryProcessInstanceQueryParams
   ): Promise<ClientResult<{ count: number }>>;
 
+  /**
+   * Get a single historical process instance by ID
+   */
+  getHistoryProcessInstance(
+    processInstanceId: string
+  ): Promise<ClientResult<HistoryProcessInstance>>;
+
+  /**
+   * Query process variables by process instance
+   */
+  getProcessVariables(params: {
+    processInstanceId: string;
+    variableName?: string;
+  }): Promise<ClientResult<ProcessVariable[]>>;
+
+  /**
+   * Get process definition list
+   */
+  getProcessDefinitions(
+    params?: ProcessDefinitionQueryParams
+  ): Promise<ClientResult<ProcessDefinitionFull[]>>;
+
+  /**
+   * Get BPMN XML for a process definition key
+   */
+  getProcessXml(processKey: string): Promise<ClientResult<ProcessXmlResponse>>;
+
+  /**
+   * Get the runtime activity instance tree for a process instance
+   */
+  getActivityInstanceTree(
+    processInstanceId: string
+  ): Promise<ClientResult<ActivityInstanceTree>>;
+
+  /**
+   * Get runtime variables for a process instance
+   */
+  getRuntimeVariables(
+    processInstanceId: string
+  ): Promise<ClientResult<Record<string, { value: CamundaVariableValue; type: string }>>>;
+
+  /**
+   * Delegate a task to another user
+   */
+  delegateTask(taskId: string, userId: string): Promise<ClientResult<null>>;
+
+  /**
+   * Get task form metadata
+   */
+  getTaskForm(taskId: string): Promise<ClientResult<TaskFormData>>;
+
+  /**
+   * Get rendered task form HTML
+   */
+  getTaskRenderedForm(taskId: string): Promise<ClientResult<string>>;
+
   /**
    * Get deployed Camunda form definition for a task
    */
   getTaskDeployedForm(
     taskId: string
   ): Promise<ClientResult<CamundaFormDefinition>>;
+
+  /**
+   * Get start form metadata
+   */
+  getStartFormInfo(processKey: string): Promise<ClientResult<StartFormInfo>>;
+
+  /**
+   * Get start form variables
+   */
+  getStartFormVariables(processKey: string): Promise<ClientResult<TaskFormVariables>>;
+
+  /**
+   * Get deployed start form definition
+   */
+  getDeployedStartForm(processKey: string): Promise<ClientResult<CamundaFormDefinition>>;
+
+  /**
+   * Query historical activity instances
+   */
+  getHistoryActivityInstances(
+    params?: HistoryActivityQueryParams
+  ): Promise<ClientResult<HistoryActivityInstance[]>>;
+
+  /**
+   * Query historical variable instances
+   */
+  getHistoryVariableInstances(
+    params?: HistoryVariableQueryParams
+  ): Promise<ClientResult<HistoryVariableInstance[]>>;
+
+  /**
+   * Query user operation logs
+   */
+  getUserOperationLogs(
+    params?: UserOperationLogQueryParams
+  ): Promise<ClientResult<UserOperationLog[]>>;
+
+  /**
+   * Delete a historical process instance
+   */
+  deleteHistoryProcessInstance(processInstanceId: string): Promise<ClientResult<null>>;
+
+  /**
+   * Suspend a running process instance
+   */
+  suspendProcessInstance(processInstanceId: string): Promise<ClientResult<null>>;
+
+  /**
+   * Activate a suspended process instance
+   */
+  activateProcessInstance(processInstanceId: string): Promise<ClientResult<null>>;
+
+  /**
+   * Modify a process instance for jump/cancel/start operations
+   */
+  modifyProcessInstance(
+    processInstanceId: string,
+    modification: ProcessInstanceModification
+  ): Promise<ClientResult<null>>;
+
+  /**
+   * Get available roles in the current tenant
+   */
+  getRoles(): Promise<ClientResult<Role[]>>;
+
+  /**
+   * Get roles assigned to a user
+   */
+  getUserRoles(userId: string): Promise<ClientResult<Role[]>>;
 }
 
 /**
@@ -682,8 +807,12 @@ export interface HistoryProcessInstanceQueryParams {
   startedBy?: string;
   /** Filter finished/unfinished processes */
   finished?: boolean;
+  /** Filter unfinished processes */
+  unfinished?: boolean;
   /** Filter by process definition key */
   processDefinitionKey?: string;
+  /** Access scope: strict "my initiated" view */
+  scope?: "initiated";
   /** Sort field */
   sortBy?: string;
   /** Sort order */
@@ -706,6 +835,8 @@ export interface HistoryTaskQueryParams {
   finished?: boolean;
   /** Filter unfinished tasks */
   unfinished?: boolean;
+  /** Access scope: strict "my handled" view */
+  scope?: "handled";
   /** Pagination: first result index */
   firstResult?: number;
   /** Pagination: max results to return */
@@ -742,3 +873,235 @@ export interface CamundaFormComponent {
   values?: Array<{ label: string; value: string }>;
   properties?: Record<string, unknown>;
 }
+
+/**
+ * Full process definition information
+ */
+export interface ProcessDefinitionFull {
+  id: string;
+  key: string;
+  name: string;
+  version: number;
+  deploymentId: string;
+  resourceName: string;
+  category?: string;
+  description?: string;
+  diagram?: string;
+  suspended: boolean;
+  tenantId?: string;
+  versionTag?: string;
+  historyTimeToLive?: number;
+  startableInTasklist: boolean;
+}
+
+/**
+ * Process definition query parameters
+ */
+export interface ProcessDefinitionQueryParams {
+  key?: string;
+  name?: string;
+  latestVersion?: boolean;
+  active?: boolean;
+  suspended?: boolean;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * BPMN XML response
+ */
+export interface ProcessXmlResponse {
+  bpmn20Xml: string;
+  processDefinitionId: string;
+}
+
+/**
+ * Runtime activity instance tree
+ */
+export interface ActivityInstanceTree {
+  id: string;
+  activityId: string;
+  activityName: string;
+  activityType: string;
+  processInstanceId: string;
+  processDefinitionId: string;
+  childActivityInstances: ActivityInstanceTree[];
+  childTransitionInstances: TransitionInstance[];
+  executionIds: string[];
+  incidentIds: string[];
+}
+
+/**
+ * Runtime transition instance
+ */
+export interface TransitionInstance {
+  id: string;
+  activityId: string;
+  activityName: string;
+  activityType: string;
+  processInstanceId: string;
+  processDefinitionId: string;
+  executionId: string;
+  incidentIds: string[];
+}
+
+/**
+ * Historical activity instance
+ */
+export interface HistoryActivityInstance {
+  id: string;
+  activityId: string;
+  activityName: string;
+  activityType: string;
+  processDefinitionId: string;
+  processDefinitionKey: string;
+  processInstanceId: string;
+  executionId: string;
+  taskId?: string;
+  assignee?: string;
+  calledProcessInstanceId?: string;
+  calledCaseInstanceId?: string;
+  startTime: string;
+  endTime?: string;
+  durationInMillis?: number;
+  canceled: boolean;
+  completeScope: boolean;
+  tenantId?: string;
+  removalTime?: string;
+  rootProcessInstanceId: string;
+}
+
+/**
+ * Historical activity query parameters
+ */
+export interface HistoryActivityQueryParams {
+  processInstanceId?: string;
+  activityId?: string;
+  activityType?: string;
+  finished?: boolean;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * Historical variable instance
+ */
+export interface HistoryVariableInstance {
+  id: string;
+  name: string;
+  type: string;
+  value: CamundaVariableValue;
+  valueInfo?: Record<string, unknown>;
+  processDefinitionKey: string;
+  processDefinitionId: string;
+  processInstanceId: string;
+  executionId: string;
+  activityInstanceId?: string;
+  taskId?: string;
+  tenantId?: string;
+  errorMessage?: string;
+  state: string;
+  createTime: string;
+  removalTime?: string;
+  rootProcessInstanceId: string;
+}
+
+/**
+ * Historical variable query parameters
+ */
+export interface HistoryVariableQueryParams {
+  processInstanceId?: string;
+  variableName?: string;
+  deserializeValues?: boolean;
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * Task form metadata
+ */
+export interface TaskFormData {
+  key?: string;
+  contextPath?: string;
+  camundaFormRef?: {
+    key: string;
+    binding: string;
+    version?: number;
+  };
+}
+
+/**
+ * Start form metadata
+ */
+export interface StartFormInfo {
+  key?: string;
+  contextPath?: string;
+  camundaFormRef?: {
+    key: string;
+    binding: string;
+    version?: number;
+  };
+}
+
+/**
+ * User operation log entry
+ */
+export interface UserOperationLog {
+  id: string;
+  processDefinitionId?: string;
+  processDefinitionKey?: string;
+  processInstanceId?: string;
+  executionId?: string;
+  taskId?: string;
+  userId: string;
+  timestamp: string;
+  operationId: string;
+  operationType: string;
+  entityType: string;
+  property?: string;
+  orgValue?: string;
+  newValue?: string;
+  tenantId?: string;
+}
+
+/**
+ * User operation log query parameters
+ */
+export interface UserOperationLogQueryParams {
+  processInstanceId?: string;
+  taskId?: string;
+  userId?: string;
+  operationType?: string;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+  firstResult?: number;
+  maxResults?: number;
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * Process instance modification request
+ */
+export interface ProcessInstanceModification {
+  instructions: Array<{
+    type: 'cancel' | 'startBeforeActivity' | 'startAfterActivity' | 'startTransition';
+    activityId?: string;
+    transitionId?: string;
+    activityInstanceId?: string;
+    transitionInstanceId?: string;
+    ancestorActivityInstanceId?: string;
+    variables?: Record<string, { value: CamundaVariableValue; type?: string }>;
+  }>;
+  skipCustomListeners?: boolean;
+  skipIoMappings?: boolean;
+}
+
+/**
+ * BPM role information
+ */
+export interface Role {
+  code: string;
+  name: string;
+  description?: string;
+}

package/types/common.d.ts

@@ -1,62 +1,53 @@
 /**
  * Error information structure
- * 
+ *
  * @since 1.1.0
  */
 export interface ClientError {
-  /**
-   * HTTP status code
-   */
-  status: number;
-  
   /**
    * Error message
    */
   message: string;
-  
+
+  /**
+   * HTTP status code
+   */
+  status?: number;
+
   /**
    * 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
- * 
+ *
  * 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 case
  * const result = await client.entity.list('default', 'users');
- * if (result.success) {
+ * if (result.data) {
  *   console.log('Data:', result.data);
  * }
- * 
+ *
  * @example
  * // Error case
  * const result = await client.auth.login({ email, password });
- * if (!result.success) {
+ * if (result.error) {
  *   console.error('Error:', result.error.message);
  *   console.error('Code:', result.error.code);
  * }
- * 
+ *
  * @since 1.0.0
  */
 export interface ClientResult<T> {
@@ -64,25 +55,16 @@ export interface ClientResult<T> {
    * Response data (null if error occurred)
    */
   data: T | null;
-  
+
   /**
    * Error information (null if successful)
    */
   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;
 }
 
 /**
@@ -99,7 +81,7 @@ export interface PaginationParams {
    * @default 1
    */
   page?: number;
-  
+
   /**
    * Number of items per page
    * @default 20
@@ -109,7 +91,7 @@ export interface PaginationParams {
 
 /**
  * Paginated response structure
- * 
+ *
  * @template T - The type of items in the list
  */
 export interface PaginatedResult<T> {
@@ -117,22 +99,22 @@ 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
    */

package/types/entity.d.ts

@@ -241,7 +241,7 @@ export interface EntityClientAPI {
    * // With type safety
    * type User = { id: number; name: string; email: string };
    * const result = await client.entity.list<User>('default', 'users');
-   * if (result.success) {
+   * if (result.data) {
    *   result.data.items.forEach(user => {
    *     console.log(user.name); // Type-safe
    *   });
@@ -266,7 +266,7 @@ export interface EntityClientAPI {
    * 
    * @example
    * const result = await client.entity.get('default', 'users', 123);
-   * if (result.success) {
+   * if (result.data) {
    *   console.log('User:', result.data);
    * }
    * 
@@ -299,7 +299,7 @@ export interface EntityClientAPI {
    *   status: 'active'
    * });
    * 
-   * if (result.success) {
+   * if (result.data) {
    *   console.log('Created user with ID:', result.data.id);
    * }
    * 
@@ -327,7 +327,7 @@ export interface EntityClientAPI {
    *   status: 'inactive'
    * });
    * 
-   * if (result.success) {
+   * if (result.data) {
    *   console.log('Updated:', result.data);
    * }
    * 
@@ -350,7 +350,7 @@ export interface EntityClientAPI {
    * 
    * @example
    * const result = await client.entity.delete('default', 'users', 123);
-   * if (result.success) {
+   * if (!result.error) {
    *   console.log('User deleted');
    * }
    * 
@@ -373,7 +373,7 @@ export interface EntityClientAPI {
    * 
    * @example
    * const result = await client.entity.options('default', 'users', ['id', 'name']);
-   * if (result.success) {
+   * if (result.data) {
    *   result.data.forEach(opt => console.log(opt.name));
    * }
    * 
@@ -419,7 +419,7 @@ export interface EntityClientAPI {
    * 
    * @example
    * const result = await client.entity.bulkDelete('default', 'users', [1, 2, 3]);
-   * if (result.success) {
+   * if (!result.error) {
    *   console.log('3 users deleted');
    * }
    * 

package/types/function.d.ts

@@ -28,7 +28,7 @@ export interface FunctionClientAPI {
    *   body: 'Welcome!'
    * });
    * 
-   * if (result.success) {
+   * if (result.data) {
    *   console.log(result.data.message);
    * }
    *