zenrows 0.1.0 → 0.2.1

data/lib/zenrows/backends/net_http.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "openssl"
+
+module Zenrows
+  module Backends
+    # Net::HTTP backend adapter (stdlib fallback)
+    #
+    # Uses Ruby's built-in Net::HTTP when http.rb is not available.
+    # Provides basic proxy support with SSL verification disabled.
+    #
+    # @example Basic usage
+    #   backend = Zenrows::Backends::NetHttp.new(proxy: proxy, config: config)
+    #   http = backend.build_client(js_render: true)
+    #   response = http.get(url)
+    #
+    # @author Ernest Bursa
+    # @since 0.2.1
+    # @api public
+    class NetHttp < Base
+      # Build a configured HTTP client wrapper
+      #
+      # @param options [Hash] Request options
+      # @return [NetHttpClient] Configured client wrapper
+      def build_client(options = {})
+        opts = options.dup
+        headers = opts.delete(:headers) || {}
+        opts[:custom_headers] = true if headers.any?
+
+        proxy_config = proxy.build(opts)
+        timeouts = calculate_timeouts(opts)
+
+        NetHttpClient.new(
+          proxy_config: proxy_config,
+          headers: headers,
+          timeouts: timeouts,
+          ssl_context: ssl_context
+        )
+      end
+    end
+
+    # Wrapper around Net::HTTP that mimics http.rb interface
+    #
+    # @api private
+    class NetHttpClient
+      # @param proxy_config [Hash] Proxy configuration
+      # @param headers [Hash] Default headers
+      # @param timeouts [Hash] Timeout configuration
+      # @param ssl_context [OpenSSL::SSL::SSLContext] SSL context
+      def initialize(proxy_config:, headers:, timeouts:, ssl_context:)
+        @proxy_config = proxy_config
+        @headers = headers
+        @timeouts = timeouts
+        @ssl_context = ssl_context
+      end
+
+      # Make GET request
+      #
+      # @param url [String] Target URL
+      # @param options [Hash] Request options
+      # @return [NetHttpResponse] Response wrapper
+      def get(url, **options)
+        uri = URI.parse(url)
+        request(uri, Net::HTTP::Get.new(uri), options)
+      end
+
+      # Make POST request
+      #
+      # @param url [String] Target URL
+      # @param body [String, nil] Request body
+      # @param options [Hash] Request options
+      # @return [NetHttpResponse] Response wrapper
+      def post(url, body: nil, **options)
+        uri = URI.parse(url)
+        req = Net::HTTP::Post.new(uri)
+        req.body = body if body
+        request(uri, req, options)
+      end
+
+      private
+
+      def request(uri, req, options)
+        @headers.each { |k, v| req[k] = v }
+
+        http = Net::HTTP.new(
+          uri.host,
+          uri.port,
+          @proxy_config[:host],
+          @proxy_config[:port],
+          @proxy_config[:username],
+          @proxy_config[:password]
+        )
+
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @timeouts[:connect]
+        http.read_timeout = @timeouts[:read]
+
+        # Apply SSL context
+        ctx = options[:ssl_context] || @ssl_context
+        http.verify_mode = ctx.verify_mode if ctx
+
+        response = http.request(req)
+        NetHttpResponse.new(response)
+      end
+    end
+
+    # Response wrapper that mimics http.rb response interface
+    #
+    # @api private
+    class NetHttpResponse
+      # @return [Net::HTTPResponse] Raw response
+      attr_reader :raw
+
+      def initialize(response)
+        @raw = response
+      end
+
+      # @return [String] Response body
+      def body
+        @raw.body
+      end
+
+      # @return [Integer] HTTP status code
+      def status
+        @raw.code.to_i
+      end
+
+      # @return [Hash] Response headers
+      def headers
+        @raw.to_hash.transform_values(&:first)
+      end
+
+      # Alias for body (http.rb compatibility)
+      def to_s
+        body
+      end
+    end
+  end
+end

data/lib/zenrows/client.rb

@@ -13,7 +13,7 @@ module Zenrows
   #
   #   client = Zenrows::Client.new
   #   http = client.http(js_render: true)
-  #   response = http.get('https://example.com', ssl_context: client.ssl_context)
+  #   response = http.get('https://example.com')
   #
   # @example With custom configuration
   #   client = Zenrows::Client.new(api_key: 'KEY', host: 'proxy.zenrows.com')
@@ -74,11 +74,11 @@ module Zenrows
     #
     # @example Basic request
     #   http = client.http(js_render: true)
-    #   response = http.get(url, ssl_context: client.ssl_context)
+    #   response = http.get(url)
     #
     # @example With premium proxy and country
     #   http = client.http(premium_proxy: true, proxy_country: 'us')
-    #   response = http.get(url, ssl_context: client.ssl_context)
+    #   response = http.get(url)
     def http(options = {})
       backend.build_client(options)
     end
@@ -86,12 +86,10 @@ module Zenrows
     # Get SSL context for proxy connections
     #
     # ZenRows proxy requires SSL verification to be disabled.
+    # This is automatically applied when using #http, but exposed
+    # for advanced use cases.
     #
     # @return [OpenSSL::SSL::SSLContext] SSL context
-    #
-    # @example
-    #   http = client.http(js_render: true)
-    #   response = http.get(url, ssl_context: client.ssl_context)
     def ssl_context
       backend.ssl_context
     end
@@ -148,12 +146,40 @@ module Zenrows
     # @return [Backends::Base] Backend instance
     # @raise [ConfigurationError] if backend is not supported
     def build_backend
-      case config.backend
+      backend_name = resolve_backend
+      case backend_name
       when :http_rb
         Backends::HttpRb.new(proxy: proxy, config: config)
+      when :net_http
+        Backends::NetHttp.new(proxy: proxy, config: config)
       else
-        raise ConfigurationError, "Unsupported backend: #{config.backend}. Use :http_rb"
+        raise ConfigurationError, "Unsupported backend: #{backend_name}. Use :http_rb or :net_http"
+      end
+    end
+
+    # Resolve which backend to use
+    #
+    # @return [Symbol] Backend name
+    def resolve_backend
+      return config.backend if config.backend == :net_http
+
+      # Try http_rb first (preferred), fallback to net_http
+      if config.backend == :http_rb
+        return :http_rb if http_rb_available?
+        return :net_http
       end
+
+      config.backend
+    end
+
+    # Check if http.rb gem is available
+    #
+    # @return [Boolean]
+    def http_rb_available?
+      require "http"
+      true
+    rescue LoadError
+      false
     end
   end
 end

data/lib/zenrows/configuration.rb

@@ -42,10 +42,14 @@ module Zenrows
     # @return [Logger, nil] Logger instance for debug output
     attr_accessor :logger
 
+    # @return [String] ZenRows API endpoint for ApiClient
+    attr_accessor :api_endpoint
+
     # Default configuration values
     DEFAULTS = {
       host: "superproxy.zenrows.com",
       port: 1337,
+      api_endpoint: "https://api.zenrows.com/v1/",
       connect_timeout: 5,
       read_timeout: 180,
       backend: :http_rb
@@ -64,6 +68,7 @@ module Zenrows
         @api_key = nil
         @host = DEFAULTS[:host]
         @port = DEFAULTS[:port]
+        @api_endpoint = DEFAULTS[:api_endpoint]
         @connect_timeout = DEFAULTS[:connect_timeout]
         @read_timeout = DEFAULTS[:read_timeout]
         @backend = DEFAULTS[:backend]
@@ -99,6 +104,7 @@ module Zenrows
         api_key: api_key,
         host: host,
         port: port,
+        api_endpoint: api_endpoint,
         connect_timeout: connect_timeout,
         read_timeout: read_timeout,
         backend: backend

data/lib/zenrows/css_extractor.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Zenrows
+  # DSL for building CSS extraction rules
+  #
+  # Provides a clean interface for defining CSS selectors to extract
+  # data from web pages using the ZenRows API.
+  #
+  # @example Basic extraction
+  #   extractor = Zenrows::CssExtractor.build do
+  #     extract :title, 'h1'
+  #     extract :description, 'meta[name="description"]', attribute: 'content'
+  #   end
+  #
+  # @example With attribute extraction
+  #   extractor = Zenrows::CssExtractor.build do
+  #     extract :links, 'a.product-link', attribute: 'href'
+  #     extract :images, 'img.product-image', attribute: 'src'
+  #   end
+  #
+  # @example Using with ApiClient
+  #   api = Zenrows::ApiClient.new
+  #   response = api.get(url, css_extractor: extractor)
+  #   response.extracted  # => { "title" => "...", "links" => [...] }
+  #
+  # @author Ernest Bursa
+  # @since 0.2.0
+  # @api public
+  class CssExtractor
+    # @return [Hash{Symbol => String}] Extraction rules
+    attr_reader :rules
+
+    # Build extractor using DSL block
+    #
+    # @yield [extractor] Block for defining extraction rules
+    # @return [CssExtractor] Configured extractor
+    def self.build(&block)
+      new.tap { |e| e.instance_eval(&block) }
+    end
+
+    # Initialize empty extractor
+    def initialize
+      @rules = {}
+    end
+
+    # Define extraction rule
+    #
+    # @param name [Symbol, String] Key for extracted data
+    # @param selector [String] CSS selector
+    # @param attribute [String, nil] Attribute to extract (nil for text content)
+    # @return [self] For chaining
+    #
+    # @example Extract text content
+    #   extract :title, 'h1'
+    #
+    # @example Extract attribute
+    #   extract :link, 'a.main', attribute: 'href'
+    def extract(name, selector, attribute: nil)
+      @rules[name.to_sym] = attribute ? "#{selector} @#{attribute}" : selector
+      self
+    end
+
+    # Add rule for extracting href attributes
+    #
+    # @param name [Symbol, String] Key for extracted data
+    # @param selector [String] CSS selector for anchor elements
+    # @return [self] For chaining
+    def links(name, selector)
+      extract(name, selector, attribute: "href")
+    end
+
+    # Add rule for extracting src attributes
+    #
+    # @param name [Symbol, String] Key for extracted data
+    # @param selector [String] CSS selector for elements with src
+    # @return [self] For chaining
+    def images(name, selector)
+      extract(name, selector, attribute: "src")
+    end
+
+    # Convert to hash
+    #
+    # @return [Hash{Symbol => String}] Rules hash
+    def to_h
+      @rules
+    end
+
+    # Convert to JSON string for API
+    #
+    # @return [String] JSON representation
+    def to_json(*)
+      @rules.transform_keys(&:to_s).to_json
+    end
+
+    # Check if extractor has rules
+    #
+    # @return [Boolean]
+    def empty?
+      @rules.empty?
+    end
+
+    # Number of extraction rules
+    #
+    # @return [Integer]
+    def size
+      @rules.size
+    end
+  end
+end

data/lib/zenrows/proxy.rb

@@ -79,8 +79,12 @@ module Zenrows
     # @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)
+    # @option options [String] :device Device emulation ('mobile' or 'desktop')
+    # @option options [Boolean] :antibot Enhanced antibot bypass mode
+    # @option options [String] :session_ttl Session duration ('30s', '5m', '30m', '1h', '1d')
     # @return [Hash] Proxy configuration with :host, :port, :username, :password
     # @raise [WaitTimeError] if wait time exceeds 3 minutes
+    # @raise [ArgumentError] if session_ttl is invalid
     def build(options = {})
       opts = options.dup
       proxy_params = build_params(opts)
@@ -185,6 +189,21 @@ module Zenrows
       # Block resources
       params[:block_resources] = opts[:block_resources] if opts[:block_resources]
 
+      # Device emulation
+      params[:device] = opts[:device].to_s if opts[:device]
+
+      # Antibot bypass
+      params[:antibot] = true if opts[:antibot]
+
+      # Session TTL (duration)
+      if opts[:session_ttl]
+        ttl = opts[:session_ttl].to_s
+        unless VALID_STICKY_TTL.include?(ttl)
+          raise ArgumentError, "Invalid session_ttl: #{ttl}. Valid values: #{VALID_STICKY_TTL.join(", ")}"
+        end
+        params[:session_ttl] = ttl
+      end
+
       # Auto-enable js_render if needed
       params[:js_render] = true if requires_js_render?(params)
 

data/lib/zenrows/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zenrows
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/zenrows.rb

@@ -6,8 +6,16 @@ require_relative "zenrows/configuration"
 require_relative "zenrows/proxy"
 require_relative "zenrows/js_instructions"
 require_relative "zenrows/backends/base"
-require_relative "zenrows/backends/http_rb"
+require_relative "zenrows/backends/net_http"
+begin
+  require_relative "zenrows/backends/http_rb"
+rescue LoadError
+  # http.rb not available, will use net_http fallback
+end
 require_relative "zenrows/client"
+require_relative "zenrows/css_extractor"
+require_relative "zenrows/api_response"
+require_relative "zenrows/api_client"
 
 # ZenRows Ruby client for web scraping proxy
 #
@@ -18,7 +26,7 @@ require_relative "zenrows/client"
 #
 #   client = Zenrows::Client.new
 #   http = client.http(js_render: true, premium_proxy: true)
-#   response = http.get('https://example.com', ssl_context: client.ssl_context)
+#   response = http.get('https://example.com')
 #
 # @example With JavaScript instructions
 #   instructions = Zenrows::JsInstructions.build do

data/sig/manifest.yaml

@@ -0,0 +1,5 @@
+dependencies:
+  - name: logger
+  - name: openssl
+  - name: monitor
+  - name: json

data/sig/zenrows/api_client.rbs

@@ -0,0 +1,15 @@
+class Zenrows::ApiClient
+  attr_reader api_key: String
+  attr_reader api_endpoint: String
+  attr_reader config: Zenrows::Configuration
+
+  def initialize: (?api_key: String?, ?api_endpoint: String?) -> void
+  def get: (String url, **untyped options) -> Zenrows::ApiResponse
+  def post: (String url, ?body: String?, **untyped options) -> Zenrows::ApiResponse
+
+  private
+
+  def build_http_client: () -> untyped
+  def build_params: (String url, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+  def handle_response: (untyped http_response, Hash[Symbol, untyped] options) -> Zenrows::ApiResponse
+end

data/sig/zenrows/api_response.rbs

@@ -0,0 +1,28 @@
+class Zenrows::ApiResponse
+  attr_reader raw: untyped
+  attr_reader status: Integer
+  attr_reader options: Hash[Symbol, untyped]
+
+  def initialize: (untyped http_response, ?Hash[Symbol, untyped] options) -> void
+  def body: () -> String
+  def data: () -> untyped
+  def html: () -> String
+  def markdown: () -> String
+  def parsed: () -> untyped
+  def extracted: () -> untyped
+  def xhr: () -> Array[untyped]?
+  def js_instructions_report: () -> Hash[String, untyped]?
+  def screenshot: () -> String?
+  def headers: () -> Hash[String, String]
+  def concurrency_limit: () -> Integer?
+  def concurrency_remaining: () -> Integer?
+  def request_cost: () -> Float?
+  def final_url: () -> String?
+  def success?: () -> bool
+
+  private
+
+  def json_response?: () -> bool
+  def parse_body: () -> untyped
+  def looks_like_json?: () -> bool
+end

data/sig/zenrows/backends/base.rbs

@@ -0,0 +1,9 @@
+class Zenrows::Backends::Base
+  attr_reader proxy: Zenrows::Proxy
+  attr_reader config: Zenrows::Configuration
+
+  def initialize: (proxy: Zenrows::Proxy, config: Zenrows::Configuration) -> void
+  def build_client: (?Hash[Symbol, untyped] options) -> untyped
+  def ssl_context: () -> OpenSSL::SSL::SSLContext
+  def calculate_timeouts: (?Hash[Symbol, untyped] options) -> Hash[Symbol, Integer]
+end

data/sig/zenrows/backends/http_rb.rbs

@@ -0,0 +1,3 @@
+class Zenrows::Backends::HttpRb < Zenrows::Backends::Base
+  def build_client: (?Hash[Symbol, untyped] options) -> untyped
+end

data/sig/zenrows/backends/net_http.rbs

@@ -0,0 +1,28 @@
+class Zenrows::Backends::NetHttp < Zenrows::Backends::Base
+  def build_client: (?Hash[Symbol, untyped] options) -> Zenrows::Backends::NetHttpClient
+end
+
+class Zenrows::Backends::NetHttpClient
+  @proxy_config: Hash[Symbol, untyped]
+  @headers: Hash[String, String]
+  @timeouts: Hash[Symbol, Integer]
+  @ssl_context: OpenSSL::SSL::SSLContext
+
+  def initialize: (proxy_config: Hash[Symbol, untyped], headers: Hash[String, String], timeouts: Hash[Symbol, Integer], ssl_context: OpenSSL::SSL::SSLContext) -> void
+  def get: (String url, **untyped options) -> Zenrows::Backends::NetHttpResponse
+  def post: (String url, ?body: String?, **untyped options) -> Zenrows::Backends::NetHttpResponse
+
+  private
+
+  def request: (untyped uri, untyped req, Hash[Symbol, untyped] options) -> Zenrows::Backends::NetHttpResponse
+end
+
+class Zenrows::Backends::NetHttpResponse
+  attr_reader raw: untyped
+
+  def initialize: (untyped response) -> void
+  def body: () -> String?
+  def status: () -> Integer
+  def headers: () -> Hash[String, String]
+  def to_s: () -> String?
+end

data/sig/zenrows/backends.rbs

@@ -0,0 +1,2 @@
+module Zenrows::Backends
+end

data/sig/zenrows/client.rbs

@@ -0,0 +1,11 @@
+class Zenrows::Client
+  attr_reader config: Zenrows::Configuration
+  attr_reader proxy: Zenrows::Proxy
+  attr_reader backend: Zenrows::Backends::Base
+
+  def initialize: (?api_key: String?, ?host: String?, ?port: Integer?, ?backend: Symbol?) -> void
+  def http: (?Hash[Symbol, untyped] options) -> untyped
+  def ssl_context: () -> OpenSSL::SSL::SSLContext
+  def proxy_config: (?Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+  def proxy_url: (?Hash[Symbol, untyped] options) -> String
+end

data/sig/zenrows/configuration.rbs

@@ -0,0 +1,20 @@
+class Zenrows::Configuration
+  include MonitorMixin
+
+  DEFAULTS: Hash[Symbol, untyped]
+
+  attr_accessor api_key: String?
+  attr_accessor host: String
+  attr_accessor port: Integer
+  attr_accessor api_endpoint: String
+  attr_accessor connect_timeout: Integer
+  attr_accessor read_timeout: Integer
+  attr_accessor backend: Symbol
+  attr_accessor logger: Logger?
+
+  def initialize: () -> void
+  def reset!: () -> void
+  def validate!: () -> true
+  def valid?: () -> bool
+  def to_h: () -> Hash[Symbol, untyped]
+end

data/sig/zenrows/css_extractor.rbs

@@ -0,0 +1,14 @@
+class Zenrows::CssExtractor
+  attr_reader rules: Hash[Symbol, String]
+
+  def self.build: () { (Zenrows::CssExtractor) -> void } -> Zenrows::CssExtractor
+
+  def initialize: () -> void
+  def extract: (Symbol | String name, String selector, ?attribute: String?) -> self
+  def links: (Symbol | String name, String selector) -> self
+  def images: (Symbol | String name, String selector) -> self
+  def to_h: () -> Hash[Symbol, String]
+  def to_json: (*untyped) -> String
+  def empty?: () -> bool
+  def size: () -> Integer
+end

data/sig/zenrows/errors.rbs

@@ -0,0 +1,27 @@
+class Zenrows::Error < StandardError
+end
+
+class Zenrows::ConfigurationError < Zenrows::Error
+end
+
+class Zenrows::AuthenticationError < Zenrows::Error
+end
+
+class Zenrows::RateLimitError < Zenrows::Error
+  attr_reader retry_after: Integer?
+  def initialize: (?String message, ?retry_after: Integer?) -> void
+end
+
+class Zenrows::BotDetectedError < Zenrows::Error
+  attr_reader suggestion: String?
+  def initialize: (?String message, ?suggestion: String?) -> void
+end
+
+class Zenrows::TimeoutError < Zenrows::Error
+end
+
+class Zenrows::ProxyError < Zenrows::Error
+end
+
+class Zenrows::WaitTimeError < Zenrows::Error
+end

data/sig/zenrows/js_instructions.rbs

@@ -0,0 +1,28 @@
+class Zenrows::JsInstructions
+  attr_reader instructions: Array[Hash[Symbol, untyped]]
+
+  def initialize: () -> void
+  def self.build: () { (Zenrows::JsInstructions) -> void } -> Zenrows::JsInstructions
+
+  def click: (String selector) -> self
+  def wait: (Integer duration) -> self
+  def wait_for: (String selector) -> self
+  def wait_event: (String | Symbol event) -> self
+  def fill: (String selector, String value) -> self
+  def check: (String selector) -> self
+  def uncheck: (String selector) -> self
+  def select_option: (String selector, String value) -> self
+  def scroll_y: (Integer pixels) -> self
+  def scroll_x: (Integer pixels) -> self
+  def scroll_to: (String | Symbol position) -> self
+  def evaluate: (String code) -> self
+  def frame_click: (String iframe_selector, String element_selector) -> self
+  def frame_wait_for: (String iframe_selector, String element_selector) -> self
+  def frame_fill: (String iframe_selector, String input_selector, String value) -> self
+  def frame_evaluate: (String iframe_name, String code) -> self
+
+  def to_json: (*untyped) -> String
+  def to_a: () -> Array[Hash[Symbol, untyped]]
+  def empty?: () -> bool
+  def size: () -> Integer
+end

data/sig/zenrows/proxy.rbs

@@ -0,0 +1,14 @@
+class Zenrows::Proxy
+  MAX_WAIT_MS: Integer
+  VALID_STICKY_TTL: Array[String]
+  VALID_REGIONS: Hash[String, String]
+
+  attr_reader api_key: String
+  attr_reader host: String
+  attr_reader port: Integer
+
+  def initialize: (api_key: String, host: String, port: Integer) -> void
+  def build: (?Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+  def build_url: (?Hash[Symbol, untyped] options) -> String
+  def build_array: (?Hash[Symbol, untyped] options) -> [String, Integer, String, String]
+end

data/sig/zenrows.rbs

@@ -1,4 +1,7 @@
 module Zenrows
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> Configuration
+  def self.reset_configuration!: () -> void
 end