@sinch/functions-runtime 0.3.8 → 0.3.9

package/dist/index.d.ts

@@ -2,6 +2,7 @@
 
 import { ConversationService } from '@sinch/conversation';
 import { NumbersService } from '@sinch/numbers';
+import { Conversation, ConversationService } from '@sinch/sdk-core';
 import { SmsService } from '@sinch/sms';
 import { Voice, VoiceService } from '@sinch/voice';
 import { Express as Express$1, NextFunction, Request as Request$1, Response as Response$1 } from 'express';
@@ -377,7 +378,15 @@ export declare const MenuTemplates: {
 	 */
 	readonly numericInput: (prompt: string, digits?: number) => MenuStructure;
 };
-declare enum AgentProvider {
+/**
+ * Connect Agent Action for SVAML Builders
+ *
+ * Provides the ability to connect voice calls to AI agents via SIP.
+ */
+/**
+ * Supported AI agent providers
+ */
+export declare enum AgentProvider {
 	ElevenLabs = "elevenlabs"
 }
 /**
@@ -557,6 +566,21 @@ export declare class IceSvamlBuilder extends BaseSvamlBuilder<IceSvamlBuilder> {
 	 *
 	 * @param number - E.164 formatted phone number (e.g., '+15551234567')
 	 * @param options - Connection options
+	 *
+	 * @example
+	 * ```typescript
+	 * // Simple connect
+	 * new IceSvamlBuilder().connectPstn('+15551234567').build();
+	 *
+	 * // With options: caller ID, timeout, and AMD
+	 * new IceSvamlBuilder()
+	 *   .connectPstn('+15551234567', {
+	 *     cli: '+15559876543',
+	 *     timeout: 30,
+	 *     amd: { enabled: true },
+	 *   })
+	 *   .build();
+	 * ```
 	 */
 	connectPstn(number: string, options?: ConnectPstnOptions): this;
 	/**
@@ -585,6 +609,22 @@ export declare class IceSvamlBuilder extends BaseSvamlBuilder<IceSvamlBuilder> {
 	 *
 	 * @param menus - Array of menu definitions or MenuStructure from createMenu().build()
 	 * @param options - Menu options
+	 *
+	 * @example
+	 * ```typescript
+	 * // Using MenuTemplates
+	 * new IceSvamlBuilder()
+	 *   .runMenu(MenuTemplates.business('Acme Corp'))
+	 *   .build();
+	 *
+	 * // Using createMenu builder
+	 * const menu = createMenu()
+	 *   .prompt('Press 1 for sales, 2 for support.')
+	 *   .option('1', 'return(sales)')
+	 *   .option('2', 'return(support)')
+	 *   .build();
+	 * new IceSvamlBuilder().runMenu(menu).build();
+	 * ```
 	 */
 	runMenu(menus: Menu[] | MenuStructure, options?: RunMenuOptions): this;
 	/**
@@ -592,6 +632,14 @@ export declare class IceSvamlBuilder extends BaseSvamlBuilder<IceSvamlBuilder> {
 	 *
 	 * @param holdPrompt - Prompt to play while on hold
 	 * @param options - Park options
+	 *
+	 * @example
+	 * ```typescript
+	 * // Park with hold music prompt
+	 * new IceSvamlBuilder()
+	 *   .park('Please hold while we connect you.', { maxDuration: 120 })
+	 *   .build();
+	 * ```
 	 */
 	park(holdPrompt?: string, options?: ParkOptions): this;
 	/**
@@ -719,8 +767,23 @@ export declare function createPieBuilder(): PieSvamlBuilder;
  * Function cache interface
  *
  * Provides key-value storage with TTL support.
- * In development, uses in-memory storage.
- * In production, uses Dapr state store.
+ * In development, uses in-memory storage (data lost on restart).
+ * In production, uses persistent shared storage across instances.
+ *
+ * Access via `context.cache` — do not construct directly.
+ *
+ * @example
+ * ```typescript
+ * // Store a session with 30-minute TTL
+ * await context.cache.set('session:abc', { userId: 'u1' }, 1800);
+ *
+ * // Retrieve it later
+ * const session = await context.cache.get<{ userId: string }>('session:abc');
+ *
+ * // List and batch retrieve
+ * const keys = await context.cache.keys('session:*');
+ * const all = await context.cache.getMany(keys);
+ * ```
  */
 export interface IFunctionCache {
 	/**
@@ -729,6 +792,11 @@ export interface IFunctionCache {
 	 * @param key - Cache key
 	 * @param value - Value to store (will be JSON serialized)
 	 * @param ttlSeconds - Time to live in seconds (default: 3600)
+	 *
+	 * @example
+	 * ```typescript
+	 * await context.cache.set('user:123', { name: 'Alice' }, 3600);
+	 * ```
 	 */
 	set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
 	/**
@@ -736,6 +804,12 @@ export interface IFunctionCache {
 	 *
 	 * @param key - Cache key
 	 * @returns The stored value or null if not found/expired
+	 *
+	 * @example
+	 * ```typescript
+	 * const user = await context.cache.get<{ name: string }>('user:123');
+	 * if (user) console.log(user.name);
+	 * ```
 	 */
 	get<T = unknown>(key: string): Promise<T | null>;
 	/**
@@ -757,6 +831,12 @@ export interface IFunctionCache {
 	 * @param key - Cache key
 	 * @param additionalSeconds - Additional seconds to add to TTL
 	 * @returns true if the key exists and TTL was extended
+	 *
+	 * @example
+	 * ```typescript
+	 * // Keep session alive for another 10 minutes
+	 * await context.cache.extend('session:abc', 600);
+	 * ```
 	 */
 	extend(key: string, additionalSeconds: number): Promise<boolean>;
 	/**
@@ -764,6 +844,11 @@ export interface IFunctionCache {
 	 *
 	 * @param pattern - Pattern with * wildcard (default: '*')
 	 * @returns Array of matching keys
+	 *
+	 * @example
+	 * ```typescript
+	 * const sessionKeys = await context.cache.keys('session:*');
+	 * ```
 	 */
 	keys(pattern?: string): Promise<string[]>;
 	/**
@@ -771,6 +856,12 @@ export interface IFunctionCache {
 	 *
 	 * @param keys - Array of keys to retrieve
 	 * @returns Object with keys and their values (or null if not found)
+	 *
+	 * @example
+	 * ```typescript
+	 * const keys = await context.cache.keys('user:*');
+	 * const users = await context.cache.getMany<User>(keys);
+	 * ```
 	 */
 	getMany<T = unknown>(keys: string[]): Promise<Record<string, T | null>>;
 }
@@ -790,13 +881,30 @@ export interface FunctionConfig {
 /**
  * Main function context object passed to all handlers
  *
- * Note: Call-specific data like callId is available on the callback event data,
+ * Every handler receives this as its first argument. It provides access to
+ * configuration, cache, SDK clients, and environment variables.
+ *
+ * @remarks
+ * Call-specific data like callId is available on the callback event data,
  * not on the context object.
+ *
+ * @example
+ * ```typescript
+ * export async function ice(context, event) {
+ *   const greeting = context.config.variables?.GREETING ?? 'Hello!';
+ *   await context.cache.set('lastCaller', event.cli, 3600);
+ *   return new IceSvamlBuilder().say(greeting).hangup().build();
+ * }
+ * ```
  */
 export interface FunctionContext {
 	/** Configuration including environment variables */
 	config: FunctionConfig;
-	/** Cache client for persistent data */
+	/**
+	 * Key-value cache with TTL support.
+	 * In-memory during development, persistent and shared in production.
+	 * @see {@link IFunctionCache} for available methods
+	 */
 	cache: IFunctionCache;
 	/** Request ID for tracing */
 	requestId?: string;
@@ -804,13 +912,25 @@ export interface FunctionContext {
 	timestamp?: string;
 	/** Environment variables */
 	env?: Record<string, string | undefined>;
-	/** Sinch Voice SDK client (if available) */
+	/**
+	 * Sinch Voice SDK client.
+	 * Available when `VOICE_APPLICATION_KEY` and `VOICE_APPLICATION_SECRET` are set.
+	 */
 	voice?: VoiceService;
-	/** Sinch Conversation SDK client (if available) */
+	/**
+	 * Sinch Conversation SDK client.
+	 * Available when `CONVERSATION_APP_ID` is set.
+	 */
 	conversation?: ConversationService;
-	/** Sinch SMS SDK client (if available) */
+	/**
+	 * Sinch SMS SDK client.
+	 * Available when `SMS_SERVICE_PLAN_ID` is set.
+	 */
 	sms?: SmsService;
-	/** Sinch Numbers SDK client (if available) */
+	/**
+	 * Sinch Numbers SDK client.
+	 * Available when `ENABLE_NUMBERS_API=true` is set.
+	 */
 	numbers?: NumbersService;
 	/** Read a file from the assets/ directory (private, not served over HTTP) */
 	assets(filename: string): Promise<string>;
@@ -1041,6 +1161,7 @@ export interface VoiceFunction {
 export type SinchFunction = VoiceFunction;
 /**
  * Options for camelCase key transformation
+ * @internal
  */
 export interface CamelCaseOptions {
 	/** Transform nested objects */
@@ -1052,6 +1173,7 @@ export interface CamelCaseOptions {
 }
 /**
  * Options for JSON parsing middleware
+ * @internal
  */
 export interface JsonParsingOptions {
 	/** Maximum body size (default: '10mb') */
@@ -1063,6 +1185,7 @@ export interface JsonParsingOptions {
 }
 /**
  * Extended Express Request with rawBody for signature validation
+ * @internal
  */
 export interface SinchRequest extends Request {
 	rawBody?: string;
@@ -1075,26 +1198,44 @@ export interface SinchRequest extends Request {
  * - snake_case: call_id -> callId
  * - kebab-case: call-id -> callId
  * - lowercase concatenated: callid -> callId
+ * @internal
  */
 export declare function toCamelCase(str: string): string;
 /**
  * Deep transform object keys to camelCase
+ * @internal
  */
 export declare function transformKeys<T>(obj: T, options?: CamelCaseOptions): T;
 /**
  * Parse JSON with fallback to basic JSON5 support
+ * @internal
  */
 export declare function parseJson(text: string, allowJson5?: boolean): unknown;
 /**
  * Create Express middleware for lenient JSON parsing with camelCase transformation
+ * @internal
  */
 export declare function createLenientJsonParser(options?: JsonParsingOptions): (req: SinchRequest, res: Response, next: NextFunction) => void;
 /**
  * Setup Express app with JSON parsing middleware
+ * @internal
  */
 export declare function setupJsonParsing(app: Express, options?: JsonParsingOptions): Express;
+/**
+ * Get the landing page HTML content
+ * Exported so production runtime can also use it
+ * @internal
+ */
+export declare function getLandingPageHtml(): string;
+/**
+ * Get the favicon SVG content
+ * Exported so production runtime can also use it
+ * @internal
+ */
+export declare function getFaviconSvg(): string;
 /**
  * Options for creating the Express app
+ * @internal
  */
 export interface AppOptions {
 	/** JSON parsing options */
@@ -1106,6 +1247,7 @@ export interface AppOptions {
 }
 /**
  * Options for setting up the request handler
+ * @internal
  */
 export interface RequestHandlerOptions {
 	/** Function to load user code module (can be sync or async for ESM) */
@@ -1133,13 +1275,14 @@ export interface RequestHandlerOptions {
 }
 /**
  * Formatted response structure
+ * @internal
  */
 export interface FormattedResponse {
 	statusCode: number;
 	headers?: Record<string, string>;
 	body?: unknown;
 }
-/** Voice callback function names */
+/** Voice callback function names @internal */
 export declare const VOICE_CALLBACKS: readonly [
 	"ice",
 	"ace",
@@ -1147,7 +1290,7 @@ export declare const VOICE_CALLBACKS: readonly [
 	"dice",
 	"notify"
 ];
-/** Notification-only events (don't require SVAML response) */
+/** Notification-only events (don't require SVAML response) @internal */
 export declare const NOTIFICATION_EVENTS: readonly [
 	"dice",
 	"notify"
@@ -1156,32 +1299,39 @@ export type VoiceCallback = (typeof VOICE_CALLBACKS)[number];
 export type NotificationEvent = (typeof NOTIFICATION_EVENTS)[number];
 /**
  * Check if a function name is a voice callback
+ * @internal
  */
 export declare function isVoiceCallback(functionName: string): functionName is VoiceCallback;
 /**
  * Check if a function is a notification-only event
+ * @internal
  */
 export declare function isNotificationEvent(functionName: string): functionName is NotificationEvent;
 /**
  * Extract function name from request path or body
+ * @internal
  */
 export declare function extractFunctionName(path: string, body?: {
 	event?: string;
 }): string;
 /**
  * Generate unique request ID
+ * @internal
  */
 export declare function generateRequestId(): string;
 /**
  * Format SVAML response for voice callbacks
+ * @internal
  */
 export declare function formatSvamlResponse(result: unknown, functionName: string): FormattedResponse;
 /**
  * Format custom endpoint response
+ * @internal
  */
 export declare function formatCustomResponse(result: unknown): FormattedResponse;
 /**
  * Validate voice callback request
+ * @internal
  */
 export declare function validateVoiceRequest(body: unknown): {
 	valid: boolean;
@@ -1193,22 +1343,27 @@ export declare function validateVoiceRequest(body: unknown): {
  *
  * Note: Call-specific data like callId is available on the callback event data,
  * not on the context object.
+ * @internal
  */
 export declare function buildBaseContext(req: Request, config?: Partial<FunctionConfig>): FunctionContext;
 /**
  * Handle voice callback execution
+ * @internal
  */
 export declare function handleVoiceCallback(functionName: string, userFunction: SinchFunction, context: FunctionContext, callbackData: unknown, logger?: (...args: unknown[]) => void): Promise<FormattedResponse>;
 /**
  * Handle custom endpoint execution
+ * @internal
  */
 export declare function handleCustomEndpoint(functionName: string, userFunction: SinchFunction, context: FunctionContext, request: FunctionRequest, logger?: (...args: unknown[]) => void): Promise<FormattedResponse>;
 /**
  * Create and configure Express app with standard middleware
+ * @internal
  */
 export declare function createApp(options?: AppOptions): Express;
 /**
  * Setup the main request handler
+ * @internal
  */
 export declare function setupRequestHandler(app: Express, options?: RequestHandlerOptions): void;
 export interface SinchClients {
@@ -1233,83 +1388,868 @@ export declare function getSinchClients(): SinchClients;
  */
 export declare function resetSinchClients(): void;
 /**
- * Simple template renderer for HTML files
- * Replaces {{variableName}} placeholders with actual values
+ * ElevenLabs API Models for Sinch Functions
+ *
+ * TypeScript interfaces matching the C# models for ElevenLabs integration.
+ */
+/**
+ * Options for initiating an outbound call via ElevenLabs
+ */
+export interface ElevenLabsCallOptions {
+	/** The ElevenLabs agent ID to use for the call */
+	agentId: string;
+	/** The phone number to call (E.164 format) */
+	toNumber: string;
+	/** The caller ID to display (E.164 format) */
+	fromNumber: string;
+	/** Dynamic variables to pass to the agent */
+	dynamicVariables?: Record<string, string>;
+}
+/**
+ * Response from ElevenLabs outbound call API
+ */
+export interface ElevenLabsOutboundCallResponse {
+	call_id: string;
+	agent_id: string;
+	customer_phone_number: string;
+	agent_phone_number?: string;
+	status: string;
+}
+/**
+ * Conversation details from ElevenLabs
+ */
+export interface ElevenLabsConversationDetails {
+	conversationId: string;
+	agentId: string;
+	status: string;
+	metadata?: ConversationMetadata;
+	transcript?: TranscriptMessage[];
+	analysis?: ConversationAnalysis;
+}
+/**
+ * Call metadata
+ */
+export interface ConversationMetadata {
+	callDurationSeconds?: number;
+	startTime?: Date;
+	endTime?: Date;
+}
+/**
+ * A single transcript message
+ */
+export interface TranscriptMessage {
+	role: "user" | "agent";
+	message: string;
+	timeInCallSeconds?: number;
+}
+/**
+ * Conversation analysis results
+ */
+export interface ConversationAnalysis {
+	summary?: string;
+	customData?: Record<string, unknown>;
+}
+/**
+ * Options for auto-configuring ElevenLabs with Sinch SIP trunk.
+ * Matches the C# ElevenLabsAutoConfigOptions.
+ */
+export interface ElevenLabsAutoConfigOptions {
+	/** The ElevenLabs agent ID to configure */
+	agentId: string;
+	/** Sinch phone number in E.164 format (e.g. +15551234567) */
+	phoneNumber: string;
+	/** SIP trunk address (e.g. "use1.vp.sip.sinch.com") */
+	sipAddress: string;
+	/** SIP trunk username (VOICE_APPLICATION_KEY) */
+	sipUsername: string;
+	/** SIP trunk password (VOICE_APPLICATION_SECRET) */
+	sipPassword: string;
+	/** Base URL for webhook callbacks. If not provided, webhooks won't be configured */
+	webhookBaseUrl?: string;
+	/** Function name used as label in ElevenLabs (default: "Sinch Function") */
+	functionName?: string;
+}
+/**
+ * Result of auto-configuration
  */
-export declare class TemplateRender {
+export interface ElevenLabsAutoConfigResult {
+	success: boolean;
+	phoneNumberId?: string;
+	phoneNumber?: string;
+	sipAddress?: string;
+	agentId?: string;
+	error?: string;
+}
+/**
+ * Client for interacting with ElevenLabs Conversational AI
+ */
+export declare class ElevenLabsClient {
+	private readonly apiKey;
+	constructor(apiKey?: string);
+	private get authHeaders();
+	/**
+	 * Initiate an outbound call to a phone number using an ElevenLabs agent
+	 */
+	makeCall(options: ElevenLabsCallOptions): Promise<ElevenLabsOutboundCallResponse>;
+	/**
+	 * Get conversation details including transcript and analysis
+	 */
+	getConversationDetails(conversationId: string): Promise<ElevenLabsConversationDetails>;
+	/**
+	 * Auto-configure ElevenLabs with Sinch SIP trunk.
+	 *
+	 * Step 1: Get or import phone number with SIP trunk config
+	 * Step 2: Configure agent conversation-init webhook
+	 *
+	 * Called by tryAutoConfigureAsync (the orchestrator that reads env vars).
+	 */
+	autoConfigureAsync(options: ElevenLabsAutoConfigOptions): Promise<ElevenLabsAutoConfigResult>;
+	/**
+	 * Check if phone number already exists in ElevenLabs; create or update it.
+	 * Matches C# GetOrImportPhoneNumberAsync.
+	 */
+	private getOrImportPhoneNumber;
+	/**
+	 * Update phone number with agent association and SIP trunk config.
+	 * Matches C# UpdatePhoneNumberConfigAsync.
+	 */
+	private updatePhoneNumberConfig;
+	/**
+	 * Configure agent webhook for conversation-init events.
+	 * Matches C# ConfigureAgentWebhooksAsync.
+	 */
+	private configureAgentWebhooks;
+	/**
+	 * Map API response to our interface
+	 */
+	private mapConversationResponse;
+}
+/**
+ * Create an ElevenLabs client with the default API key
+ */
+export declare function createElevenLabsClient(apiKey?: string): ElevenLabsClient;
+/**
+ * ElevenLabs Webhook Models for Sinch Functions
+ *
+ * TypeScript interfaces for ElevenLabs webhook payloads.
+ */
+/**
+ * Conversation initialization request from ElevenLabs
+ * Sent when an inbound call is received
+ */
+export interface ConversationInitRequest {
+	/** The agent ID handling the call */
+	agent_id: string;
+	/** The caller's phone number */
+	caller_id?: string;
+	/** The called number */
+	called_number?: string;
+	/** SIP call ID */
+	call_sid?: string;
+}
+/**
+ * Response for conversation initialization
+ * Allows customizing the conversation for this specific caller
+ */
+export interface ConversationInitResponse {
+	/** Dynamic variables to use in the conversation */
+	dynamic_variables?: Record<string, string>;
+	/** Override agent configuration for this call */
+	conversation_config_override?: ConversationConfigOverride;
+}
+/**
+ * Configuration override for a specific conversation
+ */
+export interface ConversationConfigOverride {
+	agent?: AgentOverride;
+	tts?: TtsOverride;
+	turn?: TurnOverride;
+}
+/**
+ * Agent-level configuration override
+ */
+export interface AgentOverride {
+	/** Custom first message for this call */
+	first_message?: string;
+	/** Language override (e.g., "en", "es") */
+	language?: string;
+	/** Custom prompt override */
+	prompt?: string;
+}
+/**
+ * Text-to-speech configuration override
+ */
+export interface TtsOverride {
+	/** Voice ID to use */
+	voice_id?: string;
+	/** Voice settings */
+	voice_settings?: {
+		stability?: number;
+		similarity_boost?: number;
+	};
+}
+/**
+ * Turn-taking configuration override
+ */
+export interface TurnOverride {
+	/** Silence threshold in milliseconds */
+	silence_threshold_ms?: number;
+}
+/**
+ * Post-call webhook payload from ElevenLabs
+ */
+export interface ElevenLabsPostCallWebhook {
+	type: "post_call_transcription";
+	event_timestamp: string;
+	data: ConversationData;
+}
+/**
+ * Conversation data in post-call webhook
+ */
+export interface ConversationData {
+	agent_id: string;
+	conversation_id: string;
+	status: string;
+	user_id?: string;
+	transcript: TranscriptTurn[];
+	metadata: WebhookConversationMetadata;
+	analysis?: WebhookConversationAnalysis;
+}
+/**
+ * A single turn in the transcript
+ */
+export interface TranscriptTurn {
+	role: "user" | "agent";
+	message: string;
+	time_in_call_secs: number;
+}
+/**
+ * Conversation metadata in webhook
+ */
+export interface WebhookConversationMetadata {
+	start_time_unix_secs: number;
+	call_duration_secs: number;
+	cost?: number;
+	termination_reason?: string;
+}
+/**
+ * Conversation analysis in webhook
+ */
+export interface WebhookConversationAnalysis {
+	evaluation_criteria_results?: EvaluationCriteriaResult[];
+	data_collection_results?: DataCollectionResult[];
+	call_successful?: boolean;
+	transcript_summary?: string;
+}
+/**
+ * Result of an evaluation criteria check
+ */
+export interface EvaluationCriteriaResult {
+	criteria_id: string;
+	result: "success" | "failure" | "unknown";
+	rationale?: string;
+}
+/**
+ * Result of data collection
+ */
+export interface DataCollectionResult {
+	data_collection_id: string;
+	value: string;
+	json_schema?: Record<string, unknown>;
+	rationale?: string;
+}
+/**
+ * Post-call audio webhook payload
+ */
+export interface ElevenLabsPostCallAudioWebhook {
+	type: "post_call_audio";
+	event_timestamp: string;
+	data: {
+		conversation_id: string;
+		agent_id: string;
+		/** Base64-encoded MP3 audio */
+		audio_base64: string;
+	};
+}
+/**
+ * Call initiation failure webhook
+ */
+export interface ElevenLabsCallInitiationFailureWebhook {
+	type: "call_initiation_failure";
+	event_timestamp: string;
+	data: {
+		agent_id: string;
+		customer_phone_number: string;
+		failure_reason: string;
+		metadata?: Record<string, unknown>;
+	};
+}
+/**
+ * Union type for all ElevenLabs webhook types
+ */
+export type ElevenLabsWebhook = ElevenLabsPostCallWebhook | ElevenLabsPostCallAudioWebhook | ElevenLabsCallInitiationFailureWebhook;
+/**
+ * Base controller for handling ElevenLabs webhooks
+ *
+ * @example
+ * ```typescript
+ * class MyElevenLabsHandler extends ElevenLabsController {
+ *   async handleConversationInit(request: ConversationInitRequest): Promise<ConversationInitResponse> {
+ *     // Customize the conversation based on caller
+ *     return {
+ *       dynamic_variables: {
+ *         customerName: await lookupCustomer(request.caller_id)
+ *       }
+ *     };
+ *   }
+ *
+ *   async handlePostCall(webhook: ElevenLabsPostCallWebhook): Promise<void> {
+ *     // Save transcript to database
+ *     await saveTranscript(webhook.data);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ElevenLabsController {
+	/**
+	 * Handle conversation initialization webhook
+	 * Called when an inbound call is received - allows customizing the conversation
+	 *
+	 * @param request - The conversation init request with caller info
+	 * @returns Response with dynamic variables and/or config overrides
+	 */
+	handleConversationInit(request: ConversationInitRequest): Promise<ConversationInitResponse>;
+	/**
+	 * Handle post-call webhook with transcript and analysis
+	 *
+	 * @param webhook - The post-call webhook payload
+	 */
+	handlePostCall(webhook: ElevenLabsPostCallWebhook): Promise<void>;
+	/**
+	 * Handle post-call audio webhook with recording
+	 *
+	 * @param webhook - The audio webhook with base64-encoded MP3
+	 */
+	handlePostCallAudio(webhook: ElevenLabsPostCallAudioWebhook): Promise<void>;
+	/**
+	 * Handle call initiation failure webhook
+	 *
+	 * @param webhook - The failure webhook with error details
+	 */
+	handleCallInitiationFailure(webhook: ElevenLabsCallInitiationFailureWebhook): Promise<void>;
 	/**
-	 * Load and render an HTML template with variables
-	 * @param templatePath - Path to the HTML template file
-	 * @param variables - Object containing variables to replace in template
-	 * @returns Rendered HTML string
+	 * Express route handler for conversation init endpoint
+	 * Mount at: POST /elevenlabs/conversation-init
 	 */
-	static render(templatePath: string, variables?: Record<string, any>): string;
+	getConversationInitHandler(): (req: Request, res: Response) => Promise<void>;
 	/**
-	 * Get the absolute path to a template file relative to the current directory
-	 * @param templateName - Name of the template file (e.g., 'index.html')
-	 * @param baseDir - Base directory to search from (defaults to cwd)
-	 * @returns Absolute path to the template file
+	 * Express route handler for webhook endpoint
+	 * Mount at: POST /elevenlabs/webhook
+	 * Handles all webhook types based on the 'type' field
 	 */
-	static getTemplatePath(templateName: string, baseDir?: string): string;
+	getWebhookHandler(): (req: Request, res: Response) => Promise<void>;
 }
 /**
- * Version extractor utility for reading template versions from README.md files
+ * Try to auto-configure ElevenLabs from environment variables.
+ * Returns null if ELEVENLABS_AUTO_CONFIGURE is not "true".
+ *
+ * @param webhookUrl - Base URL for webhook callbacks (must be HTTPS in production)
+ * @param functionName - Optional name for labeling in ElevenLabs (max 100 chars)
+ * @param sinchPhoneNumber - Optional phone number override (skips auto-discovery)
  */
-export declare class VersionExtractor {
+export declare function tryAutoConfigureAsync(webhookUrl: string, functionName?: string, sinchPhoneNumber?: string): Promise<ElevenLabsAutoConfigResult | null>;
+/**
+ * @deprecated Use `tryAutoConfigureAsync` directly. This class wrapper is kept for backwards compatibility.
+ */
+export declare class ElevenLabsAutoConfigurator {
+	static tryAutoConfigureAsync: typeof tryAutoConfigureAsync;
+}
+/**
+ * ElevenLabs State Management for Sinch Functions
+ *
+ * Singleton to store auto-configuration results for subsequent calls.
+ */
+/**
+ * State for ElevenLabs configuration
+ */
+export interface ElevenLabsStateData {
+	/** Phone number ID from Sinch */
+	phoneNumberId?: string;
+	/** The phone number (E.164 format) */
+	phoneNumber?: string;
+	/** The ElevenLabs agent ID */
+	agentId?: string;
+	/** SIP address for the agent */
+	sipAddress?: string;
+	/** Whether auto-configuration has been completed */
+	isConfigured: boolean;
+	/** Timestamp of last configuration */
+	configuredAt?: Date;
+}
+declare class ElevenLabsStateManager {
+	private state;
 	/**
-	 * Extract version from README.md file in the template directory
-	 * Looks for "Template Version: X.X.X" pattern in the last few lines
-	 * @param templateDir - Path to the template directory containing README.md
-	 * @returns Version string or default fallback
+	 * Get the current state
 	 */
-	static getTemplateVersion(templateDir?: string): string;
+	getState(): Readonly<ElevenLabsStateData>;
+	/**
+	 * Check if ElevenLabs is configured
+	 */
+	isConfigured(): boolean;
+	/**
+	 * Update state with auto-configuration results
+	 */
+	setConfigured(data: Omit<ElevenLabsStateData, "isConfigured" | "configuredAt">): void;
+	/**
+	 * Clear the configuration state
+	 */
+	clear(): void;
+	/**
+	 * Get the phone number ID for making calls
+	 */
+	getPhoneNumberId(): string | undefined;
+	/**
+	 * Get the SIP address for connecting to the agent
+	 */
+	getSipAddress(): string | undefined;
+	/**
+	 * Get the configured agent ID
+	 */
+	getAgentId(): string | undefined;
 }
-export interface DefaultEndpointOptions {
-	serviceName?: string;
-	companyName?: string;
-	templateVersion?: string;
-	availableEndpoints?: Record<string, string>;
+/**
+ * Singleton instance of ElevenLabs state
+ */
+export declare const ElevenLabsState: ElevenLabsStateManager;
+/**
+ * Message inbound event from Conversation API
+ */
+export type MessageInboundEvent = Conversation.MessageInboundEvent;
+/**
+ * Contact message content
+ */
+export type ContactMessage = Conversation.ContactMessage;
+/**
+ * Media properties type (URL, thumbnail, filename)
+ */
+export type MediaProperties = Conversation.MediaProperties;
+/**
+ * Location message item type (coordinates, title, label)
+ */
+export type LocationMessageItem = Conversation.LocationMessageItem;
+/**
+ * Get the text content from an inbound message
+ */
+export declare function getText(event: MessageInboundEvent): string | undefined;
+/**
+ * Get media content from an inbound message (images, videos, files)
+ */
+export declare function getMedia(event: MessageInboundEvent): MediaProperties | undefined;
+/**
+ * Get postback data from a button/quick reply click
+ */
+export declare function getPostbackData(event: MessageInboundEvent): string | undefined;
+/**
+ * Get the contact ID of the sender
+ */
+export declare function getContactId(event: MessageInboundEvent): string | undefined;
+/**
+ * Get the conversation ID (for non-DISPATCH mode apps)
+ */
+export declare function getConversationId(event: MessageInboundEvent): string | undefined;
+/**
+ * Get the channel name (SMS, WHATSAPP, MESSENGER, etc.)
+ */
+export declare function getChannel(event: MessageInboundEvent): string | undefined;
+/**
+ * Get the channel-specific identity (phone number, PSID, etc.)
+ * This is the sender's identity (FROM)
+ */
+export declare function getIdentity(event: MessageInboundEvent): string | undefined;
+/**
+ * Get the destination number that the contact sent the message TO.
+ * For SMS/MMS, this is your Sinch number that received the message.
+ * Used automatically by reply() to set SMS_SENDER when replying.
+ */
+export declare function getTo(event: MessageInboundEvent): string | undefined;
+/**
+ * Get location data if the message contains a location
+ */
+export declare function getLocation(event: MessageInboundEvent): LocationMessageItem | undefined;
+/**
+ * Check if the message is a text message
+ */
+export declare function isTextMessage(event: MessageInboundEvent): boolean;
+/**
+ * Check if the message is a media message
+ */
+export declare function isMediaMessage(event: MessageInboundEvent): boolean;
+/**
+ * Check if the message is a button/quick reply response
+ */
+export declare function isPostback(event: MessageInboundEvent): boolean;
+/**
+ * Extension helper object with all methods bound to an event
+ */
+export declare function createMessageHelper(event: MessageInboundEvent): {
+	getText: () => string | undefined;
+	getMedia: () => Conversation.MediaProperties | undefined;
+	getPostbackData: () => string | undefined;
+	getContactId: () => string | undefined;
+	getConversationId: () => string | undefined;
+	getChannel: () => string | undefined;
+	getIdentity: () => string | undefined;
+	getTo: () => string | undefined;
+	getLocation: () => Conversation.LocationMessageItem | undefined;
+	isTextMessage: () => boolean;
+	isMediaMessage: () => boolean;
+	isPostback: () => boolean;
+};
+/**
+ * Channel type for Conversation API
+ */
+export type ConversationChannel = "SMS" | "WHATSAPP" | "MESSENGER" | "VIBER" | "RCS" | "INSTAGRAM" | "MMS" | "LINE" | "KAKAOTALK" | "TELEGRAM" | "WECHAT" | "APPLEBC" | "GOOGLEBM" | string;
+/**
+ * Simplified send message request type that works with SDK
+ */
+export interface SendMessageRequest {
+	app_id: string;
+	message: {
+		text_message?: {
+			text: string;
+		};
+	};
+	recipient: {
+		identified_by: {
+			channel_identities: Array<{
+				channel: ConversationChannel;
+				identity: string;
+			}>;
+		};
+	};
+	channel_properties?: Record<string, string>;
 }
-export interface HttpRequest {
-	method: string;
-	path: string;
-	query?: Record<string, any>;
-	headers?: Record<string, string>;
-	body?: any;
-	params?: Record<string, string>;
+/**
+ * Create a text reply to an inbound message (replies on same channel).
+ * Automatically sets SMS_SENDER channel property if sending to SMS.
+ *
+ * @param inbound - The inbound message event to reply to
+ * @param text - The reply text
+ * @param smsSender - Optional SMS sender number
+ * @returns A SendMessageRequest ready to send
+ *
+ * @example
+ * ```typescript
+ * await context.conversation.messages.send(
+ *   textReply(inbound, "Thanks for your message!", config.FROM_NUMBER)
+ * );
+ * ```
+ */
+export declare function textReply(inbound: MessageInboundEvent, text: string, smsSender?: string): SendMessageRequest;
+/**
+ * Create an SMS message to a phone number.
+ *
+ * @param appId - The Conversation API app ID
+ * @param phoneNumber - Phone number in E.164 format (e.g., +15551234567)
+ * @param text - Message text
+ * @param smsSender - SMS sender number (required for SMS channel)
+ */
+export declare function createSms(appId: string, phoneNumber: string, text: string, smsSender?: string): SendMessageRequest;
+/**
+ * Create a WhatsApp message to a phone number.
+ *
+ * @param appId - The Conversation API app ID
+ * @param phoneNumber - Phone number in E.164 format (e.g., +15551234567)
+ * @param text - Message text
+ */
+export declare function createWhatsApp(appId: string, phoneNumber: string, text: string): SendMessageRequest;
+/**
+ * Create a Facebook Messenger message.
+ *
+ * @param appId - The Conversation API app ID
+ * @param psid - The Page-Scoped ID of the user
+ * @param text - Message text
+ */
+export declare function createMessenger(appId: string, psid: string, text: string): SendMessageRequest;
+/**
+ * Create a message for any channel.
+ *
+ * @param appId - The Conversation API app ID
+ * @param channel - Channel name (SMS, WHATSAPP, MESSENGER, VIBER, etc.)
+ * @param identity - Channel-specific identity (phone number, PSID, etc.)
+ * @param text - Message text
+ * @param smsSender - SMS sender number (only used for SMS channel)
+ */
+export declare function createChannelMessage(appId: string, channel: string, identity: string, text: string, smsSender?: string): SendMessageRequest;
+/**
+ * ConversationMessage namespace for static helpers
+ */
+export declare const ConversationMessage: {
+	textReply: typeof textReply;
+	createSms: typeof createSms;
+	createWhatsApp: typeof createWhatsApp;
+	createMessenger: typeof createMessenger;
+	createChannelMessage: typeof createChannelMessage;
+};
+/**
+ * Configuration interface for the message builder
+ */
+export interface MessageBuilderConfig {
+	CONVERSATION_APP_ID?: string;
+	FROM_NUMBER?: string;
 }
-export interface HttpResponse {
-	statusCode: number;
-	headers: Record<string, string>;
-	body: any;
+/**
+ * Fluent builder for creating Conversation API messages.
+ *
+ * @example
+ * ```typescript
+ * // Simple case - use static helper
+ * await context.conversation.messages.send(
+ *   ConversationMessage.textReply(inbound, "Hello!")
+ * );
+ *
+ * // Complex case - use builder
+ * const msg = new ConversationMessageBuilder(config)
+ *   .fromInbound(inbound)
+ *   .text("Hello!")
+ *   .build();
+ * await context.conversation.messages.send(msg);
+ * ```
+ */
+export declare class ConversationMessageBuilder {
+	private config;
+	private appId?;
+	private channel?;
+	private identity?;
+	private conversationId?;
+	private messageText?;
+	/**
+	 * Create a new builder with configuration
+	 */
+	constructor(config?: MessageBuilderConfig);
+	/**
+	 * Pre-fill builder from an inbound message (for replies)
+	 */
+	fromInbound(inbound: MessageInboundEvent): this;
+	/**
+	 * Set the app ID (defaults to CONVERSATION_APP_ID from config)
+	 */
+	setAppId(appId: string): this;
+	/**
+	 * Set the recipient channel and identity
+	 *
+	 * @param channel - Channel name (SMS, WHATSAPP, MESSENGER, etc.)
+	 * @param identity - Channel-specific identity (phone number, PSID, etc.)
+	 */
+	to(channel: string, identity: string): this;
+	/**
+	 * Set the conversation ID (for non-DISPATCH mode apps)
+	 */
+	setConversationId(conversationId: string): this;
+	/**
+	 * Set a text message
+	 */
+	text(text: string): this;
+	/**
+	 * Build the SendMessageRequest.
+	 * Automatically sets SMS_SENDER from config if sending to SMS channel.
+	 *
+	 * @returns A SendMessageRequest ready to send via context.conversation.messages.send()
+	 */
+	build(): SendMessageRequest;
+}
+/**
+ * Create a new conversation message builder
+ */
+export declare function createMessageBuilder(config?: MessageBuilderConfig): ConversationMessageBuilder;
+/**
+ * Conversation API event types
+ */
+export type MessageDeliveryEvent = Conversation.MessageDeliveryReceiptEvent;
+export type EventInboundEvent = Conversation.EventInbound;
+export type ConversationStartEvent = Conversation.ConversationStartEvent;
+export type ConversationStopEvent = Conversation.ConversationStopEvent;
+/**
+ * Configuration for the conversation controller
+ */
+export interface ConversationControllerConfig {
+	CONVERSATION_APP_ID?: string;
+	FROM_NUMBER?: string;
+	VERBOSE?: string;
 }
-export declare class DefaultEndpointHandler {
+/**
+ * Base controller for handling Sinch Conversation API webhooks.
+ *
+ * Derived classes override the virtual handlers they need.
+ *
+ * @example
+ * ```typescript
+ * class MyConversationHandler extends ConversationController {
+ *   constructor(conversation: ConversationService, config: ConversationControllerConfig) {
+ *     super(conversation, config);
+ *   }
+ *
+ *   async handleMessageInbound(event: MessageInboundEvent): Promise<void> {
+ *     const text = getText(event);
+ *     if (!text) return;
+ *
+ *     // Reply using helper method
+ *     await this.conversation.messages.send({
+ *       sendMessageRequestBody: this.reply(event, "Thanks for your message!")
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ConversationController {
+	protected conversation?: ConversationService;
+	protected config: ConversationControllerConfig;
+	constructor(conversation: ConversationService | undefined, config?: ConversationControllerConfig);
+	/**
+	 * MESSAGE_INBOUND - Called when a user sends a message.
+	 * Override this to handle incoming messages from users.
+	 */
+	handleMessageInbound(event: MessageInboundEvent): Promise<void>;
+	/**
+	 * MESSAGE_DELIVERY - Called when message delivery status updates.
+	 * Override this to track delivery receipts.
+	 */
+	handleMessageDelivery(event: MessageDeliveryEvent): Promise<void>;
+	/**
+	 * EVENT_INBOUND - Called for events like composing indicators.
+	 * Override this to handle typing indicators, read receipts, etc.
+	 */
+	handleEventInbound(event: EventInboundEvent): Promise<void>;
+	/**
+	 * CONVERSATION_START - Called when a conversation begins.
+	 * Override this to handle conversation initialization.
+	 */
+	handleConversationStart(event: ConversationStartEvent): Promise<void>;
 	/**
-	 * Handle the default endpoint with content negotiation
-	 * @param context - Function context with config and cache
-	 * @param request - HTTP request object with method, path, query, headers, body, params
-	 * @param options - Configuration options for the response
-	 * @returns HTTP response object with statusCode, headers, and body
+	 * CONVERSATION_STOP - Called when a conversation ends.
+	 * Override this to handle conversation cleanup.
 	 */
-	static handle(context: FunctionContext, request: HttpRequest, options?: DefaultEndpointOptions): Promise<HttpResponse>;
+	handleConversationStop(event: ConversationStopEvent): Promise<void>;
+	/**
+	 * Gets the sender number from configuration (FROM_NUMBER).
+	 * Used for setting SMS_SENDER channel property when sending to SMS channel.
+	 */
+	get fromNumber(): string | undefined;
+	/**
+	 * Create a text reply to an inbound message.
+	 * Automatically sets SMS_SENDER from FROM_NUMBER config.
+	 */
+	reply(inbound: MessageInboundEvent, text: string): SendMessageRequest;
+	/**
+	 * Create a ConversationMessageBuilder for building messages with full control.
+	 */
+	createMessage(): ConversationMessageBuilder;
+	/**
+	 * Create a ConversationMessageBuilder pre-filled from an inbound message.
+	 */
+	createReply(inbound: MessageInboundEvent): ConversationMessageBuilder;
+	/**
+	 * Express route handler for the webhook endpoint.
+	 * Mount at: POST /conversation
+	 *
+	 * Routes to appropriate handler based on event type.
+	 * Uses manual JSON parsing as workaround for SDK issues with extra fields.
+	 */
+	getWebhookHandler(): (req: Request, res: Response) => Promise<void>;
 }
-/** @deprecated Import from '@sinch/voice' instead: `import type { Voice } from '@sinch/voice'` then use `Voice.IceRequest` */
+/**
+ * Converts an E.164 phone number to local/national format.
+ *
+ * @param phoneNumber - The phone number in E.164 format (e.g., "+15551234567")
+ * @param defaultRegion - The default region code (default: "US")
+ * @returns The phone number in national format, or the original if conversion fails
+ *
+ * @example
+ * ```typescript
+ * toLocalPhoneNumber('+15551234567');  // Returns "(555) 123-4567"
+ * toLocalPhoneNumber('+442071234567'); // Returns "020 7123 4567"
+ * ```
+ */
+export declare function toLocalPhoneNumber(phoneNumber: string, defaultRegion?: string): string;
+/**
+ * Formats a phone number for display (adds dashes/spaces for readability)
+ *
+ * @param phoneNumber - Phone number in any format
+ * @returns Formatted phone number
+ */
+export declare function formatPhoneNumber(phoneNumber: string): string;
+/**
+ * Helper methods for creating common error responses
+ */
+export declare const VoiceErrorHelper: {
+	/**
+	 * Create a standard error response that plays a message and hangs up
+	 *
+	 * @param message - Error message to speak
+	 * @param locale - Language locale (default: "en-US")
+	 * @returns SVAML response object
+	 */
+	createErrorResponse(message: string, locale?: string): ReturnType<IceSvamlBuilder["build"]>;
+	/**
+	 * Create a service unavailable response
+	 *
+	 * @param locale - Language locale (default: "en-US")
+	 * @returns SVAML response object
+	 */
+	serviceUnavailable(locale?: string): ReturnType<IceSvamlBuilder["build"]>;
+	/**
+	 * Create an invalid input response for PIE handlers
+	 *
+	 * @param locale - Language locale (default: "en-US")
+	 * @returns SVAML response object
+	 */
+	invalidInput(locale?: string): ReturnType<PieSvamlBuilder["build"]>;
+	/**
+	 * Create a timeout response for PIE handlers
+	 *
+	 * @param locale - Language locale (default: "en-US")
+	 * @returns SVAML response object
+	 */
+	timeout(locale?: string): ReturnType<PieSvamlBuilder["build"]>;
+	/**
+	 * Create a goodbye response that thanks the caller and hangs up
+	 *
+	 * @param locale - Language locale (default: "en-US")
+	 * @returns SVAML response object
+	 */
+	goodbye(locale?: string): ReturnType<IceSvamlBuilder["build"]>;
+};
+/**
+ * Formats duration in seconds to human-readable format
+ *
+ * @param seconds - Duration in seconds
+ * @returns Formatted duration string (e.g., "2m 30s")
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Extracts the caller's phone number from CLI (Caller ID)
+ *
+ * @param cli - Caller ID string
+ * @returns Normalized phone number
+ */
+export declare function extractCallerNumber(cli: string | undefined): string | undefined;
+/** @deprecated Import from '@sinch/voice' instead: `import type { Voice } from '@sinch/voice'` then use `Voice.IceRequest` @internal */
 export type IceCallbackData = Voice.IceRequest;
-/** @deprecated Import from '@sinch/voice' instead */
+/** @deprecated Import from '@sinch/voice' instead @internal */
 export type AceCallbackData = Voice.AceRequest;
-/** @deprecated Import from '@sinch/voice' instead */
+/** @deprecated Import from '@sinch/voice' instead @internal */
 export type PieCallbackData = Voice.PieRequest;
-/** @deprecated Import from '@sinch/voice' instead */
+/** @deprecated Import from '@sinch/voice' instead @internal */
 export type DiceCallbackData = Voice.DiceRequest;
-/** @deprecated Import from '@sinch/voice' instead */
+/** @deprecated Import from '@sinch/voice' instead @internal */
 export type NotifyCallbackData = Voice.NotifyRequest;
-/** @deprecated Import from '@sinch/voice' instead */
+/** @deprecated Import from '@sinch/voice' instead @internal */
 export type MenuResult = Voice.MenuResult;
-/** @deprecated Import from '@sinch/voice' instead */
+/** @deprecated Import from '@sinch/voice' instead @internal */
 export type AmdResult = Voice.AnsweringMachineDetection;
-/** @deprecated Import from '@sinch/voice' instead */
+/** @deprecated Import from '@sinch/voice' instead @internal */
 export type DisconnectReason = Voice.DiceReasonEnum;
-/** @deprecated Import from '@sinch/voice' instead */
+/** @deprecated Import from '@sinch/voice' instead @internal */
 export type CallResult = Voice.ResultEnum;
 /**
  * Union type for all voice callback data
@@ -1320,6 +2260,8 @@ export type VoiceCallbackData = Voice.IceRequest | Voice.AceRequest | Voice.PieR
  *
  * Implements IFunctionCache using an in-memory Map with TTL support.
  * Data is lost when the process restarts.
+ *
+ * @internal Dev-only implementation — access cache via `context.cache`
  */
 export declare class LocalCache implements IFunctionCache {
 	private cache;
@@ -1347,6 +2289,7 @@ export declare class LocalCache implements IFunctionCache {
  *
  * @param _projectId - Project ID (unused in local development)
  * @param _functionName - Function name (unused in local development)
+ * @internal Dev-only factory — access cache via `context.cache`
  */
 export declare function createCacheClient(_projectId?: string, _functionName?: string): IFunctionCache;
 /**
@@ -1361,7 +2304,10 @@ export declare function createCacheClient(_projectId?: string, _functionName?: s
  * - ElevenLabs auto-configuration (when enabled)
  * - Stale webhook cleanup on connect
  * - Webhook cleanup on disconnect
+ *
+ * @internal Dev-only — used by `sinch functions dev`, not by user code
  */
+/** @internal */
 export declare class TunnelClient {
 	private ws;
 	private tunnelUrl;
@@ -1398,6 +2344,7 @@ export declare class TunnelClient {
 	getTunnelUrl(): string | null;
 	getIsConnected(): boolean;
 }
+/** @internal */
 export declare function getTunnelClient(localPort?: number): TunnelClient;
 /**
  * Secrets Loader for Local Development
@@ -1408,7 +2355,10 @@ export declare function getTunnelClient(localPort?: number): TunnelClient;
  *
  * Security: Only loads secrets that are declared in .env file (empty values)
  * In production, secrets are injected by the platform, so this is development-only.
+ *
+ * @internal Dev-only — used by the runtime dev server, not by user code
  */
+/** @internal */
 export declare class SecretsLoader {
 	private SERVICE_NAME;
 	private username;