@scalebrowser/sdk 0.2.0

package/dist/index.js

@@ -0,0 +1,1239 @@
+import WebSocket from 'ws';
+
+// src/errors.ts
+var ErrorCode = {
+  NotFound: 4001,
+  ProxyGeo: 4002,
+  Capacity: 4003,
+  EngineMissing: 4004,
+  Preflight: 4005,
+  AlreadyRunning: 4006,
+  /** Retired: the removed Methode-D (VM) tier produced this. Reserved (never reused)
+   * to match the server's append-only code contract; never returned now. */
+  VmProvisionFailed: 4007,
+  /** The subscription's abo-wide concurrent-browser allowance is used up (DEC-012).
+   * Distinct from Capacity (4003 = this machine is full, wait): the caller's move
+   * is to stop a running browser anywhere or upgrade the plan. */
+  ConcurrencyLimit: 4008,
+  Unauthorized: 4010
+};
+var CODE_LABELS = {
+  4001: "Not found",
+  4002: "Proxy or geo check failed",
+  4003: "Capacity exceeded",
+  4004: "Engine missing",
+  4005: "Launch preflight failed",
+  4006: "Profile already running",
+  4008: "Concurrent-browser limit reached (subscription-wide)",
+  4010: "Unauthorized"
+};
+var ScalebrowserError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var ApiError = class extends ScalebrowserError {
+  status;
+  code;
+  body;
+  constructor(status, body, fallbackMessage) {
+    const label = body?.code ? CODE_LABELS[body.code] : void 0;
+    super(body?.message || label || fallbackMessage || `Request failed (HTTP ${status})`);
+    this.status = status;
+    this.code = body?.code;
+    this.body = body;
+  }
+  /** True for auth failures that must trigger re-authentication. */
+  get isAuthError() {
+    return this.status === 401 || this.code === ErrorCode.Unauthorized;
+  }
+  /** Short label for the error code, if any. */
+  get codeLabel() {
+    return this.code ? CODE_LABELS[this.code] : void 0;
+  }
+};
+var NetworkError = class extends ScalebrowserError {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+  }
+};
+var CdpError = class extends ScalebrowserError {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+};
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+// src/client-core.ts
+var DEFAULT_BASE_URL = "http://127.0.0.1:8787";
+var ClientCore = class {
+  baseUrl;
+  #token;
+  #fetch;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.#token = options.token ?? null;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+  }
+  /** For subclasses that hand the token to a sibling transport (SSE, CDP). */
+  get token() {
+    return this.#token;
+  }
+  get fetchImpl() {
+    return this.#fetch;
+  }
+  /** Rotate the Bearer token at runtime. */
+  setToken(token) {
+    this.#token = token && token.trim() ? token.trim() : null;
+  }
+  // ── Internals ────────────────────────────────────────────────────────────
+  async request(method, path, body, opts) {
+    const headers = {};
+    if (this.#token) headers["Authorization"] = `Bearer ${this.#token}`;
+    let payload;
+    if (body instanceof Uint8Array || body instanceof ArrayBuffer) {
+      headers["Content-Type"] = "application/octet-stream";
+      payload = body instanceof ArrayBuffer ? new Uint8Array(body) : body;
+    } else if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+    let res;
+    try {
+      res = await this.#fetch(this.#buildUrl(path, opts?.query), {
+        method,
+        headers,
+        body: payload,
+        signal: opts?.signal
+      });
+    } catch (cause) {
+      throw new NetworkError("Could not reach the daemon. Is it running?", cause);
+    }
+    if (!res.ok) {
+      throw new ApiError(res.status, await safeJson(res), res.status === 401 ? "Unauthorized" : void 0);
+    }
+    if (res.status === 204) return void 0;
+    const text = await res.text();
+    return text ? JSON.parse(text) : void 0;
+  }
+  /**
+   * A route that answers with bytes, not JSON — artifacts and run stills.
+   *
+   * Separate from {@link ClientCore.request} rather than a flag on it, because the two
+   * differ in the error path as well: a failed byte fetch still answers JSON,
+   * so the mapping to {@link ApiError} has to happen before the body is read as
+   * binary.
+   */
+  async requestBytes(method, path, opts) {
+    const headers = {};
+    if (this.#token) headers["Authorization"] = `Bearer ${this.#token}`;
+    let res;
+    try {
+      res = await this.#fetch(this.#buildUrl(path, opts?.query), {
+        method,
+        headers,
+        signal: opts?.signal
+      });
+    } catch (cause) {
+      throw new NetworkError("Could not reach the daemon. Is it running?", cause);
+    }
+    if (!res.ok) {
+      throw new ApiError(res.status, await safeJson(res), res.status === 401 ? "Unauthorized" : void 0);
+    }
+    const disposition = res.headers.get("content-disposition");
+    return {
+      bytes: new Uint8Array(await res.arrayBuffer()),
+      content_type: res.headers.get("content-type"),
+      filename: parseFilename(disposition)
+    };
+  }
+  #buildUrl(path, query) {
+    const url = this.baseUrl + path;
+    if (!query) return url;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0 && value !== null && value !== "") params.append(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `${url}?${qs}` : url;
+  }
+  /** Never leak the token in logs / inspection. */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return `${this.constructor.name} { baseUrl: '${this.baseUrl}', token: ${this.#token ? "'***'" : "null"} }`;
+  }
+};
+function applyMixins(target, mixins) {
+  for (const mixin of mixins) {
+    for (const name of Object.getOwnPropertyNames(mixin.prototype)) {
+      if (name === "constructor") continue;
+      Object.defineProperty(
+        target.prototype,
+        name,
+        Object.getOwnPropertyDescriptor(mixin.prototype, name)
+      );
+    }
+  }
+}
+function parseFilename(disposition) {
+  if (!disposition) return null;
+  const match = /filename="([^"]*)"/.exec(disposition) ?? /filename=([^;]+)/.exec(disposition);
+  const name = match?.[1]?.trim();
+  return name ? name : null;
+}
+async function safeJson(res) {
+  try {
+    const text = await res.text();
+    return text ? JSON.parse(text) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function enc(id) {
+  return encodeURIComponent(id);
+}
+
+// src/client-control.ts
+var SELF_HOSTED = {
+  licensed: false,
+  running_local: 0,
+  profiles_local: 0,
+  permits_launch: true
+};
+var ControlApi = class extends ClientCore {
+  // ── Interruptions ──────────────────────────────────────────────────────────
+  /** Which browser surfaces are locked shut, and what actually applies. */
+  listInterruptionLocks(signal) {
+    return this.request("GET", "/v1/interruptions/locks", void 0, { signal });
+  }
+  /** Omit `profile_id` to set the fleet-wide default. */
+  setInterruptionLock(body) {
+    return this.request("PUT", "/v1/interruptions/locks", body);
+  }
+  /** Standing answers per origin and kind. */
+  listInterruptionRules(signal) {
+    return this.request("GET", "/v1/interruptions/rules", void 0, { signal });
+  }
+  setInterruptionRule(body) {
+    return this.request("PUT", "/v1/interruptions/rules", body);
+  }
+  deleteInterruptionRule(params) {
+    return this.request("DELETE", "/v1/interruptions/rules", void 0, {
+      query: { origin: params.origin, kind: params.kind, profile_id: params.profile_id }
+    });
+  }
+  // ── Artifacts ──────────────────────────────────────────────────────────────
+  /**
+   * Hand the daemon a file so `interact action=upload` has something to attach.
+   *
+   * The bytes are bound to the PROFILE, not to a reservation: set a file up
+   * before leasing, and a lease released mid-task does not destroy it.
+   */
+  putArtifact(profileId, bytes, name) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/artifacts`, bytes, {
+      query: { name }
+    });
+  }
+  /**
+   * Fetch one artifact's bytes — a screenshot, a download, a saved PDF.
+   *
+   * A miss is a plain 404 whether the id never existed, expired, or belonged to
+   * a released lease: the caller's next move is the same in all three cases.
+   */
+  getArtifact(artifactId, signal) {
+    return this.requestBytes("GET", `/v1/artifacts/${enc(artifactId)}`, { signal });
+  }
+  // ── Account + health ───────────────────────────────────────────────────────
+  /**
+   * Licence state for display. The launch gate stays the authority on starts.
+   *
+   * A daemon predating the route answers 404, and that is not an error worth
+   * throwing: it means "self-hosted, no control plane", which is exactly what
+   * `licensed: false` says. Same shape of tolerance as {@link getMetrics}.
+   */
+  async getAccount(signal) {
+    try {
+      return await this.request("GET", "/v1/account", void 0, { signal });
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 404) return { ...SELF_HOSTED };
+      throw err;
+    }
+  }
+  /** "Is the daemon alive?" Public, needs no token. */
+  health(signal) {
+    return this.request("GET", "/health", void 0, { signal });
+  }
+  /** "Can it serve?" Local facts only — the control plane is deliberately not consulted. */
+  ready(signal) {
+    return this.request("GET", "/health/ready", void 0, { signal });
+  }
+};
+
+// src/client-extensions.ts
+var ExtensionsApi = class extends ClientCore {
+  // ── Extension library (daemon-wide) ─────────────────────────────────────────
+  //
+  // Upload a `.crx`; the daemon lifts its public key out of the CRX header and
+  // writes it into the unpacked `manifest.json`, so every profile loads the
+  // package under its CANONICAL Web-Store id. A key-less package is refused — it
+  // would take a path-derived id, identical across the fleet.
+  /** The library, newest first. */
+  listLibraryExtensions(signal) {
+    return this.request("GET", "/v1/extensions", void 0, { signal });
+  }
+  /**
+   * Add a package. `crx` is the raw `.crx` file. A new VERSION is stocked alongside the
+   * existing ones (profiles draw their own); re-uploading the same version replaces it.
+   */
+  uploadExtension(crx) {
+    return this.request("POST", "/v1/extensions", crx);
+  }
+  /** One library entry — the most recently added version. */
+  getLibraryExtension(id, signal) {
+    return this.request("GET", `/v1/extensions/${enc(id)}`, void 0, { signal });
+  }
+  /** Remove EVERY version of a package, its files and every profile's assignment of it. */
+  deleteLibraryExtension(id) {
+    return this.request("DELETE", `/v1/extensions/${enc(id)}`);
+  }
+  /**
+   * Remove ONE stocked version.
+   *
+   * Assignments survive — they name the extension, not the version — unless this
+   * was the last version, in which case they go with it.
+   */
+  deleteLibraryExtensionVersion(id, version) {
+    return this.request("DELETE", `/v1/extensions/${enc(id)}/${enc(version)}`);
+  }
+  // ── Extensions per profile ──────────────────────────────────────────────────
+  //
+  // `extRef` is a LIBRARY ID, not a path. The launch copies each assigned package
+  // into the profile's own tree and loads that, so files and state stay per-profile
+  // while the id stays shared (which is the camouflage, not the leak).
+  /** The profile's assigned set, resolved, + the launch policy. */
+  listExtensions(profileId, signal) {
+    return this.request(
+      "GET",
+      `/v1/profiles/${enc(profileId)}/extensions`,
+      void 0,
+      { signal }
+    );
+  }
+  /** Assign a library id (idempotent) → the updated set + policy. 404 if unknown. */
+  attachExtension(profileId, extRef) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/extensions`, {
+      ext_ref: extRef
+    });
+  }
+  /** Unassign a library id (idempotent) → the updated set + policy. */
+  detachExtension(profileId, extRef) {
+    return this.request("DELETE", `/v1/profiles/${enc(profileId)}/extensions`, {
+      ext_ref: extRef
+    });
+  }
+};
+
+// src/client-identity.ts
+var IdentityApi = class extends ClientCore {
+  // ── Platform credentials ────────────────────────────────────────────────────
+  //
+  // Stored logins, so an agent can sign a profile into a platform WITHOUT ever
+  // holding the password — the daemon decrypts and types it. Only `revealCredential`
+  // and the bundle calls return plaintext, and every one of them needs the vault
+  // password: the bearer token alone is not enough, because the MCP agent layer
+  // authenticates with exactly the same one.
+  //
+  // `platform` is whatever you have: the service's domain ("discord.com"), its
+  // name ("Discord") or a host under it ("www.discord.com"). The daemon resolves
+  // all of them to ONE key — the registrable domain — and every response echoes
+  // that key, so `listCredentials` and a later `deleteCredential` agree. Pass a
+  // whole sign-in URL only to the MCP tools: here the platform is a path segment,
+  // and a `/` in it is refused rather than read as a path.
+  /** Which platforms this profile can log into. Never carries a secret. */
+  listCredentials(profileId, signal) {
+    return this.request(
+      "GET",
+      `/v1/profiles/${enc(profileId)}/credentials`,
+      void 0,
+      { signal }
+    );
+  }
+  /**
+   * Store or update one login.
+   *
+   * An omitted secret keeps its stored value rather than clearing it — an edit form
+   * never saw the password in the clear, so it cannot resend one; delete the row to
+   * remove a credential. `totp_secret` may be pasted exactly as a site presents it
+   * (grouped, lower case): it is normalised and test-decoded by the daemon, so a
+   * broken key is refused here rather than half-way through a login.
+   */
+  putCredential(profileId, platform, body) {
+    return this.request(
+      "PUT",
+      `/v1/profiles/${enc(profileId)}/credentials/${enc(platform)}`,
+      body
+    );
+  }
+  /** Forget one login. The account itself is untouched. */
+  deleteCredential(profileId, platform) {
+    return this.request(
+      "DELETE",
+      `/v1/profiles/${enc(profileId)}/credentials/${enc(platform)}`
+    );
+  }
+  /** Read one login back in the clear. Needs the vault password. */
+  revealCredential(profileId, platform, vaultPassword) {
+    return this.request(
+      "POST",
+      `/v1/profiles/${enc(profileId)}/credentials/${enc(platform)}/reveal`,
+      { vault_password: vaultPassword }
+    );
+  }
+  /**
+   * Pack this profile's logins into a bundle sealed with `password`.
+   *
+   * `password` is deliberately separate from the vault password: a backup gets
+   * handed to another machine, and that must not also hand over daemon access. This
+   * is the answer to a lost master key — a daemon-generated password exists nowhere
+   * else.
+   */
+  exportCredentials(profileId, vaultPassword, password) {
+    return this.request(
+      "POST",
+      `/v1/profiles/${enc(profileId)}/credential-bundle/export`,
+      { vault_password: vaultPassword, password }
+    );
+  }
+  /** Restore a bundle into this profile. */
+  importCredentials(profileId, vaultPassword, password, bundle) {
+    return this.request(
+      "POST",
+      `/v1/profiles/${enc(profileId)}/credential-bundle/import`,
+      { vault_password: vaultPassword, password, bundle }
+    );
+  }
+  /** Has a vault password been set on this daemon? */
+  vaultStatus(signal) {
+    return this.request("GET", "/v1/vault", void 0, { signal });
+  }
+  /** Set the vault password, or change it (then `currentPassword` is required). */
+  setVaultPassword(newPassword, currentPassword) {
+    return this.request("PUT", "/v1/vault", {
+      new_password: newPassword,
+      current_password: currentPassword
+    });
+  }
+  // ── Mailboxes ──────────────────────────────────────────────────────────────
+  /** Mailboxes, passwords never returned. */
+  listInboxes(signal) {
+    return this.request("GET", "/v1/inboxes", void 0, { signal });
+  }
+  createInbox(body) {
+    return this.request("POST", "/v1/inboxes", body);
+  }
+  /** An omitted `password` leaves the stored one unchanged. */
+  updateInbox(inboxId, body) {
+    return this.request("PUT", `/v1/inboxes/${enc(inboxId)}`, body);
+  }
+  deleteInbox(inboxId) {
+    return this.request("DELETE", `/v1/inboxes/${enc(inboxId)}`);
+  }
+  /** Which mailbox a profile's confirmation codes arrive in, per channel. */
+  getInboxBindings(profileId, signal) {
+    return this.request("GET", `/v1/profiles/${enc(profileId)}/inbox`, void 0, {
+      signal
+    });
+  }
+  bindInbox(profileId, body) {
+    return this.request("PUT", `/v1/profiles/${enc(profileId)}/inbox`, body);
+  }
+  unbindInbox(profileId, channel) {
+    return this.request("DELETE", `/v1/profiles/${enc(profileId)}/inbox/${enc(channel)}`);
+  }
+  // ── Passkeys ───────────────────────────────────────────────────────────────
+  /** What this profile can sign in to without a password. Metadata only. */
+  listPasskeys(profileId, signal) {
+    return this.request("GET", `/v1/profiles/${enc(profileId)}/passkeys`, void 0, {
+      signal
+    });
+  }
+  /**
+   * Retire a passkey.
+   *
+   * Calling it twice is meaningful: the first call retires a live key and leaves
+   * a headstone, the second clears the headstone for good.
+   */
+  deletePasskey(profileId, credentialId) {
+    return this.request("DELETE", `/v1/profiles/${enc(profileId)}/passkeys/${enc(credentialId)}`);
+  }
+  // ── Cookies ────────────────────────────────────────────────────────────────
+  /**
+   * The one door a cookie VALUE leaves through, and it needs the vault password.
+   *
+   * A session cookie skips both the password and the second factor, which is why
+   * every other cookie surface answers with metadata only.
+   */
+  revealCookies(profileId, body) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/cookies/reveal`, body);
+  }
+};
+
+// src/client-runs.ts
+var RunsApi = class extends ClientCore {
+  // ── Agent runs ─────────────────────────────────────────────────────────────
+  /** Runs, newest first. Read-only, all of it. */
+  listRuns(params = {}, signal) {
+    return this.request("GET", "/v1/runs", void 0, {
+      query: { profile_id: params.profile_id, limit: params.limit, offset: params.offset },
+      signal
+    });
+  }
+  /** One run. */
+  getRun(runId, signal) {
+    return this.request("GET", `/v1/runs/${enc(runId)}`, void 0, { signal });
+  }
+  /** A run's steps, oldest first — the order they happened in. */
+  listRunSteps(runId, params = {}, signal) {
+    return this.request("GET", `/v1/runs/${enc(runId)}/steps`, void 0, {
+      query: { limit: params.limit, offset: params.offset },
+      signal
+    });
+  }
+  /**
+   * The still taken at one step, as JPEG bytes.
+   *
+   * The picture shows a customer's account, so it is decrypted only on the way
+   * out and never cached anywhere shared.
+   */
+  getRunShot(runId, seq, signal) {
+    return this.requestBytes("GET", `/v1/runs/${enc(runId)}/shots/${seq}`, { signal });
+  }
+  /** What every running profile currently shows. */
+  getActivity(signal) {
+    return this.request("GET", "/v1/activity", void 0, { signal });
+  }
+};
+
+// src/events.ts
+var MAX_BACKOFF_MS = 15e3;
+function subscribeEvents(params, handlers) {
+  const controller = new AbortController();
+  const fetchImpl = params.fetch ?? globalThis.fetch;
+  let closed = false;
+  let attempt = 0;
+  let lastSeq = null;
+  let everConnected = false;
+  const setStatus = (s) => handlers.onStatus?.(s);
+  const resync = (dropped) => handlers.onEvent({ type: "resync", dropped, at: Math.floor(Date.now() / 1e3) });
+  const deliver = (event) => {
+    if (typeof event.seq === "number") {
+      if (lastSeq !== null && event.seq > lastSeq + 1) resync(event.seq - lastSeq - 1);
+      lastSeq = event.seq;
+    }
+    handlers.onEvent(event);
+  };
+  async function connect() {
+    while (!closed) {
+      setStatus("connecting");
+      try {
+        const headers = { Accept: "text/event-stream" };
+        if (params.token) headers["Authorization"] = `Bearer ${params.token}`;
+        const res = await fetchImpl(`${params.baseUrl}/v1/events`, {
+          headers,
+          signal: controller.signal
+        });
+        if (res.status === 401) {
+          params.onUnauthorized?.();
+          break;
+        }
+        if (!res.ok || !res.body) {
+          throw new NetworkError(`event stream failed (HTTP ${res.status})`);
+        }
+        attempt = 0;
+        setStatus("open");
+        lastSeq = null;
+        if (everConnected) resync(0);
+        everConnected = true;
+        await pump(res.body, deliver, controller.signal);
+      } catch {
+        if (closed || controller.signal.aborted) break;
+      }
+      if (closed) break;
+      setStatus("connecting");
+      attempt += 1;
+      const delay2 = Math.min(MAX_BACKOFF_MS, 500 * 2 ** Math.min(attempt, 5));
+      await sleep(delay2, controller.signal);
+    }
+    setStatus("closed");
+  }
+  void connect();
+  return () => {
+    closed = true;
+    controller.abort();
+  };
+}
+async function pump(body, onEvent, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (!signal.aborted) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let sep;
+      while ((sep = indexOfFrameEnd(buffer)) !== -1) {
+        const frame = buffer.slice(0, sep);
+        buffer = buffer.slice(sep).replace(/^(\r?\n){1,2}/, "");
+        const event = parseSseFrame(frame);
+        if (event) onEvent(event);
+      }
+    }
+  } finally {
+    void reader.cancel().catch(() => {
+    });
+  }
+}
+function indexOfFrameEnd(buffer) {
+  const lf = buffer.indexOf("\n\n");
+  const crlf = buffer.indexOf("\r\n\r\n");
+  if (lf === -1) return crlf;
+  if (crlf === -1) return lf;
+  return Math.min(lf, crlf);
+}
+function parseSseFrame(frame) {
+  const dataLines = [];
+  for (const line of frame.split(/\r?\n/)) {
+    if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  if (dataLines.length === 0) return null;
+  const payload = dataLines.join("\n");
+  if (!payload || payload === "[DONE]") return null;
+  try {
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+}
+function eventStream(params) {
+  const buffer = [];
+  const waiters = [];
+  let done = false;
+  const unsubscribe = subscribeEvents(params, {
+    onEvent: (event) => {
+      const waiter = waiters.shift();
+      if (waiter) waiter({ value: event, done: false });
+      else buffer.push(event);
+    }
+  });
+  const finish = () => {
+    if (!done) {
+      done = true;
+      unsubscribe();
+      for (const w of waiters.splice(0)) w({ value: void 0, done: true });
+    }
+    return { value: void 0, done: true };
+  };
+  return {
+    next() {
+      const next = buffer.shift();
+      if (next !== void 0) return Promise.resolve({ value: next, done: false });
+      if (done) return Promise.resolve({ value: void 0, done: true });
+      return new Promise((resolve) => waiters.push(resolve));
+    },
+    return() {
+      return Promise.resolve(finish());
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    }
+  };
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const t = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+var CdpConnection = class {
+  #ws;
+  #nextId = 0;
+  #pending = /* @__PURE__ */ new Map();
+  #subscribers = /* @__PURE__ */ new Set();
+  #closeListeners = /* @__PURE__ */ new Set();
+  #closeReason = null;
+  constructor(ws) {
+    this.#ws = ws;
+    ws.on("message", (data) => this.#onMessage(data));
+    ws.on("close", () => this.#onClose(new CdpError(-1, "CDP connection closed")));
+    ws.on("error", (err) => this.#onClose(new NetworkError("CDP connection error", err)));
+  }
+  request(method, params, sessionId) {
+    if (this.#closeReason) return Promise.reject(this.#closeReason);
+    const id = ++this.#nextId;
+    const frame = { id, method };
+    if (params !== void 0) frame["params"] = params;
+    if (sessionId !== void 0) frame["sessionId"] = sessionId;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#ws.send(JSON.stringify(frame), (err) => {
+        if (err) {
+          this.#pending.delete(id);
+          reject(new NetworkError("failed to send CDP command", err));
+        }
+      });
+    });
+  }
+  subscribe(cb) {
+    this.#subscribers.add(cb);
+    return () => this.#subscribers.delete(cb);
+  }
+  /** Register a callback fired once when the connection closes (immediately if
+   *  it already has) — event streams use this to end instead of hanging. */
+  onClose(cb) {
+    if (this.#closeReason) {
+      cb();
+      return () => {
+      };
+    }
+    this.#closeListeners.add(cb);
+    return () => this.#closeListeners.delete(cb);
+  }
+  close() {
+    this.#ws.close();
+  }
+  get closed() {
+    return this.#closeReason !== null;
+  }
+  #onMessage(data) {
+    let frame;
+    try {
+      frame = JSON.parse(rawToString(data));
+    } catch {
+      return;
+    }
+    if (typeof frame.id === "number") {
+      const pending = this.#pending.get(frame.id);
+      if (!pending) return;
+      this.#pending.delete(frame.id);
+      if (frame.error) pending.reject(new CdpError(frame.error.code, frame.error.message, frame.error.data));
+      else pending.resolve(frame.result);
+      return;
+    }
+    if (typeof frame.method === "string") {
+      const event = { method: frame.method, params: frame.params ?? {}, sessionId: frame.sessionId };
+      for (const cb of [...this.#subscribers]) cb(event);
+    }
+  }
+  #onClose(reason) {
+    if (this.#closeReason) return;
+    this.#closeReason = reason;
+    for (const [, pending] of this.#pending) pending.reject(reason);
+    this.#pending.clear();
+    this.#subscribers.clear();
+    for (const cb of [...this.#closeListeners]) cb();
+    this.#closeListeners.clear();
+  }
+};
+function rawToString(data) {
+  if (typeof data === "string") return data;
+  if (Buffer.isBuffer(data)) return data.toString("utf8");
+  if (Array.isArray(data)) return Buffer.concat(data).toString("utf8");
+  return Buffer.from(data).toString("utf8");
+}
+var CdpSession = class _CdpSession {
+  #conn;
+  sessionId;
+  #client;
+  #profileId;
+  #isolatedContextId;
+  constructor(conn, sessionId, client, profileId) {
+    this.#conn = conn;
+    this.sessionId = sessionId;
+    this.#client = client;
+    this.#profileId = profileId;
+  }
+  /** Send a raw CDP command and await its result (by id). */
+  send(method, params) {
+    return this.#conn.request(method, params, this.sessionId);
+  }
+  /** Register a callback for a CDP event scoped to this session. Returns unsubscribe. */
+  on(method, callback) {
+    return this.#conn.subscribe((event) => {
+      if (event.method === method && event.sessionId === this.sessionId) callback(event.params);
+    });
+  }
+  /** `for await (const event of session.events())` over this session's CDP events. */
+  events() {
+    return scopedEventStream(this.#conn, this.sessionId);
+  }
+  /** Attach to a page target, returning a page-bound child session. */
+  async attachToPage(opts = {}) {
+    let targetId = opts.targetId;
+    if (opts.create) {
+      const created = await this.send("Target.createTarget", { url: opts.url ?? "about:blank" });
+      targetId = created.targetId;
+    } else if (!targetId) {
+      const { targetInfos } = await this.send("Target.getTargets");
+      const page = targetInfos.find((t) => t.type === "page");
+      if (page) {
+        targetId = page.targetId;
+      } else {
+        const created = await this.send("Target.createTarget", { url: opts.url ?? "about:blank" });
+        targetId = created.targetId;
+      }
+    }
+    const { sessionId } = await this.send("Target.attachToTarget", { targetId, flatten: true });
+    return new _CdpSession(this.#conn, sessionId, this.#client, this.#profileId);
+  }
+  /** Navigate the page; optionally wait for load. Never calls `Runtime.enable`. */
+  async navigate(url, opts = {}) {
+    const res = await this.send("Page.navigate", { url });
+    if (res.errorText) throw new CdpError(-1, `navigation failed: ${res.errorText}`);
+    if (opts.wait !== false) await this.#waitForLoad(opts.timeout ?? 3e4);
+    return res;
+  }
+  /** Evaluate a JS expression in the page (or an isolated world) and return its value. */
+  async evaluate(expression, opts = {}) {
+    const params = {
+      expression,
+      awaitPromise: opts.awaitPromise ?? true,
+      returnByValue: opts.returnByValue ?? true
+    };
+    if (opts.isolated) params["contextId"] = await this.#isolatedContext();
+    const res = await this.send("Runtime.evaluate", params);
+    if (res.exceptionDetails) {
+      throw new CdpError(-1, res.exceptionDetails.text || res.exceptionDetails.exception?.description || "evaluate exception");
+    }
+    return res.result.value;
+  }
+  /** Create an isolated world for the (main) frame and return its execution context id. */
+  async createIsolatedWorld(frameId, worldName = "__sb") {
+    let frame = frameId;
+    if (!frame) {
+      const { frameTree } = await this.send("Page.getFrameTree");
+      frame = frameTree.frame.id;
+    }
+    const { executionContextId } = await this.send("Page.createIsolatedWorld", {
+      frameId: frame,
+      worldName,
+      grantUniveralAccess: false
+    });
+    return executionContextId;
+  }
+  // ── Humanized trusted input (routes through the daemon, G8) ────────────────
+  humanizeMove(x, y, opts = {}) {
+    return this.#input({ action: "move", x, y, width: opts.width });
+  }
+  humanizeClick(x, y, opts = {}) {
+    return this.#input({
+      action: "click",
+      x,
+      y,
+      button: opts.button ?? "left",
+      click_count: opts.clickCount ?? 1,
+      width: opts.width
+    });
+  }
+  /**
+   * B5: humanized move to the CENTRE of an element box, with the box width fed to the
+   * daemon's Fitts-law approach so the pointer lands *within* the element (not on a
+   * fixed corner). Pass a `getBoundingClientRect()`-shaped box.
+   */
+  humanizeMoveToElement(box) {
+    return this.humanizeMove(box.x + box.width / 2, box.y + box.height / 2, { width: box.width });
+  }
+  /** B5: humanized click at the centre of an element box (see {@link humanizeMoveToElement}). */
+  humanizeClickElement(box, opts = {}) {
+    return this.humanizeClick(box.x + box.width / 2, box.y + box.height / 2, { ...opts, width: box.width });
+  }
+  humanizeType(text) {
+    return this.#input({ action: "type", text });
+  }
+  humanizeScroll(x, y, opts = {}) {
+    return this.#input({ action: "scroll", x, y, delta_x: opts.deltaX ?? 0, delta_y: opts.deltaY ?? 0 });
+  }
+  /** Close the underlying CDP connection. */
+  close() {
+    this.#conn.close();
+  }
+  #input(body) {
+    if (!this.#client || !this.#profileId) {
+      return Promise.reject(
+        new CdpError(-1, "humanize requires a CDP session created via client.connectCdp(result, profileId)")
+      );
+    }
+    return this.#client.sendInput(this.#profileId, { ...body, humanize: true });
+  }
+  async #isolatedContext() {
+    if (this.#isolatedContextId === void 0) this.#isolatedContextId = await this.createIsolatedWorld();
+    return this.#isolatedContextId;
+  }
+  async #waitForLoad(timeout) {
+    const deadline = Date.now() + timeout;
+    for (; ; ) {
+      const ready = await this.evaluate("document.readyState");
+      if (ready === "complete") return;
+      if (Date.now() > deadline) throw new CdpError(-1, "navigation wait timed out");
+      await delay(50);
+    }
+  }
+};
+async function openCdpSession(url, options = {}) {
+  const headers = {};
+  if (options.token) headers["Authorization"] = `Bearer ${options.token}`;
+  const ws = new WebSocket(url, { headers, handshakeTimeout: options.openTimeout ?? 3e4 });
+  await waitForOpen(ws);
+  const conn = new CdpConnection(ws);
+  const root = new CdpSession(conn, void 0, options.client, options.profileId);
+  if (options.autoAttach === false) return root;
+  return root.attachToPage({ create: options.createTarget ?? false, url: options.targetUrl });
+}
+function waitForOpen(ws) {
+  return new Promise((resolve, reject) => {
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = (err) => {
+      cleanup();
+      reject(new NetworkError("CDP websocket failed to open", err));
+    };
+    const cleanup = () => {
+      ws.off("open", onOpen);
+      ws.off("error", onError);
+    };
+    ws.on("open", onOpen);
+    ws.on("error", onError);
+  });
+}
+function scopedEventStream(conn, sessionId) {
+  const buffer = [];
+  const waiters = [];
+  let done = false;
+  const unsubscribe = conn.subscribe((event) => {
+    if (event.sessionId !== sessionId) return;
+    const waiter = waiters.shift();
+    if (waiter) waiter({ value: event, done: false });
+    else buffer.push(event);
+  });
+  let offClose = () => {
+  };
+  const finish = () => {
+    if (!done) {
+      done = true;
+      unsubscribe();
+      offClose();
+      for (const w of waiters.splice(0)) w({ value: void 0, done: true });
+    }
+    return { value: void 0, done: true };
+  };
+  offClose = conn.onClose(() => {
+    finish();
+  });
+  return {
+    next() {
+      const next = buffer.shift();
+      if (next !== void 0) return Promise.resolve({ value: next, done: false });
+      if (done) return Promise.resolve({ value: void 0, done: true });
+      return new Promise((resolve) => waiters.push(resolve));
+    },
+    return() {
+      return Promise.resolve(finish());
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    }
+  };
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/client.ts
+var DEFAULT_CAPACITY = {
+  max_concurrent: 64,
+  ram_budget_mb: 24576,
+  vram_budget_mb: null
+};
+var ScalebrowserClient = class extends ClientCore {
+  // ── Profiles ───────────────────────────────────────────────────────────────
+  listProfiles(params = {}, signal) {
+    return this.request("GET", "/v1/profiles", void 0, {
+      query: {
+        group: params.group,
+        state: params.state,
+        q: params.q,
+        limit: params.limit,
+        offset: params.offset,
+        sort: params.sort,
+        order: params.order
+      },
+      signal
+    });
+  }
+  /**
+   * Every id matching `params`, unpaged — what "act on all matches" needs.
+   *
+   * `listProfiles` is paged, so acting on "everything" from it only ever covers the
+   * page you fetched. Asking for ids costs one request and no persona payloads.
+   */
+  listProfileIds(params = {}, signal) {
+    return this.request("GET", "/v1/profiles/ids", void 0, {
+      query: {
+        group: params.group,
+        state: params.state,
+        q: params.q,
+        sort: params.sort,
+        order: params.order
+      },
+      signal
+    });
+  }
+  getProfile(id, signal) {
+    return this.request("GET", `/v1/profiles/${enc(id)}`, void 0, { signal });
+  }
+  createProfile(body) {
+    return this.request("POST", "/v1/profiles", body);
+  }
+  updateProfile(id, body) {
+    return this.request("PATCH", `/v1/profiles/${enc(id)}`, body);
+  }
+  deleteProfile(id) {
+    return this.request("DELETE", `/v1/profiles/${enc(id)}`);
+  }
+  /** Start a profile → CDP ws endpoint. Errors: 4002/4003/4005/4006/4008. */
+  startProfile(id, body = {}) {
+    return this.request("POST", `/v1/profiles/${enc(id)}/start`, body);
+  }
+  stopProfile(id) {
+    return this.request("POST", `/v1/profiles/${enc(id)}/stop`, {});
+  }
+  // ── Bulk (PRD §D2) ───────────────────────────────────────────────────────
+  bulkCreateProfiles(body) {
+    return this.request("POST", "/v1/bulk/profiles", body);
+  }
+  /**
+   * Start a batch. `headless` is the ONE visibility decision for the run; omitted
+   * means headless, the right default for an unattended client. The daemon stops at
+   * the machine's capacity limit and reports how far it got (`started` /
+   * `remaining` / `stopped_reason`) instead of failing every remaining id.
+   */
+  bulkStart(ids, headless) {
+    return this.request("POST", "/v1/bulk/start", { ids, headless });
+  }
+  bulkStop(ids) {
+    return this.request("POST", "/v1/bulk/stop", { ids });
+  }
+  bulkDelete(ids) {
+    return this.request("POST", "/v1/bulk/delete", { ids });
+  }
+  bulkAssignProxy(ids, proxyId) {
+    return this.request("POST", "/v1/bulk/assign-proxy", { ids, proxy_id: proxyId });
+  }
+  /**
+   * Give every id exactly this set of extensions.
+   *
+   * It REPLACES rather than adds, the same shape as assigning a proxy: picking a
+   * set for a batch states what those profiles carry. An empty list is a
+   * legitimate "none". An id the library does not hold refuses the whole call.
+   */
+  bulkAssignExtensions(ids, extRefs) {
+    return this.request("POST", "/v1/bulk/assign-extensions", { ids, ext_refs: extRefs });
+  }
+  // ── Groups & presets ───────────────────────────────────────────────────────
+  listGroups(signal) {
+    return this.request("GET", "/v1/groups", void 0, { signal });
+  }
+  getGroup(id, signal) {
+    return this.request("GET", `/v1/groups/${enc(id)}`, void 0, { signal });
+  }
+  createGroup(body) {
+    return this.request("POST", "/v1/groups", body);
+  }
+  updateGroup(id, body) {
+    return this.request("PATCH", `/v1/groups/${enc(id)}`, body);
+  }
+  deleteGroup(id) {
+    return this.request("DELETE", `/v1/groups/${enc(id)}`);
+  }
+  listPresets(signal) {
+    return this.request("GET", "/v1/presets", void 0, { signal });
+  }
+  getPreset(id, signal) {
+    return this.request("GET", `/v1/presets/${enc(id)}`, void 0, { signal });
+  }
+  createPreset(body) {
+    return this.request("POST", "/v1/presets", body);
+  }
+  updatePreset(id, body) {
+    return this.request("PATCH", `/v1/presets/${enc(id)}`, body);
+  }
+  deletePreset(id) {
+    return this.request("DELETE", `/v1/presets/${enc(id)}`);
+  }
+  /**
+   * The values a preset's `constraints` may take. Ask rather than hardcode: the
+   * region list comes from the daemon's embedded persona model, so a pinned copy
+   * drifts the moment that model changes and every create 400s.
+   */
+  getPersonaConstraints(signal) {
+    return this.request(
+      "GET",
+      "/v1/persona/constraints",
+      void 0,
+      { signal }
+    );
+  }
+  // ── Proxies (credentials write-only) ────────────────────────────────────────
+  listProxies(signal) {
+    return this.request("GET", "/v1/proxies", void 0, { signal });
+  }
+  getProxy(id, signal) {
+    return this.request("GET", `/v1/proxies/${enc(id)}`, void 0, { signal });
+  }
+  createProxy(body) {
+    return this.request("POST", "/v1/proxies", body);
+  }
+  updateProxy(id, body) {
+    return this.request("PATCH", `/v1/proxies/${enc(id)}`, body);
+  }
+  deleteProxy(id) {
+    return this.request("DELETE", `/v1/proxies/${enc(id)}`);
+  }
+  /** Health + geo check (exit-ip/country/healthy + JA4↔JA4T verdict). */
+  checkProxy(id) {
+    return this.request("POST", `/v1/proxies/${enc(id)}/check`, {});
+  }
+  /**
+   * Probe a proxy config WITHOUT persisting it — validate before you commit.
+   * Pass `id` (and omit the credentials) to probe an existing proxy's stored,
+   * write-only credentials in an edit form.
+   */
+  checkProxyConfig(body) {
+    return this.request("POST", "/v1/proxies/check", body);
+  }
+  // ── Live detector audit ─────────────────────────────────────────────────────
+  //
+  // Drives the profile's OWN running browser through ~15 third-party fingerprint
+  // sites and keeps what each one saw. The profile must be RUNNING; the run takes
+  // minutes, so `startAudit` returns immediately and you poll `getAudit`.
+  /** Queue a run → the status right after queueing. `409` if not running / already running. */
+  startAudit(profileId) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/audit`);
+  }
+  /** State plus the last stored report. */
+  getAudit(profileId, signal) {
+    return this.request("GET", `/v1/profiles/${enc(profileId)}/audit`, void 0, {
+      signal
+    });
+  }
+  // ── Session bundles (AC-ST-002/003) ─────────────────────────────────────────
+  exportSession(profileId, body) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/session/export`, body);
+  }
+  importSession(profileId, body) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/session/import`, body);
+  }
+  // ── Trusted input (G8, AC-API-003) ─────────────────────────────────────────
+  sendInput(profileId, body) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/input`, body);
+  }
+  // ── Metrics (with graceful fallback) ────────────────────────────────────────
+  async getMetrics(signal) {
+    try {
+      return await this.request("GET", "/v1/metrics", void 0, { signal });
+    } catch (err) {
+      if (err instanceof ApiError && (err.status === 404 || err.code === 4001)) {
+        return deriveMetricsFromProfiles(await this.listProfiles({ limit: 1e4 }, signal));
+      }
+      throw err;
+    }
+  }
+  // ── Events (SSE) ───────────────────────────────────────────────────────────
+  /** Subscribe to lifecycle events. Returns an unsubscribe function. */
+  subscribeEvents(handlers) {
+    return subscribeEvents({ baseUrl: this.baseUrl, token: this.token, fetch: this.fetchImpl }, handlers);
+  }
+  /** `for await (const event of client.events())` over lifecycle events. */
+  events() {
+    return eventStream({ baseUrl: this.baseUrl, token: this.token, fetch: this.fetchImpl });
+  }
+  // ── Direct-CDP driver plane ─────────────────────────────────────────────────
+  /**
+   * Open a direct-CDP session against a started profile's `cdp_ws`. Pass the
+   * `profileId` so `humanize*` helpers can route trusted input through the daemon.
+   */
+  connectCdp(target, profileId) {
+    const url = typeof target === "string" ? target : target.cdp_ws;
+    return openCdpSession(url, { token: this.token, client: this, profileId });
+  }
+  /**
+   * Start a profile, connect direct-CDP, and return a {@link LaunchHandle} whose
+   * `stop()` (or `await using`) closes CDP and stops the profile.
+   */
+  async launch(profileId, body = {}) {
+    const result = await this.startProfile(profileId, { headless: body.headless ?? true });
+    const cdp = await this.connectCdp(result, profileId);
+    const stop = async () => {
+      cdp.close();
+      await this.stopProfile(profileId);
+    };
+    return { cdp, result, stop, [Symbol.asyncDispose]: stop };
+  }
+};
+function deriveMetricsFromProfiles(profiles) {
+  const running = profiles.filter((p) => p.runtime_state === "running").length;
+  return {
+    running,
+    capacity_max_concurrent: DEFAULT_CAPACITY.max_concurrent,
+    ram_used_mb: null,
+    ram_budget_mb: DEFAULT_CAPACITY.ram_budget_mb,
+    vram_used_mb: null,
+    vram_budget_mb: DEFAULT_CAPACITY.vram_budget_mb,
+    cpu_pct: null,
+    gpu_pct: null,
+    // Mark the fallback derived so consumers can tell it from a live sample
+    // whose probes happen to be unavailable.
+    source: "derived",
+    sampled_at: null,
+    availability: {
+      ram: "unavailable",
+      cpu: "unavailable",
+      gpu: "unavailable",
+      vram: "unavailable",
+      per_profile: "unavailable"
+    },
+    profiles: []
+  };
+}
+applyMixins(ScalebrowserClient, [IdentityApi, RunsApi, ControlApi, ExtensionsApi]);
+
+// src/types.ts
+var RUNTIME_STATES = ["stopped", "starting", "running", "crashed"];
+var HOST_MODES = ["linux_engine_spoof", "local_native_windows"];
+var GEO_MODES = ["strict_expected", "follow_exit", "off"];
+var PROXY_KINDS = ["http", "socks5", "gateway"];
+var ROTATIONS = ["sticky", "rotating"];
+
+// src/index.ts
+var VERSION = "0.2.0";
+
+export { ApiError, CdpError, CdpSession, DEFAULT_CAPACITY, ErrorCode, GEO_MODES, HOST_MODES, NetworkError, PROXY_KINDS, ROTATIONS, RUNTIME_STATES, ScalebrowserClient, ScalebrowserError, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };