@scalebrowser/sdk 0.3.0 → 0.4.0

package/README.md

@@ -59,50 +59,50 @@ try {
 
 Every `/v1` endpoint is a typed method on `ScalebrowserClient`:
 
-- **Profiles** — `listProfiles`, `getProfile`, `createProfile`, `updateProfile`,
+- **Profiles**: `listProfiles`, `getProfile`, `createProfile`, `updateProfile`,
   `deleteProfile`, `startProfile`, `stopProfile`
-- **Bulk** — `bulkCreateProfiles`, `bulkStart`, `bulkStop`, `bulkDelete`,
+- **Bulk**: `bulkCreateProfiles`, `bulkStart`, `bulkStop`, `bulkDelete`,
   `bulkAssignProxy`
-- **Groups / Presets** — `listGroups`/`createGroup`/`getGroup`/`updateGroup`/`deleteGroup`,
+- **Groups / Presets**: `listGroups`/`createGroup`/`getGroup`/`updateGroup`/`deleteGroup`,
   `listPresets`/`createPreset`/`getPreset`/`updatePreset`/`deletePreset`,
   `getPersonaConstraints`. A preset is `config` (what the profiles do:
   `geo_mode`, `proxy_id`, …) plus `constraints` (what they are: `country`, which
   pins the persona's language, timezone and voices). Both are typed and the daemon
-  refuses an unknown key with a 400 — read the valid regions from
+  refuses an unknown key with a 400, so read the valid regions from
   `getPersonaConstraints()` rather than hardcoding them.
-- **Proxies** — `listProxies`, `createProxy`, `getProxy`, `updateProxy`,
+- **Proxies**: `listProxies`, `createProxy`, `getProxy`, `updateProxy`,
   `deleteProxy`, `checkProxy`, `checkProxyConfig` (probe a config before you save
-  it; pass `id` to reuse an existing proxy's stored credentials) — credentials
+  it; pass `id` to reuse an existing proxy's stored credentials). Credentials
   are write-only, never returned
-- **Extensions** — `listExtensions`, `attachExtension`, `detachExtension`, plus
+- **Extensions**: `listExtensions`, `attachExtension`, `detachExtension`, plus
   the daemon-wide library (`uploadExtension`, `getLibraryExtension`,
   `deleteLibraryExtension`). An attached package IS loaded into the browser at
   launch, under the canonical Web-Store id its own key derives
-- **Credentials** — `listCredentials`, `putCredential`, `revealCredential`
+- **Credentials**: `listCredentials`, `putCredential`, `revealCredential`
   (needs the vault password), `exportCredentials`, `importCredentials`
-- **Cookies** — `revealCookies`, the one route a cookie VALUE leaves through,
+- **Cookies**: `revealCookies`, the one route a cookie VALUE leaves through,
   behind the same vault password
-- **Sessions** — `exportSession`, `importSession`
-- **Mailboxes** — `listInboxes`, `createInbox`, `updateInbox`, `deleteInbox`,
-  `getInboxBindings`, `bindInbox`, `unbindInbox` — where a profile's
+- **Sessions**: `exportSession`, `importSession`
+- **Mailboxes**: `listInboxes`, `createInbox`, `updateInbox`, `deleteInbox`,
+  `getInboxBindings`, `bindInbox`, `unbindInbox`, which is where a profile's
   confirmation codes arrive
-- **Passkeys** — `listPasskeys`, `deletePasskey`. Metadata only: the private key
+- **Passkeys**: `listPasskeys`, `deletePasskey`. Metadata only: the private key
   has no field and no endpoint
-- **Agent runs** — `listRuns`, `getRun`, `listRunSteps`, `getRunShot`,
+- **Agent runs**: `listRuns`, `getRun`, `listRunSteps`, `getRunShot`,
   `getActivity`. Read-only, all of it
-- **Interruptions** — `listInterruptionLocks`, `setInterruptionLock`,
-  `listInterruptionRules`, `setInterruptionRule`, `deleteInterruptionRule` — who
+- **Interruptions**: `listInterruptionLocks`, `setInterruptionLock`,
+  `listInterruptionRules`, `setInterruptionRule`, `deleteInterruptionRule`: who
   may answer when the browser asks something
-- **Artifacts** — `putArtifact` (hand the daemon a file to upload later),
+- **Artifacts**: `putArtifact` (hand the daemon a file to upload later),
   `getArtifact` (fetch a screenshot, download or saved PDF as bytes)
-- **Input** — `sendInput`
-- **Metrics / Account / Health** — `getMetrics`, `getAccount`, `health`, `ready`.
+- **Input**: `sendInput`
+- **Metrics / Account / Health**: `getMetrics`, `getAccount`, `health`, `ready`.
   The first two answer 404 on a daemon without them, which the SDK treats as
   information rather than as an error: metrics are then derived from profile
   state, and the account reads `licensed: false`, which is what "self-hosted, no
   control plane" means
 
-Errors map to typed exceptions carrying the daemon's numeric code (4001–4010):
+Errors map to typed exceptions carrying the daemon's numeric code (4001–4012):
 
 ```ts
 import { ApiError, ErrorCode } from '@scalebrowser/sdk';
@@ -111,7 +111,7 @@ try {
   await sb.startProfile(id);
 } catch (err) {
   if (err instanceof ApiError && err.code === ErrorCode.Capacity) {
-    // 4003 — capacity exceeded
+    // 4003: capacity exceeded
   }
 }
 ```
@@ -136,11 +136,11 @@ for await (const e of sb.events()) {
 
 `CdpSession` (returned by `connectCdp` / `launch`) gives you:
 
-- `send<T>(method, params?)` — raw CDP command, awaited by id (concurrent-safe)
+- `send<T>(method, params?)`: raw CDP command, awaited by id (concurrent-safe)
 - `navigate(url, { wait, timeout })`, `evaluate<T>(expr, { isolated })`
 - `createIsolatedWorld(frameId?, worldName?)`
 - `attachToPage({ targetId?, create?, url? })`
-- `on(method, cb)` / `events()` — CDP event subscription scoped to the session
+- `on(method, cb)` / `events()`: CDP event subscription scoped to the session
 - `humanizeMove` / `humanizeClick` / `humanizeType` / `humanizeScroll`
 - `close()`
 
@@ -149,6 +149,12 @@ for await (const e of sb.events()) {
 - Bearer token is sent on every request and the SSE/CDP handshakes; it is
   **never logged** (the client's inspect output masks it).
 - Proxy credentials are injected by the daemon and never travel over CDP.
+- **The CDP endpoint is guarded by the OS user, not by that token.** The engine's
+  DevTools port has no authentication of its own: it answers a bogus bearer with
+  `200`, measured, so the engine drops any connection whose peer process runs as
+  a different user. Nothing to configure and nothing to pass: your process is the
+  one that started the profile, so it is on the allowed side. A helper running as
+  another account will not get in, by design.
 
 ## Develop
 

package/dist/index.cjs

@@ -21,7 +21,17 @@ var ErrorCode = {
    * 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
+  Unauthorized: 4010,
+  /** No account is connected to this machine, so nothing may run (DEC-014).
+   * Distinct from Unauthorized (4010 = the daemon's own bearer token is wrong, so
+   * re-read the token): 4011 means the machine needs to be signed in, and no token
+   * a client holds can substitute for that. Connect it in the desktop app. */
+  NotSignedIn: 4011,
+  /** This ONE profile is open on another machine of the same account (DEC-015).
+   * Distinct from ConcurrencyLimit (4008 = the plan is full, buy more or free any
+   * browser): the caller's move here costs nothing. Close it on that machine, or
+   * take it over from the app running there. */
+  ProfileInUse: 4012
 };
 var CODE_LABELS = {
   4001: "Not found",
@@ -31,7 +41,9 @@ var CODE_LABELS = {
   4005: "Launch preflight failed",
   4006: "Profile already running",
   4008: "Concurrent-browser limit reached (subscription-wide)",
-  4010: "Unauthorized"
+  4010: "Unauthorized",
+  4011: "No account connected to this machine",
+  4012: "This profile is open on another machine"
 };
 var ScalebrowserError = class extends Error {
   constructor(message) {
@@ -133,7 +145,7 @@ var ClientCore = class {
     return text ? JSON.parse(text) : void 0;
   }
   /**
-   * A route that answers with bytes, not JSON — artifacts and run stills.
+   * 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,
@@ -251,7 +263,7 @@ var ControlApi = class extends ClientCore {
     });
   }
   /**
-   * Fetch one artifact's bytes — a screenshot, a download, a saved PDF.
+   * 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.
@@ -264,7 +276,7 @@ var ControlApi = class extends ClientCore {
    * 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 — but it is read pessimistically: nothing can be shown to be
+   * throwing, but it is read pessimistically: nothing can be shown to be
    * connected or permitted. Same shape of tolerance as {@link getMetrics}.
    */
   async getAccount(signal) {
@@ -279,7 +291,7 @@ var ControlApi = class extends ClientCore {
   health(signal) {
     return this.request("GET", "/health", void 0, { signal });
   }
-  /** "Can it serve?" Local facts only — the control plane is deliberately not consulted. */
+  /** "Can it serve?" Local facts only; the control plane is deliberately not consulted. */
   ready(signal) {
     return this.request("GET", "/health/ready", void 0, { signal });
   }
@@ -291,7 +303,7 @@ var ExtensionsApi = class extends ClientCore {
   //
   // 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
+  // package under its CANONICAL Web-Store id. A key-less package is refused, since it
   // would take a path-derived id, identical across the fleet.
   /** The library, newest first. */
   listLibraryExtensions(signal) {
@@ -304,7 +316,7 @@ var ExtensionsApi = class extends ClientCore {
   uploadExtension(crx) {
     return this.request("POST", "/v1/extensions", crx);
   }
-  /** One library entry — the most recently added version. */
+  /** One library entry: the most recently added version. */
   getLibraryExtension(id, signal) {
     return this.request("GET", `/v1/extensions/${enc(id)}`, void 0, { signal });
   }
@@ -315,7 +327,7 @@ var ExtensionsApi = class extends ClientCore {
   /**
    * Remove ONE stocked version.
    *
-   * Assignments survive — they name the extension, not the version — unless this
+   * Assignments survive, because they name the extension and not the version, unless this
    * was the last version, in which case they go with it.
    */
   deleteLibraryExtensionVersion(id, version) {
@@ -354,14 +366,14 @@ 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`
+  // 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
+  // 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.
@@ -377,7 +389,7 @@ var IdentityApi = class extends ClientCore {
   /**
    * Store or update one login.
    *
-   * An omitted secret keeps its stored value rather than clearing it — an edit form
+   * An omitted secret keeps its stored value rather than clearing it, because 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
@@ -410,7 +422,7 @@ var IdentityApi = class extends ClientCore {
    *
    * `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
+   * is the answer to a lost master key: a daemon-generated password exists nowhere
    * else.
    */
   exportCredentials(profileId, vaultPassword, password) {
@@ -482,6 +494,72 @@ var IdentityApi = class extends ClientCore {
   deletePasskey(profileId, credentialId) {
     return this.request("DELETE", `/v1/profiles/${enc(profileId)}/passkeys/${enc(credentialId)}`);
   }
+  // ── Secret Layer ───────────────────────────────────────────────────────────
+  //
+  // Values a profile holds that no agent ever reads. Nothing here returns a
+  // value, and that is not an oversight: the wrapper below starts the command
+  // INSIDE the daemon precisely so that no route has to hand plaintext out.
+  /** The entries this profile keeps, with the placeholder that stands for each. */
+  listSecrets(profileId, signal) {
+    return this.request(
+      "GET",
+      `/v1/profiles/${enc(profileId)}/secrets`,
+      void 0,
+      { signal }
+    );
+  }
+  /** Change a title, a binding, or the state. Never the label. */
+  updateSecret(profileId, secretId, body) {
+    return this.request(
+      "PATCH",
+      `/v1/profiles/${enc(profileId)}/secrets/${enc(secretId)}`,
+      body
+    );
+  }
+  /** Delete an entry. The reply names the runs it appeared in. */
+  deleteSecret(profileId, secretId) {
+    return this.request(
+      "DELETE",
+      `/v1/profiles/${enc(profileId)}/secrets/${enc(secretId)}`
+    );
+  }
+  /**
+   * Filter a text you hold against this profile's values.
+   *
+   * The SDK path exists because censoring only makes sense where a MODEL is
+   * reading: your own code is not, and a placeholder in the middle of it would
+   * break parsing. So the daemon offers the filter as a call rather than
+   * applying it to a channel it does not own.
+   */
+  scrubText(profileId, text) {
+    return this.request(
+      "POST",
+      `/v1/profiles/${enc(profileId)}/secrets/scrub`,
+      { text }
+    );
+  }
+  /**
+   * Run a command with named values in its environment.
+   *
+   * The daemon starts the child, so no value crosses a socket. At least one
+   * `env` entry is required: without the rule an `npm publish` would carry every
+   * value of the profile.
+   */
+  runWithSecrets(profileId, body) {
+    return this.request(
+      "POST",
+      `/v1/profiles/${enc(profileId)}/secrets/run`,
+      body
+    );
+  }
+  /** Is the secret layer on? It is by default. */
+  getSecretLayer(signal) {
+    return this.request("GET", "/v1/secret-layer", void 0, { signal });
+  }
+  /** Turn the secret layer on or off for the whole daemon. */
+  setSecretLayer(enabled) {
+    return this.request("POST", "/v1/secret-layer", { enabled });
+  }
   // ── Cookies ────────────────────────────────────────────────────────────────
   /**
    * The one door a cookie VALUE leaves through, and it needs the vault password.
@@ -508,7 +586,7 @@ var RunsApi = class extends ClientCore {
   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. */
+  /** 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 },
@@ -713,7 +791,7 @@ var CdpConnection = class {
     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. */
+   *  it already has); event streams use this to end instead of hanging. */
   onClose(cb) {
     if (this.#closeReason) {
       cb();
@@ -997,7 +1075,7 @@ var ScalebrowserClient = class extends ClientCore {
     });
   }
   /**
-   * Every id matching `params`, unpaged — what "act on all matches" needs.
+   * 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.
@@ -1033,6 +1111,14 @@ var ScalebrowserClient = class extends ClientCore {
   stopProfile(id) {
     return this.request("POST", `/v1/profiles/${enc(id)}/stop`, {});
   }
+  /** Ask for a profile that is open on another machine of this account.
+   *
+   *  Closes nothing here and nothing there: the control plane revokes the holder's
+   *  right, the holder closes its own browser at its next heartbeat. Start only
+   *  after this answered `free`. Errors: 4012 when it is held elsewhere. */
+  takeoverProfile(id) {
+    return this.request("POST", `/v1/profiles/${enc(id)}/takeover`, {});
+  }
   // ── Bulk (PRD §D2) ───────────────────────────────────────────────────────
   bulkCreateProfiles(body) {
     return this.request("POST", "/v1/bulk/profiles", body);
@@ -1130,7 +1216,7 @@ var ScalebrowserClient = class extends ClientCore {
     return this.request("POST", `/v1/proxies/${enc(id)}/check`, {});
   }
   /**
-   * Probe a proxy config WITHOUT persisting it — validate before you commit.
+   * 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.
    */