eleven_rb 0.1.0

data/lib/eleven_rb/collections/voice_collection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Collections
+    # Collection of Voice objects
+    class VoiceCollection < Base
+      # Find voice by ID
+      #
+      # @param voice_id [String]
+      # @return [Objects::Voice, nil]
+      def find_by_id(voice_id)
+        items.find { |v| v.voice_id == voice_id }
+      end
+
+      # Find voice by name (case-insensitive)
+      #
+      # @param name [String]
+      # @return [Objects::Voice, nil]
+      def find_by_name(name)
+        items.find { |v| v.name&.downcase == name.downcase }
+      end
+
+      # Filter voices by gender
+      #
+      # @param gender [String]
+      # @return [Array<Objects::Voice>]
+      def by_gender(gender)
+        items.select { |v| v.gender&.downcase == gender.downcase }
+      end
+
+      # Filter voices by language
+      #
+      # @param language [String]
+      # @return [Array<Objects::Voice>]
+      def by_language(language)
+        items.select { |v| v.language&.downcase == language.downcase }
+      end
+
+      # Filter voices by accent
+      #
+      # @param accent [String]
+      # @return [Array<Objects::Voice>]
+      def by_accent(accent)
+        items.select { |v| v.accent&.downcase&.include?(accent.downcase) }
+      end
+
+      # Filter voices by category
+      #
+      # @param category [String]
+      # @return [Array<Objects::Voice>]
+      def by_category(category)
+        items.select { |v| v.category&.downcase == category.downcase }
+      end
+
+      # Get all voice IDs
+      #
+      # @return [Array<String>]
+      def voice_ids
+        items.map(&:voice_id)
+      end
+
+      # Check if voice ID exists in collection
+      #
+      # @param voice_id [String]
+      # @return [Boolean]
+      def include_voice?(voice_id)
+        voice_ids.include?(voice_id)
+      end
+
+      private
+
+      def parse_items(response)
+        voices = response['voices'] || response || []
+        voices.map { |v| Objects::Voice.from_response(v) }
+      end
+    end
+  end
+end

data/lib/eleven_rb/configuration.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  # Configuration for the ElevenRb client
+  #
+  # @example Basic configuration
+  #   config = ElevenRb::Configuration.new(api_key: "your-api-key")
+  #
+  # @example Full configuration with callbacks
+  #   config = ElevenRb::Configuration.new(
+  #     api_key: "your-api-key",
+  #     timeout: 60,
+  #     on_error: ->(error:, **) { Sentry.capture_exception(error) }
+  #   )
+  class Configuration
+    include Callbacks
+
+    DEFAULTS = {
+      base_url: 'https://api.elevenlabs.io/v1',
+      timeout: 120,
+      open_timeout: 10,
+      max_retries: 3,
+      retry_delay: 1.0,
+      retry_statuses: [429, 500, 502, 503, 504].freeze
+    }.freeze
+
+    attr_accessor :api_key, :base_url, :timeout, :open_timeout,
+                  :max_retries, :retry_delay, :retry_statuses,
+                  :logger
+
+    # Initialize a new configuration
+    #
+    # @param options [Hash] configuration options
+    # @option options [String] :api_key ElevenLabs API key (required)
+    # @option options [String] :base_url API base URL (default: https://api.elevenlabs.io/v1)
+    # @option options [Integer] :timeout Request timeout in seconds (default: 120)
+    # @option options [Integer] :open_timeout Connection timeout in seconds (default: 10)
+    # @option options [Integer] :max_retries Maximum retry attempts (default: 3)
+    # @option options [Float] :retry_delay Base delay between retries in seconds (default: 1.0)
+    # @option options [Array<Integer>] :retry_statuses HTTP status codes to retry (default: [429, 500, 502, 503, 504])
+    # @option options [Logger] :logger Logger instance for debug output
+    # @option options [Proc] :on_request Callback before each request
+    # @option options [Proc] :on_response Callback after successful response
+    # @option options [Proc] :on_error Callback when an error occurs
+    # @option options [Proc] :on_audio_generated Callback after TTS generation
+    # @option options [Proc] :on_retry Callback before retry attempt
+    # @option options [Proc] :on_rate_limit Callback when rate limited
+    # @option options [Proc] :on_voice_added Callback when voice added
+    # @option options [Proc] :on_voice_deleted Callback when voice deleted
+    def initialize(**options)
+      # Set defaults
+      DEFAULTS.each { |k, v| send("#{k}=", v) }
+
+      # Override with provided options (including callbacks)
+      options.each do |key, value|
+        send("#{key}=", value) if respond_to?("#{key}=")
+      end
+    end
+
+    # Validate the configuration
+    #
+    # @raise [Errors::ConfigurationError] if configuration is invalid
+    # @return [true]
+    def validate!
+      if api_key.nil? || api_key.to_s.empty?
+        raise Errors::ConfigurationError,
+              'API key is required. Set via api_key option or ELEVENLABS_API_KEY environment variable.'
+      end
+
+      true
+    end
+
+    # Return a hash representation (with API key redacted)
+    #
+    # @return [Hash]
+    def to_h
+      {
+        api_key: api_key ? '[REDACTED]' : nil,
+        base_url: base_url,
+        timeout: timeout,
+        open_timeout: open_timeout,
+        max_retries: max_retries,
+        retry_delay: retry_delay
+      }
+    end
+  end
+end

data/lib/eleven_rb/errors.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Errors
+    # Base error class for all ElevenRb errors
+    class Base < StandardError
+      attr_reader :http_status, :response_body, :error_code
+
+      def initialize(message = nil, http_status: nil, response_body: nil, error_code: nil)
+        @http_status = http_status
+        @response_body = response_body
+        @error_code = error_code
+        super(message)
+      end
+    end
+
+    # Configuration/setup errors
+    class ConfigurationError < Base; end
+
+    # HTTP 400 - Bad request / validation errors
+    class ValidationError < Base; end
+
+    # HTTP 401 - Unauthorized
+    class AuthenticationError < Base; end
+
+    # HTTP 403 - Forbidden
+    class ForbiddenError < Base; end
+
+    # HTTP 404 - Not found
+    class NotFoundError < Base; end
+
+    # HTTP 422 - Unprocessable entity
+    class UnprocessableError < Base; end
+
+    # HTTP 429 - Rate limited
+    class RateLimitError < Base
+      attr_reader :retry_after
+
+      def initialize(message = nil, retry_after: nil, **kwargs)
+        @retry_after = retry_after
+        super(message, **kwargs)
+      end
+    end
+
+    # HTTP 5xx - Server errors
+    class ServerError < Base; end
+
+    # Generic API error (fallback)
+    class APIError < Base; end
+
+    # Voice slot specific errors
+    class VoiceSlotLimitError < Base; end
+
+    # Network/connection errors
+    class ConnectionError < Base; end
+    class TimeoutError < ConnectionError; end
+  end
+end

data/lib/eleven_rb/http/client.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'json'
+
+module ElevenRb
+  module HTTP
+    # HTTP client for making requests to the ElevenLabs API
+    class Client
+      include HTTParty
+
+      attr_reader :config
+
+      # Initialize the HTTP client
+      #
+      # @param config [Configuration] the configuration object
+      def initialize(config)
+        @config = config
+      end
+
+      # Make a GET request
+      #
+      # @param path [String] the API path
+      # @param params [Hash] query parameters
+      # @return [Hash, Array] parsed JSON response
+      def get(path, params = {})
+        request(:get, path, params: params)
+      end
+
+      # Make a POST request
+      #
+      # @param path [String] the API path
+      # @param body [Hash] request body
+      # @param response_type [Symbol] :json or :binary
+      # @return [Hash, Array, String] parsed response
+      def post(path, body = {}, response_type: :json)
+        request(:post, path, body: body, response_type: response_type)
+      end
+
+      # Make a DELETE request
+      #
+      # @param path [String] the API path
+      # @return [Hash] parsed JSON response
+      def delete(path)
+        request(:delete, path)
+      end
+
+      # Make a multipart POST request (for file uploads)
+      #
+      # @param path [String] the API path
+      # @param params [Hash] form parameters including files
+      # @return [Hash] parsed JSON response
+      def post_multipart(path, params)
+        request(:post, path, body: params, multipart: true)
+      end
+
+      # Make a streaming POST request
+      #
+      # @param path [String] the API path
+      # @param body [Hash] request body
+      # @yield [String] yields each chunk of data
+      # @return [void]
+      def post_stream(path, body = {}, &block)
+        request(:post, path, body: body, stream: true, &block)
+      end
+
+      private
+
+      def request(method, path, body: nil, params: nil, response_type: :json, multipart: false, stream: false,
+                  attempt: 1, &block)
+        url = "#{config.base_url}#{path}"
+        start_time = Time.now
+
+        # Trigger before request callback
+        config.trigger(:on_request, method: method, path: path, body: sanitize_body_for_logging(body))
+
+        begin
+          response = execute_request(method, url, body, params, multipart, stream, &block)
+          duration = ((Time.now - start_time) * 1000).round(2)
+
+          # For streaming, we've already processed the data
+          return nil if stream
+
+          # Trigger after response callback
+          config.trigger(:on_response, method: method, path: path, response: response, duration: duration)
+
+          # Return binary data directly
+          return response.body if response_type == :binary && response.success?
+
+          handle_response(response)
+        rescue Errors::RateLimitError => e
+          config.trigger(:on_rate_limit, retry_after: e.retry_after, error: e)
+          handle_retry(e, method, path, body, params, response_type, multipart, stream, attempt, &block)
+        rescue Errors::ServerError => e
+          handle_retry(e, method, path, body, params, response_type, multipart, stream, attempt, &block)
+        rescue Errors::Base => e
+          config.trigger(:on_error, error: e, method: method, path: path,
+                                    context: { body: sanitize_body_for_logging(body) })
+          raise
+        rescue StandardError => e
+          wrapped_error = wrap_error(e)
+          config.trigger(:on_error, error: wrapped_error, method: method, path: path,
+                                    context: { body: sanitize_body_for_logging(body) })
+          raise wrapped_error
+        end
+      end
+
+      def execute_request(method, url, body, params, multipart, stream, &block)
+        options = build_options(body, params, multipart, stream, &block)
+
+        case method
+        when :get
+          self.class.get(url, options)
+        when :post
+          self.class.post(url, options)
+        when :delete
+          self.class.delete(url, options)
+        else
+          raise ArgumentError, "Unknown HTTP method: #{method}"
+        end
+      end
+
+      def build_options(body, params, multipart, stream, &block)
+        options = {
+          headers: headers(multipart),
+          timeout: config.timeout,
+          open_timeout: config.open_timeout
+        }
+
+        options[:query] = params if params && !params.empty?
+
+        if body && !body.empty?
+          options[:body] = if multipart
+                             build_multipart_body(body)
+                           else
+                             body.to_json
+                           end
+        end
+
+        if stream && block_given?
+          options[:stream_body] = true
+          options[:on_data] = block
+        end
+
+        options
+      end
+
+      def headers(multipart = false)
+        h = {
+          'xi-api-key' => config.api_key,
+          'Accept' => 'application/json'
+        }
+        h['Content-Type'] = 'application/json' unless multipart
+        h
+      end
+
+      def build_multipart_body(params)
+        body = {}
+
+        params.each do |key, value|
+          case key.to_sym
+          when :files
+            # Handle file array
+            Array(value).each_with_index do |file, index|
+              body["files[#{index}]"] = file
+            end
+          else
+            body[key.to_s] = value
+          end
+        end
+
+        body
+      end
+
+      def handle_response(response)
+        return parse_json(response.body) if response.success?
+
+        handle_error_response(response)
+      end
+
+      def handle_error_response(response)
+        status = response.code
+        body = parse_error_body(response.body)
+        message = extract_error_message(body)
+
+        error_class = case status
+                      when 400 then Errors::ValidationError
+                      when 401 then Errors::AuthenticationError
+                      when 403 then Errors::ForbiddenError
+                      when 404 then Errors::NotFoundError
+                      when 422 then Errors::UnprocessableError
+                      when 429 then Errors::RateLimitError
+                      when 500..599 then Errors::ServerError
+                      else Errors::APIError
+                      end
+
+        error_kwargs = {
+          http_status: status,
+          response_body: body,
+          error_code: body['error_code']
+        }
+
+        if error_class == Errors::RateLimitError
+          retry_after = response.headers['retry-after']&.to_i
+          error_kwargs[:retry_after] = retry_after
+        end
+
+        raise error_class.new(message, **error_kwargs)
+      end
+
+      def handle_retry(error, method, path, body, params, response_type, multipart, stream, attempt, &block)
+        raise error if attempt > config.max_retries || !config.retry_statuses.include?(error.http_status)
+
+        delay = if error.is_a?(Errors::RateLimitError) && error.retry_after
+                  error.retry_after
+                else
+                  config.retry_delay * attempt
+                end
+
+        config.trigger(:on_retry, error: error, attempt: attempt, max_attempts: config.max_retries, delay: delay)
+
+        sleep(delay)
+
+        request(method, path,
+                body: body, params: params, response_type: response_type, multipart: multipart, stream: stream, attempt: attempt + 1, &block)
+      end
+
+      def wrap_error(error)
+        case error
+        when Timeout::Error, Net::OpenTimeout
+          Errors::TimeoutError.new(error.message)
+        when SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET
+          Errors::ConnectionError.new(error.message)
+        else
+          Errors::APIError.new(error.message)
+        end
+      end
+
+      def parse_json(body)
+        return {} if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def parse_error_body(body)
+        parse_json(body)
+      end
+
+      def extract_error_message(body)
+        detail = body['detail']
+        case detail
+        when Hash
+          detail['message'] || detail['status'] || detail.to_s
+        when String
+          detail
+        else
+          body['message'] || body['error'] || 'Unknown error'
+        end
+      end
+
+      def sanitize_body_for_logging(body)
+        return nil if body.nil?
+
+        # Remove any sensitive data or large binary content
+        if body.is_a?(Hash)
+          body.transform_values do |v|
+            v.is_a?(File) ? "[FILE: #{v.path}]" : v
+          end
+        else
+          body
+        end
+      end
+    end
+  end
+end

data/lib/eleven_rb/instrumentation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  # Provides ActiveSupport::Notifications integration for Rails apps
+  #
+  # @example Subscribing to events
+  #   ActiveSupport::Notifications.subscribe(/eleven_rb/) do |name, start, finish, id, payload|
+  #     duration = (finish - start) * 1000
+  #     Rails.logger.info("[ElevenRb] #{name} completed in #{duration.round(2)}ms")
+  #   end
+  module Instrumentation
+    module_function
+
+    # Instrument a block with ActiveSupport::Notifications if available
+    #
+    # @param name [String] the event name (will be suffixed with .eleven_rb)
+    # @param payload [Hash] additional data to include in the notification
+    # @yield the block to instrument
+    # @return [Object] the return value of the block
+    def instrument(name, payload = {}, &block)
+      if defined?(ActiveSupport::Notifications)
+        ActiveSupport::Notifications.instrument("#{name}.eleven_rb", payload, &block)
+      elsif block_given?
+        yield
+      end
+    end
+
+    # Check if ActiveSupport::Notifications is available
+    #
+    # @return [Boolean]
+    def available?
+      defined?(ActiveSupport::Notifications)
+    end
+  end
+end

data/lib/eleven_rb/objects/audio.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module ElevenRb
+  module Objects
+    # Represents generated audio data
+    class Audio
+      attr_reader :data, :format, :voice_id, :text, :model_id
+
+      # Initialize audio object
+      #
+      # @param data [String] binary audio data
+      # @param format [String] audio format (e.g., "mp3_44100_128")
+      # @param voice_id [String] the voice ID used
+      # @param text [String] the text that was converted
+      # @param model_id [String, nil] the model ID used
+      def initialize(data:, format:, voice_id:, text:, model_id: nil)
+        @data = data
+        @format = format
+        @voice_id = voice_id
+        @text = text
+        @model_id = model_id
+      end
+
+      # Save audio to a file
+      #
+      # @param path [String] file path to save to
+      # @return [String] the path that was written to
+      def save_to_file(path)
+        File.binwrite(path, data)
+        path
+      end
+
+      # Get the size in bytes
+      #
+      # @return [Integer]
+      def bytes
+        data.bytesize
+      end
+
+      # Get the size in kilobytes
+      #
+      # @return [Float]
+      def kilobytes
+        bytes / 1024.0
+      end
+
+      # Convert to IO object for streaming/uploading
+      #
+      # @return [StringIO]
+      def to_io
+        StringIO.new(data)
+      end
+
+      # Get the content type based on format
+      #
+      # @return [String]
+      def content_type
+        case format
+        when /mp3/
+          'audio/mpeg'
+        when /pcm/
+          'audio/pcm'
+        when /ogg/
+          'audio/ogg'
+        when /wav/
+          'audio/wav'
+        when /flac/
+          'audio/flac'
+        else
+          'application/octet-stream'
+        end
+      end
+
+      # Get file extension based on format
+      #
+      # @return [String]
+      def extension
+        case format
+        when /mp3/
+          'mp3'
+        when /pcm/
+          'pcm'
+        when /ogg/
+          'ogg'
+        when /wav/
+          'wav'
+        when /flac/
+          'flac'
+        else
+          'bin'
+        end
+      end
+
+      # Get character count of source text
+      #
+      # @return [Integer]
+      def character_count
+        text.length
+      end
+
+      # Check if data is present
+      #
+      # @return [Boolean]
+      def present?
+        data && !data.empty?
+      end
+
+      # Inspect the object
+      #
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} format=#{format.inspect} bytes=#{bytes} voice_id=#{voice_id.inspect}>"
+      end
+    end
+  end
+end