@robota-sdk/agent-plugin 3.0.0-beta.64

package/src/webhook/transformer.ts

@@ -0,0 +1,209 @@
+/**
+ * Webhook data transformation utilities
+ * Converts base plugin types to webhook-specific types safely
+ */
+
+import type {
+  IPluginExecutionContext,
+  IPluginExecutionResult,
+  TLoggerData,
+  TUniversalValue,
+} from '@robota-sdk/agent-core';
+import type {
+  IWebhookExecutionContext,
+  IWebhookExecutionResult,
+  IWebhookEventData,
+  IWebhookExecutionData,
+  IWebhookConversationData,
+  IWebhookToolData,
+  IWebhookErrorData,
+  IWebhookToolCallData,
+  TWebhookEventName,
+} from './types';
+
+/**
+ * Webhook data transformer utility class
+ */
+export class WebhookTransformer {
+  /**
+   * Convert IPluginExecutionContext to WebhookExecutionContext
+   */
+  static contextToWebhook(context: IPluginExecutionContext): IWebhookExecutionContext {
+    return {
+      executionId: context.executionId,
+      sessionId: context.sessionId,
+      userId: context.userId,
+    };
+  }
+
+  /**
+   * Convert IPluginExecutionResult to WebhookExecutionResult
+   */
+  static resultToWebhook(result: IPluginExecutionResult): IWebhookExecutionResult {
+    return {
+      response: result.response,
+      content: result.content,
+      duration: result.duration,
+      tokensUsed: result.tokensUsed,
+      toolsExecuted: result.toolsExecuted,
+      success: result.success,
+      usage: result.usage,
+      toolCalls: result.toolCalls,
+      error: result.error,
+    };
+  }
+
+  /**
+   * Create execution event data
+   */
+  static createExecutionData(
+    context: IWebhookExecutionContext,
+    result: IWebhookExecutionResult,
+  ): IWebhookEventData {
+    const executionData: IWebhookExecutionData = {
+      response: result.response || undefined,
+      duration: result.duration || undefined,
+      tokensUsed: result.tokensUsed || undefined,
+      toolsExecuted: result.toolsExecuted || undefined,
+      success: result.success !== undefined ? result.success : undefined,
+    };
+
+    return {
+      executionId: context.executionId,
+      sessionId: context.sessionId,
+      userId: context.userId,
+      result: executionData,
+    };
+  }
+
+  /**
+   * Create conversation event data
+   */
+  static createConversationData(
+    context: IWebhookExecutionContext,
+    result: IWebhookExecutionResult,
+  ): IWebhookEventData {
+    const toolCalls: IWebhookToolCallData[] =
+      result.toolCalls?.map((call) => ({
+        id: call.id || '',
+        name: call.name || '',
+        arguments: JSON.stringify(call.arguments || {}),
+        result: String(call.result || ''),
+      })) || [];
+
+    const conversationData: IWebhookConversationData = {
+      response: result.content || result.response || undefined,
+      tokensUsed: result.usage?.totalTokens || result.tokensUsed || undefined,
+      toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+    };
+
+    return {
+      executionId: context.executionId,
+      sessionId: context.sessionId,
+      userId: context.userId,
+      conversation: conversationData,
+    };
+  }
+
+  /**
+   * Create tool execution event data
+   *
+   * REASON: Tool result structure varies by tool type and provider, needs flexible handling for webhook processing
+   * ALTERNATIVES_CONSIDERED:
+   * 1. Strict tool result interfaces (breaks tool compatibility)
+   * 2. Union types (insufficient for dynamic tool results)
+   * 3. Generic constraints (too complex for webhook processing)
+   * 4. Interface definitions (too rigid for varied tool results)
+   * 5. Type assertions (decreases type safety)
+   * TODO: Consider standardized tool result interface across tools
+   */
+  static createToolData(
+    context: IWebhookExecutionContext,
+    toolResult: TLoggerData,
+  ): IWebhookEventData {
+    // Safely extract tool data from result
+    const toolName = this.safeGetProperty(toolResult, 'toolName') || 'unknown';
+    const toolId =
+      this.safeGetProperty(toolResult, 'toolId') ||
+      this.safeGetProperty(toolResult, 'executionId') ||
+      'unknown';
+    const hasError = this.safeGetProperty(toolResult, 'error');
+    const duration = this.safeGetProperty(toolResult, 'duration');
+    const result = this.safeGetProperty(toolResult, 'result');
+
+    const toolData: IWebhookToolData = {
+      name: String(toolName),
+      id: String(toolId),
+      success: !hasError,
+      duration: typeof duration === 'number' ? duration : undefined,
+      result: hasError ? undefined : String(result || ''),
+      error: hasError
+        ? hasError instanceof Error
+          ? hasError.message
+          : String(hasError)
+        : undefined,
+    };
+
+    return {
+      executionId: context.executionId,
+      sessionId: context.sessionId,
+      userId: context.userId,
+      tool: toolData,
+    };
+  }
+
+  /**
+   * Create error event data
+   */
+  static createErrorData(context: IWebhookExecutionContext, error: Error): IWebhookEventData {
+    const errorData: IWebhookErrorData = {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      type: error instanceof Error ? error.constructor.name : 'Unknown',
+      context: context
+        ? {
+            executionId: context.executionId || '',
+            sessionId: context.sessionId || '',
+            userId: context.userId || '',
+          }
+        : undefined,
+    };
+
+    return {
+      executionId: context.executionId,
+      sessionId: context.sessionId,
+      userId: context.userId,
+      error: errorData,
+    };
+  }
+
+  /**
+   * Safely get property from object (handles index signature issues)
+   *
+   * REASON: Safe property access for webhook data transformation needs flexible input/output types
+   * ALTERNATIVES_CONSIDERED:
+   * 1. Strict object types (breaks dynamic property access)
+   * 2. Union types (insufficient for property extraction)
+   * 3. Generic constraints (too complex for simple property access)
+   * 4. Interface definitions (too rigid for dynamic objects)
+   * 5. Type assertions (decreases type safety)
+   * TODO: Consider typed property access if patterns emerge
+   */
+  private static safeGetProperty(obj: TLoggerData, key: string): TUniversalValue | Date | Error {
+    if (!obj || typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+      return undefined;
+    }
+    return obj[key];
+  }
+
+  /**
+   * Default payload transformer for webhook events
+   */
+  static defaultPayloadTransformer(
+    _event: TWebhookEventName,
+    data: IWebhookEventData,
+  ): IWebhookEventData {
+    // Simply return the data as-is for the default transformer
+    return data;
+  }
+}

package/src/webhook/types.ts

@@ -0,0 +1,201 @@
+import type { TExecutionEventName } from '@robota-sdk/agent-core';
+
+/**
+ * Webhook plugin type definitions
+ * Clean separation of concerns with domain-specific types
+ */
+
+export type TWebhookEventName =
+  | TExecutionEventName
+  | 'conversation.complete'
+  | 'tool.executed'
+  | 'error.occurred'
+  | 'custom';
+
+/**
+ * Base webhook context data
+ */
+export interface IWebhookContextData {
+  executionId?: string | undefined;
+  sessionId?: string | undefined;
+  userId?: string | undefined;
+}
+
+/**
+ * Execution result data for webhooks
+ */
+export interface IWebhookExecutionData {
+  response?: string | undefined;
+  duration?: number | undefined;
+  tokensUsed?: number | undefined;
+  toolsExecuted?: number | undefined;
+  success?: boolean | undefined;
+}
+
+/**
+ * Conversation result data for webhooks
+ */
+export interface IWebhookConversationData {
+  response?: string | undefined;
+  tokensUsed?: number | undefined;
+  toolCalls?: IWebhookToolCallData[] | undefined;
+}
+
+/**
+ * Tool call data for webhooks
+ */
+export interface IWebhookToolCallData {
+  id: string;
+  name: string;
+  arguments: string;
+  result: string;
+}
+
+/**
+ * Tool execution data for webhooks
+ */
+export interface IWebhookToolData {
+  name: string;
+  id: string;
+  success: boolean;
+  duration?: number | undefined;
+  result?: string | undefined;
+  error?: string | undefined;
+}
+
+/**
+ * Error data for webhooks
+ */
+export interface IWebhookErrorData {
+  message: string;
+  stack?: string | undefined;
+  context?: Record<string, string | number | boolean> | undefined;
+  type?: string | undefined;
+}
+
+/**
+ * Complete webhook event data structure
+ */
+export interface IWebhookEventData extends IWebhookContextData {
+  result?: IWebhookExecutionData | undefined;
+  conversation?: IWebhookConversationData | undefined;
+  tool?: IWebhookToolData | undefined;
+  error?: IWebhookErrorData | undefined;
+}
+
+/**
+ * Webhook metadata for additional context
+ */
+export type TWebhookMetadata = Record<string, string | number | boolean | Date | string[]>;
+
+/**
+ * Webhook execution context (simplified from base types)
+ */
+export interface IWebhookExecutionContext {
+  executionId?: string | undefined;
+  sessionId?: string | undefined;
+  userId?: string | undefined;
+}
+
+/**
+ * Webhook execution result (simplified from base types)
+ */
+export interface IWebhookExecutionResult {
+  response?: string | undefined;
+  content?: string | undefined;
+  duration?: number | undefined;
+  tokensUsed?: number | undefined;
+  toolsExecuted?: number | undefined;
+  success?: boolean | undefined;
+  usage?: { totalTokens?: number | undefined } | undefined;
+  // SSOT: reuse the canonical toolCalls shape from IPluginExecutionResult.
+  toolCalls?: import('@robota-sdk/agent-core').IPluginExecutionResult['toolCalls'];
+  results?:
+    | Array<{
+        toolName?: string | undefined;
+        toolId?: string | undefined;
+        executionId?: string | undefined;
+        error?: Error | undefined;
+        duration?: number | undefined;
+        result?: string | number | boolean | undefined;
+      }>
+    | undefined;
+  error?: Error | undefined;
+}
+
+/**
+ * Webhook payload structure
+ */
+export interface IWebhookPayload {
+  event: TWebhookEventName;
+  timestamp: string;
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  data: IWebhookEventData;
+  metadata?: TWebhookMetadata;
+}
+
+/**
+ * Webhook endpoint configuration
+ */
+export interface IWebhookEndpoint {
+  url: string;
+  headers?: Record<string, string>;
+  events?: TWebhookEventName[];
+  retries?: number;
+  timeout?: number;
+  secret?: string;
+}
+
+import type { IPluginOptions, IPluginStats } from '@robota-sdk/agent-core';
+
+/**
+ * Webhook plugin configuration options
+ */
+export interface IWebhookPluginOptions extends IPluginOptions {
+  /** Webhook endpoints */
+  endpoints: IWebhookEndpoint[];
+  /** Events to send webhooks for */
+  events?: TWebhookEventName[];
+  /** Default timeout for webhook requests */
+  defaultTimeout?: number;
+  /** Default retry attempts */
+  defaultRetries?: number;
+  /** Whether to use async sending */
+  async?: boolean;
+  /** Maximum concurrent webhook requests */
+  maxConcurrency?: number;
+  /** Whether to batch webhook requests */
+  batching?: {
+    enabled: boolean;
+    maxSize: number;
+    flushInterval: number;
+  };
+  /** Custom payload transformer */
+  payloadTransformer?: (event: TWebhookEventName, data: IWebhookEventData) => IWebhookEventData;
+}
+
+/**
+ * Webhook plugin statistics
+ */
+export interface IWebhookPluginStats extends IPluginStats {
+  endpointCount: number;
+  queueLength: number;
+  batchQueueLength: number;
+  activeConcurrency: number;
+  supportedEvents: TWebhookEventName[];
+  totalSent: number;
+  totalErrors: number;
+  averageResponseTime: number;
+}
+
+/**
+ * Internal webhook request structure
+ */
+export interface IWebhookRequest {
+  endpoint: IWebhookEndpoint;
+  payload: IWebhookPayload;
+  attempt: number;
+  timestamp: Date;
+}

package/src/webhook/webhook-helpers.ts

@@ -0,0 +1,60 @@
+/**
+ * Webhook Plugin - Validation helpers and event constants.
+ *
+ * Extracted from webhook-plugin.ts to keep each file under 300 lines.
+ * @internal
+ */
+
+import { PluginError, EXECUTION_EVENTS, EXECUTION_EVENT_PREFIX } from '@robota-sdk/agent-core';
+import type { TWebhookEventName, IWebhookEndpoint } from './types';
+
+/** Local execution event names used by WebhookPlugin. @internal */
+export const WEBHOOK_EXEC_EVENTS = {
+  START: `${EXECUTION_EVENT_PREFIX}.${EXECUTION_EVENTS.START}` as TWebhookEventName,
+  COMPLETE: `${EXECUTION_EVENT_PREFIX}.${EXECUTION_EVENTS.COMPLETE}` as TWebhookEventName,
+  ERROR: `${EXECUTION_EVENT_PREFIX}.${EXECUTION_EVENTS.ERROR}` as TWebhookEventName,
+} as const;
+
+export const WEBHOOK_CONV_EVENTS = {
+  COMPLETE: 'conversation.complete' as TWebhookEventName,
+} as const;
+export const WEBHOOK_TOOL_EVENTS = { EXECUTED: 'tool.executed' as TWebhookEventName } as const;
+export const WEBHOOK_ERROR_EVENTS = { OCCURRED: 'error.occurred' as TWebhookEventName } as const;
+
+/**
+ * Validate all configured webhook endpoints. Throws PluginError for any
+ * invalid URL or unsupported event name. @internal
+ */
+export function validateWebhookEndpoints(
+  endpoints: IWebhookEndpoint[],
+  pluginName: string,
+  validEvents: TWebhookEventName[],
+): void {
+  for (const endpoint of endpoints) {
+    if (!endpoint.url) {
+      throw new PluginError(`Webhook endpoint URL is required`, pluginName);
+    }
+
+    let parsed: URL;
+    try {
+      parsed = new URL(endpoint.url);
+    } catch {
+      throw new PluginError(`Invalid webhook URL: ${endpoint.url}`, pluginName);
+    }
+
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      throw new PluginError(
+        `Webhook endpoint URL must use http or https: ${endpoint.url}`,
+        pluginName,
+      );
+    }
+
+    if (endpoint.events) {
+      for (const event of endpoint.events) {
+        if (!validEvents.includes(event)) {
+          throw new PluginError(`Invalid webhook event: ${event}`, pluginName);
+        }
+      }
+    }
+  }
+}