exaonruby 1.0.0

data/lib/exa/endpoints/webhooks.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Webhooks
+      VALID_EVENTS = %w[
+        webset.created webset.deleted webset.paused webset.idle
+        webset.search.created webset.search.canceled webset.search.completed webset.search.updated
+        import.created import.completed
+        webset.item.created webset.item.enriched
+        monitor.created monitor.updated monitor.deleted
+        monitor.run.created monitor.run.completed
+        webset.export.created webset.export.completed
+      ].freeze
+
+      # Creates a new Webhook for event notifications
+      #
+      # Webhooks notify you when events happen in your Websets via HTTP POST.
+      # The response includes a secret key for signature verification.
+      #
+      # @param url [String] URL to send webhook notifications to
+      # @param events [Array<String>] Event types to subscribe to
+      # @param metadata [Hash, nil] Custom metadata
+      #
+      # @return [Exa::Resources::Webhook] Created Webhook with secret
+      #
+      # @example Create a webhook for item events
+      #   webhook = client.create_webhook(
+      #     url: "https://example.com/webhooks/exa",
+      #     events: ["webset.item.created", "webset.item.enriched"]
+      #   )
+      #   puts "Secret (save this!): #{webhook.secret}"
+      def create_webhook(url:, events:, metadata: nil)
+        validate_webhook_params!(url, events)
+
+        params = {
+          url: url,
+          events: events
+        }
+        params[:metadata] = metadata if metadata
+
+        response = websets_post("/webhooks", params)
+
+        Resources::Webhook.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Gets a Webhook by ID
+      #
+      # @param webhook_id [String] Webhook ID
+      # @return [Exa::Resources::Webhook] The Webhook
+      def get_webhook(webhook_id)
+        raise InvalidRequestError, "webhook_id must be a non-empty string" if !webhook_id.is_a?(String) || webhook_id.empty?
+
+        response = websets_get("/webhooks/#{webhook_id}")
+
+        Resources::Webhook.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Lists all Webhooks
+      #
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page
+      #
+      # @return [Exa::Resources::WebhookListResponse] Paginated list of Webhooks
+      def list_webhooks(cursor: nil, limit: nil)
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+
+        response = websets_get("/webhooks", params)
+
+        Resources::WebhookListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Updates a Webhook
+      #
+      # @param webhook_id [String] Webhook ID
+      # @param url [String, nil] Updated URL
+      # @param events [Array<String>, nil] Updated event subscriptions
+      # @param status [String, nil] "active" or "inactive"
+      # @param metadata [Hash, nil] Updated metadata
+      #
+      # @return [Exa::Resources::Webhook] Updated Webhook
+      def update_webhook(webhook_id, url: nil, events: nil, status: nil, metadata: nil)
+        raise InvalidRequestError, "webhook_id must be a non-empty string" if !webhook_id.is_a?(String) || webhook_id.empty?
+
+        if events
+          validate_events!(events)
+        end
+
+        params = {}
+        params[:url] = url if url
+        params[:events] = events if events
+        params[:status] = status if status
+        params[:metadata] = metadata if metadata
+
+        response = websets_patch("/webhooks/#{webhook_id}", params)
+
+        Resources::Webhook.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Deletes a Webhook
+      #
+      # @param webhook_id [String] Webhook ID
+      # @return [Hash] Deletion confirmation
+      def delete_webhook(webhook_id)
+        raise InvalidRequestError, "webhook_id must be a non-empty string" if !webhook_id.is_a?(String) || webhook_id.empty?
+
+        websets_delete("/webhooks/#{webhook_id}")
+      end
+
+      # Lists delivery attempts for a Webhook
+      #
+      # @param webhook_id [String] Webhook ID
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page
+      #
+      # @return [Exa::Resources::WebhookAttemptListResponse] Paginated list of attempts
+      def list_webhook_attempts(webhook_id, cursor: nil, limit: nil)
+        raise InvalidRequestError, "webhook_id must be a non-empty string" if !webhook_id.is_a?(String) || webhook_id.empty?
+
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+
+        response = websets_get("/webhooks/#{webhook_id}/attempts", params)
+
+        Resources::WebhookAttemptListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      def validate_webhook_params!(url, events)
+        raise InvalidRequestError, "url must be a non-empty string" if !url.is_a?(String) || url.empty?
+        raise InvalidRequestError, "events must be a non-empty array" if !events.is_a?(Array) || events.empty?
+
+        validate_events!(events)
+      end
+
+      def validate_events!(events)
+        events.each do |event|
+          unless VALID_EVENTS.include?(event)
+            raise InvalidRequestError, "Invalid event: #{event}. Valid events: #{VALID_EVENTS.join(", ")}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/exa/endpoints/webset_enrichments.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module WebsetEnrichments
+      VALID_FORMATS = %w[text enum number boolean date].freeze
+
+      # Creates a new Enrichment for a Webset
+      #
+      # Enrichments automatically search for and extract specific information
+      # from each Item added to the Webset.
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param description [String] Description of what to extract
+      # @param format [String] Output format: text, enum, number, boolean, date
+      # @param options [Array<Hash>] Options for enum format [{ label: "..." }]
+      # @param instructions [String] Additional instructions for extraction
+      # @param metadata [Hash] Custom metadata
+      #
+      # @return [Exa::Resources::WebsetEnrichment] Created Enrichment
+      #
+      # @raise [Exa::NotFoundError] if Webset not found
+      #
+      # @example Create a text enrichment
+      #   enrichment = client.create_webset_enrichment(
+      #     "webset_abc123",
+      #     description: "Company's primary product or service",
+      #     format: "text"
+      #   )
+      #
+      # @example Create an enum enrichment
+      #   enrichment = client.create_webset_enrichment(
+      #     "webset_abc123",
+      #     description: "Company's funding stage",
+      #     format: "enum",
+      #     options: [
+      #       { label: "Pre-seed" },
+      #       { label: "Seed" },
+      #       { label: "Series A" },
+      #       { label: "Series B+" }
+      #     ]
+      #   )
+      #
+      # @example Create a number enrichment
+      #   enrichment = client.create_webset_enrichment(
+      #     "webset_abc123",
+      #     description: "Number of employees",
+      #     format: "number"
+      #   )
+      def create_webset_enrichment(webset_id, **enrichment_options)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "description is required" unless enrichment_options[:description]
+
+        validate_enrichment_options!(enrichment_options)
+
+        params = build_enrichment_params(enrichment_options)
+        response = websets_post("/websets/#{webset_id}/enrichments", params)
+
+        Resources::WebsetEnrichment.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Lists all Enrichments for a Webset
+      #
+      # @param webset_id [String] Webset ID or external ID
+      #
+      # @return [Array<Exa::Resources::WebsetEnrichment>] List of Enrichments
+      #
+      # @raise [Exa::NotFoundError] if Webset not found
+      #
+      # @example List Enrichments
+      #   enrichments = client.list_webset_enrichments("webset_abc123")
+      #   enrichments.each { |e| puts e.description }
+      def list_webset_enrichments(webset_id)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+
+        response = websets_get("/websets/#{webset_id}/enrichments")
+
+        enrichments_data = response.is_a?(Hash) && response[:data] ? response[:data] : response
+        enrichments_data = [enrichments_data] unless enrichments_data.is_a?(Array)
+
+        enrichments_data.map do |data|
+          Resources::WebsetEnrichment.new(
+            Utils::ParameterConverter.from_api_response(data)
+          )
+        end
+      end
+
+      # Gets an Enrichment by ID
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param enrichment_id [String] Enrichment ID
+      #
+      # @return [Exa::Resources::WebsetEnrichment] The Enrichment
+      #
+      # @raise [Exa::NotFoundError] if Webset or Enrichment not found
+      #
+      # @example Get an Enrichment
+      #   enrichment = client.get_webset_enrichment("webset_abc123", "enrichment_xyz789")
+      def get_webset_enrichment(webset_id, enrichment_id)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "enrichment_id must be a non-empty string" if !enrichment_id.is_a?(String) || enrichment_id.empty?
+
+        response = websets_get("/websets/#{webset_id}/enrichments/#{enrichment_id}")
+
+        Resources::WebsetEnrichment.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Deletes an Enrichment from a Webset
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param enrichment_id [String] Enrichment ID
+      #
+      # @return [Hash] Deletion confirmation
+      #
+      # @raise [Exa::NotFoundError] if Webset or Enrichment not found
+      #
+      # @example Delete an Enrichment
+      #   client.delete_webset_enrichment("webset_abc123", "enrichment_xyz789")
+      def delete_webset_enrichment(webset_id, enrichment_id)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "enrichment_id must be a non-empty string" if !enrichment_id.is_a?(String) || enrichment_id.empty?
+
+        websets_delete("/websets/#{webset_id}/enrichments/#{enrichment_id}")
+      end
+
+      private
+
+      # @param options [Hash] Options to validate
+      def validate_enrichment_options!(options)
+        if options[:format]
+          format = options[:format].to_s
+          unless VALID_FORMATS.include?(format)
+            raise InvalidRequestError, "Invalid format: #{format}. Valid formats: #{VALID_FORMATS.join(", ")}"
+          end
+
+          if format == "enum" && (!options[:options] || options[:options].empty?)
+            raise InvalidRequestError, "options are required when format is 'enum'"
+          end
+        end
+      end
+
+      # @param options [Hash] Enrichment options
+      # @return [Hash] API-formatted parameters
+      def build_enrichment_params(options)
+        params = { description: options[:description] }
+
+        params[:format] = options[:format] if options[:format]
+        params[:options] = options[:options] if options[:options]
+        params[:instructions] = options[:instructions] if options[:instructions]
+        params[:metadata] = options[:metadata] if options[:metadata]
+
+        params
+      end
+    end
+  end
+end

data/lib/exa/endpoints/webset_items.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module WebsetItems
+      # Lists all Items in a Webset with pagination
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page (1-100)
+      # @param source_id [String, nil] Filter by source ID
+      #
+      # @return [Exa::Resources::WebsetItemsListResponse] Paginated list of Items
+      #
+      # @raise [Exa::NotFoundError] if Webset not found
+      #
+      # @example List all Items in a Webset
+      #   response = client.list_webset_items("webset_abc123")
+      #   response.data.each { |item| puts item.url }
+      #
+      # @example Paginate through Items
+      #   response = client.list_webset_items("webset_abc123", limit: 50)
+      #   all_items = response.data.dup
+      #   while response.has_more?
+      #     response = client.list_webset_items("webset_abc123", cursor: response.next_cursor)
+      #     all_items.concat(response.data)
+      #   end
+      def list_webset_items(webset_id, cursor: nil, limit: nil, source_id: nil)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+
+        if limit && (limit < 1 || limit > 100)
+          raise InvalidRequestError, "limit must be between 1 and 100"
+        end
+
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+        params[:sourceId] = source_id if source_id
+
+        response = websets_get("/websets/#{webset_id}/items", params)
+
+        Resources::WebsetItemsListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Gets a specific Item from a Webset
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param item_id [String] Item ID
+      #
+      # @return [Exa::Resources::WebsetItem] The Item
+      #
+      # @raise [Exa::NotFoundError] if Webset or Item not found
+      #
+      # @example Get an Item
+      #   item = client.get_webset_item("webset_abc123", "item_xyz789")
+      def get_webset_item(webset_id, item_id)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "item_id must be a non-empty string" if !item_id.is_a?(String) || item_id.empty?
+
+        response = websets_get("/websets/#{webset_id}/items/#{item_id}")
+
+        Resources::WebsetItem.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Deletes an Item from a Webset
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param item_id [String] Item ID
+      #
+      # @return [Hash] Deletion confirmation
+      #
+      # @raise [Exa::NotFoundError] if Webset or Item not found
+      #
+      # @example Delete an Item
+      #   client.delete_webset_item("webset_abc123", "item_xyz789")
+      def delete_webset_item(webset_id, item_id)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "item_id must be a non-empty string" if !item_id.is_a?(String) || item_id.empty?
+
+        websets_delete("/websets/#{webset_id}/items/#{item_id}")
+      end
+    end
+  end
+end

data/lib/exa/endpoints/webset_searches.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module WebsetSearches
+      VALID_ENTITY_TYPES = %w[company person research_paper].freeze
+      VALID_BEHAVIORS = %w[override append].freeze
+
+      # Creates a new Search for a Webset
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param query [String] Search query
+      # @param count [Integer] Target number of results
+      # @param entity [Hash] Entity type configuration { type: "company"|"person"|"research_paper" }
+      # @param criteria [Array<Hash>] Criteria for filtering [{ description: "..." }]
+      # @param recall [Boolean] Enable recall estimation
+      # @param exclude [Array<Hash>] Exclusion rules
+      # @param scope [Array<Hash>] Scope configuration
+      # @param behavior [String] Behavior: "override" or "append"
+      # @param metadata [Hash] Custom metadata
+      #
+      # @return [Exa::Resources::WebsetSearch] Created Search
+      #
+      # @raise [Exa::NotFoundError] if Webset not found
+      #
+      # @example Create a Search
+      #   search = client.create_webset_search(
+      #     "webset_abc123",
+      #     query: "AI startups in healthcare",
+      #     count: 100,
+      #     entity: { type: "company" },
+      #     criteria: [{ description: "Must be in healthcare industry" }]
+      #   )
+      def create_webset_search(webset_id, **options)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "query is required" unless options[:query]
+
+        validate_webset_search_options!(options)
+
+        params = build_webset_search_params(options)
+        response = websets_post("/websets/#{webset_id}/searches", params)
+
+        Resources::WebsetSearch.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Gets a Search by ID
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param search_id [String] Search ID
+      #
+      # @return [Exa::Resources::WebsetSearch] The Search
+      #
+      # @raise [Exa::NotFoundError] if Webset or Search not found
+      #
+      # @example Get a Search with progress
+      #   search = client.get_webset_search("webset_abc123", "search_xyz789")
+      #   puts "Progress: #{search.completion_percentage}%"
+      def get_webset_search(webset_id, search_id)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "search_id must be a non-empty string" if !search_id.is_a?(String) || search_id.empty?
+
+        response = websets_get("/websets/#{webset_id}/searches/#{search_id}")
+
+        Resources::WebsetSearch.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Cancels an in-progress Search
+      #
+      # @param webset_id [String] Webset ID or external ID
+      # @param search_id [String] Search ID
+      #
+      # @return [Exa::Resources::WebsetSearch] The canceled Search
+      #
+      # @raise [Exa::NotFoundError] if Webset or Search not found
+      #
+      # @example Cancel a Search
+      #   search = client.cancel_webset_search("webset_abc123", "search_xyz789")
+      #   puts "Canceled at: #{search.canceled_at}"
+      def cancel_webset_search(webset_id, search_id)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "search_id must be a non-empty string" if !search_id.is_a?(String) || search_id.empty?
+
+        response = websets_post("/websets/#{webset_id}/searches/#{search_id}/cancel", {})
+
+        Resources::WebsetSearch.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      # @param options [Hash] Options to validate
+      def validate_webset_search_options!(options)
+        if options[:entity] && options[:entity][:type]
+          entity_type = options[:entity][:type].to_s
+          unless VALID_ENTITY_TYPES.include?(entity_type)
+            raise InvalidRequestError, "Invalid entity type: #{entity_type}. Valid types: #{VALID_ENTITY_TYPES.join(", ")}"
+          end
+        end
+
+        if options[:behavior]
+          behavior = options[:behavior].to_s
+          unless VALID_BEHAVIORS.include?(behavior)
+            raise InvalidRequestError, "Invalid behavior: #{behavior}. Valid behaviors: #{VALID_BEHAVIORS.join(", ")}"
+          end
+        end
+
+        if options[:count] && (options[:count] < 1 || options[:count] > 10_000)
+          raise InvalidRequestError, "count must be between 1 and 10000"
+        end
+      end
+
+      # @param options [Hash] Search options
+      # @return [Hash] API-formatted parameters
+      def build_webset_search_params(options)
+        params = { query: options[:query] }
+
+        params[:count] = options[:count] if options[:count]
+        params[:entity] = options[:entity] if options[:entity]
+        params[:criteria] = options[:criteria] if options[:criteria]
+        params[:recall] = options[:recall] if options.key?(:recall)
+        params[:exclude] = options[:exclude] if options[:exclude]
+        params[:scope] = options[:scope] if options[:scope]
+        params[:behavior] = options[:behavior] if options[:behavior]
+        params[:metadata] = options[:metadata] if options[:metadata]
+
+        params
+      end
+    end
+  end
+end