exaonruby 1.0.0

data/lib/exa/endpoints/websets.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Websets
+      VALID_ENTITY_TYPES = %w[company person research_paper].freeze
+      VALID_ENRICHMENT_FORMATS = %w[text enum number boolean date].freeze
+
+      # Creates a new Webset with optional search, import, and enrichment configurations
+      #
+      # The Webset will automatically begin processing once created.
+      #
+      # @param search [Hash] Optional search configuration
+      # @option search [String] :query Search query
+      # @option search [Integer] :count Target number of results (default 10)
+      # @option search [Hash] :entity Entity type configuration { type: "company"|"person"|"research_paper" }
+      # @option search [Array<Hash>] :criteria Criteria for filtering [{ description: "..." }]
+      # @option search [Boolean] :recall Enable recall estimation
+      # @option search [Array<Hash>] :exclude Exclusion rules
+      # @option search [Array<Hash>] :scope Scope configuration
+      #
+      # @param import [Array<Hash>] Optional import sources to attach
+      # @param enrichments [Array<Hash>] Optional enrichments to add
+      # @option enrichments [String] :description What to extract
+      # @option enrichments [String] :format Format: text, enum, number, boolean, date
+      # @option enrichments [Array<Hash>] :options Options for enum format
+      #
+      # @param exclude [Array<Hash>] Global exclusion sources
+      # @param external_id [String] External identifier for the Webset
+      # @param metadata [Hash] Custom metadata key-value pairs
+      #
+      # @return [Exa::Resources::Webset] Created Webset
+      #
+      # @example Create a basic Webset with search
+      #   client.create_webset(
+      #     search: {
+      #       query: "AI startups founded in 2024",
+      #       count: 50,
+      #       entity: { type: "company" },
+      #       criteria: [{ description: "Company must be focused on artificial intelligence" }]
+      #     }
+      #   )
+      #
+      # @example Create a Webset with enrichments
+      #   client.create_webset(
+      #     search: { query: "Series A startups", entity: { type: "company" } },
+      #     enrichments: [
+      #       { description: "Company's total funding amount", format: "number" },
+      #       { description: "Company's industry", format: "text" }
+      #     ]
+      #   )
+      def create_webset(**options)
+        validate_webset_options!(options)
+
+        params = build_webset_params(options)
+        response = websets_post("/websets", params)
+
+        Resources::Webset.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Retrieves a Webset by ID or external ID
+      #
+      # @param id [String] Webset ID or external ID
+      # @return [Exa::Resources::Webset] The Webset
+      #
+      # @raise [Exa::NotFoundError] if Webset not found
+      #
+      # @example Get a Webset
+      #   webset = client.get_webset("webset_abc123")
+      def get_webset(id)
+        raise InvalidRequestError, "id must be a non-empty string" if !id.is_a?(String) || id.empty?
+
+        response = websets_get("/websets/#{id}")
+
+        Resources::Webset.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Lists all Websets with pagination
+      #
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page (1-100)
+      #
+      # @return [Exa::Resources::WebsetsListResponse] Paginated list of Websets
+      #
+      # @example List all Websets
+      #   response = client.list_websets
+      #   response.data.each { |webset| puts webset.title }
+      #
+      # @example Paginate through Websets
+      #   response = client.list_websets(limit: 10)
+      #   while response.has_more?
+      #     response = client.list_websets(cursor: response.next_cursor, limit: 10)
+      #   end
+      def list_websets(cursor: nil, limit: nil)
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+
+        response = websets_get("/websets", params)
+
+        Resources::WebsetsListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Deletes a Webset and all its Items
+      #
+      # @param id [String] Webset ID to delete
+      # @return [Exa::Resources::Webset] The deleted Webset
+      #
+      # @raise [Exa::NotFoundError] if Webset not found
+      #
+      # @example Delete a Webset
+      #   client.delete_webset("webset_abc123")
+      def delete_webset(id)
+        raise InvalidRequestError, "id must be a non-empty string" if !id.is_a?(String) || id.empty?
+
+        response = websets_delete("/websets/#{id}")
+
+        Resources::Webset.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      # @param options [Hash] Options to validate
+      # @raise [Exa::InvalidRequestError] if validation fails
+      def validate_webset_options!(options)
+        if options[:search]
+          validate_search_config!(options[:search])
+        end
+
+        if options[:enrichments]
+          options[:enrichments].each { |e| validate_enrichment_config!(e) }
+        end
+      end
+
+      # @param search [Hash] Search configuration to validate
+      def validate_search_config!(search)
+        if search[:entity] && search[:entity][:type]
+          entity_type = search[:entity][:type].to_s
+          unless VALID_ENTITY_TYPES.include?(entity_type)
+            raise InvalidRequestError, "Invalid entity type: #{entity_type}. Valid types: #{VALID_ENTITY_TYPES.join(", ")}"
+          end
+        end
+
+        if search[:count] && (search[:count] < 1 || search[:count] > 10_000)
+          raise InvalidRequestError, "count must be between 1 and 10000"
+        end
+      end
+
+      # @param enrichment [Hash] Enrichment configuration to validate
+      def validate_enrichment_config!(enrichment)
+        return unless enrichment[:format]
+
+        format = enrichment[:format].to_s
+        unless VALID_ENRICHMENT_FORMATS.include?(format)
+          raise InvalidRequestError, "Invalid enrichment format: #{format}. Valid formats: #{VALID_ENRICHMENT_FORMATS.join(", ")}"
+        end
+      end
+
+      # @param options [Hash] Webset creation options
+      # @return [Hash] API-formatted parameters
+      def build_webset_params(options)
+        params = {}
+
+        params[:search] = build_search_config(options[:search]) if options[:search]
+        params[:import] = options[:import] if options[:import]
+        params[:enrichments] = options[:enrichments].map { |e| build_enrichment_config(e) } if options[:enrichments]
+        params[:exclude] = options[:exclude] if options[:exclude]
+        params[:externalId] = options[:external_id] if options[:external_id]
+        params[:metadata] = options[:metadata] if options[:metadata]
+
+        params
+      end
+
+      # @param search [Hash] Search configuration
+      # @return [Hash] API-formatted search config
+      def build_search_config(search)
+        config = {}
+
+        config[:query] = search[:query] if search[:query]
+        config[:count] = search[:count] if search[:count]
+        config[:entity] = search[:entity] if search[:entity]
+        config[:criteria] = search[:criteria] if search[:criteria]
+        config[:recall] = search[:recall] if search.key?(:recall)
+        config[:exclude] = search[:exclude] if search[:exclude]
+        config[:scope] = search[:scope] if search[:scope]
+
+        config
+      end
+
+      # @param enrichment [Hash] Enrichment configuration
+      # @return [Hash] API-formatted enrichment config
+      def build_enrichment_config(enrichment)
+        config = {}
+
+        config[:description] = enrichment[:description] if enrichment[:description]
+        config[:format] = enrichment[:format] if enrichment[:format]
+        config[:options] = enrichment[:options] if enrichment[:options]
+        config[:metadata] = enrichment[:metadata] if enrichment[:metadata]
+
+        config
+      end
+    end
+  end
+end

data/lib/exa/errors.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  class Error < StandardError
+    # @return [Integer, nil] HTTP status code if applicable
+    attr_reader :status
+
+    # @return [Hash, nil] Response body if available
+    attr_reader :response_body
+
+    # @return [String, nil] Request ID for debugging
+    attr_reader :request_id
+
+    # @param message [String] Error message
+    # @param status [Integer, nil] HTTP status code
+    # @param response_body [Hash, nil] Parsed response body
+    # @param request_id [String, nil] Request ID from response
+    def initialize(message = nil, status: nil, response_body: nil, request_id: nil)
+      @status = status
+      @response_body = response_body
+      @request_id = request_id
+      super(message)
+    end
+
+    # @return [String] Formatted error message with details
+    def to_s
+      parts = [super]
+      parts << "(status: #{status})" if status
+      parts << "(request_id: #{request_id})" if request_id
+      parts.join(" ")
+    end
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class RateLimitError < Error
+    # @return [Integer, nil] Seconds until rate limit resets
+    attr_reader :retry_after
+
+    # @param message [String] Error message
+    # @param retry_after [Integer, nil] Seconds until retry
+    # @param kwargs [Hash] Additional error options
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      @retry_after = retry_after
+      super(message, **kwargs)
+    end
+  end
+
+  class InvalidRequestError < Error
+    # @return [Array<Hash>, nil] Validation errors if available
+    attr_reader :validation_errors
+
+    # @param message [String] Error message
+    # @param validation_errors [Array<Hash>, nil] List of validation errors
+    # @param kwargs [Hash] Additional error options
+    def initialize(message = nil, validation_errors: nil, **kwargs)
+      @validation_errors = validation_errors
+      super(message, **kwargs)
+    end
+  end
+
+  class NotFoundError < Error
+  end
+
+  class ConflictError < Error
+  end
+
+  class UnprocessableEntityError < Error
+  end
+
+  class ServerError < Error
+  end
+
+  class ServiceUnavailableError < ServerError
+  end
+
+  class TimeoutError < Error
+  end
+
+  class ConnectionError < Error
+  end
+
+  class << self
+    # Maps HTTP status codes to appropriate error classes
+    # @param status [Integer] HTTP status code
+    # @param message [String, nil] Error message
+    # @param response_body [Hash, nil] Response body
+    # @param headers [Hash, nil] Response headers
+    # @return [Exa::Error] Appropriate error instance
+    def error_for_status(status, message: nil, response_body: nil, headers: nil)
+      request_id = response_body&.dig("requestId")
+      error_message = message || extract_error_message(response_body)
+
+      case status
+      when 400
+        validation_errors = response_body&.dig("errors")
+        InvalidRequestError.new(
+          error_message,
+          status: status,
+          response_body: response_body,
+          request_id: request_id,
+          validation_errors: validation_errors
+        )
+      when 401
+        AuthenticationError.new(
+          error_message || "Invalid API key",
+          status: status,
+          response_body: response_body,
+          request_id: request_id
+        )
+      when 404
+        NotFoundError.new(
+          error_message || "Resource not found",
+          status: status,
+          response_body: response_body,
+          request_id: request_id
+        )
+      when 409
+        ConflictError.new(
+          error_message,
+          status: status,
+          response_body: response_body,
+          request_id: request_id
+        )
+      when 422
+        UnprocessableEntityError.new(
+          error_message,
+          status: status,
+          response_body: response_body,
+          request_id: request_id
+        )
+      when 429
+        retry_after = headers&.dig("retry-after")&.to_i
+        RateLimitError.new(
+          error_message || "Rate limit exceeded",
+          status: status,
+          response_body: response_body,
+          request_id: request_id,
+          retry_after: retry_after
+        )
+      when 500
+        ServerError.new(
+          error_message || "Internal server error",
+          status: status,
+          response_body: response_body,
+          request_id: request_id
+        )
+      when 503
+        ServiceUnavailableError.new(
+          error_message || "Service temporarily unavailable",
+          status: status,
+          response_body: response_body,
+          request_id: request_id
+        )
+      else
+        Error.new(
+          error_message || "HTTP #{status} error",
+          status: status,
+          response_body: response_body,
+          request_id: request_id
+        )
+      end
+    end
+
+    private
+
+    # @param response_body [Hash, nil] Response body to extract message from
+    # @return [String, nil] Extracted error message
+    def extract_error_message(response_body)
+      return nil unless response_body.is_a?(Hash)
+
+      response_body["message"] ||
+        response_body["error"] ||
+        response_body.dig("error", "message")
+    end
+  end
+end

data/lib/exa/resources/answer_response.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class AnswerResponse < Base
+      # @return [String] The generated answer based on search results
+      def answer
+        get(:answer)
+      end
+
+      # @return [Array<Citation>] Search results used to generate the answer
+      def citations
+        @citations ||= (get(:citations, []) || []).map { |data| Citation.new(data) }
+      end
+
+      # @return [CostInfo, nil] Cost information for the request
+      def cost
+        cost_data = get(:cost_dollars)
+        return nil unless cost_data
+
+        CostInfo.new(cost_data)
+      end
+
+      # @return [Float] Total cost in dollars
+      def total_cost
+        cost&.total || 0.0
+      end
+
+      # @return [Integer] Number of citations
+      def citation_count
+        citations.length
+      end
+
+      # @return [Boolean] Whether answer has citations
+      def has_citations?
+        !citations.empty?
+      end
+
+      private
+
+      def inspectable_attributes
+        { answer: answer&.slice(0, 50), citation_count: citation_count }
+      end
+    end
+
+    class Citation < Base
+      # @return [String] Unique identifier
+      def id
+        get(:id)
+      end
+
+      # @return [String] URL of the source
+      def url
+        get(:url)
+      end
+
+      # @return [String] Title of the source
+      def title
+        get(:title)
+      end
+
+      # @return [String, nil] Author of the source
+      def author
+        get(:author)
+      end
+
+      # @return [Time, nil] Published date
+      def published_date
+        date_str = get(:published_date)
+        return nil unless date_str
+
+        Time.parse(date_str)
+      rescue ArgumentError
+        nil
+      end
+
+      # @return [String, nil] Text content from the source
+      def text
+        get(:text)
+      end
+
+      # @return [String, nil] Image URL
+      def image
+        get(:image)
+      end
+
+      # @return [String, nil] Favicon URL
+      def favicon
+        get(:favicon)
+      end
+
+      private
+
+      def inspectable_attributes
+        { url: url, title: title }
+      end
+    end
+  end
+end

data/lib/exa/resources/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class Base
+      # @return [Hash] Raw response data
+      attr_reader :raw_data
+
+      # @param data [Hash] Response data from API
+      def initialize(data)
+        @raw_data = data.freeze
+      end
+
+      # @return [String] String representation
+      def to_s
+        "#<#{self.class.name}>"
+      end
+
+      # @return [String] Inspect representation
+      def inspect
+        "#<#{self.class.name} #{inspectable_attributes.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}>"
+      end
+
+      # @return [Hash] Hash representation
+      def to_h
+        raw_data
+      end
+
+      alias to_hash to_h
+
+      private
+
+      # @return [Hash] Attributes to include in inspect output
+      def inspectable_attributes
+        {}
+      end
+
+      # Safely retrieves a value from raw_data
+      # @param key [Symbol] Key to retrieve
+      # @param default [Object] Default value if key not found
+      # @return [Object] Value or default
+      def get(key, default = nil)
+        raw_data.fetch(key, default)
+      end
+
+      # Safely retrieves a nested value from raw_data
+      # @param keys [Array<Symbol>] Keys to traverse
+      # @return [Object, nil] Value or nil
+      def dig(*keys)
+        raw_data.dig(*keys)
+      end
+    end
+  end
+end

data/lib/exa/resources/contents_response.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class ContentsResponse < Base
+      # @return [String] Unique request identifier
+      def request_id
+        get(:request_id)
+      end
+
+      # @return [Array<SearchResult>] Content results
+      def results
+        @results ||= (get(:results, []) || []).map { |data| SearchResult.new(data) }
+      end
+
+      # @return [String, nil] Combined context string for LLM consumption
+      def context
+        get(:context)
+      end
+
+      # @return [Array<ContentStatus>] Status information for each URL
+      def statuses
+        @statuses ||= (get(:statuses, []) || []).map { |data| ContentStatus.new(data) }
+      end
+
+      # @return [CostInfo, nil] Cost information
+      def cost
+        cost_data = get(:cost_dollars)
+        return nil unless cost_data
+
+        CostInfo.new(cost_data)
+      end
+
+      # @return [Float] Total cost in dollars
+      def total_cost
+        cost&.total || 0.0
+      end
+
+      # @return [Integer] Number of results
+      def count
+        results.length
+      end
+
+      # @return [Boolean] Whether results are empty
+      def empty?
+        results.empty?
+      end
+
+      # Iterates over each result
+      # @yield [SearchResult] Each result
+      # @return [Enumerator, self]
+      def each(&block)
+        return results.each unless block
+
+        results.each(&block)
+        self
+      end
+
+      # @param index [Integer] Index of result
+      # @return [SearchResult, nil] Result at index
+      def [](index)
+        results[index]
+      end
+
+      # @return [SearchResult, nil] First result
+      def first
+        results.first
+      end
+
+      # Checks if all content fetches were successful
+      # @return [Boolean]
+      def all_success?
+        statuses.all?(&:success?)
+      end
+
+      # Returns results that failed to fetch
+      # @return [Array<ContentStatus>]
+      def failed_statuses
+        statuses.reject(&:success?)
+      end
+
+      private
+
+      def inspectable_attributes
+        { request_id: request_id, count: count }
+      end
+    end
+
+    class ContentStatus < Base
+      # @return [String] URL/ID that was requested
+      def id
+        get(:id)
+      end
+
+      # @return [String] Status of the fetch (success, error)
+      def status
+        get(:status)
+      end
+
+      # @return [Boolean] Whether the fetch was successful
+      def success?
+        status == "success"
+      end
+
+      # @return [Hash, nil] Error information if failed
+      def error
+        get(:error)
+      end
+
+      # @return [String, nil] Error tag if failed
+      def error_tag
+        dig(:error, :tag)
+      end
+
+      # @return [Integer, nil] HTTP status code if failed
+      def http_status_code
+        dig(:error, :http_status_code)
+      end
+    end
+  end
+end