exa-ai 0.3.0 → 0.4.0

data/exe/exa-ai-webset-update

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+require "json"
+
+# Parse arguments
+webset_id = nil
+metadata = nil
+api_key = nil
+output_format = "json"
+
+# Recursively convert hash keys from strings to symbols
+def deep_symbolize_keys(obj)
+  case obj
+  when Hash
+    obj.each_with_object({}) do |(key, value), result|
+      result[key.to_sym] = deep_symbolize_keys(value)
+    end
+  when Array
+    obj.map { |item| deep_symbolize_keys(item) }
+  else
+    obj
+  end
+end
+
+# Helper to parse JSON string or load from file
+def parse_json_or_file(value)
+  json_data = if value.start_with?("@")
+                file_path = value[1..]
+                JSON.parse(File.read(file_path))
+              else
+                JSON.parse(value)
+              end
+  deep_symbolize_keys(json_data)
+rescue JSON::ParserError => e
+  $stderr.puts "Error: Invalid JSON: #{e.message}"
+  exit 1
+rescue Errno::ENOENT => e
+  $stderr.puts "Error: File not found: #{e.message}"
+  exit 1
+end
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--metadata"
+    metadata = parse_json_or_file(args.shift)
+  when "--api-key"
+    api_key = args.shift
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai webset-update <webset_id> [OPTIONS]
+
+      Update a webset's metadata
+
+      Arguments:
+        webset_id              ID of the webset to update (required)
+
+      Options:
+        --metadata JSON        Custom metadata to update (supports @file.json)
+        --api-key KEY          Exa API key (or set EXA_API_KEY env var)
+        --output-format FMT    Output format: json, pretty, or text (default: json)
+        --help, -h             Show this help message
+
+      Examples:
+        exa-ai webset-update ws_abc123 --metadata '{"project":"Q1-2025"}'
+        exa-ai webset-update ws_abc123 --metadata @metadata.json
+        exa-ai webset-update ws_abc123 --metadata '{"tags":["important"]}' --output-format pretty
+    HELP
+    exit 0
+  else
+    # First positional argument is webset_id
+    if webset_id.nil?
+      webset_id = arg
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate required arguments
+if webset_id.nil?
+  $stderr.puts "Error: webset_id argument is required"
+  $stderr.puts "Usage: exa-ai webset-update <webset_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-update --help' for more information"
+  exit 1
+end
+
+if metadata.nil?
+  $stderr.puts "Error: --metadata is required"
+  $stderr.puts "Try 'exa-ai webset-update --help' for more information"
+  exit 1
+end
+
+begin
+  # Resolve API key and format
+  api_key = Exa::CLI::Base.resolve_api_key(api_key)
+  output_format = Exa::CLI::Base.resolve_output_format(output_format)
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Update webset
+  webset = client.update_webset(webset_id, metadata: metadata)
+
+  # Format and output
+  output = Exa::CLI::Formatters::WebsetFormatter.format(webset, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Webset not found: #{e.message}"
+  exit 1
+rescue Exa::ConfigurationError => e
+  $stderr.puts "Configuration error: #{e.message}"
+  exit 1
+rescue Exa::Unauthorized => e
+  $stderr.puts "Authentication error: #{e.message}"
+  $stderr.puts "Check your API key (set EXA_API_KEY or use --api-key)"
+  exit 1
+rescue Exa::ClientError => e
+  $stderr.puts "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  $stderr.puts "Server error: #{e.message}"
+  $stderr.puts "The Exa API may be experiencing issues. Please try again later."
+  exit 1
+rescue Exa::Error => e
+  $stderr.puts "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  $stderr.puts "Unexpected error: #{e.message}"
+  $stderr.puts e.backtrace.first(5) if ENV["DEBUG"]
+  exit 1
+end

data/lib/exa/cli/base.rb

@@ -11,7 +11,7 @@ module Exa
         env_key = ENV["EXA_API_KEY"]
         return env_key if env_key && !env_key.empty?
 
-        raise ConfigurationError,
+        raise Exa::ConfigurationError,
               "Missing API key. Set EXA_API_KEY environment variable or use --api-key flag"
       end
 
@@ -24,13 +24,13 @@ module Exa
 
         return format if valid_formats.include?(format)
 
-        raise ConfigurationError,
+        raise Exa::ConfigurationError,
               "Invalid output format: #{format}. Valid formats: #{valid_formats.join(', ')}"
       end
 
       # Build a client instance with the given API key
       def self.build_client(api_key, **options)
-        Client.new(api_key: api_key, **options)
+        Exa::Client.new(api_key: api_key, **options)
       end
 
       # Format output data based on format type

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class EnrichmentFormatter
+        def self.format(enrichment, output_format)
+          case output_format
+          when "json"
+            JSON.generate(enrichment.to_h)
+          when "pretty"
+            JSON.pretty_generate(enrichment.to_h)
+          when "text"
+            format_as_text(enrichment)
+          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)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_as_text(enrichment)
+          lines = []
+          lines << "Enrichment: #{enrichment.id}"
+          lines << "Webset: #{enrichment.webset_id}" if enrichment.webset_id
+          lines << "Status: #{enrichment.status}"
+          lines << "Title: #{enrichment.title}" if enrichment.title
+          lines << "Description: #{enrichment.description}" if enrichment.description
+          lines << "Format: #{enrichment.format}" if enrichment.format
+
+          if enrichment.options && !enrichment.options.empty?
+            lines << "\nOptions:"
+            enrichment.options.each do |option|
+              lines << "  - #{option['label']}" if option['label']
+            end
+          end
+
+          lines << "Created: #{enrichment.created_at}" if enrichment.created_at
+          lines << "Updated: #{enrichment.updated_at}" if enrichment.updated_at
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_text
+
+        def self.format_collection_as_text(collection)
+          lines = ["Enrichments (#{collection.data.length} items):"]
+          collection.data.each do |enr|
+            lines << "\n  #{enr['id']}"
+            lines << "  Status: #{enr['status']}"
+            lines << "  Title: #{enr['title']}" if enr['title']
+          end
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class WebsetFormatter
+        def self.format(webset, output_format)
+          case output_format
+          when "json"
+            JSON.generate(webset.to_h)
+          when "pretty"
+            JSON.pretty_generate(webset.to_h)
+          when "text"
+            format_as_text(webset)
+          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)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_as_text(webset)
+          lines = []
+          lines << "Webset: #{webset.id}"
+          lines << "Status: #{webset.status}"
+          lines << "Created: #{webset.created_at}" if webset.created_at
+          lines << "Updated: #{webset.updated_at}" if webset.updated_at
+
+          if webset.searches && !webset.searches.empty?
+            lines << "\nSearches:"
+            webset.searches.each do |search|
+              lines << "  - #{search['query']}" if search['query']
+            end
+          end
+
+          if webset.enrichments && !webset.enrichments.empty?
+            lines << "\nEnrichments: #{webset.enrichments.length}"
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_text
+
+        def self.format_collection_as_text(collection)
+          lines = ["Websets (#{collection.data.length} items):"]
+          collection.data.each do |ws|
+            lines << "\n  #{ws['id']}"
+            lines << "  Status: #{ws['status']}"
+            lines << "  Created: #{ws['createdAt']}" if ws['createdAt']
+          end
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class WebsetItemFormatter
+        def self.format(item, output_format)
+          case output_format
+          when "json"
+            JSON.generate(item)
+          when "pretty"
+            JSON.pretty_generate(item)
+          when "text"
+            format_as_text(item)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_collection(items, output_format)
+          case output_format
+          when "json"
+            JSON.generate(items)
+          when "pretty"
+            JSON.pretty_generate(items)
+          when "text"
+            format_collection_as_text(items)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_as_text(item)
+          lines = []
+          lines << "Item: #{item['id']}"
+          lines << "URL: #{item['url']}" if item['url']
+          lines << "Title: #{item['title']}" if item['title']
+          lines << "Status: #{item['status']}" if item['status']
+          lines << "Created: #{item['createdAt']}" if item['createdAt']
+          lines << "Updated: #{item['updatedAt']}" if item['updatedAt']
+
+          if item['entity']
+            lines << "\nEntity:"
+            lines << "  Type: #{item['entity']['type']}" if item['entity']['type']
+            lines << "  Name: #{item['entity']['name']}" if item['entity']['name']
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_text
+
+        def self.format_collection_as_text(items)
+          lines = ["Items (#{items.length} total):"]
+          items.each_with_index do |item, idx|
+            lines << "\n#{idx + 1}. #{item['id']}"
+            lines << "   URL: #{item['url']}" if item['url']
+            lines << "   Title: #{item['title']}" if item['title']
+            lines << "   Status: #{item['status']}" if item['status']
+            if item['entity'] && item['entity']['name']
+              lines << "   Entity: #{item['entity']['name']}"
+            end
+          end
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end

data/lib/exa/client.rb

@@ -148,6 +148,177 @@ module Exa
       search(query, type: "keyword", includeDomains: ["linkedin.com/in"], **params)
     end
 
+    # List all websets
+    #
+    # @param params [Hash] Pagination parameters
+    # @option params [String] :cursor Cursor for pagination
+    # @option params [Integer] :limit Maximum number of websets to return
+    # @return [Resources::WebsetCollection] Paginated list of websets
+    def list_websets(**params)
+      Services::Websets::List.new(connection, **params).call
+    end
+
+    # Get a specific webset by ID
+    #
+    # @param id [String] Webset ID
+    # @param params [Hash] Optional parameters
+    # @option params [Array<String>] :expand Resources to expand in response (e.g., ['items'])
+    # @return [Resources::Webset] The requested webset
+    def get_webset(id, **params)
+      Services::Websets::Retrieve.new(connection, id: id, **params).call
+    end
+
+    # Delete a webset
+    #
+    # @param id [String] Webset ID
+    # @return [Resources::Webset] The deleted webset
+    def delete_webset(id)
+      Services::Websets::Delete.new(connection, id: id).call
+    end
+
+    # Cancel in-progress operations on a webset
+    #
+    # @param id [String] Webset ID
+    # @return [Resources::Webset] The webset with cancelled operations
+    def cancel_webset(id)
+      Services::Websets::Cancel.new(connection, id: id).call
+    end
+
+    # Update a webset's metadata
+    #
+    # @param id [String] Webset ID
+    # @param params [Hash] Update parameters
+    # @option params [Hash] :metadata Metadata to update
+    # @return [Resources::Webset] The updated webset
+    def update_webset(id, **params)
+      Services::Websets::Update.new(connection, id: id, **params).call
+    end
+
+    # Create a new webset
+    #
+    # @param params [Hash] Creation parameters
+    # @option params [Hash] :search Search configuration
+    # @return [Resources::Webset] The newly created webset
+    def create_webset(**params)
+      Services::Websets::Create.new(connection, **params).call
+    end
+
+    # Create a new enrichment for a webset
+    #
+    # @param webset_id [String] Webset ID
+    # @param params [Hash] Enrichment parameters
+    # @option params [String] :description Description of data to extract
+    # @option params [String] :format Format type (text, url, options, etc.)
+    # @option params [Array<Hash>] :options Options for enrichment
+    # @option params [Hash] :metadata Custom metadata
+    # @return [Resources::WebsetEnrichment] The newly created enrichment
+    def create_enrichment(webset_id:, **params)
+      Services::Websets::CreateEnrichment.new(connection, webset_id: webset_id, **params).call
+    end
+
+    # Get a specific enrichment by ID
+    #
+    # @param webset_id [String] Webset ID
+    # @param id [String] Enrichment ID
+    # @return [Resources::WebsetEnrichment] The requested enrichment
+    def get_enrichment(webset_id:, id:)
+      Services::Websets::RetrieveEnrichment.new(connection, webset_id: webset_id, id: id).call
+    end
+
+    # Update an enrichment
+    #
+    # @param webset_id [String] Webset ID
+    # @param id [String] Enrichment ID
+    # @param params [Hash] Update parameters
+    # @option params [String] :description Updated description
+    # @option params [String] :format Updated format
+    # @option params [Array<Hash>] :options Updated options
+    # @option params [Hash] :metadata Updated metadata
+    # @return [Resources::WebsetEnrichment] The updated enrichment
+    def update_enrichment(webset_id:, id:, **params)
+      Services::Websets::UpdateEnrichment.new(connection, webset_id: webset_id, id: id, **params).call
+    end
+
+    # Delete an enrichment
+    #
+    # @param webset_id [String] Webset ID
+    # @param id [String] Enrichment ID
+    # @return [Resources::WebsetEnrichment] The deleted enrichment
+    def delete_enrichment(webset_id:, id:)
+      Services::Websets::DeleteEnrichment.new(connection, webset_id: webset_id, id: id).call
+    end
+
+    # Cancel a running enrichment
+    #
+    # @param webset_id [String] Webset ID
+    # @param id [String] Enrichment ID
+    # @return [Resources::WebsetEnrichment] The cancelled enrichment
+    def cancel_enrichment(webset_id:, id:)
+      Services::Websets::CancelEnrichment.new(connection, webset_id: webset_id, id: id).call
+    end
+
+    # Create a new search within a webset
+    #
+    # @param webset_id [String] Webset ID
+    # @param params [Hash] Search parameters
+    # @option params [String] :query The search query (required)
+    # @option params [Integer] :count Number of results to find
+    # @option params [Hash] :entity Entity type specification
+    # @option params [Array<Hash>] :criteria Search criteria
+    # @option params [Array<Hash>] :exclude Items to exclude from results
+    # @option params [Array<Hash>] :scope Limit search to specific sources
+    # @option params [Boolean] :recall Whether to estimate total available results
+    # @option params [String] :behavior "override" or "append" (default: "override")
+    # @option params [Hash] :metadata Custom metadata
+    # @return [Resources::WebsetSearch] The newly created search
+    def create_webset_search(webset_id:, **params)
+      Services::Websets::CreateSearch.new(connection, webset_id: webset_id, **params).call
+    end
+
+    # Get a webset search by ID
+    #
+    # @param webset_id [String] Webset ID
+    # @param id [String] Search ID
+    # @return [Resources::WebsetSearch] The requested search
+    def get_webset_search(webset_id:, id:)
+      Services::Websets::GetSearch.new(connection, webset_id: webset_id, id: id).call
+    end
+
+    # Cancel a webset search
+    #
+    # @param webset_id [String] Webset ID
+    # @param id [String] Search ID
+    # @return [Resources::WebsetSearch] The cancelled search
+    def cancel_webset_search(webset_id:, id:)
+      Services::Websets::CancelSearch.new(connection, webset_id: webset_id, id: id).call
+    end
+
+    # Get a webset item by ID
+    #
+    # @param webset_id [String] Webset ID
+    # @param id [String] Item ID
+    # @return [Hash] The requested item
+    def get_item(webset_id:, id:)
+      Services::Websets::GetItem.new(connection, webset_id: webset_id, id: id).call
+    end
+
+    # Delete a webset item by ID
+    #
+    # @param webset_id [String] Webset ID
+    # @param id [String] Item ID
+    # @return [Boolean] True if deletion was successful
+    def delete_item(webset_id:, id:)
+      Services::Websets::DeleteItem.new(connection, webset_id: webset_id, id: id).call
+    end
+
+    # List all items in a webset
+    #
+    # @param webset_id [String] Webset ID
+    # @return [Array<Hash>] Array of items
+    def list_items(webset_id:)
+      Services::Websets::ListItems.new(connection, webset_id: webset_id).call
+    end
+
     private
 
     def connection
@@ -161,6 +332,7 @@ module Exa
       options = {}
       options[:base_url] = @options[:base_url] if @options[:base_url]
       options[:timeout] = @options[:timeout] if @options[:timeout]
+      options[:debug] = true if ENV["EXA_DEBUG"]
       options
     end
 

data/lib/exa/connection.rb

@@ -1,17 +1,24 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "logger"
 
 module Exa
   class Connection
+    DEFAULT_BASE_URL = "https://api.exa.ai"
     def self.build(api_key:, **options, &block)
       Faraday.new(url: options[:base_url] || DEFAULT_BASE_URL) do |conn|
         # Authentication
-        conn.request :authorization, "Bearer", api_key
+        conn.headers["x-api-key"] = api_key
 
         # Request/Response JSON encoding
         conn.request :json
 
+        # Debug logging (when enabled via option)
+        if options[:debug]
+          conn.response :logger, Logger.new($stdout), headers: true, bodies: true
+        end
+
         # Custom error handling (registered before JSON so it runs after in response chain)
         conn.response :raise_error
         conn.response :json, content_type: /\bjson$/

data/lib/exa/resources/webset.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a webset from the Exa API
+    #
+    # A webset is a collection of web entities (companies, people, etc.)
+    # discovered through searches, imports, and enrichments.
+    class Webset < Struct.new(
+      :id,
+      :object,
+      :status,
+      :external_id,
+      :title,
+      :searches,
+      :imports,
+      :enrichments,
+      :monitors,
+      :excludes,
+      :metadata,
+      :created_at,
+      :updated_at,
+      :items,
+      keyword_init: true
+    )
+      def initialize(
+        id:,
+        object:,
+        status:,
+        external_id: nil,
+        title: nil,
+        searches: nil,
+        imports: nil,
+        enrichments: nil,
+        monitors: nil,
+        excludes: nil,
+        metadata: nil,
+        created_at: nil,
+        updated_at: nil,
+        items: nil
+      )
+        super
+        freeze
+      end
+
+      def idle?
+        status == "idle"
+      end
+
+      def processing?
+        status == "processing"
+      end
+
+      def to_h
+        {
+          id: id,
+          object: object,
+          status: status,
+          external_id: external_id,
+          title: title,
+          searches: searches,
+          imports: imports,
+          enrichments: enrichments,
+          monitors: monitors,
+          excludes: excludes,
+          metadata: metadata,
+          created_at: created_at,
+          updated_at: updated_at,
+          items: items
+        }.compact
+      end
+    end
+  end
+end

data/lib/exa/resources/webset_collection.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a paginated list of websets from the Exa API
+    #
+    # This class wraps the JSON response from the GET /websets/v0/websets endpoint
+    # and provides pagination support.
+    class WebsetCollection < 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