@amaster.ai/client 1.1.0-beta.72 → 1.1.0-beta.74

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/copilot.d.ts

@@ -80,6 +80,9 @@ interface Conversation {
   status: "submitted" | "working" | "completed" | "error";
   messages: MessagesItem[];
   lastUpdated: string;
+  requestState?: ConversationRequestState;
+  runtimeError?: ConversationRuntimeError | null;
+  role?: Role;
   historyId?: string;
   system?: {
     level: "newConversation";
@@ -92,6 +95,21 @@ interface HistoryState {
   hasMore: boolean;
 }
 
+type ConversationRequestState =
+  | "idle"
+  | "submitting"
+  | "streaming"
+  | "recovering"
+  | "error";
+
+interface ConversationRuntimeError {
+  code: "network" | "unknown";
+  message: string;
+  retryable: boolean;
+  source: "send" | "stream" | "recovery";
+  timestamp: string;
+}
+
 interface UpdateMessageInput {
   taskId: string;
   messageId: string;
@@ -120,8 +138,6 @@ interface ConversationControllerOptions {
   strings: ConversationStrings;
   mode?: "conversation" | "single-turn";
   getContextId?: () => string;
-  loadHistoryOnInit?: boolean;
-  resumeOnInit?: boolean;
 }
 
 interface ConversationController {
@@ -142,17 +158,121 @@ interface ConversationController {
   updateMessage(input: UpdateMessageInput): void;
 }
 
+interface AutoVoiceReplyMessage {
+  messageId?: string;
+  role?: string;
+  kind: string;
+  content?: string;
+}
+
+interface AutoVoiceReplyConversation {
+  taskId: string;
+  status: string;
+  requestState?: string;
+  messages: AutoVoiceReplyMessage[];
+}
+
+interface AutoVoiceReplySourceSnapshot {
+  conversations: AutoVoiceReplyConversation[];
+  isLoading: boolean;
+}
+
+interface AutoVoiceReplySource {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): AutoVoiceReplySourceSnapshot;
+}
+
+interface AutoVoiceReplySpeechSnapshot {
+  status: "idle" | "connecting" | "speaking" | "error";
+  error?: string | null;
+  voice?: string | null;
+}
+
+interface AutoVoiceReplySpeechDriver {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): AutoVoiceReplySpeechSnapshot;
+  startStream(input: {
+    id: string;
+    voice?: string | null;
+    audioFormat?: "pcm" | "mp3" | "wav" | "opus";
+    sampleRate?: number;
+  }): Promise<void>;
+  appendText(input: { id: string; text: string }): Promise<void>;
+  commit(): void;
+  finish(): void;
+  stop(): void;
+  setVoice?(voice: string | null): void;
+  getVoice?(): string | null;
+}
+
+interface AutoVoiceReplyStorage {
+  getItem(key: string): string | null | undefined;
+  setItem(key: string, value: string): void;
+}
+
+interface AutoVoiceReplySnapshot {
+  enabled: boolean;
+  status: "idle" | "connecting" | "speaking" | "error";
+  connecting: boolean;
+  speaking: boolean;
+  voice: string | null;
+  activeTaskId: string | null;
+  suppressedTaskId: string | null;
+  error: string | null;
+}
+
+interface AutoVoiceReplyController {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): AutoVoiceReplySnapshot;
+  setEnabled(enabled: boolean): void;
+  toggleEnabled(): void;
+  toggleEnabledOrStop(): void;
+  stop(): void;
+  setVoice(voice: string | null): void;
+  getVoice(): string | null;
+  destroy(): void;
+}
+
+interface CreateAutoVoiceReplyControllerOptions {
+  source: AutoVoiceReplySource;
+  speech: AutoVoiceReplySpeechDriver;
+  storage?: AutoVoiceReplyStorage;
+  enabledStorageKey?: string;
+  defaultVoice?: string | null;
+  id?: string;
+  audioFormat?: "pcm" | "mp3" | "wav" | "opus";
+  sampleRate?: number;
+  preprocessText?: (text: string) => string;
+}
+
 type CopilotClientAPI = {
   createConversationController(options: ConversationControllerOptions): ConversationController;
 };
 
+declare function createAutoVoiceReplyController(
+  options: CreateAutoVoiceReplyControllerOptions
+): AutoVoiceReplyController;
+
 export {
+  createAutoVoiceReplyController,
+  type AutoVoiceReplyController,
+  type AutoVoiceReplyConversation,
+  type AutoVoiceReplyMessage,
+  type AutoVoiceReplySnapshot,
+  type AutoVoiceReplySource,
+  type AutoVoiceReplySourceSnapshot,
+  type AutoVoiceReplySpeechDriver,
+  type AutoVoiceReplySpeechSnapshot,
+  type AutoVoiceReplyStorage,
   type CopilotClientAPI,
   type ConversationController,
   type ConversationControllerOptions,
   type ConversationControllerSnapshot,
+  type ConversationRequestState,
+  type ConversationRuntimeError,
   type ConversationStrings,
   type Conversation,
+  type CreateAutoVoiceReplyControllerOptions,
   type MessagesItem,
   type TextMessage,
   type ErrorMessage,