browserscale-ts 1.3.0 → 1.5.0

package/dist/client.js

@@ -2,10 +2,10 @@ import { createClient } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
 import { Browser, 
 // request / response schemas
-SetProxyRequestSchema, GetPagesRequestSchema, NavigateRequestSchema, LoadHTMLRequestSchema, EvaluateRequestSchema, WaitForAnyParamsSchema, WaitConditionSchema, ClickRequestSchema, FillRequestSchema, MoveToRequestSchema, ScrollToRequestSchema, DragRequestSchema, SelectOptionRequestSchema, GetDOMRequestSchema, GetDOMHashRequestSchema, GetObservationRequestSchema, ScreenshotRequestSchema, ReadCanvasRequestSchema, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, TypeRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, GetStreamConfigRequestSchema, StartStreamRequestSchema, StopStreamRequestSchema, AddReactionRequestSchema, RemoveReactionRequestSchema, ListReactionsRequestSchema, } from "./gen/wrc_pb.js";
+SetProxyRequestSchema, GetPagesRequestSchema, NavigateRequestSchema, LoadHTMLRequestSchema, EvaluateRequestSchema, WaitForAnyParamsSchema, WaitConditionSchema, ClickRequestSchema, FillRequestSchema, MoveToRequestSchema, ScrollToRequestSchema, DragRequestSchema, SelectOptionRequestSchema, GetDOMRequestSchema, GetDOMHashRequestSchema, GetObservationRequestSchema, ScreenshotRequestSchema, ReadCanvasRequestSchema, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, GetAuthSessionRequestSchema, SetAuthSessionRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, TypeRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, GetStreamConfigRequestSchema, StartStreamRequestSchema, StopStreamRequestSchema, AddReactionRequestSchema, RemoveReactionRequestSchema, ListReactionsRequestSchema, } from "./gen/wrc_pb.js";
 import { DefaultWaitTimeoutMs } from "./defaults.js";
 import { BrowserScaleError } from "./errors.js";
-import { cookieParamFromProto, cookieParamsToProto, elementFields, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, splitRequestPatterns, storageEntriesToProto, storageEntryFromProto, unwrapClick, unwrapDrag, unwrapFill, unwrapMove, unwrapScroll, unwrapSelect, unwrapWait, } from "./internal/convert.js";
+import { authSessionFromProto, authSessionToProto, cookieParamFromProto, cookieParamsToProto, elementFields, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, splitRequestPatterns, storageEntriesToProto, storageEntryFromProto, unwrapClick, unwrapDrag, unwrapFill, unwrapMove, unwrapScroll, unwrapSelect, unwrapWait, } from "./internal/convert.js";
 /**
  * CloudBrowser is the SDK-side handle for an active browserscale browser session.
  *
@@ -705,38 +705,70 @@ export class CloudBrowser {
         return resp.hash;
     }
     /**
-     * Returns a compact, agent-friendly description of every interactable
-     * element currently visible on the page, together with a truncated view
-     * of the surrounding text.
+     * Returns a compact, frame-aware view of the visible page — the first thing
+     * to reach for on an unfamiliar page, and the cheapest way to re-read the
+     * current state afterwards.
      *
-     * Intended as input for LLM/agent loops where a full DOM dump would be
-     * too large; the server filters down to elements that are actually
-     * visible and interactable.
+     * Each frame opens with header lines carrying the URL, the title and the
+     * scroll position, then one line per visible element:
      *
-     * @param opts - optional caps: `maxElementsPerFrame`, `maxTextLength`;
-     *   omit either to use the server default
+     * ```
+     * input#email[47] type="email" name="loginId" value="a@b.com" required click "E-Mail"
+     * ```
      *
-     * @returns ObservationResult with both a human-readable `text` rendering
-     *   and a `json` payload of the structured observation
+     * It spans every frame, pierces open and closed shadow roots, enumerates
+     * `<select>` options, and reports live form state: `value=` is what is typed
+     * in right now (passwords as a length), `checked=` for boxes. The trailing
+     * quoted string is always the label or text, never the value, so an empty and
+     * a prefilled field stay distinguishable. Because the headers already carry
+     * URL, title and scroll offset, this replaces the usual handful of
+     * {@link evaluate} probes after each step.
+     *
+     * On what to do with the result: backendNodeId (the `47` above) is a handle
+     * for this session and can be passed straight to click/fill via
+     * {@link node}. It does not survive a new document, so for anything you write
+     * into a script, target with {@link css} or {@link js} instead — those calls
+     * return the backendNodeId they resolved to, which lets you confirm the
+     * durable anchor hits the element you saw.
+     *
+     * @param opts - optional format and budget overrides; see {@link GetObservationOpts}
+     *
+     * @returns the observation in the requested format, ready to hand to a model
      *
      * @throws UNKNOWN_ERROR - the observation could not be produced
      *
      * @example
-     * const obs = await browser.getObservation({ maxElementsPerFrame: 200 });
-     * console.log(obs.text);
+     * const obs = await browser.getObservation();
+     * console.log(obs);
      */
     async getObservation(opts) {
         const req = create(GetObservationRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         });
+        if (opts?.format !== undefined)
+            req.format = opts.format;
         if (opts?.maxElementsPerFrame !== undefined) {
             req.maxElementsPerFrame = opts.maxElementsPerFrame;
         }
         if (opts?.maxTextLength !== undefined)
             req.maxTextLength = opts.maxTextLength;
+        if (opts?.maxTotalTokens !== undefined)
+            req.maxTotalTokens = opts.maxTotalTokens;
+        if (opts?.includeBounds !== undefined)
+            req.includeBounds = opts.includeBounds;
+        if (opts?.viewportOnly !== undefined)
+            req.viewportOnly = opts.viewportOnly;
+        if (opts?.backendNodeId !== undefined)
+            req.backendNodeId = opts.backendNodeId;
+        if (opts?.selector !== undefined)
+            req.selector = opts.selector;
+        if (opts?.jsExpression !== undefined)
+            req.jsExpression = opts.jsExpression;
+        if (opts?.frameId !== undefined)
+            req.frameId = opts.frameId;
         const resp = await this.client.getObservation(req);
-        return { text: resp.observationText, json: resp.observationJson };
+        return resp.observation;
     }
     /**
      * Captures a single image of the page's current frame and returns it as
@@ -1161,6 +1193,54 @@ export class CloudBrowser {
         await this.client.clearStorage(req);
     }
     // ──────────────────────────────────────────────────────────────────
+    // Auth / DBSC (portable signed-in persona)
+    // ──────────────────────────────────────────────────────────────────
+    /**
+     * Exports the signed-in primary account and DBSC sessions of this
+     * browser context.
+     *
+     * State is read in the browser process, so no page needs to be open.
+     * Returns undefined when the context has neither a signed-in account
+     * nor DBSC sessions.
+     *
+     * @returns AuthSession, or undefined when there is nothing to export
+     *
+     * @throws UNKNOWN_ERROR - the auth session could not be read
+     *
+     * @example
+     * const auth = await browser.getAuthSession();
+     * if (auth) await fs.writeFile("auth.json", JSON.stringify(auth));
+     */
+    async getAuthSession() {
+        const resp = await this.client.getAuthSession(create(GetAuthSessionRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+        return resp.session ? authSessionFromProto(resp.session) : undefined;
+    }
+    /**
+     * Imports an auth session so the context comes up signed in (and syncing
+     * if syncConsent) with its DBSC sessions restored.
+     *
+     * Call it before navigating. Pair with setCookies() / setStorage() to
+     * restore a full persona.
+     *
+     * @param session - session as returned by getAuthSession()
+     *
+     * @throws UNKNOWN_ERROR - the auth session could not be written
+     *
+     * @example
+     * await browser.setAuthSession(saved);
+     * await browser.navigate("https://mail.google.com");
+     */
+    async setAuthSession(session) {
+        await this.client.setAuthSession(create(SetAuthSessionRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            session: authSessionToProto(session),
+        }));
+    }
+    // ──────────────────────────────────────────────────────────────────
     // Devtools / live-UI helpers
     // ──────────────────────────────────────────────────────────────────
     /**

package/dist/gen/wrc_pb.d.ts

@@ -548,6 +548,15 @@ export type OccluderInfo = Message<"browserscale.v1.OccluderInfo"> & {
      * @generated from field: optional bool hittable_while_invisible = 12;
      */
     hittableWhileInvisible?: boolean;
+    /**
+     * Computed position keyword. Reports "fixed"/"sticky" when the element is
+     * pinned by itself or by an ancestor — pinned blockers stay put no matter
+     * where the pointer goes and can only be cleared by scrolling the target out
+     * from under them; ordinary overlays often collapse once the pointer leaves.
+     *
+     * @generated from field: optional string position = 13;
+     */
+    position?: string;
 };
 /**
  * Describes the message browserscale.v1.OccluderInfo.
@@ -2332,6 +2341,146 @@ export type ClearStorageRequest = Message<"browserscale.v1.ClearStorageRequest">
  * Use `create(ClearStorageRequestSchema)` to create a new message.
  */
 export declare const ClearStorageRequestSchema: GenMessage<ClearStorageRequest>;
+/**
+ * One Device Bound Session Credentials entry (WRC.DbscSession).
+ *
+ * @generated from message browserscale.v1.DbscSession
+ */
+export type DbscSession = Message<"browserscale.v1.DbscSession"> & {
+    /**
+     * Serialized net::SchemefulSite (eTLD+1 site key), e.g. "https://google.com".
+     *
+     * @generated from field: string site = 1;
+     */
+    site: string;
+    /**
+     * Base64 of the serialized net.device_bound_sessions.proto.Session
+     * (includes the wrapped binding key; portable under WRC's software
+     * UnexportableKeyProvider).
+     *
+     * @generated from field: string session = 2;
+     */
+    session: string;
+};
+/**
+ * Describes the message browserscale.v1.DbscSession.
+ * Use `create(DbscSessionSchema)` to create a new message.
+ */
+export declare const DbscSessionSchema: GenMessage<DbscSession>;
+/**
+ * Portable snapshot of a context's signed-in Google account and/or DBSC
+ * sessions (WRC.AuthSession). All fields optional so partial state round-trips.
+ *
+ * @generated from message browserscale.v1.AuthSession
+ */
+export type AuthSession = Message<"browserscale.v1.AuthSession"> & {
+    /**
+     * Gaia obfuscated account id.
+     *
+     * @generated from field: optional string gaia_id = 1;
+     */
+    gaiaId?: string;
+    /**
+     * Account email.
+     *
+     * @generated from field: optional string email = 2;
+     */
+    email?: string;
+    /**
+     * OAuth refresh token (persistent).
+     *
+     * @generated from field: optional string refresh_token = 3;
+     */
+    refreshToken?: string;
+    /**
+     * Base64 of the wrapped device-binding key for the refresh token.
+     * Empty/absent = unbound token.
+     *
+     * @generated from field: optional string wrapped_binding_key = 4;
+     */
+    wrappedBindingKey?: string;
+    /**
+     * Signin-scoped device id; must travel with the token.
+     *
+     * @generated from field: optional string signin_scoped_device_id = 5;
+     */
+    signinScopedDeviceId?: string;
+    /**
+     * True if the account should be restored at Sync consent.
+     *
+     * @generated from field: optional bool sync_consent = 6;
+     */
+    syncConsent?: boolean;
+    /**
+     * Device Bound Session Credentials for this context (all bound sites).
+     *
+     * @generated from field: repeated browserscale.v1.DbscSession dbsc_sessions = 7;
+     */
+    dbscSessions: DbscSession[];
+};
+/**
+ * Describes the message browserscale.v1.AuthSession.
+ * Use `create(AuthSessionSchema)` to create a new message.
+ */
+export declare const AuthSessionSchema: GenMessage<AuthSession>;
+/**
+ * @generated from message browserscale.v1.GetAuthSessionRequest
+ */
+export type GetAuthSessionRequest = Message<"browserscale.v1.GetAuthSessionRequest"> & {
+    /**
+     * @generated from field: string session_id = 1;
+     */
+    sessionId: string;
+    /**
+     * @generated from field: string api_key = 2;
+     */
+    apiKey: string;
+};
+/**
+ * Describes the message browserscale.v1.GetAuthSessionRequest.
+ * Use `create(GetAuthSessionRequestSchema)` to create a new message.
+ */
+export declare const GetAuthSessionRequestSchema: GenMessage<GetAuthSessionRequest>;
+/**
+ * @generated from message browserscale.v1.GetAuthSessionResponse
+ */
+export type GetAuthSessionResponse = Message<"browserscale.v1.GetAuthSessionResponse"> & {
+    /**
+     * Present only if the context has exportable auth/DBSC state.
+     *
+     * @generated from field: optional browserscale.v1.AuthSession session = 1;
+     */
+    session?: AuthSession;
+};
+/**
+ * Describes the message browserscale.v1.GetAuthSessionResponse.
+ * Use `create(GetAuthSessionResponseSchema)` to create a new message.
+ */
+export declare const GetAuthSessionResponseSchema: GenMessage<GetAuthSessionResponse>;
+/**
+ * @generated from message browserscale.v1.SetAuthSessionRequest
+ */
+export type SetAuthSessionRequest = Message<"browserscale.v1.SetAuthSessionRequest"> & {
+    /**
+     * @generated from field: string session_id = 1;
+     */
+    sessionId: string;
+    /**
+     * @generated from field: string api_key = 2;
+     */
+    apiKey: string;
+    /**
+     * Session to import (as returned by GetAuthSession).
+     *
+     * @generated from field: browserscale.v1.AuthSession session = 3;
+     */
+    session?: AuthSession;
+};
+/**
+ * Describes the message browserscale.v1.SetAuthSessionRequest.
+ * Use `create(SetAuthSessionRequestSchema)` to create a new message.
+ */
+export declare const SetAuthSessionRequestSchema: GenMessage<SetAuthSessionRequest>;
 /**
  * @generated from message browserscale.v1.GetDOMRequest
  */
@@ -2397,17 +2546,74 @@ export type GetObservationRequest = Message<"browserscale.v1.GetObservationReque
      */
     pageId: string;
     /**
-     * Default 500.
+     * Safety net against runaway documents; max_total_tokens is the limit that
+     * normally binds. Default 800.
      *
      * @generated from field: optional int32 max_elements_per_frame = 4;
      */
     maxElementsPerFrame?: number;
     /**
-     * Default 240.
+     * Max length of human-readable strings (labels, text, values). Default 300.
+     * Identifier-like attributes have their own shorter cap.
      *
      * @generated from field: optional int32 max_text_length = 5;
      */
     maxTextLength?: number;
+    /**
+     * "text" (default) for the compact line format, "json" for the structured
+     * form. Only the requested representation is built.
+     *
+     * @generated from field: optional string format = 6;
+     */
+    format?: string;
+    /**
+     * Budget across ALL frames, in estimated tokens rather than characters.
+     * Default 8000.
+     *
+     * @generated from field: optional int32 max_total_tokens = 7;
+     */
+    maxTotalTokens?: number;
+    /**
+     * Include element bounds as bounds="x,y,w,h".
+     *
+     * @generated from field: optional bool include_bounds = 8;
+     */
+    includeBounds?: boolean;
+    /**
+     * Only emit elements intersecting the frame's current viewport.
+     *
+     * @generated from field: optional bool viewport_only = 9;
+     */
+    viewportOnly?: boolean;
+    /**
+     * Scope root by backend node ID from a previous wait/getObservation.
+     * Requires frame_id. At most one of backend_node_id, selector, js_expression.
+     * Omit all three for the whole page.
+     *
+     * @generated from field: optional int32 backend_node_id = 10;
+     */
+    backendNodeId?: number;
+    /**
+     * Scope root by CSS selector.
+     *
+     * @generated from field: optional string selector = 11;
+     */
+    selector?: string;
+    /**
+     * Scope root by JS expression that evaluates to a DOM Element
+     * (including __wrc.shadow(...) for closed shadow roots).
+     *
+     * @generated from field: optional string js_expression = 12;
+     */
+    jsExpression?: string;
+    /**
+     * Where to look up the scope root: a specific frameId, empty/omitted for
+     * the main frame, or "ALL_FRAMES" to search every frame until found.
+     * Ignored when observing the whole page.
+     *
+     * @generated from field: optional string frame_id = 13;
+     */
+    frameId?: string;
 };
 /**
  * Describes the message browserscale.v1.GetObservationRequest.
@@ -2419,17 +2625,11 @@ export declare const GetObservationRequestSchema: GenMessage<GetObservationReque
  */
 export type GetObservationResponse = Message<"browserscale.v1.GetObservationResponse"> & {
     /**
-     * Compact plain-text observation intended for LLM context.
-     *
-     * @generated from field: string observation_text = 1;
-     */
-    observationText: string;
-    /**
-     * Structured JSON with frames, elements, counts, and limits.
+     * The observation in the requested format.
      *
-     * @generated from field: string observation_json = 2;
+     * @generated from field: string observation = 1;
      */
-    observationJson: string;
+    observation: string;
 };
 /**
  * Describes the message browserscale.v1.GetObservationResponse.
@@ -3389,6 +3589,24 @@ export declare const Browser: GenService<{
         input: typeof ClearStorageRequestSchema;
         output: typeof EmptySchema;
     };
+    /**
+     * Auth / DBSC (portable signed-in persona)
+     *
+     * @generated from rpc browserscale.v1.Browser.GetAuthSession
+     */
+    getAuthSession: {
+        methodKind: "unary";
+        input: typeof GetAuthSessionRequestSchema;
+        output: typeof GetAuthSessionResponseSchema;
+    };
+    /**
+     * @generated from rpc browserscale.v1.Browser.SetAuthSession
+     */
+    setAuthSession: {
+        methodKind: "unary";
+        input: typeof SetAuthSessionRequestSchema;
+        output: typeof EmptySchema;
+    };
     /**
      * DOM / observation
      *