exa-ai 0.5.0 → 0.6.0

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class MonitorFormatter
+        def self.format(monitor, output_format)
+          case output_format
+          when "json"
+            JSON.generate(monitor.to_h)
+          when "pretty"
+            JSON.pretty_generate(monitor.to_h)
+          when "text"
+            format_as_text(monitor)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(monitor.to_h)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_collection(collection, output_format)
+          case output_format
+          when "json"
+            JSON.generate(collection.to_h)
+          when "pretty"
+            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
+        end
+
+        def self.format_as_text(monitor)
+          lines = []
+          lines << "Monitor: #{monitor.id}"
+          lines << "Webset: #{monitor.webset_id}" if monitor.webset_id
+          lines << "Status: #{monitor.status}"
+
+          if monitor.cadence
+            lines << "\nCadence:"
+            lines << "  Cron: #{monitor.cadence['cron']}" if monitor.cadence['cron']
+            lines << "  Timezone: #{monitor.cadence['timezone']}" if monitor.cadence['timezone']
+          end
+
+          if monitor.behavior
+            lines << "\nBehavior:"
+            lines << "  Type: #{monitor.behavior['type']}" if monitor.behavior['type']
+            lines << "  Query: #{monitor.behavior['query']}" if monitor.behavior['query']
+            lines << "  Count: #{monitor.behavior['count']}" if monitor.behavior['count']
+          end
+
+          lines << "\nCreated: #{monitor.created_at}" if monitor.created_at
+          lines << "Updated: #{monitor.updated_at}" if monitor.updated_at
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_text
+
+        def self.format_collection_as_text(collection)
+          lines = ["Monitors (#{collection.data.length} items):"]
+          collection.data.each do |mon|
+            lines << "\n  #{mon['id']}"
+            lines << "  Status: #{mon['status']}"
+            lines << "  Webset: #{mon['websetId']}" if mon['websetId']
+          end
+
+          if collection.has_more
+            lines << "\nMore available (cursor: #{collection.next_cursor})"
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class MonitorRunFormatter
+        def self.format(monitor_run, output_format)
+          case output_format
+          when "json"
+            JSON.generate(monitor_run.to_h)
+          when "pretty"
+            JSON.pretty_generate(monitor_run.to_h)
+          when "text"
+            format_as_text(monitor_run)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(monitor_run.to_h)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_collection(collection, output_format)
+          case output_format
+          when "json"
+            JSON.generate(collection.to_h)
+          when "pretty"
+            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
+        end
+
+        def self.format_as_text(monitor_run)
+          lines = []
+          lines << "Monitor Run: #{monitor_run.id}"
+          lines << "Monitor: #{monitor_run.monitor_id}" if monitor_run.monitor_id
+          lines << "Status: #{monitor_run.status}"
+
+          lines << "\nCreated: #{monitor_run.created_at}" if monitor_run.created_at
+          lines << "Updated: #{monitor_run.updated_at}" if monitor_run.updated_at
+          lines << "Completed: #{monitor_run.completed_at}" if monitor_run.completed_at
+
+          if monitor_run.failed?
+            lines << "Failed: #{monitor_run.failed_at}" if monitor_run.failed_at
+            lines << "Reason: #{monitor_run.failed_reason}" if monitor_run.failed_reason
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_text
+
+        def self.format_collection_as_text(collection)
+          lines = ["Monitor Runs (#{collection.data.length} items):"]
+          collection.data.each do |run|
+            lines << "\n  #{run['id']}"
+            lines << "  Status: #{run['status']}"
+            lines << "  Completed: #{run['completedAt']}" if run['completedAt']
+            lines << "  Failed: #{run['failedReason']}" if run['failedReason']
+          end
+
+          if collection.has_more
+            lines << "\nMore available (cursor: #{collection.next_cursor})"
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end

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

@@ -10,6 +10,8 @@ module Exa
             format_task_pretty(task, show_events: show_events)
           when "text"
             format_task_text(task, show_events: show_events)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(task.to_h)
           else
             JSON.pretty_generate(task.to_h)
           end
@@ -23,6 +25,8 @@ module Exa
             format_list_pretty(list)
           when "text"
             format_list_text(list)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(list.to_h)
           else
             JSON.pretty_generate(list.to_h)
           end

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

@@ -12,6 +12,8 @@ module Exa
             format_pretty(result)
           when "text"
             format_text(result)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(result.to_h)
           else
             JSON.pretty_generate(result.to_h)
           end

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/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/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)