@scalebrowser/sdk 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -9,6 +9,86 @@ reconstructing it here would look like a record that had been kept all along.
 The daemon and the SDK version independently. An SDK release names the daemon
 version it was tested against wherever that matters.
 
+## 1.3.0 (2026-11-05)
+
+Tested against daemon 0.26.0. Nothing is removed or renamed: every change adds a
+method, a field or a value to a union. A daemon up to 0.25.x answers the new
+workflow, table and plan routes with 404 or leaves the new fields out.
+
+- **Plans**: an account without a subscription is on `free` now, and
+  `enterprise` is a plan too (`Account.plan`). `Account` gains `profile_limit` and
+  `workflow_limit` (absent when the plan has no cap) and `workflows_local`.
+- `ErrorCode.PlanLimit` (4014): the plan itself stops an action, for example a
+  fourth profile on Free, a schedule on Free or a workflow over the plan's
+  number. The error body's `plan_limit` names the limit, the allowed number, the
+  plan and whether the 7-day trial is still open. `ApiError.reason` carries the
+  case where one numeric code covers several.
+- **Workflows**, the whole surface the app's workflow editor uses, about ninety
+  methods: create, edit, rename and delete (`createWorkflow`, `editWorkflow`,
+  `renameWorkflow`, `deleteWorkflow`, `workflowDeletePreview`), versions and
+  publishing (`saveWorkflowVersion`, `publishWorkflow`, `listWorkflowVersions`,
+  `diffWorkflow`, `revertWorkflow`, `adoptWorkflowVersion`, `undoWorkflowBatch`),
+  runs (`startWorkflowRun`, `listWorkflowRuns`, `getWorkflowRun`,
+  `listWorkflowRunSteps`, `cancelWorkflowRun`, `forkWorkflowRun`,
+  `previewWorkflowRunFork`, `decideWorkflowRun`, run files), approvals
+  (`listWorkflowApprovals`, `decideWorkflowApproval`, the approval webhook),
+  triggers and switches (`workflowHooks`, `rotateWorkflowHook`,
+  `listWorkflowFires`, `listWorkflowSwitches`, `setWorkflowSwitch`,
+  `emergencyStopWorkflows`), variables, file access, repairs, readiness, usage,
+  the queue, node types and the settings schema, templates
+  (`workflowTemplates`, `instantiateTemplate`), sharing (`shareWorkflow`,
+  `importSharedWorkflow`, `revokeWorkflowShare`) and the machines a workflow runs
+  on (`workflowMachines`, `cancelWorkflowForward`).
+- **Tables**: `createTable`, `listTables`, `getTable`, `updateTable`, `editTable`,
+  `listTableRows`, `countTableRows`, `importTable`, `exportTable`, the trash
+  (`listTableTrash`, `restoreTables`) and `deleteTable`.
+- **Google Sheets**: `connectGoogle`, `listGoogleConnections`, `linkSheet` and
+  `disconnectGoogle`.
+- **Model sources for the AI steps**: `listAiSources`, `createAiSource`,
+  `updateAiSource`, `checkAiSource`, `deleteAiSource`, `getAiSettings`,
+  `putAiSettings` and `listAiInvocations`.
+- **White label**: `agencyClients`, `setAgencyDistribution`, `setAgencyAiKey`,
+  `setClientBriefMode`, `wlSharing` and `setWlSharing`.
+- A run, an activity and an agent run can now name `workflow` as their actor
+  (`RunActor`), and `workflows` is a tool group (`ToolGroupId`).
+
+- `revealInbox(profileId, { vault_password })`: the profile's bound mailbox for a
+  script, with every message, the code candidates in it and each link with its
+  full address. Behind the vault password, because a sign-in link IS the account.
+- `listPendingInterruptions(profileId, { targetId })`: what waits in a tab right
+  now. Operator locks and standing rules answer what they decide first, and those
+  come back under `already_answered`.
+- `respondInterruption(profileId, { interruption_id, choice })`: answer one the
+  way its own button would. A kind an operator lock decides is refused with 409.
+- `LifecycleEvent` lacked three events the daemon sends: `concurrency_rejected`,
+  `secret_changed` (the whole entry as `SecretRow`, never a value) and
+  `secret_gone`. A test compares the union with the daemon's own list, so a new
+  event can no longer be missing here.
+- `WorkflowSyncView.unsent` (`UnsentChange[]`): what this machine could not send
+  to its other machines, with the workflow, its size and since when. The daemon
+  now splits a large saved version into parts, so only a change above about 8 MB
+  lands here. Optional: a daemon up to 0.24.0 does not send it.
+
+## 1.2.0 (2026-10-22)
+
+Two fixes in the CDP driver, both measured against a real browser, and three
+methods for routes the daemon serves since 0.24.0. Nothing is removed or renamed.
+
+- `navigate()` waited for the load by reading `document.readyState` in the
+  page's own world. A page that wraps that getter saw two reads with no script of
+  its own on the stack. The wait now reads from an isolated world.
+- `evaluate(expr, { isolated: true })` kept the id of its isolated world across a
+  navigation, so every isolated read after a page change failed with
+  `Cannot find context with specified id`. It now asks for the world of the
+  current document on every call.
+- `revealRequest(profileId, seq, { vault_password })`: what a recorded request
+  carried (the full address with its query, every header value and, on request,
+  the body), behind the vault password. `seq` is the number the agent's
+  `net_capture` tool lists.
+- `getAgentTools()` and `setAgentToolGroup(group, enabled)`: which optional MCP tool
+  groups agents on this machine see.
+- The README lists every method of the client.
+
 ## 1.1.0 (2026-10-04)
 
 Three fields the daemon has sent since 0.20.0 now have types. All three are

package/README.md

@@ -62,10 +62,13 @@ try {
 
 Every `/v1` endpoint is a typed method on `ScalebrowserClient`:
 
-- **Profiles**: `listProfiles`, `getProfile`, `createProfile`, `updateProfile`,
-  `deleteProfile`, `startProfile`, `stopProfile`
+- **Profiles**: `listProfiles`, `listProfileIds`, `countProfiles`, `getProfile`,
+  `createProfile`, `updateProfile`, `deleteProfile`, `startProfile`, `stopProfile`.
+  `releaseProfile` drops an agent's lease without its handle (the operator's way
+  out), and `takeoverProfile` asks for a profile that is open on another machine
+  of your account
 - **Bulk**: `bulkCreateProfiles`, `bulkStart`, `bulkStop`, `bulkDelete`,
-  `bulkAssignProxy`
+  `bulkAssignProxy`, `bulkAssignExtensions`
 - **Groups / Presets**: `listGroups`/`createGroup`/`getGroup`/`updateGroup`/`deleteGroup`,
   `listPresets`/`createPreset`/`getPreset`/`updatePreset`/`deletePreset`,
   `getPersonaConstraints`. A preset is `config` (what the profiles do:
@@ -78,34 +81,114 @@ Every `/v1` endpoint is a typed method on `ScalebrowserClient`:
   it; pass `id` to reuse an existing proxy's stored credentials). Credentials
   are write-only, never returned
 - **Extensions**: `listExtensions`, `attachExtension`, `detachExtension`, plus
-  the daemon-wide library (`uploadExtension`, `getLibraryExtension`,
-  `deleteLibraryExtension`). An attached package IS loaded into the browser at
+  the daemon-wide library (`listLibraryExtensions`, `uploadExtension`,
+  `getLibraryExtension`, `deleteLibraryExtension`, `deleteLibraryExtensionVersion`). An attached package IS loaded into the browser at
   launch, under the canonical Web-Store id its own key derives
-- **Credentials**: `listCredentials`, `putCredential`, `revealCredential`
-  (needs the vault password), `exportCredentials`, `importCredentials`
+- **Credentials**: `listCredentials`, `putCredential`, `deleteCredential`,
+  `revealCredential` (needs the vault password), `exportCredentials`,
+  `importCredentials`. The vault password itself: `vaultStatus`, `setVaultPassword`
+- **Secret layer**: `getSecretLayer`, `setSecretLayer`, `listSecrets`,
+  `updateSecret`, `deleteSecret`. `scrubText` filters a text you hold against a
+  profile's values, and `runWithSecrets` runs a command with named values in its
+  environment, so no value crosses a socket
 - **Cookies**: `revealCookies`, the one route a cookie VALUE leaves through,
   behind the same vault password
+- **Recorded requests**: `revealRequest`, the one route what a request carried (query,
+  header values, body) leaves through, behind the same vault password
 - **Sessions**: `exportSession`, `importSession`
 - **Mailboxes**: `listInboxes`, `createInbox`, `updateInbox`, `deleteInbox`,
   `getInboxBindings`, `bindInbox`, `unbindInbox`, which is where a profile's
-  confirmation codes arrive
+  confirmation codes arrive. `revealInbox` reads them: every message, the code
+  candidates in it and each link with its full address, behind the vault password
+  because a sign-in link IS the account
 - **Passkeys**: `listPasskeys`, `deletePasskey`. Metadata only: the private key
   has no field and no endpoint
 - **Agent runs**: `listRuns`, `getRun`, `listRunSteps`, `getRunShot`,
   `getActivity`. Read-only, all of it
 - **Interruptions**: `listInterruptionLocks`, `setInterruptionLock`,
   `listInterruptionRules`, `setInterruptionRule`, `deleteInterruptionRule`: who
-  may answer when the browser asks something
+  may answer when the browser asks something. `listPendingInterruptions` shows what
+  waits in a tab right now and `respondInterruption` answers it; a kind an
+  operator lock decides is refused (409)
 - **Artifacts**: `putArtifact` (hand the daemon a file to upload later),
   `getArtifact` (fetch a screenshot, download or saved PDF as bytes)
+- **Tasks and memory**: `listTasks`, `createTasks`, `cancelTask`, `deleteTask`,
+  plus a profile's standing instructions for agents, its `PROFILE.md`:
+  `getProfileMemory`, `putProfileMemory`, `deleteProfileMemory`
+- **Videos**: `listVideos`, `getVideo`, `renameVideo`, `deleteVideo`,
+  `cancelVideo`, `rerenderVideo`, `videoAccess`, `downloadVideoFile`,
+  `videosStorage`; recordings with `listRecordings`, `getRecording`,
+  `deleteRecordingRaw`, `renderRecording`; public links with `share`,
+  `shareStatus`, `revokeShare`
+- **Video presets**: `listVideoPresets`, `getVideoPreset`, `createVideoPreset`,
+  `updateVideoPreset`, `duplicateVideoPreset`, `deleteVideoPreset`, and a look
+  at an unsaved config with `previewVideoPreset`, `previewVideoPresetClip`,
+  `downloadVideoPresetClip`. The files a preset points at: `listMedia`,
+  `uploadMedia`, `deleteMedia`, `mediaFile`. Narration keys: `listTtsProviders`,
+  `putTtsProvider`, `verifyTtsProvider`, `deleteTtsProvider`. Encoders:
+  `getCodecs`, `setCodecEnabled`
+- **Fingerprint audit**: `startAudit` drives the profile's running browser through
+  the external detector pages, `getAudit` reads the state and the last report
+- **Exit addresses**: `getExitStatus` (which addresses a profile owns), and the
+  machine's rule that one address belongs to one profile: `getExitRule`,
+  `setExitRule`
+- **Machine settings**: `getRemoteAccess`, `setRemoteAccess` (may a chat service
+  reach this machine's browsers), `getAgentTools`, `setAgentToolGroup` (which
+  optional MCP tool groups agents see), `getConnection` (which installation
+  answered: its data directory and its binary)
 - **Input**: `sendInput`
+- **Workflows**: `listWorkflows`, `getWorkflow`, `createWorkflow`, `editWorkflow`,
+  `renameWorkflow`, `deleteWorkflow`, `workflowDeletePreview`, `extractWorkflow`.
+  `extractWorkflow` moves a part of the draft into a workflow of its own
+- **Workflow versions**: `listWorkflowVersions`, `getWorkflowVersion`,
+  `saveWorkflowVersion`, `publishWorkflow`, `diffWorkflow`, `revertWorkflow`,
+  `adoptWorkflowVersion`, `undoWorkflowBatch`. Saving, publishing and going back
+- **Workflow runs**: `startWorkflowRun`, `listWorkflowRuns`, `getWorkflowRun`,
+  `listWorkflowRunSteps`, `listWorkflowRunFiles`, `getWorkflowRunFile`,
+  `cancelWorkflowRun`, `forkWorkflowRun`, `previewWorkflowRunFork`,
+  `decideWorkflowRun`, `getWorkflowQueue`, `getWorkflowUsage`,
+  `getWorkflowReadiness`. A fork runs again from a chosen step and keeps the outputs
+  before it
+- **Approvals**: `listWorkflowApprovals`, `decideWorkflowApproval`,
+  `getApprovalWebhook`, `setApprovalWebhook`. Steps that wait for a person
+- **Triggers and switches**: `workflowHooks`, `rotateWorkflowHook`,
+  `listWorkflowFires`, `listWorkflowSwitches`, `setWorkflowSwitch`,
+  `emergencyStopWorkflows`. Schedules and webhooks need a paid plan (4014 on Free)
+- **Variables and files**: `listWorkflowVariables`, `setWorkflowVariable`,
+  `revealWorkflowVariable`, `getWorkflowFileAccess`, `setWorkflowFileAccess`,
+  `grantWorkflowFolder`, `ungrantWorkflowFolder`, `listWorkflowFastDomains`,
+  `putWorkflowFastDomain`, `deleteWorkflowFastDomain`. A secret variable is shown
+  again only through `revealWorkflowVariable`, behind the vault password
+- **Repairs**: `listWorkflowRepairs`, `getWorkflowRepair`, `revertWorkflowRepair`,
+  `getWorkflowRepairMetrics`. The fixes the repair made when a step broke
+- **Building blocks**: `listNodeTypes`, `getNodeType`, `getWorkflowSettingsSchema`,
+  `getWorkflowReferenceSources`, `workflowTemplates`, `instantiateTemplate`
+- **Sharing and machines**: `shareWorkflow`, `importSharedWorkflow`,
+  `revokeWorkflowShare`, `workflowMachines`, `cancelWorkflowForward`.
+  `workflowMachines` names the machine each profile lives on; a start sent there can
+  be cancelled
+- **Tables**: `countTableRows`, `createTable`, `deleteTable`, `editTable`,
+  `exportTable`, `getTable`, `importTable`, `listTableRows`, `listTableTrash`,
+  `listTables`, `restoreTables`, `updateTable`. The data a workflow reads and
+  writes, with a trash
+- **Google Sheets**: `connectGoogle`, `disconnectGoogle`, `linkSheet`,
+  `listGoogleConnections`. Linked with Google's own picker; on Free only through
+  your own Google Cloud project
+- **Model sources**: `checkAiSource`, `createAiSource`, `deleteAiSource`,
+  `getAiSettings`, `listAiInvocations`, `listAiSources`, `putAiSettings`,
+  `updateAiSource`. The keys and models behind the AI steps
+- **White label**: `agencyClients`, `setAgencyAiKey`, `setAgencyDistribution`,
+  `setClientBriefMode`, `setWlSharing`, `wlSharing`. For an Enterprise agency and
+  its clients
 - **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–4012):
+`setToken` swaps the bearer token on a live client.
+
+Errors map to typed exceptions carrying the daemon's numeric code (4001–4014; 4014 is a plan limit, with `plan_limit` in its body):
 
 ```ts
 import { ApiError, ErrorCode } from '@scalebrowser/sdk';
@@ -140,7 +223,10 @@ 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)
-- `navigate(url, { wait, timeout })`, `evaluate<T>(expr, { isolated })`
+- `navigate(url, { wait, timeout })`, `evaluate<T>(expr, { isolated })`. The
+  wait for the load reads from an isolated world, so a page that watches its own
+  `document.readyState` sees no foreign read; `isolated: true` asks for the world
+  of the document that is loaded now, on every call
 - `createIsolatedWorld(frameId?, worldName?)`
 - `attachToPage({ targetId?, create?, url? })`
 - `on(method, cb)` / `events()`: CDP event subscription scoped to the session