@kuralle-syrinx/server-websocket 4.2.0 → 4.3.0

package/src/telnyx.ts

@@ -5,12 +5,9 @@ import { createServer, type Server as HttpServer } from "node:http";
 import { WebSocket, WebSocketServer, type RawData } from "ws";
 import { Route, type VoiceAgentSession } from "@kuralle-syrinx/core";
 import {
-  bigEndianPcm16BytesToSamples,
-  decodeMuLawToPcm16,
-  encodePcm16ToMuLaw,
+  createG722DecoderState,
   pcm16BytesToSamples,
   pcm16SamplesToBytes,
-  pcm16SamplesToBigEndianBytes,
   resamplePcm16Streaming,
   type StreamingPcm16Resampler,
 } from "@kuralle-syrinx/core/audio";
@@ -30,12 +27,28 @@ import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation } from "./o
 import {
   decodeStrictBase64,
   nonNegativeInteger,
-  numberFromString,
   optionalNonNegativeIntegerString,
   optionalPositiveIntegerString,
   positiveInteger,
   rawDataToText,
 } from "./transport-helpers.js";
+import type { FetchLike, TelnyxRestCredentials, WarmTransferSummarizer } from "./carrier-commands.js";
+import { wireCarrierControl } from "./wire-carrier-control.js";
+import {
+  createTelnyxG722State,
+  decodeTelnyxInboundPayload,
+  defaultTelnyxContextId,
+  encodeTelnyxOutboundPayload,
+  splitTelnyxEncodedFrames,
+  validateTelnyxStart,
+  wireSampleRateForCodec,
+  type TelnyxCodec,
+  type TelnyxG722State,
+  type TelnyxStartPayload,
+} from "./telnyx-codec.js";
+
+export type { TelnyxCodec, TelnyxStartPayload } from "./telnyx-codec.js";
+export { validateTelnyxStart, defaultTelnyxContextId } from "./telnyx-codec.js";
 
 export interface TelnyxMediaStreamServerOptions {
   readonly server?: HttpServer;
@@ -47,7 +60,7 @@ export interface TelnyxMediaStreamServerOptions {
   readonly inputSampleRateHz?: number;
   readonly outputSampleRateHz?: number;
   /** Must match the `stream_bidirectional_codec` selected when starting the Telnyx call stream. */
-  readonly bidirectionalCodec?: "PCMU" | "L16";
+  readonly bidirectionalCodec?: TelnyxCodec;
   readonly outboundFrameDurationMs?: number;
   readonly maxQueuedOutputAudioMs?: number;
   /** Ambient/thinking bed mixed (ducked) under assistant speech (see BackgroundAudioConfig). */
@@ -61,6 +74,15 @@ export interface TelnyxMediaStreamServerOptions {
   readonly maxConcurrentSessions?: number;
   readonly maxConcurrentSessionsScope?: "path" | "server";
   readonly onTransportMetric?: (name: string) => void;
+  /**
+   * Injected Call Control credentials for dtmf.send / call.transfer dispatch.
+   * Workers: pass secrets from `env`. Never read from process.env here.
+   * Live dispatch unverified without credentials.
+   */
+  readonly callControlCredentials?: TelnyxRestCredentials;
+  readonly callControlFetch?: FetchLike;
+  readonly callControlWebhookUrl?: string;
+  readonly warmTransferSummarizer?: WarmTransferSummarizer;
 }
 
 export interface TelnyxMediaStreamServer {
@@ -70,17 +92,6 @@ export interface TelnyxMediaStreamServer {
   close(opts?: GracefulCloseOptions): Promise<void>;
 }
 
-export interface TelnyxStartPayload {
-  readonly stream_id?: string;
-  readonly call_control_id?: string;
-  readonly call_session_id?: string;
-  readonly media_format?: {
-    readonly encoding?: string;
-    readonly sample_rate?: number | string;
-    readonly channels?: number | string;
-  };
-}
-
 interface TelnyxMediaMessage {
   readonly event?: string;
   readonly stream_id?: string;
@@ -102,10 +113,9 @@ interface PendingTelnyxMediaFrame {
   readonly pcm: Int16Array;
 }
 
-type TelnyxCodec = "PCMU" | "L16";
-
 interface TelnyxConnectionState {
   streamId: string;
+  callControlId: string;
   contextId: string;
   contextBase: string;
   turnCounter: number;
@@ -125,6 +135,8 @@ interface TelnyxConnectionState {
   onPlaybackMarkReceived?: () => void;
   clearPlayout: (reason: string) => void;
   readonly streamingResamplers: Map<string, StreamingPcm16Resampler>;
+  /** Stateful G.722 encoder/decoder (only used when codec is G722). */
+  g722: TelnyxG722State;
 }
 
 const DEFAULT_ENGINE_SAMPLE_RATE_HZ = 16000;
@@ -155,7 +167,7 @@ export async function createTelnyxMediaStreamServer(
   const sessions = new Set<VoiceAgentSession>();
   const inputSampleRateHz = positiveInteger(options.inputSampleRateHz) ?? DEFAULT_ENGINE_SAMPLE_RATE_HZ;
   const bidirectionalCodec: TelnyxCodec = options.bidirectionalCodec ?? "PCMU";
-  const outboundSampleRateHz = bidirectionalCodec === "L16" ? 16000 : 8000;
+  const outboundSampleRateHz = wireSampleRateForCodec(bidirectionalCodec);
   const outboundFrameDurationMs = positiveInteger(options.outboundFrameDurationMs) ?? DEFAULT_OUTBOUND_FRAME_DURATION_MS;
   const maxQueuedOutputAudioMs = positiveInteger(options.maxQueuedOutputAudioMs) ?? DEFAULT_MAX_QUEUED_OUTPUT_AUDIO_MS;
   const maxInboundReorderFrames = positiveInteger(options.maxInboundReorderFrames) ?? DEFAULT_MAX_INBOUND_REORDER_FRAMES;
@@ -172,6 +184,7 @@ export async function createTelnyxMediaStreamServer(
   const adapter: TransportAdapter<TelnyxConnectionState> = {
     createState: () => ({
       streamId: "",
+      callControlId: "",
       contextId: "",
       contextBase: "",
       turnCounter: 0,
@@ -190,6 +203,7 @@ export async function createTelnyxMediaStreamServer(
       pendingEndMarkName: "",
       clearPlayout: () => undefined,
       streamingResamplers: new Map(),
+      g722: createTelnyxG722State(bidirectionalCodec),
     }),
 
     async acquireSession({ request, shouldAbort, onSessionCreated }) {
@@ -221,6 +235,15 @@ export async function createTelnyxMediaStreamServer(
       };
       state.onPlaybackMarkReceived = sendPendingEndMark;
 
+      wireCarrierControl(session, disposers, {
+        carrier: "telnyx",
+        getCallControlId: () => state.callControlId || undefined,
+        credentials: options.callControlCredentials,
+        fetchImpl: options.callControlFetch,
+        webhookUrl: options.callControlWebhookUrl,
+        warmSummarizer: options.warmTransferSummarizer,
+      });
+
       const outbound = wireTelephonyOutboundPipeline({
         session,
         socket,
@@ -323,10 +346,16 @@ export async function createTelnyxMediaStreamServer(
         const format = validateTelnyxStart(start);
         state.streamId = message.stream_id ?? start.stream_id ?? "";
         if (!state.streamId) throw new Error("Telnyx start event is missing stream_id");
+        state.callControlId = start.call_control_id?.trim() ?? "";
         state.contextId = contextIdFn(start);
         state.contextBase = state.contextId;
         state.inboundCodec = format.codec;
         state.inboundSampleRateHz = format.sampleRateHz;
+        // G.722 is stateful — reset decoder on each stream start. Keep 16 kHz
+        // for inbound (do NOT downsample before STT; that is the quality pitfall).
+        if (format.codec === "G722") {
+          state.g722.decoder = createG722DecoderState();
+        }
         state.started = true;
         state.nextInboundMediaChunk = 1;
         state.inboundMediaReorderBuffer.clear();
@@ -338,7 +367,7 @@ export async function createTelnyxMediaStreamServer(
         const payload = message.media?.payload;
         if (!payload) throw new Error("Telnyx media event is missing media.payload");
         const encoded = decodeStrictBase64(payload, "media.payload");
-        const pcm = decodeInboundPayload(encoded, state.inboundCodec);
+        const pcm = decodeInboundPayload(encoded, state);
         const chunk = optionalPositiveIntegerString(message.media?.chunk, "Telnyx media.chunk");
         if (chunk === undefined) {
           emitTelnyxMediaFrame(session, state, { chunk: 0, timestamp: message.media?.timestamp, pcm }, inputSampleRateHz);
@@ -657,25 +686,8 @@ function rememberTelnyxMediaTimestamp(
   state.lastInboundMediaTimestampMs = timestampMs;
 }
 
-function validateTelnyxStart(start: TelnyxStartPayload): { readonly codec: TelnyxCodec; readonly sampleRateHz: number } {
-  const format = start.media_format;
-  if (!format) throw new Error("Telnyx start event is missing media_format");
-  const encoding = format.encoding?.trim().toUpperCase();
-  if (encoding !== "PCMU" && encoding !== "L16") {
-    throw new Error(`Unsupported Telnyx media encoding: ${format.encoding ?? "unknown"}`);
-  }
-  const sampleRateHz = numberFromString(format.sample_rate);
-  if (encoding === "PCMU" && sampleRateHz !== 8000) throw new Error(`Unsupported Telnyx PCMU sample rate: ${String(format.sample_rate)}`);
-  if (encoding === "L16" && sampleRateHz !== 16000) throw new Error(`Unsupported Telnyx L16 sample rate: ${String(format.sample_rate)}`);
-  if (sampleRateHz === null) throw new Error(`Unsupported Telnyx sample rate: ${String(format.sample_rate)}`);
-  const channels = numberFromString(format.channels);
-  if (channels !== 1) throw new Error(`Unsupported Telnyx channel count: ${String(format.channels)}`);
-  return { codec: encoding, sampleRateHz };
-}
-
-function decodeInboundPayload(input: Uint8Array, codec: TelnyxCodec): Int16Array {
-  if (codec === "PCMU") return decodeMuLawToPcm16(input);
-  return bigEndianPcm16BytesToSamples(input);
+function decodeInboundPayload(input: Uint8Array, state: TelnyxConnectionState): Int16Array {
+  return decodeTelnyxInboundPayload(input, state.inboundCodec, state.g722);
 }
 
 function encodeOutboundPayload(
@@ -686,25 +698,8 @@ function encodeOutboundPayload(
 ): Uint8Array[] {
   const samples = pcm16BytesToSamples(audio);
   const resampled = resamplePcm16Streaming(state.streamingResamplers, samples, sourceSampleRateHz, state.outboundSampleRateHz);
-  const encoded = state.outboundCodec === "PCMU"
-    ? encodePcm16ToMuLaw(resampled)
-    : pcm16SamplesToBigEndianBytes(resampled);
-  const frameBytes = Math.max(1, Math.round((state.outboundSampleRateHz * frameDurationMs) / 1000) * (state.outboundCodec === "L16" ? 2 : 1));
-  const frames: Uint8Array[] = [];
-  for (let offset = 0; offset < encoded.byteLength; offset += frameBytes) {
-    frames.push(encoded.subarray(offset, Math.min(encoded.byteLength, offset + frameBytes)));
-  }
-  return frames;
-}
-
-function defaultTelnyxContextId(start: TelnyxStartPayload): string {
-  const callControlId = start.call_control_id?.trim();
-  if (callControlId) return `telnyx-${callControlId}`;
-  const callSessionId = start.call_session_id?.trim();
-  if (callSessionId) return `telnyx-${callSessionId}`;
-  const streamId = start.stream_id?.trim();
-  if (streamId) return `telnyx-${streamId}`;
-  return `telnyx-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  const encoded = encodeTelnyxOutboundPayload(resampled, state.outboundCodec, state.g722);
+  return splitTelnyxEncodedFrames(encoded, state.outboundCodec, state.outboundSampleRateHz, frameDurationMs);
 }
 
 function sendTelnyxError(socket: WebSocket, streamId: string, message: string, maxBufferedAmountBytes: number): void {

package/src/twilio.ts

@@ -33,6 +33,8 @@ import {
   positiveInteger,
   rawDataToText,
 } from "./transport-helpers.js";
+import type { FetchLike, TwilioRestCredentials, WarmTransferSummarizer } from "./carrier-commands.js";
+import { wireCarrierControl } from "./wire-carrier-control.js";
 
 export interface TwilioMediaStreamServerOptions {
   readonly server?: HttpServer;
@@ -56,6 +58,15 @@ export interface TwilioMediaStreamServerOptions {
   readonly maxConcurrentSessions?: number;
   readonly maxConcurrentSessionsScope?: "path" | "server";
   readonly onTransportMetric?: (name: string) => void;
+  /**
+   * Injected REST credentials for dtmf.send / call.transfer dispatch.
+   * Workers: pass secrets from `env`. Never read from process.env here.
+   * Live dispatch unverified without credentials.
+   */
+  readonly restCredentials?: TwilioRestCredentials;
+  readonly restFetch?: FetchLike;
+  readonly transferRedirectUrl?: string;
+  readonly warmTransferSummarizer?: WarmTransferSummarizer;
 }
 
 export interface TwilioMediaStreamServer {
@@ -92,6 +103,7 @@ interface TwilioMediaMessage {
 
 interface TwilioConnectionState {
   streamSid: string;
+  callSid: string;
   contextId: string;
   contextBase: string;
   turnCounter: number;
@@ -152,6 +164,7 @@ export async function createTwilioMediaStreamServer(
   const adapter: TransportAdapter<TwilioConnectionState> = {
     createState: () => ({
       streamSid: "",
+      callSid: "",
       contextId: "",
       contextBase: "",
       turnCounter: 0,
@@ -197,6 +210,15 @@ export async function createTwilioMediaStreamServer(
       };
       state.onPlaybackMarkReceived = sendPendingEndMark;
 
+      wireCarrierControl(session, disposers, {
+        carrier: "twilio",
+        getCallSid: () => state.callSid || undefined,
+        credentials: options.restCredentials,
+        fetchImpl: options.restFetch,
+        redirectUrl: options.transferRedirectUrl,
+        warmSummarizer: options.warmTransferSummarizer,
+      });
+
       const outbound = wireTelephonyOutboundPipeline({
         session,
         socket,
@@ -304,6 +326,7 @@ export async function createTwilioMediaStreamServer(
         validateTwilioStart(start, twilioSampleRateHz);
         state.streamSid = start.streamSid ?? message.streamSid ?? "";
         if (!state.streamSid) throw new Error("Twilio start event is missing streamSid");
+        state.callSid = start.callSid?.trim() ?? "";
         state.contextId = contextIdFn(start);
         state.contextBase = state.contextId;
         state.started = true;

package/src/wire-carrier-control.ts

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: MIT
+//
+// Bus wiring for dtmf.send + call.transfer → pure constructor + injectable dispatch.
+// Mechanism unit-tested; live carrier HTTP unverified.
+
+import { Route, type CallTransferPacket, type DtmfSendPacket, type VoiceAgentSession } from "@kuralle-syrinx/core";
+import {
+  buildTelnyxSendDtmf,
+  buildTelnyxTransfer,
+  buildTwilioSendDigits,
+  buildTwilioTransfer,
+  dispatchTelnyxCommand,
+  dispatchTwilioCommand,
+  resolveTransferSummary,
+  type FetchLike,
+  type TelnyxRestCredentials,
+  type TwilioRestCredentials,
+  type WarmTransferSummarizer,
+} from "./carrier-commands.js";
+
+export interface TwilioCarrierControlOptions {
+  readonly carrier: "twilio";
+  /** Call SID for the active media stream (injected; may resolve lazily). */
+  getCallSid: () => string | undefined;
+  readonly credentials?: TwilioRestCredentials;
+  readonly fetchImpl?: FetchLike;
+  readonly redirectUrl?: string;
+  readonly warmSummarizer?: WarmTransferSummarizer;
+}
+
+export interface TelnyxCarrierControlOptions {
+  readonly carrier: "telnyx";
+  getCallControlId: () => string | undefined;
+  readonly credentials?: TelnyxRestCredentials;
+  readonly fetchImpl?: FetchLike;
+  readonly webhookUrl?: string;
+  readonly warmSummarizer?: WarmTransferSummarizer;
+}
+
+export type CarrierControlOptions = TwilioCarrierControlOptions | TelnyxCarrierControlOptions;
+
+/**
+ * Subscribe to `dtmf.send` and `call.transfer` on the session bus.
+ * When credentials are absent, still builds the command and emits a metric so
+ * unit tests can assert the constructor path without live HTTP.
+ */
+export function wireCarrierControl(
+  session: VoiceAgentSession,
+  disposers: Array<() => void>,
+  options: CarrierControlOptions,
+): void {
+  disposers.push(
+    session.bus.on("dtmf.send", (pkt) => {
+      void handleDtmfSend(session, pkt as DtmfSendPacket, options);
+    }),
+    session.bus.on("call.transfer", (pkt) => {
+      void handleCallTransfer(session, pkt as CallTransferPacket, options);
+    }),
+  );
+}
+
+async function handleDtmfSend(
+  session: VoiceAgentSession,
+  pkt: DtmfSendPacket,
+  options: CarrierControlOptions,
+): Promise<void> {
+  try {
+    if (options.carrier === "twilio") {
+      const callSid = options.getCallSid();
+      if (!callSid) {
+        emitMetric(session, pkt.contextId, "carrier.dtmf_send.missing_call_handle", "twilio");
+        return;
+      }
+      const command = buildTwilioSendDigits(callSid, pkt);
+      emitMetric(session, pkt.contextId, "carrier.dtmf_send.built", JSON.stringify({ carrier: "twilio", digits: command.form.SendDigits }));
+      if (!options.credentials) {
+        emitMetric(session, pkt.contextId, "carrier.dtmf_send.no_credentials", "twilio");
+        return;
+      }
+      const res = await dispatchTwilioCommand(options.credentials, command, options.fetchImpl);
+      emitMetric(session, pkt.contextId, "carrier.dtmf_send.dispatched", String(res.status));
+      return;
+    }
+
+    const callControlId = options.getCallControlId();
+    if (!callControlId) {
+      emitMetric(session, pkt.contextId, "carrier.dtmf_send.missing_call_handle", "telnyx");
+      return;
+    }
+    const command = buildTelnyxSendDtmf(callControlId, pkt);
+    emitMetric(session, pkt.contextId, "carrier.dtmf_send.built", JSON.stringify({ carrier: "telnyx", digits: command.json.digits }));
+    if (!options.credentials) {
+      emitMetric(session, pkt.contextId, "carrier.dtmf_send.no_credentials", "telnyx");
+      return;
+    }
+    const res = await dispatchTelnyxCommand(options.credentials, command, options.fetchImpl);
+    emitMetric(session, pkt.contextId, "carrier.dtmf_send.dispatched", String(res.status));
+  } catch (err) {
+    emitMetric(session, pkt.contextId, "carrier.dtmf_send.error", err instanceof Error ? err.message : String(err));
+  }
+}
+
+async function handleCallTransfer(
+  session: VoiceAgentSession,
+  pkt: CallTransferPacket,
+  options: CarrierControlOptions,
+): Promise<void> {
+  try {
+    const summary = await resolveTransferSummary(pkt, options.warmSummarizer);
+    const resolved = summary !== undefined ? { ...pkt, summary } : pkt;
+
+    if (options.carrier === "twilio") {
+      const callSid = options.getCallSid();
+      if (!callSid) {
+        emitMetric(session, pkt.contextId, "carrier.transfer.missing_call_handle", "twilio");
+        return;
+      }
+      const command = buildTwilioTransfer(callSid, resolved, {
+        redirectUrl: options.redirectUrl,
+      });
+      emitMetric(
+        session,
+        pkt.contextId,
+        "carrier.transfer.built",
+        JSON.stringify({
+          carrier: "twilio",
+          mode: command.mode,
+          target: resolved.target,
+          summary: command.summary ?? null,
+        }),
+      );
+      if (!options.credentials) {
+        emitMetric(session, pkt.contextId, "carrier.transfer.no_credentials", "twilio");
+        return;
+      }
+      const res = await dispatchTwilioCommand(options.credentials, command, options.fetchImpl);
+      emitMetric(session, pkt.contextId, "carrier.transfer.dispatched", String(res.status));
+      return;
+    }
+
+    const callControlId = options.getCallControlId();
+    if (!callControlId) {
+      emitMetric(session, pkt.contextId, "carrier.transfer.missing_call_handle", "telnyx");
+      return;
+    }
+    const command = buildTelnyxTransfer(callControlId, resolved, {
+      webhookUrl: options.webhookUrl,
+    });
+    emitMetric(
+      session,
+      pkt.contextId,
+      "carrier.transfer.built",
+      JSON.stringify({
+        carrier: "telnyx",
+        mode: command.mode,
+        target: command.json.to,
+        summary: command.summary ?? null,
+      }),
+    );
+    if (!options.credentials) {
+      emitMetric(session, pkt.contextId, "carrier.transfer.no_credentials", "telnyx");
+      return;
+    }
+    const res = await dispatchTelnyxCommand(options.credentials, command, options.fetchImpl);
+    emitMetric(session, pkt.contextId, "carrier.transfer.dispatched", String(res.status));
+  } catch (err) {
+    emitMetric(session, pkt.contextId, "carrier.transfer.error", err instanceof Error ? err.message : String(err));
+  }
+}
+
+function emitMetric(session: VoiceAgentSession, contextId: string, name: string, value: string): void {
+  session.bus.push(Route.Background, {
+    kind: "metric.conversation",
+    contextId,
+    timestampMs: Date.now(),
+    name,
+    value,
+  });
+}