eleven_rb 0.1.0

data/lib/eleven_rb/objects/base.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Objects
+    # Base class for all response objects
+    #
+    # Provides attribute accessors and common functionality for
+    # parsing API responses into structured objects.
+    class Base
+      class << self
+        # Create an object from an API response hash
+        #
+        # @param response [Hash] the API response
+        # @return [Base] the object instance
+        def from_response(response)
+          new(response)
+        end
+
+        # Define an attribute accessor
+        #
+        # @param name [Symbol] the attribute name
+        # @param key [String, nil] the JSON key (defaults to name.to_s)
+        # @param type [Class, Symbol, nil] optional type for conversion
+        def attribute(name, key: nil, type: nil)
+          key ||= name.to_s
+
+          define_method(name) do
+            value = @attributes[key]
+            return nil if value.nil?
+
+            case type
+            when :boolean
+              !!value
+            when Class
+              if value.is_a?(Array)
+                value.map { |v| type.from_response(v) }
+              else
+                type.from_response(value)
+              end
+            else
+              value
+            end
+          end
+        end
+      end
+
+      # Initialize with attributes hash
+      #
+      # @param attributes [Hash] the attributes
+      def initialize(attributes = {})
+        @attributes = attributes || {}
+      end
+
+      # Return raw attributes hash
+      #
+      # @return [Hash]
+      def to_h
+        @attributes.dup
+      end
+
+      # Access raw attribute by key
+      #
+      # @param key [String, Symbol] the attribute key
+      # @return [Object, nil]
+      def [](key)
+        @attributes[key.to_s]
+      end
+
+      # Check if attribute exists
+      #
+      # @param key [String, Symbol] the attribute key
+      # @return [Boolean]
+      def key?(key)
+        @attributes.key?(key.to_s)
+      end
+
+      # Inspect the object
+      #
+      # @return [String]
+      def inspect
+        attrs = @attributes.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+        "#<#{self.class.name} #{attrs}>"
+      end
+    end
+  end
+end

data/lib/eleven_rb/objects/cost_info.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Objects
+    # Cost information for TTS generation
+    class CostInfo
+      attr_reader :character_count, :voice_id, :model_id
+
+      # Approximate cost per 1000 characters by model
+      # These are estimates and may vary by subscription tier
+      COST_PER_1K_CHARS = {
+        'eleven_monolingual_v1' => 0.30,
+        'eleven_multilingual_v1' => 0.30,
+        'eleven_multilingual_v2' => 0.30,
+        'eleven_turbo_v2' => 0.18,
+        'eleven_turbo_v2_5' => 0.18,
+        'eleven_english_sts_v2' => 0.30,
+        'eleven_flash_v2' => 0.10,
+        'eleven_flash_v2_5' => 0.10
+      }.freeze
+
+      DEFAULT_COST_PER_1K = 0.30
+
+      # Initialize cost info
+      #
+      # @param text [String] the text being converted
+      # @param voice_id [String] the voice ID
+      # @param model_id [String] the model ID
+      def initialize(text:, voice_id:, model_id:)
+        @character_count = text.length
+        @voice_id = voice_id
+        @model_id = model_id
+      end
+
+      # Get estimated cost in USD
+      #
+      # @return [Float]
+      def estimated_cost
+        rate = COST_PER_1K_CHARS[model_id] || DEFAULT_COST_PER_1K
+        (character_count / 1000.0 * rate).round(4)
+      end
+
+      # Get cost per character for this model
+      #
+      # @return [Float]
+      def cost_per_character
+        rate = COST_PER_1K_CHARS[model_id] || DEFAULT_COST_PER_1K
+        rate / 1000.0
+      end
+
+      # Check if this is a turbo/cheaper model
+      #
+      # @return [Boolean]
+      def turbo_model?
+        model_id&.include?('turbo') || model_id&.include?('flash')
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash]
+      def to_h
+        {
+          character_count: character_count,
+          voice_id: voice_id,
+          model_id: model_id,
+          estimated_cost: estimated_cost,
+          cost_per_character: cost_per_character
+        }
+      end
+    end
+  end
+end

data/lib/eleven_rb/objects/library_voice.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Objects
+    # Represents a voice from the shared voice library
+    class LibraryVoice < Base
+      attribute :voice_id
+      attribute :public_owner_id
+      attribute :name
+      attribute :description
+      attribute :category
+      attribute :preview_url
+      attribute :gender
+      attribute :age
+      attribute :accent
+      attribute :language
+      attribute :locale
+      attribute :use_cases
+      attribute :notice_period
+      attribute :rate
+      attribute :cloned_by_count
+      attribute :usage_character_count_1d
+      attribute :usage_character_count_7d
+      attribute :usage_character_count_30d
+      attribute :free_users_allowed, type: :boolean
+      attribute :live_moderation_enabled, type: :boolean
+      attribute :verified, type: :boolean
+
+      # Get parameters needed to add this voice to account
+      #
+      # @return [Hash]
+      def add_params
+        {
+          public_user_id: public_owner_id,
+          voice_id: voice_id,
+          name: name
+        }
+      end
+
+      # Human-readable display name with metadata
+      #
+      # @return [String]
+      def display_name
+        parts = [name]
+        parts << "(#{gender})" if gender
+        parts << "- #{accent || language}" if accent || language
+        parts.join(' ')
+      end
+
+      # Check if this voice is popular (high usage)
+      #
+      # @param threshold [Integer] minimum usage count
+      # @return [Boolean]
+      def popular?(threshold: 10_000)
+        (usage_character_count_30d || 0) >= threshold
+      end
+
+      # Check if voice is available for free users
+      #
+      # @return [Boolean]
+      def available_for_free?
+        free_users_allowed != false
+      end
+    end
+  end
+end

data/lib/eleven_rb/objects/model.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Objects
+    # Represents an ElevenLabs TTS model
+    class Model < Base
+      attribute :model_id
+      attribute :name
+      attribute :description
+      attribute :can_be_finetuned, type: :boolean
+      attribute :can_do_text_to_speech, type: :boolean
+      attribute :can_do_voice_conversion, type: :boolean
+      attribute :can_use_style, type: :boolean
+      attribute :can_use_speaker_boost, type: :boolean
+      attribute :serves_pro_voices, type: :boolean
+      attribute :token_cost_factor
+      attribute :languages
+      attribute :max_characters_request_free_user
+      attribute :max_characters_request_subscribed_user
+      attribute :concurrency_group
+
+      # Check if this model supports a given language
+      #
+      # @param language_code [String] ISO language code
+      # @return [Boolean]
+      def supports_language?(language_code)
+        return false unless languages
+
+        languages.any? { |l| l['language_id'] == language_code }
+      end
+
+      # Get list of supported language codes
+      #
+      # @return [Array<String>]
+      def supported_language_codes
+        return [] unless languages
+
+        languages.map { |l| l['language_id'] }
+      end
+
+      # Check if this is a multilingual model
+      #
+      # @return [Boolean]
+      def multilingual?
+        name&.downcase&.include?('multilingual') || supported_language_codes.size > 1
+      end
+
+      # Check if this is a turbo/fast model
+      #
+      # @return [Boolean]
+      def turbo?
+        name&.downcase&.include?('turbo') || model_id&.include?('turbo')
+      end
+    end
+  end
+end

data/lib/eleven_rb/objects/subscription.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Objects
+    # Represents user subscription information
+    class Subscription < Base
+      attribute :tier
+      attribute :character_count
+      attribute :character_limit
+      attribute :voice_limit
+      attribute :professional_voice_limit
+      attribute :can_extend_character_limit, type: :boolean
+      attribute :allowed_to_extend_character_limit, type: :boolean
+      attribute :next_character_count_reset_unix
+      attribute :can_extend_voice_limit, type: :boolean
+      attribute :can_use_instant_voice_cloning, type: :boolean
+      attribute :can_use_professional_voice_cloning, type: :boolean
+      attribute :currency
+      attribute :status
+
+      # Get the number of voice slots currently used
+      # Note: This requires checking voices.list count
+      #
+      # @return [Integer, nil]
+      attr_accessor :voice_slots_used
+
+      # Set voice slots used (called by VoiceSlotManager)
+      #
+      # @param count [Integer]
+
+      # Get available voice slots
+      #
+      # @return [Integer, nil]
+      def voice_slots_available
+        return nil unless voice_limit && voice_slots_used
+
+        voice_limit - voice_slots_used
+      end
+
+      # Check if voice slots are full
+      #
+      # @return [Boolean]
+      def voice_slots_full?
+        return false unless voice_slots_available
+
+        voice_slots_available <= 0
+      end
+
+      # Get remaining characters
+      #
+      # @return [Integer]
+      def characters_remaining
+        return 0 unless character_limit && character_count
+
+        character_limit - character_count
+      end
+
+      # Get percentage of characters used
+      #
+      # @return [Float]
+      def characters_used_percentage
+        return 0.0 unless character_limit&.positive?
+
+        (character_count.to_f / character_limit * 100).round(1)
+      end
+
+      # Get next reset time as Time object
+      #
+      # @return [Time, nil]
+      def next_reset_at
+        return nil unless next_character_count_reset_unix
+
+        Time.at(next_character_count_reset_unix)
+      end
+
+      # Check if subscription is active
+      #
+      # @return [Boolean]
+      def active?
+        status == 'active'
+      end
+
+      # Check if this is a free tier
+      #
+      # @return [Boolean]
+      def free?
+        tier&.downcase == 'free'
+      end
+    end
+  end
+end

data/lib/eleven_rb/objects/user_info.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Objects
+    # Represents user account information
+    class UserInfo < Base
+      attribute :user_id
+      attribute :email
+      attribute :first_name
+      attribute :is_new_user, type: :boolean
+      attribute :xi_api_key
+      attribute :can_use_delayed_payment_methods, type: :boolean
+      attribute :is_onboarding_completed, type: :boolean
+      attribute :is_onboarding_checklist_completed, type: :boolean
+
+      # Get full display name
+      #
+      # @return [String]
+      def display_name
+        first_name || email&.split('@')&.first || 'User'
+      end
+    end
+  end
+end

data/lib/eleven_rb/objects/voice.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Objects
+    # Represents an ElevenLabs voice
+    class Voice < Base
+      attribute :voice_id
+      attribute :name
+      attribute :description
+      attribute :category
+      attribute :preview_url
+      attribute :labels
+      attribute :settings, type: VoiceSettings
+      attribute :samples
+      attribute :sharing
+      attribute :high_quality_base_model_ids
+      attribute :safety_control
+
+      # Get the gender from labels
+      #
+      # @return [String, nil]
+      def gender
+        labels&.dig('gender')
+      end
+
+      # Get the accent from labels
+      #
+      # @return [String, nil]
+      def accent
+        labels&.dig('accent')
+      end
+
+      # Get the language from labels
+      #
+      # @return [String, nil]
+      def language
+        labels&.dig('language')
+      end
+
+      # Get the age from labels
+      #
+      # @return [String, nil]
+      def age
+        labels&.dig('age')
+      end
+
+      # Get the use case from labels
+      #
+      # @return [String, nil]
+      def use_case
+        labels&.dig('use_case')
+      end
+
+      # Check if this voice is banned
+      #
+      # @return [Boolean]
+      def banned?
+        safety_control == 'BAN'
+      end
+
+      # Provider identifier for wrapper compatibility
+      #
+      # @return [Symbol]
+      def provider
+        :elevenlabs
+      end
+
+      # Alias for voice_id for wrapper compatibility
+      #
+      # @return [String]
+      def provider_voice_id
+        voice_id
+      end
+
+      # Human-readable display name with metadata
+      #
+      # @return [String]
+      def display_name
+        parts = [name]
+        parts << "(#{gender})" if gender
+        parts << "- #{accent || language}" if accent || language
+        parts.join(' ')
+      end
+    end
+  end
+end

data/lib/eleven_rb/objects/voice_settings.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Objects
+    # Voice settings for TTS generation
+    class VoiceSettings < Base
+      attribute :stability
+      attribute :similarity_boost
+      attribute :style
+      attribute :use_speaker_boost, type: :boolean
+
+      # Default settings for TTS generation
+      DEFAULTS = {
+        stability: 0.5,
+        similarity_boost: 0.75,
+        style: 0.0,
+        use_speaker_boost: true
+      }.freeze
+
+      # Create settings with defaults merged in
+      #
+      # @param overrides [Hash] settings to override defaults
+      # @return [VoiceSettings]
+      def self.with_defaults(overrides = {})
+        from_response(DEFAULTS.merge(overrides))
+      end
+
+      # Convert to hash suitable for API request
+      #
+      # @return [Hash]
+      def to_api_hash
+        {
+          stability: stability,
+          similarity_boost: similarity_boost,
+          style: style,
+          use_speaker_boost: use_speaker_boost
+        }.compact
+      end
+    end
+  end
+end

data/lib/eleven_rb/resources/base.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Base class for API resources
+    class Base
+      attr_reader :http_client
+
+      # Initialize resource
+      #
+      # @param http_client [HTTP::Client]
+      def initialize(http_client)
+        @http_client = http_client
+      end
+
+      private
+
+      # Make a GET request
+      #
+      # @param path [String]
+      # @param params [Hash]
+      # @return [Hash, Array]
+      def get(path, params = {})
+        http_client.get(path, params)
+      end
+
+      # Make a POST request
+      #
+      # @param path [String]
+      # @param body [Hash]
+      # @param response_type [Symbol]
+      # @return [Hash, Array, String]
+      def post(path, body = {}, response_type: :json)
+        http_client.post(path, body, response_type: response_type)
+      end
+
+      # Make a DELETE request
+      #
+      # @param path [String]
+      # @return [Hash]
+      def delete(path)
+        http_client.delete(path)
+      end
+
+      # Make a binary POST request
+      #
+      # @param path [String]
+      # @param body [Hash]
+      # @return [String]
+      def post_binary(path, body = {})
+        http_client.post(path, body, response_type: :binary)
+      end
+
+      # Make a streaming POST request
+      #
+      # @param path [String]
+      # @param body [Hash]
+      # @yield [String] chunk
+      def post_stream(path, body = {}, &block)
+        http_client.post_stream(path, body, &block)
+      end
+
+      # Make a multipart POST request
+      #
+      # @param path [String]
+      # @param params [Hash]
+      # @return [Hash]
+      def post_multipart(path, params)
+        http_client.post_multipart(path, params)
+      end
+
+      # Validate presence of a value
+      #
+      # @param value [Object]
+      # @param name [String]
+      # @raise [Errors::ValidationError]
+      def validate_presence!(value, name)
+        return unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+        raise Errors::ValidationError, "#{name} cannot be blank"
+      end
+    end
+  end
+end

data/lib/eleven_rb/resources/models.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Models resource
+    #
+    # @example List all models
+    #   models = client.models.list
+    #
+    # @example Find multilingual models
+    #   client.models.multilingual
+    class Models < Base
+      # List all available models
+      #
+      # @return [Array<Objects::Model>]
+      def list
+        response = get('/models')
+        response.map { |m| Objects::Model.from_response(m) }
+      end
+
+      # Get a specific model by ID
+      #
+      # @param model_id [String] the model ID
+      # @return [Objects::Model, nil]
+      def get(model_id)
+        list.find { |m| m.model_id == model_id }
+      end
+
+      # Get all multilingual models
+      #
+      # @return [Array<Objects::Model>]
+      def multilingual
+        list.select(&:multilingual?)
+      end
+
+      # Get all turbo/fast models
+      #
+      # @return [Array<Objects::Model>]
+      def turbo
+        list.select(&:turbo?)
+      end
+
+      # Get models that support TTS
+      #
+      # @return [Array<Objects::Model>]
+      def tts_capable
+        list.select(&:can_do_text_to_speech)
+      end
+
+      # Get the default/recommended model for TTS
+      #
+      # @return [Objects::Model, nil]
+      def default
+        get('eleven_multilingual_v2') || tts_capable.first
+      end
+
+      # Get model IDs as array
+      #
+      # @return [Array<String>]
+      def ids
+        list.map(&:model_id)
+      end
+    end
+  end
+end