browserbeam 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15e5f1fad0f6f29ae8ce9616b429a9078771a1d6911a220e32b5f230c12ca02a
+  data.tar.gz: 18116e46d6cabbc54716f800964ae354a993cead2f1c44d2edf0e97bbc1f2656
+SHA512:
+  metadata.gz: b8b82446fe2731ac36af5d52ee59706a43cc0e7214d404b066d472bb520cac5565a9eb04d1287858077b085e26bb0771f55cdfd3de3e63275e562859caeadd0b
+  data.tar.gz: d5f19a469e10f1eb4ff9225c24e5bb44155504a26a6d936be209f48efa4bbc0f4a1c46516b25f7c540bacdfc83f04b1ba3a72ddce54318c11e0926a522204ae2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolae Rotaru
+
+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,116 @@
+# Browserbeam Ruby SDK
+
+Official Ruby SDK for the [Browserbeam API](https://browserbeam.com) — browser automation built for AI agents.
+
+## Installation
+
+```bash
+gem install browserbeam
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "browserbeam"
+```
+
+## Quick Start
+
+```ruby
+require "browserbeam"
+
+client = Browserbeam::Client.new(api_key: "sk_live_...")
+
+session = client.sessions.create(url: "https://example.com")
+
+# Page state is available immediately
+puts session.page.title
+puts session.page.interactive_elements
+
+# Interact with the page
+session.click(ref: "e1")
+
+# Extract structured data
+result = session.extract(
+  title: "h1 >> text",
+  links: ["a >> href"]
+)
+puts result.extraction
+
+# Close when done
+session.close
+```
+
+## Configuration
+
+```ruby
+client = Browserbeam::Client.new(
+  api_key: "sk_live_...",       # or set BROWSERBEAM_API_KEY env var
+  base_url: "https://api.browserbeam.com",  # default
+  timeout: 120,                 # request timeout in seconds
+)
+```
+
+## Session Options
+
+```ruby
+session = client.sessions.create(
+  url: "https://example.com",
+  viewport: { width: 1280, height: 720 },
+  locale: "en-US",
+  timezone: "America/New_York",
+  proxy: "http://user:pass@proxy:8080",
+  block_resources: ["image", "font"],
+  auto_dismiss_blockers: true,
+  timeout: 300,
+)
+```
+
+## Available Methods
+
+| Method | Description |
+|--------|-------------|
+| `session.goto(url)` | Navigate to a URL |
+| `session.observe` | Get page state as markdown |
+| `session.click(ref:)` | Click an element by ref, text, or label |
+| `session.fill(value, ref:)` | Fill an input field |
+| `session.type(value, label:)` | Type text character by character |
+| `session.select(value, label:)` | Select a dropdown option |
+| `session.check(label:)` | Toggle a checkbox |
+| `session.scroll(to: "bottom")` | Scroll the page |
+| `session.scroll_collect` | Scroll and collect all content |
+| `session.screenshot` | Take a screenshot |
+| `session.extract(**schema)` | Extract structured data |
+| `session.fill_form(fields, submit:)` | Fill and submit a form |
+| `session.wait(ms:)` | Wait for time, selector, or text |
+| `session.pdf` | Generate a PDF |
+| `session.execute_js(expr)` | Run JavaScript |
+| `session.close` | Close the session |
+
+## Session Management
+
+```ruby
+sessions = client.sessions.list(status: "active")
+info = client.sessions.get("ses_abc123")
+client.sessions.destroy("ses_abc123")
+```
+
+## Error Handling
+
+```ruby
+begin
+  session = client.sessions.create(url: "https://example.com")
+rescue Browserbeam::RateLimitError => e
+  puts "Rate limited. Retry after #{e.retry_after}s"
+rescue Browserbeam::SessionNotFoundError => e
+  puts "Session not found: #{e.message}"
+end
+```
+
+## Documentation
+
+Full API documentation at [browserbeam.com/docs](https://browserbeam.com/docs/).
+
+## License
+
+MIT

data/lib/browserbeam/client.rb

@@ -0,0 +1,62 @@
+module Browserbeam
+  class Client
+    attr_reader :sessions
+
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      resolved_key = api_key || ENV["BROWSERBEAM_API_KEY"] || ""
+      raise ArgumentError, "No API key provided. Pass api_key: or set the BROWSERBEAM_API_KEY environment variable." if resolved_key.empty?
+
+      @http = Http.new(api_key: resolved_key, base_url: base_url, timeout: timeout)
+      @sessions = Sessions.new(@http)
+    end
+  end
+
+  class Sessions
+    def initialize(http)
+      @http = http
+    end
+
+    def create(url: nil, steps: nil, timeout: nil, viewport: nil, user_agent: nil,
+               locale: nil, timezone: nil, proxy: nil, block_resources: nil,
+               auto_dismiss_blockers: nil, cookies: nil, idempotency_key: nil)
+      body = {}
+      body[:url] = url if url
+      body[:steps] = steps if steps
+      body[:timeout] = timeout if timeout
+      body[:viewport] = viewport if viewport
+      body[:user_agent] = user_agent if user_agent
+      body[:locale] = locale if locale
+      body[:timezone] = timezone if timezone
+      body[:proxy] = proxy if proxy
+      body[:block_resources] = block_resources if block_resources
+      body[:auto_dismiss_blockers] = auto_dismiss_blockers unless auto_dismiss_blockers.nil?
+      body[:cookies] = cookies if cookies
+
+      extra_headers = {}
+      extra_headers["Idempotency-Key"] = idempotency_key if idempotency_key
+
+      data = @http.post("/v1/sessions", body, extra_headers)
+      envelope = SessionEnvelope.from_hash(data)
+      Session.new(envelope, @http)
+    end
+
+    def get(session_id)
+      data = @http.get("/v1/sessions/#{session_id}")
+      SessionInfo.from_hash(data)
+    end
+
+    def list(status: nil, limit: nil, after: nil)
+      params = {}
+      params[:status] = status if status
+      params[:limit] = limit if limit
+      params[:after] = after if after
+      data = @http.get("/v1/sessions", params)
+      SessionList.from_hash(data)
+    end
+
+    def destroy(session_id)
+      @http.delete("/v1/sessions/#{session_id}")
+      nil
+    end
+  end
+end

data/lib/browserbeam/errors.rb

@@ -0,0 +1,86 @@
+module Browserbeam
+  class Error < StandardError
+    attr_reader :code, :status_code, :context, :request_id
+
+    def initialize(message, code: "", status_code: 0, context: {}, request_id: nil)
+      super(message)
+      @code = code
+      @status_code = status_code
+      @context = context || {}
+      @request_id = request_id
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class InvalidRequestError < Error; end
+  class SessionNotFoundError < Error; end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  class QuotaExceededError < Error
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  class EngineUnavailableError < Error
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  class StepExecutionError < Error
+    attr_reader :step_index, :action
+
+    def initialize(message, step_index: 0, action: "", **kwargs)
+      super(message, **kwargs)
+      @step_index = step_index
+      @action = action
+    end
+  end
+
+  module ErrorHandler
+    def self.raise_for_status(status_code, body, headers)
+      error_data = body.is_a?(Hash) ? (body["error"] || {}) : {}
+      code = error_data["code"] || "unknown"
+      message = error_data["message"] || "Unknown error"
+      context = error_data["context"]
+      request_id = headers["x-request-id"]
+      retry_after_raw = headers["retry-after"]
+      retry_after = retry_after_raw ? retry_after_raw.to_i : nil
+
+      kwargs = { code: code, status_code: status_code, context: context, request_id: request_id }
+
+      case status_code
+      when 401
+        raise AuthenticationError.new(message, **kwargs)
+      when 429
+        if code == "quota_exceeded"
+          raise QuotaExceededError.new(message, retry_after: retry_after, **kwargs)
+        end
+        raise RateLimitError.new(message, retry_after: retry_after, **kwargs)
+      when 404
+        raise SessionNotFoundError.new(message, **kwargs)
+      when 503
+        raise EngineUnavailableError.new(message, retry_after: retry_after, **kwargs)
+      when 400
+        raise InvalidRequestError.new(message, **kwargs)
+      else
+        raise Error.new(message, **kwargs)
+      end
+    end
+  end
+end

data/lib/browserbeam/http.rb

@@ -0,0 +1,55 @@
+require "faraday"
+require "json"
+
+module Browserbeam
+  class Http
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      @conn = Faraday.new(url: base_url) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+        f.headers["Authorization"] = "Bearer #{api_key}"
+        f.headers["User-Agent"] = "browserbeam-ruby/#{VERSION}"
+        f.options.timeout = timeout
+        f.options.open_timeout = 10
+      end
+    end
+
+    def post(path, body = {}, extra_headers = {})
+      response = @conn.post(path) do |req|
+        req.body = body
+        extra_headers.each { |k, v| req.headers[k] = v }
+      end
+      handle_response(response)
+    end
+
+    def get(path, params = {})
+      response = @conn.get(path) do |req|
+        params.each { |k, v| req.params[k.to_s] = v unless v.nil? }
+      end
+      handle_response(response)
+    end
+
+    def delete(path)
+      response = @conn.delete(path)
+      return {} if response.status == 204
+      handle_response(response)
+    end
+
+    private
+
+    def handle_response(response)
+      return {} if response.status == 204
+
+      body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
+
+      if response.status >= 400
+        headers = {}
+        response.headers.each { |k, v| headers[k.downcase] = v }
+        ErrorHandler.raise_for_status(response.status, body, headers)
+      end
+
+      body
+    end
+  end
+end

data/lib/browserbeam/session.rb

@@ -0,0 +1,158 @@
+module Browserbeam
+  class Session
+    attr_reader :session_id, :expires_at, :request_id, :completed,
+                :page, :media, :extraction, :blockers_dismissed, :error
+
+    def initialize(envelope, http)
+      @http = http
+      update(envelope)
+    end
+
+    def last_response
+      @last
+    end
+
+    def act(steps)
+      data = @http.post("/v1/sessions/#{session_id}/act", { steps: steps })
+      envelope = SessionEnvelope.from_hash(data)
+      update(envelope)
+      envelope
+    end
+
+    def goto(url, wait_for: nil, wait_timeout: nil)
+      params = { url: url }
+      params[:wait_for] = wait_for if wait_for
+      params[:wait_timeout] = wait_timeout if wait_timeout
+      act([{ goto: params }])
+    end
+
+    def observe(scope: nil, format: nil, include_links: nil, max_text_length: nil)
+      params = {}
+      params[:scope] = scope if scope
+      params[:format] = format if format
+      params[:include_links] = include_links unless include_links.nil?
+      params[:max_text_length] = max_text_length if max_text_length
+      act([{ observe: params }])
+    end
+
+    def click(ref: nil, text: nil, label: nil)
+      params = {}
+      params[:ref] = ref if ref
+      params[:text] = text if text
+      params[:label] = label if label
+      act([{ click: params }])
+    end
+
+    def fill(value, ref: nil, label: nil)
+      params = { value: value }
+      params[:ref] = ref if ref
+      params[:label] = label if label
+      act([{ fill: params }])
+    end
+
+    def type(value, label: nil, ref: nil, delay: nil)
+      params = { value: value }
+      params[:label] = label if label
+      params[:ref] = ref if ref
+      params[:delay] = delay if delay
+      act([{ type: params }])
+    end
+
+    def select(value, label: nil, ref: nil)
+      params = { value: value }
+      params[:label] = label if label
+      params[:ref] = ref if ref
+      act([{ select: params }])
+    end
+
+    def check(label: nil, ref: nil, checked: nil)
+      params = {}
+      params[:label] = label if label
+      params[:ref] = ref if ref
+      params[:checked] = checked unless checked.nil?
+      act([{ check: params }])
+    end
+
+    def scroll(to: nil, direction: nil, amount: nil, times: nil, ref: nil)
+      params = {}
+      params[:to] = to if to
+      params[:direction] = direction if direction
+      params[:amount] = amount if amount
+      params[:times] = times if times
+      params[:ref] = ref if ref
+      act([{ scroll: params }])
+    end
+
+    def scroll_collect(max_scrolls: nil, wait_ms: nil, timeout_ms: nil, max_text_length: nil)
+      params = {}
+      params[:max_scrolls] = max_scrolls if max_scrolls
+      params[:wait_ms] = wait_ms if wait_ms
+      params[:timeout_ms] = timeout_ms if timeout_ms
+      params[:max_text_length] = max_text_length if max_text_length
+      act([{ scroll_collect: params }])
+    end
+
+    def screenshot(full_page: nil, format: nil, quality: nil, selector: nil)
+      params = {}
+      params[:full_page] = full_page unless full_page.nil?
+      params[:format] = format if format
+      params[:quality] = quality if quality
+      params[:selector] = selector if selector
+      act([{ screenshot: params }])
+    end
+
+    def wait(ms: nil, selector: nil, text: nil, timeout: nil)
+      params = {}
+      params[:ms] = ms if ms
+      params[:selector] = selector if selector
+      params[:text] = text if text
+      params[:timeout] = timeout if timeout
+      act([{ wait: params }])
+    end
+
+    def extract(**schema)
+      act([{ extract: schema }])
+    end
+
+    def fill_form(fields, submit: false)
+      params = { fields: fields }
+      params[:submit] = true if submit
+      act([{ fill_form: params }])
+    end
+
+    def upload(ref, files)
+      act([{ upload: { ref: ref, files: files } }])
+    end
+
+    def pdf(format: nil, landscape: nil, print_background: nil)
+      params = {}
+      params[:format] = format if format
+      params[:landscape] = landscape unless landscape.nil?
+      params[:print_background] = print_background unless print_background.nil?
+      act([{ pdf: params }])
+    end
+
+    def execute_js(expression)
+      act([{ execute_js: { expression: expression } }])
+    end
+
+    def close
+      act([{ close: {} }])
+    end
+
+    private
+
+    def update(envelope)
+      @last = envelope
+      @session_id = envelope.session_id
+      @expires_at = envelope.expires_at
+      @request_id = envelope.request_id
+      @completed = envelope.completed
+      @page = envelope.page
+      @media = envelope.media
+      @extraction = envelope.extraction
+      @blockers_dismissed = envelope.blockers_dismissed
+      @error = envelope.error
+    end
+  end
+end

data/lib/browserbeam/types.rb

@@ -0,0 +1,119 @@
+module Browserbeam
+  MarkdownContent = Struct.new(:content, :length, keyword_init: true) do
+    def self.from_hash(data)
+      return nil unless data.is_a?(Hash)
+      new(content: data["content"] || "", length: data["length"])
+    end
+  end
+
+  InteractiveElement = Struct.new(:ref, :tag, :role, :label, :value, keyword_init: true) do
+    def self.from_hash(data)
+      new(
+        ref: data["ref"] || "",
+        tag: data["tag"] || "",
+        role: data["role"] || "",
+        label: data["label"] || "",
+        value: data["value"],
+      )
+    end
+  end
+
+  Changes = Struct.new(:content_changed, :content_delta, :elements_added, :elements_removed, keyword_init: true) do
+    def self.from_hash(data)
+      return nil unless data.is_a?(Hash)
+      new(
+        content_changed: data["content_changed"] || false,
+        content_delta: data["content_delta"],
+        elements_added: data["elements_added"] || [],
+        elements_removed: data["elements_removed"] || [],
+      )
+    end
+  end
+
+  ScrollState = Struct.new(:y, :height, :viewport, :percent, keyword_init: true) do
+    def self.from_hash(data)
+      return nil unless data.is_a?(Hash)
+      new(y: data["y"] || 0, height: data["height"] || 0, viewport: data["viewport"] || 0, percent: data["percent"] || 0)
+    end
+  end
+
+  PageState = Struct.new(:url, :title, :stable, :markdown, :interactive_elements, :forms, :changes, :scroll, keyword_init: true) do
+    def self.from_hash(data)
+      return nil unless data.is_a?(Hash)
+      new(
+        url: data["url"] || "",
+        title: data["title"] || "",
+        stable: data["stable"] || false,
+        markdown: MarkdownContent.from_hash(data["markdown"]),
+        interactive_elements: (data["interactive_elements"] || []).map { |el| InteractiveElement.from_hash(el) },
+        forms: data["forms"] || [],
+        changes: Changes.from_hash(data["changes"]),
+        scroll: ScrollState.from_hash(data["scroll"]),
+      )
+    end
+  end
+
+  MediaItem = Struct.new(:type, :format, :data, keyword_init: true) do
+    def self.from_hash(data)
+      new(type: data["type"] || "", format: data["format"] || "", data: data["data"] || "")
+    end
+  end
+
+  StepError = Struct.new(:step, :action, :code, :message, :context, keyword_init: true) do
+    def self.from_hash(data)
+      return nil unless data.is_a?(Hash)
+      new(
+        step: data["step"] || 0,
+        action: data["action"] || "",
+        code: data["code"] || "",
+        message: data["message"] || "",
+        context: data["context"] || {},
+      )
+    end
+  end
+
+  SessionEnvelope = Struct.new(:session_id, :expires_at, :request_id, :completed, :page, :media, :extraction, :blockers_dismissed, :error, keyword_init: true) do
+    def self.from_hash(data)
+      new(
+        session_id: data["session_id"] || "",
+        expires_at: data["expires_at"] || "",
+        request_id: data["request_id"] || "",
+        completed: data["completed"] || 0,
+        page: PageState.from_hash(data["page"]),
+        media: (data["media"] || []).map { |m| MediaItem.from_hash(m) },
+        extraction: data["extraction"],
+        blockers_dismissed: data["blockers_dismissed"] || [],
+        error: StepError.from_hash(data["error"]),
+      )
+    end
+  end
+
+  SessionInfo = Struct.new(:session_id, :status, :started_at, :ended_at, :duration_seconds, :expires_at, keyword_init: true) do
+    def self.from_hash(data)
+      new(
+        session_id: data["session_id"] || "",
+        status: data["status"] || "",
+        started_at: data["started_at"] || "",
+        ended_at: data["ended_at"],
+        duration_seconds: data["duration_seconds"],
+        expires_at: data["expires_at"] || "",
+      )
+    end
+  end
+
+  SessionListItem = Struct.new(:session_id, :status, :started_at, keyword_init: true) do
+    def self.from_hash(data)
+      new(session_id: data["session_id"] || "", status: data["status"] || "", started_at: data["started_at"] || "")
+    end
+  end
+
+  SessionList = Struct.new(:sessions, :has_more, :next_cursor, keyword_init: true) do
+    def self.from_hash(data)
+      new(
+        sessions: (data["sessions"] || []).map { |s| SessionListItem.from_hash(s) },
+        has_more: data["has_more"] || false,
+        next_cursor: data["next_cursor"],
+      )
+    end
+  end
+end

data/lib/browserbeam/version.rb

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

data/lib/browserbeam.rb

@@ -0,0 +1,11 @@
+require_relative "browserbeam/version"
+require_relative "browserbeam/errors"
+require_relative "browserbeam/types"
+require_relative "browserbeam/http"
+require_relative "browserbeam/session"
+require_relative "browserbeam/client"
+
+module Browserbeam
+  DEFAULT_BASE_URL = "https://api.browserbeam.com"
+  DEFAULT_TIMEOUT = 120
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: browserbeam
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Browserbeam
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Browser automation built for AI agents. Control real browsers through
+  a simple Ruby interface.
+email:
+- hello@browserbeam.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/browserbeam.rb
+- lib/browserbeam/client.rb
+- lib/browserbeam/errors.rb
+- lib/browserbeam/http.rb
+- lib/browserbeam/session.rb
+- lib/browserbeam/types.rb
+- lib/browserbeam/version.rb
+homepage: https://browserbeam.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://browserbeam.com
+  source_code_uri: https://github.com/nyku/browserbeam-ruby
+  documentation_uri: https://browserbeam.com/docs/
+  changelog_uri: https://github.com/nyku/browserbeam-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Browserbeam API
+test_files: []