@amaster.ai/client 1.1.0-beta.5 → 1.1.0-beta.50

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,335 +1,49 @@
-/**
- * ============================================================================
- * Copilot AI Assistant - Type Definitions
- * ============================================================================
- * 
- * AI-powered assistant for interactive conversations and task assistance.
- * 
- * @module copilot
- */
-
+import type { SendStreamingMessageResponse, CancelTaskResponse, GetTaskResponse } from '@a2a-js/sdk';
 import type { ClientResult } from './common';
 
-// ============================================================================
-// A2UI Protocol Types (for streaming UI)
-// ============================================================================
-
-/**
- * String value with data binding support
- */
-export interface StringValue {
-  path?: string;
-  literalString?: string;
-  literal?: string;
-}
-
-/**
- * Number value with data binding support
- */
-export interface NumberValue {
-  path?: string;
-  literalNumber?: number;
-  literal?: number;
-}
-
-/**
- * Boolean value with data binding support
- */
-export interface BooleanValue {
-  path?: string;
-  literalBoolean?: boolean;
-  literal?: boolean;
-}
-
-/**
- * Component properties in A2UI protocol
- */
-export type ComponentProperties = Record<string, unknown>;
-
-/**
- * Component instance from server
- */
-export interface ComponentInstance {
-  id: string;
-  weight?: number;
-  component?: ComponentProperties;
-}
-
-/**
- * Value map for data model updates
- */
-export interface ValueMap {
-  key: string;
-  valueString?: string;
-  valueNumber?: number;
-  valueBoolean?: boolean;
-  valueMap?: ValueMap[];
-  [k: string]: unknown;
-}
-
-/**
- * Begin rendering message - initializes a new UI surface
- */
-export interface BeginRenderingMessage {
-  surfaceId: string;
-  root: string;
-  styles?: Record<string, string>;
-}
-
-/**
- * Surface update message - updates UI components
- */
-export interface SurfaceUpdateMessage {
-  surfaceId: string;
-  components: ComponentInstance[];
-}
-
-/**
- * Data model update message - updates data bindings
- */
-export interface DataModelUpdate {
-  surfaceId: string;
-  path?: string;
-  contents: ValueMap[];
-}
-
-/**
- * Delete surface message - removes a UI surface
- */
-export interface DeleteSurfaceMessage {
-  surfaceId: string;
-}
-
-/**
- * Server-to-client message in A2UI protocol
- * 
- * 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;
-  surfaceUpdate?: SurfaceUpdateMessage;
-  dataModelUpdate?: DataModelUpdate;
-  deleteSurface?: DeleteSurfaceMessage;
-}
-
-/**
- * Complete UI surface state
- */
-export interface Surface {
-  rootComponentId: string | null;
-  componentTree: unknown | null;
-  dataModel: Record<string, unknown>;
-  components: Map<string, ComponentInstance>;
-  styles: Record<string, string>;
-}
-
-/**
- * Message processor for handling A2UI updates
- */
-export interface MessageProcessor {
-  getSurfaces(): ReadonlyMap<string, Surface>;
-  clearSurfaces(): void;
-  processMessages(messages: ServerToClientMessage[]): void;
-  resolvePath(path: string, dataContextPath?: string): string;
-}
-
-/**
- * Text content in a message
- */
-export interface TextContent {
-  type: 'text';
-  text: string;
-}
-
-/**
- * Image content in a message
- */
-export interface ImageContent {
-  type: 'image';
-  imageUrl: string;
-}
-
-/**
- * File content in a message
- */
-export interface FileContent {
-  type: 'file';
-  fileUrl: string;
-  fileName?: string;
-  mimeType?: string;
-}
-
-/**
- * Message content (text, image, or file)
- */
-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 */
-  role: 'system' | 'user' | 'assistant';
-  
-  /** Message content (string or structured content) */
-  content: string | MessageContent[];
-}
-
-/**
- * Chat options
- */
-export interface ChatOptions {
-  /** Stream response */
-  stream?: boolean;
-  
-  /** Temperature (0-1) */
-  temperature?: number;
-  
-  /** Maximum tokens to generate */
-  maxTokens?: number;
-  
-  /** Callback for streamed chunks */
-  onChunk?: (chunk: string) => void;
-  
-  /** Callback when streaming completes */
-  onComplete?: (fullResponse: string) => void;
-}
-
-/**
- * Copilot AI Assistant Client API
- * 
- * @example
- * Basic chat:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * const result = await client.copilot.sendMessage([
- *   { role: 'user', content: 'Hello, how are you?' }
- * ]);
- * 
- * if (result.data) {
- *   console.log('AI Response:', result.data.content);
- * }
- * ```
- * 
- * @example
- * Streaming response:
- * ```typescript
- * await client.copilot.sendMessage(
- *   [{ role: 'user', content: 'Tell me a story' }],
- *   {
- *     stream: true,
- *     onChunk: (chunk) => {
- *       process.stdout.write(chunk);
- *     },
- *     onComplete: (fullResponse) => {
- *       console.log('\n\nFull response:', fullResponse);
- *     }
- *   }
- * );
- * ```
- * 
- * @example
- * Multi-turn conversation:
- * ```typescript
- * const conversation: ChatMessage[] = [
- *   { role: 'user', content: 'What is TypeScript?' },
- *   { role: 'assistant', content: 'TypeScript is a typed superset of JavaScript...' },
- *   { role: 'user', content: 'How do I define interfaces?' }
- * ];
- * 
- * const result = await client.copilot.sendMessage(conversation);
- * ```
- */
-export interface CopilotA2UIClient {
-  /**
-   * Send a message to the AI assistant
-   * 
-   * @param messages - Conversation messages
-   * @param options - Chat options (streaming, temperature, etc.)
-   * @returns AI response
-   * 
-   * @example
-   * Simple question:
-   * ```typescript
-   * const result = await client.copilot.sendMessage([
-   *   { role: 'user', content: 'What is the capital of France?' }
-   * ]);
-   * 
-   * console.log(result.data.content); // "Paris"
-   * ```
-   * 
-   * @example
-   * With system prompt:
-   * ```typescript
-   * const result = await client.copilot.sendMessage([
-   *   { role: 'system', content: 'You are a helpful coding assistant' },
-   *   { role: 'user', content: 'How do I reverse a string in JavaScript?' }
-   * ]);
-   * ```
-   * 
-   * @example
-   * Streaming response:
-   * ```typescript
-   * await client.copilot.sendMessage(
-   *   [{ role: 'user', content: 'Explain async/await' }],
-   *   {
-   *     stream: true,
-   *     onChunk: (chunk) => {
-   *       // Update UI with each chunk
-   *       appendToChat(chunk);
-   *     },
-   *     onComplete: (fullText) => {
-   *       console.log('Complete response received');
-   *     }
-   *   }
-   * );
-   * ```
-   */
-  sendMessage(
-    messages: ChatMessage[],
-    options?: ChatOptions
-  ): Promise<ClientResult<{ content: string; role: 'assistant' }>>;
-}
+interface TextContent {
+    type: "text";
+    text: string;
+}
+interface ImageContent {
+    type: "image";
+    data?: string;
+    url?: string;
+    mimeType?: string;
+}
+interface FileContent {
+    type: "file";
+    data?: string;
+    url?: string;
+    mimeType?: string;
+    name?: string;
+}
+type MessageContent = TextContent | ImageContent | FileContent;
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string | MessageContent[];
+}
+interface ChatOptions {
+    taskId?: string;
+}
+type CopilotClientAPI = {
+    /**
+     * Stream messages from Copilot Agent.
+     *
+     * @example
+     * ```typescript
+     * import { createCopilotClient, Data } from "@amaster.ai/copilot-client";
+     *
+     * const client = createCopilotClient();
+     *
+     * for await (const response of client.chat([{ role: "user", content: "Hello" }])) {
+     *   // deal response
+     * }
+     * ```
+     */
+    chat(messages: ChatMessage[], options?: ChatOptions): AsyncGenerator<SendStreamingMessageResponse, void, unknown>;
+    cancelChat(taskId: string): Promise<ClientResult<CancelTaskResponse>>;
+    getChatStatus(taskId: string): Promise<ClientResult<GetTaskResponse>>;
+};
+
+export { type ChatMessage, type ChatOptions, type CopilotClientAPI, type FileContent, type ImageContent, type MessageContent, type TextContent };