browserscale-ts 1.8.0 → 1.10.0

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import { CloudBrowser } from "./client.ts";
 import { BrowserConfig } from "./config.ts";
-import type { BrowserInfo } from "./types.ts";
+import type { BrowserInfo, SessionUsage } from "./types.ts";
 export { CloudBrowser } from "./client.ts";
 export { BrowserConfig } from "./config.ts";
 export { Locator, css, js, node, at, AllFrames } from "./locator.ts";
 export { DefaultWaitTimeoutMs, DefaultVisible, DefaultSteadyMs, } from "./defaults.ts";
 export { BrowserScaleError, CommandError, ClickError, FillError, DragError, ScrollError, MoveError, SelectOptionError, WaitError, } from "./errors.ts";
-export type { Rect, FrameInfo, PageInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, NetworkResourceType, NetworkServedFrom, NetworkBodies, NetworkCaptureOptions, WaitResult, WaitConditionStatus, OccluderInfo, ElementRef, NavigateResult, EvaluateResult, ElementResult, DragResult, SelectOptionResult, ScreenshotResult, ReadCanvasResult, DOMResult, InspectResult, RentResponse, BrowserInfo, IceServer, StreamAnswer, ReactionInfo, } from "./types.ts";
+export type { Rect, FrameInfo, PageInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, NetworkResourceType, NetworkServedFrom, NetworkBodies, NetworkBody, NetworkBodyRange, NetworkCaptureOptions, WaitResult, WaitConditionStatus, OccluderInfo, ElementRef, NavigateResult, EvaluateResult, ElementResult, DragResult, SelectOptionResult, ScreenshotResult, ReadCanvasResult, DOMResult, InspectResult, RentResponse, BrowserInfo, SessionUsage, IceServer, StreamAnswer, ReactionInfo, } from "./types.ts";
 export type { Button, ClickAction, ClickOpts, FillOpts, ReactionOpts, SelectOpts, WaitOpts, WaitUntil, NavigateOpts, LoadHTMLOpts, GetDOMOpts, GetObservationOpts, ScreenshotOpts, ReadCanvasOpts, } from "./options.ts";
 export { type RequestPattern, type HeaderModification, type HeaderModificationAction, } from "./network.ts";
 export { ScriptRun, ScriptFollow, type ScriptEvent, type ScriptEventHandler, type ScriptFinished, type ScriptLogEntry, type ScriptResult, type ScriptRunInfo, } from "./scripts.ts";
@@ -88,13 +88,16 @@ export declare function connectSession(grpcUrl: string, apiKey: string, sessionI
  * @param apiKey - API key the session was rented with
  * @param sessionId - id of the session to release
  *
+ * @returns SessionUsage what the session consumed over its whole life;
+ *   undefined when the server could not report it
+ *
  * Rejects when the stop API refuses the request. Stopping a session that is
  * already gone is a no-op rather than a failure.
  *
  * @example
- * await stopBrowser(apiKey, sessionId);
+ * const usage = await stopBrowser(apiKey, sessionId);
  */
-export declare function stopBrowser(apiKey: string, sessionId: string): Promise<void>;
+export declare function stopBrowser(apiKey: string, sessionId: string): Promise<SessionUsage | undefined>;
 /**
  * Reports the sessions an API key currently holds.
  *

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createGrpcTransport } from "@connectrpc/connect-node";
 import { CloudBrowser } from "./client.js";
+import { sessionUsageFromJson } from "./internal/convert.js";
 // Public API ──────────────────────────────────────────────────────────
 export { CloudBrowser } from "./client.js";
 export { BrowserConfig } from "./config.js";
@@ -61,9 +62,7 @@ export async function rentBrowser(config) {
     const transport = createGrpcTransport({
         baseUrl: grpcBaseUrl(rentResp.grpcUrl),
     });
-    return new CloudBrowser(transport, rentResp.sessionId, config.apiKey, rentResp.fingerprint, async () => {
-        await callStopApi(config.apiKey, rentResp.sessionId);
-    });
+    return new CloudBrowser(transport, rentResp.sessionId, config.apiKey, rentResp.fingerprint, () => callStopApi(config.apiKey, rentResp.sessionId));
 }
 /**
  * Attaches to an already-rented session over a fresh gRPC connection.
@@ -90,9 +89,7 @@ export async function rentBrowser(config) {
  */
 export function connectSession(grpcUrl, apiKey, sessionId) {
     const transport = createGrpcTransport({ baseUrl: grpcBaseUrl(grpcUrl) });
-    return new CloudBrowser(transport, sessionId, apiKey, "", async () => {
-        await callStopApi(apiKey, sessionId);
-    });
+    return new CloudBrowser(transport, sessionId, apiKey, "", () => callStopApi(apiKey, sessionId));
 }
 /**
  * Releases a session without needing a {@link CloudBrowser} handle.
@@ -104,14 +101,17 @@ export function connectSession(grpcUrl, apiKey, sessionId) {
  * @param apiKey - API key the session was rented with
  * @param sessionId - id of the session to release
  *
+ * @returns SessionUsage what the session consumed over its whole life;
+ *   undefined when the server could not report it
+ *
  * Rejects when the stop API refuses the request. Stopping a session that is
  * already gone is a no-op rather than a failure.
  *
  * @example
- * await stopBrowser(apiKey, sessionId);
+ * const usage = await stopBrowser(apiKey, sessionId);
  */
 export async function stopBrowser(apiKey, sessionId) {
-    await callStopApi(apiKey, sessionId);
+    return await callStopApi(apiKey, sessionId);
 }
 /**
  * Reports the sessions an API key currently holds.
@@ -224,4 +224,5 @@ async function callStopApi(apiKey, sessionId) {
     if (!resp.ok || !data.success) {
         throw new Error(`stop failed: ${data.error ?? resp.statusText}`);
     }
+    return sessionUsageFromJson(data.usage);
 }

package/dist/internal/convert.d.ts

@@ -1,5 +1,5 @@
-import { type Rect as ProtoRect, type ClickResult as ProtoClickResult, type FillResult as ProtoFillResult, type MoveResult as ProtoMoveResult, type ScrollResult as ProtoScrollResult, type DragResult as ProtoDragResult, type SelectOptionResult as ProtoSelectOptionResult, type WaitResult as ProtoWaitResult, type FrameInfo as ProtoFrameInfo, type PageInfo as ProtoPageInfo, type Header as ProtoHeader, type InterceptedRequest as ProtoInterceptedRequest, type InterceptedResponse as ProtoInterceptedResponse, type NetworkExchange as ProtoNetworkExchange, type HeaderModification as ProtoHeaderModification, type CookieParam as ProtoCookieParam, type StorageOriginEntry as ProtoStorageOriginEntry, type AuthSession as ProtoAuthSession } from "../gen/wrc_pb.ts";
-import type { DragResult, ElementResult, FrameInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, PageInfo, Rect, SelectOptionResult, WaitResult } from "../types.ts";
+import { type Rect as ProtoRect, type ClickResult as ProtoClickResult, type FillResult as ProtoFillResult, type MoveResult as ProtoMoveResult, type ScrollResult as ProtoScrollResult, type DragResult as ProtoDragResult, type SelectOptionResult as ProtoSelectOptionResult, type WaitResult as ProtoWaitResult, type FrameInfo as ProtoFrameInfo, type PageInfo as ProtoPageInfo, type SessionUsage as ProtoSessionUsage, type Header as ProtoHeader, type InterceptedRequest as ProtoInterceptedRequest, type InterceptedResponse as ProtoInterceptedResponse, type NetworkExchange as ProtoNetworkExchange, type HeaderModification as ProtoHeaderModification, type CookieParam as ProtoCookieParam, type StorageOriginEntry as ProtoStorageOriginEntry, type AuthSession as ProtoAuthSession } from "../gen/wrc_pb.ts";
+import type { DragResult, ElementResult, FrameInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, PageInfo, Rect, SelectOptionResult, SessionUsage, WaitResult } from "../types.ts";
 import type { CookieParam } from "../cookies.ts";
 import type { StorageOriginEntry } from "../storage.ts";
 import type { AuthSession } from "../auth-session.ts";
@@ -36,6 +36,8 @@ export declare function unwrapSelect(r: ProtoSelectOptionResult): SelectOptionRe
 export declare function unwrapWait(r: ProtoWaitResult): WaitResult;
 export declare function frameInfoFromProto(f: ProtoFrameInfo): FrameInfo;
 export declare function pageInfoFromProto(p: ProtoPageInfo): PageInfo;
+export declare function sessionUsageFromProto(u: ProtoSessionUsage): SessionUsage;
+export declare function sessionUsageFromJson(v: unknown): SessionUsage | undefined;
 export declare function headerFromProto(h: ProtoHeader): Header;
 export declare function headersToProto(headers: Header[] | undefined): ProtoHeader[];
 export declare function interceptedRequestFromProto(r: ProtoInterceptedRequest | undefined): InterceptedRequest | null;

package/dist/internal/convert.js

@@ -228,6 +228,33 @@ export function pageInfoFromProto(p) {
             : {},
     };
 }
+export function sessionUsageFromProto(u) {
+    return {
+        wallTime: u.wallTime,
+        cpuTime: u.cpuTime,
+        minMemory: u.minMemory,
+        averageMemory: u.averageMemory,
+        peakMemory: u.peakMemory,
+        renderersUsed: u.renderersUsed,
+        framesCreated: u.framesCreated,
+    };
+}
+// The stop endpoint answers in JSON, with the same field names as SessionUsage.
+export function sessionUsageFromJson(v) {
+    if (!v || typeof v !== "object")
+        return undefined;
+    const u = v;
+    const num = (x) => (typeof x === "number" ? x : 0);
+    return {
+        wallTime: num(u.wallTime),
+        cpuTime: num(u.cpuTime),
+        minMemory: num(u.minMemory),
+        averageMemory: num(u.averageMemory),
+        peakMemory: num(u.peakMemory),
+        renderersUsed: num(u.renderersUsed),
+        framesCreated: num(u.framesCreated),
+    };
+}
 // ──────────────────────────────────────────────────────────────────────
 // Headers
 // ──────────────────────────────────────────────────────────────────────
@@ -279,7 +306,8 @@ export function networkExchangeFromProto(e) {
         initiatorUrl: e.initiatorUrl,
         requestHeaders: e.requestHeaders.map(headerFromProto),
         requestHeadersAreWire: e.requestHeadersAreWire,
-        requestBody: e.requestBody,
+        requestBodyId: e.requestBodyId,
+        requestBodySize: Number(e.requestBodySize),
         requestBodyTruncated: e.requestBodyTruncated,
         hasResponse: e.hasResponse,
         statusCode: e.statusCode,
@@ -290,9 +318,9 @@ export function networkExchangeFromProto(e) {
         servedFrom: e.servedFrom,
         responseHeaders: e.responseHeaders.map(headerFromProto),
         responseHeadersAreWire: e.responseHeadersAreWire,
-        responseBody: e.responseBody,
+        responseBodyId: e.responseBodyId,
+        responseBodySize: Number(e.responseBodySize),
         responseBodyTruncated: e.responseBodyTruncated,
-        responseBodyCaptured: e.responseBodyCaptured,
         encodedDataLength: Number(e.encodedDataLength),
         error: e.error,
     };

package/dist/network-capture.d.ts

@@ -52,8 +52,8 @@ export declare class NetworkCapture {
     get error(): Error | null;
     /**
      * How many exchanges the server discarded because this reader fell behind.
-     * Anything above zero means the log has holes: make the handler cheaper,
-     * narrow `patterns`, or stop capturing bodies.
+     * Anything above zero means the log has holes: make the handler cheaper or
+     * narrow `patterns`.
      */
     get dropped(): number;
     /**

package/dist/network-capture.js

@@ -57,8 +57,8 @@ export class NetworkCapture {
     }
     /**
      * How many exchanges the server discarded because this reader fell behind.
-     * Anything above zero means the log has holes: make the handler cheaper,
-     * narrow `patterns`, or stop capturing bodies.
+     * Anything above zero means the log has holes: make the handler cheaper or
+     * narrow `patterns`.
      */
     get dropped() {
         return this.droppedCount;

package/dist/types.d.ts

@@ -26,6 +26,46 @@ export interface PageInfo {
     viewport: Rect;
     frameTree: FrameInfo;
 }
+/**
+ * SessionUsage is what a session's browser has consumed since the session
+ * started: the CPU time and memory of every process that rendered its pages —
+ * main frames, cross-site iframes and the workers they host — including
+ * processes that have since exited. Work done on the session's behalf in
+ * processes it shares with other sessions is not included.
+ *
+ * {@link CloudBrowser.getUsage} reports it while the session runs, and
+ * {@link CloudBrowser.stopBrowser} resolves with the final figures, so there is
+ * no need to read it right before stopping.
+ */
+export interface SessionUsage {
+    /** Real time since the session's browser was created, in seconds. */
+    wallTime: number;
+    /**
+     * User plus kernel CPU time in seconds. Only time a thread actually ran on a
+     * core counts; waiting and idling do not.
+     */
+    cpuTime: number;
+    /**
+     * The least memory the session held once its browser was ready, in bytes.
+     * Sampled about once a second.
+     */
+    minMemory: number;
+    /**
+     * The memory held, averaged over wallTime, in bytes; averageMemory * wallTime
+     * is the memory-time used. Sampled about once a second, so short spikes count
+     * toward the peak but barely toward the average.
+     */
+    averageMemory: number;
+    /** The most memory held at any one moment, in bytes. */
+    peakMemory: number;
+    /**
+     * Renderer processes that hosted at least one of the session's frames: one
+     * per site its pages and cross-site iframes needed.
+     */
+    renderersUsed: number;
+    /** Child frames created in the session's pages, whether or not they got a process of their own. */
+    framesCreated: number;
+}
 /** Header is a single HTTP header (name/value pair) on an intercepted request or response. */
 export interface Header {
     name: string;
@@ -102,10 +142,16 @@ export interface NetworkExchange {
      */
     requestHeadersAreWire: boolean;
     /**
-     * Inline body only. File and streamed uploads set requestBodyTruncated
-     * instead of appearing here.
+     * Names the request body; read it with {@link CloudBrowser.readNetworkBody}.
+     * Empty when the request had no body. Bodies never travel with the exchange.
+     */
+    requestBodyId: string;
+    /** Bytes kept for the request body. */
+    requestBodySize: number;
+    /**
+     * Part of the request body is missing: it hit the per-body cap, or it was a
+     * file or streamed upload, which are not kept.
      */
-    requestBody: Uint8Array;
     requestBodyTruncated: boolean;
     /** False when the request failed before any response arrived; see error. */
     hasResponse: boolean;
@@ -119,26 +165,49 @@ export interface NetworkExchange {
     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
+     * Names the response body; read it with {@link CloudBrowser.readNetworkBody}.
+     * Empty when body capture did not apply to this exchange — see
      * {@link NetworkCaptureOptions.bodies}.
      */
-    responseBody: Uint8Array;
+    responseBodyId: string;
+    /** Bytes kept for the response body, after content decoding. */
+    responseBodySize: number;
+    /**
+     * The kept body is shorter than the one the page received: it hit the
+     * per-body cap or the load ended early.
+     */
     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. */
+/** One range of a captured body, from {@link CloudBrowser.readNetworkBodyRange}. */
+export interface NetworkBodyRange {
+    /** The bytes read; empty past the end of the body. */
+    data: Uint8Array;
+    /** Bytes kept for the body as a whole. */
+    totalSize: number;
+    /** Matches the exchange's truncated flag for this body. */
+    truncated: boolean;
+}
+/** A whole captured body, from {@link CloudBrowser.readNetworkBody}. */
+export interface NetworkBody {
+    data: Uint8Array;
+    /** The kept body is shorter than the original; see the exchange's flag. */
+    truncated: boolean;
+}
+/**
+ * Which response bodies a network capture keeps. Kept bodies are not part of
+ * the exchange; read them with {@link CloudBrowser.readNetworkBody}.
+ */
 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.
+ * There is deliberately no byte-cap option: kept bodies are stored on a
+ * machine shared with other sessions, so the server owns the quota. When a
+ * session's bodies exceed it, the oldest are dropped first.
  */
 export interface NetworkCaptureOptions {
     /**
@@ -149,9 +218,8 @@ export interface NetworkCaptureOptions {
     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.
+     * `"all"` keeps every body, binary included. Defaults to `"none"`, headers
+     * and status only. Request bodies are kept whenever a request has one.
      */
     bodies?: NetworkBodies;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browserscale-ts",
-  "version": "1.8.0",
+  "version": "1.10.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",