zenrows 0.1.0

data/lib/zenrows/configuration.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Zenrows
+  # Global configuration for Zenrows client
+  #
+  # @example Configure with block
+  #   Zenrows.configure do |config|
+  #     config.api_key = 'YOUR_API_KEY'
+  #     config.host = 'superproxy.zenrows.com'
+  #     config.port = 1337
+  #   end
+  #
+  # @example Configure directly
+  #   Zenrows.configuration.api_key = 'YOUR_API_KEY'
+  #
+  # @author Ernest Bursa
+  # @since 0.1.0
+  # @api public
+  class Configuration
+    include MonitorMixin
+
+    # @return [String, nil] ZenRows API key (required)
+    attr_accessor :api_key
+
+    # @return [String] ZenRows proxy host
+    attr_accessor :host
+
+    # @return [Integer] ZenRows proxy port
+    attr_accessor :port
+
+    # @return [Integer] Default connection timeout in seconds
+    attr_accessor :connect_timeout
+
+    # @return [Integer] Default read timeout in seconds
+    attr_accessor :read_timeout
+
+    # @return [Symbol] HTTP backend to use (:http_rb, :faraday, :net_http)
+    attr_accessor :backend
+
+    # @return [Logger, nil] Logger instance for debug output
+    attr_accessor :logger
+
+    # Default configuration values
+    DEFAULTS = {
+      host: "superproxy.zenrows.com",
+      port: 1337,
+      connect_timeout: 5,
+      read_timeout: 180,
+      backend: :http_rb
+    }.freeze
+
+    def initialize
+      super # Initialize MonitorMixin
+      reset!
+    end
+
+    # Reset configuration to defaults
+    #
+    # @return [void]
+    def reset!
+      synchronize do
+        @api_key = nil
+        @host = DEFAULTS[:host]
+        @port = DEFAULTS[:port]
+        @connect_timeout = DEFAULTS[:connect_timeout]
+        @read_timeout = DEFAULTS[:read_timeout]
+        @backend = DEFAULTS[:backend]
+        @logger = nil
+      end
+    end
+
+    # Validate that required configuration is present
+    #
+    # @raise [ConfigurationError] if api_key is missing
+    # @return [true] if configuration is valid
+    def validate!
+      raise ConfigurationError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      true
+    end
+
+    # Check if configuration is valid
+    #
+    # @return [Boolean] true if configuration is valid
+    def valid?
+      validate!
+      true
+    rescue ConfigurationError
+      false
+    end
+
+    # Convert configuration to hash
+    #
+    # @return [Hash] configuration as hash
+    def to_h
+      {
+        api_key: api_key,
+        host: host,
+        port: port,
+        connect_timeout: connect_timeout,
+        read_timeout: read_timeout,
+        backend: backend
+      }
+    end
+  end
+
+  class << self
+    # @return [Configuration] Global configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure Zenrows with a block
+    #
+    # @example
+    #   Zenrows.configure do |config|
+    #     config.api_key = 'YOUR_API_KEY'
+    #   end
+    #
+    # @yield [Configuration] configuration instance
+    # @return [Configuration] configuration instance
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Reset configuration to defaults
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/zenrows/errors.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Zenrows
+  # Base error class for all Zenrows errors
+  #
+  # @author Ernest Bursa
+  # @since 0.1.0
+  # @api public
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or missing
+  #
+  # @example
+  #   raise Zenrows::ConfigurationError, "API key is required"
+  class ConfigurationError < Error; end
+
+  # Raised when API authentication fails (invalid API key)
+  #
+  # @example
+  #   raise Zenrows::AuthenticationError, "Invalid API key"
+  class AuthenticationError < Error; end
+
+  # Raised when rate limited (HTTP 429)
+  #
+  # @example Handling rate limits
+  #   begin
+  #     response = http.get(url)
+  #   rescue Zenrows::RateLimitError => e
+  #     sleep(e.retry_after || 60)
+  #     retry
+  #   end
+  class RateLimitError < Error
+    # @return [Integer, nil] Seconds to wait before retrying
+    attr_reader :retry_after
+
+    # @param message [String] Error message
+    # @param retry_after [Integer, nil] Seconds to wait before retrying
+    def initialize(message = "Rate limited", retry_after: nil)
+      @retry_after = retry_after
+      super(message)
+    end
+  end
+
+  # Raised when bot detection triggers (HTTP 400/403/422)
+  #
+  # @example
+  #   begin
+  #     response = http.get(url)
+  #   rescue Zenrows::BotDetectedError => e
+  #     # Retry with premium proxy
+  #     http = client.http(premium_proxy: true, proxy_country: 'us')
+  #     response = http.get(url)
+  #   end
+  class BotDetectedError < Error
+    # @return [String, nil] Suggested fix command
+    attr_reader :suggestion
+
+    # @param message [String] Error message
+    # @param suggestion [String, nil] Suggested fix
+    def initialize(message = "Bot detected", suggestion: nil)
+      @suggestion = suggestion
+      super(message)
+    end
+  end
+
+  # Raised when request times out
+  class TimeoutError < Error; end
+
+  # Raised when proxy connection fails
+  class ProxyError < Error; end
+
+  # Raised when wait time exceeds maximum (180 seconds)
+  class WaitTimeError < Error; end
+end

data/lib/zenrows/js_instructions.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Zenrows
+  # DSL for building JavaScript instructions
+  #
+  # JavaScript instructions enable dynamic interaction with web pages
+  # by automating user actions like clicking, filling forms, scrolling,
+  # and executing custom JavaScript.
+  #
+  # @example Building instructions with DSL
+  #   instructions = Zenrows::JsInstructions.build do
+  #     click '.load-more'
+  #     wait 2000
+  #     fill 'input#email', 'test@example.com'
+  #     scroll_to :bottom
+  #     wait_for '.results'
+  #   end
+  #
+  # @example Using with client
+  #   client = Zenrows::Client.new
+  #   http = client.http(
+  #     js_render: true,
+  #     js_instructions: instructions
+  #   )
+  #
+  # @author Ernest Bursa
+  # @since 0.1.0
+  # @api public
+  class JsInstructions
+    # @return [Array<Hash>] List of instructions
+    attr_reader :instructions
+
+    def initialize
+      @instructions = []
+    end
+
+    # Build instructions using DSL block
+    #
+    # @yield [JsInstructions] Builder instance
+    # @return [JsInstructions] Built instructions
+    #
+    # @example
+    #   Zenrows::JsInstructions.build do
+    #     click '.button'
+    #     wait 1000
+    #   end
+    def self.build(&block)
+      builder = new
+      builder.instance_eval(&block) if block
+      builder
+    end
+
+    # Click an element
+    #
+    # @param selector [String] CSS selector
+    # @return [self]
+    #
+    # @example
+    #   click '.submit-button'
+    #   click '#load-more'
+    def click(selector)
+      @instructions << {click: selector}
+      self
+    end
+
+    # Wait for a duration in milliseconds
+    #
+    # @param duration [Integer] Milliseconds to wait (max 10000)
+    # @return [self]
+    #
+    # @example
+    #   wait 2000  # Wait 2 seconds
+    def wait(duration)
+      @instructions << {wait: duration}
+      self
+    end
+
+    # Wait for an element to appear
+    #
+    # @param selector [String] CSS selector
+    # @return [self]
+    #
+    # @example
+    #   wait_for '.dynamic-content'
+    #   wait_for '#results-loaded'
+    def wait_for(selector)
+      @instructions << {wait_for: selector}
+      self
+    end
+
+    # Wait for a browser event
+    #
+    # @param event [String, Symbol] Event name: networkidle, load, domcontentloaded
+    # @return [self]
+    #
+    # @example
+    #   wait_event :networkidle
+    def wait_event(event)
+      @instructions << {wait_event: event.to_s}
+      self
+    end
+
+    # Fill an input field
+    #
+    # @param selector [String] CSS selector for input
+    # @param value [String] Value to fill
+    # @return [self]
+    #
+    # @example
+    #   fill 'input#email', 'user@example.com'
+    #   fill 'input[name="password"]', 'secret123'
+    def fill(selector, value)
+      @instructions << {fill: [selector, value]}
+      self
+    end
+
+    # Check a checkbox
+    #
+    # @param selector [String] CSS selector
+    # @return [self]
+    def check(selector)
+      @instructions << {check: selector}
+      self
+    end
+
+    # Uncheck a checkbox
+    #
+    # @param selector [String] CSS selector
+    # @return [self]
+    def uncheck(selector)
+      @instructions << {uncheck: selector}
+      self
+    end
+
+    # Select an option from dropdown
+    #
+    # @param selector [String] CSS selector for select element
+    # @param value [String] Option value to select
+    # @return [self]
+    #
+    # @example
+    #   select_option '#country', 'US'
+    def select_option(selector, value)
+      @instructions << {select_option: [selector, value]}
+      self
+    end
+
+    # Scroll vertically
+    #
+    # @param pixels [Integer] Pixels to scroll (negative = up)
+    # @return [self]
+    #
+    # @example
+    #   scroll_y 1500   # Scroll down
+    #   scroll_y -500   # Scroll up
+    def scroll_y(pixels)
+      @instructions << {scroll_y: pixels}
+      self
+    end
+
+    # Scroll horizontally
+    #
+    # @param pixels [Integer] Pixels to scroll (negative = left)
+    # @return [self]
+    def scroll_x(pixels)
+      @instructions << {scroll_x: pixels}
+      self
+    end
+
+    # Scroll to position
+    #
+    # @param position [String, Symbol] :bottom or :top
+    # @return [self]
+    #
+    # @example
+    #   scroll_to :bottom
+    #   scroll_to :top
+    def scroll_to(position)
+      @instructions << {scroll_to: position.to_s}
+      self
+    end
+
+    # Execute custom JavaScript
+    #
+    # @param code [String] JavaScript code to execute
+    # @return [self]
+    #
+    # @example
+    #   evaluate "window.scrollTo(0, document.body.scrollHeight)"
+    #   evaluate "document.querySelector('.modal').remove()"
+    def evaluate(code)
+      @instructions << {evaluate: code}
+      self
+    end
+
+    # Click element inside iframe
+    #
+    # @param iframe_selector [String] CSS selector for iframe
+    # @param element_selector [String] CSS selector for element inside iframe
+    # @return [self]
+    def frame_click(iframe_selector, element_selector)
+      @instructions << {frame_click: [iframe_selector, element_selector]}
+      self
+    end
+
+    # Wait for element inside iframe
+    #
+    # @param iframe_selector [String] CSS selector for iframe
+    # @param element_selector [String] CSS selector for element
+    # @return [self]
+    def frame_wait_for(iframe_selector, element_selector)
+      @instructions << {frame_wait_for: [iframe_selector, element_selector]}
+      self
+    end
+
+    # Fill input inside iframe
+    #
+    # @param iframe_selector [String] CSS selector for iframe
+    # @param input_selector [String] CSS selector for input
+    # @param value [String] Value to fill
+    # @return [self]
+    def frame_fill(iframe_selector, input_selector, value)
+      @instructions << {frame_fill: [iframe_selector, input_selector, value]}
+      self
+    end
+
+    # Execute JavaScript inside iframe
+    #
+    # @param iframe_name [String] Iframe name or URL
+    # @param code [String] JavaScript code
+    # @return [self]
+    def frame_evaluate(iframe_name, code)
+      @instructions << {frame_evaluate: [iframe_name, code]}
+      self
+    end
+
+    # Convert to JSON string for API
+    #
+    # @return [String] JSON-encoded instructions
+    def to_json(*_args)
+      @instructions.to_json
+    end
+
+    # Convert to array
+    #
+    # @return [Array<Hash>] Instructions array
+    def to_a
+      @instructions.dup
+    end
+
+    # Check if there are any instructions
+    #
+    # @return [Boolean]
+    def empty?
+      @instructions.empty?
+    end
+
+    # Number of instructions
+    #
+    # @return [Integer]
+    def size
+      @instructions.size
+    end
+  end
+end

data/lib/zenrows/proxy.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "securerandom"
+
+module Zenrows
+  # Builds ZenRows proxy configuration
+  #
+  # ZenRows proxy encodes options in the password field of the proxy URL.
+  # Format: http://API_KEY-opt1=val1&opt2=val2:@host:port
+  #
+  # @example Basic proxy configuration
+  #   proxy = Zenrows::Proxy.new(api_key: 'key', host: 'proxy.zenrows.com', port: 1337)
+  #   proxy.build(js_render: true, premium_proxy: true)
+  #   # => { host: 'proxy.zenrows.com', port: 1337, username: 'key', password: 'js_render=true&premium_proxy=true' }
+  #
+  # @author Ernest Bursa
+  # @since 0.1.0
+  # @api public
+  class Proxy
+    # Maximum wait time in milliseconds (3 minutes)
+    MAX_WAIT_MS = 180_000
+
+    # Valid sticky TTL values for HTTP proxy
+    VALID_STICKY_TTL = %w[30s 5m 30m 1h 1d].freeze
+
+    # Valid region codes for HTTP proxy
+    VALID_REGIONS = {
+      "africa" => "af",
+      "af" => "af",
+      "asia pacific" => "ap",
+      "ap" => "ap",
+      "europe" => "eu",
+      "eu" => "eu",
+      "middle east" => "me",
+      "me" => "me",
+      "north america" => "na",
+      "na" => "na",
+      "south america" => "sa",
+      "sa" => "sa",
+      "global" => nil
+    }.freeze
+
+    # @return [String] ZenRows API key
+    attr_reader :api_key
+
+    # @return [String] Proxy host
+    attr_reader :host
+
+    # @return [Integer] Proxy port
+    attr_reader :port
+
+    # @param api_key [String] ZenRows API key
+    # @param host [String] Proxy host
+    # @param port [Integer] Proxy port
+    def initialize(api_key:, host:, port:)
+      @api_key = api_key
+      @host = host
+      @port = port
+    end
+
+    # Build proxy configuration hash for HTTP client
+    #
+    # @param options [Hash] Proxy options
+    # @option options [Boolean] :js_render Enable JavaScript rendering
+    # @option options [Boolean] :premium_proxy Use residential proxies
+    # @option options [String] :proxy_country Country code (us, gb, de, etc.)
+    # @option options [Boolean, Integer] :wait Wait time (true=15s, Integer=ms)
+    # @option options [String] :wait_for CSS selector to wait for
+    # @option options [Boolean, String, Integer] :session_id Session persistence
+    # @option options [Integer] :window_height Browser window height
+    # @option options [Integer] :window_width Browser window width
+    # @option options [Array, String] :js_instructions JavaScript instructions
+    # @option options [Boolean] :json_response Return JSON instead of HTML
+    # @option options [Boolean] :original_status Return original HTTP status
+    # @option options [Boolean] :screenshot Take screenshot
+    # @option options [Boolean] :screenshot_fullpage Full page screenshot
+    # @option options [String] :screenshot_selector Screenshot specific element
+    # @option options [Boolean] :custom_headers Enable custom headers passthrough
+    # @option options [String] :block_resources Block resources (image,media,font)
+    # @return [Hash] Proxy configuration with :host, :port, :username, :password
+    # @raise [WaitTimeError] if wait time exceeds 3 minutes
+    def build(options = {})
+      opts = options.dup
+      proxy_params = build_params(opts)
+
+      {
+        host: host,
+        port: port,
+        username: api_key,
+        password: proxy_params.map { |k, v| "#{k}=#{v}" }.join("&")
+      }
+    end
+
+    # Build proxy URL string
+    #
+    # @param options [Hash] Proxy options (same as #build)
+    # @return [String] Proxy URL
+    def build_url(options = {})
+      config = build(options)
+      password = config[:password].empty? ? "" : config[:password]
+      "http://#{config[:username]}:#{password}@#{config[:host]}:#{config[:port]}"
+    end
+
+    # Build proxy configuration as array [host, port, username, password]
+    #
+    # @param options [Hash] Proxy options (same as #build)
+    # @return [Array<String, Integer, String, String>] Proxy array
+    def build_array(options = {})
+      config = build(options)
+      [config[:host], config[:port], config[:username], config[:password]]
+    end
+
+    private
+
+    # Build proxy parameters hash from options
+    #
+    # @param opts [Hash] Options hash (will be modified)
+    # @return [Hash] Parameters for proxy password
+    def build_params(opts)
+      params = {}
+
+      # Custom headers must be enabled first if we'll use headers
+      params[:custom_headers] = true if opts[:custom_headers]
+
+      # JavaScript rendering
+      params[:js_render] = true if opts[:js_render]
+
+      # Premium proxy
+      params[:premium_proxy] = true if opts[:premium_proxy]
+
+      # Wait time handling
+      if opts[:wait]
+        wait_ms = normalize_wait(opts[:wait])
+        raise WaitTimeError, "Wait time cannot exceed 3 minutes (#{MAX_WAIT_MS}ms), got #{wait_ms}ms" if wait_ms > MAX_WAIT_MS
+
+        params[:wait] = wait_ms
+      end
+
+      # Wait for selector
+      params[:wait_for] = opts[:wait_for] if opts[:wait_for]
+
+      # JSON response
+      params[:json_response] = true if opts[:json_response]
+
+      # Original status
+      params[:original_status] = true if opts[:original_status]
+
+      # Session ID
+      if opts[:session_id] == true
+        params[:session_id] = SecureRandom.random_number(1_000)
+      elsif opts[:session_id]
+        params[:session_id] = opts[:session_id]
+      end
+
+      # Window dimensions
+      params[:window_height] = opts[:window_height].to_i if opts[:window_height]
+      params[:window_width] = opts[:window_width].to_i if opts[:window_width]
+
+      # Proxy country (auto-enables premium_proxy)
+      if opts[:proxy_country]
+        params[:proxy_country] = opts[:proxy_country].to_s.downcase
+        params[:premium_proxy] = true
+      end
+
+      # JavaScript instructions
+      if opts[:js_instructions]
+        instructions = opts[:js_instructions]
+        instructions = instructions.to_json if instructions.is_a?(Array)
+        params[:js_instructions] = CGI.escape(instructions)
+      end
+
+      # Screenshots
+      params[:screenshot] = true if opts[:screenshot]
+      if opts[:screenshot_fullpage]
+        params[:screenshot] = true
+        params[:screenshot_fullpage] = true
+      end
+      if opts[:screenshot_selector]
+        params[:screenshot] = true
+        params[:screenshot_selector] = opts[:screenshot_selector]
+      end
+
+      # Block resources
+      params[:block_resources] = opts[:block_resources] if opts[:block_resources]
+
+      # Auto-enable js_render if needed
+      params[:js_render] = true if requires_js_render?(params)
+
+      params
+    end
+
+    # Normalize wait time to milliseconds
+    #
+    # @param wait [Boolean, Integer, Object] Wait value
+    # @return [Integer] Wait time in milliseconds
+    def normalize_wait(wait)
+      case wait
+      when true then 15_000
+      when Integer then wait
+      when ->(w) { w.respond_to?(:to_i) && w.respond_to?(:parts) }
+        # ActiveSupport::Duration - convert seconds to ms
+        wait.to_i * 1000
+      else
+        wait.to_i
+      end
+    end
+
+    # Check if JS rendering is required based on params
+    #
+    # @param params [Hash] Current parameters
+    # @return [Boolean] true if js_render should be enabled
+    def requires_js_render?(params)
+      params[:wait] ||
+        params[:wait_for] ||
+        params[:json_response] ||
+        params[:window_height] ||
+        params[:window_width] ||
+        params[:js_instructions] ||
+        params[:screenshot] ||
+        params[:screenshot_fullpage] ||
+        params[:screenshot_selector]
+    end
+  end
+end