@boxline/sdk 1.1.0

package/dist/client.js

@@ -0,0 +1,874 @@
+import { queryString, send } from "./core.js";
+import { BoxlineTimeoutError, ErrorCode, makeError, NotFoundError } from "./errors.js";
+import { Page, PagePromise } from "./pagination.js";
+import { Session } from "./session.js";
+import { ndjson, sse } from "./streaming.js";
+const env = (name) => (typeof process !== "undefined" ? process?.env?.[name] : undefined);
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Where the SDK goes without baseUrl or BOXLINE_API_URL (the same default as the CLI). */
+export const DEFAULT_BASE_URL = "https://api.boxline.dev";
+/** A plain-English step can wait up to 4 minutes for a person to solve a CAPTCHA (session captcha "ask"). */
+const STEP_TIMEOUT_MS = 420_000;
+/**
+ * Client for the Boxline API: isolated cloud sessions with a Chrome browser, a bash shell and a shared disk, plus
+ * the web APIs and the AI agent. Works in Node 18+ and modern browsers (it uses the global fetch).
+ *
+ *   const bx = new Boxline();                    // BOXLINE_API_KEY; BOXLINE_API_URL (default https://api.boxline.dev)
+ *   const s = await bx.sessions.create();
+ *   const browser = await chromium.connectOverCDP(s.connectUrl!);
+ */
+export class Boxline {
+    baseUrl;
+    auth;
+    project;
+    apiKeys;
+    sessions;
+    contexts;
+    crawl;
+    agent;
+    tasks;
+    secrets;
+    webhooks;
+    extensions;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? env("BOXLINE_API_URL") ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        const cfg = {
+            apiKey: opts.apiKey ?? env("BOXLINE_API_KEY"),
+            baseUrl: this.baseUrl,
+            credentials: opts.credentials,
+            // Looked up per call, so a fetch patched after the client was made (tests, tracing) is used.
+            fetch: opts.fetch ?? ((input, init) => globalThis.fetch(input, init)),
+            maxRetries: opts.maxRetries ?? 2,
+            timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            headers: { ...opts.headers },
+        };
+        // Both hold the API key: not enumerable, so console.log(bx) and JSON.stringify(bx) never show it.
+        Object.defineProperty(this, "cfg", { value: cfg, enumerable: false });
+        Object.defineProperty(this, "options", { value: opts, enumerable: false });
+        this.auth = new Auth(this);
+        this.project = new ProjectSettings(this);
+        this.apiKeys = new ApiKeys(this);
+        this.sessions = new Sessions(this);
+        this.contexts = new Contexts(this);
+        this.crawl = new Crawl(this);
+        this.agent = new Agent(this);
+        this.tasks = new Tasks(this);
+        this.secrets = new Secrets(this);
+        this.webhooks = new Webhooks(this);
+        this.extensions = new Extensions(this);
+    }
+    /** What JSON.stringify shows: where the client points, never its key. */
+    toJSON() {
+        return { baseUrl: this.baseUrl, maxRetries: this.cfg.maxRetries, timeoutMs: this.cfg.timeoutMs };
+    }
+    /** A client like this one with some options changed, e.g. `bx.withOptions({ maxRetries: 5 })`. */
+    withOptions(opts) {
+        return new Boxline({ ...this.options, baseUrl: this.baseUrl, apiKey: this.cfg.apiKey, ...opts });
+    }
+    /** The calling user/project, its plan's limits and features, and whether it is suspended. */
+    me(options) {
+        return this.request("GET", "/v1/auth/me", undefined, options);
+    }
+    /** True when the project's plan includes `feature` (calls using a missing feature fail with 402 feature_not_in_plan). */
+    async hasFeature(feature, options) {
+        return Boolean((await this.me(options)).project.limits.features[feature]);
+    }
+    /** Fetch API: open a URL in a real browser (inside a sandbox) and get Markdown, HTML or text back. */
+    fetch(url, params = {}, options) {
+        return this.request("POST", "/v1/fetch", { url, ...params }, options);
+    }
+    /** A screenshot of any URL (fresh browser context each time). Returns the image bytes. */
+    screenshot(url, params = {}, options) {
+        return this.bytes("POST", "/v1/screenshot", { url, ...params }, options);
+    }
+    /** A PDF of any URL, printed like Chrome's "Save as PDF". Returns the PDF bytes. */
+    pdf(url, params = {}, options) {
+        return this.bytes("POST", "/v1/pdf", { url, ...params }, options);
+    }
+    /**
+     * Structured data from one or more pages: they are rendered in a real browser, then a model fills `schema`
+     * (JSON Schema) and/or follows `prompt`. Defaults to a fast, low-cost model.
+     */
+    extract(params, options) {
+        return this.request("POST", "/v1/extract", params, options);
+    }
+    /**
+     * Web search (the platform's provider, Brave): titles, URLs, snippets and dates. With `fetch`, the top pages are
+     * also opened in a sandboxed browser and returned as Markdown (`content`). The same search within an hour is
+     * answered from the cache (`cached: true`, not counted). The query text goes to the provider: keep secrets and
+     * personal data out of it. 503 `search_unavailable` (SearchUnavailableError) when search is not set up.
+     */
+    search(params, options) {
+        return this.request("POST", "/v1/search", params, options);
+    }
+    /** Usage and cost of the sessions created in a period (default: this month so far). */
+    usage(params = {}, options) {
+        return this.request("GET", `/v1/usage${queryString(params)}`, undefined, options);
+    }
+    /** Totals and per-day numbers for the last `days` days (UTC, including today). */
+    stats(days = 7, options) {
+        return this.request("GET", `/v1/stats${queryString({ days })}`, undefined, options);
+    }
+    /** The public price table and plans (no API key needed). */
+    pricing(options) {
+        return this.request("GET", "/v1/pricing", undefined, options);
+    }
+    /** The OpenAPI 3.1 description of the API. */
+    openapi(options) {
+        return this.request("GET", "/v1/openapi.json", undefined, options);
+    }
+    /** `{ok: true}` when the API is up. */
+    health(options) {
+        return this.request("GET", "/healthz", undefined, options);
+    }
+    /** Low-level request: parsed JSON (undefined for 204). The SDK's retry and error rules apply. */
+    async request(method, path, body, options = {}) {
+        return (await send(this.cfg, method, path, { ...options, body })).data;
+    }
+    /** Low-level request returning the Response with its body unread (after checking for errors). */
+    async send(method, path, body, options = {}) {
+        return (await send(this.cfg, method, path, { ...options, body, as: "response" })).response;
+    }
+    /** @internal */
+    async bytes(method, path, body, options = {}) {
+        return (await send(this.cfg, method, path, { ...options, body, as: "bytes" })).data;
+    }
+    /** @internal A list whose pages follow `next`; `map` turns each raw item into what the list yields. */
+    list(path, query, map, options) {
+        const load = async (after) => {
+            const body = await this.request("GET", `${path}${queryString({ ...query, after: after ?? query.after })}`, undefined, options);
+            return new Page({ ...body, data: (body.data ?? []).map(map) }, (next) => load(next));
+        };
+        return new PagePromise(() => load());
+    }
+}
+/** The larger of the client's time limit and what a call needs (a long command, a long wait). */
+const atLeast = (client, options, ms) => ({
+    ...options,
+    timeoutMs: options?.timeoutMs ?? Math.max(client.cfg.timeoutMs, ms),
+});
+const sid = (id) => `/v1/sessions/${encodeURIComponent(id)}`;
+// ---------------------------------------------------------------- auth, project, API keys
+/** Sign-up and console logins. Server-side code uses an API key instead of logging in. */
+export class Auth {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Creates a user, a project on the Free plan and a first API key (in the response only). No API key needed.
+     * `acceptTerms: true` says the user accepts the terms of service and acceptable use policy (400
+     * `terms_not_accepted` without it); `name` is optional.
+     */
+    signup(params, options) {
+        return this.client.request("POST", "/v1/auth/signup", params, options);
+    }
+    /** Starts a console login (cookie `bx_session`): for browser apps with `credentials: "include"`. */
+    login(params, options) {
+        return this.client.request("POST", "/v1/auth/login", params, options);
+    }
+    /** Ends the console login. */
+    logout(options) {
+        return this.client.request("POST", "/v1/auth/logout", undefined, options);
+    }
+}
+/** Project settings. */
+export class ProjectSettings {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** The Trajectories program setting: on by default; see the Terms of Service and Privacy Policy. */
+    trajectories(options) {
+        return this.client.request("GET", "/v1/project/trajectories", undefined, options);
+    }
+    /** Turns the Trajectories program on or off for this project (logged). */
+    setTrajectories(enabled, opts = {}, options) {
+        return this.client.request("PUT", "/v1/project/trajectories", { enabled, ...opts }, options);
+    }
+    /**
+     * The project's settings: `captchaDefault` is what new sessions and agent runs without a `captcha` option get;
+     * `captchaDefaultEffective` what they get now (the plan may no longer include solving).
+     */
+    settings(options) {
+        return this.client.request("GET", "/v1/project/settings", undefined, options);
+    }
+    /**
+     * Changes the fields you send (`captchaDefault: "solve"` needs a plan with CAPTCHA solving: 402 otherwise).
+     * `defaultModel` is the model used when a request names none; `null` clears it.
+     */
+    setSettings(params, options) {
+        return this.client.request("PUT", "/v1/project/settings", params, options);
+    }
+    /** The four providers with the project's own-key state (never a key: `preview` is its last 4 characters). */
+    modelKeys(options) {
+        return this.client.request("GET", "/v1/project/model-keys", undefined, options);
+    }
+    /**
+     * Saves a provider key and/or the choice of whose key calls use. The provider checks the key first (400
+     * `invalid_model_key` when it refuses it). Runs on your own key have no model charge from Boxline.
+     */
+    setModelKey(provider, params, options) {
+        return this.client.request("PUT", `/v1/project/model-keys/${provider}`, params, options);
+    }
+    /** Deletes the provider's key; calls go back to the platform's key where the plan includes it. */
+    deleteModelKey(provider, options) {
+        return this.client.request("DELETE", `/v1/project/model-keys/${provider}`, undefined, options);
+    }
+}
+/** The project's API keys. */
+export class ApiKeys {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Active keys, oldest first (the keys themselves are never shown again; `prefix` identifies them). */
+    list(params = {}, options) {
+        return this.client.list("/v1/api-keys", { ...params }, (k) => k, options);
+    }
+    /** A new key; `key` is in this response only. */
+    create(params = {}, options) {
+        return this.client.request("POST", "/v1/api-keys", params, options);
+    }
+    revoke(id, options) {
+        return this.client.request("DELETE", `/v1/api-keys/${encodeURIComponent(id)}`, undefined, options);
+    }
+}
+export class Sessions {
+    client;
+    files;
+    constructor(client) {
+        this.client = client;
+        this.files = new SessionFiles(client);
+    }
+    wrap = (data) => new Session(this.client, data);
+    async one(method, path, body, options) {
+        return this.wrap(await this.client.request(method, path, body, options));
+    }
+    /** Starts a session (an Idempotency-Key is sent, so a retry never starts a second one). */
+    create(params = {}, options) {
+        return this.one("POST", "/v1/sessions", params, options);
+    }
+    get(id, options) {
+        return this.one("GET", sid(id), undefined, options);
+    }
+    /**
+     * Sessions, newest first unless `sort` says otherwise. Await it for one page (`total` counts every match), or
+     * `for await (const s of bx.sessions.list())` for all of them.
+     */
+    list(params = {}, options) {
+        return this.client.list("/v1/sessions", { ...params }, this.wrap, options);
+    }
+    /** @deprecated Use list(): its first page has `total` too. */
+    page(params = {}, options) {
+        return this.list(params, options).then((p) => p);
+    }
+    /** Pause, resume or release 1 to 100 sessions at once (session ids; 30 calls per minute per project). */
+    bulk(action, ids, options) {
+        return this.client.request("POST", "/v1/sessions/bulk", { action, ids }, options);
+    }
+    /** Changes keepAlive, userMetadata, the proxy, the captcha option or the browser settings. */
+    update(id, patch, options) {
+        return this.one("PATCH", sid(id), patch, options);
+    }
+    /** Ends the session and deletes its machine. */
+    release(id, options) {
+        return this.one("POST", `${sid(id)}/release`, undefined, options);
+    }
+    /** Saves browser state and files, frees the machine and stops billing. Touching the session resumes it. */
+    pause(id, options) {
+        return this.one("POST", `${sid(id)}/pause`, undefined, options);
+    }
+    resume(id, options) {
+        return this.one("POST", `${sid(id)}/resume`, undefined, options);
+    }
+    /** Moves the live session to a fresh machine; clients reconnect to the same connectUrl. */
+    async move(id, options) {
+        const r = await this.client.request("POST", `${sid(id)}/move`, undefined, options);
+        return { session: this.wrap(r.session), timings: r.timings, shell: r.shell ?? null };
+    }
+    /** Adds time (60–3600 s), up to the plan's maximum session length. */
+    extend(id, seconds, options) {
+        return this.one("POST", `${sid(id)}/extend`, { seconds }, options);
+    }
+    /** A new IP for the session's proxy. */
+    rotateProxy(id, options) {
+        return this.one("POST", `${sid(id)}/proxy/rotate`, undefined, options);
+    }
+    /** Revokes the session's connect, live and terminal URLs and returns the session with fresh ones. */
+    rotateUrls(id, options) {
+        return this.one("POST", `${sid(id)}/rotate-urls`, undefined, options);
+    }
+    /** Fresh signed URLs (treat them like passwords). */
+    live(id, options) {
+        return this.client.request("GET", `${sid(id)}/live`, undefined, options);
+    }
+    /**
+     * Runs browser actions in order, next to the browser; stops at the first failure. A bare string is a plain-English
+     * step: `["click Sign in", {action: "fill", selector: "#q", value: "x"}]`. Each result's `text` says what happened.
+     */
+    async actions(id, actions, opts = {}, options) {
+        const list = Array.isArray(actions) ? actions : [actions];
+        const wait = list.some((a) => typeof a === "string" || a.action === "step") ? STEP_TIMEOUT_MS : 0;
+        const r = await this.client.request("POST", `${sid(id)}/actions`, { actions: list, ...opts }, atLeast(this.client, options, wait));
+        return r.results;
+    }
+    /**
+     * Runs ONE computer-use action exactly as the model's tool gave it (Anthropic `computer` tool input, or one OpenAI
+     * `computer_call` action) on the session's page, and returns the screen after it. With `maxWidth` the screenshot is
+     * scaled down and the action's coordinates are read in its pixels. A failure in the page is `ok: false`; input that
+     * cannot be mapped, or a point off the screen, throws (400 `invalid_request` / `out_of_viewport`).
+     */
+    computer(id, action, opts = {}, options) {
+        return this.client.request("POST", `${sid(id)}/computer`, { ...action, ...opts }, options);
+    }
+    /** Runs a shell command (persistent bash by default: cd/export survive between calls). */
+    /**
+     * Runs a command and returns its output. It is read as a stream (headers at once, the API keeps the connection
+     * alive), so neither a long command nor a wait for the session's setup runs into an HTTP client's own limits
+     * (Node's fetch gives up after 300 s without headers or data). Output past 64 KB is cut in the middle, as
+     * `truncated` says.
+     */
+    async exec(id, command, opts = {}, options) {
+        const out = { stdout: new Capture(), stderr: new Capture() };
+        // An API from before streamed exec sent headers early answers only once setup and the command are done.
+        const limit = atLeast(this.client, options, (opts.timeoutMs ?? 120_000) + 30_000 + 600_000);
+        const exit = await this.execStream(id, command, (stream, data) => out[stream].push(data), opts, limit);
+        return { stdout: out.stdout.text, stderr: out.stderr.text, ...exit, truncated: exit.truncated || out.stdout.truncated || out.stderr.truncated };
+    }
+    /** Runs a command and streams its output as it happens; resolves with the exit information. */
+    async execStream(id, command, onData, opts = {}, options) {
+        const { signal, ...rest } = opts;
+        const res = await this.client.send("POST", `${sid(id)}/exec`, { command, ...rest, stream: true }, { signal, ...options });
+        let exit = null;
+        for await (const msg of ndjson(res.body)) {
+            if (msg.type === "exit")
+                exit = { exitCode: msg.exitCode ?? null, timedOut: Boolean(msg.timedOut), durationMs: msg.durationMs ?? 0, truncated: Boolean(msg.truncated) };
+            else if (msg.type === "stdout" || msg.type === "stderr")
+                onData(msg.type, msg.data ?? "");
+            else if (msg.type === "error")
+                throw makeError(msg.status ?? 500, msg.code ?? "internal", msg.message ?? "the command failed", { requestId: msg.requestId ?? null });
+            // "waiting" (for the session's setup) and "ping" lines only keep the connection open.
+        }
+        return exit ?? { exitCode: null, timedOut: false, durationMs: 0, truncated: false };
+    }
+    /**
+     * Runs Playwright code inside the session's own sandbox (needs a shell), streaming its output to `onData`. In
+     * scope: `page`, `context`, `browser`, `env`, and `step()`, `extract()`, `useModel(model)` / `useModel(provider,
+     * model)`. A step or extract uses the call's own `{provider, model}`, else the last `useModel()`, else `ai`.
+     */
+    async runScript(id, code, opts = {}, options) {
+        const { signal, onData: _onData, ...body } = opts;
+        const res = await this.client.send("POST", `${sid(id)}/scripts/run`, { code, ...body }, { signal, ...options });
+        let stdout = "";
+        let stderr = "";
+        let exit = { exitCode: null, timedOut: false, durationMs: 0 };
+        for await (const msg of ndjson(res.body)) {
+            if (msg.type === "exit")
+                exit = { exitCode: msg.exitCode ?? null, timedOut: Boolean(msg.timedOut), durationMs: msg.durationMs ?? 0 };
+            else if (msg.type === "stdout" || msg.type === "stderr") {
+                if (msg.type === "stdout")
+                    stdout += msg.data ?? "";
+                else
+                    stderr += msg.data ?? "";
+                opts.onData?.(msg.type, msg.data ?? "");
+            }
+        }
+        return { stdout, stderr, ...exit };
+    }
+    /** Restarts the persistent shell (or the named one). */
+    restartShell(id, name, options) {
+        return this.client.request("POST", `${sid(id)}/shell/restart`, name === undefined ? {} : { shell: name }, options);
+    }
+    /** Writes the browser's cookies as a Netscape cookie file in the workspace (for curl -b / wget). */
+    exportCookies(id, path, options) {
+        return this.client.request("POST", `${sid(id)}/browser/cookies/export`, path === undefined ? {} : { path }, options);
+    }
+    /** Console, network, navigation, error, lifecycle, action, exec and captcha events, oldest first. */
+    events(id, params = {}, options) {
+        const { types, after, limit } = params;
+        return this.client.list(`${sid(id)}/events`, { types, after: after === undefined ? undefined : String(after), limit }, (e) => e, options);
+    }
+    /** Events as they happen: first the backlog after `after`, then live. Stop with `break` or `options.signal`. */
+    async *streamEvents(id, params = {}, options) {
+        const res = await this.client.send("GET", `${sid(id)}/events/stream${queryString(params)}`, undefined, options);
+        yield* sse(res.body);
+    }
+    /** Pages visited, grouped by tab and URL, in the order they were first visited. */
+    pages(id, params = {}, options) {
+        return this.client.list(`${sid(id)}/pages`, { ...params }, (p) => p, options);
+    }
+    /** Replay frames kept while the session ran. */
+    recording(id, options) {
+        return this.client.request("GET", `${sid(id)}/recording`, undefined, options);
+    }
+    /** One replay frame as JPEG bytes. */
+    recordingFrame(id, index, options) {
+        return this.client.bytes("GET", `${sid(id)}/recording/frames/${index}`, undefined, options);
+    }
+}
+/** Files in a session's /workspace (shared by the shell and the browser's downloads folder). */
+/** Output kept like the machine keeps it for a plain exec: the first 64 KB and the last 448 KB, the middle marked. */
+class Capture {
+    head = "";
+    tail = "";
+    total = 0;
+    truncated = false;
+    push(chunk) {
+        this.total += chunk.length;
+        const take = Math.max(0, Math.min(64 * 1024 - this.head.length, chunk.length));
+        this.head += chunk.slice(0, take);
+        this.tail += chunk.slice(take);
+        if (this.tail.length > 2 * 448 * 1024)
+            this.trim();
+    }
+    trim() {
+        if (this.tail.length <= 448 * 1024)
+            return;
+        this.tail = this.tail.slice(-448 * 1024);
+        this.truncated = true;
+    }
+    get text() {
+        this.trim();
+        return this.truncated ? `${this.head}\n[… ${this.total - this.head.length - this.tail.length} characters not shown …]\n${this.tail}` : this.head + this.tail;
+    }
+}
+export class SessionFiles {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    url(id, q, suffix = "") {
+        return `${sid(id)}/files${suffix}${queryString(q)}`;
+    }
+    list(id, path = ".", options) {
+        return this.client.request("GET", this.url(id, { path, list: "1" }), undefined, options);
+    }
+    /** A file's bytes. */
+    read(id, path, options) {
+        return this.client.bytes("GET", this.url(id, { path }), undefined, options);
+    }
+    async readText(id, path, options) {
+        return new TextDecoder().decode(await this.read(id, path, options));
+    }
+    /** Writes a file (folders are made as needed). */
+    write(id, path, data, options) {
+        return this.client.request("PUT", this.url(id, { path }), undefined, {
+            ...options,
+            rawBody: data,
+            headers: { "content-type": "application/octet-stream", ...options?.headers },
+        });
+    }
+    delete(id, path, options) {
+        return this.client.request("DELETE", this.url(id, { path }), undefined, options);
+    }
+    /** Waits for a file matching a glob (e.g. `downloads/*.csv`) that has finished writing. */
+    waitFor(id, pattern, timeoutMs = 30_000, options) {
+        return this.client.request("GET", this.url(id, { pattern, timeoutMs }, "/wait"), undefined, atLeast(this.client, options, timeoutMs + 30_000));
+    }
+}
+// ---------------------------------------------------------------- contexts
+/** Saved logins: cookies and local storage to start sessions with (`context: {id, persist: true}` fills one). */
+export class Contexts {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * A new saved login: empty, or with `fromSession` holding that working session's current cookies and site storage
+     * (sign in there first, e.g. in its live view). `attach: true` also makes the session save to it from now on (at its
+     * checkpoints and when it ends); a session that already has a saved login refuses that (409 `conflict`). 413
+     * `context_too_large` over 16 MB; PlanLimitError (402) past the plan's `maxContexts` or `maxContextBytes`.
+     */
+    create(params = {}, options) {
+        return this.client.request("POST", "/v1/contexts", params, options);
+    }
+    get(id, options) {
+        return this.client.request("GET", `/v1/contexts/${encodeURIComponent(id)}`, undefined, options);
+    }
+    /** Newest first; the first page's `total` counts them all. */
+    list(params = {}, options) {
+        return this.client.list("/v1/contexts", { ...params }, (c) => c, options);
+    }
+    rename(id, name, options) {
+        return this.client.request("PATCH", `/v1/contexts/${encodeURIComponent(id)}`, { name }, options);
+    }
+    delete(id, options) {
+        return this.client.request("DELETE", `/v1/contexts/${encodeURIComponent(id)}`, undefined, options);
+    }
+    /**
+     * Keeps sign-in details on the saved login (plan feature `loginDetails`), replacing earlier ones: the site, user name,
+     * password and optionally the 2FA setup key, sealed like secrets. Returns the context, whose `login` shows
+     * `{origin, username, hasPassword, hasTotp}`, never the password or the 2FA secret.
+     */
+    setLogin(id, details, options) {
+        return this.client.request("PUT", `/v1/contexts/${encodeURIComponent(id)}/login`, details, options);
+    }
+    /**
+     * Changes some of the login details and keeps the rest (setLogin replaces them all); `totpSecret: null` removes 2FA.
+     * A password never moves to another site on its own: a new `origin` needs `password` in the same call, and
+     * `totpSecret` (a new one or null) when the login has 2FA (400 otherwise). A BoxlineError with code `conflict` (409)
+     * when the login changed meanwhile: send it again.
+     */
+    updateLogin(id, changes, options) {
+        return this.client.request("PATCH", `/v1/contexts/${encodeURIComponent(id)}/login`, changes, options);
+    }
+    /** Removes the login details (the saved cookies and storage stay). */
+    deleteLogin(id, options) {
+        return this.client.request("DELETE", `/v1/contexts/${encodeURIComponent(id)}/login`, undefined, options);
+    }
+}
+// ---------------------------------------------------------------- secrets
+const secretPath = (name) => `/v1/secrets/${encodeURIComponent(name)}`;
+/**
+ * Project secrets: write-only values the AI uses as %NAME% placeholders (`secrets` on agent runs, steps and scripts) and
+ * shells get as environment variables (`secrets` on sessions.create and exec), depending on each secret's `scope`. The
+ * value is never returned, logged or shown; every change and use is audited.
+ */
+export class Secrets {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** The project's secrets, in name order, without their values. */
+    list(params = {}, options) {
+        return this.client.list("/v1/secrets", { ...params }, (s) => s, options);
+    }
+    /**
+     * Stores a secret, sealed; the answer never has the value. SecretExistsError for a name the project has (change it
+     * with update), PlanLimitError beyond the plan's `maxSecrets`. Not retried by the SDK (the API takes no
+     * Idempotency-Key here): a retry after a lost answer may meet SecretExistsError.
+     */
+    create(params, options) {
+        return this.client.request("POST", "/v1/secrets", params, options);
+    }
+    get(name, options) {
+        return this.client.request("GET", secretPath(name), undefined, options);
+    }
+    /**
+     * Changes the fields you send. A running agent run keeps the value it started with; a session that exports the secret
+     * gets the new value on its next machine (move, resume, recovery).
+     */
+    update(name, patch, options) {
+        return this.client.request("PATCH", secretPath(name), patch, options);
+    }
+    /** Deletes it; sessions that exported it no longer get it on their next machine. */
+    delete(name, options) {
+        return this.client.request("DELETE", secretPath(name), undefined, options);
+    }
+    /** Changes to secrets and saved login details, and each use (once per session, command, run or script), newest first. */
+    audit(params = {}, options) {
+        return this.client.list("/v1/secrets/audit", { ...params }, (e) => e, options);
+    }
+}
+// ---------------------------------------------------------------- crawl
+/** Crawls: follow links from a start URL in the background (robots.txt respected); poll with get() or wait(). */
+export class Crawl {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    start(params, options) {
+        return this.client.request("POST", "/v1/crawl", params, options);
+    }
+    /** The job and one page of its pages (`limit: 0` for the job only); `next` is the cursor of the following pages. */
+    get(id, params = {}, options) {
+        return this.client.request("GET", `/v1/crawl/${encodeURIComponent(id)}${queryString({ ...params })}`, undefined, options);
+    }
+    /** Jobs, newest first (without their pages). */
+    list(params = {}, options) {
+        return this.client.list("/v1/crawl", { ...params }, (j) => j, options);
+    }
+    cancel(id, options) {
+        return this.client.request("POST", `/v1/crawl/${encodeURIComponent(id)}/cancel`, undefined, options);
+    }
+    /** Every page crawled so far, in index order: `for await (const p of bx.crawl.pages(id))`. */
+    async *pages(id, params = {}, options) {
+        let after;
+        do {
+            const job = await this.get(id, { limit: params.limit ?? 100, after }, options);
+            yield* job.data;
+            after = job.next ?? undefined;
+        } while (after);
+    }
+    /** Waits for the crawl to finish, then returns the job with every page in `data`. */
+    async wait(id, opts = {}, options) {
+        const deadline = Date.now() + (opts.timeoutMs ?? 30 * 60_000);
+        let job = await this.get(id, { limit: 0 }, options);
+        while (job.status === "running") {
+            if (Date.now() > deadline)
+                throw new BoxlineTimeoutError("the crawl did not finish in time");
+            await new Promise((r) => setTimeout(r, opts.pollMs ?? 1000));
+            job = await this.get(id, { limit: 0 }, options);
+        }
+        const data = [];
+        for await (const p of this.pages(id, {}, options))
+            data.push(p);
+        return { ...job, data, next: null };
+    }
+}
+// ---------------------------------------------------------------- webhooks
+const whid = (id) => `/v1/webhooks/${encodeURIComponent(id)}`;
+/**
+ * Webhook endpoints: signed HTTPS callbacks when something finishes or needs a person. Verify each delivery with
+ * verifyWebhook(rawBody, header, secret) and drop event ids you have handled already.
+ */
+export class Webhooks {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** A new endpoint (public HTTPS only); `secret` ("whsec_…") is in this response only. */
+    create(params, options) {
+        return this.client.request("POST", "/v1/webhooks", params, options);
+    }
+    /** The project's endpoints, oldest first (never their secrets). */
+    list(params = {}, options) {
+        return this.client.list("/v1/webhooks", { ...params }, (w) => w, options);
+    }
+    get(id, options) {
+        return this.client.request("GET", whid(id), undefined, options);
+    }
+    /** Changes the URL, events, description, or switches it on or off (`enabled: true` also forgets its failures). */
+    update(id, patch, options) {
+        return this.client.request("PATCH", whid(id), patch, options);
+    }
+    /** Deletes the endpoint with its queue and delivery log. */
+    delete(id, options) {
+        return this.client.request("DELETE", whid(id), undefined, options);
+    }
+    /** A new secret (in this response only); the old one keeps signing too for 24 hours (a second v1). */
+    rotateSecret(id, options) {
+        return this.client.request("POST", `${whid(id)}/rotate-secret`, undefined, options);
+    }
+    /**
+     * Sends a `webhook.test` event to this endpoint now, or with `type` a made-up sample of that event type (marked
+     * `test: true`); one attempt, waits up to 12 s for the answer.
+     */
+    test(id, params = {}, options) {
+        return this.client.request("POST", `${whid(id)}/test`, params.type ? { type: params.type } : undefined, options);
+    }
+    /** Every event type an endpoint can subscribe to, with its group and description (subscribe to "*" for all). */
+    eventTypes(options) {
+        return this.client.request("GET", "/v1/webhooks/events", undefined, options);
+    }
+    /** The endpoint's deliveries, newest first, each with its attempt history; `status` filters them. */
+    deliveries(id, params = {}, options) {
+        return this.client.list(`${whid(id)}/deliveries`, { ...params }, (d) => d, options);
+    }
+    /**
+     * Sends a finished delivery again now, with the same event id and body (409 invalid_state while it is still queued,
+     * PayloadExpiredError after 7 days, WebhookDisabledError while the endpoint is switched off).
+     */
+    retryDelivery(id, deliveryId, options) {
+        return this.client.request("POST", `${whid(id)}/deliveries/${encodeURIComponent(deliveryId)}/retry`, undefined, options);
+    }
+}
+// ---------------------------------------------------------------- tasks
+const tid = (id) => `/v1/tasks/${encodeURIComponent(id)}`;
+/** The task-run statuses of a run that has not finished (queued: a scheduled run waiting for its turn). */
+const TASK_RUN_OPEN = ["queued", "running", "paused"];
+/**
+ * Tasks: saved agent runs (an instruction with %name% variables, an optional output schema, browser settings, a saved
+ * login and a model), run by hand or on a schedule. Every run is an agent run tagged with the task. Needs the plan's
+ * `agentRuns`; the plan limits tasks and schedules switched on (PlanLimitError).
+ */
+export class Tasks {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Saves a task (an Idempotency-Key is sent, so a retry never saves it twice). */
+    create(params, options) {
+        return this.client.request("POST", "/v1/tasks", params, options);
+    }
+    /** The project's tasks, newest first. */
+    list(params = {}, options) {
+        return this.client.list("/v1/tasks", { ...params }, (t) => t, options);
+    }
+    get(id, options) {
+        return this.client.request("GET", tid(id), undefined, options);
+    }
+    /**
+     * Changes the fields you send; `null` removes an optional one. `schedule` fields are merged into the current schedule
+     * (`{schedule: {enabled: false}}` pauses it); switching it on, or changing cron or timezone, counts from now.
+     */
+    update(id, patch, options) {
+        return this.client.request("PATCH", tid(id), patch, options);
+    }
+    /** Deletes the task with its run history (its agent runs stay, and runs in progress go on). */
+    delete(id, options) {
+        return this.client.request("DELETE", tid(id), undefined, options);
+    }
+    /**
+     * Runs the task now and returns its task run (status running) right away; waitForRun() waits for the result. Plain
+     * values are written into the instruction; secret ones must come with every run and go in as agent variables (the
+     * model sees only %name%). MissingVariablesError when a variable without a default has no value. Counts as an agent
+     * run (rate, plan, spend cap). An Idempotency-Key is sent, so a retry never starts a second run. `T`: the type of the
+     * result (the JSON answer when the task has an output schema).
+     */
+    run(id, params = {}, options) {
+        return this.client.request("POST", `${tid(id)}/runs`, params, options);
+    }
+    /** The task's runs, newest first: by hand, on the schedule, and skipped or missed times (kept 30 days); `status` filters. */
+    runs(id, params = {}, options) {
+        return this.client.list(`${tid(id)}/runs`, { ...params }, (r) => r, options);
+    }
+    async waitForRun(first, second, third, fourth) {
+        const byIds = typeof first === "string";
+        const taskId = byIds ? first : first.taskId;
+        const runId = byIds ? second : first.id;
+        const opts = ((byIds ? third : second) ?? {});
+        const options = (byIds ? fourth : third);
+        const deadline = Date.now() + (opts.timeoutMs ?? 30 * 60_000);
+        for (;;) {
+            // There is no GET for one task run: the unfinished ones are a short list, and a run missing from it has finished.
+            let open = false;
+            for await (const r of this.runs(taskId, { status: TASK_RUN_OPEN, limit: 100 }, options)) {
+                if (r.id === runId) {
+                    open = true;
+                    break;
+                }
+            }
+            if (!open) {
+                for await (const r of this.runs(taskId, { limit: 100 }, options))
+                    if (r.id === runId)
+                        return r;
+                throw new NotFoundError(404, ErrorCode.notFound, `task run ${runId} is not in the run history of task ${taskId}`);
+            }
+            if (Date.now() > deadline)
+                throw new BoxlineTimeoutError("the task run did not finish in time");
+            await new Promise((r) => setTimeout(r, opts.pollMs ?? 1000));
+        }
+    }
+}
+// ---------------------------------------------------------------- extensions
+/** A file's bytes (Node, Deno, Bun); kept out of static imports so browser bundles never see node:fs. */
+async function readFileBytes(path) {
+    const fs = (await import(["node", "fs/promises"].join(":")));
+    return new Uint8Array(await fs.readFile(path));
+}
+/**
+ * Chrome extensions (Manifest V3) to start sessions with (`extensions: [id]`; plan feature `extensions`). An extension
+ * sees every page and every typed value in the sessions that use it: upload only extensions you trust.
+ */
+export class Extensions {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Uploads an unpacked extension as a zip, at most 10 MB: its bytes, a Blob, or a file path (Node). It is checked
+     * before it is stored (InvalidExtensionError says why; PayloadTooLargeError over 10 MB; LimitReachedError beyond 100
+     * extensions). An Idempotency-Key is sent, so a retry never stores it twice.
+     */
+    async upload(zip, options) {
+        const body = typeof zip === "string" ? await readFileBytes(zip) : zip instanceof ArrayBuffer ? new Uint8Array(zip) : zip;
+        return this.client.request("POST", "/v1/extensions", undefined, {
+            ...options,
+            rawBody: body,
+            headers: { "content-type": "application/zip", ...options?.headers },
+        });
+    }
+    /** The project's extensions, newest first. */
+    list(params = {}, options) {
+        return this.client.list("/v1/extensions", { ...params }, (e) => e, options);
+    }
+    get(id, options) {
+        return this.client.request("GET", `/v1/extensions/${encodeURIComponent(id)}`, undefined, options);
+    }
+    /** Deletes it; sessions already running with it keep it until they move or resume. */
+    delete(id, options) {
+        return this.client.request("DELETE", `/v1/extensions/${encodeURIComponent(id)}`, undefined, options);
+    }
+}
+// ---------------------------------------------------------------- agent
+/** Agent runs: a model (Claude or GPT) drives the session's browser and shell to finish a task. */
+export class Agent {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Providers and models customers can choose, with prices and whether each is configured on the server. */
+    models(options) {
+        return this.client.request("GET", "/v1/agent/models", undefined, options);
+    }
+    /**
+     * Starts a run and returns right away (an Idempotency-Key is sent, so a retry never starts a second run). With
+     * `output` (a JSON Schema) the answer is JSON matching it: read it with `wait<T>(id)` or `get<T>(id)`.
+     */
+    run(params, options) {
+        return this.client.request("POST", "/v1/agent/runs", params, options);
+    }
+    /** The run with its steps. `T`: the type of `result` (text by default; the JSON answer's type with an output schema). */
+    get(id, options) {
+        return this.client.request("GET", `/v1/agent/runs/${encodeURIComponent(id)}`, undefined, options);
+    }
+    /** Runs, newest first. */
+    list(params = {}, options) {
+        return this.client.list("/v1/agent/runs", { ...params }, (r) => r, options);
+    }
+    /** Take the browser from the agent (it finishes its current action, then waits). RunNotLiveError when its server stopped. */
+    takeover(id, reason, options) {
+        return this.client.request("POST", `/v1/agent/runs/${encodeURIComponent(id)}/takeover`, reason === undefined ? {} : { reason }, options);
+    }
+    /** Give the browser back; the agent reads `note` before it continues. RunNotLiveError when its server stopped: continueRun. */
+    handBack(id, note, options) {
+        return this.client.request("POST", `/v1/agent/runs/${encodeURIComponent(id)}/handback`, note === undefined ? {} : { note }, options);
+    }
+    /** Stops the run for good. */
+    cancel(id, options) {
+        return this.client.request("POST", `/v1/agent/runs/${encodeURIComponent(id)}/cancel`, undefined, options);
+    }
+    /**
+     * Continues a run that stopped at one of its limits (errorCode max_steps, max_cost, too_many_errors or no_progress)
+     * while its `continuable` is set: a new run in the same session, with the same model, mode, output schema, secrets
+     * and saved login, and a compact record of what the previous run did. Returns the new run (`continuedFrom` links
+     * back); wait for it with `wait(run.id)` or `stream(run.id)` like any run. A run that had `variables` needs them again
+     * (MissingVariablesError otherwise). NotContinuableError: it did not stop at a limit, was continued already, or its
+     * window passed. An Idempotency-Key is sent, so a retry never starts a second run.
+     *
+     * `const next = await bx.agent.continueRun(run.id, { maxSteps: 30, instruction: "The CSV is downloaded already" })`
+     */
+    continueRun(id, params = {}, options) {
+        return this.client.request("POST", `/v1/agent/runs/${encodeURIComponent(id)}/continue`, params, options);
+    }
+    /**
+     * Tells a working run something (1–2000 characters) without taking the browser: the agent reads it at its next step
+     * (a model call or tool under way is not interrupted), and it shows as a `message` step. A run waiting for your help
+     * (ask_user_for_help) takes it as the answer and goes on. At most 50 per run; InvalidStateError-like 409
+     * (a BoxlineError with code `invalid_state`) once the run has finished, TooManyMessagesError after 50.
+     */
+    sendMessage(id, text, options) {
+        return this.client.request("POST", `/v1/agent/runs/${encodeURIComponent(id)}/messages`, { text }, options);
+    }
+    /**
+     * The run as it happens: its steps so far, then new steps, `status` changes, live shell `exec`/`output`, and a
+     * final `done` event, after which the iteration ends.
+     */
+    async *stream(id, options) {
+        const res = await this.client.send("GET", `/v1/agent/runs/${encodeURIComponent(id)}/events`, undefined, options);
+        for await (const event of sse(res.body)) {
+            yield event;
+            if (event.type === "done")
+                return;
+        }
+    }
+    /**
+     * Polls until the run finishes (a paused run keeps waiting for the user). `T` as on get():
+     * `const run = await bx.agent.wait<{ books: Book[] }>(id)`.
+     */
+    async wait(id, opts = {}, options) {
+        const deadline = Date.now() + (opts.timeoutMs ?? 30 * 60_000);
+        for (;;) {
+            const run = await this.get(id, options);
+            if (run.status !== "running" && run.status !== "paused")
+                return run;
+            if (Date.now() > deadline)
+                throw new BoxlineTimeoutError("the agent run did not finish in time");
+            await new Promise((r) => setTimeout(r, opts.pollMs ?? 1000));
+        }
+    }
+}
+export default Boxline;
+//# sourceMappingURL=client.js.map