@scalebrowser/sdk 0.3.0 → 0.4.1

package/dist/index.d.cts

@@ -1,65 +1,5 @@
 import WebSocket from 'ws';
 
-/**
- * Error model — stable numeric API error codes (SPEC §5,
- * `crates/core/src/error.rs`) and the typed exceptions the SDK throws.
- */
-/** Stable numeric API error codes (4001–4010). */
-declare const ErrorCode: {
-    readonly NotFound: 4001;
-    readonly ProxyGeo: 4002;
-    readonly Capacity: 4003;
-    readonly EngineMissing: 4004;
-    readonly Preflight: 4005;
-    readonly 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. */
-    readonly 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. */
-    readonly ConcurrencyLimit: 4008;
-    readonly Unauthorized: 4010;
-};
-type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
-/** Error body shape: `{ code, message }` (docs/features/api.md). */
-interface ApiErrorBody {
-    code?: number;
-    message?: string;
-}
-/** Base class for every error this SDK throws — lets callers `catch` one type. */
-declare class ScalebrowserError extends Error {
-    constructor(message: string);
-}
-/**
- * A typed transport/contract error. Carries the HTTP `status` and the daemon's
- * numeric `code` so callers (and the auth layer) can react — e.g. 401 / code
- * 4010 → re-authenticate.
- */
-declare class ApiError extends ScalebrowserError {
-    readonly status: number;
-    readonly code?: number;
-    readonly body?: ApiErrorBody;
-    constructor(status: number, body?: ApiErrorBody, fallbackMessage?: string);
-    /** True for auth failures that must trigger re-authentication. */
-    get isAuthError(): boolean;
-    /** Short label for the error code, if any. */
-    get codeLabel(): string | undefined;
-}
-/** A network-level failure (daemon unreachable, socket error, fetch rejected). */
-declare class NetworkError extends ScalebrowserError {
-    readonly cause?: unknown;
-    constructor(message: string, cause?: unknown);
-}
-/** A CDP command that returned an `error` frame, or a closed CDP connection. */
-declare class CdpError extends ScalebrowserError {
-    readonly code: number;
-    readonly data?: unknown;
-    constructor(code: number, message: string, data?: unknown);
-}
-/** Narrow an unknown thrown value to a user-facing message. */
-declare function errorMessage(err: unknown): string;
-
 interface Screen {
     width: number;
     height: number;
@@ -167,14 +107,14 @@ interface Persona {
 }
 
 /**
- * Wire types — a 1:1 mirror of the daemon's serialized domain model
+ * Wire types: a 1:1 mirror of the daemon's serialized domain model
  * (`crates/core/src/model.rs`, `persona.rs`, `events.rs`) and the endpoint
  * contract in `docs/features/api.md`. Mirrored against `web-ui/src/api/types/`
  * (a directory of split files behind the `web-ui/src/api/types.ts` barrel), and
  * that mirror is ENFORCED: `web-ui/src/test/sdk-type-mirror.test.ts` compares
  * every shared exported declaration and goes red on drift. The Python SDK
  * (`sdks/python/src/scalebrowser/models*.py`) carries the same shapes by hand,
- * deliberately without a gate — a TS↔pydantic comparator is its own tool.
+ * deliberately without a gate; a TS↔pydantic comparator is its own tool.
  *
  * All Rust enums serialize `snake_case` (serde `rename_all`). Timestamps are
  * unix seconds (`number`, Rust `i64`). The truth for any disagreement is the
@@ -200,7 +140,7 @@ declare const ROTATIONS: readonly Rotation[];
 type SessionKind = 'cookies' | 'local_storage' | 'indexed_db' | 'service_worker';
 type OsFamily = 'windows' | 'macos' | 'linux';
 /** How protected a profile is right now, decided by the daemon WITHOUT starting a
- *  browser — it runs the same gates the launch runs. `blocked` means the launch
+ *  browser: it runs the same gates the launch runs. `blocked` means the launch
  *  will refuse this profile; `warn` means it starts but something measurably
  *  weakens it (most often a missing proxy). */
 type ProtectionLevel = 'ok' | 'warn' | 'blocked';
@@ -235,7 +175,7 @@ interface Profile {
     protection?: ProtectionStatus;
     /**
      * Platform slugs this profile has a stored login for, sorted by the daemon.
-     * Additive — a daemon predating the credential vault simply omits it.
+     * Additive; a daemon predating the credential vault simply omits it.
      */
     platforms?: string[];
 }
@@ -247,7 +187,7 @@ interface Group {
 /**
  * Operating config: what the created profiles DO. Every key mirrors a
  * `POST /v1/profiles` body field. The daemon refuses an unknown key with a 400
- * rather than dropping it — a preset makes up to 1000 profiles, so a swallowed
+ * rather than dropping it, because a preset makes up to 1000 profiles, so a swallowed
  * key is a thousand wrong ones.
  */
 interface PresetConfig {
@@ -255,12 +195,12 @@ interface PresetConfig {
     engine_version?: string | null;
     host_mode?: HostMode | null;
     geo_mode?: GeoMode | null;
-    /** The geo GATE's expectation — not the persona's drawn region. */
+    /** The geo GATE's expectation, not the persona's drawn region. */
     expected_country?: string | null;
     group_id?: string | null;
     proxy_id?: string | null;
     /**
-     * Library ids every profile of the batch is created with. Empty is normal —
+     * Library ids every profile of the batch is created with. Empty is normal, since
      * about half of real Chrome users carry no extension.
      *
      * An id the library no longer holds refuses the whole batch: a thousand profiles
@@ -271,7 +211,7 @@ interface PresetConfig {
 /**
  * Generator constraints: what the created profiles ARE. Exactly one axis,
  * because an axis is only honest here if the daemon does not overwrite it at
- * launch — the GPU, screen, DPR and Chrome version all are.
+ * launch; the GPU, screen, DPR and Chrome version all are.
  */
 interface PresetConstraints {
     /**
@@ -287,11 +227,11 @@ interface Preset {
     config: PresetConfig;
     created_at: number;
 }
-/** `GET /v1/persona/constraints` — the values a preset may constrain to. */
+/** `GET /v1/persona/constraints`: the values a preset may constrain to. */
 interface PersonaConstraintOptions {
     countries: string[];
 }
-/** Proxy — credentials are write-only (`#[serde(skip_serializing)]`); never returned. */
+/** Proxy; credentials are write-only (`#[serde(skip_serializing)]`) and never returned. */
 interface Proxy {
     id: string;
     kind: ProxyKind;
@@ -323,7 +263,7 @@ interface AuditStatus {
     state: 'idle' | 'running' | 'finished';
     started_at?: number;
     finished_at?: number;
-    /** Why the RUN failed — distinct from a detector's own `skip`. */
+    /** Why the RUN failed, distinct from a detector's own `skip`. */
     error?: string;
     report?: AuditReport;
 }
@@ -418,7 +358,7 @@ interface RunStep {
     /** Path of the still under the runs API; the image is fetched separately. */
     shot_path: string | null;
     /**
-     * What the call produced, in one line — "3 blocks, 122 characters",
+     * What the call produced, in one line: "3 blocks, 122 characters",
      * "no visible change · 14 elements".
      *
      * `summary` says what the agent asked for, this says what came back. A step
@@ -495,7 +435,7 @@ type LifecycleEvent = {
     goal: string;
     at: number;
 }
-/** One tool call was appended to a run's trail — the whole stored step. */
+/** One tool call was appended to a run's trail: the whole stored step. */
  | {
     type: 'run_step';
     run_id: string;
@@ -533,7 +473,7 @@ type LifecycleEvent = {
 /**
  * An event as it arrives, with its position in this connection's stream.
  *
- * The daemon numbers every frame, starting at 1. A jump means frames were lost —
+ * The daemon numbers every frame, starting at 1. A jump means frames were lost, and
  * the only way to tell "nothing happened" from "something happened and I did not
  * get it". Optional so a daemon predating the numbering still type-checks.
  */
@@ -544,13 +484,13 @@ type StreamedEvent = LifecycleEvent & {
 /**
  * Live lifecycle event stream (`GET /v1/events`, AC-API-003).
  *
- * Read as `text/event-stream` over `fetch` (so the Bearer header is attached —
+ * Read as `text/event-stream` over `fetch` (so the Bearer header is attached, which
  * the browser `EventSource` cannot do that) and reconnect with backoff. A
  * `/v1/ws` websocket carries the same events; SSE is sufficient for one-way
  * fan-out. Mirrors `web-ui/src/api/events.ts`.
  */
 
-/** Injectable `fetch` — defaults to the global at call time. */
+/** Injectable `fetch`; defaults to the global at call time. */
 type FetchLike = typeof globalThis.fetch;
 type StreamStatus = 'connecting' | 'open' | 'closed';
 interface StreamParams {
@@ -597,7 +537,7 @@ declare function eventStream(params: StreamParams): AsyncIterableIterator<Lifecy
 /** What an operator has taken out of an agent's hands. */
 type InterruptionLock = 'always_block' | 'always_allow' | 'agent_decides';
 /**
- * One answer, in the browser's OWN vocabulary — hence `allowOnce` in camelCase
+ * One answer, in the browser's OWN vocabulary, hence `allowOnce` in camelCase
  * while everything else in this API is snake_case. The daemon's enum is
  * `#[serde(rename_all = "camelCase")]`; sending `allow_once` is a 400.
  */
@@ -636,7 +576,7 @@ interface InterruptionRuleRow {
     origin: string;
     kind: string;
     choice: InterruptionChoice;
-    /** Who wrote it — an agent must not be able to widen what the operator allowed. */
+    /** Who wrote it: an agent must not be able to widen what the operator allowed. */
     author: 'operator' | 'agent';
     profile_id: string | null;
 }
@@ -668,13 +608,13 @@ interface ArtifactBytes {
  * Licence state, for display.
  *
  * The daemon decides on every launch whether a start is allowed; this never
- * gets a say in it. Never gate your own code on it — a green light on a profile
+ * gets a say in it. Never gate your own code on it: a green light on a profile
  * the launch gate refuses is worse than no light.
  */
 interface Account {
     /** Whether an entitlement snapshot has arrived. Also `false` in the seconds
      *  between signing in and the first refresh, so it never answers "is this
-     *  machine connected to an account" — `signed_in` does. */
+     *  machine connected to an account"; `signed_in` does. */
     licensed: boolean;
     /** Whether an account is connected to this machine. One without an account
      *  starts no browser (DEC-014). */
@@ -731,7 +671,7 @@ declare class ClientCore {
     setToken(token: string | null): void;
     protected request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
     /**
-     * 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,
@@ -758,7 +698,7 @@ declare class ControlApi extends ClientCore {
      */
     putArtifact(profileId: string, bytes: Uint8Array | ArrayBuffer, name?: string): Promise<ArtifactPutResult>;
     /**
-     * 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.
@@ -768,13 +708,13 @@ declare class ControlApi 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}.
      */
     getAccount(signal?: AbortSignal): Promise<Account>;
     /** "Is the daemon alive?" Public, needs no token. */
     health(signal?: AbortSignal): Promise<HealthStatus>;
-    /** "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?: AbortSignal): Promise<ReadyStatus>;
 }
 
@@ -782,12 +722,12 @@ declare class ControlApi extends ClientCore {
  *  a paged fleet while looking authoritative, so ordering is a server parameter. */
 type ProfileSort = 'created_at' | 'name' | 'runtime_state' | 'last_open_at';
 type SortOrder = 'asc' | 'desc';
-/** `GET /v1/profiles/ids` — every id matching the same filters, unpaged. */
+/** `GET /v1/profiles/ids`: every id matching the same filters, unpaged. */
 interface ProfileIdsResult {
     count: number;
     ids: string[];
 }
-/** `POST /v1/bulk/start` — per-id results plus what the batch as a whole did. */
+/** `POST /v1/bulk/start`: per-id results plus what the batch as a whole did. */
 interface BulkStartResult {
     results: {
         id: string;
@@ -818,7 +758,7 @@ interface CreateProfileBody {
     proxy_id?: string | null;
 }
 /**
- * PATCH — all mutable fields optional. `host_mode` and `seed` are fixed at create
+ * PATCH, all mutable fields optional. `host_mode` and `seed` are fixed at create
  * time (C4/C5): a DIFFERING `host_mode` is refused with 400, an unchanged echo is
  * accepted. Changing a tier requires delete + recreate.
  */
@@ -836,6 +776,17 @@ interface StartProfileResult {
     pid: number | null;
     started_at: number;
 }
+/** What a takeover request answered.
+ *
+ *  `free` means the profile is yours to start now; `pending` means the machine that
+ *  held it has been told and is closing its browser, so ask again in a moment.
+ *  Never start on `pending`: two machines on one identity is what a site reads as
+ *  a cloned account. */
+interface TakeoverResult {
+    state: 'free' | 'pending';
+    /** The holder as a person reads it: its label, else a short machine id. */
+    holder?: string | null;
+}
 interface StopProfileResult {
     stopped: boolean;
 }
@@ -875,11 +826,11 @@ interface ProxyCheckResult {
     ja4t_mismatch?: boolean;
     warnings?: string[];
     checked_at?: number;
-    /** Round-trip RTT — `null` on an unreachable exit (a timeout is not a latency). */
+    /** Round-trip RTT, `null` on an unreachable exit (a timeout is not a latency). */
     latency_ms?: number | null;
 }
 /**
- * Body of `POST /v1/proxies/check` — probe a proxy config that is NOT persisted
+ * Body of `POST /v1/proxies/check`: probe a proxy config that is NOT persisted
  * (health + geo before you commit it).
  *
  * Edit-mode: pass the `id` of an existing proxy and omit `username`/`password`
@@ -893,7 +844,7 @@ interface CheckProxyConfigBody {
     username?: string | null;
     password?: string | null;
     rotation?: Rotation;
-    /** Existing proxy id — enables the stored-credential fallback. */
+    /** Existing proxy id; enables the stored-credential fallback. */
     id?: string | null;
 }
 /**
@@ -913,7 +864,7 @@ interface Extension {
      * dir does not leave every row pointing at nothing.
      */
     dir: string;
-    /** SHA-256 of the unpacked tree — names the CONTENT of this version. */
+    /** SHA-256 of the unpacked tree; it names the CONTENT of this version. */
     content_hash: string;
     added_at: number;
 }
@@ -922,7 +873,7 @@ interface Extension {
  * extensions response; `engine_switches` is what the launch actually emits.
  *
  * `id_model` is `"canonical"`: the id comes from the package's key and is the same
- * for every profile — deliberately, since it is the id millions of real users
+ * for every profile, deliberately, since it is the id millions of real users
  * report. Only the FILES are per-profile (`delivery: "per_profile_copy"`).
  */
 interface ExtensionPolicy {
@@ -937,7 +888,7 @@ interface ExtensionsResult {
     /** Assigned library ids, as an idempotent set. */
     extensions: string[];
     /**
-     * The set this profile actually loads — ONE version per extension, drawn from the
+     * The set this profile actually loads: ONE version per extension, drawn from the
      * profile's seed over what the library stocks. Shorter than `extensions` when an id
      * no longer resolves.
      */
@@ -945,7 +896,7 @@ interface ExtensionsResult {
     policy: ExtensionPolicy;
     /**
      * What is worth knowing about THIS set, judged by the daemon with the same
-     * function the launch gate uses. Empty for an unremarkable set — including an
+     * function the launch gate uses. Empty for an unremarkable set, including an
      * empty one, since about half of real Chrome users carry no extension.
      *
      * Never recompute it client-side: a second opinion could contradict the gate.
@@ -954,7 +905,7 @@ interface ExtensionsResult {
 }
 /** One finding about a profile's extension set. */
 interface ExtensionAdvice {
-    /** `warn` — a launch is never blocked by an extension. */
+    /** `warn`: a launch is never blocked by an extension. */
     level: string;
     message: string;
 }
@@ -967,14 +918,14 @@ declare class ExtensionsApi extends ClientCore {
      * existing ones (profiles draw their own); re-uploading the same version replaces it.
      */
     uploadExtension(crx: Uint8Array | ArrayBuffer): Promise<Extension>;
-    /** One library entry — the most recently added version. */
+    /** One library entry: the most recently added version. */
     getLibraryExtension(id: string, signal?: AbortSignal): Promise<Extension>;
     /** Remove EVERY version of a package, its files and every profile's assignment of it. */
     deleteLibraryExtension(id: string): Promise<unknown>;
     /**
      * 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: string, version: string): Promise<unknown>;
@@ -986,58 +937,6 @@ declare class ExtensionsApi extends ClientCore {
     detachExtension(profileId: string, extRef: string): Promise<ExtensionsResult>;
 }
 
-/**
- * One stored platform login — everything about it EXCEPT the secrets.
- *
- * The username IS returned: it is the account's display identity, not a secret on
- * any platform, and without it two stored accounts are indistinguishable. The
- * password and two-factor key travel only through `revealCredential`, which needs
- * the vault password.
- */
-interface CredentialMeta {
-    platform: string;
-    username: string | null;
-    login_url: string | null;
-    has_password: boolean;
-    has_totp: boolean;
-    /** Typed into a sign-up form but never confirmed — the account may not exist. */
-    pending?: boolean;
-    created_at: number;
-    updated_at: number;
-    last_used_at: number | null;
-    /** No longer opens with the current master key: listable, deletable, unusable. */
-    secrets_unreadable?: boolean;
-}
-/** An omitted secret means "leave it unchanged", not "delete it". */
-interface PutCredentialBody {
-    username?: string | null;
-    password?: string | null;
-    /** Base32 setup key. Grouped, lower-case input is normalised by the daemon. */
-    totp_secret?: string | null;
-    login_url?: string | null;
-}
-/** The only shape in this SDK that carries a password. */
-interface RevealedCredential {
-    platform: string;
-    username: string | null;
-    password: string | null;
-    totp_secret: string | null;
-}
-/** A passphrase-sealed backup of one profile's logins. */
-interface CredentialBundle {
-    bundle: string;
-    count: number;
-}
-interface CredentialImportResult {
-    /** Boolean, like the session import — the number is in `count`. */
-    imported: boolean;
-    count: number;
-    platforms: string[];
-}
-interface VaultStatus {
-    configured: boolean;
-}
-
 /**
  * The account layer: mailboxes, passkeys and the one door a cookie value leaves
  * through.
@@ -1064,7 +963,7 @@ interface Inbox {
     address_domain: string | null;
     created_at: number;
     /**
-     * The stored password could not be decrypted — a restored database without
+     * The stored password could not be decrypted: a restored database without
      * its key. The row stays visible and deletable; every use of it fails closed.
      */
     credentials_unreadable?: boolean;
@@ -1106,7 +1005,7 @@ interface InboxBindings {
     bindings: InboxBinding[];
 }
 /**
- * One passkey of a profile — a login that needs no password.
+ * One passkey of a profile: a login that needs no password.
  *
  * `credential_id` names the row for deletion and nothing else. The private key
  * has no field here and no endpoint: it IS the account, and it could not be
@@ -1120,7 +1019,7 @@ interface PasskeyRow {
     user_display: string | null;
     created_at: number;
     last_used_at: number | null;
-    /** True when a stored secret cannot be decrypted — the sign-in WILL fail. */
+    /** True when a stored secret cannot be decrypted; the sign-in WILL fail. */
     secrets_unreadable: boolean;
     /**
      * When the key stopped being usable, if it has. A retired key is never loaded
@@ -1131,7 +1030,7 @@ interface PasskeyRow {
     retired_at: number | null;
     /**
      * `unknown` is a reason this build cannot name, and it deliberately claims
-     * nothing — reading it as `operator` would tell you that you had deleted
+     * nothing, because reading it as `operator` would tell you that you had deleted
      * something you never touched.
      */
     retired_reason: 'operator' | 'agent' | 'site_revoked' | 'unknown' | null;
@@ -1154,6 +1053,150 @@ interface RevealCookiesResult {
     domain: string;
     cookies: RevealedCookie[];
 }
+/** What a stored value is. */
+type SecretKind = 'api_token' | 'password' | 'recovery_code' | 'totp_seed' | 'private_key' | 'unknown';
+/** How the layer came to know it. The first three are the honest origins. */
+type SecretOrigin = 'generated' | 'stored' | 'typed' | 'captured';
+/** How narrowly it is bound to where it may be used. */
+type SecretBindingMode = 'domain' | 'host' | 'prefix' | 'exact' | 'off';
+/** Where it stands between "just seen" and "known good". */
+type SecretState = 'quarantined' | 'confirmed' | 'doubtful' | 'released';
+interface SecretRow {
+    id: string;
+    /** The immutable name inside the placeholder. Renaming changes the title. */
+    label: string;
+    display_title?: string | null;
+    /** The placeholder for THIS daemon run. A new run draws a new session part. */
+    secret_ref?: string;
+    kind: SecretKind;
+    origin: SecretOrigin;
+    detected_by?: string | null;
+    binding_mode: SecretBindingMode;
+    binding_value?: string | null;
+    field_bound: boolean;
+    state: SecretState;
+    sole_copy: boolean;
+    /** Only present where the length is the FORMAT's rather than the value's. */
+    length?: number | null;
+    expires_at?: number | null;
+    created_at: number;
+    updated_at: number;
+    last_used_at?: number | null;
+    value_unreadable?: boolean;
+}
+interface SecretListResult {
+    secrets: SecretRow[];
+    /** Values still being censored that have no entry, because the list is full. */
+    withheld_without_an_entry: number;
+    layer_enabled: boolean;
+}
+/** What may be changed about one entry. The label is deliberately absent. */
+interface SecretPatchBody {
+    display_title?: string;
+    binding_mode?: SecretBindingMode;
+    binding_value?: string;
+    clear_binding_value?: boolean;
+    field_bound?: boolean;
+    state?: SecretState;
+    expires_at?: number;
+    clear_expires_at?: boolean;
+}
+interface SecretRunMention {
+    run_id: string;
+    goal: string;
+    started_at: number;
+    steps: number;
+}
+interface SecretDeleteResult {
+    deleted: string;
+    label: string;
+    /** The runs this entry appeared in, so nothing is removed blind. */
+    appeared_in_runs: SecretRunMention[];
+}
+interface SecretScrubResult {
+    text: string;
+    /** Which entries were replaced, by label. Never a value. */
+    replaced: string[];
+}
+interface SecretRunBody {
+    /** `NAME=<label>` pairs. At least one is required. */
+    env: string[];
+    /** The command and its arguments, already split. Never a shell line. */
+    command: string[];
+    cwd?: string;
+    timeout_secs?: number;
+}
+interface SecretRunResult {
+    command: string;
+    exit_code: number | null;
+    stdout: string;
+    stderr: string;
+    values_supplied: string[];
+}
+
+/**
+ * One stored platform login: everything about it EXCEPT the secrets.
+ *
+ * The username IS returned: it is the account's display identity, not a secret on
+ * any platform, and without it two stored accounts are indistinguishable. The
+ * password and two-factor key travel only through `revealCredential`, which needs
+ * the vault password.
+ */
+interface CredentialMeta {
+    platform: string;
+    username: string | null;
+    login_url: string | null;
+    has_password: boolean;
+    has_totp: boolean;
+    /** Typed into a sign-up form but never confirmed, so the account may not exist. */
+    pending?: boolean;
+    created_at: number;
+    updated_at: number;
+    last_used_at: number | null;
+    /** No longer opens with the current master key: listable, deletable, unusable. */
+    secrets_unreadable?: boolean;
+    /** Where this login may be typed (Secret Layer). */
+    binding_mode: SecretBindingMode;
+    binding_value?: string | null;
+    /** Is the field-kind check on for this login? */
+    field_bound: boolean;
+}
+/** An omitted secret means "leave it unchanged", not "delete it". */
+interface PutCredentialBody {
+    username?: string | null;
+    password?: string | null;
+    /** Base32 setup key. Grouped, lower-case input is normalised by the daemon. */
+    totp_secret?: string | null;
+    login_url?: string | null;
+    /**
+     * Where this login may be typed. Absent leaves it as it is, so changing a
+     * password never silently widens a binding.
+     */
+    binding_mode?: SecretBindingMode;
+    binding_value?: string;
+    field_bound?: boolean;
+}
+/** The only shape in this SDK that carries a password. */
+interface RevealedCredential {
+    platform: string;
+    username: string | null;
+    password: string | null;
+    totp_secret: string | null;
+}
+/** A passphrase-sealed backup of one profile's logins. */
+interface CredentialBundle {
+    bundle: string;
+    count: number;
+}
+interface CredentialImportResult {
+    /** Boolean, like the session import; the number is in `count`. */
+    imported: boolean;
+    count: number;
+    platforms: string[];
+}
+interface VaultStatus {
+    configured: boolean;
+}
 
 declare class IdentityApi extends ClientCore {
     /** Which platforms this profile can log into. Never carries a secret. */
@@ -1161,7 +1204,7 @@ declare class IdentityApi 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
@@ -1177,7 +1220,7 @@ declare class IdentityApi 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: string, vaultPassword: string, password: string): Promise<CredentialBundle>;
@@ -1206,6 +1249,37 @@ declare class IdentityApi extends ClientCore {
      * a headstone, the second clears the headstone for good.
      */
     deletePasskey(profileId: string, credentialId: string): Promise<unknown>;
+    /** The entries this profile keeps, with the placeholder that stands for each. */
+    listSecrets(profileId: string, signal?: AbortSignal): Promise<SecretListResult>;
+    /** Change a title, a binding, or the state. Never the label. */
+    updateSecret(profileId: string, secretId: string, body: SecretPatchBody): Promise<SecretRow>;
+    /** Delete an entry. The reply names the runs it appeared in. */
+    deleteSecret(profileId: string, secretId: string): Promise<SecretDeleteResult>;
+    /**
+     * 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: string, text: string): Promise<SecretScrubResult>;
+    /**
+     * 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: string, body: SecretRunBody): Promise<SecretRunResult>;
+    /** Is the secret layer on? It is by default. */
+    getSecretLayer(signal?: AbortSignal): Promise<{
+        enabled: boolean;
+    }>;
+    /** Turn the secret layer on or off for the whole daemon. */
+    setSecretLayer(enabled: boolean): Promise<{
+        enabled: boolean;
+    }>;
     /**
      * The one door a cookie VALUE leaves through, and it needs the vault password.
      *
@@ -1221,7 +1295,7 @@ declare class IdentityApi extends ClientCore {
  * All of it is display: nothing here starts, stops or changes anything.
  *
  * `RunActor`, `RunOutcome`, `StepKind`, `StepTarget`, `RunStep` and
- * `ProfileActivity` are NOT redeclared here — they live in `types.ts` because
+ * `ProfileActivity` are NOT redeclared here; they live in `types.ts` because
  * the live event stream carries them, and the run list describes the same rows.
  * A second copy would let the two drift apart while both looked right.
  *
@@ -1239,7 +1313,7 @@ interface AgentRun {
     profile_id: string;
     profile_name: string;
     actor: RunActor;
-    /** Never empty — described when it was not declared (see `goal_source`). */
+    /** Never empty; described when it was not declared (see `goal_source`). */
     goal: string;
     goal_source: GoalSource;
     /**
@@ -1280,7 +1354,7 @@ declare class RunsApi extends ClientCore {
     listRuns(params?: ListRunsParams, signal?: AbortSignal): Promise<AgentRun[]>;
     /** One run. */
     getRun(runId: string, signal?: AbortSignal): Promise<AgentRun>;
-    /** A run's steps, oldest first — the order they happened in. */
+    /** A run's steps, oldest first: the order they happened in. */
     listRunSteps(runId: string, params?: ListStepsParams, signal?: AbortSignal): Promise<RunStep[]>;
     /**
      * The still taken at one step, as JPEG bytes.
@@ -1294,7 +1368,7 @@ declare class RunsApi extends ClientCore {
 }
 
 /**
- * Direct-CDP driver (DEC-006, AC-FP-005) — a minimal, nodriver-style Chrome
+ * Direct-CDP driver (DEC-006, AC-FP-005): a minimal, nodriver-style Chrome
  * DevTools Protocol client over a raw websocket. This is the recommended SDK
  * driver plane: it is NOT the Playwright/Puppeteer control plane (which is a
  * detection vector independent of patch quality). We never call `Runtime.enable`
@@ -1328,7 +1402,7 @@ declare class CdpConnection {
     request<T>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T>;
     subscribe(cb: (event: CdpEvent) => void): () => void;
     /** 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: () => void): () => void;
     close(): void;
     get closed(): boolean;
@@ -1357,7 +1431,7 @@ interface ClickOptions {
     button?: string;
     clickCount?: number;
     /**
-     * B5: element-relative targeting — the effective target width (an element's
+     * B5: element-relative targeting. The effective target width (an element's
      * bounding-box size). The daemon's Fitts-law approach lands within the element
      * instead of on a fixed corner. Prefer {@link CdpSession.humanizeClickElement}.
      */
@@ -1472,7 +1546,7 @@ interface Metrics {
     availability?: MetricsAvailability;
     profiles?: ProfileResource[];
     /**
-     * Launchable host memory (MiB) — the capacity gate's own reading. "How many
+     * Launchable host memory (MiB), the capacity gate's own reading. "How many
      * more browsers fit" derives from THIS; `ram_budget_mb − ram_used_mb` does
      * not subtract (used is host-wide, the budget is the daemon's own ceiling).
      */
@@ -1480,11 +1554,11 @@ interface Metrics {
 }
 
 /**
- * `ScalebrowserClient` — the one typed HTTP surface every REST call goes
+ * `ScalebrowserClient`: the one typed HTTP surface every REST call goes
  * through. It centralises the base URL, Bearer auth, query-string building, JSON
  * (de)serialisation and error mapping (`{ code, message }` → {@link ApiError}).
  * Backend endpoint drift is a change in THIS file (paths) plus `types.ts`
- * (shapes) — nowhere else.
+ * (shapes), nowhere else.
  */
 
 /** Mirrors `CapacityConfig::default()` (`crates/core/src/config.rs`). */
@@ -1501,7 +1575,7 @@ interface LaunchHandle {
     readonly result: StartProfileResult;
     /** Close the CDP connection and stop the profile. */
     stop(): Promise<void>;
-    /** `await using` support — calls {@link stop}. */
+    /** `await using` support; calls {@link stop}. */
     [Symbol.asyncDispose](): Promise<void>;
 }
 /** Fallback: compute what we can purely from profile runtime states. */
@@ -1509,7 +1583,7 @@ declare function deriveMetricsFromProfiles(profiles: Profile[]): Metrics;
 declare class ScalebrowserClient extends ClientCore {
     listProfiles(params?: ListProfilesParams, signal?: AbortSignal): Promise<Profile[]>;
     /**
-     * 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.
@@ -1522,6 +1596,12 @@ declare class ScalebrowserClient extends ClientCore {
     /** Start a profile → CDP ws endpoint. Errors: 4002/4003/4005/4006/4008. */
     startProfile(id: string, body?: StartProfileBody): Promise<StartProfileResult>;
     stopProfile(id: string): Promise<StopProfileResult>;
+    /** 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: string): Promise<TakeoverResult>;
     bulkCreateProfiles(body: BulkCreateBody): Promise<Profile[]>;
     /**
      * Start a batch. `headless` is the ONE visibility decision for the run; omitted
@@ -1565,7 +1645,7 @@ declare class ScalebrowserClient extends ClientCore {
     /** Health + geo check (exit-ip/country/healthy + JA4↔JA4T verdict). */
     checkProxy(id: string): Promise<ProxyCheckResult>;
     /**
-     * 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.
      */
@@ -1597,9 +1677,80 @@ interface ScalebrowserClient extends IdentityApi, RunsApi, ControlApi, Extension
 }
 
 /**
- * `@scalebrowser/sdk` — the official Node/TypeScript SDK for the Scalebrowser
+ * Error model: stable numeric API error codes (SPEC §5,
+ * `crates/core/src/error.rs`) and the typed exceptions the SDK throws.
+ */
+/** Stable numeric API error codes (4001–4012, append-only: a retired code stays
+ * reserved rather than being reused). */
+declare const ErrorCode: {
+    readonly NotFound: 4001;
+    readonly ProxyGeo: 4002;
+    readonly Capacity: 4003;
+    readonly EngineMissing: 4004;
+    readonly Preflight: 4005;
+    readonly 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. */
+    readonly 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. */
+    readonly ConcurrencyLimit: 4008;
+    readonly 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. */
+    readonly 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. */
+    readonly ProfileInUse: 4012;
+};
+type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Error body shape: `{ code, message }` (docs/features/api.md). */
+interface ApiErrorBody {
+    code?: number;
+    message?: string;
+}
+/** Base class for every error this SDK throws, so callers can `catch` one type. */
+declare class ScalebrowserError extends Error {
+    constructor(message: string);
+}
+/**
+ * A typed transport/contract error. Carries the HTTP `status` and the daemon's
+ * numeric `code` so callers (and the auth layer) can react, e.g. 401 / code
+ * 4010 → re-authenticate.
+ */
+declare class ApiError extends ScalebrowserError {
+    readonly status: number;
+    readonly code?: number;
+    readonly body?: ApiErrorBody;
+    constructor(status: number, body?: ApiErrorBody, fallbackMessage?: string);
+    /** True for auth failures that must trigger re-authentication. */
+    get isAuthError(): boolean;
+    /** Short label for the error code, if any. */
+    get codeLabel(): string | undefined;
+}
+/** A network-level failure (daemon unreachable, socket error, fetch rejected). */
+declare class NetworkError extends ScalebrowserError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/** A CDP command that returned an `error` frame, or a closed CDP connection. */
+declare class CdpError extends ScalebrowserError {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** Narrow an unknown thrown value to a user-facing message. */
+declare function errorMessage(err: unknown): string;
+
+/**
+ * `@scalebrowser/sdk`: the official Node/TypeScript SDK for the Scalebrowser
  * daemon. A typed REST client plus a direct-CDP driver plane (nodriver-style,
- * NOT Playwright — DEC-006).
+ * NOT Playwright, DEC-006).
  *
  * ```ts
  * import { ScalebrowserClient } from '@scalebrowser/sdk';
@@ -1613,6 +1764,6 @@ interface ScalebrowserClient extends IdentityApi, RunsApi, ControlApi, Extension
  * ```
  */
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.4.1";
 
-export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type ClickOptions, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, HOST_MODES, type HealthStatus, type HostMode, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type Profile, type ProfileActivity, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TrustedInputBody, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };
+export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type ClickOptions, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, HOST_MODES, type HealthStatus, type HostMode, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type Profile, type ProfileActivity, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TrustedInputBody, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };