ffa7c13c9b
On gateway restart, persisted non-terminal calls are now verified with the provider (Twilio/Plivo/Telnyx) before being restored to memory. This prevents phantom calls from blocking the concurrent call limit. - Add getCallStatus() to VoiceCallProvider interface - Implement for all providers with SSRF-guarded fetch - Transient errors (5xx, network) keep the call with timer fallback - 404/known-terminal statuses drop the call - Restart max-duration timers for restored answered calls - Skip calls older than maxDurationSeconds or without providerCallId
79 lines
2.1 KiB
TypeScript
79 lines
2.1 KiB
TypeScript
import type {
|
|
GetCallStatusInput,
|
|
GetCallStatusResult,
|
|
HangupCallInput,
|
|
InitiateCallInput,
|
|
InitiateCallResult,
|
|
PlayTtsInput,
|
|
ProviderName,
|
|
WebhookParseOptions,
|
|
ProviderWebhookParseResult,
|
|
StartListeningInput,
|
|
StopListeningInput,
|
|
WebhookContext,
|
|
WebhookVerificationResult,
|
|
} from "../types.js";
|
|
|
|
/**
|
|
* Abstract base interface for voice call providers.
|
|
*
|
|
* Each provider (Telnyx, Twilio, etc.) implements this interface to provide
|
|
* a consistent API for the call manager.
|
|
*
|
|
* Responsibilities:
|
|
* - Webhook verification and event parsing
|
|
* - Outbound call initiation and hangup
|
|
* - Media control (TTS playback, STT listening)
|
|
*/
|
|
export interface VoiceCallProvider {
|
|
/** Provider identifier */
|
|
readonly name: ProviderName;
|
|
|
|
/**
|
|
* Verify webhook signature/HMAC before processing.
|
|
* Must be called before parseWebhookEvent.
|
|
*/
|
|
verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
|
|
|
|
/**
|
|
* Parse provider-specific webhook payload into normalized events.
|
|
* Returns events and optional response to send back to provider.
|
|
*/
|
|
parseWebhookEvent(ctx: WebhookContext, options?: WebhookParseOptions): ProviderWebhookParseResult;
|
|
|
|
/**
|
|
* Initiate an outbound call.
|
|
* @returns Provider call ID and status
|
|
*/
|
|
initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
|
|
|
|
/**
|
|
* Hang up an active call.
|
|
*/
|
|
hangupCall(input: HangupCallInput): Promise<void>;
|
|
|
|
/**
|
|
* Play TTS audio to the caller.
|
|
* The provider should handle streaming if supported.
|
|
*/
|
|
playTts(input: PlayTtsInput): Promise<void>;
|
|
|
|
/**
|
|
* Start listening for user speech (activate STT).
|
|
*/
|
|
startListening(input: StartListeningInput): Promise<void>;
|
|
|
|
/**
|
|
* Stop listening for user speech (deactivate STT).
|
|
*/
|
|
stopListening(input: StopListeningInput): Promise<void>;
|
|
|
|
/**
|
|
* Query provider for current call status.
|
|
* Used to verify persisted calls are still active on restart.
|
|
* Must return `isUnknown: true` for transient errors (network, 5xx)
|
|
* so the caller can keep the call and rely on timer-based fallback.
|
|
*/
|
|
getCallStatus(input: GetCallStatusInput): Promise<GetCallStatusResult>;
|
|
}
|