@absolutejs/voice 0.0.22-beta.70 → 0.0.22-beta.71

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { createVoiceToolIdempotencyKey, createVoiceToolRuntime } from './toolRun
 export { createVoiceToolContract, createVoiceToolContractHTMLHandler, createVoiceToolContractJSONHandler, createVoiceToolContractRoutes, createVoiceToolRuntimeContractDefaults, renderVoiceToolContractHTML, runVoiceToolContractSuite, runVoiceToolContract } from './toolContract';
 export { createVoiceTurnQualityHTMLHandler, createVoiceTurnQualityJSONHandler, createVoiceTurnQualityRoutes, renderVoiceTurnQualityHTML, summarizeVoiceTurnQuality } from './turnQuality';
 export { createVoiceOutcomeContractHTMLHandler, createVoiceOutcomeContractJSONHandler, createVoiceOutcomeContractRoutes, renderVoiceOutcomeContractHTML, runVoiceOutcomeContractSuite } from './outcomeContract';
-export { applyVoiceTelephonyOutcome, createVoiceTelephonyOutcomePolicy, createVoiceTelephonyWebhookHandler, createVoiceTelephonyWebhookRoutes, parseVoiceTelephonyWebhookEvent, resolveVoiceTelephonyOutcome, voiceTelephonyOutcomeToRouteResult } from './telephonyOutcome';
+export { applyVoiceTelephonyOutcome, createVoiceTelephonyOutcomePolicy, createVoiceTelephonyWebhookHandler, createVoiceTelephonyWebhookRoutes, parseVoiceTelephonyWebhookEvent, resolveVoiceTelephonyOutcome, signVoiceTwilioWebhook, verifyVoiceTwilioWebhookSignature, voiceTelephonyOutcomeToRouteResult } from './telephonyOutcome';
 export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileExternalObjectMapStore, createVoiceFileAssistantMemoryStore, createVoiceFileIntegrationEventStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore } from './fileStore';
 export { createVoiceAssistantMemoryHandle, createVoiceAssistantMemoryRecord, createVoiceMemoryAssistantMemoryStore, resolveVoiceAssistantMemoryNamespace } from './assistantMemory';
 export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter } from './modelAdapters';
@@ -57,7 +57,7 @@ export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProvid
 export type { VoiceProviderCapabilityDefinition, VoiceProviderCapabilityHandlerOptions, VoiceProviderCapabilityHTMLHandlerOptions, VoiceProviderCapabilityKind, VoiceProviderCapabilityOptions, VoiceProviderCapabilityReport, VoiceProviderCapabilityRoutesOptions, VoiceProviderCapabilitySummary } from './providerCapabilities';
 export type { VoiceTurnQualityHTMLHandlerOptions, VoiceTurnQualityItem, VoiceTurnQualityOptions, VoiceTurnQualityReport, VoiceTurnQualityRoutesOptions, VoiceTurnQualityStatus } from './turnQuality';
 export type { VoiceOutcomeContractDefinition, VoiceOutcomeContractHTMLHandlerOptions, VoiceOutcomeContractIssue, VoiceOutcomeContractOptions, VoiceOutcomeContractReport, VoiceOutcomeContractRoutesOptions, VoiceOutcomeContractStatus, VoiceOutcomeContractSuiteReport } from './outcomeContract';
-export type { VoiceTelephonyOutcomeAction, VoiceTelephonyOutcomeDecision, VoiceTelephonyOutcomePolicy, VoiceTelephonyOutcomeProviderEvent, VoiceTelephonyOutcomeRouteResult, VoiceTelephonyOutcomeStatusDecision, VoiceTelephonyWebhookDecision, VoiceTelephonyWebhookHandlerOptions, VoiceTelephonyWebhookParseInput, VoiceTelephonyWebhookProvider, VoiceTelephonyWebhookRoutesOptions } from './telephonyOutcome';
+export type { VoiceTelephonyOutcomeAction, VoiceTelephonyOutcomeDecision, VoiceTelephonyOutcomePolicy, VoiceTelephonyOutcomeProviderEvent, VoiceTelephonyOutcomeRouteResult, VoiceTelephonyOutcomeStatusDecision, VoiceTelephonyWebhookDecision, VoiceTelephonyWebhookHandlerOptions, VoiceTelephonyWebhookParseInput, VoiceTelephonyWebhookProvider, VoiceTelephonyWebhookRoutesOptions, VoiceTelephonyWebhookVerificationResult } from './telephonyOutcome';
 export type { VoiceOpsConsoleLink, VoiceOpsConsoleReport, VoiceOpsConsoleRoutesOptions } from './opsConsoleRoutes';
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';
 export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingDecisionSummary, VoiceRoutingDecisionSummaryOptions, VoiceRoutingEvent, VoiceRoutingEventKind } from './resilienceRoutes';

package/dist/index.js

@@ -2990,7 +2990,7 @@ var toVoiceSessionSummary = (session) => ({
 });
 
 // src/session.ts
-import { Buffer } from "buffer";
+import { Buffer as Buffer2 } from "buffer";
 
 // src/handoff.ts
 var toHex3 = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -3425,7 +3425,7 @@ var createEmptyCurrentTurn = () => ({
   transcripts: []
 });
 var cloneTranscript = (transcript) => ({ ...transcript });
-var encodeBase64 = (chunk) => Buffer.from(chunk).toString("base64");
+var encodeBase64 = (chunk) => Buffer2.from(chunk).toString("base64");
 var countWords2 = (text) => text.trim().split(/\s+/).filter(Boolean).length;
 var normalizeText2 = (text) => text.trim().replace(/\s+/g, " ");
 var getAudioChunkDurationMs = (chunk) => chunk.byteLength / (DEFAULT_FORMAT.sampleRateHz * DEFAULT_FORMAT.channels * 2) * 1000;
@@ -10601,6 +10601,15 @@ var DEFAULT_MACHINE_VOICEMAIL_VALUES = [
 ];
 var DEFAULT_NO_ANSWER_SIP_CODES = [408, 480, 486, 487, 603];
 var isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+class VoiceTelephonyWebhookVerificationError extends Error {
+  result;
+  constructor(result) {
+    super(result.ok ? "telephony webhook verified" : result.reason);
+    this.name = "VoiceTelephonyWebhookVerificationError";
+    this.result = result;
+  }
+}
 var normalizeToken = (value) => typeof value === "string" ? value.trim().toLowerCase().replace(/\s+/g, "-").replace(/_+/g, "-") : undefined;
 var firstString = (source, keys) => {
   for (const key of keys) {
@@ -10649,6 +10658,30 @@ var flattenPayload = (value) => {
     ...isRecord(data?.payload) ? data.payload : undefined
   };
 };
+var toBase64 = (bytes) => Buffer.from(new Uint8Array(bytes)).toString("base64");
+var timingSafeEqual = (left, right) => {
+  const encoder = new TextEncoder;
+  const leftBytes = encoder.encode(left);
+  const rightBytes = encoder.encode(right);
+  if (leftBytes.length !== rightBytes.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let index = 0;index < leftBytes.length; index += 1) {
+    diff |= leftBytes[index] ^ rightBytes[index];
+  }
+  return diff === 0;
+};
+var signHmacSHA1Base64 = async (secret, payload) => {
+  const encoder = new TextEncoder;
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+    hash: "SHA-1",
+    name: "HMAC"
+  }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  return toBase64(signature);
+};
+var sortedParamsForSignature = (body) => Object.entries(flattenPayload(body)).filter(([, value]) => value !== undefined && value !== null).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}${String(value)}`).join("");
 var normalizeList = (values, fallback) => new Set((values ?? fallback).map(normalizeToken).filter(Boolean));
 var metadataValue = (metadata, keys) => {
   for (const key of keys) {
@@ -10882,9 +10915,8 @@ var applyVoiceTelephonyOutcome = async (api, decision, result) => {
       break;
   }
 };
-var parseRequestBody = async (request) => {
-  const contentType = request.headers.get("content-type") ?? "";
-  const text = await request.text();
+var parseRequestBodyText = (input) => {
+  const { contentType, text } = input;
   if (!text) {
     return {};
   }
@@ -10896,6 +10928,58 @@ var parseRequestBody = async (request) => {
   }
   return parseMaybeJSON(text) ?? Object.fromEntries(new URLSearchParams(text));
 };
+var readRequestBody = async (request) => {
+  const contentType = request.headers.get("content-type") ?? "";
+  const text = await request.text();
+  return {
+    body: parseRequestBodyText({ contentType, text }),
+    rawBody: text
+  };
+};
+var signVoiceTwilioWebhook = async (input) => signHmacSHA1Base64(input.authToken, `${input.url}${sortedParamsForSignature(input.body ?? {})}`);
+var verifyVoiceTwilioWebhookSignature = async (input) => {
+  if (!input.authToken) {
+    return { ok: false, reason: "missing-secret" };
+  }
+  const signature = input.headers.get("x-twilio-signature");
+  if (!signature) {
+    return { ok: false, reason: "missing-signature" };
+  }
+  const expected = await signVoiceTwilioWebhook({
+    authToken: input.authToken,
+    body: input.body,
+    url: input.url
+  });
+  return timingSafeEqual(signature, expected) ? { ok: true } : { ok: false, reason: "invalid-signature" };
+};
+var resolveVerificationUrl = (option, input) => typeof option === "function" ? option(input) : option ?? input.request.url;
+var verifyVoiceTelephonyWebhook = async (input) => {
+  if (input.options.verify) {
+    return input.options.verify({
+      body: input.body,
+      headers: input.request.headers,
+      provider: input.provider,
+      query: input.query,
+      rawBody: input.rawBody,
+      request: input.request
+    });
+  }
+  if (!input.options.signingSecret) {
+    return input.options.requireVerification ? { ok: false, reason: "missing-secret" } : { ok: true };
+  }
+  if (input.provider !== "twilio") {
+    return { ok: false, reason: "unsupported-provider" };
+  }
+  return verifyVoiceTwilioWebhookSignature({
+    authToken: input.options.signingSecret,
+    body: input.body,
+    headers: input.request.headers,
+    url: resolveVerificationUrl(input.options.verificationUrl, {
+      query: input.query,
+      request: input.request
+    })
+  });
+};
 var durationMsFromSeconds = (value) => typeof value === "number" ? value * 1000 : undefined;
 var parseVoiceTelephonyWebhookEvent = (input) => {
   const payload = flattenPayload(input.body);
@@ -10978,7 +11062,18 @@ var defaultSessionId = (input) => {
 var createVoiceTelephonyWebhookHandler = (options = {}) => async (input) => {
   const provider = options.provider ?? "generic";
   const query = input.query ?? {};
-  const body = await parseRequestBody(input.request);
+  const { body, rawBody } = await readRequestBody(input.request);
+  const verification = await verifyVoiceTelephonyWebhook({
+    body,
+    options,
+    provider,
+    query,
+    rawBody,
+    request: input.request
+  });
+  if (!verification.ok) {
+    throw new VoiceTelephonyWebhookVerificationError(verification);
+  }
   const event = options.parse ? await options.parse({
     body,
     headers: input.request.headers,
@@ -11046,7 +11141,21 @@ var createVoiceTelephonyWebhookRoutes = (options = {}) => {
   const handler = createVoiceTelephonyWebhookHandler(options);
   return new Elysia16({
     name: options.name ?? "absolutejs-voice-telephony-webhooks"
-  }).post(path, async ({ query, request }) => handler({ query, request }));
+  }).post(path, async ({ query, request }) => {
+    try {
+      return await handler({ query, request });
+    } catch (error) {
+      if (error instanceof VoiceTelephonyWebhookVerificationError) {
+        return new Response(JSON.stringify({ verification: error.result }), {
+          headers: {
+            "content-type": "application/json"
+          },
+          status: 401
+        });
+      }
+      throw error;
+    }
+  });
 };
 // src/fileStore.ts
 import { mkdir as mkdir2, readFile, readdir, rename, rm, writeFile } from "fs/promises";
@@ -13152,7 +13261,7 @@ var signVoiceOpsWebhookBody = async (input) => {
   const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(`${input.timestamp}.${input.body}`));
   return `sha256=${toHex5(new Uint8Array(signature))}`;
 };
-var timingSafeEqual = (left, right) => {
+var timingSafeEqual2 = (left, right) => {
   const encoder = new TextEncoder;
   const leftBytes = encoder.encode(left);
   const rightBytes = encoder.encode(right);
@@ -13259,7 +13368,7 @@ var verifyVoiceOpsWebhookSignature = async (input) => {
     secret: input.secret,
     timestamp: input.timestamp
   });
-  if (!timingSafeEqual(expected, input.signature)) {
+  if (!timingSafeEqual2(expected, input.signature)) {
     return {
       ok: false,
       reason: "invalid-signature"
@@ -14978,7 +15087,7 @@ var createVoiceSTTRoutingCorrectionHandler = (mode = "generic") => {
   return createPhraseHintCorrectionHandler();
 };
 // src/telephony/twilio.ts
-import { Buffer as Buffer2 } from "buffer";
+import { Buffer as Buffer3 } from "buffer";
 var TWILIO_MULAW_SAMPLE_RATE = 8000;
 var VOICE_PCM_SAMPLE_RATE = 16000;
 var escapeXml2 = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
@@ -15083,7 +15192,7 @@ var bytesToInt16Array = (bytes) => {
   return output;
 };
 var decodeTwilioMulawBase64 = (payload) => {
-  const bytes = Uint8Array.from(Buffer2.from(payload, "base64"));
+  const bytes = Uint8Array.from(Buffer3.from(payload, "base64"));
   const samples = new Int16Array(bytes.length);
   for (let index = 0;index < bytes.length; index += 1) {
     samples[index] = decodeMulawSample(bytes[index] ?? 0);
@@ -15095,7 +15204,7 @@ var encodeTwilioMulawBase64 = (samples) => {
   for (let index = 0;index < samples.length; index += 1) {
     bytes[index] = encodeMulawSample(samples[index] ?? 0);
   }
-  return Buffer2.from(bytes).toString("base64");
+  return Buffer3.from(bytes).toString("base64");
 };
 var transcodeTwilioInboundPayloadToPCM16 = (payload) => {
   const narrowband = decodeTwilioMulawBase64(payload);
@@ -15104,7 +15213,7 @@ var transcodeTwilioInboundPayloadToPCM16 = (payload) => {
 };
 var transcodePCMToTwilioOutboundPayload = (chunk, format) => {
   if (format.container === "raw" && format.encoding === "mulaw" && format.channels === 1 && format.sampleRateHz === TWILIO_MULAW_SAMPLE_RATE) {
-    return Buffer2.from(chunk).toString("base64");
+    return Buffer3.from(chunk).toString("base64");
   }
   if (format.encoding !== "pcm_s16le") {
     throw new Error(`Unsupported outbound telephony audio format: ${format.container}/${format.encoding}`);
@@ -15145,7 +15254,7 @@ var createTwilioSocketAdapter = (socket, getState) => ({
       return;
     }
     if (message.type === "audio") {
-      const payload = transcodePCMToTwilioOutboundPayload(Uint8Array.from(Buffer2.from(message.chunkBase64, "base64")), message.format);
+      const payload = transcodePCMToTwilioOutboundPayload(Uint8Array.from(Buffer3.from(message.chunkBase64, "base64")), message.format);
       state.hasOutboundAudioSinceLastInbound = true;
       state.reviewRecorder?.recordTwilioOutbound({
         bytes: payload.length,
@@ -15415,6 +15524,7 @@ export {
   withVoiceIntegrationEventId,
   voiceTelephonyOutcomeToRouteResult,
   voice,
+  verifyVoiceTwilioWebhookSignature,
   verifyVoiceOpsWebhookSignature,
   validateVoiceWorkflowRouteResult,
   transcodeTwilioInboundPayloadToPCM16,
@@ -15437,6 +15547,7 @@ export {
   summarizeVoiceAssistantHealth,
   summarizeVoiceAppKitStatus,
   startVoiceOpsTask,
+  signVoiceTwilioWebhook,
   shapeTelephonyAssistantText,
   selectVoiceTraceEventsForPrune,
   runVoiceToolContractSuite,

package/dist/telephonyOutcome.d.ts

@@ -59,6 +59,12 @@ export type VoiceTelephonyWebhookDecision<TResult = unknown> = {
     routeResult: VoiceTelephonyOutcomeRouteResult<TResult>;
     sessionId?: string;
 };
+export type VoiceTelephonyWebhookVerificationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'invalid-signature' | 'missing-secret' | 'missing-signature' | 'unsupported-provider';
+};
 export type VoiceTelephonyWebhookHandlerOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     apply?: boolean | ((input: VoiceTelephonyWebhookDecision<TResult>) => boolean);
     context?: TContext;
@@ -76,6 +82,7 @@ export type VoiceTelephonyWebhookHandlerOptions<TContext = unknown, TSession ext
     parse?: (input: VoiceTelephonyWebhookParseInput) => Promise<VoiceTelephonyOutcomeProviderEvent> | VoiceTelephonyOutcomeProviderEvent;
     policy?: VoiceTelephonyOutcomePolicy;
     provider?: VoiceTelephonyWebhookProvider;
+    requireVerification?: boolean;
     resolveSessionId?: (input: {
         body: unknown;
         event: VoiceTelephonyOutcomeProviderEvent;
@@ -87,15 +94,43 @@ export type VoiceTelephonyWebhookHandlerOptions<TContext = unknown, TSession ext
         event: VoiceTelephonyOutcomeProviderEvent;
         sessionId?: string;
     }) => Promise<TResult | undefined> | TResult | undefined);
+    signingSecret?: string;
+    verificationUrl?: string | ((input: {
+        query: Record<string, unknown>;
+        request: Request;
+    }) => string);
+    verify?: (input: {
+        body: unknown;
+        headers: Headers;
+        provider: VoiceTelephonyWebhookProvider;
+        query: Record<string, unknown>;
+        rawBody: string;
+        request: Request;
+    }) => Promise<VoiceTelephonyWebhookVerificationResult> | VoiceTelephonyWebhookVerificationResult;
 };
 export type VoiceTelephonyWebhookRoutesOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = VoiceTelephonyWebhookHandlerOptions<TContext, TSession, TResult> & {
     name?: string;
     path?: string;
 };
+export declare class VoiceTelephonyWebhookVerificationError extends Error {
+    result: VoiceTelephonyWebhookVerificationResult;
+    constructor(result: VoiceTelephonyWebhookVerificationResult);
+}
 export declare const createVoiceTelephonyOutcomePolicy: (policy?: VoiceTelephonyOutcomePolicy) => Required<Pick<VoiceTelephonyOutcomePolicy, "completedStatuses" | "escalationStatuses" | "failedAsNoAnswer" | "failedStatuses" | "includeProviderPayload" | "machineDetectionVoicemailValues" | "noAnswerOnZeroDuration" | "noAnswerSipCodes" | "noAnswerStatuses" | "transferStatuses" | "voicemailStatuses">> & VoiceTelephonyOutcomePolicy;
 export declare const resolveVoiceTelephonyOutcome: (event: VoiceTelephonyOutcomeProviderEvent, policyInput?: VoiceTelephonyOutcomePolicy) => VoiceTelephonyOutcomeDecision;
 export declare const voiceTelephonyOutcomeToRouteResult: <TResult = unknown>(decision: VoiceTelephonyOutcomeDecision, result?: TResult) => VoiceTelephonyOutcomeRouteResult<TResult>;
 export declare const applyVoiceTelephonyOutcome: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(api: VoiceSessionHandle<TContext, TSession, TResult>, decision: VoiceTelephonyOutcomeDecision, result?: TResult) => Promise<void>;
+export declare const signVoiceTwilioWebhook: (input: {
+    authToken: string;
+    body?: unknown;
+    url: string;
+}) => Promise<string>;
+export declare const verifyVoiceTwilioWebhookSignature: (input: {
+    authToken?: string;
+    body?: unknown;
+    headers: Headers;
+    url: string;
+}) => Promise<VoiceTelephonyWebhookVerificationResult>;
 export declare const parseVoiceTelephonyWebhookEvent: (input: VoiceTelephonyWebhookParseInput) => VoiceTelephonyOutcomeProviderEvent;
 export declare const createVoiceTelephonyWebhookHandler: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options?: VoiceTelephonyWebhookHandlerOptions<TContext, TSession, TResult>) => (input: {
     query?: Record<string, unknown>;
@@ -124,7 +159,7 @@ export declare const createVoiceTelephonyWebhookRoutes: <TContext = unknown, TSe
             query: unknown;
             headers: unknown;
             response: {
-                200: VoiceTelephonyWebhookDecision<TResult>;
+                200: Response | VoiceTelephonyWebhookDecision<TResult>;
             };
         };
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.70",
+	"version": "0.0.22-beta.71",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",