exa-ai 0.4.1 → 0.6.0

data/lib/exa/cli/formatters/webset_formatter.rb

@@ -12,6 +12,8 @@ module Exa
             JSON.pretty_generate(webset.to_h)
           when "text"
             format_as_text(webset)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(webset.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -25,6 +27,8 @@ module Exa
             JSON.pretty_generate(collection.to_h)
           when "text"
             format_collection_as_text(collection)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(collection.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end

data/lib/exa/cli/formatters/webset_item_formatter.rb

@@ -12,6 +12,8 @@ module Exa
             JSON.pretty_generate(item)
           when "text"
             format_as_text(item)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(item)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -25,6 +27,8 @@ module Exa
             JSON.pretty_generate(items)
           when "text"
             format_collection_as_text(items)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(items)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end

data/lib/exa/client.rb

@@ -319,6 +319,143 @@ module Exa
       Services::Websets::ListItems.new(connection, webset_id: webset_id).call
     end
 
+    # List all imports
+    #
+    # @param params [Hash] Pagination parameters
+    # @option params [String] :cursor Cursor for pagination
+    # @option params [Integer] :limit Maximum number of imports to return
+    # @return [Resources::ImportCollection] Paginated list of imports
+    def list_imports(**params)
+      Services::Websets::ListImports.new(connection, **params).call
+    end
+
+    # Create a new import
+    #
+    # @param params [Hash] Import parameters
+    # @option params [Integer] :size Size of the import file
+    # @option params [Integer] :count Number of items to import
+    # @option params [String] :title Import title
+    # @option params [String] :format Import format (e.g., "csv")
+    # @option params [Hash] :entity Entity type specification
+    # @option params [Hash] :metadata Custom metadata
+    # @option params [Hash] :csv CSV-specific configuration
+    # @return [Resources::Import] The newly created import
+    def create_import(**params)
+      Services::Websets::CreateImport.new(connection, **params).call
+    end
+
+    # Upload a file for import (creates import and uploads file)
+    #
+    # @param file_path [String] Path to the file to upload
+    # @param params [Hash] Import parameters
+    # @option params [Integer] :count Number of items to import
+    # @option params [String] :title Import title
+    # @option params [String] :format Import format (e.g., "csv")
+    # @option params [Hash] :entity Entity type specification
+    # @option params [Hash] :metadata Custom metadata
+    # @option params [Hash] :csv CSV-specific configuration
+    # @return [Resources::Import] The created import (file size is inferred automatically)
+    def upload_import(file_path:, **params)
+      Services::Websets::UploadImport.new(connection, file_path: file_path, **params).call
+    end
+
+    # Get a specific import by ID
+    #
+    # @param id [String] Import ID
+    # @return [Resources::Import] The requested import
+    def get_import(id)
+      Services::Websets::GetImport.new(connection, id: id).call
+    end
+
+    # Update an import
+    #
+    # @param id [String] Import ID
+    # @param params [Hash] Update parameters
+    # @option params [String] :title Updated title
+    # @option params [Hash] :metadata Updated metadata
+    # @return [Resources::Import] The updated import
+    def update_import(id, **params)
+      Services::Websets::UpdateImport.new(connection, id: id, **params).call
+    end
+
+    # Delete an import
+    #
+    # @param id [String] Import ID
+    # @return [Resources::Import] The deleted import
+    def delete_import(id)
+      Services::Websets::DeleteImport.new(connection, id: id).call
+    end
+
+    # Create a new monitor for a webset
+    #
+    # @param webset_id [String] Webset ID
+    # @param cadence [Hash] Schedule configuration with :cron and :timezone
+    # @param behavior [Hash] Behavior configuration (type, query, etc.)
+    # @param params [Hash] Additional monitor parameters
+    # @option params [Hash] :metadata Custom metadata
+    # @return [Resources::Monitor] The newly created monitor
+    def create_monitor(webset_id:, cadence:, behavior:, **params)
+      Services::Websets::Monitors::Create.new(connection, webset_id: webset_id, cadence: cadence, behavior: behavior, **params).call
+    end
+
+    # List all monitors
+    #
+    # @param params [Hash] Pagination parameters
+    # @option params [String] :cursor Cursor for pagination
+    # @option params [Integer] :limit Maximum number of monitors to return
+    # @return [Resources::MonitorCollection] Paginated list of monitors
+    def list_monitors(**params)
+      Services::Websets::Monitors::List.new(connection, **params).call
+    end
+
+    # Get a specific monitor by ID
+    #
+    # @param id [String] Monitor ID
+    # @return [Resources::Monitor] The requested monitor
+    def get_monitor(id:)
+      Services::Websets::Monitors::Get.new(connection, id: id).call
+    end
+
+    # Update a monitor
+    #
+    # @param id [String] Monitor ID
+    # @param params [Hash] Update parameters
+    # @option params [Hash] :cadence Updated schedule configuration
+    # @option params [Hash] :behavior Updated behavior configuration
+    # @option params [Hash] :metadata Updated metadata
+    # @return [Resources::Monitor] The updated monitor
+    def update_monitor(id:, **params)
+      Services::Websets::Monitors::Update.new(connection, id: id, **params).call
+    end
+
+    # Delete a monitor
+    #
+    # @param id [String] Monitor ID
+    # @return [Resources::Monitor] The deleted monitor
+    def delete_monitor(id:)
+      Services::Websets::Monitors::Delete.new(connection, id: id).call
+    end
+
+    # List all runs for a specific monitor
+    #
+    # @param monitor_id [String] Monitor ID
+    # @param params [Hash] Pagination parameters
+    # @option params [String] :cursor Cursor for pagination
+    # @option params [Integer] :limit Maximum number of runs to return
+    # @return [Resources::MonitorRunCollection] Paginated list of monitor runs
+    def list_monitor_runs(monitor_id:, **params)
+      Services::Websets::Monitors::Runs::List.new(connection, monitor_id: monitor_id, **params).call
+    end
+
+    # Get a specific monitor run by ID
+    #
+    # @param monitor_id [String] Monitor ID
+    # @param id [String] Run ID
+    # @return [Resources::MonitorRun] The requested monitor run
+    def get_monitor_run(monitor_id:, id:)
+      Services::Websets::Monitors::Runs::Get.new(connection, monitor_id: monitor_id, id: id).call
+    end
+
     private
 
     def connection

data/lib/exa/constants/websets.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Exa
+  module Constants
+    module Websets
+      # Valid entity types for websets
+      ENTITY_TYPES = %w[company person article research_paper custom].freeze
+
+      # Valid enrichment formats
+      ENRICHMENT_FORMATS = %w[text date number options url].freeze
+
+      # Valid source types for imports and exclusions
+      SOURCE_TYPES = %w[import webset].freeze
+
+      # Valid import formats
+      IMPORT_FORMATS = %w[csv].freeze
+    end
+  end
+end

data/lib/exa/middleware/raise_error.rb

@@ -41,6 +41,11 @@ module Exa
         body = env[:body]
 
         if body.is_a?(Hash)
+          # Prioritize "message" field for detailed error descriptions
+          return body["message"] if body["message"]
+          return body[:message] if body[:message]
+
+          # Fall back to "error" field
           return body["error"] if body["error"]
           return body[:error] if body[:error]
         end

data/lib/exa/resources/import.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents an import operation for bringing external data into Exa
+    #
+    # An import allows uploading CSV data containing entities (e.g., companies)
+    # to be processed and enriched within the Exa system.
+    class Import < Struct.new(
+      :id,
+      :object,
+      :status,
+      :format,
+      :entity,
+      :title,
+      :count,
+      :metadata,
+      :failed_reason,
+      :failed_at,
+      :failed_message,
+      :created_at,
+      :updated_at,
+      :upload_url,
+      :upload_valid_until,
+      keyword_init: true
+    )
+      def initialize(
+        id:,
+        object:,
+        status:,
+        format: nil,
+        entity: nil,
+        title: nil,
+        count: nil,
+        metadata: nil,
+        failed_reason: nil,
+        failed_at: nil,
+        failed_message: nil,
+        created_at: nil,
+        updated_at: nil,
+        upload_url: nil,
+        upload_valid_until: nil
+      )
+        super
+        freeze
+      end
+
+      # Status helper methods
+      def pending?
+        status == "pending"
+      end
+
+      def processing?
+        status == "processing"
+      end
+
+      def completed?
+        status == "completed"
+      end
+
+      def failed?
+        status == "failed"
+      end
+
+      def to_h
+        {
+          id: id,
+          object: object,
+          status: status,
+          format: format,
+          entity: entity,
+          title: title,
+          count: count,
+          metadata: metadata,
+          failed_reason: failed_reason,
+          failed_at: failed_at,
+          failed_message: failed_message,
+          created_at: created_at,
+          updated_at: updated_at,
+          upload_url: upload_url,
+          upload_valid_until: upload_valid_until
+        }.compact
+      end
+    end
+  end
+end

data/lib/exa/resources/import_collection.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a paginated list of imports from the Exa API
+    #
+    # This class wraps the JSON response from the GET /websets/v0/imports endpoint
+    # and provides pagination support.
+    class ImportCollection < Struct.new(
+      :data,
+      :has_more,
+      :next_cursor,
+      keyword_init: true
+    )
+      def initialize(data:, has_more: false, next_cursor: nil)
+        super
+        freeze
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def to_h
+        {
+          data: data,
+          has_more: has_more,
+          next_cursor: next_cursor
+        }
+      end
+    end
+  end
+end

data/lib/exa/resources/monitor.rb

@@ -0,0 +1,48 @@
+module Exa
+  module Resources
+    # Represents a webset monitor that automates updates on a schedule
+    Monitor = Struct.new(
+      :id,
+      :object,
+      :status,
+      :webset_id,
+      :cadence,
+      :behavior,
+      :created_at,
+      :updated_at,
+      keyword_init: true
+    ) do
+      def freeze
+        super
+        cadence.freeze if cadence
+        behavior.freeze if behavior
+        self
+      end
+
+      def pending?
+        status == "pending"
+      end
+
+      def active?
+        status == "active"
+      end
+
+      def paused?
+        status == "paused"
+      end
+
+      def to_h
+        {
+          id: id,
+          object: object,
+          status: status,
+          webset_id: webset_id,
+          cadence: cadence,
+          behavior: behavior,
+          created_at: created_at,
+          updated_at: updated_at
+        }.compact
+      end
+    end
+  end
+end

data/lib/exa/resources/monitor_collection.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a paginated list of monitors from the Exa API
+    class MonitorCollection < Struct.new(
+      :data,
+      :has_more,
+      :next_cursor,
+      keyword_init: true
+    )
+      def initialize(data:, has_more: false, next_cursor: nil)
+        super
+        freeze
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def to_h
+        {
+          data: data,
+          has_more: has_more,
+          next_cursor: next_cursor
+        }
+      end
+    end
+  end
+end

data/lib/exa/resources/monitor_run.rb

@@ -0,0 +1,52 @@
+module Exa
+  module Resources
+    # Represents a monitor run execution
+    MonitorRun = Struct.new(
+      :id,
+      :object,
+      :monitor_id,
+      :status,
+      :created_at,
+      :updated_at,
+      :completed_at,
+      :failed_at,
+      :failed_reason,
+      keyword_init: true
+    ) do
+      def freeze
+        super
+        self
+      end
+
+      def pending?
+        status == "pending"
+      end
+
+      def running?
+        status == "running"
+      end
+
+      def completed?
+        status == "completed"
+      end
+
+      def failed?
+        status == "failed"
+      end
+
+      def to_h
+        {
+          id: id,
+          object: object,
+          monitor_id: monitor_id,
+          status: status,
+          created_at: created_at,
+          updated_at: updated_at,
+          completed_at: completed_at,
+          failed_at: failed_at,
+          failed_reason: failed_reason
+        }.compact
+      end
+    end
+  end
+end

data/lib/exa/resources/monitor_run_collection.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a paginated list of monitor runs from the Exa API
+    class MonitorRunCollection < Struct.new(
+      :data,
+      :has_more,
+      :next_cursor,
+      keyword_init: true
+    )
+      def initialize(data:, has_more: false, next_cursor: nil)
+        super
+        freeze
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def to_h
+        {
+          data: data,
+          has_more: has_more,
+          next_cursor: next_cursor
+        }
+      end
+    end
+  end
+end

data/lib/exa/services/search.rb

@@ -5,9 +5,13 @@ require_relative "parameter_converter"
 module Exa
   module Services
     class Search
+      VALID_SEARCH_TYPES = ["fast", "deep", "keyword", "auto"].freeze
+      DEFAULT_SEARCH_TYPE = "fast"
+
       def initialize(connection, **params)
         @connection = connection
-        @params = params
+        @params = normalize_params(params)
+        validate_search_type!
       end
 
       def call
@@ -23,6 +27,22 @@ module Exa
           cost_dollars: body["costDollars"]
         )
       end
+
+      private
+
+      def normalize_params(params)
+        normalized = params.dup
+        # Set default search type if not provided
+        normalized[:type] = DEFAULT_SEARCH_TYPE unless normalized.key?(:type)
+        normalized
+      end
+
+      def validate_search_type!
+        search_type = @params[:type]
+        return if VALID_SEARCH_TYPES.include?(search_type)
+
+        raise ArgumentError, "Invalid search type: '#{search_type}'. Must be one of: #{VALID_SEARCH_TYPES.join(', ')}"
+      end
     end
   end
 end

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

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../constants/websets"
+
 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
+        VALID_ENTITY_TYPES = Constants::Websets::ENTITY_TYPES
+        VALID_ENRICHMENT_FORMATS = Constants::Websets::ENRICHMENT_FORMATS
+        VALID_SOURCE_TYPES = Constants::Websets::SOURCE_TYPES
 
         class << self
           def validate!(params)

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class CreateImport
+        def initialize(connection, **params)
+          @connection = connection
+          @params = params
+        end
+
+        def call
+          response = @connection.post(
+            "/websets/v0/imports",
+            @params
+          )
+          body = response.body
+
+          Resources::Import.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            format: body["format"],
+            entity: body["entity"],
+            title: body["title"],
+            count: body["count"],
+            metadata: body["metadata"],
+            failed_reason: body["failedReason"],
+            failed_at: body["failedAt"],
+            failed_message: body["failedMessage"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            upload_url: body["uploadUrl"],
+            upload_valid_until: body["uploadValidUntil"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class DeleteImport
+        def initialize(connection, id:)
+          @connection = connection
+          @id = id
+        end
+
+        def call
+          response = @connection.delete("/websets/v0/imports/#{@id}")
+          body = response.body
+
+          Resources::Import.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            format: body["format"],
+            entity: body["entity"],
+            title: body["title"],
+            count: body["count"],
+            metadata: body["metadata"],
+            failed_reason: body["failedReason"],
+            failed_at: body["failedAt"],
+            failed_message: body["failedMessage"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            upload_url: body["uploadUrl"],
+            upload_valid_until: body["uploadValidUntil"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class GetImport
+        def initialize(connection, id:)
+          @connection = connection
+          @id = id
+        end
+
+        def call
+          response = @connection.get("/websets/v0/imports/#{@id}")
+          body = response.body
+
+          Resources::Import.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            format: body["format"],
+            entity: body["entity"],
+            title: body["title"],
+            count: body["count"],
+            metadata: body["metadata"],
+            failed_reason: body["failedReason"],
+            failed_at: body["failedAt"],
+            failed_message: body["failedMessage"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            upload_url: body["uploadUrl"],
+            upload_valid_until: body["uploadValidUntil"]
+          )
+        end
+      end
+    end
+  end
+end

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

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