From f5e09f2d8ab69f56dc4f02ea71738ee27275a509 Mon Sep 17 00:00:00 2001
From: Techulus Agent <agent@techulus.com>
Date: Wed, 17 Jun 2026 23:11:53 +1000
Subject: [PATCH] Document CDP session support

---
 README.md            | 15 +++++++++++++++
 spec/capture_spec.rb | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/README.md b/README.md
index deb096f..30aadd5 100644
--- a/README.md
+++ b/README.md
@@ -145,6 +145,21 @@ screenshot = client.sessions.action(session_id, "screenshot", "fullPage" => true
 client.sessions.close(session_id)
 ```
 
+### CDP Sessions
+
+Pass `"cdp" => true` when creating a browser session to get a Chrome DevTools Protocol connection URL in the response.
+
+```ruby
+session = client.sessions.create(
+  "maxTtlSeconds" => 300,
+  "cdp" => true
+)
+
+connect_url = session["session"]["connect_url"] || session["session"]["connectUrl"]
+```
+
+CDP sessions cannot be combined with `proxy` or `bypassBotDetection`.
+
 ## Configuration Options
 
 ### Constructor Options
diff --git a/spec/capture_spec.rb b/spec/capture_spec.rb
index ecce554..adbd6b9 100644
--- a/spec/capture_spec.rb
+++ b/spec/capture_spec.rb
@@ -221,6 +221,42 @@ def initialize(body)
       expect(Net::HTTP).to have_received(:start).with("edge.test", 443, use_ssl: true)
     end
 
+    it "creates a CDP session with cdp enabled" do
+      stub_const("Capture::EDGE_URL", "https://edge.test")
+      client = Capture.new("user_123", "secret")
+      requests = []
+      http = double("http")
+      response = FakeSessionSuccess.new("201", JSON.generate(
+        "success" => true,
+        "session" => {
+          "id" => "sess_cdp",
+          "status" => "active",
+          "connectUrl" => "wss://edge.capture.page/v1/sessions/sess_cdp/cdp"
+        }
+      ))
+
+      allow(http).to receive(:request) do |request|
+        requests << request
+        response
+      end
+      allow(Net::HTTP).to receive(:start).and_yield(http)
+
+      result = client.sessions.create("maxTtlSeconds" => 300, "cdp" => true)
+
+      expect(result).to eq(
+        "success" => true,
+        "session" => {
+          "id" => "sess_cdp",
+          "status" => "active",
+          "connectUrl" => "wss://edge.capture.page/v1/sessions/sess_cdp/cdp"
+        }
+      )
+      expect(requests.first).to be_a(Net::HTTP::Post)
+      expect(requests.first["Authorization"]).to eq("Bearer dXNlcl8xMjM6c2VjcmV0")
+      expect(requests.first["Content-Type"]).to eq("application/json")
+      expect(JSON.parse(requests.first.body)).to eq("maxTtlSeconds" => 300, "cdp" => true)
+    end
+
     it "gets, closes, and executes actions against session paths" do
       stub_const("Capture::EDGE_URL", "https://edge.test")
       client = Capture.new("user_123", "secret")