exa-ai 0.3.1 → 0.4.0

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

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

data/lib/exa/resources/webset_enrichment.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a webset enrichment from the Exa API
+    #
+    # An enrichment extracts specific data from web entities in a webset.
+    class WebsetEnrichment < Struct.new(
+      :id,
+      :object,
+      :status,
+      :webset_id,
+      :title,
+      :description,
+      :format,
+      :options,
+      :instructions,
+      :metadata,
+      :created_at,
+      :updated_at,
+      keyword_init: true
+    )
+      def initialize(
+        id:,
+        object:,
+        status:,
+        webset_id: nil,
+        title: nil,
+        description: nil,
+        format: nil,
+        options: nil,
+        instructions: nil,
+        metadata: nil,
+        created_at: nil,
+        updated_at: nil
+      )
+        super
+        freeze
+      end
+
+      def pending?
+        status == "pending"
+      end
+
+      def running?
+        status == "running"
+      end
+
+      def completed?
+        status == "completed"
+      end
+
+      def to_h
+        {
+          id: id,
+          object: object,
+          status: status,
+          webset_id: webset_id,
+          title: title,
+          description: description,
+          format: format,
+          options: options,
+          instructions: instructions,
+          metadata: metadata,
+          created_at: created_at,
+          updated_at: updated_at
+        }.compact
+      end
+    end
+  end
+end

data/lib/exa/resources/webset_enrichment_collection.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a list of enrichments for a webset from the Exa API
+    #
+    # This class wraps the JSON response from the GET /websets/v0/websets/{id}/enrichments endpoint
+    class WebsetEnrichmentCollection < Struct.new(
+      :data,
+      keyword_init: true
+    )
+      def initialize(data:)
+        super
+        freeze
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def to_h
+        {
+          data: data
+        }
+      end
+    end
+  end
+end

data/lib/exa/resources/webset_search.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a search operation within a webset
+    #
+    # A search finds entities matching specific criteria and can either
+    # override existing webset items or append to them.
+    class WebsetSearch < Struct.new(
+      :id,
+      :object,
+      :status,
+      :webset_id,
+      :query,
+      :entity,
+      :criteria,
+      :count,
+      :behavior,
+      :exclude,
+      :scope,
+      :progress,
+      :recall,
+      :metadata,
+      :canceled_at,
+      :canceled_reason,
+      :created_at,
+      :updated_at,
+      keyword_init: true
+    )
+      def initialize(
+        id:,
+        object:,
+        status:,
+        webset_id: nil,
+        query: nil,
+        entity: nil,
+        criteria: nil,
+        count: nil,
+        behavior: nil,
+        exclude: nil,
+        scope: nil,
+        progress: nil,
+        recall: nil,
+        metadata: nil,
+        canceled_at: nil,
+        canceled_reason: nil,
+        created_at: nil,
+        updated_at: nil
+      )
+        super
+        freeze
+      end
+
+      # Status helper methods
+      def created?
+        status == "created"
+      end
+
+      def running?
+        status == "running"
+      end
+
+      def completed?
+        status == "completed"
+      end
+
+      def failed?
+        status == "failed"
+      end
+
+      def canceled?
+        status == "canceled"
+      end
+
+      def in_progress?
+        created? || running?
+      end
+
+      # Behavior helper methods
+      def override?
+        behavior == "override"
+      end
+
+      def append?
+        behavior == "append"
+      end
+
+      def to_h
+        {
+          id: id,
+          object: object,
+          status: status,
+          webset_id: webset_id,
+          query: query,
+          entity: entity,
+          criteria: criteria,
+          count: count,
+          behavior: behavior,
+          exclude: exclude,
+          scope: scope,
+          progress: progress,
+          recall: recall,
+          metadata: metadata,
+          canceled_at: canceled_at,
+          canceled_reason: canceled_reason,
+          created_at: created_at,
+          updated_at: updated_at
+        }.compact
+      end
+    end
+  end
+end

data/lib/exa/services/parameter_converter.rb

@@ -35,6 +35,7 @@ module Exa
         when :end_crawl_date then :endCrawlDate
         when :include_text then :includeText
         when :exclude_text then :excludeText
+        when :external_id then :externalId
         else
           key
         end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class Cancel
+        def initialize(connection, id:)
+          @connection = connection
+          @id = id
+        end
+
+        def call
+          response = @connection.post("/websets/v0/websets/#{@id}/cancel", {})
+          body = response.body
+
+          Resources::Webset.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            external_id: body["externalId"],
+            title: body["title"],
+            searches: body["searches"],
+            imports: body["imports"],
+            enrichments: body["enrichments"],
+            monitors: body["monitors"],
+            excludes: body["excludes"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            items: body["items"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class CancelEnrichment
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          response = @connection.post("/websets/v0/websets/#{@webset_id}/enrichments/#{@id}/cancel", {})
+          body = response.body
+
+          Resources::WebsetEnrichment.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            title: body["title"],
+            description: body["description"],
+            format: body["format"],
+            options: body["options"],
+            instructions: body["instructions"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class CancelSearch
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          response = @connection.post(
+            "/websets/v0/websets/#{@webset_id}/searches/#{@id}/cancel",
+            {}
+          )
+          body = response.body
+
+          Resources::WebsetSearch.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            query: body["query"],
+            entity: body["entity"],
+            criteria: body["criteria"],
+            count: body["count"],
+            behavior: body["behavior"],
+            exclude: body["exclude"],
+            scope: body["scope"],
+            progress: body["progress"],
+            recall: body["recall"],
+            metadata: body["metadata"],
+            canceled_at: body["canceledAt"],
+            canceled_reason: body["canceledReason"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "create_validator"
+require_relative "../websets_parameter_converter"
+
+module Exa
+  module Services
+    module Websets
+      class Create
+        def initialize(connection, **params)
+          @connection = connection
+          @params = params
+        end
+
+        def call
+          # Validate parameters before making the API call
+          CreateValidator.validate!(@params)
+
+          # Convert Ruby snake_case params to API camelCase
+          converted_params = WebsetsParameterConverter.convert(@params)
+
+          response = @connection.post("/websets/v0/websets", converted_params)
+          body = response.body
+
+          Resources::Webset.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            external_id: body["externalId"],
+            title: body["title"],
+            searches: body["searches"],
+            imports: body["imports"],
+            enrichments: body["enrichments"],
+            monitors: body["monitors"],
+            excludes: body["excludes"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            items: body["items"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class CreateEnrichment
+        def initialize(connection, webset_id:, **params)
+          @connection = connection
+          @webset_id = webset_id
+          @params = params
+        end
+
+        def call
+          response = @connection.post("/websets/v0/websets/#{@webset_id}/enrichments", @params)
+          body = response.body
+
+          Resources::WebsetEnrichment.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            title: body["title"],
+            description: body["description"],
+            format: body["format"],
+            options: body["options"],
+            instructions: body["instructions"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end