@dexwox-labs/a2a-client
Version:
TypeScript client implementation for Google's Agent-to-Agent (A2A) protocol - includes HTTP/WebSocket communication, circuit breakers and error handling
249 lines • 9.53 kB
TypeScript
/**
* @module TaskClient
* @description Client for managing tasks in the A2A protocol
*/
import { Task, TaskState } from '@dexwox-labs/a2a-core';
import { MessageClientOptions, PushNotificationConfig } from './types';
import { EventEmitter } from 'events';
/**
* Client for managing tasks in the A2A protocol
*
* The TaskClient provides methods for creating, monitoring, and managing tasks
* with support for real-time status updates and push notifications.
*
* @example
* ```typescript
* const taskClient = new TaskClient({ baseUrl: 'https://a2a-server.example.com' });
*
* // Get task status
* const task = await taskClient.getTaskStatus('task-123');
* console.log(`Task status: ${task.status}`);
*
* // Cancel a task
* await taskClient.cancelTask('task-123');
* ```
*/
export declare class TaskClient extends EventEmitter {
private options;
/** @private Cache of push notification configurations by task ID */
private pushConfigs;
/** @private Map of task ID to callback functions for task updates */
private taskCallbacks;
/**
* Creates a new TaskClient instance
* @param options - Configuration options for the client
*/
constructor(options: MessageClientOptions);
/**
* Gets the current status of a task
*
* Retrieves the current state and details of a task by its ID. This method
* fetches the complete task object including status, input, output, and any
* error information.
*
* @param taskId - The ID of the task to check
* @returns Promise resolving to the complete task object
* @throws {A2ANetworkError} If there's a network issue contacting the server
* @throws {A2AValidationError} If the task ID is invalid or not found
*
* @example
* ```typescript
* try {
* const task = await taskClient.getTaskStatus('task-123');
* console.log(`Task status: ${task.status}`);
*
* if (task.status === 'completed') {
* console.log('Task output:', task.output);
* } else if (task.status === 'failed') {
* console.error('Task failed:', task.error);
* }
* } catch (error) {
* console.error('Error checking task status:', error.message);
* }
* ```
*/
getTaskStatus(taskId: string): Promise<Task>;
/**
* Cancels a running task
*
* Attempts to cancel a task that is currently in progress. This will transition
* the task to the 'canceled' state if successful. Tasks that have already
* completed or failed cannot be canceled.
*
* @param taskId - The ID of the task to cancel
* @returns Promise resolving when cancellation is complete
* @throws {A2ANetworkError} If there's a network issue contacting the server
* @throws {A2AValidationError} If the task cannot be canceled (e.g., already completed)
*
* @example
* ```typescript
* try {
* await taskClient.cancelTask('task-123');
* console.log('Task canceled successfully');
* } catch (error) {
* if (error.code === 'VALIDATION_ERROR') {
* console.error('Cannot cancel task:', error.message);
* } else {
* console.error('Error canceling task:', error.message);
* }
* }
* ```
*/
cancelTask(taskId: string): Promise<void>;
/**
* Lists all tasks for the current session
* @param options Optional filters for the task list
* @returns Promise resolving to an array of tasks
* @throws A2AError if the request fails
*/
/**
* Sets push notification configuration for a task
*
* Configures server-side push notifications for task status updates. This allows
* your application to receive real-time updates about task progress without polling.
*
* @param taskId - The task ID to configure notifications for
* @param config - Push notification settings including endpoint and events to subscribe to
* @returns Promise resolving when configuration is complete
* @throws {A2ANetworkError} If there's a network issue contacting the server
* @throws {A2ATimeoutError} If the request times out
* @throws {A2AValidationError} If the configuration is invalid
*
* @example
* ```typescript
* await taskClient.setPushConfig('task-123', {
* enabled: true,
* endpoint: 'https://my-app.example.com/webhooks/tasks',
* authToken: 'secret-token-123',
* events: ['task.updated', 'task.completed', 'task.failed']
* });
*
* console.log('Push notifications configured for task');
* ```
*/
setPushConfig(taskId: string, config: PushNotificationConfig): Promise<void>;
/**
* Gets push notification configuration for a task
*
* Retrieves the current push notification settings for a task. This method
* first checks the local cache and only makes a server request if needed.
*
* @param taskId - The task ID to check
* @returns Promise resolving to the push notification configuration
* @throws {A2ANetworkError} If there's a network issue contacting the server
* @throws {A2AValidationError} If the task ID is invalid or not found
*
* @example
* ```typescript
* const config = await taskClient.getPushConfig('task-123');
*
* console.log('Push notifications enabled:', config.enabled);
* console.log('Subscribed events:', config.events);
* console.log('Webhook endpoint:', config.endpoint);
* ```
*/
getPushConfig(taskId: string): Promise<PushNotificationConfig>;
/**
* Updates the status of a task
*
* Changes a task's status from one state to another. The transition is validated
* to ensure it follows the allowed state machine transitions in the A2A protocol.
*
* @param taskId - The ID of the task to update
* @param status - Object containing the current state and target state
* @param status.from - The current state of the task
* @param status.to - The desired new state of the task
* @returns Promise resolving when the status update is complete
* @throws {A2ANetworkError} If there's a network issue contacting the server
* @throws {A2AValidationError} If the state transition is invalid
*
* @example
* ```typescript
* // Mark a task as completed
* await taskClient.updateTaskStatus('task-123', {
* from: 'working',
* to: 'completed'
* });
*
* // Mark a task as failed
* await taskClient.updateTaskStatus('task-456', {
* from: 'working',
* to: 'failed'
* });
* ```
*/
updateTaskStatus(taskId: string, status: {
from: TaskState;
to: TaskState;
}): Promise<void>;
/**
* Lists tasks matching the specified criteria
*
* Retrieves a list of tasks from the server, with optional filtering by status,
* limiting the number of results, and filtering by creation date.
*
* @param options - Optional filter criteria for the task list
* @param options.status - Optional filter by task status
* @param options.limit - Optional maximum number of tasks to return
* @param options.since - Optional ISO timestamp to filter tasks created after this time
* @returns Promise resolving to an array of tasks matching the criteria
* @throws {A2ANetworkError} If there's a network issue contacting the server
*
* @example
* ```typescript
* // Get all tasks
* const allTasks = await taskClient.listTasks();
*
* // Get only completed tasks
* const completedTasks = await taskClient.listTasks({ status: 'completed' });
*
* // Get the 10 most recent tasks
* const recentTasks = await taskClient.listTasks({ limit: 10 });
*
* // Get tasks created in the last hour
* const oneHourAgo = new Date(Date.now() - 3600000).toISOString();
* const recentTasks = await taskClient.listTasks({ since: oneHourAgo });
* ```
*/
listTasks(options?: {
status?: TaskState;
limit?: number;
since?: string;
}): Promise<Task[]>;
/**
* Registers a callback for task updates
*
* Sets up a callback function to be called whenever a specific task is updated.
* This provides a way to monitor task progress in real-time without polling.
*
* @param taskId - The ID of the task to monitor
* @param callback - Function to call when the task is updated
*
* @example
* ```typescript
* // Monitor a specific task
* taskClient.onTaskUpdate('task-123', (task) => {
* console.log(`Task ${task.id} updated:`, task.status);
*
* if (task.status === 'completed') {
* console.log('Task completed with result:', task.output);
* } else if (task.status === 'failed') {
* console.error('Task failed with error:', task.error);
* }
* });
* ```
*/
onTaskUpdate(taskId: string, callback: (task: Task) => void): void;
/**
* Handles incoming task updates and triggers callbacks
*
* This internal method processes task updates received from the server and
* triggers the appropriate callbacks and events. It's typically called by
* the MessageClient when streaming updates.
*
* @param task - The updated task object
* @internal
*/
handleTaskUpdate(task: Task): void;
}
//# sourceMappingURL=task-client.d.ts.map