digital-samba-mcp-server/dist/src/webhooks.d.ts

Digital Samba MCP Server - Model Context Protocol server for Digital Samba's video conferencing API

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
export declare enum WebhookEventType {
    ROOM_CREATED = "room.created",
    ROOM_UPDATED = "room.updated",
    ROOM_DELETED = "room.deleted",
    SESSION_STARTED = "session.started",
    SESSION_ENDED = "session.ended",
    PARTICIPANT_JOINED = "participant.joined",
    PARTICIPANT_LEFT = "participant.left",
    RECORDING_STARTED = "recording.started",
    RECORDING_STOPPED = "recording.stopped",
    RECORDING_READY = "recording.ready",
    CHAT_MESSAGE = "chat.message",
    POLL_CREATED = "poll.created",
    POLL_UPDATED = "poll.updated",
    POLL_DELETED = "poll.deleted",
    QUESTION_ASKED = "qa.question",
    QUESTION_ANSWERED = "qa.answer"
}
export interface WebhookPayload {
    event: WebhookEventType;
    timestamp: string;
    data: Record<string, any>;
}
interface WebhookConfig {
    secret?: string;
    endpoint: string;
}
type WebhookEventHandler = (payload: WebhookPayload) => Promise<void>;
/**
 * Webhook service for handling Digital Samba events
 *
 * This class provides the core functionality for receiving, processing, and
 * propagating webhook events from the Digital Samba API. It manages event
 * handlers, signature verification, and client notifications.
 *
 * @class
 * @example
 * const webhookService = new WebhookService(mcpServer, {
 *   secret: process.env.WEBHOOK_SECRET,
 *   endpoint: '/webhooks/digitalsamba'
 * });
 *
 * // Register an event handler
 * webhookService.on(WebhookEventType.RECORDING_READY, async (payload) => {
*   logger.info('Recording is ready:', payload.data.id);
* });
 *
 * // Register the webhook endpoint with Express
 * webhookService.registerWebhookEndpoint(app);
 */
export declare class WebhookService {
    private server;
    private config;
    private eventHandlers;
    /**
     * Create a new webhook service
     *
     * @constructor
     * @param {McpServer} server - The MCP server instance for notifications
     * @param {WebhookConfig} config - Configuration for the webhook service
     * @param {string} [config.secret] - Secret for verifying webhook signatures
     * @param {string} config.endpoint - HTTP endpoint path for receiving webhooks
     */
    constructor(server: McpServer, config: WebhookConfig);
    /**
     * Register the webhook endpoint with the Express app
     *
     * This method sets up the HTTP route that will receive webhook events from
     * the Digital Samba API and process them through the webhook service.
     *
     * @param {express.Application} app - Express application instance
     * @returns {void}
     */
    registerWebhookEndpoint(app: express.Application): void;
    /**
     * Handle incoming webhook requests
     *
     * This method processes HTTP requests to the webhook endpoint. It verifies
     * signatures if a secret is configured, validates the payload, and triggers
     * event processing.
     *
     * @private
     * @param {Request} req - Express request object
     * @param {Response} res - Express response object
     * @returns {Promise<void>}
     */
    private handleWebhookRequest;
    /**
     * Verify the webhook signature
     *
     * Uses HMAC-SHA256 to verify that the webhook was sent by Digital Samba
     * and that the payload hasn't been tampered with.
     *
     * @private
     * @param {Request} req - Express request object
     * @param {string} signature - Signature from the X-DigitalSamba-Signature header
     * @returns {boolean} True if signature is valid, false otherwise
     */
    private verifySignature;
    /**
     * Process a webhook event
     *
     * Executes all registered handlers for the event type and notifies MCP clients.
     *
     * @private
     * @param {WebhookPayload} payload - The webhook event payload
     * @returns {Promise<void>}
     */
    private processWebhookEvent;
    /**
     * Register a handler for a specific event type
     *
     * Allows custom logic to be executed when specific webhook events are received.
     *
     * @public
     * @param {WebhookEventType} event - The event type to listen for
     * @param {WebhookEventHandler} handler - Function to execute when event occurs
     * @returns {void}
     * @example
     * webhookService.on(WebhookEventType.RECORDING_READY, async (payload) => {
  *   logger.info(`Recording ${payload.data.id} is ready for viewing`);
  *   // Custom logic for when a recording is ready
  * });
     */
    on(event: WebhookEventType, handler: WebhookEventHandler): void;
    /**
     * Notify MCP clients about a webhook event
     *
     * Sends a notification to all connected MCP clients about the webhook event.
     * This allows clients to receive real-time updates about Digital Samba events.
     *
     * @private
     * @param {WebhookPayload} payload - The webhook event payload
     * @returns {Promise<void>}
     */
    private notifyMcpClients;
    /**
     * Create a notification object based on the event type
     *
     * Formats the webhook payload into a structured notification object
     * based on the event type, extracting relevant fields for each event category.
     *
     * @private
     * @param {WebhookPayload} payload - The webhook event payload
     * @returns {Object} Formatted notification object
     */
    private createNotificationForEvent;
    /**
     * Register or update a webhook with Digital Samba API
     *
     * Creates a new webhook registration or updates an existing one with
     * the Digital Samba API, specifying which events to subscribe to.
     *
     * @public
     * @param {string} apiKey - Digital Samba API key
     * @param {string} apiBaseUrl - Base URL for the Digital Samba API
     * @param {string} webhookUrl - URL where webhook events should be sent
     * @param {WebhookEventType[]} [eventTypes] - Event types to subscribe to (defaults to all)
     * @returns {Promise<void>}
     * @throws Will throw an error if the API request fails
     */
    registerWebhook(apiKey: string, apiBaseUrl: string, webhookUrl: string, eventTypes?: WebhookEventType[]): Promise<void>;
    /**
     * Delete a webhook with Digital Samba API
     *
     * Deletes a webhook registration with the Digital Samba API based on the URL.
     *
     * @public
     * @param {string} apiKey - Digital Samba API key
     * @param {string} apiBaseUrl - Base URL for the Digital Samba API
     * @param {string} webhookUrl - URL of the webhook to delete
     * @returns {Promise<void>}
     * @throws Will throw an error if the API request fails
     */
    deleteWebhook(apiKey: string, apiBaseUrl: string, webhookUrl: string): Promise<void>;
}
/**
 * Create webhook handling tools for MCP server
 *
 * Sets up MCP tools for managing webhooks, including registration, deletion,
 * and listing of webhooks and available event types. These tools allow clients
 * to interact with the webhook system through the MCP interface.
 *
 * @param {McpServer} server - The MCP server instance
 * @param {WebhookService} webhookService - The webhook service instance
 * @param {string} apiBaseUrl - Base URL for the Digital Samba API
 * @returns {void}
 */
export declare function setupWebhookTools(server: McpServer, webhookService: WebhookService, apiBaseUrl: string): void;
export default WebhookService;
//# sourceMappingURL=webhooks.d.ts.map