wrc-ts 0.1.0

package/dist/network.d.ts

@@ -0,0 +1,37 @@
+/**
+ * RequestPattern matches a URL pattern in waitForAnyRequest/Response.
+ * Set abort to true to drop the request with an empty 200 response
+ * instead of letting it through to the network.
+ */
+export interface RequestPattern {
+    url: string;
+    /** Default false. */
+    abort?: boolean;
+}
+/** Action verb for a {@link HeaderModification}. */
+export type HeaderModificationAction = "add" | "edit" | "remove";
+/**
+ * HeaderModification is one entry passed to {@link CloudBrowser.modifyRequest}.
+ * Write it as a plain object literal.
+ */
+export interface HeaderModification {
+    /**
+     * `"add"` inserts a new header, `"edit"` replaces an existing header's
+     * value, `"remove"` drops the header.
+     */
+    action: HeaderModificationAction;
+    /** Header name the action applies to. */
+    name: string;
+    /** Header value for add/edit; ignored for remove. */
+    value?: string;
+    /**
+     * Positions an `"add"` immediately before the named existing header;
+     * otherwise the header is appended at the end. Ignored for edit/remove.
+     */
+    before?: string;
+    /**
+     * Positions an `"add"` immediately after the named existing header.
+     * Mirror of `before`; ignored for edit/remove.
+     */
+    after?: string;
+}

package/dist/network.js

@@ -0,0 +1,2 @@
+// Network helpers — request-pattern matching, header modifications.
+export {};

package/dist/options.d.ts

@@ -0,0 +1,96 @@
+/** Mouse button used by {@link CloudBrowser.click}. */
+export type Button = "left" | "right" | "middle";
+/** Mouse phase performed by {@link CloudBrowser.click}. */
+export type ClickAction = "click" | "press" | "release";
+/**
+ * Optional customization for {@link CloudBrowser.click}. All fields are
+ * optional; missing or zero values mean "use the server default".
+ */
+export interface ClickOpts {
+    /**
+     * Override the locator's frame. Omit to use the locator's own
+     * {@link Locator.inFrame} (or the main frame). Pass a specific
+     * `frameId` or {@link AllFrames} to search elsewhere.
+     */
+    inFrame?: string;
+    /** Mouse button. Default `"left"`. */
+    button?: Button;
+    /** `1` = single click (default), `2` = double-click. */
+    clickCount?: number;
+    /**
+     * `"click"` (default) performs a full mouseDown+mouseUp.
+     * `"press"` only dispatches mouseDown, `"release"` only mouseUp at
+     * the current cursor position.
+     */
+    action?: ClickAction;
+}
+/**
+ * Optional customization for {@link CloudBrowser.fill}. All fields are
+ * optional; missing values mean "use the server default".
+ */
+export interface FillOpts {
+    /**
+     * Override the locator's frame. Omit to use the locator's own
+     * {@link Locator.inFrame} (or the main frame). Pass a specific
+     * `frameId` or {@link AllFrames} to search elsewhere.
+     */
+    inFrame?: string;
+    /**
+     * `true` wipes the field's existing content with Ctrl+A, Delete
+     * before typing. Default (`false`) appends to whatever is already
+     * in the field.
+     */
+    clearFirst?: boolean;
+}
+/**
+ * Optional customization for {@link CloudBrowser.selectByIndex},
+ * {@link CloudBrowser.selectByValue} and {@link CloudBrowser.selectByText}.
+ */
+export interface SelectOpts {
+    /**
+     * Override the locator's frame. Omit to use the locator's own
+     * {@link Locator.inFrame} (or the main frame). Pass a specific
+     * `frameId` or {@link AllFrames} to search elsewhere.
+     */
+    inFrame?: string;
+    /**
+     * `false` suppresses change/input events. Default (`true`) fires the
+     * standard events after the selection.
+     */
+    fireEvents?: boolean;
+}
+/** Optional customization for {@link CloudBrowser.wait} / {@link CloudBrowser.waitForAny}. */
+export interface WaitOpts {
+    /** Default `DefaultWaitTimeoutMs` (30 000 ms). */
+    timeoutMs?: number;
+}
+/** Lifecycle event {@link CloudBrowser.navigate} waits for before returning. */
+export type WaitUntil = "load" | "domcontentloaded" | "networkidle";
+/** Optional customization for {@link CloudBrowser.navigate}. */
+export interface NavigateOpts {
+    /** Default 30 000 ms. */
+    timeoutMs?: number;
+    /** Default "load". */
+    waitUntil?: WaitUntil;
+}
+/** Optional customization for {@link CloudBrowser.loadHTML}. */
+export interface LoadHTMLOpts {
+    /** Extra headers to attach to the synthetic response. */
+    headers?: {
+        name: string;
+        value: string;
+    }[];
+    /** Default 200. */
+    statusCode?: number;
+}
+/** Depth used by getDOM(). 0 = whole tree (default), >0 = limited depth. */
+export interface GetDOMOpts {
+    depth?: number;
+}
+/** Optional customization for {@link CloudBrowser.getObservation}. */
+export interface GetObservationOpts {
+    /** Default 200. */
+    maxElementsPerFrame?: number;
+    /** Default 200. */
+    maxTextLength?: number;
+}

package/dist/options.js

@@ -0,0 +1,7 @@
+// Option bags for the element-action methods. All fields are optional —
+// pass nothing (or `{}`) to take all defaults. Empty/zero values mean
+// "use server default".
+//
+// `inFrame` on each opts struct wins over the locator's own .inFrame(...)
+// chain — useful when reusing a locator across frames.
+export {};

package/dist/storage.d.ts

@@ -0,0 +1,14 @@
+/** StorageItem is a single localStorage key/value pair. */
+export interface StorageItem {
+    key: string;
+    value: string;
+}
+/**
+ * StorageOriginEntry groups the localStorage entries of one origin
+ * (e.g. "https://example.com"). getStorage() returns these and
+ * setStorage() accepts the same shape, so a dump can be fed back verbatim.
+ */
+export interface StorageOriginEntry {
+    origin: string;
+    items: StorageItem[];
+}

package/dist/storage.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+/** Rect mirrors WRC.pdl Rect: position and size in CSS pixels. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** FrameInfo describes a single frame within a page's frame tree. */
+export interface FrameInfo {
+    frameId: string;
+    url: string;
+    isOOPIF: boolean;
+    hasJSContext: boolean;
+    isLoading: boolean;
+    isVisible: boolean;
+    absoluteRect: Rect;
+    relativeRect: Rect;
+    children: FrameInfo[];
+}
+/** PageInfo describes an open page (tab or popup) inside a browser context. */
+export interface PageInfo {
+    pageId: string;
+    browserContextId: string;
+    url: string;
+    title: string;
+    viewport: Rect;
+    frameTree: FrameInfo;
+}
+/** Header is a single HTTP header (name/value pair) on an intercepted request or response. */
+export interface Header {
+    name: string;
+    value: string;
+}
+/**
+ * InterceptedRequest describes an outgoing request captured by
+ * {@link CloudBrowser.waitForAnyRequest}.
+ */
+export interface InterceptedRequest {
+    method: string;
+    url: string;
+    headers: Header[];
+    body: string;
+    resourceType: string;
+}
+/**
+ * InterceptedResponse describes a network response captured by
+ * {@link CloudBrowser.waitForAnyResponse}.
+ */
+export interface InterceptedResponse {
+    url: string;
+    statusCode: number;
+    headers: Header[];
+    body: string;
+}
+/**
+ * WaitResult is the outcome of a {@link CloudBrowser.wait} /
+ * {@link CloudBrowser.waitForAny} call: which condition matched (index, in
+ * argument order) and where the matched element lives.
+ */
+export interface WaitResult {
+    index: number;
+    frameId: string;
+    backendNodeId: number;
+    isVisible: boolean;
+    bounds: Rect;
+}
+/** NavigateResult reports where a {@link CloudBrowser.navigate} call ended up after redirects. */
+export interface NavigateResult {
+    frameId: string;
+    url: string;
+}
+/**
+ * EvaluateResult carries the outcome of a JS evaluate call.
+ *
+ * If the expression returned a DOM element, backendNodeId/isVisible/bounds
+ * are populated and value is null. Otherwise value holds the parsed JSON
+ * value (string/number/boolean/array/object/null). On parse failure value
+ * falls back to the raw server string so the caller is never empty-handed.
+ *
+ * The optional generic T types the .value field for convenience — this is
+ * purely a TS hint, not a runtime guarantee.
+ */
+export interface EvaluateResult<T = unknown> {
+    value: T;
+    backendNodeId: number;
+    isVisible: boolean;
+    bounds: Rect;
+}
+/**
+ * ElementResult is the outcome of an element interaction such as
+ * {@link CloudBrowser.click}, {@link CloudBrowser.fill} or
+ * {@link CloudBrowser.scrollTo}: the resolved element plus the
+ * root-relative coordinates the action was performed at.
+ */
+export interface ElementResult {
+    success: boolean;
+    frameId: string;
+    backendNodeId: number;
+    isVisible: boolean;
+    bounds: Rect;
+    rootX: number;
+    rootY: number;
+}
+/**
+ * DragResult is the outcome of a {@link CloudBrowser.drag} gesture: the
+ * resolved source element and the start/end coordinates of the performed drag.
+ */
+export interface DragResult {
+    success: boolean;
+    frameId: string;
+    backendNodeId: number;
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+}
+/** SelectOptionResult reports which option a selectByXxx call ended up selecting. */
+export interface SelectOptionResult {
+    selectedIndex: number;
+    selectedValue: string;
+    selectedText: string;
+}
+/**
+ * ObservationResult is the compact page snapshot returned by
+ * {@link CloudBrowser.getObservation} — the visible, interactive elements
+ * rendered as prompt-friendly text and as JSON.
+ */
+export interface ObservationResult {
+    text: string;
+    json: string;
+}
+/**
+ * DOMResult is the full-tree DOM snapshot returned by
+ * {@link CloudBrowser.getDOM}, plus its sha256[:8] hash for cheap
+ * change detection.
+ */
+export interface DOMResult {
+    hash: string;
+    dom: string;
+}
+/**
+ * InspectResult describes the topmost element hit at viewport-relative
+ * (x, y). backendNodeId === 0 means nothing was found at that position.
+ */
+export interface InspectResult {
+    backendNodeId: number;
+    frameId: string;
+    tagName: string;
+    textContent: string;
+    isVisible: boolean;
+    bounds: Rect;
+}
+/** RentResponse is the result of renting a browser via the REST API. */
+export interface RentResponse {
+    sessionId: string;
+    grpcUrl: string;
+    countryCode: string;
+    timezone: string;
+    acceptLanguage: string;
+    fingerprint: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Plain user-facing types. These mirror wrc_go/types.go field-for-field;
+// only naming convention differs (camelCase here, PascalCase in Go).
+export {};