telnyx 6.41.0 → 6.42.0

package/src/lib/text-to-speech-ws-internal.ts

@@ -0,0 +1,111 @@
+import * as TextToSpeechAPI from '../resources/text-to-speech/text-to-speech';
+import { Telnyx } from '../client';
+import { EventEmitter } from '../core/EventEmitter';
+import { TelnyxError } from '../core/error';
+
+import type { RawWebSocketData, ReconnectingEvent, UnsentMessage } from '../internal/ws';
+
+export type TextToSpeechStreamMessage =
+  | { type: 'connecting' | 'open' | 'closing' }
+  | {
+      type: 'close';
+      code: number;
+      reason: string;
+      unsent: UnsentMessage<TextToSpeechAPI.StreamClientEvent>[];
+    }
+  | { type: 'reconnecting'; reconnect: ReconnectingEvent }
+  | { type: 'reconnected' }
+  | { type: 'message'; message: TextToSpeechAPI.StreamServerEvent }
+  | { type: 'raw'; data: RawWebSocketData }
+  | { type: 'error'; error: WebSocketError };
+
+export class WebSocketError extends TelnyxError {
+  /**
+   * The error data that the API sent back in an error event.
+   */
+  error?: TextToSpeechAPI.StreamServerEvent.ErrorFrame | undefined;
+
+  constructor(message: string, event: TextToSpeechAPI.StreamServerEvent.ErrorFrame | null) {
+    super(message);
+
+    this.error = event ?? undefined;
+  }
+}
+
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+
+type WebSocketEvents = Simplify<
+  {
+    event: (event: TextToSpeechAPI.StreamServerEvent) => void;
+    raw: (data: RawWebSocketData) => void;
+    error: (error: WebSocketError) => void;
+    close: (code: number, reason: string, unsent: UnsentMessage<TextToSpeechAPI.StreamClientEvent>[]) => void;
+    reconnecting: (event: ReconnectingEvent) => void;
+    reconnected: () => void;
+  } & {
+    [EventType in Exclude<NonNullable<TextToSpeechAPI.StreamServerEvent['type']>, 'error'>]: (
+      event: Extract<TextToSpeechAPI.StreamServerEvent, { type?: EventType }>,
+    ) => unknown;
+  }
+>;
+
+export abstract class TextToSpeechEmitter extends EventEmitter<WebSocketEvents> {
+  /**
+   * Send an event to the API.
+   */
+  abstract send(event: TextToSpeechAPI.StreamClientEvent): void;
+
+  /**
+   * Send raw data over the WebSocket without JSON serialization.
+   */
+  abstract sendRaw(data: RawWebSocketData): void;
+
+  /**
+   * Close the WebSocket connection.
+   */
+  abstract close(props?: { code: number; reason: string }): void;
+
+  protected _onError(event: null, message: string, cause: any): void;
+  protected _onError(event: TextToSpeechAPI.StreamServerEvent.ErrorFrame, message?: string | undefined): void;
+  protected _onError(
+    event: TextToSpeechAPI.StreamServerEvent.ErrorFrame | null,
+    message?: string | undefined,
+    cause?: any,
+  ): void {
+    message = message ?? safeJSONStringify(event) ?? 'unknown error';
+
+    if (!this._hasListener('error')) {
+      const error = new WebSocketError(
+        message +
+          `\n\nTo resolve these unhandled rejection errors you should bind an \`error\` callback, e.g. \`ws.on('error', (error) => ...)\` `,
+        event,
+      );
+      // @ts-ignore
+      error.cause = cause;
+      Promise.reject(error);
+      return;
+    }
+
+    const error = new WebSocketError(message, event);
+    // @ts-ignore
+    error.cause = cause;
+
+    this._emit('error', error);
+  }
+}
+
+export function buildURL(client: Telnyx, parameters: Record<string, unknown>): URL {
+  const { ...query } = parameters;
+  const endpoint = '/text-to-speech/speech';
+  const url = new URL(client.buildURL(endpoint, query, undefined));
+  url.protocol = url.protocol === 'http:' || url.protocol === 'ws:' ? 'ws:' : 'wss:';
+  return url;
+}
+
+function safeJSONStringify(value: unknown): string | null {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return null;
+  }
+}

package/src/lib/text-to-speech-ws.ts

@@ -0,0 +1,40 @@
+import * as WS from 'ws';
+import { NodeWebSocket } from '../internal/ws-adapter-node';
+import { TextToSpeechWSBase, type TextToSpeechWSBaseOptions } from './text-to-speech-ws-base';
+import { Telnyx } from '../client';
+
+export type { TextToSpeechWSReconnectOptions } from './text-to-speech-ws-base';
+
+export interface TextToSpeechWSClientOptions extends WS.ClientOptions, TextToSpeechWSBaseOptions {}
+
+export class TextToSpeechWS extends TextToSpeechWSBase<NodeWebSocket> {
+  private _wsOptions: WS.ClientOptions | null | undefined;
+
+  constructor(
+    client: Telnyx,
+    parameters?: Record<string, unknown> | undefined,
+    options?: TextToSpeechWSClientOptions | null | undefined,
+  ) {
+    if (!WS?.WebSocket) {
+      throw new Error(
+        'TextToSpeechWS from "telnyx/resources/text-to-speech/ws" requires the "ws" package but it could not be loaded.',
+      );
+    }
+
+    const { reconnect, maxQueueSize, ...wsOptions } = options ?? {};
+    super(client, parameters, { reconnect, maxQueueSize });
+    this._wsOptions = wsOptions;
+    this._connectInitial();
+  }
+
+  protected _createSocket(url: URL, authHeaders: Record<string, string>): NodeWebSocket {
+    const ws = new WS.WebSocket(url, {
+      ...this._wsOptions,
+      headers: {
+        ...authHeaders,
+        ...this._wsOptions?.headers,
+      },
+    });
+    return new NodeWebSocket(ws);
+  }
+}

package/src/lib/webhooks.ts

@@ -30,6 +30,33 @@ export class TelnyxWebhookVerificationError extends TelnyxError {
   }
 }
 
+export interface WebhookUnwrapOptions {
+  headers?: Record<string, string>;
+  key?: string | Uint8Array;
+}
+
+export function unsafeUnwrapWebhook<T>(body: string): T {
+  return JSON.parse(body) as T;
+}
+
+export async function unwrapWebhook<T>(
+  body: string,
+  options: WebhookUnwrapOptions | undefined,
+  clientPublicKey: string | null,
+): Promise<T> {
+  if (options?.headers) {
+    const key = options.key || clientPublicKey;
+    if (!key) {
+      throw new TelnyxWebhookVerificationError('No public key provided for webhook verification');
+    }
+
+    const webhook = new TelnyxWebhook(key);
+    await webhook.verify(body, options.headers);
+  }
+
+  return unsafeUnwrapWebhook<T>(body);
+}
+
 // Type for the SubtleCrypto interface we need
 // Using unknown for key type to avoid CryptoKey dependency
 interface SubtleCryptoLike {