@dexwox-labs/a2a-server/src/push-notifications/push-service.ts

TypeScript server implementation for Google's Agent-to-Agent (A2A) protocol - includes Express/WebSocket handlers, request validation and queue management

/**
 * @module PushNotificationService
 * @description Service for managing and sending push notifications for task events
 * 
 * This module provides functionality for configuring and sending push notifications
 * for task-related events in the A2A protocol server. It allows clients to receive
 * real-time updates about task status changes and other events.
 */

import type { PushNotificationConfig } from '@dexwox-labs/a2a-core';

/**
 * Service for managing and sending push notifications
 * 
 * The PushNotificationService handles the configuration and delivery of push
 * notifications for task-related events. It maintains a store of notification
 * configurations for each task and provides methods for sending notifications
 * when events occur.
 * 
 * @example
 * ```typescript
 * // Create a push notification service
 * const pushService = new PushNotificationService();
 * 
 * // Configure push notifications for a task
 * await pushService.setConfig('task-123', {
 *   enabled: true,
 *   endpoint: 'https://example.com/webhooks/a2a',
 *   authToken: 'secret-token',
 *   events: ['taskCompleted', 'taskFailed']
 * });
 * 
 * // Send a notification
 * await pushService.notify('task-123', 'taskCompleted', {
 *   taskId: 'task-123',
 *   status: 'completed',
 *   timestamp: Date.now()
 * });
 * ```
 */
export class PushNotificationService {
  /**
   * Notifies subscribers about a task status change
   * 
   * This method sends a notification when a task's status changes.
   * It's a convenience wrapper around the notify method.
   * 
   * @param taskId - ID of the task whose status changed
   * @param status - New status of the task
   * @returns Promise that resolves when the notification is sent
   * 
   * @example
   * ```typescript
   * await pushService.notifyStatusChange('task-123', 'completed');
   * ```
   */
  async notifyStatusChange(taskId: string, status: string): Promise<void> {
    // Implementation goes here
  }
  
  /** Store of push notification configurations by task ID */
  private configStore = new Map<string, PushNotificationConfig>();

  /**
   * Sets the push notification configuration for a task
   * 
   * This method stores a push notification configuration for a specific task.
   * The configuration includes settings like the endpoint URL, authentication
   * token, and which events to send notifications for.
   * 
   * @param taskId - ID of the task to configure notifications for
   * @param config - Push notification configuration
   * @returns Promise that resolves when the configuration is stored
   * 
   * @example
   * ```typescript
   * await pushService.setConfig('task-123', {
   *   enabled: true,
   *   endpoint: 'https://example.com/webhooks/a2a',
   *   authToken: 'secret-token',
   *   events: ['taskCompleted', 'taskFailed']
   * });
   * ```
   */
  async setConfig(taskId: string, config: PushNotificationConfig): Promise<void> {
    this.configStore.set(taskId, config);
  }

  /**
   * Gets the push notification configuration for a task
   * 
   * This method retrieves the push notification configuration for a specific task.
   * If no configuration is found, it throws an error.
   * 
   * @param taskId - ID of the task to get the configuration for
   * @returns Promise resolving to the push notification configuration
   * @throws Error with code -32005 if the configuration is not found
   * 
   * @example
   * ```typescript
   * try {
   *   const config = await pushService.getConfig('task-123');
   *   console.log('Push notifications enabled:', config.enabled);
   *   console.log('Endpoint:', config.endpoint);
   * } catch (error) {
   *   console.error('Failed to get push config:', error.message);
   * }
   * ```
   */
  async getConfig(taskId: string): Promise<PushNotificationConfig> {
    const config = this.configStore.get(taskId);
    if (!config) {
      throw { code: -32005, message: 'Push config not found' };
    }
    return config;
  }

  /**
   * Sends a push notification for a task event
   * 
   * This method sends a push notification for a specific event related to a task.
   * It checks if notifications are enabled for the task and if the event is
   * included in the list of events to send notifications for.
   * 
   * @param taskId - ID of the task the event is related to
   * @param event - Name of the event (e.g., 'taskCompleted', 'taskFailed')
   * @param data - Data to include in the notification
   * @returns Promise that resolves when the notification is sent
   * 
   * @example
   * ```typescript
   * await pushService.notify('task-123', 'taskCompleted', {
   *   taskId: 'task-123',
   *   status: 'completed',
   *   timestamp: Date.now(),
   *   result: { data: 'Task output' }
   * });
   * ```
   */
  async notify(taskId: string, event: string, data: unknown): Promise<void> {
    const config = await this.getConfig(taskId);
    if (config.enabled && config.events.includes(event)) {
      // Implementation would send to configured endpoint
      console.log(`Sending ${event} notification for task ${taskId}`);
    }
  }
}