exaonruby 1.0.0

data/lib/exa/endpoints/imports.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Imports
+      VALID_FORMATS = %w[csv webset].freeze
+      VALID_ENTITY_TYPES = %w[company person article research_paper custom].freeze
+
+      # Creates a new Import to upload data into Websets
+      #
+      # Imports can be used to:
+      # - Enrich: Enhance data with additional information
+      # - Search: Query data using Websets' agentic search
+      # - Exclude: Prevent duplicate results in searches
+      #
+      # Once created, upload your data to the returned uploadUrl.
+      #
+      # @param size [Integer] File size in bytes (max 50MB)
+      # @param count [Integer] Number of records to import
+      # @param format [String] Import format: "csv" or "webset"
+      # @param entity [Hash] Entity type configuration
+      # @option entity [String] :type "company", "person", "article", "research_paper", or "custom"
+      # @param title [String, nil] Title of the import
+      # @param metadata [Hash, nil] Custom metadata
+      # @param csv [Hash, nil] CSV-specific parameters (identifier column index)
+      #
+      # @return [Exa::Resources::Import] Created Import with uploadUrl
+      #
+      # @example Create a CSV import
+      #   import = client.create_import(
+      #     size: 1024,
+      #     count: 100,
+      #     format: "csv",
+      #     entity: { type: "company" },
+      #     title: "Q4 Leads",
+      #     csv: { identifier: 1 }
+      #   )
+      #   puts "Upload to: #{import.upload_url}"
+      #   puts "Valid until: #{import.upload_valid_until}"
+      def create_import(size:, count:, format: "csv", entity:, title: nil, metadata: nil, csv: nil)
+        validate_import_params!(size, format, entity)
+
+        params = {
+          size: size,
+          count: count,
+          format: format,
+          entity: entity
+        }
+        params[:title] = title if title
+        params[:metadata] = metadata if metadata
+        params[:csv] = csv if csv
+
+        response = websets_post("/imports", params)
+
+        Resources::Import.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Gets an Import by ID
+      #
+      # @param import_id [String] Import ID
+      # @return [Exa::Resources::Import] The Import
+      def get_import(import_id)
+        raise InvalidRequestError, "import_id must be a non-empty string" if !import_id.is_a?(String) || import_id.empty?
+
+        response = websets_get("/imports/#{import_id}")
+
+        Resources::Import.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Lists all Imports
+      #
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page
+      #
+      # @return [Exa::Resources::ImportListResponse] Paginated list of Imports
+      def list_imports(cursor: nil, limit: nil)
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+
+        response = websets_get("/imports", params)
+
+        Resources::ImportListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Updates an Import
+      #
+      # @param import_id [String] Import ID
+      # @param title [String, nil] Updated title
+      # @param metadata [Hash, nil] Updated metadata
+      #
+      # @return [Exa::Resources::Import] Updated Import
+      def update_import(import_id, title: nil, metadata: nil)
+        raise InvalidRequestError, "import_id must be a non-empty string" if !import_id.is_a?(String) || import_id.empty?
+
+        params = {}
+        params[:title] = title if title
+        params[:metadata] = metadata if metadata
+
+        response = websets_patch("/imports/#{import_id}", params)
+
+        Resources::Import.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Deletes an Import
+      #
+      # @param import_id [String] Import ID
+      # @return [Hash] Deletion confirmation
+      def delete_import(import_id)
+        raise InvalidRequestError, "import_id must be a non-empty string" if !import_id.is_a?(String) || import_id.empty?
+
+        websets_delete("/imports/#{import_id}")
+      end
+
+      private
+
+      def validate_import_params!(size, format, entity)
+        if size > 50_000_000
+          raise InvalidRequestError, "size must be 50MB or less"
+        end
+
+        unless VALID_FORMATS.include?(format)
+          raise InvalidRequestError, "Invalid format: #{format}. Valid formats: #{VALID_FORMATS.join(", ")}"
+        end
+
+        if entity && entity[:type]
+          entity_type = entity[:type].to_s.downcase.tr(" ", "_")
+          unless VALID_ENTITY_TYPES.include?(entity_type)
+            raise InvalidRequestError, "Invalid entity type: #{entity[:type]}. Valid types: #{VALID_ENTITY_TYPES.join(", ")}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/exa/endpoints/monitors.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Monitors
+      VALID_BEHAVIOR_TYPES = %w[search refresh].freeze
+
+      # Creates a new Monitor to continuously keep Websets updated
+      #
+      # Monitors automatically run on your defined schedule to ensure Websets
+      # stay current without manual intervention:
+      # - Find new content via search operations
+      # - Update existing content via refresh operations
+      # - Automated scheduling using cron expressions
+      #
+      # @param webset_id [String] The Webset ID to monitor
+      # @param cadence [Hash] Schedule configuration
+      # @option cadence [String] :cron Cron expression for scheduling
+      # @option cadence [String] :timezone Timezone (default: "Etc/UTC")
+      # @param behavior [Hash] Behavior when monitor runs
+      # @option behavior [String] :type "search" or "refresh"
+      # @option behavior [Hash] :config Configuration for the behavior
+      # @param metadata [Hash] Custom metadata key-value pairs
+      #
+      # @return [Exa::Resources::Monitor] Created Monitor
+      #
+      # @example Create a daily search monitor
+      #   monitor = client.create_monitor(
+      #     webset_id: "webset_abc123",
+      #     cadence: { cron: "0 9 * * *", timezone: "America/New_York" },
+      #     behavior: {
+      #       type: "search",
+      #       config: {
+      #         count: 50,
+      #         query: "AI news today",
+      #         entity: { type: "article" },
+      #         behavior: "append"
+      #       }
+      #     }
+      #   )
+      def create_monitor(webset_id:, cadence:, behavior:, metadata: nil)
+        validate_monitor_params!(webset_id, cadence, behavior)
+
+        params = {
+          websetId: webset_id,
+          cadence: cadence,
+          behavior: behavior
+        }
+        params[:metadata] = metadata if metadata
+
+        response = websets_post("/monitors", params)
+
+        Resources::Monitor.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Gets a Monitor by ID
+      #
+      # @param monitor_id [String] Monitor ID
+      # @return [Exa::Resources::Monitor] The Monitor
+      #
+      # @example Get a monitor
+      #   monitor = client.get_monitor("monitor_abc123")
+      #   puts "Next run: #{monitor.next_run_at}"
+      def get_monitor(monitor_id)
+        raise InvalidRequestError, "monitor_id must be a non-empty string" if !monitor_id.is_a?(String) || monitor_id.empty?
+
+        response = websets_get("/monitors/#{monitor_id}")
+
+        Resources::Monitor.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Lists all Monitors
+      #
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page
+      # @param webset_id [String, nil] Filter by Webset ID
+      #
+      # @return [Exa::Resources::MonitorListResponse] Paginated list of Monitors
+      #
+      # @example List monitors
+      #   response = client.list_monitors(limit: 10)
+      #   response.data.each { |m| puts "#{m.id}: #{m.status}" }
+      def list_monitors(cursor: nil, limit: nil, webset_id: nil)
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+        params[:websetId] = webset_id if webset_id
+
+        response = websets_get("/monitors", params)
+
+        Resources::MonitorListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Updates a Monitor
+      #
+      # @param monitor_id [String] Monitor ID
+      # @param cadence [Hash, nil] Updated schedule configuration
+      # @param behavior [Hash, nil] Updated behavior configuration
+      # @param status [String, nil] "enabled" or "disabled"
+      # @param metadata [Hash, nil] Updated metadata
+      #
+      # @return [Exa::Resources::Monitor] Updated Monitor
+      #
+      # @example Disable a monitor
+      #   monitor = client.update_monitor("monitor_abc123", status: "disabled")
+      def update_monitor(monitor_id, cadence: nil, behavior: nil, status: nil, metadata: nil)
+        raise InvalidRequestError, "monitor_id must be a non-empty string" if !monitor_id.is_a?(String) || monitor_id.empty?
+
+        params = {}
+        params[:cadence] = cadence if cadence
+        params[:behavior] = behavior if behavior
+        params[:status] = status if status
+        params[:metadata] = metadata if metadata
+
+        response = websets_patch("/monitors/#{monitor_id}", params)
+
+        Resources::Monitor.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Deletes a Monitor
+      #
+      # @param monitor_id [String] Monitor ID
+      # @return [Hash] Deletion confirmation
+      #
+      # @example Delete a monitor
+      #   client.delete_monitor("monitor_abc123")
+      def delete_monitor(monitor_id)
+        raise InvalidRequestError, "monitor_id must be a non-empty string" if !monitor_id.is_a?(String) || monitor_id.empty?
+
+        websets_delete("/monitors/#{monitor_id}")
+      end
+
+      # Gets a specific Monitor Run
+      #
+      # @param monitor_id [String] Monitor ID
+      # @param run_id [String] Run ID
+      # @return [Exa::Resources::MonitorRun] The Monitor Run
+      def get_monitor_run(monitor_id, run_id)
+        raise InvalidRequestError, "monitor_id must be a non-empty string" if !monitor_id.is_a?(String) || monitor_id.empty?
+        raise InvalidRequestError, "run_id must be a non-empty string" if !run_id.is_a?(String) || run_id.empty?
+
+        response = websets_get("/monitors/#{monitor_id}/runs/#{run_id}")
+
+        Resources::MonitorRun.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Lists runs for a Monitor
+      #
+      # @param monitor_id [String] Monitor ID
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page
+      #
+      # @return [Exa::Resources::MonitorRunListResponse] Paginated list of runs
+      def list_monitor_runs(monitor_id, cursor: nil, limit: nil)
+        raise InvalidRequestError, "monitor_id must be a non-empty string" if !monitor_id.is_a?(String) || monitor_id.empty?
+
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+
+        response = websets_get("/monitors/#{monitor_id}/runs", params)
+
+        Resources::MonitorRunListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      def validate_monitor_params!(webset_id, cadence, behavior)
+        raise InvalidRequestError, "webset_id must be a non-empty string" if !webset_id.is_a?(String) || webset_id.empty?
+        raise InvalidRequestError, "cadence is required" unless cadence
+        raise InvalidRequestError, "behavior is required" unless behavior
+
+        if behavior[:type] && !VALID_BEHAVIOR_TYPES.include?(behavior[:type])
+          raise InvalidRequestError, "Invalid behavior type: #{behavior[:type]}. Valid types: #{VALID_BEHAVIOR_TYPES.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/exa/endpoints/research.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Research
+      VALID_MODELS = %w[exa-research-fast exa-research exa-research-pro].freeze
+      VALID_STATUSES = %w[pending running completed canceled failed].freeze
+
+      # Create an asynchronous research task
+      #
+      # Creates a research task that explores the web, gathers sources, synthesizes
+      # findings, and returns results with citations. Can generate:
+      # 1. Structured JSON matching an outputSchema you provide
+      # 2. A detailed markdown report when no schema is provided
+      #
+      # The API responds immediately with a research_id for polling completion status.
+      #
+      # @param instructions [String] Instructions for what to research (max 4096 chars)
+      # @param model [String] Research model: "exa-research-fast", "exa-research", "exa-research-pro"
+      # @param output_schema [Hash] JSON Schema to enforce structured output
+      #
+      # @return [Exa::Resources::ResearchTask] Research task with ID for polling
+      #
+      # @raise [Exa::InvalidRequestError] if parameters are invalid
+      #
+      # @example Create a basic research task
+      #   task = client.create_research(
+      #     instructions: "Summarize the latest developments in AI safety research"
+      #   )
+      #   puts "Task ID: #{task.research_id}"
+      #   puts "Status: #{task.status}"
+      #
+      # @example Create research with structured output
+      #   schema = {
+      #     type: "object",
+      #     properties: {
+      #       companies: {
+      #         type: "array",
+      #         items: { type: "string" }
+      #       },
+      #       summary: { type: "string" }
+      #     }
+      #   }
+      #   task = client.create_research(
+      #     instructions: "Find the top 5 AI startups in 2024",
+      #     model: "exa-research-pro",
+      #     output_schema: schema
+      #   )
+      def create_research(instructions:, model: "exa-research", output_schema: nil)
+        validate_research_params!(instructions, model)
+
+        params = {
+          instructions: instructions,
+          model: model
+        }
+        params[:outputSchema] = output_schema if output_schema
+
+        response = post("/research/v1", params)
+
+        Resources::ResearchTask.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Get the status and results of a research task
+      #
+      # Poll this endpoint to check research progress. When status is "completed",
+      # the output field contains the research results.
+      #
+      # @param research_id [String] The research task ID
+      #
+      # @return [Exa::Resources::ResearchTask] Research task with current status and output
+      #
+      # @raise [Exa::NotFoundError] if research task not found
+      #
+      # @example Poll for completion
+      #   task = client.get_research(research_id)
+      #   case task.status
+      #   when "completed"
+      #     puts task.output
+      #   when "running"
+      #     puts "Progress: #{task.operations_completed}/#{task.operations_total}"
+      #   when "failed"
+      #     puts "Error: #{task.error_message}"
+      #   end
+      def get_research(research_id)
+        raise InvalidRequestError, "research_id must be a non-empty string" if !research_id.is_a?(String) || research_id.empty?
+
+        response = get("/research/v1/#{research_id}")
+
+        Resources::ResearchTask.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # List all research tasks
+      #
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page
+      #
+      # @return [Exa::Resources::ResearchListResponse] Paginated list of research tasks
+      #
+      # @example List recent research tasks
+      #   response = client.list_research(limit: 10)
+      #   response.data.each { |task| puts "#{task.research_id}: #{task.status}" }
+      def list_research(cursor: nil, limit: nil)
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+
+        response = get("/research/v1", params)
+
+        Resources::ResearchListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Cancel a running research task
+      #
+      # @param research_id [String] The research task ID to cancel
+      #
+      # @return [Exa::Resources::ResearchTask] The canceled research task
+      #
+      # @raise [Exa::NotFoundError] if research task not found
+      #
+      # @example Cancel a research task
+      #   task = client.cancel_research(research_id)
+      #   puts "Canceled: #{task.status}" # => "canceled"
+      def cancel_research(research_id)
+        raise InvalidRequestError, "research_id must be a non-empty string" if !research_id.is_a?(String) || research_id.empty?
+
+        response = post("/research/v1/#{research_id}/cancel", {})
+
+        Resources::ResearchTask.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      # @param instructions [String] Research instructions
+      # @param model [String] Research model
+      def validate_research_params!(instructions, model)
+        raise InvalidRequestError, "instructions must be a non-empty string" if !instructions.is_a?(String) || instructions.empty?
+
+        if instructions.length > 4096
+          raise InvalidRequestError, "instructions must be 4096 characters or less"
+        end
+
+        unless VALID_MODELS.include?(model)
+          raise InvalidRequestError, "Invalid model: #{model}. Valid models: #{VALID_MODELS.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/exa/endpoints/search.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Search
+      VALID_SEARCH_TYPES = %i[neural auto fast deep].freeze
+      VALID_CATEGORIES = %i[
+        people company research_paper news pdf github tweet personal_site financial_report
+      ].freeze
+      VALID_LIVECRAWL_OPTIONS = %i[never fallback preferred always].freeze
+
+      # Performs an intelligent web search using Exa's embeddings-based model
+      #
+      # @param query [String] The search query string
+      # @param type [Symbol] Search type: :neural, :auto (default), :fast, or :deep
+      # @param additional_queries [Array<String>] Additional query variations for deep search
+      # @param category [Symbol] Data category to focus on (e.g., :people, :company, :research_paper)
+      # @param num_results [Integer] Number of results to return (max 100)
+      # @param include_domains [Array<String>] Domains to include in results
+      # @param exclude_domains [Array<String>] Domains to exclude from results
+      # @param start_crawl_date [String, Time] Results crawled after this date (ISO 8601)
+      # @param end_crawl_date [String, Time] Results crawled before this date (ISO 8601)
+      # @param start_published_date [String, Time] Results published after this date (ISO 8601)
+      # @param end_published_date [String, Time] Results published before this date (ISO 8601)
+      # @param include_text [Array<String>] Strings that must be present in page text
+      # @param exclude_text [Array<String>] Strings that must not be present in page text
+      # @param country [String] Two-letter ISO country code (e.g., "US")
+      # @param text [Boolean, Hash] Return text content. Hash for options: { max_characters: 1000 }
+      # @param highlights [Boolean, Hash] Return highlights. Hash for options: { num_sentences: 3, highlight_query: "..." }
+      # @param summary [Boolean, Hash] Return summary. Hash for options: { query: "..." }
+      # @param context [Boolean, Integer] Return context string for LLM. Integer for max characters
+      # @param moderation [Boolean] Enable content moderation
+      # @param livecrawl [Symbol] Livecrawl option: :never, :fallback, :preferred, :always
+      # @param livecrawl_timeout [Integer] Livecrawl timeout in milliseconds
+      # @param subpages [Integer] Number of subpages to crawl
+      # @param subpage_target [String, Array<String>] Terms to find specific subpages
+      #
+      # @return [Exa::Resources::SearchResponse] Search results
+      #
+      # @raise [Exa::InvalidRequestError] if parameters are invalid
+      # @raise [Exa::AuthenticationError] if API key is invalid
+      # @raise [Exa::RateLimitError] if rate limit is exceeded
+      #
+      # @example Basic search
+      #   client.search("Latest developments in LLMs")
+      #
+      # @example Search with content extraction
+      #   client.search("AI research papers", text: true, num_results: 20)
+      #
+      # @example Deep search with filters
+      #   client.search(
+      #     "Machine learning startups",
+      #     type: :deep,
+      #     category: :company,
+      #     include_domains: ["linkedin.com", "crunchbase.com"],
+      #     start_published_date: "2024-01-01T00:00:00.000Z"
+      #   )
+      def search(query, **options)
+        validate_search_options!(options)
+
+        params = build_search_params(query, options)
+        response = post("/search", params)
+
+        Resources::SearchResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      # @param options [Hash] Search options to validate
+      # @raise [Exa::InvalidRequestError] if options are invalid
+      def validate_search_options!(options)
+        if options[:type] && !VALID_SEARCH_TYPES.include?(options[:type])
+          raise InvalidRequestError, "Invalid search type: #{options[:type]}. Valid types: #{VALID_SEARCH_TYPES.join(", ")}"
+        end
+
+        if options[:category] && !VALID_CATEGORIES.include?(options[:category])
+          raise InvalidRequestError, "Invalid category: #{options[:category]}. Valid categories: #{VALID_CATEGORIES.join(", ")}"
+        end
+
+        if options[:livecrawl] && !VALID_LIVECRAWL_OPTIONS.include?(options[:livecrawl])
+          raise InvalidRequestError, "Invalid livecrawl option: #{options[:livecrawl]}. Valid options: #{VALID_LIVECRAWL_OPTIONS.join(", ")}"
+        end
+
+        if options[:num_results] && (options[:num_results] < 1 || options[:num_results] > 100)
+          raise InvalidRequestError, "num_results must be between 1 and 100"
+        end
+
+        if options[:additional_queries] && options[:type] != :deep
+          raise InvalidRequestError, "additional_queries is only supported with type: :deep"
+        end
+      end
+
+      # @param query [String] Search query
+      # @param options [Hash] Search options
+      # @return [Hash] API-formatted parameters
+      def build_search_params(query, options)
+        params = { query: query }
+
+        params[:type] = options[:type].to_s if options[:type]
+        params[:additionalQueries] = options[:additional_queries] if options[:additional_queries]
+        params[:category] = format_category(options[:category]) if options[:category]
+        params[:numResults] = options[:num_results] if options[:num_results]
+        params[:userLocation] = options[:country] if options[:country]
+        params[:moderation] = options[:moderation] if options.key?(:moderation)
+
+        add_domain_filters!(params, options)
+        add_date_filters!(params, options)
+        add_text_filters!(params, options)
+        add_content_options!(params, options)
+
+        params
+      end
+
+      # @param category [Symbol] Category symbol
+      # @return [String] API-formatted category
+      def format_category(category)
+        category.to_s.tr("_", " ")
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_domain_filters!(params, options)
+        params[:includeDomains] = options[:include_domains] if options[:include_domains]
+        params[:excludeDomains] = options[:exclude_domains] if options[:exclude_domains]
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_date_filters!(params, options)
+        params[:startCrawlDate] = format_date(options[:start_crawl_date]) if options[:start_crawl_date]
+        params[:endCrawlDate] = format_date(options[:end_crawl_date]) if options[:end_crawl_date]
+        params[:startPublishedDate] = format_date(options[:start_published_date]) if options[:start_published_date]
+        params[:endPublishedDate] = format_date(options[:end_published_date]) if options[:end_published_date]
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_text_filters!(params, options)
+        params[:includeText] = options[:include_text] if options[:include_text]
+        params[:excludeText] = options[:exclude_text] if options[:exclude_text]
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_content_options!(params, options)
+        params[:text] = format_content_option(options[:text]) if options.key?(:text)
+        params[:highlights] = format_highlights_option(options[:highlights]) if options.key?(:highlights)
+        params[:summary] = format_summary_option(options[:summary]) if options.key?(:summary)
+
+        if options.key?(:context)
+          params[:context] = options[:context].is_a?(Integer) ? { maxCharacters: options[:context] } : options[:context]
+        end
+
+        params[:livecrawl] = options[:livecrawl].to_s if options[:livecrawl]
+        params[:livecrawlTimeout] = options[:livecrawl_timeout] if options[:livecrawl_timeout]
+        params[:subpages] = options[:subpages] if options[:subpages]
+        params[:subpageTarget] = options[:subpage_target] if options[:subpage_target]
+      end
+
+      # @param option [Boolean, Hash] Text option
+      # @return [Boolean, Hash] Formatted option
+      def format_content_option(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param option [Boolean, Hash] Highlights option
+      # @return [Boolean, Hash] Formatted option
+      def format_highlights_option(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param option [Boolean, Hash] Summary option
+      # @return [Boolean, Hash] Formatted option
+      def format_summary_option(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param value [Time, Date, String, nil] Date value
+      # @return [String, nil] ISO 8601 formatted string
+      def format_date(value)
+        Utils::ParameterConverter.format_date(value)
+      end
+    end
+  end
+end