wrc-ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebRobot Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# wrc-ts — WebRobot Cloud SDK for TypeScript
+
+Official TypeScript SDK for [WebRobot Cloud](https://webrobot.cloud): real
+Chromium browsers in the cloud, driven over gRPC. Rent an isolated browser
+session in seconds, automate it with human-like input, intercept network
+traffic, solve captchas, and watch a live video stream of everything your
+script does.
+
+## Features
+
+- **Real browser sessions as a service** — full Chromium in the cloud with
+  pages, frames, cookies, storage and network state. No local binary.
+- **Parallel isolated contexts** — each task gets its own session, fingerprint
+  and lifecycle; large queues never share browser state. Sessions are browser
+  contexts, not VMs or processes, so they spin up in under 50 ms and fan out to
+  thousands in parallel.
+- **Fingerprint & proxy handling** — pinnable server-side fingerprints,
+  native Chrome control without CDP/Playwright/Puppeteer leaks, bring your own
+  proxy or let WRC allocate one.
+- **Native engine-level control** — automation runs natively inside Chromium
+  itself, not from outside over the DevTools protocol. Nothing is injected, no
+  `Runtime.enable`, no DevTools handshake — page JS can't observe it. Waits run
+  fully async with no polling loop, and built-in steady-time checks only report
+  an element once it's stable in the DOM.
+- **One flat frame tree** — main document, same-origin iframes and cross-origin
+  OOPIFs are all just a `frameId` in one tree, no flattened sessions or
+  per-frame execution-context juggling. `wait`/`click` act across all frames or
+  a single iframe, and `wait` returns the `frameId` that matched.
+- **Human-like interaction** — mouse paths use WRC's own movement algorithm
+  instead of instant synthetic jumps.
+- **WebRTC live video stream** — watch and control the rented browser live
+  from the WRC web interface; mouse and keyboard go back over data channels.
+- **Captcha support, no third-party solvers** — passive anti-bot checks are
+  handled automatically; interactive challenges are solved with `solveCaptcha`
+  by WRC's own AI solver, which learns the known challenge types — puzzle,
+  OCR, slide, hold and more — on its own and keeps improving as they evolve.
+  No token is ever synthesized or fetched from an external API: the challenge
+  is completed in the valid live browser and the provider's own JavaScript
+  issues the token itself — which is why even new or unknown protections
+  pass.
+- **Real hardware, real GPUs** — sessions run hardware-accelerated on real
+  consumer GPUs, not on VM cores with a WebGL faking layer. Canvas and WebGL
+  readbacks (`toDataURL`, `getImageData`) return genuinely rendered pixels —
+  no spoofing layer or fingerprint hash database for new bot protections to
+  unmask.
+- **Network control at the source** — interception sits in the browser's
+  network stack itself, so every request from every frame (including
+  cross-origin OOPIFs) passes through it; no handler races, nothing slips
+  through. Wait for, block, mock or modify requests and responses without
+  leaving the SDK; mark repeated assets as static with `setStaticPaths` to
+  serve them from a server-side cache and cut proxy bandwidth on repeat runs.
+- **Agent-friendly observation** — `getObservation` returns a compact
+  text/JSON view of the visible, interactive elements across every frame, each
+  with a node handle to act on, so a model reasons over what matters instead of
+  raw HTML.
+- **Flow-optimized TypeScript** — fully typed promise-based API, `wait` races
+  multiple outcomes, JS locators target elements by page logic when CSS is
+  not enough. Runs in Node.js (native gRPC) and the browser (WebSocket via
+  `wrc-ts/browser`).
+
+## Install
+
+```bash
+npm install wrc-ts
+```
+
+Requires Node 18+. Ships as an ES module with bundled type declarations.
+
+## Quickstart
+
+```ts
+import { rentBrowser, BrowserConfig, css } from "wrc-ts";
+
+async function main() {
+    // Empty proxy fields tell WRC to allocate a managed proxy server-side;
+    // pass your own host/port/creds to bring your own.
+    const cfg = new BrowserConfig(
+        "YOUR_API_KEY", // sk_…
+        300,            // rent duration in seconds (5 minutes)
+        "", 0, "", "",  // proxy host / port / user / pass
+    );
+
+    const browser = await rentBrowser(cfg);
+    try {
+        await browser.navigate("https://example.com");
+        await browser.wait(css("h1"));
+
+        const res = await browser.evaluate("document.title");
+        console.log("title:", res.value);
+    } finally {
+        await browser.stopBrowser(); // always release the session
+    }
+}
+
+main();
+```
+
+Run it and you should see `title: Example Domain`. Get an API key from your
+[dashboard](https://webrobot.cloud/dashboard/api-keys).
+
+## Documentation
+
+- [Introduction](https://webrobot.cloud/docs) — what WRC is, use cases and
+  the mental model behind sessions, pages, frames and locators
+- [Quickstart](https://webrobot.cloud/docs/quickstart) — from install to a
+  running script in under a minute
+- [Core concepts](https://webrobot.cloud/docs/concepts)
+- Guides — [locators](https://webrobot.cloud/docs/guides/locators),
+  [waiting](https://webrobot.cloud/docs/guides/waiting),
+  [network](https://webrobot.cloud/docs/guides/network),
+  [cookies](https://webrobot.cloud/docs/guides/cookies),
+  [captchas](https://webrobot.cloud/docs/guides/captchas) and more
+- [TypeScript API reference](https://webrobot.cloud/docs/api-reference/ts) —
+  every method, type and option with runnable examples
+
+## Go
+
+Prefer Go? Use the Go SDK:
+[wrc_go](https://github.com/webrobot-dev/wrc_go).
+
+## License
+
+[MIT](LICENSE)

package/dist/browser.d.ts

@@ -0,0 +1,39 @@
+import { CloudBrowser } from "./client.ts";
+export { CloudBrowser } from "./client.ts";
+export { WebSocketTransport } from "./ws-transport.ts";
+export { BrowserConfig } from "./config.ts";
+export { Locator, css, js, node, at, AllFrames } from "./locator.ts";
+export { DefaultWaitTimeoutMs, DefaultVisible, DefaultSteadyMs, } from "./defaults.ts";
+export { WRCError } from "./errors.ts";
+export type { Rect, FrameInfo, PageInfo, Header, InterceptedRequest, InterceptedResponse, WaitResult, NavigateResult, EvaluateResult, ElementResult, DragResult, SelectOptionResult, ObservationResult, DOMResult, InspectResult, RentResponse, } from "./types.ts";
+export type { Button, ClickAction, ClickOpts, FillOpts, SelectOpts, WaitOpts, WaitUntil, NavigateOpts, LoadHTMLOpts, GetDOMOpts, GetObservationOpts, } from "./options.ts";
+export { type RequestPattern, type HeaderModification, type HeaderModificationAction, } from "./network.ts";
+export type { CookieParam } from "./cookies.ts";
+export type { StorageItem, StorageOriginEntry } from "./storage.ts";
+/**
+ * Attaches a {@link CloudBrowser} to an existing session over a raw
+ * WebSocket transport.
+ *
+ * Use this from a browser context: the WebSocket transport framing is
+ * defined by {@link WebSocketTransport} and is served directly by the
+ * WRC session host. The session must already exist server-side; unlike
+ * {@link rentBrowser} this does not call the rent API. Closing the
+ * returned handle (via {@link CloudBrowser.stopBrowser}) only closes the
+ * transport — the rental stays alive.
+ *
+ * @param wsUrl - WebSocket URL (ws:// or wss://) of the session host
+ * @param sessionId - id of the existing session
+ * @param apiKey - API key authorizing access to the session
+ * @param fingerprint - browser fingerprint id; empty if unknown
+ *
+ * @returns CloudBrowser attached to the existing session
+ *
+ * @example
+ * const browser = createWebSocketBrowser(
+ *   "wss://session-abc.wrc.example.com/ws",
+ *   sessionId,
+ *   apiKey,
+ * );
+ * await browser.navigate("https://example.com");
+ */
+export declare function createWebSocketBrowser(wsUrl: string, sessionId: string, apiKey: string, fingerprint?: string): CloudBrowser;

package/dist/browser.js

@@ -0,0 +1,43 @@
+import { CloudBrowser } from "./client.js";
+import { WebSocketTransport } from "./ws-transport.js";
+// Public API — browser entry point ────────────────────────────────────
+export { CloudBrowser } from "./client.js";
+export { WebSocketTransport } from "./ws-transport.js";
+export { BrowserConfig } from "./config.js";
+// Locator + constructors + AllFrames sentinel
+export { Locator, css, js, node, at, AllFrames } from "./locator.js";
+// Defaults the SDK applies before sending a request
+export { DefaultWaitTimeoutMs, DefaultVisible, DefaultSteadyMs, } from "./defaults.js";
+// Errors
+export { WRCError } from "./errors.js";
+// Browser-side factory functions ───────────────────────────────────────
+/**
+ * Attaches a {@link CloudBrowser} to an existing session over a raw
+ * WebSocket transport.
+ *
+ * Use this from a browser context: the WebSocket transport framing is
+ * defined by {@link WebSocketTransport} and is served directly by the
+ * WRC session host. The session must already exist server-side; unlike
+ * {@link rentBrowser} this does not call the rent API. Closing the
+ * returned handle (via {@link CloudBrowser.stopBrowser}) only closes the
+ * transport — the rental stays alive.
+ *
+ * @param wsUrl - WebSocket URL (ws:// or wss://) of the session host
+ * @param sessionId - id of the existing session
+ * @param apiKey - API key authorizing access to the session
+ * @param fingerprint - browser fingerprint id; empty if unknown
+ *
+ * @returns CloudBrowser attached to the existing session
+ *
+ * @example
+ * const browser = createWebSocketBrowser(
+ *   "wss://session-abc.wrc.example.com/ws",
+ *   sessionId,
+ *   apiKey,
+ * );
+ * await browser.navigate("https://example.com");
+ */
+export function createWebSocketBrowser(wsUrl, sessionId, apiKey, fingerprint = "") {
+    const transport = new WebSocketTransport(wsUrl);
+    return new CloudBrowser(transport, sessionId, apiKey, fingerprint);
+}