experimental-ash 0.13.0 → 0.14.0

package/dist/src/public/channels/twilio/index.d.ts

@@ -0,0 +1,5 @@
+export { twilioChannel, type TwilioAllowFrom, type TwilioChannel, type TwilioChannelConfig, type TwilioChannelCredentials, type TwilioChannelEvents, type TwilioChannelState, type TwilioContext, type TwilioEventContext, type TwilioHandle, type TwilioInboundResult, type TwilioInboundResultOrPromise, type TwilioMessagingConfig, type TwilioReceiveArgs, type TwilioSendMessageOptions, type TwilioVoiceConfig, type TwilioVoiceResult, type TwilioVoiceResultOrPromise, } from "#public/channels/twilio/twilioChannel.js";
+export { callTwilioApi, resolveTwilioAccountSid, sendTwilioMessage, updateTwilioCall, type TwilioAccountSid, type TwilioApiOptions, type TwilioApiResponse, type TwilioCredentials, type TwilioFetch, type TwilioSendMessageInput, type TwilioUpdateCallInput, } from "#public/channels/twilio/api.js";
+export type { TwilioInboundContext, TwilioTextMessage, TwilioVoiceCall, TwilioVoiceTranscription, } from "#public/channels/twilio/inbound.js";
+export { emptyTwilioResponse, escapeXml, gatherSpeechTwilioResponse, sayTwilioResponse, twimlResponse, type TwilioGatherTwimlOptions, } from "#public/channels/twilio/twiml.js";
+export { buildTwilioSignatureBase, resolveTwilioAuthToken, signTwilioRequest, verifyTwilioRequest, type TwilioAuthToken, type TwilioVerifiedRequest, type TwilioVerifyOptions, type TwilioWebhookUrl, } from "#public/channels/twilio/verify.js";

package/dist/src/public/channels/twilio/index.js

@@ -0,0 +1,4 @@
+export { twilioChannel, } from "#public/channels/twilio/twilioChannel.js";
+export { callTwilioApi, resolveTwilioAccountSid, sendTwilioMessage, updateTwilioCall, } from "#public/channels/twilio/api.js";
+export { emptyTwilioResponse, escapeXml, gatherSpeechTwilioResponse, sayTwilioResponse, twimlResponse, } from "#public/channels/twilio/twiml.js";
+export { buildTwilioSignatureBase, resolveTwilioAuthToken, signTwilioRequest, verifyTwilioRequest, } from "#public/channels/twilio/verify.js";

package/dist/src/public/channels/twilio/twilioChannel.d.ts

@@ -0,0 +1,179 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import { type TwilioApiOptions, type TwilioApiResponse, type TwilioCredentials } from "#public/channels/twilio/api.js";
+import { type TwilioTextMessage, type TwilioVoiceCall, type TwilioVoiceTranscription } from "#public/channels/twilio/inbound.js";
+import { type TwilioAuthToken, type TwilioWebhookUrl } from "#public/channels/twilio/verify.js";
+import { type Channel } from "#public/definitions/defineChannel.js";
+type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessageStreamEvent, {
+    type: T;
+}> extends {
+    data: infer D;
+} ? D : undefined;
+/** Pre-dispatch Twilio context passed to inbound text and voice hooks. */
+export interface TwilioContext {
+    readonly twilio: TwilioHandle;
+}
+/** Event-handler Twilio context, including mutable per-phone channel state. */
+export interface TwilioEventContext extends TwilioContext {
+    state: TwilioChannelState;
+}
+/** JSON-serializable state for the phone-number conversation. */
+export interface TwilioChannelState {
+    /** Caller / sender phone number. */
+    from: string | null;
+    /** Twilio number or sender that received the latest session-starting webhook. */
+    to: string | null;
+    /** Most recent inbound SMS SID when this session was started by text. */
+    lastMessageSid?: string | null;
+    /** Most recent inbound Call SID when this session was started by voice. */
+    lastCallSid?: string | null;
+}
+/** Twilio channel credentials. `authToken` also verifies inbound webhook signatures. */
+export interface TwilioChannelCredentials extends TwilioCredentials {
+    readonly authToken?: TwilioAuthToken;
+}
+/** Arguments accepted by `receive(twilio, args)` for proactive phone-number sessions. */
+export interface TwilioReceiveArgs {
+    readonly phoneNumber: string;
+    /** Twilio sender included in the phone-pair continuation token. */
+    readonly from?: string;
+}
+/** Result of an inbound Twilio text or transcription hook. Return `null` to drop the webhook. */
+export type TwilioInboundResult = {
+    auth: SessionAuthContext | null;
+} | null;
+/** Sync or async {@link TwilioInboundResult}. */
+export type TwilioInboundResultOrPromise = TwilioInboundResult | Promise<TwilioInboundResult>;
+/** Phone-number allow list for inbound Twilio webhook triggers. `"*"` allows every sender. */
+export type TwilioAllowFrom = string | readonly string[] | (() => string | readonly string[] | Promise<string | readonly string[]>);
+/**
+ * Result of an inbound Twilio voice hook. Return `null` to reject the call.
+ * Any result other than `null` accepts the call and can override the answering TwiML.
+ */
+export interface TwilioVoiceResult {
+    /** Prompt spoken before Twilio starts speech recognition. */
+    readonly prompt?: string;
+    /** BCP 47 language used for speech recognition and the nested `<Say>` prompt. */
+    readonly language?: string;
+    /** Twilio `<Say voice>` used for the prompt, e.g. `Polly.Joanna-Neural`. */
+    readonly voice?: string;
+    /** Twilio `<Gather speechModel>` used for speech recognition. */
+    readonly speechModel?: string;
+    /** Twilio `<Gather timeout>` in seconds. */
+    readonly timeoutSeconds?: number;
+    /** Twilio `<Gather speechTimeout>`, such as `"auto"` or a second count string. */
+    readonly speechTimeout?: string;
+    /** Twilio `<Gather hints>` for expected words or phrases. */
+    readonly hints?: string | readonly string[];
+    /** Twilio `<Gather profanityFilter>` toggle. */
+    readonly profanityFilter?: boolean;
+}
+/** Sync or async {@link TwilioVoiceResult}. */
+export type TwilioVoiceResultOrPromise = TwilioVoiceResult | null | undefined | Promise<TwilioVoiceResult | null | undefined>;
+type TwilioEventHandler<T extends HandleMessageStreamEvent["type"]> = (data: EventData<T>, ctx: TwilioEventContext) => void | Promise<void>;
+/** Event handlers supported by `twilioChannel({ events })`. */
+export interface TwilioChannelEvents {
+    readonly "turn.started"?: TwilioEventHandler<"turn.started">;
+    readonly "actions.requested"?: TwilioEventHandler<"actions.requested">;
+    readonly "action.result"?: TwilioEventHandler<"action.result">;
+    readonly "message.completed"?: TwilioEventHandler<"message.completed">;
+    readonly "message.appended"?: TwilioEventHandler<"message.appended">;
+    readonly "input.requested"?: TwilioEventHandler<"input.requested">;
+    readonly "turn.failed"?: TwilioEventHandler<"turn.failed">;
+    readonly "turn.completed"?: TwilioEventHandler<"turn.completed">;
+    readonly "session.failed"?: TwilioEventHandler<"session.failed">;
+    readonly "session.completed"?: TwilioEventHandler<"session.completed">;
+    readonly "session.waiting"?: TwilioEventHandler<"session.waiting">;
+    readonly "connection.authorization_required"?: TwilioEventHandler<"connection.authorization_required">;
+    readonly "connection.authorization_pending"?: TwilioEventHandler<"connection.authorization_pending">;
+    readonly "connection.authorization_completed"?: TwilioEventHandler<"connection.authorization_completed">;
+}
+/** SMS/Messaging defaults for Twilio outbound replies. */
+export interface TwilioMessagingConfig {
+    /** Sender phone number. Defaults to the inbound `To` number when available. */
+    readonly from?: string;
+    /** Messaging Service SID. Used instead of `from` when supplied. */
+    readonly messagingServiceSid?: string;
+    /** Optional Twilio status callback URL for outbound messages. */
+    readonly statusCallbackUrl?: string;
+}
+/** Voice webhook defaults for accepting calls and gathering speech. */
+export interface TwilioVoiceConfig {
+    /** Prompt spoken when a caller reaches the voice route. */
+    readonly prompt?: string;
+    /** Twilio `<Say voice>` used for the prompt, e.g. `Polly.Joanna-Neural`. */
+    readonly voice?: string;
+    /** Spoken acknowledgement after a transcription webhook is accepted. */
+    readonly acknowledgement?: string;
+    /** BCP 47 language used for speech recognition and the nested `<Say>` prompt. */
+    readonly language?: string;
+    /** Twilio `<Gather speechModel>` used for speech recognition. */
+    readonly speechModel?: string;
+    /** Twilio `<Gather timeout>` in seconds. */
+    readonly timeoutSeconds?: number;
+    /** Twilio `<Gather speechTimeout>`, such as `"auto"` or a second count string. */
+    readonly speechTimeout?: string;
+    /** Twilio `<Gather hints>` for expected words or phrases. */
+    readonly hints?: string | readonly string[];
+    /** Twilio `<Gather profanityFilter>` toggle. */
+    readonly profanityFilter?: boolean;
+}
+/** Configuration for {@link twilioChannel}. */
+export interface TwilioChannelConfig {
+    readonly credentials?: TwilioChannelCredentials;
+    /**
+     * Base route for Twilio webhooks. Defaults to `/ash/v1/twilio` and
+     * mounts `/messages`, `/voice`, and `/voice/transcription` below it.
+     */
+    readonly route?: string;
+    /**
+     * Public URL Twilio used for signing. Set this when proxies or local
+     * tunnels make `request.url` differ from the configured webhook URL.
+     */
+    readonly webhookUrl?: TwilioWebhookUrl;
+    /** Public base URL used to render absolute voice `<Gather action>` URLs. */
+    readonly publicBaseUrl?: string | ((request: Request) => string | Promise<string>);
+    /**
+     * Exact caller/sender numbers allowed to reach inbound hooks, or `"*"` to
+     * allow every verified Twilio sender. Resolvers run on each inbound webhook.
+     */
+    readonly allowFrom: TwilioAllowFrom;
+    readonly messaging?: TwilioMessagingConfig;
+    readonly voice?: TwilioVoiceConfig;
+    readonly api?: Omit<TwilioApiOptions, "credentials">;
+    /** Inbound text hook. Defaults to phone-number auth and dispatch. */
+    onText?(ctx: TwilioContext, message: TwilioTextMessage): TwilioInboundResultOrPromise;
+    /** Inbound voice hook. Return `null` to reject the call before gathering speech. */
+    onVoice?(ctx: TwilioContext, call: TwilioVoiceCall): TwilioVoiceResultOrPromise;
+    /** Inbound voice transcription hook. Defaults to phone-number auth and dispatch. */
+    onVoiceTranscription?(ctx: TwilioContext, transcription: TwilioVoiceTranscription): TwilioInboundResultOrPromise;
+    readonly events?: TwilioChannelEvents;
+}
+/** Low-level Twilio handle exposed to hooks and event handlers. */
+export interface TwilioHandle {
+    /** Caller / sender phone number bound to this conversation. */
+    readonly from: string;
+    /** Twilio receiver / sender number for replies, when known. */
+    readonly to: string | undefined;
+    /** Most recent call SID, when the session started from a voice transcription. */
+    readonly callSid: string | undefined;
+    /** Raw Twilio REST API escape hatch. */
+    request(path: string, body: Readonly<Record<string, string | number | boolean | undefined | null>>): Promise<TwilioApiResponse>;
+    /** Sends a text message to this conversation's phone number by default. */
+    sendMessage(message: string, options?: TwilioSendMessageOptions): Promise<TwilioApiResponse>;
+    /** Updates a live call with replacement TwiML. */
+    updateCall(callSid: string, twiml: string): Promise<TwilioApiResponse>;
+}
+/** Per-call overrides for {@link TwilioHandle.sendMessage}. */
+export interface TwilioSendMessageOptions {
+    readonly to?: string;
+    readonly from?: string;
+    readonly messagingServiceSid?: string;
+    readonly statusCallbackUrl?: string;
+}
+/** Concrete return type of {@link twilioChannel}. */
+export interface TwilioChannel extends Channel<TwilioChannelState> {
+}
+/** Twilio channel factory for SMS and speech-transcribed inbound calls. */
+export declare function twilioChannel(config: TwilioChannelConfig): TwilioChannel;
+export {};

package/dist/src/public/channels/twilio/twilioChannel.js

@@ -0,0 +1,319 @@
+import { createLogger } from "#internal/logging.js";
+import { callTwilioApi, sendTwilioMessage, updateTwilioCall, } from "#public/channels/twilio/api.js";
+import { defaultEvents, defaultOnText, defaultOnVoice, defaultOnVoiceTranscription, } from "#public/channels/twilio/defaults.js";
+import { parseTwilioTextMessage, parseTwilioVoiceCall, parseTwilioVoiceTranscription, prependTwilioContext, } from "#public/channels/twilio/inbound.js";
+import { emptyTwilioResponse, gatherSpeechTwilioResponse, sayTwilioResponse, } from "#public/channels/twilio/twiml.js";
+import { verifyTwilioRequest, } from "#public/channels/twilio/verify.js";
+import { defineChannel, POST, } from "#public/definitions/defineChannel.js";
+const log = createLogger("twilio.channel");
+/** Twilio channel factory for SMS and speech-transcribed inbound calls. */
+export function twilioChannel(config) {
+    assertAllowFromConfigured(config);
+    const routes = buildRoutes(config.route ?? "/ash/v1/twilio");
+    const onText = config.onText ?? defaultOnText;
+    const onVoice = config.onVoice ?? defaultOnVoice;
+    const onVoiceTranscription = config.onVoiceTranscription ?? defaultOnVoiceTranscription;
+    const mergedEvents = { ...defaultEvents, ...config.events };
+    return defineChannel({
+        kindHint: "twilio",
+        state: {
+            from: null,
+            to: null,
+            lastCallSid: null,
+            lastMessageSid: null,
+        },
+        context(state) {
+            return rebuildTwilioContext(state, config);
+        },
+        routes: [
+            POST(routes.messages, async (req, { send, waitUntil }) => {
+                const verified = await verifyInbound(req, config);
+                if (verified === null)
+                    return new Response("unauthorized", { status: 401 });
+                const message = parseTwilioTextMessage(verified.params);
+                if (!message)
+                    return emptyTwilioResponse();
+                if (!(await isAllowed(message.from, config.allowFrom)))
+                    return new Response("forbidden", { status: 403 });
+                waitUntil(dispatchText({ config, message, onText, send }));
+                return emptyTwilioResponse();
+            }),
+            POST(routes.voice, async (req) => {
+                const verified = await verifyInbound(req, config);
+                if (verified === null)
+                    return new Response("unauthorized", { status: 401 });
+                const call = parseTwilioVoiceCall(verified.params);
+                if (!call)
+                    return sayTwilioResponse("Missing caller information.");
+                if (!(await isAllowed(call.from, config.allowFrom)))
+                    return new Response("forbidden", { status: 403 });
+                const voiceResult = await acceptVoiceCall({
+                    call,
+                    config,
+                    onVoice,
+                });
+                if (voiceResult === null)
+                    return new Response("forbidden", { status: 403 });
+                const voiceOptions = voiceResult ?? {};
+                return gatherSpeechTwilioResponse({
+                    actionUrl: await buildActionUrl(req, config, routes.transcription),
+                    hints: voiceOptions.hints ?? config.voice?.hints,
+                    language: voiceOptions.language ?? config.voice?.language,
+                    profanityFilter: voiceOptions.profanityFilter ?? config.voice?.profanityFilter,
+                    prompt: voiceOptions.prompt ??
+                        config.voice?.prompt ??
+                        "Please say your message after the tone.",
+                    speechModel: voiceOptions.speechModel ?? config.voice?.speechModel,
+                    speechTimeout: voiceOptions.speechTimeout ?? config.voice?.speechTimeout ?? "auto",
+                    timeoutSeconds: voiceOptions.timeoutSeconds ?? config.voice?.timeoutSeconds,
+                    voice: voiceOptions.voice ?? config.voice?.voice,
+                });
+            }),
+            POST(routes.transcription, async (req, { send, waitUntil }) => {
+                const verified = await verifyInbound(req, config);
+                if (verified === null)
+                    return new Response("unauthorized", { status: 401 });
+                const transcription = parseTwilioVoiceTranscription(verified.params);
+                if (!transcription) {
+                    return gatherSpeechTwilioResponse({
+                        actionUrl: await buildActionUrl(req, config, routes.transcription),
+                        language: config.voice?.language,
+                        prompt: config.voice?.prompt ?? "Please say your message after the tone.",
+                        speechTimeout: config.voice?.speechTimeout ?? "auto",
+                        timeoutSeconds: config.voice?.timeoutSeconds,
+                    });
+                }
+                if (!(await isAllowed(transcription.from, config.allowFrom))) {
+                    return new Response("forbidden", { status: 403 });
+                }
+                waitUntil(dispatchVoiceTranscription({ config, onVoiceTranscription, send, transcription }));
+                return sayTwilioResponse(config.voice?.acknowledgement ?? "Thanks. I'll follow up by text.");
+            }),
+        ],
+        async receive(input, { send }) {
+            const phoneNumber = readString(input.args.phoneNumber);
+            if (!phoneNumber) {
+                throw new Error("twilioChannel().receive requires args.phoneNumber.");
+            }
+            const from = readString(input.args.from) ?? config.messaging?.from ?? null;
+            const continuationToken = encodeTwilioContinuationToken(phoneNumber, from);
+            return send(input.message, {
+                auth: input.auth,
+                continuationToken,
+                state: {
+                    from: phoneNumber,
+                    lastCallSid: null,
+                    lastMessageSid: null,
+                    to: from,
+                },
+            });
+        },
+        events: mergedEvents,
+    });
+}
+function rebuildTwilioContext(state, config) {
+    return {
+        state,
+        twilio: buildTwilioHandle({
+            callSid: state.lastCallSid ?? undefined,
+            config,
+            from: state.from ?? "",
+            to: state.to ?? undefined,
+        }),
+    };
+}
+function buildTwilioHandle(input) {
+    const api = input.config.api;
+    const credentials = input.config.credentials;
+    const defaultFrom = input.config.messaging?.from ?? input.to;
+    const defaultMessagingServiceSid = input.config.messaging?.messagingServiceSid;
+    const defaultStatusCallbackUrl = input.config.messaging?.statusCallbackUrl;
+    return {
+        callSid: input.callSid,
+        from: input.from,
+        to: input.to,
+        request(path, body) {
+            return callTwilioApi({
+                apiBaseUrl: api?.apiBaseUrl,
+                body,
+                credentials,
+                fetch: api?.fetch,
+                path,
+            });
+        },
+        sendMessage(message, options) {
+            return sendTwilioMessage({
+                apiBaseUrl: api?.apiBaseUrl,
+                body: message,
+                credentials,
+                fetch: api?.fetch,
+                from: options?.from ?? defaultFrom,
+                messagingServiceSid: options?.messagingServiceSid ?? defaultMessagingServiceSid,
+                statusCallbackUrl: options?.statusCallbackUrl ?? defaultStatusCallbackUrl,
+                to: options?.to ?? input.from,
+            });
+        },
+        updateCall(callSid, twiml) {
+            return updateTwilioCall({
+                apiBaseUrl: api?.apiBaseUrl,
+                callSid,
+                credentials,
+                fetch: api?.fetch,
+                twiml,
+            });
+        },
+    };
+}
+function buildRoutes(baseRoute) {
+    const base = baseRoute.endsWith("/") ? baseRoute.slice(0, -1) : baseRoute;
+    return {
+        messages: `${base}/messages`,
+        transcription: `${base}/voice/transcription`,
+        voice: `${base}/voice`,
+    };
+}
+function assertAllowFromConfigured(config) {
+    if (config?.allowFrom === undefined) {
+        throw new Error('twilioChannel requires allowFrom. Use allowFrom: "*" to allow all numbers.');
+    }
+}
+async function verifyInbound(req, config) {
+    try {
+        return await verifyTwilioRequest(req, {
+            authToken: config.credentials?.authToken,
+            webhookUrl: config.webhookUrl,
+        });
+    }
+    catch (error) {
+        log.warn("twilio inbound verification failed", { error });
+        return null;
+    }
+}
+async function dispatchText(input) {
+    const { message } = input;
+    const twilio = {
+        twilio: buildTwilioHandle({
+            callSid: undefined,
+            config: input.config,
+            from: message.from,
+            to: message.to,
+        }),
+    };
+    let result;
+    try {
+        result = await input.onText(twilio, message);
+    }
+    catch (error) {
+        log.error("text handler failed", { error });
+        return;
+    }
+    if (result === null || result === undefined)
+        return;
+    const turnMessage = prependTwilioContext(message.body, {
+        channel: "text",
+        from: message.from,
+        messageSid: message.messageSid,
+        to: message.to,
+    });
+    try {
+        await input.send(turnMessage, {
+            auth: result.auth,
+            continuationToken: encodeTwilioContinuationToken(message.from, message.to),
+            state: {
+                from: message.from,
+                lastCallSid: null,
+                lastMessageSid: message.messageSid ?? null,
+                to: message.to ?? null,
+            },
+        });
+    }
+    catch (error) {
+        log.error("text delivery failed", { error });
+    }
+}
+async function acceptVoiceCall(input) {
+    const { call } = input;
+    const twilio = {
+        twilio: buildTwilioHandle({
+            callSid: call.callSid,
+            config: input.config,
+            from: call.from,
+            to: call.to,
+        }),
+    };
+    try {
+        return await input.onVoice(twilio, call);
+    }
+    catch (error) {
+        log.error("voice handler failed", { error });
+        return null;
+    }
+}
+async function dispatchVoiceTranscription(input) {
+    const { transcription } = input;
+    const twilio = {
+        twilio: buildTwilioHandle({
+            callSid: transcription.callSid,
+            config: input.config,
+            from: transcription.from,
+            to: transcription.to,
+        }),
+    };
+    let result;
+    try {
+        result = await input.onVoiceTranscription(twilio, transcription);
+    }
+    catch (error) {
+        log.error("voice transcription handler failed", { error });
+        return;
+    }
+    if (result === null || result === undefined)
+        return;
+    const turnMessage = prependTwilioContext(transcription.text, {
+        callSid: transcription.callSid,
+        channel: "voice",
+        from: transcription.from,
+        to: transcription.to,
+    });
+    try {
+        await input.send(turnMessage, {
+            auth: result.auth,
+            continuationToken: encodeTwilioContinuationToken(transcription.from, transcription.to),
+            state: {
+                from: transcription.from,
+                lastCallSid: transcription.callSid ?? null,
+                lastMessageSid: null,
+                to: transcription.to ?? null,
+            },
+        });
+    }
+    catch (error) {
+        log.error("voice transcription delivery failed", { error });
+    }
+}
+async function isAllowed(from, allowFrom) {
+    const resolved = typeof allowFrom === "function" ? await allowFrom() : allowFrom;
+    if (resolved === "*")
+        return true;
+    return typeof resolved === "string" ? resolved === from : resolved.includes(from);
+}
+function encodeTwilioContinuationToken(from, to) {
+    return `${from}:${to ?? ""}`;
+}
+async function buildActionUrl(request, config, route) {
+    const base = typeof config.publicBaseUrl === "function"
+        ? await config.publicBaseUrl(request)
+        : config.publicBaseUrl;
+    if (base)
+        return new URL(route, ensureTrailingSlash(base)).toString();
+    const url = new URL(request.url);
+    url.pathname = route;
+    url.search = "";
+    return url.toString();
+}
+function ensureTrailingSlash(value) {
+    return value.endsWith("/") ? value : `${value}/`;
+}
+function readString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/dist/src/public/channels/twilio/twiml.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tiny TwiML builders for Twilio webhook responses.
+ *
+ * The channel keeps TwiML generation local so callers do not need the
+ * Twilio SDK just to acknowledge a webhook or gather speech.
+ */
+/** Options for rendering a voice `<Gather input="speech">` response. */
+export interface TwilioGatherTwimlOptions {
+    /** Absolute callback URL that receives the speech result. */
+    readonly actionUrl: string;
+    /** Prompt spoken before Twilio starts speech recognition. */
+    readonly prompt: string;
+    /** Twilio `<Say voice>` used for the prompt, e.g. `Polly.Joanna-Neural`. */
+    readonly voice?: string;
+    /** BCP 47 language used for speech recognition and the nested `<Say>` prompt. */
+    readonly language?: string;
+    /** Twilio `<Gather speechModel>` used for speech recognition. */
+    readonly speechModel?: string;
+    /** Twilio `<Gather timeout>` in seconds. */
+    readonly timeoutSeconds?: number;
+    /** Twilio `<Gather speechTimeout>`, such as `"auto"` or a second count string. */
+    readonly speechTimeout?: string;
+    /** Twilio `<Gather hints>` for expected words or phrases. */
+    readonly hints?: string | readonly string[];
+    /** Twilio `<Gather profanityFilter>` toggle. */
+    readonly profanityFilter?: boolean;
+}
+/** Returns an empty TwiML response, useful for acknowledging inbound SMS without replying. */
+export declare function emptyTwilioResponse(): Response;
+/** Returns a TwiML response that speaks `message` and then ends the call. */
+export declare function sayTwilioResponse(message: string): Response;
+/** Returns a TwiML response that asks the caller to speak and posts the transcript to `actionUrl`. */
+export declare function gatherSpeechTwilioResponse(options: TwilioGatherTwimlOptions): Response;
+/** Wraps a TwiML string in a Twilio-compatible XML response. */
+export declare function twimlResponse(twiml: string): Response;
+/** Escapes text for XML element content or attribute values. */
+export declare function escapeXml(value: string): string;

package/dist/src/public/channels/twilio/twiml.js

@@ -0,0 +1,58 @@
+/**
+ * Tiny TwiML builders for Twilio webhook responses.
+ *
+ * The channel keeps TwiML generation local so callers do not need the
+ * Twilio SDK just to acknowledge a webhook or gather speech.
+ */
+/** Returns an empty TwiML response, useful for acknowledging inbound SMS without replying. */
+export function emptyTwilioResponse() {
+    return twimlResponse("<Response></Response>");
+}
+/** Returns a TwiML response that speaks `message` and then ends the call. */
+export function sayTwilioResponse(message) {
+    return twimlResponse(`<Response><Say>${escapeXml(message)}</Say></Response>`);
+}
+/** Returns a TwiML response that asks the caller to speak and posts the transcript to `actionUrl`. */
+export function gatherSpeechTwilioResponse(options) {
+    const hints = typeof options.hints === "string" ? options.hints : options.hints?.join(",");
+    const attributes = [
+        `input="speech"`,
+        `action="${escapeXml(options.actionUrl)}"`,
+        `method="POST"`,
+        `actionOnEmptyResult="true"`,
+        options.language ? `language="${escapeXml(options.language)}"` : undefined,
+        options.speechModel ? `speechModel="${escapeXml(options.speechModel)}"` : undefined,
+        options.timeoutSeconds !== undefined ? `timeout="${options.timeoutSeconds}"` : undefined,
+        options.speechTimeout ? `speechTimeout="${escapeXml(options.speechTimeout)}"` : undefined,
+        hints ? `hints="${escapeXml(hints)}"` : undefined,
+        options.profanityFilter !== undefined
+            ? `profanityFilter="${options.profanityFilter ? "true" : "false"}"`
+            : undefined,
+    ]
+        .filter((value) => value !== undefined)
+        .join(" ");
+    const sayAttributes = [
+        options.voice ? `voice="${escapeXml(options.voice)}"` : undefined,
+        options.language ? `language="${escapeXml(options.language)}"` : undefined,
+    ]
+        .filter((value) => value !== undefined)
+        .join(" ");
+    const sayOpen = sayAttributes ? `<Say ${sayAttributes}>` : "<Say>";
+    return twimlResponse(`<Response><Gather ${attributes}>${sayOpen}${escapeXml(options.prompt)}</Say></Gather></Response>`);
+}
+/** Wraps a TwiML string in a Twilio-compatible XML response. */
+export function twimlResponse(twiml) {
+    return new Response(twiml, {
+        status: 200,
+        headers: { "content-type": "text/xml;charset=UTF-8" },
+    });
+}
+/** Escapes text for XML element content or attribute values. */
+export function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}

package/dist/src/public/channels/twilio/verify.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Twilio inbound-webhook verification.
+ *
+ * Twilio signs webhook requests with `X-Twilio-Signature`. For form
+ * posts, the signed payload is the exact public URL Twilio called plus
+ * every POST parameter sorted by name and appended as `name + value`.
+ */
+/** Auth token, materialized either directly or from an async secret provider. */
+export type TwilioAuthToken = string | (() => string | Promise<string>);
+/** Public URL resolver used when the runtime request URL differs from Twilio's configured URL. */
+export type TwilioWebhookUrl = string | ((request: Request) => string | Promise<string>);
+/**
+ * Parsed and verified Twilio webhook body.
+ *
+ * `params` contains every form parameter Twilio sent. Signature
+ * validation happens before the channel reads any business fields.
+ */
+export interface TwilioVerifiedRequest {
+    readonly body: string;
+    readonly params: URLSearchParams;
+}
+/** Options for {@link verifyTwilioRequest}. */
+export interface TwilioVerifyOptions {
+    readonly authToken: TwilioAuthToken | undefined;
+    readonly webhookUrl?: TwilioWebhookUrl;
+}
+/** Resolves a Twilio auth token, falling back to `TWILIO_AUTH_TOKEN`. */
+export declare function resolveTwilioAuthToken(authToken?: TwilioAuthToken): Promise<string>;
+/**
+ * Verifies an inbound Twilio webhook and returns the raw body plus form params.
+ *
+ * Throws when the auth token is missing, the signature header is missing,
+ * or the computed signature does not match `X-Twilio-Signature`.
+ */
+export declare function verifyTwilioRequest(request: Request, options: TwilioVerifyOptions): Promise<TwilioVerifiedRequest>;
+/** Computes Twilio's HMAC-SHA1 request signature. */
+export declare function signTwilioRequest(input: {
+    readonly authToken: string;
+    readonly url: string;
+    readonly params: URLSearchParams;
+}): string;
+/** Builds the string Twilio signs for a form POST webhook. */
+export declare function buildTwilioSignatureBase(url: string, params: URLSearchParams): string;