@teneo-protocol/sdk 1.0.0

package/dist/handlers/webhook-handler.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Webhook handler for Teneo Protocol SDK
+ * Manages webhook delivery with retries and error handling using Zod validation
+ */
+import { EventEmitter } from "eventemitter3";
+import { WebhookConfig, WebhookEventType, BaseMessage, Logger, SDKConfig } from "../types";
+import { SDKEvents } from "../types/events";
+export declare class WebhookHandler extends EventEmitter<SDKEvents> {
+    private readonly config;
+    private webhookConfig?;
+    private readonly logger;
+    private queue;
+    private circuitBreaker;
+    private retryPolicy;
+    private isProcessing;
+    private processTimer?;
+    private isDestroyed;
+    constructor(config: SDKConfig, logger: Logger);
+    /**
+     * Configures or updates webhook settings with runtime validation.
+     * Validates the webhook URL for security (HTTPS requirement except localhost)
+     * and sets up retry logic, timeout, and event filtering.
+     *
+     * @param config - Webhook configuration object
+     * @param config.url - Webhook endpoint URL (must be HTTPS unless localhost)
+     * @param config.headers - Optional HTTP headers to include with requests
+     * @param config.retries - Maximum number of retry attempts for failed deliveries (default: 3)
+     * @param config.timeout - Request timeout in milliseconds (default: 30000)
+     * @param config.events - Array of event types to send webhooks for (default: all events)
+     * @throws {WebhookError} If URL is invalid, insecure, or points to private IP ranges
+     *
+     * @example
+     * ```typescript
+     * webhookHandler.configure({
+     *   url: 'https://api.example.com/webhooks',
+     *   headers: { 'Authorization': 'Bearer token' },
+     *   retries: 5,
+     *   timeout: 60000,
+     *   events: ['message', 'agent_selected', 'error']
+     * });
+     * ```
+     */
+    configure(config: WebhookConfig): void;
+    /**
+     * Sends a webhook for a specific event type with payload validation.
+     * Validates event type and payload with Zod schemas before queueing.
+     * Webhooks are queued and delivered asynchronously with retry logic.
+     * Emits 'webhook:sent', 'webhook:success', or 'webhook:error' events.
+     *
+     * @param eventType - Type of event to send ('message', 'task_response', 'agent_selected', or 'error')
+     * @param data - Event-specific data payload (validated with Zod)
+     * @param metadata - Optional metadata to include with the event
+     * @returns Promise that resolves when webhook is queued (not when delivered)
+     * @throws {ValidationError} If eventType or data fail Zod validation
+     *
+     * @example
+     * ```typescript
+     * await webhookHandler.sendWebhook('agent_selected', {
+     *   agent_id: 'weather-agent',
+     *   agent_name: 'Weather Agent',
+     *   capabilities: ['weather-forecast']
+     * }, {
+     *   agentId: 'weather-agent',
+     *   taskId: 'task-123'
+     * });
+     * ```
+     */
+    sendWebhook(eventType: WebhookEventType, data: any, metadata?: any): Promise<void>;
+    /**
+     * Sends a webhook specifically for message events with automatic event type detection.
+     * Filters out system messages (ping, pong, auth) and maps message types to webhook events.
+     * Validates message with Zod schema before sending.
+     *
+     * @param message - The message to send as a webhook
+     * @returns Promise that resolves when webhook is queued
+     * @throws {ValidationError} If message fails Zod validation
+     *
+     * @example
+     * ```typescript
+     * const userMessage = createUserMessage('Hello', 'general', walletAddress);
+     * await webhookHandler.sendMessageWebhook(userMessage);
+     * // Webhook will be sent with event type 'message'
+     * ```
+     */
+    sendMessageWebhook(message: BaseMessage): Promise<void>;
+    /**
+     * Process webhook queue
+     */
+    private processQueue;
+    /**
+     * Deliver a webhook
+     */
+    private deliverWebhook;
+    /**
+     * Validate webhook URL for SSRF vulnerabilities
+     * Uses comprehensive SSRF validator to block:
+     * - Private IP ranges (RFC1918)
+     * - Cloud metadata endpoints (AWS, GCP, Azure)
+     * - Kubernetes service discovery
+     * - Dangerous internal ports
+     * - Localhost (unless allowInsecureWebhooks is enabled)
+     */
+    private validateWebhookUrl;
+    /**
+     * Gets the current status of the webhook delivery queue.
+     * Useful for monitoring webhook health and detecting delivery issues.
+     *
+     * @returns Object containing queue statistics
+     * @returns {number} returns.pending - Total number of webhooks in queue (including failed)
+     * @returns {boolean} returns.processing - Whether queue is currently being processed
+     * @returns {number} returns.failed - Number of webhooks that have failed and are awaiting retry
+     *
+     * @example
+     * ```typescript
+     * const status = webhookHandler.getQueueStatus();
+     * console.log(`Queue: ${status.pending} pending, ${status.failed} failed`);
+     * if (status.failed > 10) {
+     *   console.warn('High number of failed webhooks detected');
+     * }
+     * ```
+     */
+    getQueueStatus(): {
+        pending: number;
+        processing: boolean;
+        failed: number;
+        circuitState: string;
+    };
+    /**
+     * Clears all pending and failed webhooks from the delivery queue.
+     * Warning: This permanently discards all queued webhooks.
+     * Use this to recover from queue issues or when webhooks are no longer relevant.
+     *
+     * @example
+     * ```typescript
+     * webhookHandler.clearQueue();
+     * console.log('All pending webhooks cleared');
+     * ```
+     */
+    clearQueue(): void;
+    /**
+     * Retries all failed webhooks in the queue immediately.
+     * Resets attempt counters and error states for failed webhooks.
+     * Useful for recovering from temporary network or endpoint issues.
+     *
+     * @example
+     * ```typescript
+     * const status = webhookHandler.getQueueStatus();
+     * if (status.failed > 0) {
+     *   webhookHandler.retryFailed();
+     *   console.log(`Retrying ${status.failed} failed webhooks`);
+     * }
+     * ```
+     */
+    retryFailed(): void;
+    /**
+     * Destroys the webhook handler and cleans up resources.
+     * Stops queue processing, clears all timers, removes event listeners,
+     * and discards all pending webhooks. After destruction, the handler cannot be reused.
+     *
+     * @example
+     * ```typescript
+     * webhookHandler.destroy();
+     * console.log('Webhook handler destroyed');
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Quick check for whether a webhook URL has been configured.
+     * Returns true if configure() has been called with a valid URL.
+     *
+     * @returns True if webhook is configured, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (webhookHandler.isConfigured) {
+     *   console.log('Webhooks are enabled');
+     * } else {
+     *   console.log('Webhooks not configured');
+     * }
+     * ```
+     */
+    get isConfigured(): boolean;
+    /**
+     * Gets the current webhook configuration including URL, headers, and settings.
+     * Returns a defensive copy to prevent external modification of internal state.
+     * Returns undefined if webhook has not been configured.
+     *
+     * @returns Copy of current webhook configuration, or undefined if not configured
+     *
+     * @example
+     * ```typescript
+     * const config = webhookHandler.getConfig();
+     * if (config) {
+     *   console.log(`Webhook URL: ${config.url}`);
+     *   console.log(`Max retries: ${config.retries}`);
+     *   console.log(`Timeout: ${config.timeout}ms`);
+     * }
+     * ```
+     */
+    getConfig(): WebhookConfig | undefined;
+}
+//# sourceMappingURL=webhook-handler.d.ts.map

package/dist/handlers/webhook-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-handler.d.ts","sourceRoot":"","sources":["../../src/handlers/webhook-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAM7C,OAAO,EACL,aAAa,EAEb,gBAAgB,EAIhB,WAAW,EAEX,MAAM,EAEN,SAAS,EAEV,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAiC,MAAM,iBAAiB,CAAC;AAW3E,qBAAa,cAAe,SAAQ,YAAY,CAAC,SAAS,CAAC;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM;IAqD7C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAmB7C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,WAAW,CAAC,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA6C/F;;;;;;;;;;;;;;;OAeG;IACU,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDpE;;OAEG;YACW,YAAY;IA+E1B;;OAEG;YACW,cAAc;IAoD5B;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;;;;;;;;;;;;;;;OAiBG;IACI,cAAc,IAAI;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;KACtB;IAUD;;;;;;;;;;OAUG;IACI,UAAU,IAAI,IAAI;IAKzB;;;;;;;;;;;;;OAaG;IACI,WAAW,IAAI,IAAI;IAU1B;;;;;;;;;;OAUG;IACI,OAAO,IAAI,IAAI;IAWtB;;;;;;;;;;;;;;OAcG;IACH,IAAW,YAAY,IAAI,OAAO,CAEjC;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,SAAS,IAAI,aAAa,GAAG,SAAS;CAG9C"}