agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2a/notifications/webhook-service.d.ts

@@ -0,0 +1,257 @@
+/**
+ * A2A Webhook Service
+ *
+ * Delivers webhook notifications for A2A task events with signature verification,
+ * retry logic, and subscription management integration.
+ *
+ * @module adapters/a2a/notifications/webhook-service
+ * @see https://a2a-protocol.org/latest/specification/
+ */
+import { EventEmitter } from 'events';
+import type { TaskStatus } from '../jsonrpc/methods.js';
+import { SubscriptionStore, type Subscription, type SubscriptionStoreConfig } from './subscription-store.js';
+import { RetryQueue, type RetryConfig, type RetryQueueConfig } from './retry-queue.js';
+/**
+ * Webhook event types
+ */
+export type WebhookEvent = 'task.submitted' | 'task.working' | 'task.completed' | 'task.failed' | 'task.canceled' | 'task.input_required' | 'task.auth_required' | 'task.rejected' | 'task.artifact_created';
+/**
+ * Webhook configuration
+ */
+export interface WebhookConfig {
+    /** Webhook URL for notifications */
+    url: string;
+    /** Secret for signing webhook payloads */
+    secret: string;
+    /** Events to subscribe to */
+    events: WebhookEvent[];
+    /** Request timeout in milliseconds */
+    timeout: number;
+    /** Maximum retry attempts */
+    maxRetries: number;
+}
+/**
+ * Webhook payload structure
+ */
+export interface WebhookPayload {
+    /** Event type */
+    event: WebhookEvent;
+    /** Task ID */
+    taskId: string;
+    /** Context ID (for multi-turn) */
+    contextId?: string;
+    /** Event timestamp (ISO 8601) */
+    timestamp: string;
+    /** Event-specific data */
+    data: WebhookEventData;
+    /** Protocol metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Event-specific data
+ */
+export interface WebhookEventData {
+    /** Current task status */
+    status?: TaskStatus;
+    /** Previous status (for state changes) */
+    previousStatus?: TaskStatus;
+    /** Error information (for failures) */
+    error?: {
+        message: string;
+        code?: string;
+    };
+    /** Artifact information (for artifact events) */
+    artifact?: {
+        id: string;
+        name: string;
+        mimeType?: string;
+        size?: number;
+    };
+    /** Additional context */
+    [key: string]: unknown;
+}
+/**
+ * Delivery result
+ */
+export interface DeliveryResult {
+    /** Whether delivery was successful */
+    success: boolean;
+    /** HTTP status code */
+    statusCode?: number;
+    /** Error message if failed */
+    error?: string;
+    /** Response time in milliseconds */
+    responseTimeMs: number;
+    /** Number of attempts */
+    attempts: number;
+    /** Whether delivery was queued for retry */
+    queued: boolean;
+    /** Delivery ID if queued */
+    deliveryId?: string;
+}
+/**
+ * Webhook service configuration
+ */
+export interface WebhookServiceConfig {
+    /** User agent for webhook requests */
+    userAgent?: string;
+    /** Default timeout in milliseconds */
+    defaultTimeoutMs?: number;
+    /** Default retry configuration */
+    defaultRetryConfig?: Partial<RetryConfig>;
+    /** Subscription store configuration */
+    subscriptionStoreConfig?: SubscriptionStoreConfig;
+    /** Retry queue configuration */
+    retryQueueConfig?: RetryQueueConfig;
+    /** HTTP client for making requests (injectable for testing) */
+    httpClient?: HttpClient;
+    /** Enable metrics collection */
+    enableMetrics?: boolean;
+}
+/**
+ * HTTP client interface for making requests
+ */
+export interface HttpClient {
+    post(url: string, body: string, headers: Record<string, string>, timeout: number): Promise<HttpResponse>;
+}
+/**
+ * HTTP response interface
+ */
+export interface HttpResponse {
+    status: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/**
+ * Webhook service metrics
+ */
+export interface WebhookMetrics {
+    /** Total deliveries attempted */
+    totalDeliveries: number;
+    /** Successful deliveries */
+    successfulDeliveries: number;
+    /** Failed deliveries (after retries) */
+    failedDeliveries: number;
+    /** Average response time (ms) */
+    avgResponseTimeMs: number;
+    /** Delivery success rate (0-1) */
+    successRate: number;
+    /** Deliveries by event type */
+    byEvent: Record<WebhookEvent, number>;
+    /** Active subscriptions */
+    activeSubscriptions: number;
+    /** Items in retry queue */
+    retryQueueSize: number;
+}
+export declare const DEFAULT_WEBHOOK_CONFIG: Partial<WebhookConfig>;
+export declare const DEFAULT_SERVICE_CONFIG: Required<Omit<WebhookServiceConfig, 'httpClient'>>;
+/**
+ * Map task status to webhook event
+ */
+export declare function statusToEvent(status: TaskStatus): WebhookEvent;
+/**
+ * A2A Webhook Service
+ *
+ * Manages webhook subscriptions and delivers notifications for task events.
+ * Supports signature verification, exponential backoff retries, and metrics.
+ */
+export declare class WebhookService extends EventEmitter {
+    private readonly config;
+    private readonly httpClient;
+    private readonly subscriptionStore;
+    private readonly retryQueue;
+    private metrics;
+    constructor(config?: WebhookServiceConfig);
+    /**
+     * Create a subscription for a task
+     */
+    subscribe(taskId: string, webhookConfig: Partial<WebhookConfig> & {
+        url: string;
+        secret: string;
+    }, options?: {
+        contextId?: string;
+        expiresAt?: Date;
+    }): Subscription;
+    /**
+     * Get subscription for a task
+     */
+    getSubscription(taskId: string): Subscription | null;
+    /**
+     * Remove subscription for a task
+     */
+    unsubscribe(taskId: string): number;
+    /**
+     * List subscriptions for a task
+     */
+    listSubscriptions(taskId: string): Subscription[];
+    /**
+     * Deliver a webhook notification
+     */
+    deliver(config: WebhookConfig, payload: WebhookPayload): Promise<DeliveryResult>;
+    /**
+     * Deliver with automatic retry
+     */
+    deliverWithRetry(config: WebhookConfig, payload: WebhookPayload): Promise<DeliveryResult>;
+    /**
+     * Notify subscribers of a task event
+     */
+    notifySubscribers(taskId: string, event: WebhookEvent, data: WebhookEventData, contextId?: string): Promise<Map<string, DeliveryResult>>;
+    /**
+     * Notify subscribers of a task state change
+     */
+    notifyStateChange(taskId: string, newStatus: TaskStatus, previousStatus?: TaskStatus, error?: {
+        message: string;
+        code?: string;
+    }, contextId?: string): Promise<Map<string, DeliveryResult>>;
+    /**
+     * Notify subscribers of artifact creation
+     */
+    notifyArtifactCreated(taskId: string, artifact: {
+        id: string;
+        name: string;
+        mimeType?: string;
+        size?: number;
+    }, contextId?: string): Promise<Map<string, DeliveryResult>>;
+    /**
+     * Get service metrics
+     */
+    getMetrics(): WebhookMetrics;
+    /**
+     * Reset metrics
+     */
+    resetMetrics(): void;
+    /**
+     * Get subscription store for direct access
+     */
+    getSubscriptionStore(): SubscriptionStore;
+    /**
+     * Get retry queue for direct access
+     */
+    getRetryQueue(): RetryQueue;
+    /**
+     * Destroy the service
+     */
+    destroy(): void;
+    /**
+     * Attempt a single delivery
+     */
+    private attemptDelivery;
+    /**
+     * Process a retry from the queue
+     */
+    private processRetry;
+    /**
+     * Check if a status code is retryable
+     */
+    private shouldRetry;
+    /**
+     * Sleep for a specified duration
+     */
+    private sleep;
+}
+/**
+ * Create a new webhook service
+ */
+export declare function createWebhookService(config?: WebhookServiceConfig): WebhookService;
+//# sourceMappingURL=webhook-service.d.ts.map

package/v3/dist/adapters/a2a/notifications/webhook-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-service.d.ts","sourceRoot":"","sources":["../../../../src/adapters/a2a/notifications/webhook-service.ts"],"names":[],"mappings":"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"}