browserscale-ts 1.5.0 → 1.7.0

package/dist/scripts.js

@@ -0,0 +1,234 @@
+import { BrowserScaleError } from "./errors.js";
+/** @internal Converts one log entry off the wire. */
+export function scriptLogEntryFromProto(e) {
+    return {
+        level: e.level,
+        message: e.message,
+        timestamp: new Date(Number(e.timestamp)),
+    };
+}
+/**
+ * @internal Converts one stream item, or returns null for an event carrying
+ * neither variant — which a newer server could send and an older client should
+ * ignore rather than report as an empty log line.
+ */
+export function scriptEventFromProto(event) {
+    const payload = event.event;
+    if (payload.case === "log") {
+        if (!payload.value.line)
+            return null;
+        return {
+            runId: payload.value.runId,
+            log: scriptLogEntryFromProto(payload.value.line),
+        };
+    }
+    if (payload.case === "finished") {
+        return {
+            runId: payload.value.runId,
+            finished: {
+                success: payload.value.success,
+                result: payload.value.result,
+                stopped: payload.value.stopped,
+            },
+        };
+    }
+    return null;
+}
+/**
+ * ScriptRun is a script running in the background, returned by
+ * {@link CloudBrowser.startScript}. Its output is delivered to the handler
+ * passed there; this handle exists to await the outcome and to cancel the run.
+ */
+export class ScriptRun {
+    /** @internal Constructed by CloudBrowser; not part of the public API. */
+    constructor(init) {
+        this.detached = false;
+        this.failure = null;
+        this.droppedCount = 0;
+        this.result = null;
+        this.id = init.runId;
+        this.abort = init.abort;
+        this.cancel = init.cancel;
+        this.endedPromise = new Promise((resolve) => {
+            this.ended = resolve;
+        });
+        this.finished = this.pump(init.stream, init.onEvent);
+    }
+    /**
+     * The id the browser gave this run. Pass it to
+     * {@link CloudBrowser.stopScripts} to cancel the run from elsewhere, or to
+     * {@link CloudBrowser.followScript} to watch it from another tab.
+     */
+    get runId() {
+        return this.id;
+    }
+    /**
+     * Reads the stream and calls the handler for each event belonging to this
+     * run. Filtering happens here rather than server-side because the
+     * subscription had to exist before the run id did.
+     *
+     * It never rejects: a failure is recorded for {@link ScriptRun.error}
+     * instead, so nothing surfaces as an unhandled rejection.
+     */
+    async pump(stream, onEvent) {
+        try {
+            for await (const message of stream) {
+                if (message.dropped > 0n) {
+                    this.droppedCount = Number(message.dropped);
+                }
+                const event = scriptEventFromProto(message);
+                if (!event || event.runId !== this.id)
+                    continue;
+                onEvent(event);
+                if (event.finished) {
+                    this.result = event.finished;
+                    this.ended();
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            // Cancelling is how stop() and detach() end the stream, so the resulting
+            // error is expected rather than a failure worth reporting.
+            if (!this.detached) {
+                this.failure = err instanceof Error ? err : new Error(String(err));
+            }
+        }
+        finally {
+            this.ended();
+        }
+    }
+    /**
+     * Why the stream ended: null while it is still open, and after a clean stop
+     * or the session ending normally.
+     */
+    get error() {
+        return this.failure;
+    }
+    /**
+     * How many events the server discarded because this reader fell behind.
+     * Anything above zero means the log has holes: make the handler cheaper, or
+     * have the script print less.
+     */
+    get dropped() {
+        return this.droppedCount;
+    }
+    /**
+     * Resolves once the run ends, with how it ended.
+     *
+     * A script that threw is an outcome, not an error: it resolves with
+     * `success: false`. It rejects when the run's fate is unknown — the stream
+     * broke or the session died before the script finished.
+     *
+     * @returns how the script ended
+     *
+     * @throws UNKNOWN_ERROR - the outcome could not be observed
+     */
+    async wait() {
+        await this.endedPromise;
+        if (this.result)
+            return this.result;
+        if (this.failure)
+            throw this.failure;
+        throw new BrowserScaleError("browserscale.ScriptRun.wait: stream ended before the run did");
+    }
+    /**
+     * Cancels the run and detaches this reader. Idempotent, and safe to call from
+     * a `finally`.
+     *
+     * A script that is executing is interrupted; one parked on an await unwinds
+     * at its next operation in the page. Either way the handler sees a `finished`
+     * with `stopped` set, unless the local reader is torn down first.
+     *
+     * @throws UNKNOWN_ERROR - the run could not be cancelled server-side; the
+     *   local reader is detached regardless
+     */
+    async stop() {
+        if (this.detached)
+            return;
+        this.detached = true;
+        try {
+            await this.cancel(this.id);
+        }
+        finally {
+            this.abort.abort();
+            await this.finished;
+        }
+    }
+    /**
+     * Stops reading this run's output without cancelling the run. The script
+     * keeps going with nobody watching, which is what makes a detached run
+     * outlive the page that started it.
+     */
+    async detach() {
+        if (this.detached)
+            return;
+        this.detached = true;
+        this.abort.abort();
+        await this.finished;
+    }
+}
+/**
+ * ScriptFollow is a read-only view of script output, returned by
+ * {@link CloudBrowser.followScript}.
+ */
+export class ScriptFollow {
+    /** @internal Constructed by CloudBrowser; not part of the public API. */
+    constructor(init) {
+        this.stopped = false;
+        this.failure = null;
+        this.droppedCount = 0;
+        this.abort = init.abort;
+        this.finished = this.pump(init.stream, init.onEvent);
+    }
+    async pump(stream, onEvent) {
+        try {
+            for await (const message of stream) {
+                if (message.dropped > 0n) {
+                    this.droppedCount = Number(message.dropped);
+                }
+                const event = scriptEventFromProto(message);
+                if (event)
+                    onEvent(event);
+            }
+        }
+        catch (err) {
+            if (!this.stopped) {
+                this.failure = err instanceof Error ? err : new Error(String(err));
+            }
+        }
+    }
+    /**
+     * Why the subscription ended: null while it is still open and after a clean
+     * stop.
+     */
+    get error() {
+        return this.failure;
+    }
+    /** How many events the server discarded because this reader fell behind. */
+    get dropped() {
+        return this.droppedCount;
+    }
+    /**
+     * Resolves once the subscription ends — {@link ScriptFollow.stop}, a dead
+     * session or a transport failure.
+     *
+     * @throws the transport failure that ended the subscription, if any
+     */
+    async wait() {
+        await this.finished;
+        if (this.failure)
+            throw this.failure;
+    }
+    /**
+     * Ends the subscription. Idempotent, and safe to call from a `finally`. It
+     * never cancels a run: other readers, and the script itself, are unaffected.
+     */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.abort.abort();
+        await this.finished;
+    }
+}

package/dist/types.d.ts

@@ -52,6 +52,115 @@ export interface InterceptedResponse {
     headers: Header[];
     body: string;
 }
+/**
+ * NetworkResourceType is the kind of load an exchange belongs to.
+ *
+ * Typed as a union with a `string` fallback so an exchange from a newer browser
+ * still carries its value through instead of failing to type. Note that
+ * `fetch()`, XMLHttpRequest and EventSource all report `"fetch"`: they are
+ * indistinguishable at the capture point.
+ */
+export type NetworkResourceType = "document" | "subframe" | "script" | "stylesheet" | "image" | "font" | "media" | "fetch" | "worker" | "manifest" | "object" | "csp-report" | "other" | (string & {});
+/**
+ * NetworkServedFrom says where an exchange's response came from.
+ * `"wrcStaticCache"` is browserscale's own static cache — see
+ * {@link CloudBrowser.setStaticPaths}.
+ */
+export type NetworkServedFrom = "network" | "cache" | "serviceWorker" | "wrcStaticCache" | "wrcSynthetic" | (string & {});
+/**
+ * NetworkExchange is one request together with the response it received, as
+ * reported by {@link CloudBrowser.captureNetwork}.
+ *
+ * A redirect chain arrives as one exchange per hop: the hops share `chainId` and
+ * count up `redirectIndex`, so a 302 and the request it points at are two
+ * exchanges, each with its own headers and status.
+ */
+export interface NetworkExchange {
+    /** Unique per hop. */
+    requestId: string;
+    /** Shared by every hop of one redirect chain. */
+    chainId: string;
+    /** 0 for the original request, incremented once per redirect followed. */
+    redirectIndex: number;
+    /** The frame that issued the request; empty for worker traffic. */
+    frameId: string;
+    /**
+     * Whether that frame runs in its own process. Capture happens in the browser
+     * process, so cross-process iframes are included.
+     */
+    isOopif: boolean;
+    resourceType: NetworkResourceType;
+    method: string;
+    url: string;
+    /** The origin that started the request; empty when the browser itself did. */
+    initiatorUrl: string;
+    requestHeaders: Header[];
+    /**
+     * Whether requestHeaders are the bytes actually sent — Cookie, User-Agent and
+     * Sec-* included — rather than what the page asked for before the network
+     * stack filled in the rest.
+     */
+    requestHeadersAreWire: boolean;
+    /**
+     * Inline body only. File and streamed uploads set requestBodyTruncated
+     * instead of appearing here.
+     */
+    requestBody: Uint8Array;
+    requestBodyTruncated: boolean;
+    /** False when the request failed before any response arrived; see error. */
+    hasResponse: boolean;
+    statusCode: number;
+    statusText: string;
+    mimeType: string;
+    /** Negotiated ALPN protocol, e.g. "h2" or "http/1.1". */
+    protocol: string;
+    remoteAddress: string;
+    servedFrom: NetworkServedFrom;
+    responseHeaders: Header[];
+    responseHeadersAreWire: boolean;
+    /**
+     * Populated only when body capture was requested for this URL and applied;
+     * check responseBodyCaptured to tell an empty body from an uncaptured one.
+     * Binary content does not survive the browser boundary intact — see
+     * {@link NetworkCaptureOptions.bodies}.
+     */
+    responseBody: Uint8Array;
+    responseBodyTruncated: boolean;
+    responseBodyCaptured: boolean;
+    /** Bytes on the wire, not body size; 0 for a response served from cache. */
+    encodedDataLength: number;
+    /** Net error name (e.g. "net::ERR_ABORTED"), empty on success. */
+    error: string;
+}
+/** How much of a response body a network capture keeps. */
+export type NetworkBodies = "none" | "text" | "all";
+/**
+ * Configures {@link CloudBrowser.captureNetwork}.
+ *
+ * There is deliberately no byte-cap option: buffer sizes bound memory on a
+ * machine shared with other sessions, so the server owns them.
+ */
+export interface NetworkCaptureOptions {
+    /**
+     * URL wildcards to capture; omit to capture every request the session makes.
+     * Prefix a pattern with "!" to exclude it, which is the short way to say
+     * "everything except this".
+     */
+    patterns?: string[];
+    /**
+     * Response-body capture. `"text"` keeps bodies whose MIME type is textual,
+     * `"all"` keeps every body — but binary payloads (images, fonts, video) do
+     * not cross the browser boundary intact, so prefer `"text"` unless you know
+     * the bodies are textual. Defaults to `"none"`, headers and status only.
+     */
+    bodies?: NetworkBodies;
+    /**
+     * Narrows body capture to a subset of the captured requests; omit to apply
+     * bodies to all of them. Use it to log every request but only keep the
+     * payloads you care about.
+     */
+    bodyPatterns?: string[];
+}
 /**
  * WaitResult is the outcome of a {@link CloudBrowser.wait} /
  * {@link CloudBrowser.waitForAny} call: which condition matched (index, in
@@ -269,6 +378,34 @@ export interface RentResponse {
     acceptLanguage: string;
     fingerprint: string;
 }
+/** BrowserInfo describes one running session, as `listBrowsers` reports it. */
+export interface BrowserInfo {
+    sessionId: string;
+    /**
+     * The endpoint this session is driven from — the same one rent returned. It is
+     * what makes a listed id usable: pass it to `connectSession`.
+     */
+    grpcUrl: string;
+    /** Unix seconds the session was rented at. */
+    startTime: number;
+    /** The rental length in seconds; 0 means unlimited. */
+    rentDuration: number;
+    /**
+     * Seconds left on the rental, and undefined for an unlimited one — there is
+     * nothing to count down.
+     */
+    remainingSeconds?: number;
+    countryCode: string;
+    timezone: string;
+    proxyHost: string;
+    /** The address the session egresses from. */
+    publicIp: string;
+    /**
+     * The physical card the session renders on, and undefined on a
+     * software-rendered host.
+     */
+    gpuIndex?: number;
+}
 /**
  * IceServer is one entry for a WebRTC `RTCPeerConnection`'s `iceServers`
  * config: a TURN (or STUN) URL plus the short-lived credentials to
@@ -282,6 +419,26 @@ export interface IceServer {
     /** Short-lived TURN REST credential (empty for plain STUN). */
     credential: string;
 }
+/**
+ * StreamAnswer is what {@link CloudBrowser.startStream} replies with.
+ */
+export interface StreamAnswer {
+    /** SDP answer to apply as your peer's remote description. */
+    answerSdp: string;
+    /**
+     * The page's viewport in CSS pixels — the coordinate space its input
+     * expects. The video may be displayed at any size, so map your pointer
+     * positions into this space before sending them. It comes back with the
+     * answer rather than from a separate {@link CloudBrowser.getPages} so it
+     * cannot race the stream or describe a different page, and the browser
+     * pushes `{"type":"viewport","width":W,"height":H}` on the reliable "input"
+     * data channel whenever it changes. Null against an older engine.
+     */
+    viewport: {
+        width: number;
+        height: number;
+    } | null;
+}
 /**
  * ReactionInfo describes a still-pending reaction, as returned by
  * {@link CloudBrowser.listReactions}. One-shot reactions that have already

package/dist/ws-transport.d.ts

@@ -3,13 +3,27 @@ import type { DescMessage, DescMethodUnary, DescMethodStreaming, MessageInitShap
 export declare class WebSocketTransport implements Transport {
     private ws;
     private pending;
+    private streams;
     private queue;
     private connected;
     private url;
     constructor(url: string);
     private connect;
+    private dispatchStreamFrame;
     private send;
+    /** Builds a request frame: [4B id LE][2B method_len LE][method][payload]. */
+    private static frame;
     unary<I extends DescMessage, O extends DescMessage>(method: DescMethodUnary<I, O>, signal: AbortSignal | undefined, _timeoutMs: number | undefined, _header: HeadersInit | undefined, input: MessageInitShape<I>, _contextValues?: ContextValues): Promise<UnaryResponse<I, O>>;
-    stream<I extends DescMessage, O extends DescMessage>(_method: DescMethodStreaming<I, O>, _signal: AbortSignal | undefined, _timeoutMs: number | undefined, _header: HeadersInit | undefined, _input: AsyncIterable<MessageInitShape<I>>, _contextValues?: ContextValues): Promise<StreamResponse<I, O>>;
+    /**
+     * Runs a server-streaming call. Client-streaming is not supported: the frame
+     * format carries exactly one request message, and no RPC needs more.
+     *
+     * Resolving means the server confirmed the subscription, so a caller may act
+     * on it — arm a network capture, say — without racing the first message.
+     */
+    stream<I extends DescMessage, O extends DescMessage>(method: DescMethodStreaming<I, O>, signal: AbortSignal | undefined, _timeoutMs: number | undefined, _header: HeadersInit | undefined, input: AsyncIterable<MessageInitShape<I>>, _contextValues?: ContextValues): Promise<StreamResponse<I, O>>;
+    private readStream;
+    /** Drops a stream locally and asks the server to stop producing. */
+    private cancelStream;
     close(): void;
 }

package/dist/ws-transport.js

@@ -1,9 +1,35 @@
 import { create, toBinary, fromBinary } from "@bufbuild/protobuf";
 let nextId = 0;
+/**
+ * Response frame status byte, mirroring the wsStatus constants in
+ * internal/bserver/ws_grpc_proxy.go.
+ */
+const STATUS_OK = 0;
+const STATUS_ERROR = 1;
+const STATUS_STREAM_MSG = 2;
+const STATUS_STREAM_END = 3;
+const STATUS_STREAM_READY = 4;
+/** Control frame method name; real gRPC methods always contain a "/". */
+const CANCEL = "cancel";
+function wake(stream) {
+    const pending = stream.wake;
+    stream.wake = null;
+    pending?.();
+}
+/**
+ * Fails a stream so its iterator stops instead of parking forever. Passing a
+ * null error ends it cleanly.
+ */
+function endStream(stream, err) {
+    stream.done = true;
+    stream.error = err;
+    wake(stream);
+}
 export class WebSocketTransport {
     constructor(url) {
         this.ws = null;
         this.pending = new Map();
+        this.streams = new Map();
         this.queue = [];
         this.connected = false;
         this.url = url;
@@ -27,11 +53,16 @@ export class WebSocketTransport {
             const id = view.getUint32(0, true);
             const status = buf[4];
             const payload = buf.slice(5);
+            const stream = this.streams.get(id);
+            if (stream) {
+                this.dispatchStreamFrame(id, stream, status, payload);
+                return;
+            }
             const call = this.pending.get(id);
             if (!call)
                 return;
             this.pending.delete(id);
-            if (status === 0) {
+            if (status === STATUS_OK) {
                 call.resolve(payload);
             }
             else {
@@ -44,12 +75,48 @@ export class WebSocketTransport {
                 call.reject(new Error("WebSocket closed"));
             }
             this.pending.clear();
+            // Streams cannot survive the socket: the reconnect below is a fresh
+            // connection the server knows nothing about. Callers that need to keep
+            // reading resubscribe — for a network capture the capture itself stays
+            // armed server-side, so only the gap is lost.
+            const closed = new Error("WebSocket closed");
+            for (const [, stream] of this.streams) {
+                stream.onReadyFailed?.(closed);
+                endStream(stream, closed);
+            }
+            this.streams.clear();
             setTimeout(() => this.connect(), 1000);
         };
         this.ws.onerror = () => {
             this.ws?.close();
         };
     }
+    dispatchStreamFrame(id, stream, status, payload) {
+        switch (status) {
+            case STATUS_STREAM_READY: {
+                const ready = stream.onReady;
+                stream.onReady = null;
+                stream.onReadyFailed = null;
+                ready?.();
+                return;
+            }
+            case STATUS_STREAM_MSG:
+                stream.queue.push(payload);
+                wake(stream);
+                return;
+            case STATUS_STREAM_END:
+                this.streams.delete(id);
+                endStream(stream, null);
+                return;
+            default: {
+                const err = new Error(new TextDecoder().decode(payload));
+                this.streams.delete(id);
+                stream.onReadyFailed?.(err);
+                endStream(stream, err);
+                return;
+            }
+        }
+    }
     send(data) {
         if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
             this.ws.send(data);
@@ -58,21 +125,25 @@ export class WebSocketTransport {
             this.queue.push(data);
         }
     }
-    async unary(method, signal, _timeoutMs, _header, input, _contextValues) {
-        const id = ++nextId;
-        const methodName = `${method.parent.typeName}/${method.name}`;
-        const inputMsg = create(method.input, input);
-        const payload = toBinary(method.input, inputMsg);
-        const methodBytes = new TextEncoder().encode(methodName);
+    /** Builds a request frame: [4B id LE][2B method_len LE][method][payload]. */
+    static frame(id, method, payload) {
+        const methodBytes = new TextEncoder().encode(method);
         const frame = new Uint8Array(6 + methodBytes.length + payload.length);
         const view = new DataView(frame.buffer);
         view.setUint32(0, id, true);
         view.setUint16(4, methodBytes.length, true);
         frame.set(methodBytes, 6);
         frame.set(payload, 6 + methodBytes.length);
+        return frame;
+    }
+    async unary(method, signal, _timeoutMs, _header, input, _contextValues) {
+        const id = ++nextId;
+        const methodName = `${method.parent.typeName}/${method.name}`;
+        const inputMsg = create(method.input, input);
+        const payload = toBinary(method.input, inputMsg);
         const responsePayload = await new Promise((resolve, reject) => {
             this.pending.set(id, { resolve, reject });
-            this.send(frame);
+            this.send(WebSocketTransport.frame(id, methodName, payload));
             if (signal) {
                 signal.addEventListener("abort", () => {
                     this.pending.delete(id);
@@ -90,8 +161,82 @@ export class WebSocketTransport {
             message: output,
         };
     }
-    async stream(_method, _signal, _timeoutMs, _header, _input, _contextValues) {
-        throw new Error("Streaming not supported over WebSocket transport");
+    /**
+     * Runs a server-streaming call. Client-streaming is not supported: the frame
+     * format carries exactly one request message, and no RPC needs more.
+     *
+     * Resolving means the server confirmed the subscription, so a caller may act
+     * on it — arm a network capture, say — without racing the first message.
+     */
+    async stream(method, signal, _timeoutMs, _header, input, _contextValues) {
+        let request;
+        for await (const msg of input) {
+            request = msg;
+            break;
+        }
+        if (request === undefined) {
+            throw new Error("WebSocket transport: server streaming needs one request message");
+        }
+        const id = ++nextId;
+        const methodName = `${method.parent.typeName}/${method.name}`;
+        const payload = toBinary(method.input, create(method.input, request));
+        const stream = {
+            queue: [],
+            wake: null,
+            done: false,
+            error: null,
+            onReady: null,
+            onReadyFailed: null,
+        };
+        this.streams.set(id, stream);
+        const ready = new Promise((resolve, reject) => {
+            stream.onReady = resolve;
+            stream.onReadyFailed = reject;
+        });
+        this.send(WebSocketTransport.frame(id, methodName, payload));
+        signal?.addEventListener("abort", () => this.cancelStream(id), { once: true });
+        await ready;
+        return {
+            stream: true,
+            service: method.parent,
+            method,
+            header: new Headers(),
+            trailer: new Headers(),
+            message: this.readStream(method, id, stream),
+        };
+    }
+    async *readStream(method, id, stream) {
+        try {
+            for (;;) {
+                while (stream.queue.length === 0 && !stream.done) {
+                    await new Promise((resolve) => {
+                        stream.wake = resolve;
+                    });
+                }
+                const buf = stream.queue.shift();
+                if (buf === undefined) {
+                    // Queue drained; a failure only surfaces once nothing is left.
+                    if (stream.error)
+                        throw stream.error;
+                    return;
+                }
+                yield fromBinary(method.output, buf);
+            }
+        }
+        finally {
+            // Reached on break/return/throw in the consumer too, so abandoning the
+            // loop stops the server rather than leaking the stream.
+            this.cancelStream(id);
+        }
+    }
+    /** Drops a stream locally and asks the server to stop producing. */
+    cancelStream(id) {
+        const stream = this.streams.get(id);
+        if (!stream)
+            return;
+        this.streams.delete(id);
+        endStream(stream, null);
+        this.send(WebSocketTransport.frame(id, CANCEL, new Uint8Array(0)));
     }
     close() {
         this.ws?.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browserscale-ts",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Official SDK for browserscale — undetected stealth browsers in the cloud. Rent real Chromium sessions with unique fingerprints, built-in proxies, captcha solving, human-like input and live video — scale web scraping and automation without running a single browser yourself.",
   "main": "dist/index.js",
   "type": "module",