exa-ai 0.3.1 → 0.4.1

data/lib/exa/services/websets/create_search.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "create_search_validator"
+
+module Exa
+  module Services
+    module Websets
+      class CreateSearch
+        def initialize(connection, webset_id:, **params)
+          @connection = connection
+          @webset_id = webset_id
+          @params = params
+        end
+
+        def call
+          CreateSearchValidator.validate!(@params)
+
+          response = @connection.post(
+            "/websets/v0/websets/#{@webset_id}/searches",
+            @params
+          )
+          body = response.body
+
+          Resources::WebsetSearch.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            query: body["query"],
+            entity: body["entity"],
+            criteria: body["criteria"],
+            count: body["count"],
+            behavior: body["behavior"],
+            exclude: body["exclude"],
+            scope: body["scope"],
+            progress: body["progress"],
+            recall: body["recall"],
+            metadata: body["metadata"],
+            canceled_at: body["canceledAt"],
+            canceled_reason: body["canceledReason"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/create_search_validator.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      # Validates parameters for webset search creation
+      class CreateSearchValidator
+        VALID_ENTITY_TYPES = %w[company person article research_paper custom].freeze
+        VALID_BEHAVIORS = %w[override append].freeze
+        VALID_SOURCE_TYPES = %w[import webset].freeze
+
+        class << self
+          def validate!(params)
+            validate_query!(params[:query]) if params[:query]
+            validate_count!(params[:count]) if params[:count]
+            validate_entity!(params[:entity]) if params[:entity]
+            validate_criteria!(params[:criteria]) if params[:criteria]
+            validate_scope!(params[:scope]) if params[:scope]
+            validate_exclude!(params[:exclude]) if params[:exclude]
+            validate_behavior!(params[:behavior]) if params[:behavior]
+            validate_metadata!(params[:metadata]) if params[:metadata]
+          end
+
+          private
+
+          def validate_query!(query)
+            raise ArgumentError, "query must be a String" unless query.is_a?(String)
+            raise ArgumentError, "query cannot be empty" if query.strip.empty?
+            raise ArgumentError, "query cannot exceed 5000 characters" if query.length > 5000
+          end
+
+          def validate_count!(count)
+            raise ArgumentError, "count must be a positive Integer" unless count.is_a?(Integer) && count > 0
+          end
+
+          def validate_entity!(entity)
+            raise ArgumentError, "entity must be a Hash" unless entity.is_a?(Hash)
+            raise ArgumentError, "entity[:type] is required" unless entity[:type]
+
+            type = entity[:type]
+            unless VALID_ENTITY_TYPES.include?(type)
+              raise ArgumentError, "entity[:type] must be one of: #{VALID_ENTITY_TYPES.join(', ')}"
+            end
+
+            if type == "custom"
+              raise ArgumentError, "entity[:description] is required for custom entity type" unless entity[:description]
+              validate_string_length!(entity[:description], "entity[:description]", min: 2, max: 200)
+            end
+          end
+
+          def validate_criteria!(criteria)
+            raise ArgumentError, "criteria must be an Array" unless criteria.is_a?(Array)
+            raise ArgumentError, "criteria must have at least 1 item" if criteria.empty?
+            raise ArgumentError, "criteria cannot have more than 5 items" if criteria.length > 5
+
+            criteria.each_with_index do |criterion, index|
+              raise ArgumentError, "criteria[#{index}] must be a Hash" unless criterion.is_a?(Hash)
+              raise ArgumentError, "criteria[#{index}][:description] is required" unless criterion[:description]
+              validate_string_length!(criterion[:description], "criteria[#{index}][:description]", min: 1, max: 1000)
+            end
+          end
+
+          def validate_scope!(scope)
+            raise ArgumentError, "scope must be an Array" unless scope.is_a?(Array)
+
+            scope.each_with_index do |item, index|
+              validate_source_reference!(item, "scope[#{index}]")
+
+              next unless item[:relationship]
+
+              rel = item[:relationship]
+              raise ArgumentError, "scope[#{index}][:relationship] must be a Hash" unless rel.is_a?(Hash)
+              raise ArgumentError, "scope[#{index}][:relationship][:definition] is required" unless rel[:definition]
+              raise ArgumentError, "scope[#{index}][:relationship][:limit] is required" unless rel[:limit]
+
+              limit = rel[:limit]
+              unless limit.is_a?(Integer) && limit >= 1 && limit <= 10
+                raise ArgumentError, "scope[#{index}][:relationship][:limit] must be an Integer between 1 and 10"
+              end
+            end
+          end
+
+          def validate_exclude!(exclude)
+            raise ArgumentError, "exclude must be an Array" unless exclude.is_a?(Array)
+
+            exclude.each_with_index do |item, index|
+              validate_source_reference!(item, "exclude[#{index}]")
+            end
+          end
+
+          def validate_behavior!(behavior)
+            unless VALID_BEHAVIORS.include?(behavior)
+              raise ArgumentError, "behavior must be one of: #{VALID_BEHAVIORS.join(', ')}"
+            end
+          end
+
+          def validate_metadata!(metadata)
+            raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
+            metadata.each do |key, value|
+              raise ArgumentError, "metadata values must be Strings" unless value.is_a?(String)
+              raise ArgumentError, "metadata value for '#{key}' cannot exceed 1000 characters" if value.length > 1000
+            end
+          end
+
+          def validate_source_reference!(item, context)
+            raise ArgumentError, "#{context} must be a Hash" unless item.is_a?(Hash)
+            raise ArgumentError, "#{context}[:source] is required" unless item[:source]
+            raise ArgumentError, "#{context}[:id] is required" unless item[:id]
+
+            source = item[:source]
+            unless VALID_SOURCE_TYPES.include?(source)
+              raise ArgumentError, "#{context}[:source] must be one of: #{VALID_SOURCE_TYPES.join(', ')}"
+            end
+
+            raise ArgumentError, "#{context}[:id] must be a non-empty String" unless item[:id].is_a?(String) && !item[:id].empty?
+          end
+
+          def validate_string_length!(value, name, min: nil, max: nil)
+            raise ArgumentError, "#{name} must be a String" unless value.is_a?(String)
+            raise ArgumentError, "#{name} must be at least #{min} characters" if min && value.length < min
+            raise ArgumentError, "#{name} cannot exceed #{max} characters" if max && value.length > max
+          end
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/create_validator.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      # Validates parameters for webset creation
+      class CreateValidator
+        VALID_ENTITY_TYPES = %w[company person article research_paper custom].freeze
+        VALID_ENRICHMENT_FORMATS = %w[text date number options url].freeze
+        VALID_SOURCE_TYPES = %w[import webset].freeze
+
+        class << self
+          def validate!(params)
+            validate_has_search_or_import!(params)
+            validate_search!(params[:search]) if params[:search]
+            validate_import!(params[:import]) if params[:import]
+            validate_enrichments!(params[:enrichments]) if params[:enrichments]
+            validate_exclude!(params[:exclude]) if params[:exclude]
+            validate_external_id!(params[:externalId]) if params[:externalId]
+            validate_metadata!(params[:metadata]) if params[:metadata]
+          end
+
+          private
+
+          def validate_has_search_or_import!(params)
+            return if params[:search] || params[:import]
+
+            raise ArgumentError, "At least one of :search or :import is required"
+          end
+
+          def validate_search!(search)
+            raise ArgumentError, "search must be a Hash" unless search.is_a?(Hash)
+            raise ArgumentError, "search[:query] is required" unless search[:query]
+            raise ArgumentError, "search[:query] must be a String" unless search[:query].is_a?(String)
+            raise ArgumentError, "search[:query] cannot be empty" if search[:query].strip.empty?
+            raise ArgumentError, "search[:query] cannot exceed 5000 characters" if search[:query].length > 5000
+
+            validate_count!(search[:count]) if search[:count]
+            validate_entity!(search[:entity]) if search[:entity]
+            validate_criteria!(search[:criteria]) if search[:criteria]
+            validate_scope!(search[:scope]) if search[:scope]
+            validate_exclude_list!(search[:exclude]) if search[:exclude]
+          end
+
+          def validate_count!(count)
+            raise ArgumentError, "count must be a positive Integer" unless count.is_a?(Integer) && count > 0
+          end
+
+          def validate_entity!(entity)
+            raise ArgumentError, "entity must be a Hash" unless entity.is_a?(Hash)
+            raise ArgumentError, "entity[:type] is required" unless entity[:type]
+
+            type = entity[:type]
+            unless VALID_ENTITY_TYPES.include?(type)
+              raise ArgumentError, "entity[:type] must be one of: #{VALID_ENTITY_TYPES.join(', ')}"
+            end
+
+            if type == "custom"
+              raise ArgumentError, "entity[:description] is required for custom entity type" unless entity[:description]
+              validate_string_length!(entity[:description], "entity[:description]", min: 2, max: 200)
+            end
+          end
+
+          def validate_criteria!(criteria)
+            raise ArgumentError, "criteria must be an Array" unless criteria.is_a?(Array)
+            raise ArgumentError, "criteria must have at least 1 item" if criteria.empty?
+            raise ArgumentError, "criteria cannot have more than 5 items" if criteria.length > 5
+
+            criteria.each_with_index do |criterion, index|
+              raise ArgumentError, "criteria[#{index}] must be a Hash" unless criterion.is_a?(Hash)
+              raise ArgumentError, "criteria[#{index}][:description] is required" unless criterion[:description]
+              validate_string_length!(criterion[:description], "criteria[#{index}][:description]", min: 1, max: 1000)
+            end
+          end
+
+          def validate_scope!(scope)
+            raise ArgumentError, "scope must be an Array" unless scope.is_a?(Array)
+
+            scope.each_with_index do |item, index|
+              validate_source_reference!(item, "scope[#{index}]")
+
+              next unless item[:relationship]
+
+              rel = item[:relationship]
+              raise ArgumentError, "scope[#{index}][:relationship] must be a Hash" unless rel.is_a?(Hash)
+              raise ArgumentError, "scope[#{index}][:relationship][:definition] is required" unless rel[:definition]
+              raise ArgumentError, "scope[#{index}][:relationship][:limit] is required" unless rel[:limit]
+
+              limit = rel[:limit]
+              unless limit.is_a?(Integer) && limit >= 1 && limit <= 10
+                raise ArgumentError, "scope[#{index}][:relationship][:limit] must be an Integer between 1 and 10"
+              end
+            end
+          end
+
+          def validate_exclude_list!(exclude)
+            raise ArgumentError, "exclude must be an Array" unless exclude.is_a?(Array)
+
+            exclude.each_with_index do |item, index|
+              validate_source_reference!(item, "exclude[#{index}]")
+            end
+          end
+
+          def validate_import!(import)
+            raise ArgumentError, "import must be an Array" unless import.is_a?(Array)
+
+            import.each_with_index do |item, index|
+              validate_source_reference!(item, "import[#{index}]")
+            end
+          end
+
+          def validate_enrichments!(enrichments)
+            raise ArgumentError, "enrichments must be an Array" unless enrichments.is_a?(Array)
+
+            enrichments.each_with_index do |enrichment, index|
+              raise ArgumentError, "enrichments[#{index}] must be a Hash" unless enrichment.is_a?(Hash)
+              raise ArgumentError, "enrichments[#{index}][:description] is required" unless enrichment[:description]
+              validate_string_length!(enrichment[:description], "enrichments[#{index}][:description]", min: 1, max: 5000)
+
+              if enrichment[:format]
+                format = enrichment[:format]
+                unless VALID_ENRICHMENT_FORMATS.include?(format)
+                  raise ArgumentError, "enrichments[#{index}][:format] must be one of: #{VALID_ENRICHMENT_FORMATS.join(', ')}"
+                end
+
+                if format == "options"
+                  validate_enrichment_options!(enrichment[:options], index)
+                end
+              end
+            end
+          end
+
+          def validate_enrichment_options!(options, enrichment_index)
+            unless options.is_a?(Array)
+              raise ArgumentError, "enrichments[#{enrichment_index}][:options] is required when format is 'options'"
+            end
+
+            if options.empty? || options.length > 150
+              raise ArgumentError, "enrichments[#{enrichment_index}][:options] must have between 1 and 150 items"
+            end
+
+            options.each_with_index do |option, option_index|
+              unless option.is_a?(Hash) && option[:label]
+                raise ArgumentError, "enrichments[#{enrichment_index}][:options][#{option_index}][:label] is required"
+              end
+            end
+          end
+
+          def validate_exclude!(exclude)
+            validate_exclude_list!(exclude)
+          end
+
+          def validate_external_id!(external_id)
+            raise ArgumentError, "externalId must be a String" unless external_id.is_a?(String)
+            raise ArgumentError, "externalId cannot exceed 300 characters" if external_id.length > 300
+          end
+
+          def validate_metadata!(metadata)
+            raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
+            metadata.each do |key, value|
+              raise ArgumentError, "metadata values must be Strings" unless value.is_a?(String)
+              raise ArgumentError, "metadata value for '#{key}' cannot exceed 1000 characters" if value.length > 1000
+            end
+          end
+
+          def validate_source_reference!(item, context)
+            raise ArgumentError, "#{context} must be a Hash" unless item.is_a?(Hash)
+            raise ArgumentError, "#{context}[:source] is required" unless item[:source]
+            raise ArgumentError, "#{context}[:id] is required" unless item[:id]
+
+            source = item[:source]
+            unless VALID_SOURCE_TYPES.include?(source)
+              raise ArgumentError, "#{context}[:source] must be one of: #{VALID_SOURCE_TYPES.join(', ')}"
+            end
+
+            raise ArgumentError, "#{context}[:id] must be a non-empty String" unless item[:id].is_a?(String) && !item[:id].empty?
+          end
+
+          def validate_string_length!(value, name, min: nil, max: nil)
+            raise ArgumentError, "#{name} must be a String" unless value.is_a?(String)
+            raise ArgumentError, "#{name} must be at least #{min} characters" if min && value.length < min
+            raise ArgumentError, "#{name} cannot exceed #{max} characters" if max && value.length > max
+          end
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/delete.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class Delete
+        def initialize(connection, id:)
+          @connection = connection
+          @id = id
+        end
+
+        def call
+          response = @connection.delete("/websets/v0/websets/#{@id}")
+          body = response.body
+
+          Resources::Webset.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            external_id: body["externalId"],
+            title: body["title"],
+            searches: body["searches"],
+            imports: body["imports"],
+            enrichments: body["enrichments"],
+            monitors: body["monitors"],
+            excludes: body["excludes"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            items: body["items"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/delete_enrichment.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class DeleteEnrichment
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          response = @connection.delete("/websets/v0/websets/#{@webset_id}/enrichments/#{@id}")
+          body = response.body
+
+          Resources::WebsetEnrichment.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            title: body["title"],
+            description: body["description"],
+            format: body["format"],
+            options: body["options"],
+            instructions: body["instructions"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/delete_item.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class DeleteItem
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          @connection.delete("/websets/v0/websets/#{@webset_id}/items/#{@id}")
+          true
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/get_item.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class GetItem
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          response = @connection.get("/websets/v0/websets/#{@webset_id}/items/#{@id}")
+          response.body
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/get_search.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class GetSearch
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          response = @connection.get(
+            "/websets/v0/websets/#{@webset_id}/searches/#{@id}"
+          )
+          body = response.body
+
+          Resources::WebsetSearch.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            query: body["query"],
+            entity: body["entity"],
+            criteria: body["criteria"],
+            count: body["count"],
+            behavior: body["behavior"],
+            exclude: body["exclude"],
+            scope: body["scope"],
+            progress: body["progress"],
+            recall: body["recall"],
+            metadata: body["metadata"],
+            canceled_at: body["canceledAt"],
+            canceled_reason: body["canceledReason"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/list.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class List
+        def initialize(connection, **params)
+          @connection = connection
+          @params = params
+        end
+
+        def call
+          response = @connection.get("/websets/v0/websets", @params)
+          body = response.body
+
+          Resources::WebsetCollection.new(
+            data: body["data"],
+            has_more: body["hasMore"],
+            next_cursor: body["nextCursor"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/list_items.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class ListItems
+        def initialize(connection, webset_id:)
+          @connection = connection
+          @webset_id = webset_id
+        end
+
+        def call
+          response = @connection.get("/websets/v0/websets/#{@webset_id}/items")
+          body = response.body
+          body["data"] || []
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/retrieve.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class Retrieve
+        def initialize(connection, id:, **params)
+          @connection = connection
+          @id = id
+          @params = normalize_params(params)
+        end
+
+        def call
+          response = @connection.get("/websets/v0/websets/#{@id}", @params)
+          body = response.body
+
+          Resources::Webset.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            external_id: body["externalId"],
+            title: body["title"],
+            searches: body["searches"],
+            imports: body["imports"],
+            enrichments: body["enrichments"],
+            monitors: body["monitors"],
+            excludes: body["excludes"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            items: body["items"]
+          )
+        end
+
+        private
+
+        def normalize_params(params)
+          # Convert expand array to comma-separated string for API compatibility
+          if params[:expand].is_a?(Array)
+            params[:expand] = params[:expand].join(",")
+          end
+          params
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/retrieve_enrichment.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class RetrieveEnrichment
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          response = @connection.get("/websets/v0/websets/#{@webset_id}/enrichments/#{@id}")
+          body = response.body
+
+          Resources::WebsetEnrichment.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            title: body["title"],
+            description: body["description"],
+            format: body["format"],
+            options: body["options"],
+            instructions: body["instructions"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end