1import { EventEmitter } from "node:events";
2import WebSocket from "ws";
3 
4type JsonObject = Record<string, unknown>;
5 
6interface CdpPendingCommand {
7  resolve(value: unknown): void;
8  reject(error: unknown): void;
9  method: string;
10}
11 
12interface CdpErrorShape {
13  message?: string;
14}
15 
16interface CdpCommandResult<T> {
17  result?: T;
18  error?: CdpErrorShape;
19}
20 
21interface CreatePageSessionOptions {
22  initialUrl?: string;
23  visible?: boolean;
24}
25 
26export class TargetSession extends EventEmitter {
27  constructor(
28    private readonly client: CdpClient,
29    public readonly targetId: string,
30    public readonly sessionId: string,
31  ) {
32    super();
33  }
34 
35  async send<T>(method: string, params: JsonObject = {}): Promise<T> {
36    return this.client.sendSessionCommand<T>(this.sessionId, method, params);
37  }
38 
39  handleEvent(method: string, params: JsonObject): void {
40    this.emit(method, params);
41    this.emit("event", { method, params });
42  }
43 
44  async waitForEvent<T extends JsonObject>(
45    method: string,
46    predicate?: (params: T) => boolean,
47    timeoutMs = 30_000,
48  ): Promise<T> {
49    return new Promise<T>((resolve, reject) => {
50      const timeout = setTimeout(() => {
51        this.off(method, listener);
52        reject(new Error(`Timed out waiting for ${method}`));
53      }, timeoutMs);
54 
55      const listener = (params: T): void => {
56        if (predicate && !predicate(params)) {
57          return;
58        }
59        clearTimeout(timeout);
60        this.off(method, listener);
61        resolve(params);
62      };
63 
64      this.on(method, listener);
65    });
66  }
67}
68 
69export class CdpClient {
70  private readonly ws: WebSocket;
71  private readonly pending = new Map<number, CdpPendingCommand>();
72  private readonly sessions = new Map<string, TargetSession>();
73  private nextId = 1;
74 
75  private constructor(ws: WebSocket) {
76    this.ws = ws;
77    this.ws.on("message", (raw) => {
78      this.handleMessage(raw.toString());
79    });
80  }
81 
82  static async connect(browserWsUrl: string): Promise<CdpClient> {
83    const ws = await new Promise<WebSocket>((resolve, reject) => {
84      const socket = new WebSocket(browserWsUrl);
85      socket.once("open", () => resolve(socket));
86      socket.once("error", (error) => reject(error));
87    });
88 
89    return new CdpClient(ws);
90  }
91 
92  private handleMessage(rawMessage: string): void {
93    const message = JSON.parse(rawMessage) as {
94      id?: number;
95      sessionId?: string;
96      method?: string;
97      params?: JsonObject;
98      result?: unknown;
99      error?: CdpErrorShape;
100    };
101 
102    if (typeof message.id === "number") {
103      const pending = this.pending.get(message.id);
104      if (!pending) {
105        return;
106      }
107      this.pending.delete(message.id);
108      if (message.error) {
109        pending.reject(new Error(`${pending.method}: ${message.error.message ?? "Unknown CDP error"}`));
110        return;
111      }
112      pending.resolve(message.result);
113      return;
114    }
115 
116    if (typeof message.sessionId === "string" && typeof message.method === "string") {
117      const session = this.sessions.get(message.sessionId);
118      if (session) {
119        session.handleEvent(message.method, (message.params ?? {}) as JsonObject);
120      }
121    }
122  }
123 
124  private async sendCommand<T>(
125    method: string,
126    params: JsonObject = {},
127    sessionId?: string,
128  ): Promise<T> {
129    const id = this.nextId;
130    this.nextId += 1;
131 
132    const payload = sessionId ? { id, method, params, sessionId } : { id, method, params };
133 
134    const result = new Promise<T>((resolve, reject) => {
135      this.pending.set(id, {
136        resolve: (value) => resolve(value as T),
137        reject,
138        method,
139      });
140    });
141 
142    this.ws.send(JSON.stringify(payload));
143    return result;
144  }
145 
146  async sendBrowserCommand<T>(method: string, params: JsonObject = {}): Promise<T> {
147    return this.sendCommand<T>(method, params);
148  }
149 
150  async sendSessionCommand<T>(sessionId: string, method: string, params: JsonObject = {}): Promise<T> {
151    return this.sendCommand<T>(method, params, sessionId);
152  }
153 
154  private async createPageTarget(initialUrl: string, visible = false): Promise<{ targetId: string }> {
155    const attempts: JsonObject[] = visible
156      ? [
157          {
158            url: initialUrl,
159            newWindow: true,
160            focus: true,
161          },
162          {
163            url: initialUrl,
164            focus: true,
165          },
166          {
167            url: initialUrl,
168          },
169        ]
170      : [
171          {
172            url: initialUrl,
173            hidden: true,
174          },
175          {
176            url: initialUrl,
177            background: true,
178            focus: false,
179          },
180          {
181            url: initialUrl,
182          },
183        ];
184 
185    let lastError: unknown;
186 
187    for (const params of attempts) {
188      try {
189        return await this.sendBrowserCommand<{ targetId: string }>("Target.createTarget", params);
190      } catch (error) {
191        lastError = error;
192      }
193    }
194 
195    throw lastError instanceof Error ? lastError : new Error("Target.createTarget failed");
196  }
197 
198  async createPageSession(options: CreatePageSessionOptions = {}): Promise<TargetSession> {
199    const initialUrl = options.initialUrl ?? "about:blank";
200    const created = await this.createPageTarget(initialUrl, Boolean(options.visible));
201    const attached = await this.sendBrowserCommand<{ sessionId: string }>("Target.attachToTarget", {
202      targetId: created.targetId,
203      flatten: true,
204    });
205 
206    const session = new TargetSession(this, created.targetId, attached.sessionId);
207    this.sessions.set(attached.sessionId, session);
208 
209    if (options.visible) {
210      await this.sendBrowserCommand("Target.activateTarget", {
211        targetId: created.targetId,
212      }).catch(() => {});
213    }
214 
215    await session.send("Page.enable");
216    await session.send("Runtime.enable");
217    await session.send("DOM.enable");
218 
219    if (options.visible) {
220      await session.send("Page.bringToFront").catch(() => {});
221    }
222 
223    return session;
224  }
225 
226  async closeTarget(targetId: string): Promise<void> {
227    try {
228      await this.sendBrowserCommand("Target.closeTarget", { targetId });
229    } catch {
230      // Target may already be gone.
231    }
232  }
233 
234  async close(): Promise<void> {
235    await new Promise<void>((resolve) => {
236      if (this.ws.readyState === WebSocket.CLOSED) {
237        resolve();
238        return;
239      }
240      this.ws.once("close", () => resolve());
241      this.ws.close();
242    });
243  }
244}
245 
246export async function evaluateRuntime<T>(session: TargetSession, expression: string): Promise<T> {
247  const response = await session.send<CdpCommandResult<{ value?: T; description?: string }>>("Runtime.evaluate", {
248    expression,
249    awaitPromise: true,
250    returnByValue: true,
251  });
252 
253  if (response.error) {
254    throw new Error(response.error.message ?? "Runtime.evaluate failed");
255  }
256 
257  return (response.result?.value as T | undefined) ?? (undefined as T);
258}
259