browser-control-sdk 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c869a20d4d53b4253a30369b1664e68ee9cb9905447209a32d84aacae2f5cc6
+  data.tar.gz: e787d6e4a8f1523429467bfdba1fc0dabe7768aa8c208ee1be2329aca2e065e8
+SHA512:
+  metadata.gz: 68fb3e2352ffb9df87d7e91eb39ef6962fa724c26dbd34abd053bea1f243e02749a81bdab0397c98d37d44f5655230ee9d37dbf422a89255ecd799969cf8bd90
+  data.tar.gz: 53d5498ef3c0b01581c9e94fbb10e4fa59fb6f37b9103bb35b7c2051c7a54e39fc97d1d9eae22ba348f0f759fd123713334f9e5594766f46f74e3344dfc23868

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TitanCSA
+
+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,18 @@
+# Browser Control SDK for Ruby
+
+`gem install browser-control-sdk`
+
+Requires Ruby 3.1+ on Windows x64 and the running BrowserControl application. The included native bridge communicates directly with its private named pipe. No Python or driver installation is required.
+
+```ruby
+require 'browser_control_sdk'
+BrowserControlSDK::Browser.connect do |browser|
+  p browser.info
+  tab = browser.new_tab
+  browser.navigate(tab.fetch('id'), 'https://example.com')
+end
+```
+
+Use `connect(endpoint: 'C:/path/to/private/endpoint.json')` to select one running instance. Without a path the native SDK discovers a responding instance for the current user. The endpoint contains a private authentication token; keep it private.
+
+Every documented protocol operation is available through `browser.call(method, params, timeout_ms: 15000)`. See [API documentation](docs/API.md) and [example](examples/browser.rb). Call `close` if you do not use the block form.

data/docs/API.md

@@ -0,0 +1,9 @@
+# Ruby API
+
+`BrowserControlSDK::Browser.connect(endpoint: nil) { |browser| ... }` connects and confirms the running instance. The block form always closes the client. `close` is idempotent. Windows x64 is required.
+
+`call(method, params = {}, timeout_ms: 15000)` returns parsed JSON. Parameters must be a Hash, timeout an integer from 1 to 120000 milliseconds. Each client serializes calls. Convenience methods: `info`, `tabs`, `new_tab(options = {})`, `navigate(tab_id, url, timeout_ms: 15000)`.
+
+`BrowserControlSDK::Error` exposes `code` and `details`. A `result_unknown` error means the action may have executed; inspect state before retrying. No request is automatically retried. Transport request/response bounds and timeouts are those of the original C++ SDK (1 MiB request and 64 MiB reply). Ruby Integer preserves JSON integers without converting them to floating point.
+
+The bridge source and C ABI are in the repository's `Browser-Control-SDK-C-ffi` directory. Native handles and returned buffers are released by the wrapper. BrowserControl itself is distributed separately; the gem never downloads or launches it.

data/docs/THIRD-PARTY-LICENSES.txt

@@ -0,0 +1,22 @@
+JSON for Modern C++
+Copyright (c) 2013-2025 Niels Lohmann
+
+Copyright (c) 2026 TitanCSA
+
+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/examples/browser.rb

@@ -0,0 +1,2 @@
+require 'browser_control_sdk'
+BrowserControlSDK::Browser.connect { |browser| puts JSON.pretty_generate(browser.info); puts JSON.pretty_generate(browser.tabs) }

data/lib/browser_control_sdk.rb

@@ -0,0 +1,78 @@
+require 'json'
+require 'fiddle/import'
+require 'thread'
+module BrowserControlSDK
+  VERSION = '0.2.2'
+  class Error < StandardError
+    attr_reader :code, :details
+    def initialize(data)
+      @code = data.fetch('code', 'sdk_error'); @details = data.fetch('details', {})
+      super(data.fetch('message', @code))
+    end
+  end
+  module Native
+    extend Fiddle::Importer
+    raise LoadError, 'BrowserControlSDK requires Windows x64' unless RUBY_PLATFORM.match?(/mswin|mingw/) && Fiddle::SIZEOF_VOIDP == 8
+    dlload File.expand_path('native/BrowserControlBridge.dll', __dir__)
+    extern 'unsigned long long bcs_connect(const char*, void*)'
+    extern 'int bcs_call(unsigned long long, const char*, const char*, unsigned int, void*)'
+    extern 'void bcs_close(unsigned long long)'
+    extern 'void bcs_free(void*)'
+    def self.output
+      ptr = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP, Fiddle::RUBY_FREE)
+      ptr[0, Fiddle::SIZEOF_VOIDP] = [0].pack('J'); ptr
+    end
+    def self.take(out)
+      address = out[0, Fiddle::SIZEOF_VOIDP].unpack1('J')
+      raise Error.new('code'=>'sdk_error', 'message'=>'Native SDK returned no response') if address.zero?
+      text = Fiddle::Pointer.new(address)
+      begin
+        JSON.parse(text.to_s.force_encoding(Encoding::UTF_8))
+      ensure
+        bcs_free(text)
+      end
+    end
+  end
+  class Browser
+    def self.connect(endpoint: nil)
+      client = new(endpoint)
+      return client unless block_given?
+      begin
+        yield client
+      ensure
+        client.close
+      end
+    end
+    def initialize(endpoint = nil)
+      @mutex = Mutex.new
+      raise ArgumentError, 'Endpoint must be a String or nil' unless endpoint.nil? || endpoint.is_a?(String)
+      path = endpoint&.encode(Encoding::UTF_8)
+      raise ArgumentError, 'Endpoint contains a NUL byte' if path&.include?("\0")
+      out = Native.output; @handle = Native.bcs_connect(path, out)
+      raise Error.new(Native.take(out)) if @handle.zero?
+    end
+    def call(method, params = {}, timeout_ms: 15_000)
+      raise ArgumentError, 'Parameters must be a Hash' unless params.is_a?(Hash)
+      raise ArgumentError, 'Use a nonempty method' unless method.is_a?(String) && !method.empty? && !method.include?("\0")
+      raise ArgumentError, 'Timeout must be 1..120000 milliseconds' unless timeout_ms.is_a?(Integer) && (1..120_000).cover?(timeout_ms)
+      @mutex.synchronize do
+        raise Error.new('code'=>'closed', 'message'=>'Browser client is closed') if @handle.zero?
+        out = Native.output
+        code = Native.bcs_call(@handle, method.encode(Encoding::UTF_8), JSON.generate(params), timeout_ms, out)
+        data = Native.take(out)
+        raise Error.new(data) unless code.zero?
+        data
+      end
+    end
+    def info; call('browser.info'); end
+    def tabs; call('tabs.list'); end
+    def new_tab(options = {}); call('tabs.create', options); end
+    def navigate(tab, url, timeout_ms: 15_000)
+      call('page.navigate', {'tab'=>tab, 'url'=>url, 'wait'=>'load', 'timeout_ms'=>timeout_ms}, timeout_ms: timeout_ms)
+    end
+    def close
+      @mutex.synchronize { Native.bcs_close(@handle) unless @handle.zero?; @handle = 0 }
+      nil
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: browser-control-sdk
+version: !ruby/object:Gem::Version
+  version: 0.2.2
+platform: ruby
+authors:
+- TitanCSA
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Ruby bindings to the native BrowserControl SDK. All protocol methods,
+  bounded transport, UTF-8 JSON and structured errors. Windows x64 only; no Python
+  dependency.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- docs/API.md
+- docs/THIRD-PARTY-LICENSES.txt
+- examples/browser.rb
+- lib/browser_control_sdk.rb
+- lib/native/BrowserControlBridge.dll
+homepage: https://github.com/TitanCSA/Browser-Control-SDK
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/TitanCSA/Browser-Control-SDK/tree/main/Browser-Control-SDK-Ruby-rubygems
+  documentation_uri: https://github.com/TitanCSA/Browser-Control-SDK/tree/main/Browser-Control-SDK-Ruby-rubygems/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Direct Windows named-pipe SDK for BrowserControl
+test_files: []