@cloudflare/voice-telnyx 0.0.0 → 0.0.2

package/README.md

@@ -0,0 +1,160 @@
+# @cloudflare/voice-telnyx
+
+Telnyx voice providers for the Cloudflare Agents voice pipeline.
+
+This package includes:
+
+- **STT** — real-time speech-to-text via Telnyx's WebSocket transcription API.
+- **TTS** — text-to-speech via Telnyx REST and Workers WebSocket backends.
+- **Telephony** — Telnyx WebRTC/PSTN helpers for routing phone-call audio into a `@cloudflare/voice` agent.
+
+## Installation
+
+```bash
+npm install @cloudflare/voice @cloudflare/voice-telnyx
+```
+
+## Subpath imports
+
+The package root is server-safe and does not import browser WebRTC code. Use
+`/browser` only when you need the browser-side PSTN bridge:
+
+```ts
+import { TelnyxSTT } from "@cloudflare/voice-telnyx/stt";
+import { TelnyxTTS } from "@cloudflare/voice-telnyx/tts";
+import { TelnyxJWTEndpoint } from "@cloudflare/voice-telnyx";
+import { TelnyxCallBridge } from "@cloudflare/voice-telnyx/browser";
+```
+
+## Worker voice agent
+
+```ts
+import { Agent, routeAgentRequest } from "agents";
+import { withVoice, type VoiceTurnContext } from "@cloudflare/voice";
+import { TelnyxSTT } from "@cloudflare/voice-telnyx/stt";
+import { TelnyxTTS } from "@cloudflare/voice-telnyx/tts";
+
+const VoiceAgent = withVoice(Agent);
+
+export class MyVoiceAgent extends VoiceAgent<Env> {
+  transcriber = new TelnyxSTT({ apiKey: this.env.TELNYX_API_KEY });
+  tts = new TelnyxTTS({
+    apiKey: this.env.TELNYX_API_KEY,
+    voice: "Telnyx.NaturalHD.astra"
+  });
+
+  async onTurn(transcript: string, context: VoiceTurnContext) {
+    return `You said: ${transcript}`;
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    return (
+      (await routeAgentRequest(request, env)) ||
+      new Response("Not found", { status: 404 })
+    );
+  }
+};
+```
+
+## API
+
+### `TelnyxSTT`
+
+Implements `Transcriber` from `@cloudflare/voice`.
+
+```ts
+const stt = new TelnyxSTT({
+  apiKey: env.TELNYX_API_KEY,
+  engine: "Telnyx", // or "Deepgram"
+  language: "en",
+  transcriptionModel: "nova-3", // optional, useful with Deepgram engine
+  interimResults: true
+});
+```
+
+The Cloudflare voice pipeline feeds raw 16 kHz mono PCM16 audio. Telnyx STT expects a container, so the default `inputFormat: "wav"` prepends a WAV header before streaming audio chunks.
+
+### `TelnyxTTS`
+
+Implements `TTSProvider` and `StreamingTTSProvider` from `@cloudflare/voice`.
+
+```ts
+const tts = new TelnyxTTS({
+  apiKey: env.TELNYX_API_KEY,
+  voice: "Telnyx.NaturalHD.astra",
+  backend: "rest" // default; use "websocket" only in Workers runtime
+});
+```
+
+- `backend: "rest"` works anywhere and returns one complete audio buffer per sentence.
+- `backend: "websocket"` streams chunks with lower time-to-first-audio, but requires Cloudflare Workers' fetch-upgrade WebSocket pattern because authentication uses request headers.
+
+### Telephony / PSTN bridge
+
+Server-side token helpers are available from the package root. Browser-side
+WebRTC/PSTN helpers are exported from `@cloudflare/voice-telnyx/browser`.
+
+```ts
+import { TelnyxJWTEndpoint } from "@cloudflare/voice-telnyx";
+import {
+  createTelnyxVoiceConfig,
+  TelnyxPhoneClient
+} from "@cloudflare/voice-telnyx/browser";
+import { WebSocketVoiceTransport } from "@cloudflare/voice/client";
+```
+
+Create a server-side endpoint that keeps your Telnyx API key secret. The endpoint requires an `authorize` callback by default so a public route cannot mint Telnyx credentials for arbitrary clients:
+
+```ts
+const jwt = new TelnyxJWTEndpoint({
+  apiKey: env.TELNYX_API_KEY,
+  credentialConnectionId: env.TELNYX_CREDENTIAL_CONNECTION_ID,
+  allowedOrigins: ["https://your-app.example"],
+  authorize: async (request) => {
+    // Check your app session, signed token, or other auth state here.
+    return Boolean(request.headers.get("Authorization"));
+  }
+});
+
+return jwt.handleRequest(request);
+```
+
+Create a browser bridge and connect it with `TelnyxPhoneClient`:
+
+```ts
+const telnyx = await createTelnyxVoiceConfig({
+  jwtEndpoint: "/api/telnyx-token",
+  autoAnswer: true
+});
+
+const client = new TelnyxPhoneClient({
+  transport: new WebSocketVoiceTransport({ agent: "my-voice-agent" }),
+  bridge: telnyx.bridge
+});
+```
+
+`TelnyxPhoneClient` sends phone-call audio to the agent as PCM16. For playback,
+it routes PCM16 responses directly to the phone bridge and decodes formats such
+as MP3 in the browser before playback. If you use the lower-level
+`TelnyxPhoneTransport`, configure your server agent to send PCM16 audio because
+that transport does not decode non-PCM formats.
+
+## Environment variables
+
+| Variable                          | Required       | Description                                                                   |
+| --------------------------------- | -------------- | ----------------------------------------------------------------------------- |
+| `TELNYX_API_KEY`                  | Yes            | Telnyx API key. Store as a Worker secret.                                     |
+| `TELNYX_CREDENTIAL_CONNECTION_ID` | Telephony only | Credential connection ID used by `TelnyxJWTEndpoint` for WebRTC login tokens. |
+
+Set secrets with Wrangler:
+
+```bash
+wrangler secret put TELNYX_API_KEY
+wrangler secret put TELNYX_CREDENTIAL_CONNECTION_ID
+```
+
+## Attribution
+
+This package is adapted from Telnyx's `@telnyx/voice-cloudflare` implementation, whose npm package metadata declares the MIT license.

package/dist/browser.d.ts

@@ -0,0 +1,304 @@
+import {
+  TranscriptMessage,
+  VoiceAudioFormat,
+  VoiceAudioInput,
+  VoicePipelineMetrics,
+  VoiceStatus,
+  VoiceTransport
+} from "@cloudflare/voice/client";
+
+//#region src/providers/call-bridge.d.ts
+/**
+ * Configuration for the TelnyxCallBridge.
+ *
+ * Uses JWT authentication (browser-side). The JWT is generated
+ * server-side from a Telnyx API key + credential connection.
+ */
+interface TelnyxCallBridgeConfig {
+  /** JWT token from the Telnyx telephony credentials API. */
+  loginToken: string;
+  /** Automatically answer inbound calls. @default false */
+  autoAnswer?: boolean;
+  /** Enable debug logging. @default false */
+  debug?: boolean;
+}
+/**
+ * Bridges Telnyx phone calls into the Cloudflare voice pipeline.
+ *
+ * Implements `VoiceAudioInput` from @cloudflare/voice — extracts PCM
+ * audio from inbound phone calls and feeds it to the AI pipeline.
+ * Also provides `playAudio()` for injecting response audio back
+ * into the phone call.
+ *
+ * Usage:
+ * ```typescript
+ * const bridge = new TelnyxCallBridge({ loginToken: jwt });
+ * const voiceClient = new VoiceClient({
+ *   agent: "my-agent",
+ *   audioInput: bridge,
+ * });
+ * ```
+ */
+declare class TelnyxCallBridge implements VoiceAudioInput {
+  onAudioLevel: ((rms: number) => void) | null;
+  onAudioData?: ((pcm: ArrayBuffer) => void) | null;
+  private readonly config;
+  private _connected;
+  private _activeCall;
+  private client;
+  private captureContext;
+  private captureSource;
+  private captureWorklet;
+  private captureBlobUrl;
+  private captureAudioEl;
+  private statsInterval;
+  private playbackContext;
+  private playbackWorklet;
+  private playbackBlobUrl;
+  private startPromise;
+  private finishStart;
+  private startAttempt;
+  private mediaSetupAttempt;
+  constructor(config: TelnyxCallBridgeConfig);
+  /** Whether the Telnyx client is connected to the platform. */
+  get connected(): boolean;
+  /** The currently active Telnyx call, or null. */
+  get activeCall(): unknown | null;
+  /** Connect to Telnyx and start listening for calls. */
+  start(): Promise<void>;
+  /** Answer the current inbound call. */
+  answer(): void;
+  /** End the active call. */
+  hangup(): void;
+  /**
+   * Initiate an outbound PSTN call.
+   * @param destination Phone number or SIP URI to call.
+   * @param callerNumber The caller ID number to present.
+   * @returns The Telnyx Call object.
+   */
+  dial(destination: string, callerNumber?: string): unknown;
+  /** Send DTMF digits on the active call. */
+  sendDTMF(digits: string): void;
+  /**
+   * Clear any buffered audio in the playback pipeline.
+   * Used during interrupt detection to stop stale audio from playing.
+   */
+  clearPlaybackBuffer(): void;
+  /**
+   * Inject PCM audio into the active phone call (agent → caller).
+   * Accepts 16kHz mono Int16 PCM. Upsamples to 48kHz for WebRTC.
+   * No-op if no active call.
+   */
+  playAudio(pcm: ArrayBuffer): void;
+  /** Disconnect from Telnyx and clean up all resources. */
+  stop(): void;
+  private handleNotification;
+  private isCurrentMediaSetup;
+  private cleanupCaptureResources;
+  private cleanupPlaybackResources;
+  private startAudioCapture;
+  private monitorInboundStats;
+  private stopAudioCapture;
+  private startAudioPlayback;
+  private stopAudioPlayback;
+}
+//#endregion
+//#region src/phone-client.d.ts
+interface TelnyxPhoneClientConfig {
+  /** The transport for server communication (e.g. WebSocketVoiceTransport). */
+  transport: VoiceTransport;
+  /** The call bridge for PSTN audio I/O. */
+  bridge: TelnyxCallBridge;
+  /**
+   * Preferred audio format sent to the server in `start_call`.
+   * Must be `"pcm16"` for TelnyxCallBridge compatibility.
+   * @default "pcm16"
+   */
+  preferredFormat?: VoiceAudioFormat;
+  /** RMS threshold below which audio is considered silence. @default 0.04 */
+  silenceThreshold?: number;
+  /** How long silence must last before sending end_of_speech (ms). @default 500 */
+  silenceDurationMs?: number;
+  /** RMS threshold for detecting user speech during agent playback. @default 0.05 */
+  interruptThreshold?: number;
+  /** Consecutive high-RMS chunks needed to trigger an interrupt. @default 2 */
+  interruptChunks?: number;
+  /** Maximum transcript messages to keep in memory. @default 200 */
+  maxTranscriptMessages?: number;
+}
+interface TelnyxPhoneClientEventMap {
+  statuschange: VoiceStatus;
+  transcriptchange: TranscriptMessage[];
+  interimtranscript: string | null;
+  metricschange: VoicePipelineMetrics | null;
+  audiolevelchange: number;
+  connectionchange: boolean;
+  error: string | null;
+  mutechange: boolean;
+  custommessage: unknown;
+}
+type TelnyxPhoneClientEvent = keyof TelnyxPhoneClientEventMap;
+declare class TelnyxPhoneClient {
+  private _status;
+  private _transcript;
+  private _metrics;
+  private _audioLevel;
+  private _isMuted;
+  private _connected;
+  private _error;
+  private _interimTranscript;
+  private _lastCustomMessage;
+  private _audioFormat;
+  private _serverProtocolVersion;
+  private inCall;
+  private isPlaying;
+  private isSpeaking;
+  private silenceTimer;
+  private interruptChunkCount;
+  private warnedFormat;
+  private listeners;
+  private transport;
+  private bridge;
+  private preferredFormat;
+  private silenceThreshold;
+  private silenceDurationMs;
+  private interruptThreshold;
+  private interruptChunks;
+  private maxTranscriptMessages;
+  constructor(config: TelnyxPhoneClientConfig);
+  get status(): VoiceStatus;
+  get transcript(): TranscriptMessage[];
+  get metrics(): VoicePipelineMetrics | null;
+  get audioLevel(): number;
+  get isMuted(): boolean;
+  get connected(): boolean;
+  get error(): string | null;
+  get interimTranscript(): string | null;
+  get lastCustomMessage(): unknown;
+  get audioFormat(): VoiceAudioFormat | null;
+  get serverProtocolVersion(): number | null;
+  addEventListener<K extends TelnyxPhoneClientEvent>(
+    event: K,
+    listener: (data: TelnyxPhoneClientEventMap[K]) => void
+  ): void;
+  removeEventListener<K extends TelnyxPhoneClientEvent>(
+    event: K,
+    listener: (data: TelnyxPhoneClientEventMap[K]) => void
+  ): void;
+  private emit;
+  /** Open the transport connection and send the protocol handshake. */
+  connect(): void;
+  /** End any active call, then close the transport. */
+  disconnect(): void;
+  /**
+   * Start a voice call. Wires up the bridge audio callbacks,
+   * starts the bridge, and sends `start_call` to the server.
+   *
+   * The bridge's `start()` is called here — do not call it separately.
+   */
+  startCall(): Promise<void>;
+  /**
+   * End the voice call. Detaches audio callbacks from the bridge
+   * and sends `end_call` to the server.
+   *
+   * Does NOT stop the bridge or hang up the phone — call
+   * `bridge.stop()` or `cleanup()` separately for that.
+   */
+  endCall(): void;
+  /** Toggle mute. When muted, audio is not sent to the server. */
+  toggleMute(): void;
+  /** Send a text message to the agent (bypasses STT, goes to onTurn). */
+  sendText(text: string): void;
+  /** Send arbitrary JSON to the agent (app-level messages). */
+  sendJSON(data: Record<string, unknown>): void;
+  private createStartCallMessage;
+  private handleJSON;
+  private handleAudio;
+  private decodeContext;
+  private decodeAndPlay;
+  private processAudioLevel;
+  private resetDetection;
+  private trimTranscript;
+}
+//#endregion
+//#region src/transport/phone-transport.d.ts
+interface TelnyxPhoneTransportConfig {
+  /**
+   * The underlying transport to wrap. Typically a `WebSocketVoiceTransport`
+   * from @cloudflare/voice/client.
+   */
+  inner: VoiceTransport;
+  /** The call bridge to route audio into. */
+  bridge: TelnyxCallBridge;
+  /**
+   * Optional callback for every binary audio frame received from the server.
+   * Called with the raw ArrayBuffer regardless of format.
+   */
+  onServerAudio?: (audio: ArrayBuffer) => void;
+}
+declare class TelnyxPhoneTransport implements VoiceTransport {
+  private inner;
+  private bridge;
+  private audioFormat;
+  private warnedFormat;
+  private userAudioCallback?;
+  onopen: (() => void) | null;
+  onclose: (() => void) | null;
+  onerror: ((error?: unknown) => void) | null;
+  onmessage: ((data: string | ArrayBuffer | Blob) => void) | null;
+  constructor(config: TelnyxPhoneTransportConfig);
+  get connected(): boolean;
+  sendJSON(data: Record<string, unknown>): void;
+  sendBinary(data: ArrayBuffer): void;
+  connect(): void;
+  disconnect(): void;
+  private intercept;
+  /** Parse audio_config messages to know what format the server is sending. */
+  private trackAudioConfig;
+  /** Fork audio to the bridge (pcm16 only) and optional user callback. */
+  private routeAudio;
+}
+//#endregion
+//#region src/helpers/transport-config.d.ts
+interface TelnyxVoiceConfigOptions {
+  /** URL of the JWT endpoint (the TelnyxJWTEndpoint handler). */
+  jwtEndpoint: string;
+  /** Automatically answer inbound calls. @default false */
+  autoAnswer?: boolean;
+  /** Enable Telnyx SDK debug logging. @default false */
+  debug?: boolean;
+}
+interface TelnyxVoiceSetup {
+  /** The TelnyxCallBridge instance — use for playAudio(), dial(), hangup(), etc. */
+  bridge: TelnyxCallBridge;
+  /** Pass this to VoiceClientOptions.audioInput. Same as `bridge`. */
+  audioInput: TelnyxCallBridge;
+  /** The server-side credential ID (for manual cleanup if needed). */
+  credentialId: string;
+  /** The SIP username (e.g. "genCredXYZ123") — call this to reach the agent. */
+  sipUsername: string;
+  /** Stop the bridge and revoke the server-side credential. */
+  cleanup: () => Promise<void>;
+}
+/**
+ * Fetch a JWT from the server, create a TelnyxCallBridge, and return
+ * everything needed to configure a VoiceClient for phone calls.
+ */
+declare function createTelnyxVoiceConfig(
+  options: TelnyxVoiceConfigOptions
+): Promise<TelnyxVoiceSetup>;
+//#endregion
+export {
+  TelnyxCallBridge,
+  type TelnyxCallBridgeConfig,
+  TelnyxPhoneClient,
+  type TelnyxPhoneClientConfig,
+  type TelnyxPhoneClientEvent,
+  type TelnyxPhoneClientEventMap,
+  TelnyxPhoneTransport,
+  type TelnyxPhoneTransportConfig,
+  type TelnyxVoiceConfigOptions,
+  type TelnyxVoiceSetup,
+  createTelnyxVoiceConfig
+};
+//# sourceMappingURL=browser.d.ts.map