@boxline/sdk 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -2,7 +2,99 @@
 
 All notable changes to `@boxline/sdk`. The SDK follows [semantic versioning](https://semver.org).
 
-## 1.1.0 (not published yet)
+## 1.3.0 (2026-10-03)
+
+### Added
+
+- **Time limits that fit the server.** `session.login`, `typeCredential` with `field: "otp"` and plain-English steps that use `%NAME.otp%` or
+  `%NAME.link%` wait as long as the server may (up to 24 minutes for `login`, 16 for a code), instead of the
+  default 120 s that cut off a login waiting for a pushed code.
+
+- **Codes from your own system.** A password credential's `codeSource` is `"totp"` (the authenticator key,
+  `totpSecret`; `totpSecret` alone still means this), `"push"` or `"url"`, or null for no 2FA; with `"push"` or
+  `"url"` a run, action or `boxline-otp` that needs a code (or a sign-in link) waits for a fresh one, up to
+  `codeTimeoutSeconds` (5 to 900, default 300). `credentials.create` and `credentials.update` take `codeSource`,
+  `codeUrl` (a public HTTPS endpoint the platform asks with a signed POST) and `codeTimeoutSeconds`; a `PasswordCredential`
+  shows `codeSource`, `codeUrl` and `codeTimeoutSeconds`. Changing `codeSource` or `codeUrl` needs the `password` again
+  (400 `invalid_request`, 409 `conflict` on a race). With a `codeUrl` the answer has `codeUrlSecret` once (type
+  `CredentialWritten`). Types `CredentialCodeSource` and `CredentialWritten`.
+- **`credentials.pushCode(name, {code} | {link})`**: sends the code or sign-in link the site emailed or texted to a wait
+  in progress (used once, kept sealed for 10 minutes; a link must be on one of the credential's sites). Types
+  `CredentialCodePush` and `CredentialCodeAccepted`. Not retried by the SDK.
+- **`credentials.rotateCodeUrlSecret(name)`**: a new `codeUrlSecret` for the requests to `codeUrl` (check them with
+  `verifyWebhook`).
+- **`session.login(credential?, {url?, allowWithExtensions?})`** and the `login` action: signs the browser in with a
+  password credential in one call (a short browser-only agent run with that one credential and its sites). Resolves to
+  `{url, title, runId}` (`LoginValue`); an `ActionResult` of a failed `login` has `runId` and a `code`.
+- Errors `CredentialCodeTimeoutError` (`credential_code_timeout`: no code or link in time), `CredentialLinkWrongSiteError`
+  (`credential_link_wrong_site`), `CredentialLoginFailedError` (`credential_login_failed`, with `runId`),
+  `CredentialLoginTimeoutError` (`credential_login_timeout`: the login ran out of time, 15 steps plus the credential's
+  `codeTimeoutSeconds` for a pushed or asked code, and its run was canceled; a kind of `CredentialLoginFailedError`) and
+  `CodeUrlNotAllowedError` (`code_url_not_allowed`), and the matching `ErrorCode` values.
+- `session.login` resolves to the page's origin only (`value.url`) when the page is the one a sign-in link opened, since
+  such a link can keep its token in the path.
+- The webhook event `credential.code_needed` (`WebhookCredentialCodeNeededData`: `credential`, `type`, `sessionId`,
+  `runId`): a run waits for a code or link, so forward the site's email or SMS now. Never a code or link.
+- The credentials audit has `action: "code"` for a pushed code or link (never its value).
+- An agent run's steps (and `agent.stream` events) have `type: "code"` while it waits for a code or link: `state`
+  `"waiting"` (push it now), then `"received"` or `"timeout"`, with `credential` and `kind`; never the value.
+
+## 1.2.0 (2026-10-03)
+
+### Added
+
+- **Credentials**: `bx.credentials.list/create/get/update/delete/audit` (`/v1/credentials`), one place for what the AI
+  types and the shell uses, with a typed union per type: a **password** (`origins`, `username`, `password`, optional
+  `totpSecret`; shown as `PasswordCredential` with `username` and `hasTotp`) and a **secret** (`value`, optional
+  `origins`; shown as `SecretCredential` with `preview`). `credentials.create` returns the matching type; `scope`,
+  `shell`, `description` and the write-only rules are as for secrets. Types `Credential`, `CredentialType`,
+  `CredentialScope`, `CredentialField`, `PasswordCredential`, `SecretCredential`, `CredentialCreateParams`,
+  `PasswordCredentialCreateParams`, `SecretCredentialCreateParams`, `CredentialUpdateParams`,
+  `CredentialAuditEntry` (with `type`, and the new `usedBy` kinds `action` and `otp`) and `CredentialAuditParams`.
+  Passwords need the plan's `loginDetails`; `PlanLimit` is `maxCredentials`.
+- `credentials.update` that makes an AI-only credential readable by shells (`scope` to `"shell"` or `"all"`, or
+  `shell: true`) needs the values again in the same call, like a new site (the API answers 400 `invalid_request`
+  otherwise, 409 `conflict` when the sites, scope or `shell` changed meanwhile).
+- **`credentials: ["NAME"]`** where the API takes them: `sessions.create` (exported into the shell: a secret as `$NAME`,
+  a password as `$NAME_USERNAME` and `$NAME_PASSWORD`; `boxline-otp NAME` prints its 2FA code), `exec` and `execStream`,
+  `agent.run` and `session.step()` and the step action (placeholders `%NAME%`, `%NAME.username%`, `%NAME.password%`,
+  `%NAME.otp%`), `runScript`, and `tasks.create` / `tasks.update` (a task shows its `credentials`). A `Session` lists
+  the exported `credentials`.
+- **`session.typeCredential(name, {field, selector, allowWithExtensions})`** and the `type` action with `credential`
+  (and `field`: `"username"`, `"password"` or `"otp"`): a credential's value typed into a field without passing
+  through your code, only on the credential's sites.
+- **`profiles.update(id, {name?, credential?})`**: rename a profile and/or link the password credential it signs in
+  with (`credential: null` unlinks it). A `Profile` has `credential`; sessions with the profile, and the agent runs,
+  task runs and steps in them, get that credential as if it were listed.
+- Errors `CredentialExistsError` (409 `credential_exists`), `CredentialNotAllowedError` (400 `credential_not_for_ai`
+  / `credential_not_for_shell`), `TooManyCredentialValuesError` (409 `too_many_credential_values`) and
+  `ErrorCode.credentialNotFound` (404 `credential_not_found`, a `NotFoundError`). The webhook event `credential.changed`
+  (`WebhookCredentialChangedData`: `name`, `action`, `type`, `by`, `changed`).
+- `examples/credentials.ts`.
+
+### Changed (breaking)
+
+Nothing above shipped before, so these old names are gone with no aliases.
+
+- **Secrets and profile login details became credentials.** `bx.secrets` is `bx.credentials`; `secrets` on
+  `sessions.create`, `exec`, `agent.run`, steps, `runScript` and tasks is `credentials` (`Session.secrets` is
+  `Session.credentials`, `Task.secrets` is `Task.credentials`); `login: true` on `runScript` is gone (list the
+  credential); `profiles.setLogin`, `updateLogin` and `deleteLogin`, `Profile.login`, `LoginDetails`,
+  `LoginDetailsUpdate` and the placeholders `%login.username%`, `%login.password%` and `%login.otp%` are gone: create a
+  password credential and link it with `profiles.update(id, {credential})`. Types `Secret`, `SecretScope`,
+  `SecretCreateParams`, `SecretUpdateParams`, `SecretAuditEntry` and `SecretAuditParams` are replaced by the credential
+  types above; `SecretExistsError`, `SecretNotAllowedError` and `TooManySecretValuesError` by `CredentialExistsError`,
+  `CredentialNotAllowedError` and `TooManyCredentialValuesError`; the plan field `maxSecrets` is `maxCredentials`; the
+  webhook event `secret.changed` is `credential.changed`.
+- **Saved logins (contexts) are now browser profiles.** `bx.contexts` is `bx.profiles` (`create`, `get`, `list`,
+  `update`, `delete`; the routes are `/v1/profiles`; `contexts.rename` is `profiles.update(id, {name})`). Sessions and
+  agent runs take `profile: {id, persist?}` instead of `context`; tasks take `profile` instead of `savedLogin` (and
+  show it); a `Session` has `profileId` and `profilePersist` instead of `contextId` and `contextPersist`; the plan
+  fields are `maxProfiles` and `maxProfileBytes`, the plan feature is `"profiles"`, and the error code is
+  `ErrorCode.profileTooLarge` (`profile_too_large`). Types: `Profile` (was `ContextInfo`) and `TaskProfile`; the class
+  `Contexts` is `Profiles`. New profiles have ids starting with `prof_`. The old names are gone.
+
+## 1.1.0 (2026-10-02)
 
 ### Added
 

package/README.md

@@ -1,6 +1,8 @@
 # Boxline Node SDK
 
-Cloud browsers and shell sandboxes for AI agents. Each session is an isolated machine with a real Chrome and, if you
+**Give your AI agents the infrastructure they need: browsers, shells, storage and isolated machines.**
+
+Each session is an isolated machine with a real Chrome and, if you
 ask for it, a bash shell with Python and Node, sharing one `/workspace` disk.
 
 ```bash
@@ -22,7 +24,7 @@ instead of an API key, on the platform's own sites.
 - [An agent run with variables](#an-agent-run-with-variables)
 - [Limits, Continue and messages](#limits-continue-and-messages)
 - [Tasks and structured output](#tasks-and-structured-output)
-- [Secrets and saved login details](#secrets-and-saved-login-details)
+- [Credentials and browser profiles](#credentials-and-browser-profiles)
 - [A script with useModel](#a-script-with-usemodel)
 - [CAPTCHAs](#captchas)
 - [Browser settings and extensions](#browser-settings-and-extensions)
@@ -204,7 +206,7 @@ await bx.agent.sendMessage(run.id, "Also open page C and include its heading in
 
 ## Tasks and structured output
 
-A task is a saved agent run: an instruction with `%name%` variables, an output schema, browser settings, a saved login,
+A task is a saved agent run: an instruction with `%name%` variables, an output schema, browser settings, a profile,
 a model and, if you like, a schedule. Run it by hand or on its schedule; every run is an agent run.
 
 ```ts
@@ -239,45 +241,100 @@ await bx.tasks.update(task.id, { schedule: { enabled: true } });  // null remove
 - **Variables**: plain ones are written into the instruction (and kept with the run); `{ name, secret: true, origins }`
   is never stored, must come with every run, and is typed without the model seeing it. A task with a secret variable
   cannot have a schedule. A run missing a value throws `MissingVariablesError`.
+- **Credentials**: `credentials: ["SHOP"]` on `tasks.create` gives every run the saved credentials' placeholders (see
+  [Credentials and browser profiles](#credentials-and-browser-profiles)); a scheduled task may use them, and the task
+  keeps the names only.
 - **Schedules**: five-field cron (at most every 5 minutes) read in `timezone`. A scheduled run is `queued` until it
   starts; a time that comes while a run is still going is `skipped`, and times the platform was down for are `missed`
   (`reason`, `missedCount`). The plan limits tasks and schedules switched on (`PlanLimitError`).
 - `waitForRun` takes the run from `run()` or `(taskId, taskRunId)`, with `{pollMs, timeoutMs}`; there is no GET for
   one task run, so it watches the task's unfinished runs.
 
-## Secrets and saved login details
+## Credentials and browser profiles
 
-Project secrets are write-only: the value is sealed when stored and never returned or shown. Each secret's `scope` says
-where it may be used: `"agent"` (the default: only the AI, as `%NAME%`), `"shell"` (only as `$NAME` in shells) or `"all"`.
+Credentials are write-only: the value is sealed when stored and never returned or shown. There are two types, a website
+**password** (sites, user name, password and an optional 2FA key) and a **secret** (one value, such as an API token).
+The name is the handle: the AI's placeholder (`%GITHUB_TOKEN%`, `%SHOP.password%`) and the shell variable
+(`$GITHUB_TOKEN`, `$SHOP_PASSWORD`). Each credential's `scope` says where it may be used: `"agent"` (the default: only
+the AI), `"shell"` (only as variables in shells) or `"all"`.
 
 ```ts
-await bx.secrets.create({ name: "GITHUB_TOKEN", value: process.env.GITHUB_TOKEN!, scope: "shell" });
-await bx.secrets.create({ name: "SITE_PASSWORD", value: process.env.SITE_PASSWORD!, origins: ["https://example.com"] });
+await bx.credentials.create({ name: "GITHUB_TOKEN", type: "secret", value: process.env.GITHUB_TOKEN!, scope: "shell" });
+const shop = await bx.credentials.create({
+  name: "SHOP",
+  type: "password",
+  origins: ["https://shop.example.com"],          // the only site the AI may type it on
+  username: "ops@example.com",
+  password: process.env.SHOP_PASSWORD!,
+  totpSecret: process.env.SHOP_2FA_KEY,           // optional: %SHOP.otp% is the current code
+});
+console.log(shop.type, shop.username, shop.hasTotp); // narrowed to PasswordCredential; no value anywhere
 
-// In a shell: exported as $GITHUB_TOKEN, and shown as %GITHUB_TOKEN% wherever it appears in the output.
-const s = await bx.sessions.create({ shell: true, env: { REGION: "eu" }, secrets: ["GITHUB_TOKEN"] });
+// In a shell: $GITHUB_TOKEN, shown as %GITHUB_TOKEN% wherever it appears in the output.
+const s = await bx.sessions.create({ shell: true, env: { REGION: "eu" }, credentials: ["GITHUB_TOKEN"] });
 await s.exec("gh repo list --limit 3");
-await s.exec("./deploy.sh", { secrets: ["DEPLOY_KEY"] });                 // this one command only
+await s.exec("./deploy.sh", { credentials: ["DEPLOY_KEY"] });             // this one command only
+
+// For the AI: typed only on the credential's sites, never shown to the model.
+await s.step("sign in with %SHOP.username% and %SHOP.password%", { credentials: ["SHOP"] });
+await bx.agent.run({ task: "Sign in to https://shop.example.com with %SHOP.username% and %SHOP.password%", credentials: ["SHOP"] });
+// Or type one field yourself without seeing it (the field's own frame must be on one of the credential's sites):
+await s.typeCredential("SHOP", { field: "password", selector: "#password" });
 
-// For the AI: typed as %SITE_PASSWORD% only on its sites, never shown to the model.
-await s.step("type %SITE_PASSWORD% into the password field", { secrets: ["SITE_PASSWORD"] });
-await bx.agent.run({ task: "Sign in to https://example.com with %SITE_PASSWORD%", secrets: ["SITE_PASSWORD"] });
+// A profile keeps cookies; link a password and the AI can sign in again when they expire.
+await bx.profiles.update(profile.id, { credential: "SHOP" });
+
+for await (const e of bx.credentials.audit({ name: "SHOP" })) console.log(e.at, e.action, e.actor, e.usedBy?.type);
+```
+
+- **Exported credentials can be read by anything that runs in the shell**, including an agent's commands that a web
+  page tries to steer. Export only what you accept that for; keep website passwords at scope `"agent"` with `origins`.
+  Hiding values in output is a guard against accidents, not a boundary. A 2FA key never enters the machine:
+  `boxline-otp SHOP` in the shell asks the platform for the current code.
+- `credentials.update` changes the fields you send; a new site needs the sensitive values again in the same call, and
+  so does a change of where the codes come from (`codeSource`, `codeUrl`: the `password` again).
+- `runScript(code, { credentials })` lets the script's `step()` calls use credentials (the values never enter the
+  machine). In a session with Chrome extensions, steps, scripts and the `type` action with credentials need
+  `allowWithExtensions: true`, as agent runs with variables do.
+- Errors: `CredentialExistsError` (use `update`), `CredentialNotAllowedError` (the scope does not allow that use),
+  `NotFoundError` (`credential_not_found`), `TooManyCredentialValuesError` (the session hides as many values as it can:
+  start a new one), `FeatureNotInPlanError` (a password needs the plan's `loginDetails`), `MachineTooOldError` (during
+  a deploy), `PlanLimitError` (beyond the plan's `maxCredentials`), `CredentialCodeTimeoutError` (no code or link came
+  in time), `CredentialLinkWrongSiteError` (a sign-in link not on the credential's sites), `CredentialLoginFailedError`
+  (`session.login` could not sign in; `runId` is the run that tried), `CodeUrlNotAllowedError` (a `codeUrl` that is not a
+  public HTTPS address).
+- The `credential.changed` webhook event says a credential was created, changed (or linked to a profile) or deleted,
+  never a value.
+
+### Codes sent by email or SMS, and signing in in one call
+
+A password's 2FA codes can come from an authenticator key (`codeSource: "totp"`, what `totpSecret` alone means), from
+**your system** (`"push"`) or from **an endpoint of yours** (`"url"`). The site's email or SMS goes to you; the AI
+never sees the code or a sign-in ("magic") link.
+
+```ts
+await bx.credentials.create({
+  name: "SHOP", type: "password", origins: ["https://shop.example.com"], username: "ops@example.com",
+  password: process.env.SHOP_PASSWORD!,
+  codeSource: "push",              // or "url" with codeUrl: "https://ops.example.com/boxline-codes"
+  codeTimeoutSeconds: 300,         // how long a run waits for a code (5 to 900)
+});
 
-// A saved login's details with 2FA: %login.username%, %login.password% and %login.otp% in sessions started with it.
-await bx.contexts.setLogin(context.id, { origin: "https://example.com", username: "ada@example.com", password, totpSecret });
+// A run, an action or `boxline-otp SHOP` that needs a code waits for a fresh one. The webhook credential.code_needed
+// ({credential, type: "code" | "link", sessionId, runId}) says when; then push what the site sent:
+await bx.credentials.pushCode("SHOP", { code: "482913" });                      // a 2FA code
+await bx.credentials.pushCode("SHOP", { link: "https://shop.example.com/magic?t=…" }); // or a sign-in link
 
-for await (const e of bx.secrets.audit({ name: "GITHUB_TOKEN" })) console.log(e.at, e.action, e.actor, e.usedBy?.type);
+// Sign in in one call: a short browser-only run with this one credential (default: the session's profile's).
+const page = await s.login("SHOP", { url: "https://shop.example.com/login" });   // {url, title, runId}
 ```
 
-- **Exported secrets can be read by anything that runs in the shell**, including an agent's commands that a web page
-  tries to steer. Export only what you accept that for; keep passwords at scope `"agent"` with `origins`. Hiding
-  values in output is a guard against accidents, not a boundary.
-- `runScript(code, { secrets, login: true })` lets the script's `step()` calls use secrets and the saved login's
-  details (the values never enter the machine). In a session with Chrome extensions, steps and scripts with secrets
-  need `allowWithExtensions: true`, as agent runs with variables do.
-- Errors: `SecretExistsError` (use `update`), `SecretNotAllowedError` (the scope does not allow that use),
-  `TooManySecretValuesError` (the session hides as many values as it can: start a new one), `MachineTooOldError`
-  (during a deploy), `PlanLimitError` (beyond the plan's `maxSecrets`).
+- A pushed code or link is used once, by a wait that began before it arrived, and kept sealed for 10 minutes. A link must
+  be on one of the credential's sites. `pushCode` is not retried by the SDK (a second push is a second code).
+- With `codeSource: "url"` the platform asks your `codeUrl` every 5 s while a run waits (a signed POST; check it with
+  `verifyWebhook` and the `codeUrlSecret` that `create` and `update` return once; `credentials.rotateCodeUrlSecret(name)`
+  makes a new one). Answer `{code}` or `{link}`, or 204 for "not yet".
+- Without a code in time a step, action or `login` throws `CredentialCodeTimeoutError`.
 
 ## A script with useModel
 
@@ -397,8 +454,8 @@ for await (const e of session.events({ types: ["console", "error"] })) console.l
 for await (const p of page.iterPages()) console.log(p.data.length);
 ```
 
-Lists: `sessions.list`, `sessions.events`, `sessions.pages`, `contexts.list`, `apiKeys.list`, `agent.list`,
-`crawl.list`, `extensions.list`, `tasks.list`, `tasks.runs`, `secrets.list`, `secrets.audit`, and a crawl's pages (`crawl.get(id, {after})`, or
+Lists: `sessions.list`, `sessions.events`, `sessions.pages`, `profiles.list`, `apiKeys.list`, `agent.list`,
+`crawl.list`, `extensions.list`, `tasks.list`, `tasks.runs`, `credentials.list`, `credentials.audit`, and a crawl's pages (`crawl.get(id, {after})`, or
 `for await (const p of bx.crawl.pages(id))`).
 
 ## Errors, retries and time limits
@@ -411,13 +468,14 @@ Lists: `sessions.list`, `sessions.events`, `sessions.pages`, `contexts.list`, `a
   `OutOfViewportError`, `WebhookUrlNotAllowedError`, `WebhooksUnavailableError`, `WebhookDisabledError`,
   `PayloadExpiredError`, `WebhookSignatureError` (from verifyWebhook), `VariablesWithExtensionsError`,
   `InvalidExtensionError`, `PayloadTooLargeError`, `LimitReachedError`, `ExtensionDeniedError`, `CrossSiteRequestError`,
-  `MissingVariablesError`, `PlanLimitError`, `SecretExistsError`, `SecretNotAllowedError`, `TooManySecretValuesError`,
+  `MissingVariablesError`, `PlanLimitError`, `CredentialExistsError`, `CredentialNotAllowedError`, `TooManyCredentialValuesError`,
+  `CredentialCodeTimeoutError`, `CredentialLinkWrongSiteError`, `CredentialLoginFailedError`, `CodeUrlNotAllowedError`,
   `MachineTooOldError`, `NotContinuableError`, `TooManyMessagesError`, `SessionNotRunningError`, `AuthenticationError`,
   `NotFoundError`, and
   `BoxlineConnectionError` /
   `BoxlineTimeoutError` when no answer came back. `ErrorCode` has the codes.
 - **Retries.** GETs, and the calls that create or start something (sessions, bulk, agent runs, continued runs, messages
-  to runs, crawls, API keys, contexts, extension uploads, tasks, task runs), are retried after a network error, a time-out, 429 and 5xx: 2 retries by default, exponential backoff
+  to runs, crawls, API keys, profiles, extension uploads, tasks, task runs), are retried after a network error, a time-out, 429 and 5xx: 2 retries by default, exponential backoff
   from 0.5 s to 8 s with jitter, or what `Retry-After` / `RateLimit-Reset` say (up to 60 s; longer waits go to you as a
   `RateLimitError`). Other POSTs (exec, actions, fetch…) are never retried: they could run twice.
 - **Idempotency keys.** The SDK sends a new `Idempotency-Key` with every create, and the same one on its retries, so a
@@ -446,12 +504,12 @@ same methods without it (`session.pause()`).
 | Account | `me`, `hasFeature`, `auth.signup`, `auth.login`, `auth.logout`, `project.trajectories`, `project.setTrajectories`, `project.settings`, `project.setSettings`, `apiKeys.list`, `apiKeys.create`, `apiKeys.revoke` |
 | Webhooks | `webhooks.create`, `list`, `get`, `update`, `delete`, `rotateSecret`, `test`, `deliveries`, `retryDelivery`; `verifyWebhook` (no request) |
 | Sessions | `sessions.create`, `get`, `list`, `update`, `release`, `pause`, `resume`, `move`, `extend`, `rotateProxy`, `rotateUrls`, `live`, `bulk` |
-| Browser | `sessions.actions`, `sessions.computer`; on a session: `goto`, `click`, `hover`, `fill`, `type`, `press`, `scroll`, `wait`, `select`, `elements`, `evaluate`, `content`, `screenshot`, `cursor`, `upload`, `tabs`, `newTab`, `switchTab`, `closeTab`, `back`, `forward`, `reload`, `step`, `extract`, `exportCookies`, `computer`, `mouse.move`/`moveBy`/`click`/`down`/`up`/`drag`, `keyboard.key`/`type`/`press` |
+| Browser | `sessions.actions`, `sessions.computer`; on a session: `goto`, `click`, `hover`, `fill`, `type`, `typeCredential`, `press`, `scroll`, `wait`, `select`, `elements`, `evaluate`, `content`, `screenshot`, `cursor`, `upload`, `tabs`, `newTab`, `switchTab`, `closeTab`, `back`, `forward`, `reload`, `step`, `extract`, `exportCookies`, `computer`, `mouse.move`/`moveBy`/`click`/`down`/`up`/`drag`, `keyboard.key`/`type`/`press` |
 | Shell and scripts | `sessions.exec`, `execStream`, `runScript`, `restartShell` |
 | Files | `sessions.files.list`, `read`, `readText`, `write`, `delete`, `waitFor` |
 | Logs | `sessions.events`, `streamEvents`, `pages`, `recording`, `recordingFrame`; on a session: `waitForHuman`, `onCaptcha` |
-| Saved logins | `contexts.create`, `get`, `list`, `rename`, `delete`, `setLogin`, `deleteLogin` |
-| Secrets | `secrets.create`, `list`, `get`, `update`, `delete`, `audit` |
+| Browser profiles | `profiles.create`, `get`, `list`, `update`, `delete` |
+| Credentials | `credentials.create`, `list`, `get`, `update`, `delete`, `audit`, `pushCode`, `rotateCodeUrlSecret`; on a session: `typeCredential`, `login` |
 | Extensions | `extensions.upload`, `list`, `get`, `delete` |
 | Web | `fetch`, `screenshot`, `pdf`, `extract`, `search`, `crawl.start`, `get`, `list`, `cancel`, `pages`, `wait` |
 | Agent | `agent.models`, `run`, `get`, `list`, `takeover`, `handBack`, `cancel`, `continueRun`, `sendMessage`, `stream`, `wait` |
@@ -477,7 +535,7 @@ reach, so run them with `BOXLINE_API_URL=http://localhost:8080`; `search.ts` and
 | `webhooks.ts` | endpoints, deliveries and their history, re-sending, rotating the secret, a test event |
 | `agent-variables.ts` | an agent run with `%email%` / `%password%` limited to one site |
 | `tasks.ts` | a task with an output schema on a demo shop: run with a variable, waited for, its history, changed, deleted; an agent run with `output` |
-| `secrets.ts` | a secret exported into a shell (its length checked, its value hidden in output), changed, audited, deleted; login details on a saved login |
+| `credentials.ts` | a secret exported into a shell (its length checked, its value hidden in output), changed, audited, deleted; a password with 2FA linked to a profile |
 | `script-use-model.ts` | `useModel`, `step()` and `extract()` in a script |
 | `captcha.ts` | noticing a CAPTCHA and handing it to a person |
 | `block-ads.ts` | a session that blocks ads and trackers, and its `blockedRequests` count |

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { type CoreConfig, type Query, type RequestOptions, type SendInit } from "./core.js";
 import { Page, PagePromise } from "./pagination.js";
 import { Session } from "./session.js";
-import type { ActionItem, ActionResult, AgentMessageSent, AgentModelCatalog, AgentRun, AgentRunEvent, AgentRunParams, AgentRunStarted, ContinueRunParams, ApiKeyInfo, BulkResult, ComputerAction, ComputerOptions, ComputerResult, ContextInfo, LoginDetails, LoginDetailsUpdate, MoveShell, Secret, SecretAuditEntry, SecretAuditParams, SecretCreateParams, SecretUpdateParams, CrawlGetParams, CrawlJob, CrawlPage, CrawlParams, CreateSessionParams, ExecExit, ExecOptions, ExecResult, ExtensionInfo, ExtractParams, ExtractResult, FetchParams, FetchResult, FileList, FileRef, ListParams, LoginResponse, Me, MoveTimings, NewApiKey, NewWebhookEndpoint, ProjectSettings as ProjectSettingsData, AgentProvider, ModelKey, ModelKeyParams, CaptchaMode, WebhookCreateParams, WebhookDelivery, WebhookDeliveryListParams, WebhookEndpoint, WebhookEventType, WebhookEventTypeList, WebhookUpdateParams, PdfParams, PlanFeature, Pricing, Recording, RunScriptOptions, ScreenshotParams, ScriptResult, SearchParams, SearchResponse, SessionEvent, SessionEventsParams, SessionListParams, SessionUrls, SignupResponse, Stats, Task, TaskCreateParams, TaskRun, TaskRunListParams, TaskRunParams, TaskUpdateParams, TrajectoriesSetting, UpdateSessionParams, Usage, VisitedPage } from "./types.js";
+import type { ActionItem, ActionResult, AgentMessageSent, AgentModelCatalog, AgentRun, AgentRunEvent, AgentRunParams, AgentRunStarted, ContinueRunParams, ApiKeyInfo, BulkResult, ComputerAction, ComputerOptions, ComputerResult, Profile, ProfileUpdateParams, MoveShell, Credential, CredentialAuditEntry, CredentialCodeAccepted, CredentialCodePush, CredentialAuditParams, CredentialCreateParams, CredentialUpdateParams, CredentialWritten, PasswordCredential, PasswordCredentialCreateParams, SecretCredential, SecretCredentialCreateParams, CrawlGetParams, CrawlJob, CrawlPage, CrawlParams, CreateSessionParams, ExecExit, ExecOptions, ExecResult, ExtensionInfo, ExtractParams, ExtractResult, FetchParams, FetchResult, FileList, FileRef, ListParams, LoginResponse, Me, MoveTimings, NewApiKey, NewWebhookEndpoint, ProjectSettings as ProjectSettingsData, AgentProvider, ModelKey, ModelKeyParams, CaptchaMode, WebhookCreateParams, WebhookDelivery, WebhookDeliveryListParams, WebhookEndpoint, WebhookEventType, WebhookEventTypeList, WebhookUpdateParams, PdfParams, PlanFeature, Pricing, Recording, RunScriptOptions, ScreenshotParams, ScriptResult, SearchParams, SearchResponse, SessionEvent, SessionEventsParams, SessionListParams, SessionUrls, SignupResponse, Stats, Task, TaskCreateParams, TaskRun, TaskRunListParams, TaskRunParams, TaskUpdateParams, TrajectoriesSetting, UpdateSessionParams, Usage, VisitedPage } from "./types.js";
 export interface BoxlineOptions {
     /** Defaults to the BOXLINE_API_KEY environment variable. */
     apiKey?: string;
@@ -34,11 +34,11 @@ export declare class Boxline {
     readonly project: ProjectSettings;
     readonly apiKeys: ApiKeys;
     readonly sessions: Sessions;
-    readonly contexts: Contexts;
+    readonly profiles: Profiles;
     readonly crawl: Crawl;
     readonly agent: Agent;
     readonly tasks: Tasks;
-    readonly secrets: Secrets;
+    readonly credentials: Credentials;
     readonly webhooks: Webhooks;
     readonly extensions: Extensions;
     /** @internal */
@@ -284,70 +284,92 @@ export declare class SessionFiles {
     /** Waits for a file matching a glob (e.g. `downloads/*.csv`) that has finished writing. */
     waitFor(id: string, pattern: string, timeoutMs?: number, options?: RequestOptions): Promise<FileRef>;
 }
-/** Saved logins: cookies and local storage to start sessions with (`context: {id, persist: true}` fills one). */
-export declare class Contexts {
+/** Browser profiles: cookies and local storage to start sessions with (`profile: {id, persist: true}` fills one). */
+export declare class Profiles {
     private readonly client;
     constructor(client: Boxline);
     /**
-     * A new saved login: empty, or with `fromSession` holding that working session's current cookies and site storage
+     * A new profile: empty, or with `fromSession` holding that working session's current cookies and site storage
      * (sign in there first, e.g. in its live view). `attach: true` also makes the session save to it from now on (at its
-     * checkpoints and when it ends); a session that already has a saved login refuses that (409 `conflict`). 413
-     * `context_too_large` over 16 MB; PlanLimitError (402) past the plan's `maxContexts` or `maxContextBytes`.
+     * checkpoints and when it ends); a session that already has a profile refuses that (409 `conflict`). 413
+     * `profile_too_large` over 16 MB; PlanLimitError (402) past the plan's `maxProfiles` or `maxProfileBytes`.
      */
     create(params?: {
         name?: string;
         fromSession?: string;
         attach?: boolean;
-    }, options?: RequestOptions): Promise<ContextInfo>;
-    get(id: string, options?: RequestOptions): Promise<ContextInfo>;
+    }, options?: RequestOptions): Promise<Profile>;
+    get(id: string, options?: RequestOptions): Promise<Profile>;
     /** Newest first; the first page's `total` counts them all. */
-    list(params?: ListParams, options?: RequestOptions): PagePromise<ContextInfo, Page<ContextInfo> & {
+    list(params?: ListParams, options?: RequestOptions): PagePromise<Profile, Page<Profile> & {
         total: number;
     }>;
-    rename(id: string, name: string, options?: RequestOptions): Promise<ContextInfo>;
-    delete(id: string, options?: RequestOptions): Promise<void>;
-    /**
-     * Keeps sign-in details on the saved login (plan feature `loginDetails`), replacing earlier ones: the site, user name,
-     * password and optionally the 2FA setup key, sealed like secrets. Returns the context, whose `login` shows
-     * `{origin, username, hasPassword, hasTotp}`, never the password or the 2FA secret.
-     */
-    setLogin(id: string, details: LoginDetails, options?: RequestOptions): Promise<ContextInfo>;
     /**
-     * Changes some of the login details and keeps the rest (setLogin replaces them all); `totpSecret: null` removes 2FA.
-     * A password never moves to another site on its own: a new `origin` needs `password` in the same call, and
-     * `totpSecret` (a new one or null) when the login has 2FA (400 otherwise). A BoxlineError with code `conflict` (409)
-     * when the login changed meanwhile: send it again.
+     * Changes the name and/or the password credential the profile signs in with: `credential: "SHOP"` links a password
+     * credential (see `credentials`), so sessions with this profile, and agent runs, task runs and steps in them, get it
+     * as if it were listed in their `credentials` and the AI can sign in again when the cookies have expired; `null`
+     * unlinks it. NotFoundError (404 `credential_not_found`) for a name the project does not have, a 400 BoxlineError
+     * for a secret (only passwords sign in), FeatureNotInPlanError (402) without the plan's `loginDetails`.
      */
-    updateLogin(id: string, changes: LoginDetailsUpdate, options?: RequestOptions): Promise<ContextInfo>;
-    /** Removes the login details (the saved cookies and storage stay). */
-    deleteLogin(id: string, options?: RequestOptions): Promise<void>;
+    update(id: string, changes: ProfileUpdateParams, options?: RequestOptions): Promise<Profile>;
+    delete(id: string, options?: RequestOptions): Promise<void>;
 }
 /**
- * Project secrets: write-only values the AI uses as %NAME% placeholders (`secrets` on agent runs, steps and scripts) and
- * shells get as environment variables (`secrets` on sessions.create and exec), depending on each secret's `scope`. The
- * value is never returned, logged or shown; every change and use is audited.
+ * Credentials: write-only website passwords (with an optional 2FA key) and secrets. The AI uses them as placeholders
+ * (`%NAME%`, `%SHOP.password%`) with `credentials` on agent runs, steps, scripts, tasks and `Session.typeCredential`;
+ * shells get them as environment variables (`credentials` on sessions.create and exec), depending on each
+ * credential's `scope`. A value is never returned, logged or shown; every change and use is audited.
  */
-export declare class Secrets {
+export declare class Credentials {
     private readonly client;
     constructor(client: Boxline);
-    /** The project's secrets, in name order, without their values. */
-    list(params?: ListParams, options?: RequestOptions): PagePromise<Secret>;
+    /** The project's credentials, in name order, without their values. */
+    list(params?: ListParams, options?: RequestOptions): PagePromise<Credential>;
     /**
-     * Stores a secret, sealed; the answer never has the value. SecretExistsError for a name the project has (change it
-     * with update), PlanLimitError beyond the plan's `maxSecrets`. Not retried by the SDK (the API takes no
-     * Idempotency-Key here): a retry after a lost answer may meet SecretExistsError.
+     * Stores a credential, sealed; the answer never has a value. `type: "password"` takes `origins`, `username`,
+     * `password` and optionally where its 2FA codes come from: `codeSource: "totp"` with `totpSecret`, `"push"` (send
+     * each code or sign-in link with `pushCode`) or `"url"` with `codeUrl` (needs the plan's `loginDetails`:
+     * FeatureNotInPlanError); `type: "secret"` takes `value`. CredentialExistsError for a name the project has (change it
+     * with update), PlanLimitError beyond the plan's `maxCredentials`; 400 `code_url_not_allowed` for a `codeUrl` that is
+     * not a public HTTPS address. With `codeUrl` the answer has `codeUrlSecret`, the key that signs the platform's
+     * requests, shown this once. Not retried by the SDK (the API takes no Idempotency-Key here): a retry after a lost
+     * answer may meet CredentialExistsError.
      */
-    create(params: SecretCreateParams, options?: RequestOptions): Promise<Secret>;
-    get(name: string, options?: RequestOptions): Promise<Secret>;
+    create(params: PasswordCredentialCreateParams, options?: RequestOptions): Promise<CredentialWritten<PasswordCredential>>;
+    create(params: SecretCredentialCreateParams, options?: RequestOptions): Promise<CredentialWritten<SecretCredential>>;
+    create(params: CredentialCreateParams, options?: RequestOptions): Promise<CredentialWritten>;
+    get(name: string, options?: RequestOptions): Promise<Credential>;
     /**
-     * Changes the fields you send. A running agent run keeps the value it started with; a session that exports the secret
-     * gets the new value on its next machine (move, resume, recovery).
+     * Changes the fields you send (the type cannot change: delete it and create it again). A new site, or a `scope`
+     * or `shell` that makes an AI-only credential readable by shells, needs the sensitive values again in the same call
+     * (a secret's `value`; a password's `password`, and `totpSecret` when it has 2FA), else a 400 `invalid_request`; so
+     * does a change of where a password's codes come from (`codeSource`, removing 2FA included, or `codeUrl`: the
+     * `password` again). A 409 `conflict` when the sites, scope, `shell`, `codeSource` or `codeUrl` changed meanwhile
+     * (send it again). A new `codeUrl` answers with a new `codeUrlSecret`, shown once. A running agent run keeps the
+     * values it started with; a session that exports the credential gets the new ones on its next machine (move,
+     * resume, recovery).
      */
-    update(name: string, patch: SecretUpdateParams, options?: RequestOptions): Promise<Secret>;
-    /** Deletes it; sessions that exported it no longer get it on their next machine. */
+    update(name: string, patch: CredentialUpdateParams, options?: RequestOptions): Promise<CredentialWritten>;
+    /** Deletes it; profiles that link it are unlinked, and sessions that exported it no longer get it on their next machine. */
     delete(name: string, options?: RequestOptions): Promise<void>;
-    /** Changes to secrets and saved login details, and each use (once per session, command, run or script), newest first. */
-    audit(params?: SecretAuditParams, options?: RequestOptions): PagePromise<SecretAuditEntry>;
+    /**
+     * For a password with `codeSource: "push"`: sends the code (`{code}`) or the sign-in link (`{link}`) the site emailed
+     * or texted, for a run, action or `boxline-otp` that waits for it (the webhook `credential.code_needed` says when).
+     * It is kept sealed for up to 10 minutes and used once, by a wait that began before it arrived. A link must be on one of
+     * the credential's sites (400 `credential_link_wrong_site`). 400 `invalid_request` for a credential whose source is
+     * not "push"; NotFoundError for one the project does not have. Not retried by the SDK (a second push is a second
+     * code). The value is never logged or returned.
+     */
+    pushCode(name: string, code: CredentialCodePush, options?: RequestOptions): Promise<CredentialCodeAccepted>;
+    /**
+     * For a password with `codeSource: "url"`: a new `codeUrlSecret` (`whsec_…`, shown this once). Requests to `codeUrl` are
+     * signed with it from now on (check them with `verifyWebhook`); the old one stops at once.
+     */
+    rotateCodeUrlSecret(name: string, options?: RequestOptions): Promise<{
+        codeUrlSecret: string;
+    }>;
+    /** Changes to credentials and each use (once per session, command, run, script, task run, typed field or 2FA code) and pushed codes, newest first. */
+    audit(params?: CredentialAuditParams, options?: RequestOptions): PagePromise<CredentialAuditEntry>;
 }
 /** Crawls: follow links from a start URL in the background (robots.txt respected); poll with get() or wait(). */
 export declare class Crawl {
@@ -496,8 +518,8 @@ export declare class Agent {
     cancel(id: string, options?: RequestOptions): Promise<AgentRun>;
     /**
      * Continues a run that stopped at one of its limits (errorCode max_steps, max_cost, too_many_errors or no_progress)
-     * while its `continuable` is set: a new run in the same session, with the same model, mode, output schema, secrets
-     * and saved login, and a compact record of what the previous run did. Returns the new run (`continuedFrom` links
+     * while its `continuable` is set: a new run in the same session, with the same model, mode, output schema, credentials
+     * and profile, and a compact record of what the previous run did. Returns the new run (`continuedFrom` links
      * back); wait for it with `wait(run.id)` or `stream(run.id)` like any run. A run that had `variables` needs them again
      * (MissingVariablesError otherwise). NotContinuableError: it did not stop at a limit, was continued already, or its
      * window passed. An Idempotency-Key is sent, so a retry never starts a second run.