browserscale-ts 1.8.0 → 1.9.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, 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
 // ──────────────────────────────────────────────────────────────────────

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;

package/package.json

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