telnyx 5.66.0 → 5.67.0

data/lib/telnyx/lib/websocket/text_to_speech_stream_params.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Lib
+    module WebSocket
+      # Parameters for configuring Text-to-Speech WebSocket streaming.
+      #
+      # These parameters are passed as query string parameters when
+      # establishing the WebSocket connection.
+      #
+      # Example usage:
+      #
+      #   params = TextToSpeechStreamParams.new(
+      #     voice: "telnyx.NaturalHD.Alloy",
+      #     output_format: "mp3"
+      #   )
+      #   url = params.to_query_string
+      #
+      class TextToSpeechStreamParams
+        # @return [String, nil] The voice to use (e.g., "telnyx.NaturalHD.Alloy")
+        attr_accessor :voice
+
+        # @return [String, nil] The audio output format (e.g., "mp3", "pcm", "wav")
+        attr_accessor :output_format
+
+        # @return [Integer, nil] Sample rate in Hz (e.g., 22050, 24000)
+        attr_accessor :sample_rate
+
+        # @return [String, nil] Language code (e.g., "en-US")
+        attr_accessor :language
+
+        # @return [Float, nil] Speaking rate/speed multiplier (0.5 to 2.0)
+        attr_accessor :speed
+
+        # @return [Float, nil] Pitch adjustment (-20.0 to 20.0)
+        attr_accessor :pitch
+
+        # @return [String, nil] TTS model to use
+        attr_accessor :model
+
+        # @return [String, nil] Client reference identifier
+        attr_accessor :client_ref
+
+        # Create params from a hash
+        #
+        # @param options [Hash] The parameter options
+        # @return [TextToSpeechStreamParams]
+        def self.from_hash(options)
+          params = new
+          params.voice = options[:voice] || options["voice"]
+          params.output_format = options[:output_format] || options["output_format"]
+          params.sample_rate = options[:sample_rate] || options["sample_rate"]
+          params.language = options[:language] || options["language"]
+          params.speed = options[:speed] || options["speed"]
+          params.pitch = options[:pitch] || options["pitch"]
+          params.model = options[:model] || options["model"]
+          params.client_ref = options[:client_ref] || options["client_ref"]
+          params
+        end
+
+        # Convert to a hash for URL encoding
+        #
+        # @return [Hash] The params as a hash with string keys
+        def to_hash
+          hash = {}
+          hash["voice"] = voice if voice
+          hash["output_format"] = output_format if output_format
+          hash["sample_rate"] = sample_rate.to_s if sample_rate
+          hash["language"] = language if language
+          hash["speed"] = speed.to_s if speed
+          hash["pitch"] = pitch.to_s if pitch
+          hash["model"] = model if model
+          hash["client_ref"] = client_ref if client_ref
+          hash
+        end
+
+        # Convert to URL query string
+        #
+        # @return [String]
+        def to_query_string
+          require("cgi")
+          to_hash.map { |k, v| "#{CGI.escape(k)}=#{CGI.escape(v.to_s)}" }.join("&")
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/lib/websocket/text_to_speech_ws.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+require_relative "tts_server_event"
+require_relative "text_to_speech_stream_params"
+require_relative "websocket_error"
+
+module Telnyx
+  module Lib
+    module WebSocket
+      # WebSocket stream message types for async iteration.
+      #
+      # @api private
+      StreamMessage = Struct.new(:type, :message, :error)
+
+      # WebSocket client for Text-to-Speech (TTS) streaming synthesis.
+      #
+      # This client establishes a WebSocket connection to the Telnyx TTS API
+      # for real-time speech synthesis. Text input events are sent as JSON
+      # and audio chunks are received as events.
+      #
+      # Example usage with event callbacks:
+      #
+      #   client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])
+      #
+      #   ws = Telnyx::Lib::WebSocket::TextToSpeechWS.new(client, {
+      #     voice: "telnyx.NaturalHD.Alloy"
+      #   })
+      #
+      #   ws.on(:audio_chunk) do |event|
+      #     audio = event.decode_audio
+      #     # Process audio chunk
+      #   end
+      #
+      #   ws.on(:final) do |event|
+      #     puts "Synthesis complete"
+      #   end
+      #
+      #   ws.wait_for_open
+      #   ws.send({ type: "text", text: "Hello, world!" })
+      #   ws.send({ type: "flush" })
+      #
+      # Example usage with Enumerable pattern:
+      #
+      #   ws.each do |msg|
+      #     case msg.type
+      #     when :message
+      #       event = msg.message
+      #       if event.audio_chunk?
+      #         # Process audio
+      #       end
+      #     when :error
+      #       puts "Error: #{msg.error.message}"
+      #     when :close
+      #       break
+      #     end
+      #   end
+      #
+      class TextToSpeechWS < Base
+        include Enumerable
+
+        # The WebSocket API path for TTS
+        API_PATH = "/v2/text-to-speech/speech"
+
+        # @return [Telnyx::Client] The Telnyx client
+        attr_reader :client
+
+        # @return [TextToSpeechStreamParams, nil] The stream parameters
+        attr_reader :params
+
+        # Create a new TTS WebSocket connection.
+        #
+        # @param client [Telnyx::Client] The Telnyx client
+        # @param params [Hash, TextToSpeechStreamParams, nil] Stream configuration parameters
+        # @param options [Hash] Additional WebSocket options
+        # @option options [Hash] :headers Additional HTTP headers
+        def initialize(client, params = nil, options = {})
+          super()
+          @client = client
+          @params = normalize_params(params)
+          @options = options
+          @stream_queue = nil # Will be a ::Queue
+          @streaming = false
+
+          @url = build_url(client, API_PATH, @params&.to_hash)
+          connect
+        end
+
+        # Send a text input event to the server for synthesis.
+        #
+        # @param event [Hash] The event to send
+        # @option event [String] :type Event type ("text", "flush", "close")
+        # @option event [String] :text The text to synthesize (for type: "text")
+        # @return [void]
+        # @raise [WebSocketError] If send fails
+        #
+        # Event types:
+        # - { type: "text", text: "Hello" } - Add text to synthesize
+        # - { type: "flush" } - Flush buffered text and generate audio
+        # - { type: "close" } - Signal end of input
+        def send(event)
+          unless open?
+            raise WebSocketError.new("Cannot send: WebSocket is not open")
+          end
+
+          begin
+            json_data = event.is_a?(String) ? event : JSON.generate(event)
+            @socket.send(json_data, type: :text)
+          rescue StandardError => e
+            emit_error(nil, "could not send data", e)
+          end
+        end
+
+        # Iterate over WebSocket events using the Enumerable pattern.
+        #
+        # This provides an alternative to the callback-based `.on()` API.
+        # The iterator yields StreamMessage structs with :type, :message, and :error.
+        #
+        # @yield [StreamMessage] Each event as a StreamMessage
+        # @yieldparam msg [StreamMessage] The stream message
+        # @yieldparam msg.type [Symbol] One of :connecting, :open, :closing, :close, :message, :error
+        # @yieldparam msg.message [TtsServerEvent, nil] The parsed event (for :message type)
+        # @yieldparam msg.error [WebSocketError, nil] The error (for :error type)
+        # @return [Enumerator] If no block given
+        #
+        # Example:
+        #
+        #   ws.each do |msg|
+        #     case msg.type
+        #     when :message
+        #       puts msg.message.type
+        #     when :close
+        #       break
+        #     end
+        #   end
+        # rubocop:disable Lint/UnusedMethodArgument
+        def each(&block)
+          return to_enum(:each) unless block_given?
+          # rubocop:enable Lint/UnusedMethodArgument
+
+          @stream_queue = ::Queue.new
+          @streaming = true
+
+          # Set up event forwarding
+          setup_streaming
+
+          # Yield initial state
+          case @ready_state
+          when CONNECTING
+            yield(StreamMessage.new(type: :connecting))
+          when OPEN
+            yield(StreamMessage.new(type: :open))
+          when CLOSING
+            yield(StreamMessage.new(type: :closing))
+          when CLOSED
+            yield(StreamMessage.new(type: :close))
+            return
+          end
+
+          # Process events from the queue
+          loop do
+            msg = @stream_queue.pop
+            break if msg.nil? || (msg.type == :close)
+
+            yield(msg)
+
+            break if msg.type == :close
+          end
+        ensure
+          @streaming = false
+          @stream_queue = nil
+        end
+
+        # Alias for each - provides async iterator semantics
+        #
+        # @return [Enumerator]
+        def stream
+          each
+        end
+
+        private
+
+        def normalize_params(params)
+          case params
+          when nil
+            nil
+          when TextToSpeechStreamParams
+            params
+          when Hash
+            TextToSpeechStreamParams.from_hash(params)
+          else
+            raise ArgumentError, "params must be a Hash or TextToSpeechStreamParams"
+          end
+        end
+
+        def connect
+          require("websocket-client-simple")
+
+          headers = auth_headers(@client).merge(@options[:headers] || {})
+
+          ws_self = self
+          @socket = ::WebSocket::Client::Simple.connect(@url.to_s, headers: headers)
+
+          @socket.on(:open) do
+            ws_self.send(:handle_open)
+          end
+
+          @socket.on(:message) do |msg|
+            ws_self.send(:handle_message, msg)
+          end
+
+          @socket.on(:error) do |e|
+            ws_self.send(:handle_socket_error, e)
+          end
+
+          @socket.on(:close) do |e|
+            code = begin
+              e&.code
+            rescue StandardError
+              nil
+            end
+            reason = begin
+              e&.reason
+            rescue StandardError
+              nil
+            end
+            ws_self.send(:handle_close, code, reason)
+          end
+        end
+
+        def handle_open
+          mark_open
+          push_stream_message(StreamMessage.new(type: :open)) if @streaming
+        end
+
+        def handle_message(msg)
+          # Parse the JSON message
+          event = parse_event(msg)
+          return unless event
+
+          # Emit generic event
+          emit(:event, event)
+
+          # Push to stream queue if streaming
+          push_stream_message(StreamMessage.new(type: :message, message: event)) if @streaming
+
+          # Emit type-specific event
+          if event.error?
+            error = WebSocketError.new(event.error || "Server error", error: event.raw)
+            emit(:error, error)
+            push_stream_message(StreamMessage.new(type: :error, error: error)) if @streaming
+          elsif event.type
+            emit(event.type.to_sym, event)
+          end
+        end
+
+        def parse_event(msg)
+          data = JSON.parse(msg.data)
+          TtsServerEvent.from_hash(data)
+        rescue JSON::ParserError => e
+          emit_error(nil, "could not parse websocket event", e)
+          nil
+        end
+
+        def handle_socket_error(e)
+          emit_error(nil, e.message, e)
+          return unless @streaming
+          error = WebSocketError.new(e.message, cause: e)
+          push_stream_message(StreamMessage.new(type: :error, error: error))
+        end
+
+        def handle_close(code, reason)
+          mark_closed(code, reason)
+          push_stream_message(StreamMessage.new(type: :close)) if @streaming
+        end
+
+        def push_stream_message(msg)
+          @stream_queue&.push(msg)
+        end
+
+        def setup_streaming
+          # The streaming is already set up via handle_* methods
+          # This method exists for potential future enhancements
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/lib/websocket/tts_server_event.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Lib
+    module WebSocket
+      # Server event types for Text-to-Speech WebSocket streaming.
+      #
+      # These events are received from the Telnyx TTS WebSocket API
+      # during real-time speech synthesis.
+      #
+      # Example usage:
+      #
+      #   ws.on(:audio_chunk) do |event|
+      #     audio_data = Base64.decode64(event.audio)
+      #     # Process audio chunk
+      #   end
+      #
+      #   ws.on(:final) do |event|
+      #     puts "Stream complete"
+      #   end
+      #
+      class TtsServerEvent
+        # @return [String] The event type ("audio_chunk", "final", or "error")
+        attr_accessor :type
+
+        # @return [String, nil] Base64-encoded audio data
+        attr_accessor :audio
+
+        # @return [String, nil] The text being synthesized
+        attr_accessor :text
+
+        # @return [Boolean, nil] Whether this is the final event
+        attr_accessor :is_final
+
+        # @return [Boolean, nil] Whether the response was served from cache
+        attr_accessor :cached
+
+        # @return [Integer, nil] Time in milliseconds to first audio frame
+        attr_accessor :time_to_first_audio_frame_ms
+
+        # @return [String, nil] Error message if type is "error"
+        attr_accessor :error
+
+        # @return [String, nil] Audio encoding format (e.g., "mp3", "pcm")
+        attr_accessor :encoding
+
+        # @return [Integer, nil] Sample rate in Hz
+        attr_accessor :sample_rate
+
+        # @return [Integer, nil] Sequence number for ordering
+        attr_accessor :sequence
+
+        # @return [Hash, nil] Original raw event data
+        attr_accessor :raw
+
+        # Create a TtsServerEvent from a parsed JSON hash
+        #
+        # @param data [Hash] The parsed JSON event data
+        # @return [TtsServerEvent]
+        def self.from_hash(data)
+          event = new
+          event.raw = data
+          event.type = data["type"]
+          event.audio = data["audio"]
+          event.text = data["text"]
+          event.is_final = data["is_final"]
+          event.cached = data["cached"]
+          event.time_to_first_audio_frame_ms = data["time_to_first_audio_frame_ms"]
+          event.error = data["error"]
+          event.encoding = data["encoding"]
+          event.sample_rate = data["sample_rate"]
+          event.sequence = data["sequence"]
+          event
+        end
+
+        # Check if this is the final event
+        #
+        # @return [Boolean]
+        def final?
+          type == "final" || is_final == true
+        end
+
+        # Check if this is an error event
+        #
+        # @return [Boolean]
+        def error?
+          type == "error"
+        end
+
+        # Check if this is an audio chunk
+        #
+        # @return [Boolean]
+        def audio_chunk?
+          type == "audio_chunk"
+        end
+
+        # Decode the audio data from Base64
+        #
+        # @return [String, nil] Raw audio bytes, or nil if no audio data
+        def decode_audio
+          return nil unless audio
+          require("base64")
+          Base64.decode64(audio)
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/lib/websocket/websocket_error.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Lib
+    module WebSocket
+      # Error class for WebSocket-related errors in STT/TTS streaming.
+      #
+      # This error is raised when WebSocket connections encounter issues,
+      # including connection failures, message parsing errors, and
+      # server-side error events.
+      #
+      # Example usage:
+      #
+      #   ws.on(:error) do |error|
+      #     puts "WebSocket error: #{error.message}"
+      #     puts "Server error: #{error.error}" if error.error
+      #   end
+      #
+      class WebSocketError < Telnyx::Errors::Error
+        # @return [Hash, nil] The error data sent by the server in an error event
+        attr_reader :error
+
+        # @return [StandardError, nil] The underlying cause of this error
+        attr_reader :cause
+
+        # @api private
+        #
+        # @param message [String] Human-readable error message
+        # @param error [Hash, nil] Server error event data
+        # @param cause [StandardError, nil] The underlying exception that caused this error
+        def initialize(message, error: nil, cause: nil)
+          @error = error
+          @cause = cause
+          super(message)
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/lib/websocket.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# WebSocket support for Telnyx Speech-to-Text (STT) and Text-to-Speech (TTS) streaming.
+#
+# This module provides WebSocket clients for real-time audio transcription
+# and speech synthesis using the Telnyx API.
+#
+# Example - Speech-to-Text:
+#
+#   require "telnyx"
+#   require "telnyx/lib/websocket"
+#
+#   client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])
+#
+#   ws = Telnyx::Lib::WebSocket::SpeechToTextWS.new(client, {
+#     transcription_engine: "Deepgram",
+#     language: "en-US"
+#   })
+#
+#   ws.on(:transcript) do |event|
+#     puts event.transcript if event.is_final
+#   end
+#
+#   ws.wait_for_open
+#   ws.send(audio_data)
+#   ws.close
+#
+# Example - Text-to-Speech:
+#
+#   ws = Telnyx::Lib::WebSocket::TextToSpeechWS.new(client, {
+#     voice: "telnyx.NaturalHD.Alloy"
+#   })
+#
+#   ws.each do |msg|
+#     case msg.type
+#     when :message
+#       audio = msg.message.decode_audio if msg.message.audio_chunk?
+#     when :close
+#       break
+#     end
+#   end
+#
+
+require_relative "websocket/websocket_error"
+require_relative "websocket/stt_server_event"
+require_relative "websocket/tts_server_event"
+require_relative "websocket/speech_to_text_stream_params"
+require_relative "websocket/text_to_speech_stream_params"
+require_relative "websocket/base"
+require_relative "websocket/speech_to_text_ws"
+require_relative "websocket/text_to_speech_ws"

data/lib/telnyx/resources/terms_of_service/number_reputation.rb

@@ -21,7 +21,7 @@ module Telnyx
         def agree(params = {})
           @client.request(
             method: :post,
-            path: "terms-of-service/number-reputation/agree",
+            path: "terms_of_service/number_reputation/agree",
             model: NilClass,
             options: params[:request_options]
           )

data/lib/telnyx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Telnyx
-  VERSION = "5.66.0"
+  VERSION = "5.67.0"
 end

data/rbi/telnyx/lib/websocket/speech_to_text_stream_params.rbi

@@ -0,0 +1,55 @@
+# typed: strong
+
+module Telnyx
+  module Lib
+    module WebSocket
+      class SpeechToTextStreamParams
+        sig { returns(String) }
+        attr_accessor :transcription_engine
+
+        sig { returns(String) }
+        attr_accessor :input_format
+
+        sig { returns(String) }
+        attr_accessor :language
+
+        sig { returns(T.nilable(Integer)) }
+        attr_accessor :sample_rate
+
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :interim_results
+
+        sig { returns(T.nilable(String)) }
+        attr_accessor :client_ref
+
+        sig do
+          params(
+            transcription_engine: String,
+            input_format: String,
+            language: String,
+            sample_rate: T.nilable(Integer),
+            interim_results: T.nilable(T::Boolean),
+            client_ref: T.nilable(String)
+          ).void
+        end
+        def initialize(
+          transcription_engine: "Deepgram",
+          input_format: "wav",
+          language: "en-US",
+          sample_rate: nil,
+          interim_results: nil,
+          client_ref: nil
+        )
+        end
+
+        sig { returns(T::Hash[String, String]) }
+        def to_query_params
+        end
+
+        sig { returns(String) }
+        def to_query_string
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/lib/websocket/speech_to_text_ws.rbi

@@ -0,0 +1,43 @@
+# typed: strong
+
+module Telnyx
+  module Lib
+    module WebSocket
+      class SpeechToTextWS
+        sig { returns(Telnyx::Client) }
+        attr_reader :client
+
+        sig { returns(SpeechToTextStreamParams) }
+        attr_reader :params
+
+        sig { returns(T::Boolean) }
+        attr_reader :connected
+
+        sig do
+          params(
+            client: Telnyx::Client,
+            params: SpeechToTextStreamParams
+          ).void
+        end
+        def initialize(client, params)
+        end
+
+        sig { params(timeout: Integer).void }
+        def wait_for_open(timeout: 30)
+        end
+
+        sig { params(audio_data: String).void }
+        def send(audio_data)
+        end
+
+        sig { void }
+        def close
+        end
+
+        sig { params(event: String, block: T.proc.void).void }
+        def on(event, &block)
+        end
+      end
+    end
+  end
+end