@amaster.ai/client 1.1.0-beta.30 → 1.1.0-beta.31

package/types/bpm.d.ts

@@ -1,17 +1,4 @@
 /**
- * ============================================================================
- * 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
  */
@@ -47,14 +34,7 @@ export type CamundaVariableValue =
 
 /**
  * Camunda variable with type hint
- * 
- * @example
- * ```typescript
- * const variable: CamundaVariable = {
- *   value: 1000,
- *   type: 'Long'
- * };
- * ```
+ *
  */
 export interface CamundaVariable {
   value: CamundaVariableValue;
@@ -63,17 +43,7 @@ export interface CamundaVariable {
 
 /**
  * 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>;
@@ -203,33 +173,7 @@ export interface TaskCount {
  * 
  * 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' }
- * });
- * ```
+ * @since 1.0.0
  */
 export interface BpmClientAPI {
   // ==================== Process Management ====================
@@ -242,26 +186,24 @@ export interface BpmClientAPI {
    * @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'
    * });
-   * ```
+   * 
+   * if (result.success) {
+   *   console.log('Process started:', result.data.id);
+   * }
    * 
    * @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,
@@ -273,15 +215,7 @@ export interface BpmClientAPI {
    * 
    * @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
@@ -292,12 +226,7 @@ export interface BpmClientAPI {
    * 
    * @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
@@ -309,11 +238,7 @@ export interface BpmClientAPI {
    * @param processInstanceId - Process instance ID
    * @param params - Optional parameters
    * @returns null on success
-   * 
-   * @example
-   * ```typescript
-   * await client.bpm.deleteProcessInstance('proc-123');
-   * ```
+   *
    */
   deleteProcessInstance(
     processInstanceId: string,
@@ -325,23 +250,7 @@ export interface BpmClientAPI {
    * 
    * @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;
@@ -357,25 +266,23 @@ export interface BpmClientAPI {
    * @returns Array of tasks
    * 
    * @example
-   * Get tasks assigned to current user:
-   * ```typescript
-   * const result = await client.bpm.getTasks({
-   *   assignee: 'user-123'
-   * });
+   * // Get all tasks
+   * const result = await client.bpm.getTasks();
    * 
-   * 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[]>>;
 
@@ -385,13 +292,7 @@ export interface BpmClientAPI {
    * @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`);
-   * ```
+   * @since 1.0.0
    */
   getTaskCount(params?: TaskQueryParams): Promise<ClientResult<TaskCount>>;
 
@@ -402,10 +303,12 @@ export interface BpmClientAPI {
    * @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>>;
 
@@ -417,24 +320,24 @@ export interface BpmClientAPI {
    * @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!'
    * });
-   * ```
+   * 
+   * if (result.success) {
+   *   console.log('Task completed');
+   * }
    * 
    * @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,
@@ -448,17 +351,7 @@ export interface BpmClientAPI {
    * 
    * @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
@@ -469,15 +362,7 @@ export interface BpmClientAPI {
    * 
    * @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

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;
 }
 
 /**

package/types/copilot.d.ts

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * Copilot AI Assistant - Type Definitions
- * ============================================================================
- * 
- * AI-powered assistant for interactive conversations and task assistance.
+ *  * AI-powered assistant for interactive conversations and task assistance.
  * 
  * @module copilot
  */
@@ -105,26 +101,7 @@ export interface DeleteSurfaceMessage {
  * 
  * Used by the chat() streaming API to send UI updates.
  * Each message can contain one of several update types.
- * 
- * @example
- * ```typescript
- * const stream = client.copilot.chat([
- *   { role: 'user', content: 'Show me a chart' }
- * ]);
- * 
- * for await (const messages of stream) {
- *   for (const msg of messages) {
- *     if (msg.surfaceUpdate) {
- *       // Render UI components
- *       renderComponents(msg.surfaceUpdate.components);
- *     }
- *     if (msg.dataModelUpdate) {
- *       // Update data bindings
- *       updateData(msg.dataModelUpdate.contents);
- *     }
- *   }
- * }
- * ```
+ *
  */
 export interface ServerToClientMessage {
   beginRendering?: BeginRenderingMessage;
@@ -187,27 +164,7 @@ export type MessageContent = TextContent | ImageContent | FileContent;
 
 /**
  * Chat message
- * 
- * @example
- * Text message:
- * ```typescript
- * const message: ChatMessage = {
- *   role: 'user',
- *   content: 'Hello, how can you help me?'
- * };
- * ```
- * 
- * @example
- * Message with image:
- * ```typescript
- * const message: ChatMessage = {
- *   role: 'user',
- *   content: [
- *     { type: 'text', text: 'What is in this image?' },
- *     { type: 'image', imageUrl: 'https://example.com/image.jpg' }
- *   ]
- * };
- * ```
+ *
  */
 export interface ChatMessage {
   /** Message role */
@@ -241,51 +198,9 @@ export interface ChatOptions {  /** Task ID for conversation continuity */
 /**
  * Copilot AI Assistant Client API
  * 
- * @example
- * Basic chat:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * const stream = client.copilot.chat([
- *   { role: 'user', content: 'Hello, how are you?' }
- * ]);
- * 
- * for await (const messages of stream) {
- *   // Process A2UI messages
- * }
- * ```
- * 
- * @example
- * With task ID for conversation continuity:
- * ```typescript
- * const stream = client.copilot.chat(
- *   [{ role: 'user', content: 'Tell me a story' }],
- *   { taskId: 'conv-123' }
- * );
- * 
- * for await (const messages of stream) {
- *   for (const msg of messages) {
- *     if (msg.dataModelUpdate) {
- *       // Extract and display text content
- *     }
- *   }
- * }
- * ```
- * 
- * @example
- * Multi-turn conversation:
- * ```typescript
- * const conversation: ChatMessage[] = [
- *   { role: 'system', content: 'You are a helpful assistant' },
- *   { role: 'user', content: 'What is TypeScript?' }
- * ];
- * 
- * for await (const messages of client.copilot.chat(conversation)) {
- *   // Process streaming response
- * }
- * ```
+ * @since 1.0.0
  */
-export interface CopilotA2UIClient {
+export interface CopilotClientAPI {
   /**
    * Start a streaming chat session with the AI assistant
    * 
@@ -297,41 +212,43 @@ export interface CopilotA2UIClient {
    * @returns AsyncGenerator yielding arrays of A2UI messages
    * 
    * @example
-   * Simple chat:
-   * ```typescript
-   * const stream = client.copilot.chat([
-   *   { role: 'user', content: 'What is the capital of France?' }
+   * // Simple chat
+   * const chatStream = client.copilot.chat([
+   *   { role: 'user', content: 'Hello, how can you help me?' }
    * ]);
    * 
-   * for await (const messages of stream) {
-   *   // Process A2UI updates
+   * for await (const messages of chatStream) {
+   *   messages.forEach(msg => {
+   *     if (msg.surfaceUpdate) {
+   *       console.log('UI update:', msg.surfaceUpdate);
+   *     }
+   *   });
    * }
-   * ```
    * 
    * @example
-   * With system prompt:
-   * ```typescript
-   * const stream = client.copilot.chat([
-   *   { role: 'system', content: 'You are a helpful coding assistant' },
-   *   { role: 'user', content: 'How do I reverse a string in JavaScript?' }
-   * ]);
-   * ```
+   * // With conversation history
+   * const chatStream = client.copilot.chat([
+   *   { role: 'system', content: 'You are a helpful assistant.' },
+   *   { role: 'user', content: 'What is TypeScript?' },
+   *   { role: 'assistant', content: 'TypeScript is...' },
+   *   { role: 'user', content: 'Can you give an example?' }
+   * ], {
+   *   taskId: 'conversation-123'
+   * });
    * 
    * @example
-   * Extracting text content from A2UI messages:
-   * ```typescript
-   * for await (const messages of stream) {
-   *   for (const msg of messages) {
-   *     if (msg.dataModelUpdate?.contents) {
-   *       for (const content of msg.dataModelUpdate.contents) {
-   *         if (content.valueString) {
-   *           console.log(content.valueString); // Display text
-   *         }
-   *       }
-   *     }
+   * // With image content
+   * const chatStream = client.copilot.chat([
+   *   {
+   *     role: 'user',
+   *     content: [
+   *       { type: 'text', text: 'What is in this image?' },
+   *       { type: 'image', imageUrl: 'https://example.com/image.jpg' }
+   *     ]
    *   }
-   * }
-   * ```
+   * ]);
+   * 
+   * @since 1.0.0
    */
   chat(
     messages: ChatMessage[],
@@ -343,6 +260,14 @@ export interface CopilotA2UIClient {
    * 
    * @param taskId - Task ID to cancel
    * @returns Cancellation result
+   * 
+   * @example
+   * const result = await client.copilot.cancelChat('task-123');
+   * if (result.success) {
+   *   console.log('Chat cancelled');
+   * }
+   * 
+   * @since 1.0.0
    */
   cancelChat(taskId: string): Promise<ClientResult<unknown>>;
 
@@ -351,6 +276,14 @@ export interface CopilotA2UIClient {
    * 
    * @param taskId - Task ID to query
    * @returns Task status information
+   * 
+   * @example
+   * const result = await client.copilot.getChatStatus('task-123');
+   * if (result.success) {
+   *   console.log('Status:', result.data);
+   * }
+   * 
+   * @since 1.0.0
    */
   getChatStatus(taskId: string): Promise<ClientResult<unknown>>;
 }