elevenlabs_client 0.6.0 → 0.8.0

data/lib/elevenlabs_client/client.rb

@@ -1,29 +1,44 @@
 # frozen_string_literal: true
 
-require "faraday"
-require "faraday/multipart"
-require "json"
-
 module ElevenlabsClient
+  # Main client class for the ElevenLabs API
+  # Refactored for better maintainability and architecture
   class Client
-    DEFAULT_BASE_URL = "https://api.elevenlabs.io"
+    attr_reader :http_client
+
+    def initialize(api_key: nil, base_url: nil, **options)
+      # Create configuration
+      configuration = Configuration.new
+      configuration.api_key = api_key if api_key
+      configuration.base_url = base_url if base_url
+      
+      # Apply any additional options
+      options.each do |key, value|
+        configuration.public_send("#{key}=", value) if configuration.respond_to?("#{key}=")
+      end
 
-    attr_reader :base_url, :api_key, :dubs, :text_to_speech, :text_to_dialogue, :sound_generation, :text_to_voice, :models, :voices, :music, :audio_isolation, :audio_native, :forced_alignment, :speech_to_speech, :speech_to_text, :websocket_text_to_speech, :history, :usage, :user, :voice_library
+      # Validate configuration
+      configuration.validate!
 
-    def initialize(api_key: nil, base_url: nil, api_key_env: "ELEVENLABS_API_KEY", base_url_env: "ELEVENLABS_BASE_URL")
-      @api_key = api_key || fetch_api_key(api_key_env)
-      @base_url = base_url || fetch_base_url(base_url_env)
-      @conn = build_connection
+      # Create HTTP client
+      @http_client = HttpClient.new(
+        api_key: configuration.resolved_api_key,
+        base_url: configuration.resolved_base_url
+      )
+
+      # Initialize endpoints directly for now (simpler approach)
+      initialize_endpoints
+    end
+
+    private
+
+    def initialize_endpoints
+      # Core TTS/Audio endpoints
       @dubs = Dubs.new(self)
       @text_to_speech = TextToSpeech.new(self)
       @text_to_dialogue = TextToDialogue.new(self)
       @sound_generation = SoundGeneration.new(self)
       @text_to_voice = TextToVoice.new(self)
-      @models = Admin::Models.new(self)
-      @history = Admin::History.new(self)
-      @usage = Admin::Usage.new(self)
-      @user = Admin::User.new(self)
-      @voice_library = Admin::VoiceLibrary.new(self)
       @voices = Voices.new(self)
       @music = Endpoints::Music.new(self)
       @audio_isolation = AudioIsolation.new(self)
@@ -32,306 +47,132 @@ module ElevenlabsClient
       @speech_to_speech = SpeechToSpeech.new(self)
       @speech_to_text = SpeechToText.new(self)
       @websocket_text_to_speech = WebSocketTextToSpeech.new(self)
-    end
 
-    # Makes an authenticated GET request
-    # @param path [String] API endpoint path
-    # @param params [Hash] Query parameters
-    # @return [Hash] Response body
+      # Admin endpoints
+      @models = Admin::Models.new(self)
+      @history = Admin::History.new(self)
+      @usage = Admin::Usage.new(self)
+      @user = Admin::User.new(self)
+      @voice_library = Admin::VoiceLibrary.new(self)
+      @samples = Admin::Samples.new(self)
+      @pronunciation_dictionaries = Admin::PronunciationDictionaries.new(self)
+      @service_accounts = Admin::ServiceAccounts.new(self)
+      @webhooks = Admin::Webhooks.new(self)
+      @workspace_groups = Admin::WorkspaceGroups.new(self)
+      @workspace_invites = Admin::WorkspaceInvites.new(self)
+      @workspace_members = Admin::WorkspaceMembers.new(self)
+      @workspace_resources = Admin::WorkspaceResources.new(self)
+      @workspace_webhooks = Admin::WorkspaceWebhooks.new(self)
+      @service_account_api_keys = Admin::ServiceAccountApiKeys.new(self)
+
+      # Agents Platform endpoints
+      @agents = Endpoints::AgentsPlatform::Agents.new(self)
+      @conversations = Endpoints::AgentsPlatform::Conversations.new(self)
+      @tools = Endpoints::AgentsPlatform::Tools.new(self)
+      @knowledge_base = Endpoints::AgentsPlatform::KnowledgeBase.new(self)
+      @tests = Endpoints::AgentsPlatform::Tests.new(self)
+      @test_invocations = Endpoints::AgentsPlatform::TestInvocations.new(self)
+      @phone_numbers = Endpoints::AgentsPlatform::PhoneNumbers.new(self)
+      @widgets = Endpoints::AgentsPlatform::Widgets.new(self)
+      @outbound_calling = Endpoints::AgentsPlatform::OutboundCalling.new(self)
+      @batch_calling = Endpoints::AgentsPlatform::BatchCalling.new(self)
+      @workspace = Endpoints::AgentsPlatform::Workspace.new(self)
+      @llm_usage = Endpoints::AgentsPlatform::LlmUsage.new(self)
+      @mcp_servers = Endpoints::AgentsPlatform::McpServers.new(self)
+    end
+
+    public
+
+    # Endpoint accessors
+    attr_reader :dubs, :text_to_speech, :text_to_dialogue, :sound_generation, :text_to_voice, 
+                :voices, :music, :audio_isolation, :audio_native, :forced_alignment, 
+                :speech_to_speech, :speech_to_text, :websocket_text_to_speech,
+                :models, :history, :usage, :user, :voice_library, :samples, 
+                :pronunciation_dictionaries, :service_accounts, :webhooks,
+                :workspace_groups, :workspace_invites, :workspace_members, :workspace_resources,
+                :workspace_webhooks, :service_account_api_keys,
+                :agents, :conversations, :tools, :knowledge_base, :tests, :test_invocations,
+                :phone_numbers, :widgets, :outbound_calling, :batch_calling, :workspace,
+                :llm_usage, :mcp_servers
+
+    # Delegate HTTP methods to http_client for backward compatibility
     def get(path, params = {})
-      response = @conn.get(path, params) do |req|
-        req.headers["xi-api-key"] = api_key
-      end
-
-      handle_response(response)
+      http_client.get(path, params)
     end
 
-    # Makes an authenticated POST request
-    # @param path [String] API endpoint path
-    # @param body [Hash, nil] Request body
-    # @return [Hash] Response body
     def post(path, body = nil)
-      response = @conn.post(path) do |req|
-        req.headers["xi-api-key"] = api_key
-        req.headers["Content-Type"] = "application/json"
-        req.body = body.to_json if body
-      end
+      http_client.post(path, body)
+    end
 
-      handle_response(response)
+    def patch(path, body = nil)
+      http_client.patch(path, body)
     end
 
-    # Makes an authenticated DELETE request
-    # @param path [String] API endpoint path
-    # @return [Hash] Response body
     def delete(path)
-      response = @conn.delete(path) do |req|
-        req.headers["xi-api-key"] = api_key
-      end
-
-      handle_response(response)
+      http_client.delete(path)
     end
 
-    # Makes an authenticated PATCH request
-    # @param path [String] API endpoint path
-    # @param body [Hash, nil] Request body
-    # @return [Hash] Response body
-    def patch(path, body = nil)
-      response = @conn.patch(path) do |req|
-        req.headers["xi-api-key"] = api_key
-        req.headers["Content-Type"] = "application/json"
-        req.body = body.to_json if body
-      end
-
-      handle_response(response)
+    def delete_with_body(path, body = nil)
+      http_client.delete_with_body(path, body)
     end
 
-    # Makes an authenticated multipart POST request
-    # @param path [String] API endpoint path
-    # @param payload [Hash] Multipart payload
-    # @return [Hash] Response body
     def post_multipart(path, payload)
-      response = @conn.post(path) do |req|
-        req.headers["xi-api-key"] = api_key
-        req.body = payload
-      end
-
-      handle_response(response)
+      http_client.post_multipart(path, payload)
     end
 
-    # Makes an authenticated GET request expecting binary response
-    # @param path [String] API endpoint path
-    # @return [String] Binary response body
     def get_binary(path)
-      response = @conn.get(path) do |req|
-        req.headers["xi-api-key"] = api_key
-      end
-
-      handle_response(response)
+      http_client.get_binary(path)
     end
 
-    # Makes an authenticated POST request expecting binary response
-    # @param path [String] API endpoint path
-    # @param body [Hash, nil] Request body
-    # @return [String] Binary response body
     def post_binary(path, body = nil)
-      response = @conn.post(path) do |req|
-        req.headers["xi-api-key"] = api_key
-        req.headers["Content-Type"] = "application/json"
-        req.body = body.to_json if body
-      end
-
-      handle_response(response)
+      http_client.post_binary(path, body)
     end
 
-    # Makes an authenticated POST request with custom headers
-    # @param path [String] API endpoint path
-    # @param body [Hash, nil] Request body
-    # @param custom_headers [Hash] Additional headers
-    # @return [String] Response body (binary or text)
     def post_with_custom_headers(path, body = nil, custom_headers = {})
-      response = @conn.post(path) do |req|
-        req.headers["xi-api-key"] = api_key
-        req.headers["Content-Type"] = "application/json"
-        custom_headers.each { |key, value| req.headers[key] = value }
-        req.body = body.to_json if body
-      end
-
-      # For streaming/binary responses, return raw body
-      if custom_headers["Accept"]&.include?("audio") || custom_headers["Transfer-Encoding"] == "chunked"
-        handle_response(response)
-      else
-        handle_response(response)
-      end
+      http_client.post_with_custom_headers(path, body, custom_headers)
     end
 
-    # Makes an authenticated POST request with streaming response
-    # @param path [String] API endpoint path
-    # @param body [Hash, nil] Request body
-    # @param block [Proc] Block to handle each chunk
-    # @return [Faraday::Response] Response object
     def post_streaming(path, body = nil, &block)
-      response = @conn.post(path) do |req|
-        req.headers["xi-api-key"] = api_key
-        req.headers["Content-Type"] = "application/json"
-        req.headers["Accept"] = "audio/mpeg"
-        req.body = body.to_json if body
-        
-        # Set up streaming callback
-        req.options.on_data = proc do |chunk, _|
-          block.call(chunk) if block_given?
-        end
-      end
-
-      handle_response(response)
+      http_client.post_streaming(path, body, &block)
     end
 
-    # Makes an authenticated GET request with streaming response
-    # @param path [String] API endpoint path
-    # @param block [Proc] Block to handle each chunk
-    # @return [Faraday::Response] Response object
     def get_streaming(path, &block)
-      response = @conn.get(path) do |req|
-        req.headers["xi-api-key"] = api_key
-        req.headers["Accept"] = "audio/mpeg"
-        
-        # Set up streaming callback
-        req.options.on_data = proc do |chunk, _|
-          block.call(chunk) if block_given?
-        end
-      end
-
-      handle_response(response)
+      http_client.get_streaming(path, &block)
     end
 
-    # Makes an authenticated POST request with streaming response for timestamp data
-    # @param path [String] API endpoint path
-    # @param body [Hash, nil] Request body
-    # @param block [Proc] Block to handle each JSON chunk with timestamps
-    # @return [Faraday::Response] Response object
     def post_streaming_with_timestamps(path, body = nil, &block)
-      buffer = ""
-      
-      response = @conn.post(path) do |req|
-        req.headers["xi-api-key"] = api_key
-        req.headers["Content-Type"] = "application/json"
-        req.body = body.to_json if body
-        
-        # Set up streaming callback for JSON chunks
-        req.options.on_data = proc do |chunk, _|
-          if block_given?
-            buffer += chunk
-            
-            # Process complete JSON objects
-            while buffer.include?("\n")
-              line, buffer = buffer.split("\n", 2)
-              next if line.strip.empty?
-              
-              begin
-                json_data = JSON.parse(line)
-                block.call(json_data)
-              rescue JSON::ParserError
-                # Skip malformed JSON lines
-                next
-              end
-            end
-          end
-        end
-      end
-
-      handle_response(response)
+      http_client.post_streaming_with_timestamps(path, body, &block)
     end
 
-    # Helper method to create Faraday::Multipart::FilePart
-    # @param file_io [IO] File IO object
-    # @param filename [String] Original filename
-    # @return [Faraday::Multipart::FilePart]
     def file_part(file_io, filename)
-      Faraday::Multipart::FilePart.new(file_io, mime_for(filename), filename)
+      http_client.file_part(file_io, filename)
     end
 
-    private
-
-    def fetch_api_key(env_key = "ELEVENLABS_API_KEY")
-      # First try Settings, then ENV, then raise error
-      if Settings.properties&.dig(:elevenlabs_api_key)
-        Settings.elevenlabs_api_key
-      else
-        ENV.fetch(env_key) do
-          raise AuthenticationError, "#{env_key} environment variable is required but not set and Settings.properties[:elevenlabs_api_key] is not configured"
-        end
-      end
+    # Convenience accessors for backward compatibility
+    def base_url
+      http_client.base_url
     end
 
-    def fetch_base_url(env_key = "ELEVENLABS_BASE_URL")
-      # First try Settings, then ENV, then default
-      if Settings.properties&.dig(:elevenlabs_base_uri)
-        Settings.elevenlabs_base_uri
-      else
-        ENV.fetch(env_key, DEFAULT_BASE_URL)
-      end
+    def api_key
+      http_client.api_key
     end
 
-    def build_connection
-      Faraday.new(url: base_url) do |f|
-        f.request :multipart
-        f.request :url_encoded
-        f.response :json, content_type: /\bjson$/
-        f.adapter Faraday.default_adapter
-      end
+    # Debug information
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "base_url=#{base_url.inspect}>"
     end
 
-    def handle_response(response)
-      case response.status
-      when 200..299
-        response.body
-      when 400
-        error_message = extract_error_message(response.body)
-        raise BadRequestError, error_message.empty? ? "Bad request - invalid parameters" : error_message
-      when 401
-        error_message = extract_error_message(response.body)
-        raise AuthenticationError, error_message.empty? ? "Invalid API key or authentication failed" : error_message
-      when 404
-        error_message = extract_error_message(response.body)
-        raise NotFoundError, error_message.empty? ? "Resource not found" : error_message
-      when 422
-        error_message = extract_error_message(response.body)
-        raise UnprocessableEntityError, error_message.empty? ? "Unprocessable entity - invalid data" : error_message
-      when 429
-        error_message = extract_error_message(response.body)
-        raise RateLimitError, error_message.empty? ? "Rate limit exceeded" : error_message
-      when 400..499
-        error_message = extract_error_message(response.body)
-        raise ValidationError, error_message.empty? ? "Client error occurred with status #{response.status}" : error_message
-      else
-        error_message = extract_error_message(response.body)
-        raise APIError, error_message.empty? ? "API request failed with status #{response.status}" : error_message
-      end
-    end
-
-    private
-
-    def extract_error_message(response_body)
-      return "" if response_body.nil? || response_body.empty?
-      
-      # Handle non-string response bodies
-      body_str = response_body.is_a?(String) ? response_body : response_body.to_s
-      
+    # Health check method
+    def health_check
       begin
-        error_info = JSON.parse(body_str)
-        
-        # Try different common error message fields
-        message = error_info["detail"] || 
-                 error_info["message"] || 
-                 error_info["error"] ||
-                 error_info["errors"]
-        
-        # Handle nested detail objects
-        if message.is_a?(Hash)
-          message = message["message"] || message.to_s
-        elsif message.is_a?(Array)
-          message = message.first.to_s
-        end
-        
-        message.to_s
-      rescue JSON::ParserError, TypeError
-        # If not JSON or can't be parsed, return the raw body (truncated if too long)
-        body_str.length > 200 ? "#{body_str[0..200]}..." : body_str
+        # Try a simple API call to verify connectivity
+        get("/v1/models")
+        { status: :ok, message: "Client is healthy" }
+      rescue => e
+        { status: :error, message: e.message, error_class: e.class.name }
       end
     end
 
-    def mime_for(filename)
-      ext = File.extname(filename).downcase
-      case ext
-      when ".mp4"  then "video/mp4"
-      when ".mov"  then "video/quicktime"
-      when ".avi"  then "video/x-msvideo"
-      when ".mkv"  then "video/x-matroska"
-      when ".mp3"  then "audio/mpeg"
-      when ".wav"  then "audio/wav"
-      when ".flac" then "audio/flac"
-      when ".m4a"  then "audio/mp4"
-      else "application/octet-stream"
-      end
-    end
   end
 end

data/lib/elevenlabs_client/configuration.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  # Configuration management for the ElevenLabs client
+  class Configuration
+    DEFAULT_BASE_URL = "https://api.elevenlabs.io"
+    DEFAULT_API_KEY_ENV = "ELEVENLABS_API_KEY"
+    DEFAULT_BASE_URL_ENV = "ELEVENLABS_BASE_URL"
+
+    attr_accessor :api_key, :base_url, :api_key_env, :base_url_env, :timeout, :open_timeout,
+                  :retry_count, :retry_delay, :user_agent, :logger, :log_level
+
+    def initialize
+      @api_key = nil
+      @base_url = DEFAULT_BASE_URL
+      @api_key_env = DEFAULT_API_KEY_ENV
+      @base_url_env = DEFAULT_BASE_URL_ENV
+      @timeout = 30
+      @open_timeout = 10
+      @retry_count = 3
+      @retry_delay = 1
+      @user_agent = "ElevenlabsClient/#{ElevenlabsClient::VERSION}"
+      @logger = nil
+      @log_level = :info
+    end
+
+    # Get API key from configuration, environment, or Settings
+    def resolved_api_key
+      return @api_key if @api_key
+
+      # Try Settings first
+      if Settings.properties&.dig(:elevenlabs_api_key)
+        return Settings.elevenlabs_api_key
+      end
+
+      # Then try environment variable
+      env_key = ENV.fetch(@api_key_env) do
+        raise AuthenticationError, 
+          "#{@api_key_env} environment variable is required but not set and " \
+          "Settings.properties[:elevenlabs_api_key] is not configured"
+      end
+
+      env_key
+    end
+
+    # Get base URL from configuration, environment, or Settings
+    def resolved_base_url
+      return @base_url if @base_url != DEFAULT_BASE_URL
+
+      # Try Settings first
+      if Settings.properties&.dig(:elevenlabs_base_uri)
+        return Settings.elevenlabs_base_uri
+      end
+
+      # Then try environment variable, with default fallback
+      ENV.fetch(@base_url_env, DEFAULT_BASE_URL)
+    end
+
+    # Validate configuration
+    def validate!
+      resolved_api_key # This will raise if API key is missing
+      
+      unless resolved_base_url.match?(/\Ahttps?:\/\//)
+        raise ArgumentError, "Invalid base URL: #{resolved_base_url}"
+      end
+
+      unless timeout.is_a?(Numeric) && timeout > 0
+        raise ArgumentError, "Timeout must be a positive number"
+      end
+
+      unless retry_count.is_a?(Integer) && retry_count >= 0
+        raise ArgumentError, "Retry count must be a non-negative integer"
+      end
+    end
+
+    # Create a hash representation of the configuration
+    def to_h
+      {
+        api_key: api_key ? "[REDACTED]" : nil,
+        base_url: resolved_base_url,
+        timeout: timeout,
+        open_timeout: open_timeout,
+        retry_count: retry_count,
+        retry_delay: retry_delay,
+        user_agent: user_agent,
+        log_level: log_level
+      }
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      initialize
+    end
+  end
+
+  class << self
+    # Global configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the client globally
+    def configure
+      yield(configuration) if block_given?
+      configuration.validate!
+      configuration
+    end
+
+    # Reset global configuration
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Convenience method to get configured client
+    def client
+      Client.new
+    end
+  end
+end

data/lib/elevenlabs_client/endpoints/admin/history.rb

@@ -22,7 +22,7 @@ module ElevenlabsClient
       # @return [Hash] Response containing history items, pagination info
       def list(**options)
         endpoint = "/v1/history"
-        
+
         # Build query parameters
         query_params = {}
         query_params[:page_size] = options[:page_size] if options[:page_size]

data/lib/elevenlabs_client/endpoints/admin/pronunciation_dictionaries.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  module Admin
+    class PronunciationDictionaries
+      def initialize(client)
+        @client = client
+      end
+
+      # POST /v1/pronunciation-dictionaries/add-from-file (multipart)
+      # Creates a new pronunciation dictionary from a lexicon .PLS file
+      # Required: name
+      # Optional: file (IO + filename), description, workspace_access
+      def add_from_file(name:, file_io: nil, filename: nil, description: nil, workspace_access: nil)
+        raise ArgumentError, "name is required" if name.nil? || name.to_s.strip.empty?
+
+        endpoint = "/v1/pronunciation-dictionaries/add-from-file"
+        payload = { name: name }
+        payload[:description] = description if description
+        payload[:workspace_access] = workspace_access if workspace_access
+
+        if file_io && filename
+          payload[:file] = @client.file_part(file_io, filename)
+        end
+
+        @client.post_multipart(endpoint, payload)
+      end
+
+      alias_method :create_from_file, :add_from_file
+
+      # POST /v1/pronunciation-dictionaries/add-from-rules (json)
+      # Creates a new pronunciation dictionary from provided rules
+      # Required: name, rules (Array)
+      # Optional: description, workspace_access
+      def add_from_rules(name:, rules:, description: nil, workspace_access: nil)
+        raise ArgumentError, "name is required" if name.nil? || name.to_s.strip.empty?
+        raise ArgumentError, "rules must be a non-empty Array" unless rules.is_a?(Array) && !rules.empty?
+
+        endpoint = "/v1/pronunciation-dictionaries/add-from-rules"
+        body = { name: name, rules: rules }
+        body[:description] = description if description
+        body[:workspace_access] = workspace_access if workspace_access
+
+        @client.post(endpoint, body)
+      end
+
+      alias_method :create_from_rules, :add_from_rules
+
+      # GET /v1/pronunciation-dictionaries/:pronunciation_dictionary_id
+      def get_pronunciation_dictionary(pronunciation_dictionary_id)
+        raise ArgumentError, "pronunciation_dictionary_id is required" if pronunciation_dictionary_id.nil? || pronunciation_dictionary_id.to_s.strip.empty?
+
+        endpoint = "/v1/pronunciation-dictionaries/#{pronunciation_dictionary_id}"
+        @client.get(endpoint)
+      end
+
+      alias_method :get, :get_pronunciation_dictionary
+
+      # PATCH /v1/pronunciation-dictionaries/:pronunciation_dictionary_id
+      # Accepts partial attributes like archived, name, description, workspace_access
+      def update_pronunciation_dictionary(pronunciation_dictionary_id, **attributes)
+        raise ArgumentError, "pronunciation_dictionary_id is required" if pronunciation_dictionary_id.nil? || pronunciation_dictionary_id.to_s.strip.empty?
+        endpoint = "/v1/pronunciation-dictionaries/#{pronunciation_dictionary_id}"
+        @client.patch(endpoint, attributes)
+      end
+
+      alias_method :update, :update_pronunciation_dictionary
+
+      # GET /v1/pronunciation-dictionaries/:dictionary_id/:version_id/download
+      # Returns raw PLS file contents
+      def download_pronunciation_dictionary_version(dictionary_id:, version_id:)
+        raise ArgumentError, "dictionary_id is required" if dictionary_id.nil? || dictionary_id.to_s.strip.empty?
+        raise ArgumentError, "version_id is required" if version_id.nil? || version_id.to_s.strip.empty?
+
+        endpoint = "/v1/pronunciation-dictionaries/#{dictionary_id}/#{version_id}/download"
+        @client.get_binary(endpoint)
+      end
+
+      alias_method :download_version, :download_pronunciation_dictionary_version
+
+      # GET /v1/pronunciation-dictionaries
+      # Optional query: cursor, page_size, sort, sort_direction
+      def list_pronunciation_dictionaries(cursor: nil, page_size: nil, sort: nil, sort_direction: nil)
+        params = {
+          cursor: cursor,
+          page_size: page_size,
+          sort: sort,
+          sort_direction: sort_direction
+        }.compact
+
+        @client.get("/v1/pronunciation-dictionaries", params)
+      end
+
+      alias_method :list, :list_pronunciation_dictionaries
+
+      private
+
+      attr_reader :client
+    end
+  end
+end
+
+