browserbeam 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 968540abd1c037b539260f27cf439d8f49d05a25f16e398cd56f56dc6d2c4591
-  data.tar.gz: fb7920bc04046dd96d62277826d2e3b4a83fce58d96961b65643686326c510d3
+  metadata.gz: 1f56eec67915879c1fb60e4c81cd34b4bd93d52cda25c5da6f72ad3def1f6a74
+  data.tar.gz: 58fbf4bab5ba5f29414cc4368310b2c120b2224a5455ea1946b8a86773aae7b3
 SHA512:
-  metadata.gz: bfe0019f622ff4273922faa8bc386264e013c33706f4ae3fe4921c68e04a42e9b7340b61874801df22d14efbc98529de2b5ef6937469e857f78377461a8a8f66
-  data.tar.gz: f4708420e29384d4a70d4ec10fe21d1d0b43a9cd83a9973c35d90991337e4175e1cd693da190cf0271d2e65b132958c1425ef1bd0b811171c18f12fd82aeee7e
+  metadata.gz: 7654e9332dd6745df0fff89d113d8de9b6120b8d632e09eb9e114de6120569fae5e0bc2a96e721881c3b099bb33e250d24562e3fcf8576db3aaa4ac84bb0acaf
+  data.tar.gz: 1a3bdeb98537414f79d9d8cc5d1e00e488d834e8cbe66e0080116afb00ca3bfc74904c8b028fc6965dbc3422967e7554e7fee1bfd7f2e6194864ad82f23393f9

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,21 +64,39 @@ 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 |
 |--------|-------------|
 | `session.goto(url)` | Navigate to a URL |
-| `session.observe` | Get page state as markdown |
+| `session.observe` | Get page state as markdown. Supports `mode: "full"` for all sections. |
 | `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 |
@@ -87,6 +112,37 @@ session = client.sessions.create(
 | `session.execute_js(code)` | Run JavaScript |
 | `session.close` | Close the session |
 
+## Page Map & Full Mode
+
+The first `observe` call automatically includes a `page.map` — a lightweight structural outline of the page's landmark regions (header, nav, main, aside, footer) with CSS selectors and descriptive hints. Use it to discover what content is available outside the main area.
+
+```ruby
+res = session.observe
+res.page.map.each { |entry| puts "#{entry.section}: #{entry.hint}" }
+# nav: Home · Docs · Pricing
+# main: Getting started with Browserbeam...
+# aside: Related posts · Popular tags
+```
+
+To re-request the map on subsequent calls:
+
+```ruby
+session.observe(include_page_map: true)
+```
+
+When you need content from **all** page sections (sidebars, footer links, nav items), use `mode: "full"`. The response markdown is organized by region headers:
+
+```ruby
+full = session.observe(mode: "full", max_text_length: 20_000)
+puts full.page.markdown.content
+# ## [nav]
+# Home · Docs · Pricing
+# ## [main]
+# ...article content...
+# ## [aside]
+# Related posts · ...
+```
+
 ## Session Management
 
 ```ruby

data/lib/browserbeam/session.rb

@@ -27,10 +27,12 @@ module Browserbeam
       act([{ goto: params }])
     end
 
-    def observe(scope: nil, format: nil, include_links: nil, max_text_length: nil)
+    def observe(scope: nil, format: nil, mode: nil, include_page_map: nil, include_links: nil, max_text_length: nil)
       params = {}
       params[:scope] = scope if scope
       params[:format] = format if format
+      params[:mode] = mode if mode
+      params[:include_page_map] = include_page_map unless include_page_map.nil?
       params[:include_links] = include_links unless include_links.nil?
       params[:max_text_length] = max_text_length if max_text_length
       act([{ observe: params }])

data/lib/browserbeam/types.rb

@@ -18,6 +18,12 @@ module Browserbeam
     end
   end
 
+  MapEntry = Struct.new(:section, :selector, :hint, keyword_init: true) do
+    def self.from_hash(data)
+      new(section: data["section"] || "", selector: data["selector"] || "", hint: data["hint"] || "")
+    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)
@@ -37,7 +43,7 @@ module Browserbeam
     end
   end
 
-  PageState = Struct.new(:url, :title, :stable, :markdown, :interactive_elements, :forms, :changes, :scroll, keyword_init: true) do
+  PageState = Struct.new(:url, :title, :stable, :markdown, :map, :interactive_elements, :forms, :changes, :scroll, keyword_init: true) do
     def self.from_hash(data)
       return nil unless data.is_a?(Hash)
       new(
@@ -45,6 +51,7 @@ module Browserbeam
         title: data["title"] || "",
         stable: data["stable"] || false,
         markdown: MarkdownContent.from_hash(data["markdown"]),
+        map: data["map"] ? data["map"].map { |m| MapEntry.from_hash(m) } : nil,
         interactive_elements: (data["interactive_elements"] || []).map { |el| InteractiveElement.from_hash(el) },
         forms: data["forms"] || [],
         changes: Changes.from_hash(data["changes"]),

data/lib/browserbeam/version.rb

@@ -1,3 +1,3 @@
 module Browserbeam
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

metadata

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