telnyx 5.66.1 → 5.67.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd82c8cd31aaabd131bb14b35a9e067b9f3f8a4e2f9a43e9c68f343976fbc90c
-  data.tar.gz: c5c6c20bc874085965b6833d175af91e56ea847f58d59bb1ea2fdaf879492a89
+  metadata.gz: f156eac95b70864a77dfaeb5e8db6538f52eaf60d1184e3a4c08164115307a20
+  data.tar.gz: 191552e0d38c629677b3def057d01f314743af6f354799741d225acdb9d2ce0d
 SHA512:
-  metadata.gz: 6787a88a9c70d2bc6e28c5cef770b26a578f46af3fe251486ef05b54e51f3c2c9a2ea25c98255afc66d2c3e486ed8d5509b15d555b8345cc5566ae7490a1f231
-  data.tar.gz: 8419fed41b3a914da9e880d390da87814e8210784cc7ca7a84d40ec56b4c22d3123b89d07a151d0f3c93d5cb862ed25eb1362064b840a3e593cc629e2bb528bb
+  metadata.gz: 3a8471f199d00dec4d4c8d4222b89dc870075ff07605396e13ad77b0b379b171ff2ba6ea1011804e57b6882d98223bb1278138151eeff0fa5e0ac76ce07d2a15
+  data.tar.gz: 3a4fa036e4c042ddea3c68fa8687ca51040730dd6695d192782e9928b482ce70b18ab94f7f4b3db2815e4a404ebe12001c23214d730ac90cf2f9445ccc4f6f64

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 5.67.0 (2026-03-26)
+
+Full Changelog: [v5.66.1...v5.67.0](https://github.com/team-telnyx/telnyx-ruby/compare/v5.66.1...v5.67.0)
+
+### Features
+
+* **websocket:** add STT/TTS WebSocket streaming support ([34b7363](https://github.com/team-telnyx/telnyx-ruby/commit/34b73633e8b5c86b17b046746e798365628c2a66))
+
+
+### Bug Fixes
+
+* **websocket:** add Sorbet RBI type definitions ([efe7e55](https://github.com/team-telnyx/telnyx-ruby/commit/efe7e550f9f781453cf69827fe8bfca9b23d9a87))
+
 ## 5.66.1 (2026-03-25)
 
 Full Changelog: [v5.66.0...v5.66.1](https://github.com/team-telnyx/telnyx-ruby/compare/v5.66.0...v5.66.1)

data/README.md

@@ -24,7 +24,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "telnyx", "~> 5.66.1"
+gem "telnyx", "~> 5.67.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/telnyx/lib/websocket/base.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "cgi"
+
+module Telnyx
+  module Lib
+    module WebSocket
+      # Base class for WebSocket connections.
+      #
+      # This class provides the foundation for STT and TTS WebSocket clients,
+      # including event handling, connection state management, and error handling.
+      #
+      # The class uses a simple event emitter pattern with block callbacks
+      # for handling WebSocket events.
+      #
+      # Example usage:
+      #
+      #   class MyWS < Base
+      #     def initialize(client)
+      #       super()
+      #       @client = client
+      #     end
+      #   end
+      #
+      #   ws = MyWS.new(client)
+      #   ws.on(:message) { |data| puts data }
+      #   ws.on(:error) { |error| puts error.message }
+      #
+      class Base
+        # WebSocket ready states (matching WebSocket spec)
+        CONNECTING = 0
+        OPEN = 1
+        CLOSING = 2
+        CLOSED = 3
+
+        # @return [Integer] Current connection state
+        attr_reader :ready_state
+
+        # @return [URI] The WebSocket URL
+        attr_reader :url
+
+        # @api private
+        def initialize
+          @listeners = Hash.new { |h, k| h[k] = [] }
+          @ready_state = CONNECTING
+          @socket = nil
+          @mutex = Mutex.new
+          @open_queue = ::Queue.new
+        end
+
+        # Register an event listener.
+        #
+        # @param event [Symbol, String] The event name to listen for
+        # @yield [Object] Block to call when event is emitted
+        # @return [self]
+        #
+        # Available events:
+        # - :open - Connection established
+        # - :message - Raw message received
+        # - :event - Parsed event received
+        # - :error - Error occurred
+        # - :close - Connection closed
+        # - Event-specific types (e.g., :transcript, :audio_chunk)
+        def on(event, &block)
+          @listeners[event.to_sym] << block
+          self
+        end
+
+        # Remove an event listener.
+        #
+        # @param event [Symbol, String] The event name
+        # @param block [Proc, nil] The specific block to remove, or nil to remove all
+        # @return [self]
+        def off(event, block = nil)
+          if block
+            @listeners[event.to_sym].delete(block)
+          else
+            @listeners.delete(event.to_sym)
+          end
+          self
+        end
+
+        # Check if the connection is open.
+        #
+        # @return [Boolean]
+        def open?
+          @ready_state == OPEN
+        end
+
+        # Check if the connection is connecting.
+        #
+        # @return [Boolean]
+        def connecting?
+          @ready_state == CONNECTING
+        end
+
+        # Check if the connection is closed.
+        #
+        # @return [Boolean]
+        def closed?
+          @ready_state == CLOSED || @ready_state == CLOSING
+        end
+
+        # Wait for the connection to be established.
+        #
+        # @param timeout [Numeric, nil] Maximum time to wait in seconds
+        # @raise [WebSocketError] If connection fails or times out
+        # @return [self]
+        def wait_for_open(timeout: nil)
+          return self if open?
+
+          result = if timeout
+            @open_queue.pop(timeout: timeout)
+          else
+            @open_queue.pop
+          end
+
+          if result.is_a?(Exception)
+            raise result
+          end
+
+          self
+        rescue ThreadError
+          raise WebSocketError.new("Connection timed out")
+        end
+
+        # Close the WebSocket connection.
+        #
+        # @param code [Integer] Close status code (default: 1000 normal closure)
+        # @param reason [String] Close reason
+        # @return [void]
+        # rubocop:disable Lint/UnusedMethodArgument
+        def close(code: 1000, reason: "OK")
+          return if closed?
+
+          @ready_state = CLOSING
+          begin
+            @socket&.close
+          rescue StandardError => e
+            emit_error(nil, "could not close the connection", e)
+          end
+          @ready_state = CLOSED
+        end
+        # rubocop:enable Lint/UnusedMethodArgument
+
+        protected
+
+        # Emit an event to all registered listeners.
+        #
+        # @param event [Symbol] The event name
+        # @param args [Array] Arguments to pass to listeners
+        # @return [void]
+        def emit(event, *args)
+          @listeners[event.to_sym].each do |listener|
+            listener.call(*args)
+          rescue StandardError => e
+            # Don't let listener errors crash the WebSocket
+            warn("WebSocket listener error for #{event}: #{e.message}")
+          end
+        end
+
+        # Check if there are listeners for an event.
+        #
+        # @param event [Symbol] The event name
+        # @return [Boolean]
+        def listener?(event)
+          @listeners[event.to_sym].any?
+        end
+
+        # Emit an error event, handling missing error handlers.
+        #
+        # @param event_data [Hash, nil] Server error event data
+        # @param message [String, nil] Error message
+        # @param cause [StandardError, nil] Underlying exception
+        # @return [void]
+        def emit_error(event_data, message = nil, cause = nil)
+          message ||= safe_json_stringify(event_data) || "unknown error"
+
+          unless listener?(:error)
+            error = WebSocketError.new(
+              "#{message}\n\nTo handle errors, bind an `error` callback: ws.on(:error) { |e| ... }",
+              error: event_data,
+              cause: cause
+            )
+            warn("Unhandled WebSocket error: #{error.message}")
+            return
+          end
+
+          error = WebSocketError.new(message, error: event_data, cause: cause)
+          emit(:error, error)
+        end
+
+        # Mark the connection as open.
+        #
+        # @api private
+        def mark_open
+          @ready_state = OPEN
+          emit(:open)
+          @open_queue << :ok
+        end
+
+        # Mark the connection as closed.
+        #
+        # @api private
+        def mark_closed(code = nil, reason = nil)
+          @ready_state = CLOSED
+          emit(:close, code, reason)
+          @open_queue << :closed
+        end
+
+        # Build the WebSocket URL.
+        #
+        # @param client [Telnyx::Client] The Telnyx client
+        # @param path [String] The API path
+        # @param params [Hash, nil] Query parameters
+        # @return [URI]
+        def build_url(client, path, params = nil)
+          base_url = client.base_url
+          url = URI.parse(base_url + (base_url.end_with?("/") ? path[1..] : path))
+
+          if params && !params.empty?
+            query = params.map { |k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }.join("&")
+            url.query = query
+          end
+
+          # Convert to WebSocket protocol
+          url.scheme = url.scheme == "http" ? "ws" : "wss"
+          url
+        end
+
+        # Build authorization headers.
+        #
+        # @param client [Telnyx::Client] The Telnyx client
+        # @return [Hash]
+        def auth_headers(client)
+          if client.api_key
+            {"Authorization" => "Bearer #{client.api_key}"}
+          else
+            {}
+          end
+        end
+
+        private
+
+        # Safely stringify a value to JSON.
+        #
+        # @param value [Object] The value to stringify
+        # @return [String, nil]
+        def safe_json_stringify(value)
+          return nil if value.nil?
+          JSON.generate(value)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/lib/websocket/speech_to_text_stream_params.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Lib
+    module WebSocket
+      # Parameters for configuring Speech-to-Text WebSocket streaming.
+      #
+      # These parameters are passed as query string parameters when
+      # establishing the WebSocket connection.
+      #
+      # Example usage:
+      #
+      #   params = SpeechToTextStreamParams.new(
+      #     transcription_engine: "Deepgram",
+      #     language: "en-US",
+      #     input_format: "wav"
+      #   )
+      #   url = params.to_query_string
+      #
+      class SpeechToTextStreamParams
+        # @return [String, nil] The transcription engine to use (e.g., "Deepgram", "Google", "Telnyx")
+        attr_accessor :transcription_engine
+
+        # @return [String, nil] The language code (e.g., "en-US", "es-ES")
+        attr_accessor :language
+
+        # @return [String, nil] The audio input format (e.g., "wav", "mp3", "raw")
+        attr_accessor :input_format
+
+        # @return [Integer, nil] Sample rate in Hz (e.g., 8000, 16000)
+        attr_accessor :sample_rate
+
+        # @return [Boolean, nil] Enable interim/partial results
+        attr_accessor :interim_results
+
+        # @return [Boolean, nil] Enable automatic punctuation
+        attr_accessor :punctuate
+
+        # @return [Boolean, nil] Enable profanity filtering
+        attr_accessor :profanity_filter
+
+        # @return [Boolean, nil] Enable speaker diarization
+        attr_accessor :diarize
+
+        # @return [Integer, nil] Number of speakers for diarization
+        attr_accessor :diarize_speakers
+
+        # @return [String, nil] Custom vocabulary or model name
+        attr_accessor :model
+
+        # @return [Array<String>, nil] Keywords to boost recognition
+        attr_accessor :keywords
+
+        # @return [String, nil] Client reference identifier
+        attr_accessor :client_ref
+
+        # Create params from a hash
+        #
+        # @param options [Hash] The parameter options
+        # @return [SpeechToTextStreamParams]
+        def self.from_hash(options)
+          params = new
+          params.transcription_engine = options[:transcription_engine] || options["transcription_engine"]
+          params.language = options[:language] || options["language"]
+          params.input_format = options[:input_format] || options["input_format"]
+          params.sample_rate = options[:sample_rate] || options["sample_rate"]
+          params.interim_results = options[:interim_results] || options["interim_results"]
+          params.punctuate = options[:punctuate] || options["punctuate"]
+          params.profanity_filter = options[:profanity_filter] || options["profanity_filter"]
+          params.diarize = options[:diarize] || options["diarize"]
+          params.diarize_speakers = options[:diarize_speakers] || options["diarize_speakers"]
+          params.model = options[:model] || options["model"]
+          params.keywords = options[:keywords] || options["keywords"]
+          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["transcription_engine"] = transcription_engine if transcription_engine
+          hash["language"] = language if language
+          hash["input_format"] = input_format if input_format
+          hash["sample_rate"] = sample_rate.to_s if sample_rate
+          hash["interim_results"] = interim_results.to_s unless interim_results.nil?
+          hash["punctuate"] = punctuate.to_s unless punctuate.nil?
+          hash["profanity_filter"] = profanity_filter.to_s unless profanity_filter.nil?
+          hash["diarize"] = diarize.to_s unless diarize.nil?
+          hash["diarize_speakers"] = diarize_speakers.to_s if diarize_speakers
+          hash["model"] = model if model
+          hash["keywords"] = keywords.join(",") if keywords && !keywords.empty?
+          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/speech_to_text_ws.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+require_relative "stt_server_event"
+require_relative "speech_to_text_stream_params"
+require_relative "websocket_error"
+
+module Telnyx
+  module Lib
+    module WebSocket
+      # WebSocket client for Speech-to-Text (STT) streaming transcription.
+      #
+      # This client establishes a WebSocket connection to the Telnyx STT API
+      # for real-time audio transcription. Audio data is sent as binary frames
+      # and transcription results are received as JSON events.
+      #
+      # Example usage:
+      #
+      #   client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])
+      #
+      #   ws = Telnyx::Lib::WebSocket::SpeechToTextWS.new(client, {
+      #     transcription_engine: "Deepgram",
+      #     language: "en-US",
+      #     input_format: "wav"
+      #   })
+      #
+      #   ws.on(:transcript) do |event|
+      #     puts "Transcript: #{event.transcript}" if event.is_final
+      #   end
+      #
+      #   ws.on(:error) do |error|
+      #     puts "Error: #{error.message}"
+      #   end
+      #
+      #   ws.wait_for_open
+      #
+      #   # Send audio data
+      #   File.open("audio.wav", "rb") do |f|
+      #     while (chunk = f.read(4096))
+      #       ws.send(chunk)
+      #     end
+      #   end
+      #
+      #   ws.close
+      #
+      class SpeechToTextWS < Base
+        # The WebSocket API path for STT
+        API_PATH = "/v2/speech-to-text/transcription"
+
+        # @return [Telnyx::Client] The Telnyx client
+        attr_reader :client
+
+        # @return [SpeechToTextStreamParams] The stream parameters
+        attr_reader :params
+
+        # Create a new STT WebSocket connection.
+        #
+        # @param client [Telnyx::Client] The Telnyx client
+        # @param params [Hash, SpeechToTextStreamParams] 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
+
+          @url = build_url(client, API_PATH, @params&.to_hash)
+          connect
+        end
+
+        # Send binary audio data to the server for transcription.
+        #
+        # @param data [String] Raw audio bytes (mp3, wav, or raw format)
+        # @return [void]
+        # @raise [WebSocketError] If send fails
+        def send(data)
+          unless open?
+            raise WebSocketError.new("Cannot send: WebSocket is not open")
+          end
+
+          begin
+            @socket.send(data, type: :binary)
+          rescue StandardError => e
+            emit_error(nil, "could not send audio data", e)
+          end
+        end
+
+        private
+
+        def normalize_params(params)
+          case params
+          when nil
+            nil
+          when SpeechToTextStreamParams
+            params
+          when Hash
+            SpeechToTextStreamParams.from_hash(params)
+          else
+            raise ArgumentError, "params must be a Hash or SpeechToTextStreamParams"
+          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(:mark_open)
+          end
+
+          @socket.on(:message) do |msg|
+            ws_self.send(:handle_message, msg)
+          end
+
+          @socket.on(:error) do |e|
+            ws_self.send(:emit_error, nil, e.message, 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(:mark_closed, code, reason)
+          end
+        end
+
+        def handle_message(msg)
+          # Parse the JSON message
+          event = parse_event(msg)
+          return unless event
+
+          # Emit generic event
+          emit(:event, event)
+
+          # Emit type-specific event
+          if event.error?
+            emit_error(event.raw)
+          elsif event.type
+            emit(event.type.to_sym, event)
+          end
+        end
+
+        def parse_event(msg)
+          data = JSON.parse(msg.data)
+          SttServerEvent.from_hash(data)
+        rescue JSON::ParserError => e
+          emit_error(nil, "could not parse websocket event", e)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/lib/websocket/stt_server_event.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Lib
+    module WebSocket
+      # Server event types for Speech-to-Text WebSocket streaming.
+      #
+      # These events are received from the Telnyx STT WebSocket API
+      # during real-time audio transcription.
+      #
+      # Example usage:
+      #
+      #   ws.on(:transcript) do |event|
+      #     puts "Transcript: #{event.transcript}" if event.is_final
+      #   end
+      #
+      #   ws.on(:error) do |event|
+      #     puts "Error: #{event.error}"
+      #   end
+      #
+      class SttServerEvent
+        # @return [String] The event type ("transcript" or "error")
+        attr_accessor :type
+
+        # @return [String, nil] The transcribed text
+        attr_accessor :transcript
+
+        # @return [Boolean, nil] Whether this is a final transcript
+        attr_accessor :is_final
+
+        # @return [Float, nil] Confidence score (0.0 to 1.0)
+        attr_accessor :confidence
+
+        # @return [String, nil] Error message if type is "error"
+        attr_accessor :error
+
+        # @return [Float, nil] Start time offset in seconds
+        attr_accessor :start
+
+        # @return [Float, nil] Duration in seconds
+        attr_accessor :duration
+
+        # @return [Array<Hash>, nil] Word-level timing information
+        attr_accessor :words
+
+        # @return [String, nil] Detected language code
+        attr_accessor :language
+
+        # @return [String, nil] Speaker identifier for diarization
+        attr_accessor :speaker
+
+        # @return [Hash, nil] Original raw event data
+        attr_accessor :raw
+
+        # Create an SttServerEvent from a parsed JSON hash
+        #
+        # @param data [Hash] The parsed JSON event data
+        # @return [SttServerEvent]
+        def self.from_hash(data)
+          event = new
+          event.raw = data
+          event.type = data["type"]
+          event.transcript = data["transcript"]
+          event.is_final = data["is_final"]
+          event.confidence = data["confidence"]
+          event.error = data["error"]
+          event.start = data["start"]
+          event.duration = data["duration"]
+          event.words = data["words"]
+          event.language = data["language"]
+          event.speaker = data["speaker"]
+          event
+        end
+
+        # Check if this is a final transcript
+        #
+        # @return [Boolean]
+        def final?
+          is_final == true
+        end
+
+        # Check if this is an error event
+        #
+        # @return [Boolean]
+        def error?
+          type == "error"
+        end
+      end
+    end
+  end
+end