browserbeam 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b0481857f0872498c855f5c1cc7611f468f348e406299601fde653abb148487
-  data.tar.gz: 989f1e433800e1d2132cadb9bb83e8497884939da70deffe0e5148c21b74c647
+  metadata.gz: d16b959107bf89d7f6b0a8851b519e76548ce7968f249e1b7408d7fc9950fbc0
+  data.tar.gz: c2636291d527fe711292779e66498febc7b691701dc860a68c2826a37aa672e1
 SHA512:
-  metadata.gz: 0605be53e22028d51513793fb6f0542caac9a131135ea1566fff865f7a5087f3c8b168569749fefc4cb1473f46b9e0accc22020c66495d4493caae72f46815f9
-  data.tar.gz: c5d700fbcac26e7757a891729071e7cb959007e0b4f8d8b7b51a16d34a145af168db7f108b726f0e24f67ed41f67d571c33db1d1992c76320a2091656fbb1764
+  metadata.gz: 0b38c33925c606bd55e55c192700009efb2db1d0d86cdd561651dc43e6ad7a9aa88d2e113fcf8809b6481a40376a6abec1e4a422f46b1c1b977cd1370e7b42de
+  data.tar.gz: c1aaed1e4555eb2688ff3817bb10137f399c670316b328a0fa5f2543412513cc57dac552d439f0905d8a74ad7b9f49576bfb242713f7f9a02b685d39687d32d8

data/README.md

@@ -30,10 +30,17 @@ puts session.page.interactive_elements
 # Interact with the page
 session.click(ref: "e1")
 
-# Extract structured data
+# Extract with CSS, AI, and JS selectors combined
 result = session.extract(
-  title: "h1 >> text",
-  links: ["a >> href"]
+  products: [{
+    "_parent": ".product-card",
+    "_limit": 3,
+    "name": "h2 >> text",                          # CSS selector
+    "price": ".price >> text",                     # CSS selector
+    "url": "a >> href",                            # CSS attribute
+    "rating": "ai >> the star rating out of 5",    # AI selector
+    "in_stock": "js >> el.querySelector('.stock')?.textContent.includes('In stock')",  # JS
+  }]
 )
 puts result.extraction
 
@@ -57,15 +64,33 @@ client = Browserbeam::Client.new(
 session = client.sessions.create(
   url: "https://example.com",
   viewport: { width: 1280, height: 720 },
+  user_agent: "Mozilla/5.0 ...",  # omit for automatic rotation
   locale: "en-US",
   timezone: "America/New_York",
-  proxy: "http://user:pass@proxy:8080",
   block_resources: ["image", "font"],
   auto_dismiss_blockers: true,
   timeout: 300,
 )
 ```
 
+### Proxies
+
+All sessions use a datacenter proxy by default (country auto-detected from the URL's TLD). No configuration needed. To customize:
+
+```ruby
+# Use a residential proxy for a specific country
+session = client.sessions.create(
+  url: "https://example.com",
+  proxy: { kind: "residential", country: "us" },
+)
+
+# Or bring your own proxy (overrides managed proxy)
+session = client.sessions.create(
+  url: "https://example.com",
+  proxy: "http://user:pass@proxy:8080",
+)
+```
+
 ## Available Methods
 
 | Method | Description |
@@ -120,9 +145,15 @@ puts full.page.markdown.content
 
 ## Session Management
 
+Filter by `status: "active"`, `"closed"`, or `"failed"`. Failed sessions ended with a fatal error (e.g. blocked or unsolvable challenge); `get` returns `error_code` and `error_message`.
+
 ```ruby
 sessions = client.sessions.list(status: "active")
+failed = client.sessions.list(status: "failed")
 info = client.sessions.get("ses_abc123")
+if info.status == "failed"
+  warn "#{info.error_code}: #{info.error_message}"
+end
 client.sessions.destroy("ses_abc123")
 ```
 

data/lib/browserbeam/types.rb

@@ -95,7 +95,9 @@ module Browserbeam
     end
   end
 
-  SessionInfo = Struct.new(:session_id, :status, :started_at, :ended_at, :duration_seconds, :expires_at, keyword_init: true) do
+  SessionInfo = Struct.new(
+    :session_id, :status, :started_at, :ended_at, :duration_seconds, :expires_at, :error_code, :error_message, keyword_init: true
+  ) do
     def self.from_hash(data)
       new(
         session_id: data["session_id"] || "",
@@ -104,13 +106,20 @@ module Browserbeam
         ended_at: data["ended_at"],
         duration_seconds: data["duration_seconds"],
         expires_at: data["expires_at"] || "",
+        error_code: data["error_code"],
+        error_message: data["error_message"]
       )
     end
   end
 
-  SessionListItem = Struct.new(:session_id, :status, :started_at, keyword_init: true) do
+  SessionListItem = Struct.new(:session_id, :status, :started_at, :error_code, keyword_init: true) do
     def self.from_hash(data)
-      new(session_id: data["session_id"] || "", status: data["status"] || "", started_at: data["started_at"] || "")
+      new(
+        session_id: data["session_id"] || "",
+        status: data["status"] || "",
+        started_at: data["started_at"] || "",
+        error_code: data["error_code"]
+      )
     end
   end
 

data/lib/browserbeam/version.rb

@@ -1,3 +1,3 @@
 module Browserbeam
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserbeam
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Browserbeam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday