exaonruby 1.0.0

data/lib/exa/resources/event.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class Event < Base
+      # @return [String] Unique identifier
+      def id
+        get(:id)
+      end
+
+      # @return [String] Object type
+      def object
+        get(:object)
+      end
+
+      # @return [String] Event type (e.g., "webset.item.created")
+      def type
+        get(:type)
+      end
+
+      # @return [Hash] Event payload data
+      def data
+        get(:data, {})
+      end
+
+      # @return [String, nil] Related Webset ID
+      def webset_id
+        dig(:data, :webset_id) || dig(:data, :websetId)
+      end
+
+      # @return [String, nil] Related Item ID
+      def item_id
+        dig(:data, :item_id) || dig(:data, :itemId)
+      end
+
+      # @return [Time, nil] Event timestamp
+      def created_at
+        parse_time(get(:created_at))
+      end
+
+      # @return [Boolean] Whether this is a webset event
+      def webset_event?
+        type&.start_with?("webset.")
+      end
+
+      # @return [Boolean] Whether this is an item event
+      def item_event?
+        type&.include?(".item.")
+      end
+
+      # @return [Boolean] Whether this is a monitor event
+      def monitor_event?
+        type&.start_with?("monitor.")
+      end
+
+      # @return [Boolean] Whether this is an import event
+      def import_event?
+        type&.start_with?("import.")
+      end
+
+      private
+
+      def parse_time(value)
+        return nil unless value
+
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+
+      def inspectable_attributes
+        { id: id, type: type }
+      end
+    end
+
+    class EventListResponse < PaginatedResponse
+      def data
+        @data ||= (get(:data, []) || []).map { |item| Event.new(item) }
+      end
+    end
+  end
+end

data/lib/exa/resources/import.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class Import < Base
+      # @return [String] Unique identifier
+      def id
+        get(:id)
+      end
+
+      # @return [String] Object type
+      def object
+        get(:object)
+      end
+
+      # @return [String] Status: pending, processing, completed, failed
+      def status
+        get(:status)
+      end
+
+      # @return [String] Format: csv, webset
+      def format
+        get(:format)
+      end
+
+      # @return [Hash, nil] Entity configuration
+      def entity
+        get(:entity)
+      end
+
+      # @return [String, nil] Entity type
+      def entity_type
+        dig(:entity, :type)
+      end
+
+      # @return [String, nil] Title
+      def title
+        get(:title)
+      end
+
+      # @return [Integer, nil] Number of entities
+      def count
+        get(:count)
+      end
+
+      # @return [Hash] Custom metadata
+      def metadata
+        get(:metadata, {})
+      end
+
+      # @return [String, nil] URL to upload file to
+      def upload_url
+        get(:upload_url)
+      end
+
+      # @return [Time, nil] Upload URL expiration
+      def upload_valid_until
+        parse_time(get(:upload_valid_until))
+      end
+
+      # @return [Boolean] Whether upload URL is still valid
+      def upload_valid?
+        valid_until = upload_valid_until
+        return false unless valid_until
+
+        Time.now < valid_until
+      end
+
+      # @return [String, nil] Failure reason
+      def failed_reason
+        get(:failed_reason)
+      end
+
+      # @return [Time, nil] Failure timestamp
+      def failed_at
+        parse_time(get(:failed_at))
+      end
+
+      # @return [String, nil] Failure message
+      def failed_message
+        get(:failed_message)
+      end
+
+      # @return [Time, nil] Creation timestamp
+      def created_at
+        parse_time(get(:created_at))
+      end
+
+      # @return [Time, nil] Last update timestamp
+      def updated_at
+        parse_time(get(:updated_at))
+      end
+
+      # @return [Boolean] Whether import is pending
+      def pending?
+        status == "pending"
+      end
+
+      # @return [Boolean] Whether import is processing
+      def processing?
+        status == "processing"
+      end
+
+      # @return [Boolean] Whether import completed
+      def completed?
+        status == "completed"
+      end
+
+      # @return [Boolean] Whether import failed
+      def failed?
+        status == "failed"
+      end
+
+      private
+
+      def parse_time(value)
+        return nil unless value
+
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+
+      def inspectable_attributes
+        { id: id, status: status, title: title }
+      end
+    end
+
+    class ImportListResponse < PaginatedResponse
+      def data
+        @data ||= (get(:data, []) || []).map { |item| Import.new(item) }
+      end
+    end
+  end
+end

data/lib/exa/resources/monitor.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class Monitor < Base
+      # @return [String] Unique identifier
+      def id
+        get(:id)
+      end
+
+      # @return [String] Object type
+      def object
+        get(:object)
+      end
+
+      # @return [String] Status: enabled, disabled
+      def status
+        get(:status)
+      end
+
+      # @return [String] Parent Webset ID
+      def webset_id
+        get(:webset_id)
+      end
+
+      # @return [Hash, nil] Cadence configuration
+      def cadence
+        get(:cadence)
+      end
+
+      # @return [String, nil] Cron expression
+      def cron
+        dig(:cadence, :cron)
+      end
+
+      # @return [String, nil] Timezone
+      def timezone
+        dig(:cadence, :timezone)
+      end
+
+      # @return [Hash, nil] Behavior configuration
+      def behavior
+        get(:behavior)
+      end
+
+      # @return [String, nil] Behavior type: search, refresh
+      def behavior_type
+        dig(:behavior, :type)
+      end
+
+      # @return [Hash, nil] Behavior config
+      def behavior_config
+        dig(:behavior, :config)
+      end
+
+      # @return [MonitorRun, nil] Last run information
+      def last_run
+        run_data = get(:last_run)
+        return nil unless run_data
+
+        MonitorRun.new(run_data)
+      end
+
+      # @return [Time, nil] Next scheduled run
+      def next_run_at
+        parse_time(get(:next_run_at))
+      end
+
+      # @return [Hash] Custom metadata
+      def metadata
+        get(:metadata, {})
+      end
+
+      # @return [Time, nil] Creation timestamp
+      def created_at
+        parse_time(get(:created_at))
+      end
+
+      # @return [Time, nil] Last update timestamp
+      def updated_at
+        parse_time(get(:updated_at))
+      end
+
+      # @return [Boolean] Whether monitor is enabled
+      def enabled?
+        status == "enabled"
+      end
+
+      # @return [Boolean] Whether monitor is disabled
+      def disabled?
+        status == "disabled"
+      end
+
+      private
+
+      def parse_time(value)
+        return nil unless value
+
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+
+      def inspectable_attributes
+        { id: id, status: status, cron: cron }
+      end
+    end
+
+    class MonitorRun < Base
+      # @return [String] Unique identifier
+      def id
+        get(:id)
+      end
+
+      # @return [String] Object type
+      def object
+        get(:object)
+      end
+
+      # @return [String] Status: created, running, completed, failed, canceled
+      def status
+        get(:status)
+      end
+
+      # @return [String] Parent monitor ID
+      def monitor_id
+        get(:monitor_id)
+      end
+
+      # @return [String] Run type: search, refresh
+      def type
+        get(:type)
+      end
+
+      # @return [Time, nil] Completion timestamp
+      def completed_at
+        parse_time(get(:completed_at))
+      end
+
+      # @return [Time, nil] Failure timestamp
+      def failed_at
+        parse_time(get(:failed_at))
+      end
+
+      # @return [String, nil] Failure reason
+      def failed_reason
+        get(:failed_reason)
+      end
+
+      # @return [Time, nil] Cancellation timestamp
+      def canceled_at
+        parse_time(get(:canceled_at))
+      end
+
+      # @return [Time, nil] Creation timestamp
+      def created_at
+        parse_time(get(:created_at))
+      end
+
+      # @return [Time, nil] Last update timestamp
+      def updated_at
+        parse_time(get(:updated_at))
+      end
+
+      # @return [Boolean] Whether run completed successfully
+      def completed?
+        status == "completed"
+      end
+
+      # @return [Boolean] Whether run failed
+      def failed?
+        status == "failed"
+      end
+
+      # @return [Boolean] Whether run was canceled
+      def canceled?
+        status == "canceled"
+      end
+
+      private
+
+      def parse_time(value)
+        return nil unless value
+
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    class MonitorListResponse < PaginatedResponse
+      def data
+        @data ||= (get(:data, []) || []).map { |item| Monitor.new(item) }
+      end
+    end
+
+    class MonitorRunListResponse < PaginatedResponse
+      def data
+        @data ||= (get(:data, []) || []).map { |item| MonitorRun.new(item) }
+      end
+    end
+  end
+end

data/lib/exa/resources/paginated_response.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class PaginatedResponse < Base
+      # @return [Array] Data items
+      def data
+        get(:data, [])
+      end
+
+      # @return [Boolean] Whether more items exist
+      def has_more
+        get(:has_more, false)
+      end
+
+      alias has_more? has_more
+
+      # @return [String, nil] Cursor for next page
+      def next_cursor
+        get(:next_cursor)
+      end
+
+      # @return [Boolean] Whether there are more pages
+      def more_pages?
+        has_more && !next_cursor.nil?
+      end
+
+      # @return [Integer] Number of items in current page
+      def count
+        data.length
+      end
+
+      # @return [Boolean] Whether data is empty
+      def empty?
+        data.empty?
+      end
+
+      # Iterates over each item in data
+      # @yield [Object] Each item
+      # @return [Enumerator, self]
+      def each(&block)
+        return data.each unless block
+
+        data.each(&block)
+        self
+      end
+
+      # @param index [Integer] Index of item
+      # @return [Object, nil] Item at index
+      def [](index)
+        data[index]
+      end
+
+      # @return [Object, nil] First item
+      def first
+        data.first
+      end
+
+      # @return [Object, nil] Last item
+      def last
+        data.last
+      end
+
+      private
+
+      def inspectable_attributes
+        { count: count, has_more: has_more }
+      end
+    end
+
+    class WebsetsListResponse < PaginatedResponse
+      # @return [Array<Webset>] List of websets
+      def data
+        @data ||= (get(:data, []) || []).map { |item| Webset.new(item) }
+      end
+    end
+
+    class WebsetItemsListResponse < PaginatedResponse
+      # @return [Array<WebsetItem>] List of webset items
+      def data
+        @data ||= (get(:data, []) || []).map { |item| WebsetItem.new(item) }
+      end
+    end
+  end
+end

data/lib/exa/resources/research_task.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class ResearchTask < Base
+      # @return [String] Unique identifier for the research task
+      def research_id
+        get(:research_id)
+      end
+
+      # @return [String] The model used for this research
+      def model
+        get(:model)
+      end
+
+      # @return [String] The original research instructions
+      def instructions
+        get(:instructions)
+      end
+
+      # @return [String] Status: pending, running, completed, canceled, failed
+      def status
+        get(:status)
+      end
+
+      # @return [Integer, nil] Unix timestamp when research was created (ms)
+      def created_at
+        get(:created_at)
+      end
+
+      # @return [Time, nil] Creation time as Ruby Time object
+      def created_at_time
+        ts = created_at
+        return nil unless ts
+
+        Time.at(ts / 1000.0)
+      end
+
+      # @return [Integer, nil] Unix timestamp when research completed (ms)
+      def completed_at
+        get(:completed_at)
+      end
+
+      # @return [Time, nil] Completion time as Ruby Time object
+      def completed_at_time
+        ts = completed_at
+        return nil unless ts
+
+        Time.at(ts / 1000.0)
+      end
+
+      # @return [Hash, nil] JSON Schema used to validate output
+      def output_schema
+        get(:output_schema)
+      end
+
+      # @return [String, Hash, nil] Research output (markdown or structured JSON)
+      def output
+        get(:output)
+      end
+
+      # @return [Array<Hash>] Events/progress updates
+      def events
+        get(:events, [])
+      end
+
+      # @return [Integer, nil] Number of operations completed
+      def operations_completed
+        dig(:operations, :completed)
+      end
+
+      # @return [Integer, nil] Total number of operations
+      def operations_total
+        dig(:operations, :total)
+      end
+
+      # @return [Float, nil] Progress percentage (0.0 to 1.0)
+      def progress
+        completed = operations_completed
+        total = operations_total
+        return nil unless completed && total && total > 0
+
+        completed.to_f / total
+      end
+
+      # @return [Integer, nil] Reasoning tokens used
+      def reasoning_tokens
+        dig(:usage, :reasoning_tokens)
+      end
+
+      # @return [Integer, nil] Agent search operations
+      def agent_search_operations
+        dig(:usage, :agent_search_operations)
+      end
+
+      # @return [Integer, nil] Agent page reads
+      def agent_page_reads
+        dig(:usage, :agent_page_reads)
+      end
+
+      # @return [String, nil] Error message if failed
+      def error_message
+        get(:error)
+      end
+
+      # @return [CostInfo, nil] Cost information
+      def cost
+        cost_data = get(:cost_dollars)
+        return nil unless cost_data
+
+        CostInfo.new(cost_data)
+      end
+
+      # @return [Boolean] Whether research is pending
+      def pending?
+        status == "pending"
+      end
+
+      # @return [Boolean] Whether research is running
+      def running?
+        status == "running"
+      end
+
+      # @return [Boolean] Whether research is completed
+      def completed?
+        status == "completed"
+      end
+
+      # @return [Boolean] Whether research was canceled
+      def canceled?
+        status == "canceled"
+      end
+
+      # @return [Boolean] Whether research failed
+      def failed?
+        status == "failed"
+      end
+
+      # @return [Boolean] Whether research is still in progress
+      def in_progress?
+        pending? || running?
+      end
+
+      # @return [Boolean] Whether research is finished (success or failure)
+      def finished?
+        completed? || canceled? || failed?
+      end
+
+      private
+
+      def inspectable_attributes
+        { research_id: research_id, status: status, model: model }
+      end
+    end
+
+    class ResearchListResponse < PaginatedResponse
+      # @return [Array<ResearchTask>] List of research tasks
+      def data
+        @data ||= (get(:data, []) || []).map { |item| ResearchTask.new(item) }
+      end
+    end
+  end
+end