voice-router-dev 0.8.2 → 0.8.4

package/dist/webhooks.d.mts

@@ -1,12 +1,248 @@
-import { fF as TranscriptionStatus, fC as Speaker, fD as Word, fE as Utterance, Q as CallbackTranscriptionSuccessPayload, J as CallbackTranscriptionErrorPayload, cf as TranscriptWebhookNotification, d2 as ListenV1Response, ep as SpeechToTextChunkResponseModel } from './speechToTextChunkResponseModel-3IUnJXKx.mjs';
-import { T as TranscriptionProvider } from './provider-metadata-BnkedpXm.mjs';
+import { h9 as TranscriptionStatus, h6 as Speaker, h7 as Word, h8 as Utterance, Q as CallbackTranscriptionSuccessPayload, J as CallbackTranscriptionErrorPayload, bt as Transcript, dx as ListenV1Response, fj as RetrieveTranscriptResponse, fV as SpeechToTextChunkResponseModel } from './speechToTextChunkResponseModel-BcT1LJSZ.mjs';
+import { T as TranscriptionProvider } from './provider-metadata-MDUUEuqF.mjs';
 import './constants.mjs';
 
+/**
+ * Base webhook handler interface
+ * All provider-specific webhook handlers must implement this
+ */
+
+/**
+ * Abstract base class for webhook handlers
+ *
+ * Each provider implements this to parse and normalize their webhook payloads
+ */
+declare abstract class BaseWebhookHandler {
+    /** Provider name */
+    abstract readonly provider: TranscriptionProvider;
+    /**
+     * Check if this payload matches this provider's webhook format
+     *
+     * Used for auto-detection of webhook provider
+     *
+     * @param payload - Raw webhook payload
+     * @param options - Optional context (query params, headers, etc.)
+     * @returns true if this handler can process the payload
+     *
+     * @example
+     * ```typescript
+     * matches(payload, options) {
+     *   return typeof payload === 'object' &&
+     *          'event' in payload &&
+     *          'payload' in payload
+     * }
+     * ```
+     */
+    abstract matches(payload: unknown, options?: {
+        queryParams?: Record<string, string>;
+        userAgent?: string;
+    }): boolean;
+    /**
+     * Parse and normalize webhook payload
+     *
+     * Converts provider-specific webhook format to UnifiedWebhookEvent
+     *
+     * @param payload - Raw webhook payload
+     * @param options - Optional context (query params, headers, etc.)
+     * @returns Normalized webhook event
+     * @throws Error if payload cannot be parsed
+     *
+     * @example
+     * ```typescript
+     * parse(payload, options) {
+     *   const typed = payload as ProviderWebhookPayload
+     *   return {
+     *     success: true,
+     *     provider: this.provider,
+     *     eventType: 'transcription.completed',
+     *     data: { id: typed.job_id, ... },
+     *     timestamp: new Date().toISOString(),
+     *     raw: payload
+     *   }
+     * }
+     * ```
+     */
+    abstract parse(payload: unknown, options?: {
+        queryParams?: Record<string, string>;
+    }): UnifiedWebhookEvent;
+    /**
+     * Verify webhook signature (if provider supports it)
+     *
+     * Optional method - implement if provider supports webhook signature verification
+     *
+     * @param payload - Raw webhook payload
+     * @param options - Verification options (signature, secret, etc.)
+     * @returns true if signature is valid
+     *
+     * @example
+     * ```typescript
+     * verify(payload, options) {
+     *   if (!options.signature || !options.secret) return false
+     *
+     *   const computed = crypto
+     *     .createHmac('sha256', options.secret)
+     *     .update(JSON.stringify(payload))
+     *     .digest('hex')
+     *
+     *   return computed === options.signature
+     * }
+     * ```
+     */
+    verify?(payload: unknown, options: WebhookVerificationOptions): boolean;
+    /**
+     * Validate webhook payload structure
+     *
+     * Checks if payload has required fields and correct types
+     *
+     * @param payload - Raw webhook payload
+     * @param options - Optional context (query params, headers, etc.)
+     * @returns Validation result with details
+     */
+    validate(payload: unknown, options?: {
+        queryParams?: Record<string, string>;
+        userAgent?: string;
+    }): WebhookValidation;
+    /**
+     * Helper method to create error response
+     */
+    protected createErrorEvent(payload: unknown, errorMessage: string): UnifiedWebhookEvent;
+}
+
+/**
+ * Azure Speech-to-Text webhook handler
+ * Parses and normalizes Azure STT webhook callbacks
+ */
+
+/**
+ * Azure webhook event payload structure
+ * Based on Azure Speech Services v3.1 webhook format
+ */
+interface AzureWebhookPayload {
+    /** Event action (e.g., "TranscriptionCreated", "TranscriptionSucceeded", "TranscriptionFailed") */
+    action: string;
+    /** Timestamp of the event */
+    timestamp: string;
+    /** Self-link to the resource */
+    self?: string;
+    /** Additional properties */
+    properties?: Record<string, unknown>;
+    /** Error details (for failed events) */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Azure webhook handler
+ *
+ * Handles webhook callbacks from Azure Speech Services API:
+ * - TranscriptionCreated - Transcription job created
+ * - TranscriptionRunning - Transcription is processing
+ * - TranscriptionSucceeded - Transcription completed successfully
+ * - TranscriptionFailed - Transcription failed with error
+ *
+ * Azure supports optional webhook signature verification using a shared secret.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { AzureWebhookHandler } from '@meeting-baas/sdk';
+ *
+ * const handler = new AzureWebhookHandler();
+ *
+ * // Validate webhook
+ * const validation = handler.validate(req.body);
+ * if (!validation.valid) {
+ *   return res.status(400).json({ error: validation.error });
+ * }
+ *
+ * // Parse webhook
+ * const event = handler.parse(req.body);
+ * console.log('Event type:', event.eventType);
+ * console.log('Action:', event.raw.action);
+ * ```
+ *
+ * @example With signature verification
+ * ```typescript
+ * // Verify webhook signature (if configured in Azure)
+ * const isValid = handler.verify(req.body, {
+ *   signature: req.headers['x-azure-signature'],
+ *   secret: process.env.AZURE_WEBHOOK_SECRET,
+ *   rawBody: req.rawBody
+ * });
+ *
+ * if (!isValid) {
+ *   return res.status(401).json({ error: 'Invalid signature' });
+ * }
+ * ```
+ *
+ * @example Processing completed transcription
+ * ```typescript
+ * const event = handler.parse(req.body);
+ *
+ * if (event.eventType === 'transcription.completed') {
+ *   // Extract transcription ID from self link
+ *   const transcriptionId = event.data?.id;
+ *
+ *   // Fetch full transcript using AzureAdapter.getTranscript(transcriptionId)
+ *   console.log('Transcription completed:', transcriptionId);
+ * }
+ * ```
+ */
+declare class AzureWebhookHandler extends BaseWebhookHandler {
+    readonly provider: TranscriptionProvider;
+    /**
+     * Check if payload matches Azure webhook format
+     */
+    matches(payload: unknown, _options?: {
+        queryParams?: Record<string, string>;
+        userAgent?: string;
+    }): boolean;
+    /**
+     * Parse Azure webhook payload to unified format
+     */
+    parse(payload: unknown, _options?: {
+        queryParams?: Record<string, string>;
+    }): UnifiedWebhookEvent;
+    /**
+     * Verify Azure webhook signature
+     *
+     * Azure can optionally sign webhooks using HMAC-SHA256.
+     * The signature is sent in the X-Azure-Signature header.
+     *
+     * Note: Signature verification is optional in Azure and must be
+     * configured when creating the webhook.
+     *
+     * @param payload - Webhook payload
+     * @param options - Verification options with signature and secret
+     * @returns true if signature is valid or no signature provided
+     *
+     * @example
+     * ```typescript
+     * const isValid = handler.verify(req.body, {
+     *   signature: req.headers['x-azure-signature'],
+     *   secret: process.env.AZURE_WEBHOOK_SECRET,
+     *   rawBody: req.rawBody
+     * });
+     * ```
+     */
+    verify(payload: unknown, options: WebhookVerificationOptions): boolean;
+}
+/**
+ * Factory function to create an Azure webhook handler
+ */
+declare function createAzureWebhookHandler(): AzureWebhookHandler;
+
 /**
  * Unified webhook types for transcription providers
  * Normalizes webhook callbacks from different providers to a common format
  */
 
+/** AssemblyAI webhook payload — either a full Transcript or a lightweight notification (webhook schemas dropped from docs spec) */
+type AssemblyAIWebhookPayload = Transcript | {
+    transcript_id: string;
+    status: string;
+};
+
 /**
  * Union of all Gladia webhook payloads
  */
@@ -16,11 +252,11 @@ type GladiaWebhookPayload = CallbackTranscriptionSuccessPayload | CallbackTransc
  */
 type ProviderWebhookPayloadMap = {
     gladia: GladiaWebhookPayload;
-    assemblyai: TranscriptWebhookNotification;
+    assemblyai: AssemblyAIWebhookPayload;
     deepgram: ListenV1Response;
-    "azure-stt": unknown;
+    "azure-stt": AzureWebhookPayload;
     "openai-whisper": never;
-    speechmatics: unknown;
+    speechmatics: RetrieveTranscriptResponse;
     elevenlabs: SpeechToTextChunkResponseModel;
 };
 /**
@@ -123,112 +359,6 @@ interface WebhookVerificationOptions {
     headers?: Record<string, string>;
 }
 
-/**
- * Base webhook handler interface
- * All provider-specific webhook handlers must implement this
- */
-
-/**
- * Abstract base class for webhook handlers
- *
- * Each provider implements this to parse and normalize their webhook payloads
- */
-declare abstract class BaseWebhookHandler {
-    /** Provider name */
-    abstract readonly provider: TranscriptionProvider;
-    /**
-     * Check if this payload matches this provider's webhook format
-     *
-     * Used for auto-detection of webhook provider
-     *
-     * @param payload - Raw webhook payload
-     * @param options - Optional context (query params, headers, etc.)
-     * @returns true if this handler can process the payload
-     *
-     * @example
-     * ```typescript
-     * matches(payload, options) {
-     *   return typeof payload === 'object' &&
-     *          'event' in payload &&
-     *          'payload' in payload
-     * }
-     * ```
-     */
-    abstract matches(payload: unknown, options?: {
-        queryParams?: Record<string, string>;
-        userAgent?: string;
-    }): boolean;
-    /**
-     * Parse and normalize webhook payload
-     *
-     * Converts provider-specific webhook format to UnifiedWebhookEvent
-     *
-     * @param payload - Raw webhook payload
-     * @param options - Optional context (query params, headers, etc.)
-     * @returns Normalized webhook event
-     * @throws Error if payload cannot be parsed
-     *
-     * @example
-     * ```typescript
-     * parse(payload, options) {
-     *   const typed = payload as ProviderWebhookPayload
-     *   return {
-     *     success: true,
-     *     provider: this.provider,
-     *     eventType: 'transcription.completed',
-     *     data: { id: typed.job_id, ... },
-     *     timestamp: new Date().toISOString(),
-     *     raw: payload
-     *   }
-     * }
-     * ```
-     */
-    abstract parse(payload: unknown, options?: {
-        queryParams?: Record<string, string>;
-    }): UnifiedWebhookEvent;
-    /**
-     * Verify webhook signature (if provider supports it)
-     *
-     * Optional method - implement if provider supports webhook signature verification
-     *
-     * @param payload - Raw webhook payload
-     * @param options - Verification options (signature, secret, etc.)
-     * @returns true if signature is valid
-     *
-     * @example
-     * ```typescript
-     * verify(payload, options) {
-     *   if (!options.signature || !options.secret) return false
-     *
-     *   const computed = crypto
-     *     .createHmac('sha256', options.secret)
-     *     .update(JSON.stringify(payload))
-     *     .digest('hex')
-     *
-     *   return computed === options.signature
-     * }
-     * ```
-     */
-    verify?(payload: unknown, options: WebhookVerificationOptions): boolean;
-    /**
-     * Validate webhook payload structure
-     *
-     * Checks if payload has required fields and correct types
-     *
-     * @param payload - Raw webhook payload
-     * @param options - Optional context (query params, headers, etc.)
-     * @returns Validation result with details
-     */
-    validate(payload: unknown, options?: {
-        queryParams?: Record<string, string>;
-        userAgent?: string;
-    }): WebhookValidation;
-    /**
-     * Helper method to create error response
-     */
-    protected createErrorEvent(payload: unknown, errorMessage: string): UnifiedWebhookEvent;
-}
-
 /**
  * Gladia webhook handler
  * Parses and normalizes Gladia webhook callbacks
@@ -514,111 +644,6 @@ declare class DeepgramWebhookHandler extends BaseWebhookHandler {
  */
 declare function createDeepgramWebhookHandler(): DeepgramWebhookHandler;
 
-/**
- * Azure Speech-to-Text webhook handler
- * Parses and normalizes Azure STT webhook callbacks
- */
-
-/**
- * Azure webhook handler
- *
- * Handles webhook callbacks from Azure Speech Services API:
- * - TranscriptionCreated - Transcription job created
- * - TranscriptionRunning - Transcription is processing
- * - TranscriptionSucceeded - Transcription completed successfully
- * - TranscriptionFailed - Transcription failed with error
- *
- * Azure supports optional webhook signature verification using a shared secret.
- *
- * @example Basic usage
- * ```typescript
- * import { AzureWebhookHandler } from '@meeting-baas/sdk';
- *
- * const handler = new AzureWebhookHandler();
- *
- * // Validate webhook
- * const validation = handler.validate(req.body);
- * if (!validation.valid) {
- *   return res.status(400).json({ error: validation.error });
- * }
- *
- * // Parse webhook
- * const event = handler.parse(req.body);
- * console.log('Event type:', event.eventType);
- * console.log('Action:', event.raw.action);
- * ```
- *
- * @example With signature verification
- * ```typescript
- * // Verify webhook signature (if configured in Azure)
- * const isValid = handler.verify(req.body, {
- *   signature: req.headers['x-azure-signature'],
- *   secret: process.env.AZURE_WEBHOOK_SECRET,
- *   rawBody: req.rawBody
- * });
- *
- * if (!isValid) {
- *   return res.status(401).json({ error: 'Invalid signature' });
- * }
- * ```
- *
- * @example Processing completed transcription
- * ```typescript
- * const event = handler.parse(req.body);
- *
- * if (event.eventType === 'transcription.completed') {
- *   // Extract transcription ID from self link
- *   const transcriptionId = event.data?.id;
- *
- *   // Fetch full transcript using AzureAdapter.getTranscript(transcriptionId)
- *   console.log('Transcription completed:', transcriptionId);
- * }
- * ```
- */
-declare class AzureWebhookHandler extends BaseWebhookHandler {
-    readonly provider: TranscriptionProvider;
-    /**
-     * Check if payload matches Azure webhook format
-     */
-    matches(payload: unknown, _options?: {
-        queryParams?: Record<string, string>;
-        userAgent?: string;
-    }): boolean;
-    /**
-     * Parse Azure webhook payload to unified format
-     */
-    parse(payload: unknown, _options?: {
-        queryParams?: Record<string, string>;
-    }): UnifiedWebhookEvent;
-    /**
-     * Verify Azure webhook signature
-     *
-     * Azure can optionally sign webhooks using HMAC-SHA256.
-     * The signature is sent in the X-Azure-Signature header.
-     *
-     * Note: Signature verification is optional in Azure and must be
-     * configured when creating the webhook.
-     *
-     * @param payload - Webhook payload
-     * @param options - Verification options with signature and secret
-     * @returns true if signature is valid or no signature provided
-     *
-     * @example
-     * ```typescript
-     * const isValid = handler.verify(req.body, {
-     *   signature: req.headers['x-azure-signature'],
-     *   secret: process.env.AZURE_WEBHOOK_SECRET,
-     *   rawBody: req.rawBody
-     * });
-     * ```
-     */
-    verify(payload: unknown, options: WebhookVerificationOptions): boolean;
-}
-/**
- * Factory function to create an Azure webhook handler
- */
-declare function createAzureWebhookHandler(): AzureWebhookHandler;
-
 /**
  * Speechmatics webhook handler
  * Parses and normalizes Speechmatics webhook callbacks
@@ -957,4 +982,4 @@ declare class WebhookRouter {
  */
 declare function createWebhookRouter(): WebhookRouter;
 
-export { AssemblyAIWebhookHandler, TranscriptWebhookNotification as AssemblyAIWebhookPayload, AzureWebhookHandler, BaseWebhookHandler, DeepgramWebhookHandler, ListenV1Response as DeepgramWebhookPayload, ElevenLabsWebhookHandler, CallbackTranscriptionErrorPayload as GladiaWebhookErrorPayload, GladiaWebhookHandler, type GladiaWebhookPayload, CallbackTranscriptionSuccessPayload as GladiaWebhookSuccessPayload, type ProviderWebhookPayloadMap, SpeechmaticsWebhookHandler, type UnifiedWebhookEvent, type WebhookEventType, WebhookRouter, type WebhookRouterOptions, type WebhookRouterResult, type WebhookValidation, type WebhookVerificationOptions, createAssemblyAIWebhookHandler, createAzureWebhookHandler, createDeepgramWebhookHandler, createElevenLabsWebhookHandler, createGladiaWebhookHandler, createWebhookRouter };
+export { AssemblyAIWebhookHandler, type AssemblyAIWebhookPayload, AzureWebhookHandler, BaseWebhookHandler, DeepgramWebhookHandler, ListenV1Response as DeepgramWebhookPayload, ElevenLabsWebhookHandler, CallbackTranscriptionErrorPayload as GladiaWebhookErrorPayload, GladiaWebhookHandler, type GladiaWebhookPayload, CallbackTranscriptionSuccessPayload as GladiaWebhookSuccessPayload, type ProviderWebhookPayloadMap, SpeechmaticsWebhookHandler, type UnifiedWebhookEvent, type WebhookEventType, WebhookRouter, type WebhookRouterOptions, type WebhookRouterResult, type WebhookValidation, type WebhookVerificationOptions, createAssemblyAIWebhookHandler, createAzureWebhookHandler, createDeepgramWebhookHandler, createElevenLabsWebhookHandler, createGladiaWebhookHandler, createWebhookRouter };