adscrawl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 53190cac137e9d06f3175969488c05c975dc10ce41bae70c0682110242666b05
+  data.tar.gz: dbe222b0ff615996d4dbcb6071d9f4f9289d83467d850632c8778ba308be5c3b
+SHA512:
+  metadata.gz: edc122d2a0d30101806275101c8def52f424a62348428405de2a91973559952cc032f84bf4088b744e493d0add8a400d3e580638317b069fcd041bf67bbcecc2
+  data.tar.gz: ae6f562c5cc5249c2f9b31ed7a2a424ffc93e01b1ce79f38e7b4b7272b9d4b2f7ba412cc20a268cb532fe299c949df1491fb647c84cca7a9f7ccb0d55e98f132

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-09-28
+
+- Initial Ruby SDK for rendered HTML, Markdown, articles, and PNG screenshots.
+- SPA extraction, CDP session, and persistent cloud browser services.
+- Request deadlines, response validation, credential-redacted errors, and runnable examples.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AdsCrawl
+
+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,208 @@
+<p align="center">
+  <a href="https://www.adscrawl.net/?utm_source=github&utm_medium=sdk&utm_campaign=adscrawl-ruby">
+    <img src="assets/adscrawl-logo.svg" alt="AdsCrawl" width="360" />
+  </a>
+</p>
+
+<p align="center"><strong>Real browsers. Structured extraction. Screenshots and automation.</strong></p>
+
+<h1 align="center">Ruby SDK</h1>
+
+Turn a URL into rendered HTML, readable Markdown, structured data, or a PNG screenshot. Open remote CDP sessions and manage persistent cloud browsers with the same API as the TypeScript, Python, Go, and PHP SDKs.
+
+[Website](https://www.adscrawl.net/?utm_source=github&utm_medium=sdk&utm_campaign=adscrawl-ruby) · [API documentation](https://www.adscrawl.net/docs/) · [Get an API key](https://app.adscrawl.net/register/?utm_source=rubygems&utm_medium=sdk&utm_campaign=adscrawl-ruby) · [中文](./README.zh-CN.md)
+
+- Ruby 3.1+ with no runtime dependencies outside the standard library.
+- Explicit HTTP deadlines, checked response shapes, and credential-redacted errors.
+- Hash and keyword arguments use the HTTP API's camelCase field names.
+- No automatic retries of metered requests or browser creation.
+
+## Install
+
+```bash
+gem install adscrawl
+```
+
+Or add it to your bundle:
+
+```bash
+bundle add adscrawl
+```
+
+## Your first request
+
+[Create an account](https://app.adscrawl.net/register/?utm_source=rubygems&utm_medium=sdk&utm_campaign=adscrawl-ruby), create an API key, and set `ADSCRAWL_API_KEY` in your server environment.
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+markdown = client.markdown(
+  url: "https://www.adscrawl.net",
+  waitUntil: "domcontentloaded"
+)
+puts markdown
+```
+
+You can also use `AdsCrawl::Client.new(api_key: "...")`. Keep API keys in server-side code. See the complete runnable examples for [Markdown](./examples/markdown.rb), [screenshots](./examples/screenshot.rb), [structured extraction](./examples/extract.rb), [fingerprints](./examples/fingerprint.rb), [CDP](./examples/cdp.rb), and [cloud browsers](./examples/cloud_browser.rb).
+
+## Rendered content and screenshots
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+html = client.html(url: "https://www.adscrawl.net")
+article = client.article(url: "https://www.adscrawl.net")
+puts [article["title"], article["textContent"]]
+
+png = client.screenshot(
+  url: "https://www.adscrawl.net",
+  viewport: {width: 1440, height: 900},
+  fullPage: true,
+  waitUntil: "load"
+)
+File.binwrite("page.png", png)
+```
+
+`html` returns HTML, `markdown` returns Markdown, `article` returns a Hash, and `screenshot` returns binary PNG data. Page options include viewport, locale, cookies, custom `proxy`, managed `countryCode`, fingerprint, server-side `timeoutMs`, and navigation `waitUntil`. A custom proxy and managed country cannot be combined.
+
+## Proxy and fingerprint: BrowserScan screenshot
+
+AdsCrawl uses real browsers with configurable routing and browser fingerprints. This complete example uses managed `GLOBAL` routing unless proxy environment variables are present, opens [BrowserScan](https://www.browserscan.net/), and saves the returned screenshot. The same browser workflow can access and render [Pixelscan](https://pixelscan.net/) and [IPhey](https://iphey.com/); inspect the returned page for its current result.
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+server = ENV["ADSCRAWL_PROXY_SERVER"]
+username = ENV["ADSCRAWL_PROXY_USERNAME"]
+password = ENV["ADSCRAWL_PROXY_PASSWORD"]
+raise "Set both proxy username and password, or neither." if username.nil? != password.nil?
+raise "Set ADSCRAWL_PROXY_SERVER with proxy credentials." if server.nil? && (username || password)
+
+routing = {countryCode: "GLOBAL"}
+if server
+  proxy = {server: server}
+  proxy.merge!(username: username, password: password) if username && password
+  routing = {proxy: proxy}
+end
+
+png = client.screenshot(
+  **routing,
+  url: "https://www.browserscan.net/",
+  viewport: {width: 1440, height: 900},
+  fullPage: true,
+  waitUntil: "networkidle",
+  timeoutMs: 60_000,
+  userAgentMode: "random",
+  userAgentOs: "windows",
+  fingerprint: {
+    webRtc: "forward", webGl: "random", webGpu: "random",
+    webGlImage: "random", canvas: "random", audioContext: "random",
+    clientRects: "random", speechVoices: "random", fonts: "random",
+    hardware: "random", doNotTrack: "random"
+  },
+  timeout_ms: 75_000
+)
+File.binwrite("browserscan.png", png)
+```
+
+Run the included version with `ruby examples/fingerprint.rb`. Pass a detection URL and output path as optional arguments. The example never combines a custom proxy with managed routing.
+
+## Structured extraction
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+puts client.spa.templates["templates"]
+
+result = client.spa.extract(
+  url: "https://www.adscrawl.net",
+  fields: {
+    title: {source: "dom", selector: "h1", value: "text", required: true}
+  }
+)
+puts result.dig("data", "title")
+
+inspection = client.spa.inspect(url: "https://www.adscrawl.net")
+puts inspection["candidates"]
+```
+
+## Remote CDP browsers
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+session = client.cdp.create(
+  idleTimeoutMs: 600_000,
+  maxSessionMs: 3_600_000,
+  browserSettings: {viewport: {width: 1440, height: 900}}
+)
+begin
+  version = client.cdp.get_version(session)
+  puts version["Browser"]
+  # Connect a CDP-compatible Ruby library to session["cdpBaseUrl"].
+ensure
+  client.cdp.close(session["sessionId"])
+end
+```
+
+`client.cdp.list` returns active sessions. `get_version` validates the session token URL and deliberately omits the API key. CDP connection URLs contain secrets; do not log them.
+
+## Persistent cloud browsers
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+launched = client.cloud_browsers.launch(
+  proxy: {server: ENV.fetch("ADSCRAWL_PROXY_SERVER")},
+  tabs: ["https://www.adscrawl.net"]
+)
+browser_id = launched["id"]
+begin
+  profile = client.cloud_browsers.get(browser_id)
+  puts profile.dig("runtime", "status")
+ensure
+  client.cloud_browsers.stop(browser_id)
+end
+```
+
+API-key starts and launches require an explicit top-level custom proxy. A `stopping` response means shutdown is pending; poll `get` until `stopped`. A failed launch may expose a cleanup profile ID as `APIError#resource_id`.
+
+## Configuration and errors
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new(base_url: "https://api.adscrawl.net", timeout_ms: 90_000)
+begin
+  puts client.markdown(
+    {url: "https://www.adscrawl.net", timeoutMs: 60_000},
+    timeout_ms: 75_000
+  )
+rescue AdsCrawl::APIError => error
+  puts [error.status, error.api_code, error.trace_id]
+rescue AdsCrawl::TimeoutError
+  puts "Inspect remote sessions before retrying."
+end
+```
+
+The API key defaults to `ADSCRAWL_API_KEY`; the base URL defaults to `ADSCRAWL_BASE_URL`, then `ADSCRAWL_API_URL`, then `https://api.adscrawl.net`. Errors include `APIError`, `TimeoutError`, `ConnectionError`, and `ResponseError`. API response bodies are credential-redacted. The HTTP deadline includes response body reading. Requests are not automatically retried.
+
+## Develop and release
+
+```bash
+bundle install
+bundle exec rake test
+gem build adscrawl.gemspec
+```
+
+Tests use local and fake responses and consume no AdsCrawl credits. Releases use RubyGems Trusted Publishing with no long-lived registry token; see [RELEASING.md](./RELEASING.md).
+
+## License
+
+MIT

data/README.zh-CN.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <a href="https://www.adscrawl.net/?utm_source=github&utm_medium=sdk&utm_campaign=adscrawl-ruby">
+    <img src="assets/adscrawl-logo.svg" alt="AdsCrawl" width="360" />
+  </a>
+</p>
+
+<p align="center"><strong>真实浏览器、结构化提取、截图与自动化。</strong></p>
+
+<h1 align="center">Ruby SDK</h1>
+
+把 URL 转换为浏览器渲染后的 HTML、Markdown、结构化数据或 PNG 截图；也可以创建远程 CDP 会话和管理持久云浏览器。
+
+[官网](https://www.adscrawl.net/?utm_source=github&utm_medium=sdk&utm_campaign=adscrawl-ruby) · [API 文档](https://www.adscrawl.net/docs/) · [获取 API Key](https://app.adscrawl.net/register/?utm_source=rubygems&utm_medium=sdk&utm_campaign=adscrawl-ruby) · [English](./README.md)
+
+- 支持 Ruby 3.1+，除标准库外无运行时依赖。
+- 支持 HTTP 超时、响应结构校验和错误信息凭据脱敏。
+- Hash 和关键字参数与 HTTP API 使用相同的 camelCase 字段。
+- 对计费请求和浏览器创建请求不会自动重试。
+
+## 安装
+
+```bash
+gem install adscrawl
+```
+
+也可以添加到 Bundle：
+
+```bash
+bundle add adscrawl
+```
+
+## 第一个请求
+
+[注册账号](https://app.adscrawl.net/register/?utm_source=rubygems&utm_medium=sdk&utm_campaign=adscrawl-ruby)，创建 API Key，并在服务端环境变量中设置 `ADSCRAWL_API_KEY`。
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+markdown = client.markdown(
+  url: "https://www.adscrawl.net",
+  waitUntil: "domcontentloaded"
+)
+puts markdown
+```
+
+也可以使用 `AdsCrawl::Client.new(api_key: "...")`。API Key 应只保存在服务端。仓库包含完整可运行的 [Markdown](./examples/markdown.rb)、[截图](./examples/screenshot.rb)、[结构化提取](./examples/extract.rb)、[指纹检测](./examples/fingerprint.rb)、[CDP](./examples/cdp.rb) 和 [云浏览器](./examples/cloud_browser.rb) 示例。
+
+## 渲染内容与截图
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+html = client.html(url: "https://www.adscrawl.net")
+article = client.article(url: "https://www.adscrawl.net")
+puts [article["title"], article["textContent"]]
+
+png = client.screenshot(
+  url: "https://www.adscrawl.net",
+  viewport: {width: 1440, height: 900},
+  fullPage: true,
+  waitUntil: "load"
+)
+File.binwrite("page.png", png)
+```
+
+`html` 返回 HTML，`markdown` 返回 Markdown，`article` 返回 Hash，`screenshot` 返回 PNG 二进制数据。页面参数支持视口、语言、Cookie、自定义 `proxy`、托管 `countryCode`、浏览器指纹、服务端 `timeoutMs` 与导航 `waitUntil`。自定义代理和托管国家线路不能同时使用。
+
+## 代理与指纹：BrowserScan 截图
+
+AdsCrawl 使用真实浏览器，并支持配置线路和浏览器指纹。以下示例默认使用 `GLOBAL` 托管线路；设置代理环境变量后则使用自定义代理。示例访问 [BrowserScan](https://www.browserscan.net/) 并保存返回截图。同一套浏览器流程也可访问和渲染 [Pixelscan](https://pixelscan.net/) 与 [IPhey](https://iphey.com/)，可从返回页面查看网站当前的检测结果。
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+server = ENV["ADSCRAWL_PROXY_SERVER"]
+username = ENV["ADSCRAWL_PROXY_USERNAME"]
+password = ENV["ADSCRAWL_PROXY_PASSWORD"]
+raise "代理用户名和密码必须同时设置。" if username.nil? != password.nil?
+raise "使用代理凭据时必须设置 ADSCRAWL_PROXY_SERVER。" if server.nil? && (username || password)
+
+routing = {countryCode: "GLOBAL"}
+if server
+  proxy = {server: server}
+  proxy.merge!(username: username, password: password) if username && password
+  routing = {proxy: proxy}
+end
+
+png = client.screenshot(
+  **routing,
+  url: "https://www.browserscan.net/",
+  viewport: {width: 1440, height: 900},
+  fullPage: true,
+  waitUntil: "networkidle",
+  timeoutMs: 60_000,
+  userAgentMode: "random",
+  userAgentOs: "windows",
+  fingerprint: {
+    webRtc: "forward", webGl: "random", webGpu: "random",
+    webGlImage: "random", canvas: "random", audioContext: "random",
+    clientRects: "random", speechVoices: "random", fonts: "random",
+    hardware: "random", doNotTrack: "random"
+  },
+  timeout_ms: 75_000
+)
+File.binwrite("browserscan.png", png)
+```
+
+可运行 `ruby examples/fingerprint.rb`，也可以把检测网站 URL 和输出路径作为参数传入。示例不会把自定义代理和托管线路组合使用。
+
+## 结构化提取
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+puts client.spa.templates["templates"]
+
+result = client.spa.extract(
+  url: "https://www.adscrawl.net",
+  fields: {
+    title: {source: "dom", selector: "h1", value: "text", required: true}
+  }
+)
+puts result.dig("data", "title")
+
+inspection = client.spa.inspect(url: "https://www.adscrawl.net")
+puts inspection["candidates"]
+```
+
+## 远程 CDP 浏览器
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+session = client.cdp.create(
+  idleTimeoutMs: 600_000,
+  maxSessionMs: 3_600_000,
+  browserSettings: {viewport: {width: 1440, height: 900}}
+)
+begin
+  version = client.cdp.get_version(session)
+  puts version["Browser"]
+  # 使用兼容 CDP 的 Ruby 库连接 session["cdpBaseUrl"]。
+ensure
+  client.cdp.close(session["sessionId"])
+end
+```
+
+`client.cdp.list` 返回活动会话。`get_version` 会校验会话 Token URL，并且不会把 API Key 转发到数据端点。CDP 连接 URL 含有密钥，请勿写入日志。
+
+## 持久云浏览器
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+launched = client.cloud_browsers.launch(
+  proxy: {server: ENV.fetch("ADSCRAWL_PROXY_SERVER")},
+  tabs: ["https://www.adscrawl.net"]
+)
+browser_id = launched["id"]
+begin
+  profile = client.cloud_browsers.get(browser_id)
+  puts profile.dig("runtime", "status")
+ensure
+  client.cloud_browsers.stop(browser_id)
+end
+```
+
+使用 API Key 启动或快速创建云浏览器时，每次都必须传顶层自定义代理。返回 `stopping` 表示仍在关闭，需要轮询 `get` 直到状态为 `stopped`。快速创建失败时，`APIError#resource_id` 可能包含需要清理的浏览器 ID。
+
+## 配置与错误处理
+
+```ruby
+require "adscrawl"
+
+client = AdsCrawl::Client.new(base_url: "https://api.adscrawl.net", timeout_ms: 90_000)
+begin
+  puts client.markdown(
+    {url: "https://www.adscrawl.net", timeoutMs: 60_000},
+    timeout_ms: 75_000
+  )
+rescue AdsCrawl::APIError => error
+  puts [error.status, error.api_code, error.trace_id]
+rescue AdsCrawl::TimeoutError
+  puts "重试前请先检查远程会话。"
+end
+```
+
+API Key 默认读取 `ADSCRAWL_API_KEY`。基础 URL 依次读取 `ADSCRAWL_BASE_URL`、`ADSCRAWL_API_URL`，最后使用 `https://api.adscrawl.net`。错误类型包括 `APIError`、`TimeoutError`、`ConnectionError` 和 `ResponseError`。API 错误响应会进行凭据脱敏。HTTP 超时包含读取响应体的时间。SDK 不会自动重试请求。
+
+## 开发与发布
+
+```bash
+bundle install
+bundle exec rake test
+gem build adscrawl.gemspec
+```
+
+测试只使用本机和模拟响应，不消耗 AdsCrawl 额度。发布使用 RubyGems Trusted Publishing，不保存长期注册表 Token，详见 [RELEASING.md](./RELEASING.md)。
+
+## 许可证
+
+MIT

data/RELEASING.md

@@ -0,0 +1,15 @@
+# Releasing
+
+The release workflow uses RubyGems Trusted Publishing, so the repository stores no long-lived RubyGems API key.
+
+For the first release, create a pending trusted publisher in the RubyGems profile with:
+
+- Gem name: `adscrawl`
+- Repository owner: `AdsCrawl`
+- Repository name: `adscrawl-ruby`
+- Workflow filename: `release.yml`
+- Environment: `release`
+
+Then run `bundle exec rake test`, update `CHANGELOG.md`, and push a semantic version tag matching `AdsCrawl::VERSION`, such as `v0.1.0`. The workflow tests, builds, and publishes the Gem with a short-lived OIDC credential.
+
+Published Gem versions cannot be reused. If a release needs a correction, increment the version and publish a new tag.

data/assets/adscrawl-logo.svg

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="_图层_2" data-name="图层 2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1477.22 269.56">
+  <g id="_图层_1-2" data-name="图层 1">
+    <g>
+      <g>
+        <polygon points="126.17 164.02 32.77 238.88 40.36 171.56 43.32 141.82 17.48 134.9 4.69 261.79 33.69 269.56 156.33 172.1 126.17 164.02"/>
+        <polygon points="143.39 105.54 236.79 30.67 229.2 98 226.24 127.74 252.08 134.66 264.87 7.77 235.88 0 113.24 97.46 143.39 105.54"/>
+        <polygon points="105.54 126.16 30.67 32.77 98 40.36 127.74 43.32 134.66 17.48 7.77 4.69 0 33.68 97.46 156.32 105.54 126.16"/>
+        <polygon points="172.1 113.23 164.02 143.39 238.89 236.78 171.56 229.19 141.82 226.24 134.9 252.07 261.79 264.86 269.56 235.87 172.1 113.23"/>
+      </g>
+      <g>
+        <path d="M664.16,112.42c-3.12-3-6.7-5.54-10.75-7.59-6.84-3.46-14.54-5.19-23.1-5.19-11.2,0-21.12,2.72-29.76,8.15-8.65,5.43-15.48,12.84-20.5,22.23-5.02,9.39-7.53,20.01-7.53,31.86s2.51,22.23,7.53,31.62c5.02,9.39,11.89,16.8,20.63,22.23,8.72,5.43,18.61,8.15,29.64,8.15,8.56,0,16.3-1.81,23.22-5.43,4.13-2.16,7.74-4.8,10.87-7.9v10.86h32.11V48.32h-32.36v64.1ZM651.68,189.93c-4.53,2.72-9.84,4.08-15.93,4.08-5.77,0-10.95-1.36-15.56-4.08-4.61-2.72-8.19-6.5-10.74-11.36-2.55-4.86-3.83-10.5-3.83-16.92s1.27-11.77,3.83-16.55c2.55-4.77,6.09-8.56,10.62-11.36,4.53-2.8,9.84-4.2,15.93-4.2s11.15,1.36,15.68,4.08c4.53,2.72,8.07,6.51,10.62,11.36,2.55,4.86,3.83,10.42,3.83,16.67s-1.28,12.07-3.83,16.92c-2.56,4.86-6.1,8.65-10.62,11.36Z"/>
+        <path d="M797.68,156.5c-4.59-2.7-9.41-4.78-14.46-6.24-5.06-1.46-9.9-2.76-14.54-3.9-4.64-1.14-8.41-2.5-11.33-4.09-2.92-1.58-4.4-3.86-4.47-6.82-.05-2.63,1.18-4.72,3.7-6.25,2.52-1.53,6.17-2.35,10.94-2.45,5.27-.11,10.19.78,14.76,2.66,4.57,1.88,8.71,5.01,12.43,9.38l19.1-19.92c-5.41-6.8-12.15-11.85-20.21-15.14-8.06-3.29-17.02-4.83-26.9-4.63-9.38.2-17.5,1.93-24.35,5.2-6.85,3.27-12.07,7.75-15.66,13.42-3.59,5.68-5.3,12.3-5.14,19.87.15,7.25,1.71,13.1,4.69,17.57,2.97,4.47,6.79,7.93,11.46,10.38,4.66,2.46,9.52,4.41,14.58,5.87,5.05,1.46,9.9,2.76,14.53,3.9,4.63,1.14,8.41,2.58,11.33,4.33,2.92,1.75,4.41,4.27,4.48,7.56.06,2.96-1.25,5.21-3.93,6.75-2.69,1.54-6.66,2.36-11.93,2.47-6.59.14-12.62-.89-18.1-3.08-5.48-2.19-10.33-5.55-14.54-10.07l-18.85,19.91c4.05,4.53,8.82,8.34,14.32,11.44,5.5,3.1,11.52,5.48,18.06,7.16,6.54,1.67,13.18,2.44,19.94,2.3,14.48-.3,25.86-3.96,34.11-10.97,8.25-7.01,12.26-16.35,12.01-28.05-.15-7.24-1.72-13.14-4.69-17.69-2.98-4.55-6.76-8.17-11.34-10.88Z"/>
+        <polygon points="562.48 221.37 534.34 48.47 494.4 48.47 366.33 221.37 406.26 221.37 506.91 84.28 519 164.51 484.87 164.51 463.99 194.1 523.63 194.1 528.11 221.37 562.48 221.37"/>
+        <path d="M965.98,169.68c-10.34,12.89-26.19,21.17-43.96,21.17-31.08,0-56.37-25.29-56.37-56.37s25.29-56.37,56.37-56.37c17.77,0,33.62,8.28,43.96,21.17l23.48-23.48c-16.39-18.82-40.52-30.74-67.44-30.74-49.38,0-89.42,40.03-89.42,89.42s40.03,89.42,89.42,89.42c26.92,0,51.04-11.91,67.44-30.73l-23.48-23.48Z"/>
+        <path d="M1084.09,102.49c-4.61-1.89-9.8-2.84-15.56-2.84-13.34,0-23.55,4.24-30.63,12.72-.09.1-.16.22-.25.33v-10.58h-32.36v119.3h32.36v-65.95c0-8.89,2.18-15.52,6.55-19.88,4.36-4.36,10-6.55,16.92-6.55,3.29,0,6.21.49,8.77,1.48,2.55.99,4.73,2.47,6.55,4.45l20.25-23.22c-3.79-4.28-7.99-7.37-12.6-9.26Z"/>
+        <path d="M1191.19,113.5c-3.28-3.48-7.14-6.38-11.61-8.67-6.75-3.46-14.41-5.19-22.97-5.19-10.87,0-20.67,2.72-29.39,8.15-8.73,5.43-15.56,12.84-20.5,22.23-4.94,9.39-7.41,20.01-7.41,31.86s2.47,22.23,7.41,31.62c4.94,9.39,11.77,16.8,20.5,22.23,8.73,5.43,18.53,8.15,29.39,8.15,8.56,0,16.22-1.77,22.97-5.31,4.47-2.34,8.33-5.26,11.61-8.72v11.56h32.11v-119.3h-32.11v11.39ZM1184.52,184.99c-5.6,6.01-12.93,9.02-21.98,9.02-5.93,0-11.16-1.36-15.68-4.08-4.53-2.72-8.07-6.5-10.62-11.36-2.55-4.86-3.83-10.5-3.83-16.92s1.27-11.81,3.83-16.67c2.55-4.86,6.09-8.65,10.62-11.36,4.53-2.72,9.76-4.08,15.68-4.08s11.4,1.36,15.93,4.08c4.53,2.72,8.07,6.51,10.62,11.36,2.55,4.86,3.83,10.42,3.83,16.67,0,9.55-2.8,17.33-8.4,23.34Z"/>
+        <polygon points="1370.67 174.41 1345.82 102.12 1322.35 102.12 1297.5 174.41 1273.2 102.12 1240.59 102.12 1285.3 221.42 1308.52 221.42 1334.08 151.43 1359.65 221.42 1383.11 221.42 1427.58 102.12 1394.97 102.12 1370.67 174.41"/>
+        <rect x="1444.87" y="48.62" width="32.36" height="172.81"/>
+      </g>
+    </g>
+  </g>
+</svg>

data/examples/cdp.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+session = client.cdp.create(
+  idleTimeoutMs: 600_000,
+  maxSessionMs: 3_600_000,
+  browserSettings: {viewport: {width: 1440, height: 900}}
+)
+begin
+  version = client.cdp.get_version(session)
+  puts version["Browser"] || "Unknown browser"
+  puts "Connect a CDP-compatible Ruby library to session['cdpBaseUrl']."
+ensure
+  client.cdp.close(session["sessionId"])
+end

data/examples/cloud_browser.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "adscrawl"
+
+proxy_server = ENV.fetch("ADSCRAWL_PROXY_SERVER")
+client = AdsCrawl::Client.new
+launched = client.cloud_browsers.launch(
+  proxy: {server: proxy_server},
+  tabs: ["https://www.adscrawl.net"]
+)
+browser_id = launched["id"]
+begin
+  profile = client.cloud_browsers.get(browser_id)
+  puts "#{profile['id']} #{profile.dig('runtime', 'status')}"
+ensure
+  client.cloud_browsers.stop(browser_id)
+end

data/examples/extract.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "json"
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+result = client.spa.extract(
+  url: "https://www.adscrawl.net",
+  fields: {
+    title: {source: "dom", selector: "h1", value: "text", required: true}
+  }
+)
+puts JSON.pretty_generate(
+  title: result.dig("data", "title"),
+  missingFields: result["missingFields"]
+)

data/examples/fingerprint.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+server = ENV["ADSCRAWL_PROXY_SERVER"]
+username = ENV["ADSCRAWL_PROXY_USERNAME"]
+password = ENV["ADSCRAWL_PROXY_PASSWORD"]
+raise "Set both proxy username and password, or neither." if username.nil? != password.nil?
+raise "Set ADSCRAWL_PROXY_SERVER with proxy credentials." if server.nil? && (username || password)
+
+routing = {countryCode: "GLOBAL"}
+if server
+  proxy = {server: server}
+  proxy.merge!(username: username, password: password) if username && password
+  routing = {proxy: proxy}
+end
+
+url = ARGV[0] || "https://www.browserscan.net/"
+output = ARGV[1] || "browserscan.png"
+png = client.screenshot(
+  **routing,
+  url: url,
+  viewport: {width: 1440, height: 900},
+  fullPage: true,
+  waitUntil: "networkidle",
+  timeoutMs: 60_000,
+  userAgentMode: "random",
+  userAgentOs: "windows",
+  fingerprint: {
+    webRtc: "forward", webGl: "random", webGpu: "random",
+    webGlImage: "random", canvas: "random", audioContext: "random",
+    clientRects: "random", speechVoices: "random", fonts: "random",
+    hardware: "random", doNotTrack: "random"
+  },
+  timeout_ms: 75_000
+)
+File.binwrite(output, png)
+puts "Saved fingerprint-check screenshot to #{output}"

data/examples/markdown.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+url = ARGV[0] || "https://www.adscrawl.net"
+puts client.markdown(url: url, waitUntil: "domcontentloaded")

data/examples/screenshot.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "adscrawl"
+
+client = AdsCrawl::Client.new
+url = ARGV[0] || "https://www.adscrawl.net"
+output = ARGV[1] || "page.png"
+png = client.screenshot(url: url, fullPage: true)
+File.binwrite(output, png)
+puts "Saved screenshot to #{output}"

data/lib/adscrawl/client.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "socket"
+require "timeout"
+require "uri"
+
+require_relative "errors"
+require_relative "http_response"
+require_relative "service/spa"
+require_relative "service/cdp"
+require_relative "service/cloud_browsers"
+
+module AdsCrawl
+  class Client
+    DEFAULT_BASE_URL = "https://api.adscrawl.net"
+    DEFAULT_TIMEOUT_MS = 90_000
+    LAUNCH_TIMEOUT_MS = 195_000
+    MAX_TIMEOUT_MS = 2_147_483_647
+    MAX_BODY_BYTES = 64 * 1024 * 1024
+    PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b
+    RUNTIME_STATUSES = %w[starting running stopping stopped].freeze
+
+    attr_reader :spa, :cdp, :cloud_browsers
+    alias cloudBrowsers cloud_browsers
+
+    # Construction never performs a network request.
+    # A custom transport receives keyword arguments and returns HttpResponse.
+    def initialize(api_key: nil, base_url: nil, timeout_ms: nil, transport: nil)
+      selected_key = (api_key || ENV["ADSCRAWL_API_KEY"]).to_s.strip
+      raise ArgumentError, "Set ADSCRAWL_API_KEY or pass api_key to Client." if selected_key.empty?
+      raise ArgumentError, "api_key must not contain line breaks." if selected_key.match?(/[\r\n]/)
+
+      selected_url = base_url || ENV["ADSCRAWL_BASE_URL"] || ENV["ADSCRAWL_API_URL"] || DEFAULT_BASE_URL
+      @base_uri = validate_base_url(selected_url)
+      @base_url = selected_url.sub(%r{/+\z}, "")
+      @api_key = selected_key
+      @timeout_ms = validate_timeout(timeout_ms || DEFAULT_TIMEOUT_MS)
+      @custom_timeout = !timeout_ms.nil?
+      @transport = transport
+
+      @spa = Service::SPA.new(self)
+      @cdp = Service::CDP.new(self)
+      @cloud_browsers = Service::CloudBrowsers.new(self)
+    end
+
+    def html(options = nil, timeout_ms: nil, **keywords)
+      payload = options_hash(options, keywords)
+      validate_routing(payload)
+      body = send_request("POST", "/html", payload.merge("contentMode" => "html"), timeout_ms: timeout_ms)
+      raise ResponseError, "AdsCrawl returned empty page content." if body.strip.empty?
+
+      body.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def markdown(options = nil, timeout_ms: nil, **keywords)
+      payload = options_hash(options, keywords)
+      validate_routing(payload)
+      body = send_request("POST", "/html", payload.merge("contentMode" => "markdown"), timeout_ms: timeout_ms)
+      raise ResponseError, "AdsCrawl returned empty page content." if body.strip.empty?
+
+      body.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def article(options = nil, timeout_ms: nil, **keywords)
+      payload = options_hash(options, keywords)
+      validate_routing(payload)
+      request_json(
+        "POST",
+        "/html",
+        payload.merge("contentMode" => "json"),
+        timeout_ms: timeout_ms,
+        validate: lambda { |value|
+          string?(value, "title") && string?(value, "content") &&
+            string?(value, "textContent") && value["length"].is_a?(Numeric)
+        }
+      )
+    end
+
+    def screenshot(options = nil, timeout_ms: nil, **keywords)
+      payload = options_hash(options, keywords)
+      validate_routing(payload)
+      body = send_request("POST", "/screenshot", payload, timeout_ms: timeout_ms)
+      raise ResponseError, "AdsCrawl returned an invalid PNG screenshot." unless body.b.start_with?(PNG_SIGNATURE)
+
+      body.b
+    end
+
+    # Internal API used by service objects.
+    def send_request(method, path, body = nil, timeout_ms: nil, authenticate: true, extra_secrets: [])
+      deadline = validate_timeout(timeout_ms || @timeout_ms)
+      payload = body.nil? ? nil : normalize_hash(body)
+      secrets = [@api_key, *collect_secrets(payload), *extra_secrets].compact
+      encoded = payload.nil? ? nil : JSON.generate(payload)
+      headers = {"Accept" => "*/*", "User-Agent" => "adscrawl-ruby/#{VERSION}"}
+      headers["X-API-Key"] = @api_key if authenticate
+      headers["Content-Type"] = "application/json" unless encoded.nil?
+
+      response = if @transport
+        @transport.call(method: method, url: "#{@base_url}#{path}", headers: headers, body: encoded, timeout_ms: deadline)
+      else
+        net_http_request(method, "#{@base_url}#{path}", headers, encoded, deadline)
+      end
+      raise ResponseError, "The custom transport must return an AdsCrawl::HttpResponse." unless response.is_a?(HttpResponse)
+      raise ResponseError, "AdsCrawl response exceeds the 64 MiB safety limit." if response.body.bytesize > MAX_BODY_BYTES
+
+      status = Integer(response.status)
+      return response.body if status.between?(200, 299)
+
+      raise_api_error(status, response.body, response.headers || {}, secrets)
+    end
+
+    # Internal API used by service objects.
+    def request_json(method, path, body = nil, timeout_ms: nil, authenticate: true, validate: nil, extra_secrets: [])
+      raw = send_request(
+        method,
+        path,
+        body,
+        timeout_ms: timeout_ms,
+        authenticate: authenticate,
+        extra_secrets: extra_secrets
+      )
+      value = JSON.parse(raw)
+      raise ResponseError, "AdsCrawl returned invalid or unexpected JSON." unless value.is_a?(Hash)
+      if validate && !validate.call(value)
+        raise ResponseError, "AdsCrawl returned an unexpected JSON response shape."
+      end
+
+      value
+    rescue JSON::ParserError
+      raise ResponseError, "AdsCrawl returned invalid or unexpected JSON."
+    end
+
+    def launch_timeout_ms
+      @custom_timeout ? nil : LAUNCH_TIMEOUT_MS
+    end
+
+    def base_uri
+      @base_uri.dup
+    end
+
+    def normalize_hash(value)
+      raise ArgumentError, "options must be a Hash." unless value.is_a?(Hash)
+
+      normalize_value(value)
+    end
+
+    def options_hash(options, keywords)
+      if options && !keywords.empty?
+        raise ArgumentError, "Pass options as a Hash or keywords, not both."
+      end
+
+      normalize_hash(options || keywords)
+    end
+
+    def validate_routing(value)
+      return unless value.is_a?(Hash)
+
+      if value.key?("proxy") && !value["proxy"].nil? && value.key?("countryCode") && !value["countryCode"].to_s.empty?
+        raise ArgumentError, "proxy and countryCode cannot be combined."
+      end
+      validate_routing(value["browserSettings"]) if value["browserSettings"].is_a?(Hash)
+    end
+
+    def encode_id(value)
+      raise ArgumentError, "A non-empty resource id is required." unless value.is_a?(String) && !value.strip.empty? && !%w[. ..].include?(value)
+
+      URI.encode_www_form_component(value).tr("+", "%20")
+    end
+
+    def ok?(value)
+      value.is_a?(Hash) && value["ok"] == true
+    end
+
+    def session?(value)
+      value.is_a?(Hash) && string?(value, "sessionId") && string?(value, "expiresAt") && string?(value, "cdpBaseUrl")
+    end
+
+    def runtime?(value)
+      value.is_a?(Hash) && RUNTIME_STATUSES.include?(value["status"])
+    end
+
+    def cloud_browser?(value)
+      value.is_a?(Hash) && string?(value, "id") && runtime?(value["runtime"]) && value["browserSettings"].is_a?(Hash)
+    end
+
+    def page?(value)
+      value.is_a?(Hash) && string?(value, "url") && string?(value, "title")
+    end
+
+    def string?(value, key)
+      value.is_a?(Hash) && value[key].is_a?(String)
+    end
+
+    private
+
+    def validate_base_url(value)
+      uri = URI.parse(value.to_s)
+      unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+        raise ArgumentError, "base_url must be an HTTP(S) URL without credentials, query, or fragment."
+      end
+
+      uri
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url must be an HTTP(S) URL without credentials, query, or fragment."
+    end
+
+    def validate_timeout(value)
+      unless value.is_a?(Integer) && value.positive? && value <= MAX_TIMEOUT_MS
+        raise ArgumentError, "timeout_ms must be a positive Integer no greater than #{MAX_TIMEOUT_MS}."
+      end
+
+      value
+    end
+
+    def normalize_value(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), result| result[key.to_s] = normalize_value(item) }
+      when Array
+        value.map { |item| normalize_value(item) }
+      else
+        value
+      end
+    end
+
+    def net_http_request(method, url, headers, body, timeout_ms)
+      uri = URI.parse(url)
+      request_class = {
+        "GET" => Net::HTTP::Get,
+        "POST" => Net::HTTP::Post,
+        "DELETE" => Net::HTTP::Delete
+      }.fetch(method)
+      request = request_class.new(uri.request_uri, headers)
+      request.body = body unless body.nil?
+      timeout_seconds = timeout_ms / 1000.0
+      response_headers = {}
+      response_body = String.new(encoding: Encoding::BINARY)
+      status = nil
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = [timeout_seconds, 10.0].min
+      http.read_timeout = timeout_seconds
+      http.write_timeout = timeout_seconds if http.respond_to?(:write_timeout=)
+      http.request(request) do |response|
+        status = response.code.to_i
+        response.each_header { |name, value| response_headers[name.downcase] = value }
+        response.read_body do |chunk|
+          if response_body.bytesize + chunk.bytesize > MAX_BODY_BYTES
+            raise ResponseError, "AdsCrawl response exceeds the 64 MiB safety limit."
+          end
+          response_body << chunk.b
+        end
+      end
+
+      HttpResponse.new(status: status, headers: response_headers, body: response_body)
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error
+      raise TimeoutError, timeout_ms
+    rescue ResponseError
+      raise
+    rescue SocketError, OpenSSL::SSL::SSLError, EOFError, IOError, SystemCallError, URI::InvalidURIError
+      raise ConnectionError
+    end
+
+    def raise_api_error(status, raw, headers, secrets)
+      parsed = JSON.parse(raw)
+    rescue JSON::ParserError
+      parsed = raw.to_s
+    ensure
+      safe_body = redact_value(parsed, secrets)
+      message = "AdsCrawl API returned HTTP #{status}"
+      api_code = resource_id = trace_id = nil
+      if safe_body.is_a?(Hash)
+        message = safe_body["error"] if safe_body["error"].is_a?(String)
+        api_code = safe_body["code"] if safe_body["code"].is_a?(String)
+        resource_id = safe_body["id"] if safe_body["id"].is_a?(String)
+        trace_id = safe_body["traceId"] if safe_body["traceId"].is_a?(String)
+      end
+      normalized_headers = headers.each_with_object({}) { |(key, value), result| result[key.to_s.downcase] = value.to_s }
+      trace_id = redact_string(normalized_headers["x-trace-id"], secrets) if normalized_headers["x-trace-id"]
+      request_id = normalized_headers["x-request-id"] && redact_string(normalized_headers["x-request-id"], secrets)
+      raise APIError.new(
+        message.to_s.slice(0, 2048),
+        status: status,
+        api_code: api_code,
+        resource_id: resource_id,
+        trace_id: trace_id,
+        request_id: request_id,
+        body: safe_body
+      )
+    end
+
+    def collect_secrets(value, result = [])
+      case value
+      when Hash
+        value.each do |key, item|
+          if key == "cookies" && item.is_a?(Array)
+            item.each { |cookie| result << cookie["value"] if cookie.is_a?(Hash) && cookie["value"].is_a?(String) && !cookie["value"].empty? }
+          end
+          if %w[password username token controltoken].include?(key.downcase) && item.is_a?(String) && !item.empty?
+            result << item
+          end
+          collect_secrets(item, result)
+        end
+      when Array
+        value.each { |item| collect_secrets(item, result) }
+      end
+      result
+    end
+
+    def redact_string(value, secrets)
+      output = value.to_s.dup
+      secrets.each { |secret| output.gsub!(secret, "[REDACTED]") unless secret.to_s.empty? }
+      output.gsub!(/([?&](?:token|controlToken|apiKey|api_key)=)[^&#\s"<>]+/i, '\\1[REDACTED]')
+      output.gsub!(/(\b(?:https?|socks5):\/\/)[^\s\/@]+:[^\s\/@]+@/i, '\\1[REDACTED]@')
+      output
+    end
+
+    def redact_value(value, secrets)
+      case value
+      when String
+        redact_string(value, secrets)
+      when Array
+        value.map { |item| redact_value(item, secrets) }
+      when Hash
+        value.each_with_object({}) do |(key, item), result|
+          normalized = key.to_s.downcase.delete("-_")
+          result[key] = if %w[apikey xapikey authorization password username cookie cookies token controltoken websocketdebuggerurl cdpbaseurl controlurl connecturl].include?(normalized)
+            "[REDACTED]"
+          else
+            redact_value(item, secrets)
+          end
+        end
+      else
+        value
+      end
+    end
+  end
+end

data/lib/adscrawl/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AdsCrawl
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :status, :api_code, :resource_id, :trace_id, :request_id, :body
+
+    def initialize(message, status:, api_code: nil, resource_id: nil, trace_id: nil, request_id: nil, body: nil)
+      @status = status
+      @api_code = api_code
+      @resource_id = resource_id
+      @trace_id = trace_id
+      @request_id = request_id
+      @body = body
+      super(message)
+    end
+  end
+
+  class TimeoutError < Error
+    attr_reader :timeout_ms
+
+    def initialize(timeout_ms)
+      @timeout_ms = timeout_ms
+      super("AdsCrawl request timed out after #{timeout_ms}ms. Remote work may still be running; inspect sessions before retrying.")
+    end
+  end
+
+  class ConnectionError < Error
+    def initialize
+      super("Unable to complete the AdsCrawl request. Check your network and service availability.")
+    end
+  end
+
+  class ResponseError < Error; end
+end

data/lib/adscrawl/http_response.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AdsCrawl
+  # Public so custom transports can return a response without depending on internals.
+  HttpResponse = Struct.new(:status, :headers, :body, keyword_init: true)
+end

data/lib/adscrawl/service/cdp.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module AdsCrawl
+  module Service
+    class CDP
+      def initialize(client)
+        @client = client
+      end
+
+      def create(options = nil, timeout_ms: nil, **keywords)
+        payload = @client.options_hash(options, keywords)
+        @client.validate_routing(payload)
+        @client.request_json(
+          "POST",
+          "/cdp/sessions",
+          payload,
+          timeout_ms: timeout_ms,
+          validate: ->(value) { @client.session?(value) }
+        )
+      end
+
+      def list(timeout_ms: nil)
+        @client.request_json(
+          "GET",
+          "/cdp/sessions",
+          timeout_ms: timeout_ms,
+          validate: lambda { |value|
+            @client.ok?(value) && value["data"].is_a?(Array) && value["data"].all? { |session| @client.session?(session) }
+          }
+        )
+      end
+
+      def close(session_id, timeout_ms: nil)
+        id = @client.encode_id(session_id)
+        @client.request_json(
+          "DELETE",
+          "/cdp/sessions/#{id}",
+          timeout_ms: timeout_ms,
+          validate: ->(value) { @client.ok?(value) }
+        )
+      end
+
+      # Discovers the WebSocket endpoint without forwarding the API key.
+      def get_version(session, timeout_ms: nil)
+        payload = @client.normalize_hash(session)
+        session_id = payload["sessionId"]
+        cdp_base_url = payload["cdpBaseUrl"]
+        unless session_id.is_a?(String) && cdp_base_url.is_a?(String)
+          raise ArgumentError, "The session must contain sessionId and a valid cdpBaseUrl."
+        end
+
+        id = @client.encode_id(session_id)
+        parsed = URI.parse(cdp_base_url)
+        base = @client.base_uri
+        token = URI.decode_www_form(parsed.query.to_s).to_h["token"]
+        expected_path = "#{base.path.to_s.sub(%r{/+\z}, "")}/cdp/sessions/#{id}"
+        unless parsed.scheme == base.scheme && parsed.host == base.host && parsed.port == base.port &&
+            parsed.path.sub(%r{/+\z}, "") == expected_path && !parsed.userinfo && !parsed.fragment &&
+            token.is_a?(String) && !token.empty?
+          raise ArgumentError, "cdpBaseUrl must belong to this API origin and session and include a data token."
+        end
+
+        path = "/cdp/sessions/#{id}/json/version?#{URI.encode_www_form(token: token)}"
+        @client.request_json(
+          "GET",
+          path,
+          timeout_ms: timeout_ms,
+          authenticate: false,
+          extra_secrets: [token],
+          validate: ->(value) { @client.string?(value, "Browser") && @client.string?(value, "webSocketDebuggerUrl") }
+        )
+      rescue URI::InvalidURIError, ArgumentError => error
+        raise error if error.message.start_with?("cdpBaseUrl")
+
+        raise ArgumentError, "The session must contain sessionId and a valid cdpBaseUrl."
+      end
+
+      def live_token(session_id, timeout_ms: nil)
+        @client.encode_id(session_id)
+        @client.request_json(
+          "POST",
+          "/cdp/live-token",
+          {"sessionId" => session_id},
+          timeout_ms: timeout_ms,
+          validate: lambda { |value|
+            @client.ok?(value) && @client.string?(value, "controlUrl") && value["expiresAt"].is_a?(Numeric)
+          }
+        )
+      end
+    end
+  end
+end

data/lib/adscrawl/service/cloud_browsers.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module AdsCrawl
+  module Service
+    class CloudBrowsers
+      def initialize(client)
+        @client = client
+      end
+
+      def list(options = nil, timeout_ms: nil, **keywords)
+        payload = @client.options_hash(options, keywords)
+        query = payload.slice("page", "pageSize")
+        path = query.empty? ? "/cloud-browsers" : "/cloud-browsers?#{URI.encode_www_form(query)}"
+        @client.request_json(
+          "GET",
+          path,
+          timeout_ms: timeout_ms,
+          validate: lambda { |value|
+            @client.ok?(value) && value["data"].is_a?(Array) &&
+              value["data"].all? { |browser| @client.cloud_browser?(browser) } &&
+              value["pagination"].is_a?(Hash) &&
+              %w[limit runningLimit runningCount].all? { |key| value[key].is_a?(Integer) }
+          }
+        )
+      end
+
+      def create(options = nil, timeout_ms: nil, **keywords)
+        payload = @client.options_hash(options, keywords)
+        @client.validate_routing(payload)
+        @client.request_json(
+          "POST",
+          "/cloud-browsers",
+          payload,
+          timeout_ms: timeout_ms,
+          validate: ->(value) { @client.ok?(value) && @client.string?(value, "id") }
+        )
+      end
+
+      def get(browser_id, timeout_ms: nil)
+        id = @client.encode_id(browser_id)
+        @client.request_json(
+          "GET",
+          "/cloud-browsers/#{id}",
+          timeout_ms: timeout_ms,
+          validate: ->(value) { @client.cloud_browser?(value) }
+        )
+      end
+
+      def start(browser_id, options = nil, timeout_ms: nil, **keywords)
+        id = @client.encode_id(browser_id)
+        payload = require_proxy(@client.options_hash(options, keywords), "starts")
+        @client.request_json(
+          "POST",
+          "/cloud-browsers/#{id}/start",
+          payload,
+          timeout_ms: timeout_ms,
+          validate: ->(value) { @client.ok?(value) && @client.runtime?(value["runtime"]) }
+        )
+      end
+
+      def stop(browser_id, timeout_ms: nil)
+        id = @client.encode_id(browser_id)
+        @client.request_json(
+          "POST",
+          "/cloud-browsers/#{id}/stop",
+          timeout_ms: timeout_ms,
+          validate: ->(value) { @client.ok?(value) && @client.runtime?(value["runtime"]) }
+        )
+      end
+
+      def launch(options = nil, timeout_ms: nil, **keywords)
+        payload = require_proxy(@client.options_hash(options, keywords), "launches")
+        deadline = timeout_ms || @client.launch_timeout_ms
+        @client.request_json(
+          "POST",
+          "/cloud-browsers/launch",
+          payload,
+          timeout_ms: deadline,
+          validate: lambda { |value|
+            @client.ok?(value) && @client.string?(value, "id") && value["source"] == "launch" &&
+              value["deleteOnStop"] == false && @client.runtime?(value["runtime"])
+          }
+        )
+      end
+
+      private
+
+      def require_proxy(options, action)
+        payload = @client.normalize_hash(options)
+        unless payload["proxy"].is_a?(Hash)
+          raise ArgumentError, "Cloud browser #{action} require an explicit top-level proxy."
+        end
+
+        payload
+      end
+    end
+  end
+end

data/lib/adscrawl/service/spa.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AdsCrawl
+  module Service
+    class SPA
+      def initialize(client)
+        @client = client
+      end
+
+      def templates(timeout_ms: nil)
+        @client.request_json(
+          "GET",
+          "/spa-extract/templates",
+          timeout_ms: timeout_ms,
+          validate: lambda { |value|
+            value["templates"].is_a?(Array) && value["templates"].all? do |template|
+              @client.string?(template, "id") && @client.string?(template, "name")
+            end
+          }
+        )
+      end
+
+      def extract(options = nil, timeout_ms: nil, **keywords)
+        payload = @client.options_hash(options, keywords)
+        @client.validate_routing(payload)
+        @client.request_json(
+          "POST",
+          "/spa-extract",
+          payload.merge("mode" => "extract"),
+          timeout_ms: timeout_ms,
+          validate: lambda { |value|
+            value["mode"] == "extract" && @client.page?(value["page"]) &&
+              value["data"].is_a?(Hash) && value["missingFields"].is_a?(Array)
+          }
+        )
+      end
+
+      def inspect(options = nil, timeout_ms: nil, **keywords)
+        payload = @client.options_hash(options, keywords)
+        @client.validate_routing(payload)
+        @client.request_json(
+          "POST",
+          "/spa-extract",
+          payload.merge("mode" => "inspect"),
+          timeout_ms: timeout_ms,
+          validate: lambda { |value|
+            value["mode"] == "inspect" && @client.page?(value["page"]) &&
+              value["candidates"].is_a?(Hash) && value["suggestedPlan"].is_a?(Hash)
+          }
+        )
+      end
+    end
+  end
+end

data/lib/adscrawl/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AdsCrawl
+  VERSION = "0.1.0"
+end

data/lib/adscrawl.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "adscrawl/version"
+require_relative "adscrawl/client"

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: adscrawl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AdsCrawl
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Render pages in real browsers, extract structured data, capture screenshots,
+  open CDP sessions, and manage cloud browsers.
+email:
+- support@adscrawl.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- README.zh-CN.md
+- RELEASING.md
+- assets/adscrawl-logo.svg
+- examples/cdp.rb
+- examples/cloud_browser.rb
+- examples/extract.rb
+- examples/fingerprint.rb
+- examples/markdown.rb
+- examples/screenshot.rb
+- lib/adscrawl.rb
+- lib/adscrawl/client.rb
+- lib/adscrawl/errors.rb
+- lib/adscrawl/http_response.rb
+- lib/adscrawl/service/cdp.rb
+- lib/adscrawl/service/cloud_browsers.rb
+- lib/adscrawl/service/spa.rb
+- lib/adscrawl/version.rb
+homepage: https://www.adscrawl.net
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  bug_tracker_uri: https://github.com/AdsCrawl/adscrawl-ruby/issues
+  changelog_uri: https://github.com/AdsCrawl/adscrawl-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://www.adscrawl.net/docs/
+  homepage_uri: https://www.adscrawl.net
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/AdsCrawl/adscrawl-ruby
+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: Official Ruby SDK for the AdsCrawl browser and extraction API
+test_files: []