isoautomate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73ae7755ecf1b7f8ecb33fd0bfee1bbb66dbf3140716e3391c67fa33f5a96c00
+  data.tar.gz: d7a51abd998faf6c248a204feb8a3f8b43677a3bc836d1057478b36972e8abd7
+SHA512:
+  metadata.gz: ac945e07957d11158ea4a3e5b4f8c69d6dcaf5b81baca0a3dd3dccba4ded90067e79834928f1ddb043889fe04902054434619b50defe894732f03427cfe661ec
+  data.tar.gz: e9a01ab37c8143c8e62b240de1e1d4c76e7821bef63046d10b07fcc0ba2a71db74009e2538812fe6c1b139aaadb5620812b48b23b631e088d68d387adb1d6b1d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 isoAutomate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+<div align="center">
+  <h1 align="center">isoAutomate Ruby SDK</h1>
+  <p align="center">
+    <b>Enterprise-Grade Browser Orchestration for Ruby</b>
+  </p>
+
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
+  </a>
+  <a href="https://isoautomate.com/docs">
+    <img src="https://img.shields.io/badge/Docs-isoautomate.com-blue.svg" alt="Documentation">
+  </a>
+</div>
+
+---
+
+## Introduction
+
+The **isoAutomate Ruby SDK** provides a high-level, idiomatic Ruby client for controlling remote browsers via **isoFleet**. It brings the full power of 120+ SeleniumBase-style actions to the Ruby ecosystem, optimized for high-performance automation.
+
+- **Idiomatic Ruby**: Pure Ruby implementation using modern syntax.
+- **Stealth First**: Native support for OS-level GUI interactions and bot-bypass.
+- **120+ Actions**: Complete parity with Python, Go, and Java SDKs.
+- **Automated Assertions**: Failure screenshots are automatically captured and saved locally.
+
+---
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'isoautomate'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Or install it directly via:
+```bash
+$ gem install isoautomate
+```
+
+## Configuration
+The SDK automatically detects configuration from your environment or a .env file:
+```ini
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=your_password
+REDIS_DB=0
+```
+
+## Usage Example
+```Ruby
+require 'isoautomate'
+
+# The client uses Redis to communicate with your browser workers
+client = IsoAutomate::Client.new
+
+begin
+  # 1. Acquire a browser session
+  client.acquire("chrome", record: true)
+
+  # 2. Perform actions
+  client.open_url("[https://example.com](https://example.com)")
+  client.type("#search", "isoAutomate")
+  client.click(".submit-btn")
+
+  # 3. Use built-in assertions (saves screenshot on failure)
+  client.assert_text("Results", "h1")
+
+  puts "Session Video: #{client.video_url}"
+ensure
+  # Always release the browser back to the pool
+  client.release
+end
+```
+
+## Core Capabilities
+**MFA Handling**
+Generate and enter TOTP codes instantly.
+```Ruby
+code = client.get_mfa_code("YOUR_SECRET_KEY")
+client.type("#otp-input", code)
+```
+
+**Stealth & OS-Level Control**
+Bypass detection using real OS-level events.
+```Ruby
+client.gui_click_element("#captcha-checkbox")
+client.gui_write("Typing like a human...")
+```
+
+**Session Persistance**
+Maintain logins by saving and loading cookie states.
+```Ruby
+client.save_cookies("session.json")
+client.load_cookies("session.json")
+```
+## License
+MIT License - Copyright (c) 2026 isoAutomate

data/isoautomate.gemspec

@@ -0,0 +1,31 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "isoautomate/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "isoautomate"
+  spec.version       = Isoautomate::VERSION
+  spec.authors       = ["isoAutomate Team"]
+  spec.email         = ["support@isoautomate.com"]
+
+  spec.summary       = "Official Ruby SDK for the isoAutomate Sovereign Browser Infrastructure."
+  spec.description   = "Provides connectivity to the isoFleet engine via Redis for distributed browser automation."
+  spec.homepage      = "https://github.com/isoautomate/isoautomate-ruby"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by mistake - remove if you intend to publish publicly
+  # spec.metadata["allowed_push_host"] = "TODO: Set to 'https://rubygems.org'"
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "redis", ">= 4.0"
+  spec.add_dependency "dotenv", ">= 2.7"
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/isoautomate/client.rb

@@ -0,0 +1,911 @@
+require 'redis'
+require 'json'
+require 'securerandom'
+require 'base64'
+require 'logger'
+require 'fileutils'
+require 'dotenv'
+
+require 'isoautomate/config'
+require 'isoautomate/exceptions'
+require 'isoautomate/utils'
+
+module Isoautomate
+  class Client
+    # ----------------------------------------------------------------
+    # SETUP & CONFIGURATION
+    # ----------------------------------------------------------------
+    attr_reader :session, :video_url, :record_url
+
+    def initialize(redis_url: nil, redis_host: nil, redis_port: nil, redis_password: nil, redis_db: nil, redis_ssl: false, env_file: nil)
+      # Load Env
+      if env_file && File.exist?(env_file)
+        Dotenv.load(env_file)
+      else
+        Dotenv.load
+      end
+
+      # Logger
+      @logger = Logger.new(STDOUT)
+      @logger.level = Logger::INFO
+      @logger.formatter = proc do |severity, datetime, progname, msg|
+        "[#{severity}] #{msg}\n"
+      end
+
+      # Redis Config
+      env_url = ENV["REDIS_URL"]
+      env_host = ENV["REDIS_HOST"]
+      env_port = ENV["REDIS_PORT"]
+      env_pass = ENV["REDIS_PASSWORD"]
+      env_db   = ENV["REDIS_DB"]
+      env_ssl  = ENV["REDIS_SSL"].to_s.downcase == "true"
+
+      @redis_url = redis_url || env_url
+      @host = redis_host || env_host
+      @port = redis_port || env_port
+      @password = redis_password || env_pass
+      @db = redis_db || (env_db || 0).to_i
+      @ssl = redis_ssl || env_ssl
+
+      if @redis_url.nil? && @host.nil?
+        raise BrowserError, "Missing Redis Configuration."
+      end
+
+      # Connect to Redis
+      begin
+        if @redis_url
+          @r = Redis.new(url: @redis_url)
+        else
+          actual_port = @port ? @port.to_i : 6379
+          @r = Redis.new(
+            host: @host,
+            port: actual_port,
+            password: @password,
+            db: @db,
+            ssl: @ssl
+          )
+        end
+        # Test connection
+        @r.ping
+      rescue StandardError => e
+        raise BrowserError, "Failed to initialize Redis connection: #{e.message}"
+      end
+
+      @session = nil
+      @video_url = nil
+      @record_url = nil
+      @session_data = {}
+      @init_sent = false
+    end
+
+    # --- Redis Wrappers (Using the Utils Module) ---
+    def _r_rpush(key, *values)
+      Isoautomate::Utils.redis_retry { @r.rpush(key, values) }
+    end
+
+    def _r_get(key)
+      Isoautomate::Utils.redis_retry { @r.get(key) }
+    end
+
+    def _r_delete(key)
+      Isoautomate::Utils.redis_retry { @r.del(key) }
+    end
+
+    # --- Lifecycle (Ruby equivalent of Context Manager) ---
+    # Python's __enter__ returns self.
+    # In Ruby, users will likely use: client = Client.new; client.acquire; ... client.release
+    def open
+      # Placeholder if block syntax is added later
+      self
+    end
+
+    def close
+      return unless @session
+      begin
+        @logger.info("[SDK] Auto-releasing session #{@session['browser_id'][0..5]}...")
+        release
+      rescue StandardError => e
+        @logger.error("[SDK] Release failed during cleanup: #{e.message}")
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # ACQUIRE & RELEASE
+    # ----------------------------------------------------------------
+    def acquire(browser_type: "chrome", video: false, profile: nil, record: false)
+      profile_id = nil
+      
+      # Profile Handling
+      if profile == true
+        profile_store = File.join(Dir.pwd, ".iso_profiles")
+        FileUtils.mkdir_p(profile_store)
+        id_file = File.join(profile_store, "default_profile.id")
+        
+        if File.exist?(id_file)
+          profile_id = File.read(id_file).strip
+        else
+          profile_id = "user_#{SecureRandom.hex(4)}"
+          File.write(id_file, profile_id)
+        end
+      elsif profile.is_a?(String)
+        profile_id = profile
+      end
+
+      @init_sent = false
+
+      # Lua Script (Identical to Python)
+      lua_script = <<~LUA
+        local workers = redis.call('SMEMBERS', KEYS[1])
+        for i = #workers, 2, -1 do
+            local j = math.random(i)
+            workers[i], workers[j] = workers[j], workers[i]
+        end
+        
+        for _, worker in ipairs(workers) do
+            local free_key = ARGV[1] .. worker .. ':' .. ARGV[2] .. ':free'
+            local bid = redis.call('SPOP', free_key)
+            if bid then
+                local busy_key = ARGV[1] .. worker .. ':' .. ARGV[2] .. ':busy'
+                redis.call('SADD', busy_key, bid)
+                return {worker, bid}
+            end
+        end
+        return nil
+      LUA
+
+      begin
+        result = @r.eval(lua_script, keys: [Isoautomate::WORKERS_SET], argv: [Isoautomate::REDIS_PREFIX, browser_type])
+      rescue StandardError => e
+        raise BrowserError, "Redis Lua Error: #{e.message}"
+      end
+
+      if result
+        worker_name = result[0]
+        bid = result[1]
+
+        @session = {
+          "browser_id" => bid,
+          "worker" => worker_name,
+          "browser_type" => browser_type,
+          "video" => video,
+          "profile_id" => profile_id,
+          "record" => record
+        }
+
+        if profile_id || video || record
+          @logger.info("[SDK] Initializing persistent environment on #{worker_name}...")
+          _send("get_title")
+        end
+
+        return { "status" => "ok", "browser_id" => bid, "worker" => worker_name }
+      end
+
+      raise BrowserError, "No browsers available for type: '#{browser_type}'. Check workers."
+    end
+
+    def release
+      return { "status" => "error", "error" => "not_acquired" } unless @session
+
+      begin
+        if @session["video"]
+          @logger.info("[SDK] Stopping video...")
+          res = _send("stop_video", {}, timeout: 120)
+          if res["video_url"]
+            @video_url = res["video_url"]
+            @logger.info("[SDK] Session Video: #{@video_url}")
+          end
+        end
+
+        if @session["record"]
+          @logger.info("[SDK] Finalizing session record (RRWeb)...")
+          res_r = _send("stop_record", {}, timeout: 60)
+          if res_r["record_url"]
+            @record_url = res_r["record_url"]
+            @logger.info("[SDK] Session Record URL: #{@record_url}")
+          end
+        end
+
+        @logger.info("[SDK] Sending release command...")
+        res = _send("release_browser")
+        @session_data = res
+        return res
+      rescue StandardError => e
+        @logger.error("[SDK ERROR] Error inside release: #{e.message}")
+        return { "status" => "error", "error" => e.message }
+      ensure
+        @session = nil
+      end
+    end
+
+    def _send(action, args = {}, timeout: 60)
+      raise BrowserError, "Cannot perform action '#{action}': Browser session not acquired." unless @session
+
+      task_id = SecureRandom.hex
+      result_key = "#{Isoautomate::REDIS_PREFIX}result:#{task_id}"
+      queue = "#{Isoautomate::REDIS_PREFIX}#{@session['worker']}:tasks"
+
+      payload = {
+        "task_id" => task_id,
+        "browser_id" => @session["browser_id"],
+        "worker_name" => @session["worker"],
+        "action" => action,
+        "args" => args,
+        "result_key" => result_key
+      }
+
+      unless @init_sent
+        payload["video"] = true if @session["video"]
+        payload["record"] = true if @session["record"]
+        if @session["profile_id"]
+          payload["profile_id"] = @session["profile_id"]
+          payload["browser_type"] = @session["browser_type"]
+        end
+      end
+
+      _r_rpush(queue, payload.to_json)
+
+      begin
+        # Blocking Pop (Instant RPC)
+        # Redis gem blpop returns [key, value] or nil
+        resp = @r.blpop(result_key, timeout: timeout)
+        if resp
+          @init_sent = true
+          return JSON.parse(resp[1])
+        else
+          return { "status" => "error", "error" => "Timeout waiting for worker" }
+        end
+      rescue StandardError => e
+        return { "status" => "error", "error" => "Redis RPC Error: #{e.message}" }
+      end
+    end
+
+    # --- Assertions Handler ---
+    def _handle_assertion(action, args)
+      args[:screenshot] = true unless args.key?(:screenshot)
+      res = _send(action, args)
+
+      if res["status"] == "fail"
+        if res["screenshot_base64"]
+          begin
+            FileUtils.mkdir_p(Isoautomate::ASSERTION_FOLDER)
+            selector_clean = args.fetch(:selector, "unknown").gsub(/[#.\s]/, "_")[0..19]
+            timestamp = Time.now.strftime("%H%M%S")
+            filename = "FAIL_#{action}_#{selector_clean}_#{timestamp}.png"
+            path = File.join(Isoautomate::ASSERTION_FOLDER, filename)
+            
+            File.open(path, "wb") do |f|
+              f.write(Base64.decode64(res["screenshot_base64"]))
+            end
+            @logger.warn("[Assertion Fail] Screenshot saved: #{path}")
+          rescue StandardError
+            # ignore save errors
+          end
+        end
+        error_msg = res.fetch("error", "Unknown assertion error")
+        raise error_msg # Raising RuntimeError like AssertionError
+      end
+      true
+    end
+
+    # --- Helper: Save Base64 File ---
+    def _save_base64_file(res, key_name, output_path)
+      if res["status"] == "ok" && res.key?(key_name)
+        begin
+          dirname = File.dirname(output_path)
+          FileUtils.mkdir_p(dirname) unless dirname == "."
+          File.open(output_path, "wb") do |f|
+            f.write(Base64.decode64(res[key_name]))
+          end
+          return { "status" => "ok", "path" => File.expand_path(output_path) }
+        rescue StandardError => e
+          return { "status" => "error", "error" => "Failed to save local file: #{e.message}" }
+        end
+      end
+      res
+    end
+
+    # ==================================================
+    # 1. NAVIGATION & LIFECYCLE
+    # ==================================================
+    def open_url(url)
+      _send("open_url", { "url" => url })
+    end
+
+    def reload(ignore_cache: true, script: nil)
+      _send("reload", { "ignore_cache" => ignore_cache, "script_to_evaluate_on_load" => script })
+    end
+
+    def refresh
+      _send("refresh")
+    end
+
+    def go_back
+      _send("go_back")
+    end
+
+    def go_forward
+      _send("go_forward")
+    end
+
+    def internalize_links
+      _send("internalize_links")
+    end
+
+    def get_navigation_history
+      _send("get_navigation_history")
+    end
+
+    # ==================================================
+    # 2. MOUSE INTERACTION
+    # ==================================================
+    def click(selector, timeout: nil)
+      _send("click", { "selector" => selector, "timeout" => timeout })
+    end
+
+    def click_if_visible(selector)
+      _send("click_if_visible", { "selector" => selector })
+    end
+
+    def click_visible_elements(selector, limit: 0)
+      _send("click_visible_elements", { "selector" => selector, "limit" => limit })
+    end
+
+    def click_nth_element(selector, number: 1)
+      _send("click_nth_element", { "selector" => selector, "number" => number })
+    end
+
+    def click_nth_visible_element(selector, number: 1)
+      _send("click_nth_visible_element", { "selector" => selector, "number" => number })
+    end
+
+    def click_link(text)
+      _send("click_link", { "text" => text })
+    end
+
+    def click_active_element
+      _send("click_active_element")
+    end
+
+    def mouse_click(selector)
+      _send("mouse_click", { "selector" => selector })
+    end
+
+    def nested_click(parent_selector, selector)
+      _send("nested_click", { "parent_selector" => parent_selector, "selector" => selector })
+    end
+
+    def click_with_offset(selector, x, y, center: false)
+      _send("click_with_offset", { "selector" => selector, "x" => x, "y" => y, "center" => center })
+    end
+
+    # ==================================================
+    # 3. KEYBOARD & INPUT
+    # ==================================================
+    def type(selector, text, timeout: nil)
+      _send("type", { "selector" => selector, "text" => text, "timeout" => timeout })
+    end
+
+    def press_keys(selector, text)
+      _send("press_keys", { "selector" => selector, "text" => text })
+    end
+
+    def send_keys(selector, text)
+      _send("send_keys", { "selector" => selector, "text" => text })
+    end
+
+    def set_value(selector, text)
+      _send("set_value", { "selector" => selector, "text" => text })
+    end
+
+    def clear(selector)
+      _send("clear", { "selector" => selector })
+    end
+
+    def clear_input(selector)
+      _send("clear_input", { "selector" => selector })
+    end
+
+    def submit(selector)
+      _send("submit", { "selector" => selector })
+    end
+
+    def focus(selector)
+      _send("focus", { "selector" => selector })
+    end
+
+    # ==================================================
+    # 4. GUI ACTIONS (PyAutoGUI / Profiled)
+    # ==================================================
+    def gui_click_element(selector, timeframe: 0.25)
+      _send("gui_click_element", { "selector" => selector, "timeframe" => timeframe })
+    end
+
+    def gui_click_x_y(x, y, timeframe: 0.25)
+      _send("gui_click_x_y", { "x" => x, "y" => y, "timeframe" => timeframe })
+    end
+
+    def gui_click_captcha
+      _send("gui_click_captcha")
+    end
+
+    def solve_captcha
+      _send("solve_captcha")
+    end
+
+    def gui_drag_and_drop(drag_selector, drop_selector, timeframe: 0.35)
+      _send("gui_drag_and_drop", { "drag_selector" => drag_selector, "drop_selector" => drop_selector, "timeframe" => timeframe })
+    end
+
+    def gui_hover_element(selector)
+      _send("gui_hover_element", { "selector" => selector })
+    end
+
+    def gui_write(text)
+      _send("gui_write", { "text" => text })
+    end
+
+    def gui_press_keys(keys_list)
+      _send("gui_press_keys", { "keys" => keys_list })
+    end
+
+    # ==================================================
+    # 5. SELECTS & DROPDOWNS
+    # ==================================================
+    def select_option_by_text(selector, text)
+      _send("select_option_by_text", { "selector" => selector, "text" => text })
+    end
+
+    def select_option_by_value(selector, value)
+      _send("select_option_by_value", { "selector" => selector, "value" => value })
+    end
+
+    def select_option_by_index(selector, index)
+      _send("select_option_by_index", { "selector" => selector, "index" => index })
+    end
+
+    # ==================================================
+    # 6. WINDOW & TAB MANAGEMENT
+    # ==================================================
+    def open_new_tab(url)
+      _send("open_new_tab", { "url" => url })
+    end
+
+    def open_new_window(url)
+      _send("open_new_window", { "url" => url })
+    end
+
+    def switch_to_tab(index: -1)
+      _send("switch_to_tab", { "index" => index })
+    end
+
+    def switch_to_window(index: -1)
+      _send("switch_to_window", { "index" => index })
+    end
+
+    def close_active_tab
+      _send("close_active_tab")
+    end
+
+    def maximize
+      _send("maximize")
+    end
+
+    def minimize
+      _send("minimize")
+    end
+
+    def medimize
+      _send("medimize")
+    end
+
+    def tile_windows
+      _send("tile_windows")
+    end
+
+    # ==================================================
+    # 7. DATA EXTRACTION (GETTERS)
+    # ==================================================
+    def get_text(selector: "body")
+      _send("get_text", { "selector" => selector })
+    end
+
+    def get_title
+      _send("get_title")
+    end
+
+    def get_current_url
+      _send("get_current_url")
+    end
+
+    def get_page_source
+      _send("get_page_source")
+    end
+
+    def get_html(selector: nil)
+      _send("get_html", { "selector" => selector })
+    end
+
+    def get_attribute(selector, attribute)
+      _send("get_attribute", { "selector" => selector, "attribute" => attribute })
+    end
+
+    def get_element_attributes(selector)
+      _send("get_element_attributes", { "selector" => selector })
+    end
+
+    def get_user_agent
+      _send("get_user_agent")
+    end
+
+    def get_cookie_string
+      _send("get_cookie_string")
+    end
+
+    def get_element_rect(selector)
+      _send("get_element_rect", { "selector" => selector })
+    end
+
+    def get_window_rect
+      _send("get_window_rect")
+    end
+
+    def get_screen_rect
+      _send("get_screen_rect")
+    end
+
+    def is_element_visible(selector)
+      _send("is_element_visible", { "selector" => selector })
+    end
+
+    def is_text_visible(text)
+      _send("is_text_visible", { "text" => text })
+    end
+
+    def is_checked(selector)
+      _send("is_checked", { "selector" => selector })
+    end
+
+    def is_selected(selector)
+      _send("is_selected", { "selector" => selector })
+    end
+
+    def is_online
+      _send("is_online")
+    end
+
+    # ==================================================
+    # 8. COOKIES & STORAGE
+    # ==================================================
+    def get_all_cookies
+      _send("get_all_cookies")
+    end
+
+    def add_cookie(cookie_dict)
+      _send("add_cookie", { "cookie" => cookie_dict })
+    end
+
+    def delete_cookie(name)
+      _send("delete_cookie", { "name" => name })
+    end
+
+    def save_cookies(name: "cookies.txt")
+      res = _send("save_cookies")
+      if res["status"] == "ok" && res["cookies"]
+        begin
+          File.open(name, "w") { |f| f.write(JSON.pretty_generate(res["cookies"])) }
+          return { "status" => "ok", "path" => File.expand_path(name) }
+        rescue StandardError => e
+          return { "status" => "error", "error" => "Failed to write local file: #{e.message}" }
+        end
+      end
+      res
+    end
+
+    def load_cookies(name: "cookies.txt", cookies_list: nil)
+      final_cookies = cookies_list
+      if final_cookies.nil? && name
+        begin
+          if File.exist?(name)
+            final_cookies = JSON.parse(File.read(name))
+          else
+            return { "status" => "error", "error" => "Local cookie file not found: #{name}" }
+          end
+        rescue StandardError => e
+          return { "status" => "error", "error" => "Failed to read local file: #{e.message}" }
+        end
+      end
+      _send("load_cookies", { "name" => name, "cookies" => final_cookies })
+    end
+
+    def clear_cookies
+      _send("clear_cookies")
+    end
+
+    def get_local_storage_item(key)
+      _send("get_local_storage_item", { "key" => key })
+    end
+
+    def set_local_storage_item(key, value)
+      _send("set_local_storage_item", { "key" => key, "value" => value })
+    end
+
+    def get_session_storage_item(key)
+      _send("get_session_storage_item", { "key" => key })
+    end
+
+    def set_session_storage_item(key, value)
+      _send("set_session_storage_item", { "key" => key, "value" => value })
+    end
+
+    # ==================================================
+    # 9. VISUALS & HIGHLIGHTS
+    # ==================================================
+    def highlight(selector)
+      _send("highlight", { "selector" => selector })
+    end
+
+    def highlight_overlay(selector)
+      _send("highlight_overlay", { "selector" => selector })
+    end
+
+    def remove_element(selector)
+      _send("remove_element", { "selector" => selector })
+    end
+
+    def flash(selector, duration: 1)
+      _send("flash", { "selector" => selector, "duration" => duration })
+    end
+
+    # ==================================================
+    # 10. ADVANCED (MFA, Permissions, Scripting)
+    # ==================================================
+    def get_mfa_code(totp_key)
+      _send("get_mfa_code", { "totp_key" => totp_key })
+    end
+
+    def enter_mfa_code(selector, totp_key)
+      _send("enter_mfa_code", { "selector" => selector, "totp_key" => totp_key })
+    end
+
+    def grant_permissions(permissions)
+      _send("grant_permissions", { "permissions" => permissions })
+    end
+
+    def execute_script(script)
+      _send("execute_script", { "script" => script })
+    end
+
+    def evaluate(expression)
+      _send("evaluate", { "expression" => expression })
+    end
+
+    # ==================================================
+    # 11. ASSERTIONS
+    # ==================================================
+    def assert_text(text, selector: "html", screenshot: true)
+      _handle_assertion("assert_text", { "text" => text, "selector" => selector, "screenshot" => screenshot })
+    end
+
+    def assert_exact_text(text, selector: "html", screenshot: true)
+      _handle_assertion("assert_exact_text", { "text" => text, "selector" => selector, "screenshot" => screenshot })
+    end
+
+    def assert_element(selector, screenshot: true)
+      _handle_assertion("assert_element", { "selector" => selector, "screenshot" => screenshot })
+    end
+
+    def assert_element_present(selector, screenshot: true)
+      _handle_assertion("assert_element_present", { "selector" => selector, "screenshot" => screenshot })
+    end
+
+    def assert_element_absent(selector, screenshot: true)
+      _handle_assertion("assert_element_absent", { "selector" => selector, "screenshot" => screenshot })
+    end
+
+    def assert_element_not_visible(selector, screenshot: true)
+      _handle_assertion("assert_element_not_visible", { "selector" => selector, "screenshot" => screenshot })
+    end
+
+    def assert_text_not_visible(text, selector: "html", screenshot: true)
+      _handle_assertion("assert_text_not_visible", { "text" => text, "selector" => selector, "screenshot" => screenshot })
+    end
+
+    def assert_title(title, screenshot: true)
+      _handle_assertion("assert_title", { "title" => title, "screenshot" => screenshot })
+    end
+
+    def assert_url(url_substring, screenshot: true)
+      _handle_assertion("assert_url", { "url" => url_substring, "screenshot" => screenshot })
+    end
+
+    def assert_attribute(selector, attribute, value, screenshot: true)
+      _handle_assertion("assert_attribute", { "selector" => selector, "attribute" => attribute, "value" => value, "screenshot" => screenshot })
+    end
+
+    # ==================================================
+    # 12. SCROLLING & WAITING
+    # ==================================================
+    def scroll_into_view(selector)
+      _send("scroll_into_view", { "selector" => selector })
+    end
+
+    def scroll_to_bottom
+      _send("scroll_to_bottom")
+    end
+
+    def scroll_to_top
+      _send("scroll_to_top")
+    end
+
+    def scroll_down(amount: 25)
+      _send("scroll_down", { "amount" => amount })
+    end
+
+    def scroll_up(amount: 25)
+      _send("scroll_up", { "amount" => amount })
+    end
+
+    def scroll_to_y(y)
+      _send("scroll_to_y", { "y" => y })
+    end
+
+    def sleep(seconds)
+      _send("sleep", { "seconds" => seconds })
+    end
+
+    def wait_for_element(selector, timeout: nil)
+      _send("wait_for_element", { "selector" => selector, "timeout" => timeout })
+    end
+
+    def wait_for_text(text, selector: "html", timeout: nil)
+      _send("wait_for_text", { "text" => text, "selector" => selector, "timeout" => timeout })
+    end
+
+    def wait_for_element_present(selector, timeout: nil)
+      _send("wait_for_element_present", { "selector" => selector, "timeout" => timeout })
+    end
+
+    def wait_for_element_absent(selector, timeout: nil)
+      _send("wait_for_element_absent", { "selector" => selector, "timeout" => timeout })
+    end
+
+    def wait_for_element_not_visible(selector, timeout: nil)
+      _send("wait_for_element_not_visible", { "selector" => selector, "timeout" => timeout })
+    end
+
+    # ==================================================
+    # 13. SCREENSHOTS & FILES
+    # ==================================================
+    def screenshot(filename: nil, selector: nil)
+      if filename.nil?
+        timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
+        unique_id = SecureRandom.hex(2)
+        filename = File.join(Isoautomate::SCREENSHOT_FOLDER, "#{timestamp}_#{unique_id}.png")
+      end
+
+      res = _send("save_screenshot", { "name" => "temp.png", "selector" => selector })
+      _save_base64_file(res, "image_base64", filename)
+    end
+
+    def save_as_pdf(filename: nil)
+      filename = "doc_#{Time.now.to_i}.pdf" if filename.nil?
+      res = _send("save_as_pdf")
+      _save_base64_file(res, "pdf_base64", filename)
+    end
+
+    def save_page_source(name: "source.html")
+      res = _send("save_page_source")
+      if res["status"] == "ok" && res["source_base64"]
+        begin
+          data = Base64.decode64(res["source_base64"])
+          File.open(name, "w:UTF-8") { |f| f.write(data) }
+          return { "status" => "ok", "path" => File.expand_path(name) }
+        rescue StandardError => e
+          return { "status" => "error", "error" => e.message }
+        end
+      end
+      res
+    end
+
+    def upload_file(selector, local_file_path)
+      return { "status" => "error", "error" => "Local file not found: #{local_file_path}" } unless File.exist?(local_file_path)
+      
+      file_data = Base64.strict_encode64(File.read(local_file_path))
+      filename = File.basename(local_file_path)
+      _send("upload_file", { "selector" => selector, "file_name" => filename, "file_data" => file_data })
+    end
+
+    # ==================================================
+    # 14. NETWORK CONTROL
+    # ==================================================
+    def block_urls(patterns)
+      _send("block_urls", { "patterns" => patterns })
+    end
+
+    def wait_for_network_idle
+      _send("wait_for_network_idle")
+    end
+
+    def get_performance_metrics
+      _send("get_performance_metrics")
+    end
+
+    # ==================================================
+    # 15. IFRAME SWITCHING
+    # ==================================================
+    def switch_to_frame(selector)
+      _send("switch_to_frame", { "selector" => selector })
+    end
+
+    def switch_to_default_content
+      _send("switch_to_default_content")
+    end
+
+    def switch_to_parent_frame
+      _send("switch_to_parent_frame")
+    end
+
+    # ==================================================
+    # 16. ALERTS & DIALOGS
+    # ==================================================
+    def accept_alert
+      _send("accept_alert")
+    end
+
+    def dismiss_alert
+      _send("dismiss_alert")
+    end
+
+    def get_alert_text
+      _send("get_alert_text")
+    end
+
+    # ==================================================
+    # 17. ADVANCED MOUSE (DOM LEVEL)
+    # ==================================================
+    def double_click(selector)
+      _send("double_click", { "selector" => selector })
+    end
+
+    def right_click(selector)
+      _send("right_click", { "selector" => selector })
+    end
+
+    def hover(selector)
+      _send("hover", { "selector" => selector })
+    end
+
+    def drag_and_drop(drag_selector, drop_selector)
+      _send("drag_and_drop", { "drag_selector" => drag_selector, "drop_selector" => drop_selector })
+    end
+
+    # ==================================================
+    # 18. VIEWPORT SIZE
+    # ==================================================
+    def set_window_size(width, height)
+      _send("set_window_size", { "width" => width, "height" => height })
+    end
+
+    def set_window_rect(x, y, width, height)
+      _send("set_window_rect", { "x" => x, "y" => y, "width" => width, "height" => height })
+    end
+
+    # ==================================================
+    # 19. SESSION STATE (Import/Export)
+    # ==================================================
+    def export_session
+      _send("get_storage_state")
+    end
+
+    def import_session(state_dict)
+      _send("set_storage_state", { "state" => state_dict })
+    end
+
+    # ==================================================
+    # 20. GOD MODE (Raw CDP Access)
+    # ==================================================
+    def execute_cdp_cmd(cmd, params = {})
+      _send("execute_cdp_cmd", { "cmd" => cmd, "params" => params })
+    end
+  end
+end

data/lib/isoautomate/config.rb

@@ -0,0 +1,15 @@
+module Isoautomate
+  # Redis Keys
+  REDIS_PREFIX = "ISOAUTOMATE:"
+  WORKERS_SET = "#{REDIS_PREFIX}workers"
+
+  # File System Paths
+  SCREENSHOT_FOLDER = "screenshots"
+  ASSERTION_FOLDER = File.join(SCREENSHOT_FOLDER, "failures")
+
+  # Defaults (Left nil to force explicit or ENV configuration)
+  DEFAULT_REDIS_HOST = nil
+  DEFAULT_REDIS_PORT = nil
+  DEFAULT_REDIS_PASSWORD = nil
+  DEFAULT_REDIS_DB = 0
+end

data/lib/isoautomate/version.rb

@@ -0,0 +1,3 @@
+module Isoautomate
+  VERSION = "0.1.0"
+end

data/lib/isoautomate.rb

@@ -0,0 +1,11 @@
+require "dotenv/load"
+require "isoautomate/version"
+require "isoautomate/config"
+require "isoautomate/exceptions"
+require "isoautomate/utils"
+# client is required last as it depends on the above
+require "isoautomate/client"
+
+module Isoautomate
+  # Module level logger could go here if needed
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: isoautomate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- isoAutomate Team
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Provides connectivity to the isoFleet engine via Redis for distributed
+  browser automation.
+email:
+- support@isoautomate.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- ext/sdk-ruby.png
+- isoautomate.gemspec
+- lib/isoautomate.rb
+- lib/isoautomate/client.rb
+- lib/isoautomate/config.rb
+- lib/isoautomate/version.rb
+homepage: https://github.com/isoautomate/isoautomate-ruby
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Official Ruby SDK for the isoAutomate Sovereign Browser Infrastructure.
+test_files: []