@boxline/sdk 1.1.0 → 1.3.0

package/dist/types.d.ts

@@ -42,7 +42,7 @@ export interface LoginResponse {
     project: Project;
 }
 /** What a plan may use; set per plan in the admin panel. Calls that need a missing one fail with 402 `feature_not_in_plan`. */
-export type PlanFeature = "shell" | "pauseResume" | "contexts" | "recording" | "realisticBrowser" | "residentialProxy" | "datacenterProxy" | "customProxy" | "captchaSolving" | "agentRuns" | "steps" | "extract" | "quickApis" | "crawl" | "extensions" | "webSearch" | "loginDetails"
+export type PlanFeature = "shell" | "pauseResume" | "profiles" | "recording" | "realisticBrowser" | "residentialProxy" | "datacenterProxy" | "customProxy" | "captchaSolving" | "agentRuns" | "steps" | "extract" | "quickApis" | "crawl" | "extensions" | "webSearch" | "loginDetails"
 /** Model calls on Boxline's keys; without it (Free) a project runs models on its own keys only. */
  | "platformModels";
 /** A plan's limits (null = no limit) and features. */
@@ -69,12 +69,12 @@ export interface Plan {
     tasks?: number | null;
     /** Tasks with a schedule switched on; 0 = no schedules, null = no limit. */
     schedules?: number | null;
-    /** Project secrets a project may keep. */
-    maxSecrets?: number;
-    /** Saved logins (contexts) a project may keep; null = no limit. */
-    maxContexts?: number | null;
-    /** Bytes a project's saved logins may hold together; null = no limit. */
-    maxContextBytes?: number | null;
+    /** Credentials (passwords and secrets together) a project may keep. */
+    maxCredentials?: number;
+    /** Browser profiles a project may keep; null = no limit. */
+    maxProfiles?: number | null;
+    /** Bytes a project's profiles may hold together; null = no limit. */
+    maxProfileBytes?: number | null;
     features: Record<PlanFeature, boolean>;
     public?: boolean;
 }
@@ -280,9 +280,9 @@ export interface SessionData {
     /** A CAPTCHA waiting for a person, or null. */
     attention: CaptchaAttention | null;
     workspacePath: string;
-    contextId: string | null;
-    /** Whether the session saves its sign-ins back to `contextId` when it ends. */
-    contextPersist?: boolean;
+    profileId: string | null;
+    /** Whether the session saves its sign-ins back to `profileId` when it ends. */
+    profilePersist?: boolean;
     userMetadata: Record<string, unknown>;
     moves: number;
     /** When the last automatic checkpoint was taken (null before the first one). */
@@ -307,8 +307,8 @@ export interface SessionData {
     extensions: string[];
     /** The names of the session's env variables (values are never returned). */
     env?: string[];
-    /** The names of the project secrets its shell exports. */
-    secrets?: string[];
+    /** The names of the credentials its shell exports (a credential its profile links is listed too when it went into the shell). */
+    credentials?: string[];
     usage: {
         seconds: number;
         costUsd: number;
@@ -340,8 +340,8 @@ export interface CreateSessionParams {
     keepAlive?: boolean;
     viewport?: Viewport;
     userMetadata?: Record<string, unknown>;
-    /** Start from a saved login; `persist: true` saves the browser's logins back into it at the end. */
-    context?: {
+    /** Start from a profile; `persist: true` saves the browser's logins back into it at the end. */
+    profile?: {
         id: string;
         persist?: boolean;
     };
@@ -378,11 +378,13 @@ export interface CreateSessionParams {
      */
     env?: Record<string, string | number | boolean>;
     /**
-     * Project secrets exported into the shell as `$NAME` (needs shell: true; the secret needs scope "shell" or "all", or
-     * shell: true, else SecretNotAllowedError). Kept in the machine's memory only and hidden in exec, script and terminal
-     * output. Anything that runs in the shell can read them: export only what you accept that for.
+     * Credentials exported into the shell (needs shell: true; the credential needs scope "shell" or "all", or shell:
+     * true, else CredentialNotAllowedError): a secret as `$NAME`, a password as `$NAME_USERNAME` and `$NAME_PASSWORD`
+     * (its 2FA code comes from `boxline-otp NAME`, the key itself never enters the machine). Kept in the machine's
+     * memory only and hidden in exec, script and terminal output. Anything that runs in the shell can read them: export
+     * only what you accept that for.
      */
-    secrets?: string[];
+    credentials?: string[];
 }
 export interface UpdateSessionParams {
     keepAlive?: boolean;
@@ -437,13 +439,13 @@ export interface MoveTimings {
 }
 /**
  * Sessions with a shell, after a move: where the shell continues and which exported variables came along (the
- * session's env and secrets are set again as well). Running processes do not move; the ones that were stopped are listed.
+ * session's env and credentials are set again as well). Running processes do not move; the ones that were stopped are listed.
  */
 export interface MoveShell {
     cwd: string;
     /** Names of the variables the commands exported. */
     exported: string[];
-    /** `command` with secret values hidden, at most 200 characters; `seconds`: how long it had run. */
+    /** `command` with credential values hidden, at most 200 characters; `seconds`: how long it had run. */
     stoppedProcesses: {
         pid: number;
         command: string;
@@ -488,6 +490,18 @@ export type Action = {
     text: string;
     selector?: string;
     delayMs?: number;
+}
+/**
+ * Types a credential's value without it passing through you (see Session.typeCredential): `field` is `"username"`,
+ * `"password"` or `"otp"` (the current 2FA code) for a password, and left out for a secret. A credential with sites
+ * (every password) goes only into the field `selector` names, on one of those sites.
+ */
+ | {
+    action: "type";
+    credential: string;
+    field?: CredentialField;
+    selector?: string;
+    allowWithExtensions?: boolean;
 } | {
     action: "press";
     key: string;
@@ -599,9 +613,13 @@ export type Action = {
     action: "step";
     instruction: string;
     variables?: Record<string, string>;
-    /** Project secrets usable as %NAME% (scope "agent" or "all"), each on its own sites; never shown in the result. */
-    secrets?: string[];
-    /** Allow `secrets` and saved login details in a session with Chrome extensions (VariablesWithExtensionsError otherwise). */
+    /**
+     * Credentials usable as placeholders (scope "agent" or "all"): `%NAME%` for a secret, `%NAME.username%`,
+     * `%NAME.password%` and `%NAME.otp%` for a password, each on its own sites; never shown in the result. A
+     * credential the session's profile links is offered too.
+     */
+    credentials?: string[];
+    /** Allow `credentials` in a session with Chrome extensions (VariablesWithExtensionsError otherwise). */
     allowWithExtensions?: boolean;
     provider?: AgentProvider;
     model?: string;
@@ -615,6 +633,16 @@ export type Action = {
     provider?: AgentProvider;
     model?: string;
     targetId?: string;
+}
+/**
+ * Signs the browser in with a password credential (default: the one the session's profile links) in one call, see
+ * Session.login. It runs alone: the only action of its request.
+ */
+ | {
+    action: "login";
+    credential?: string;
+    url?: string;
+    allowWithExtensions?: boolean;
 };
 /** An action, or a plain-English step written as a bare string ("click Sign in"). */
 export type ActionItem = Action | string;
@@ -626,10 +654,18 @@ export interface ActionResult {
     /** One line saying what happened ("Dragged from (180, 200) to (400, 200) in 10 steps"); never typed text. */
     text?: string;
     error?: string;
-    /** A stable error code when there is one (e.g. "captcha_timeout", "out_of_viewport"). */
+    /** A stable error code when there is one (e.g. "captcha_timeout", "out_of_viewport"; for `login`: "credential_login_failed", "credential_login_timeout", "credential_code_timeout", "credential_link_wrong_site"). */
     code?: string;
+    /** `login`: the agent run that signed in (also in its value when it worked). */
+    runId?: string;
     ms: number;
 }
+/** What `Session.login` returns: the page the browser is on after signing in (no query or fragment) and the run that did it. */
+export interface LoginValue {
+    url: string;
+    title: string;
+    runId: string;
+}
 export interface GotoResult {
     url: string;
     title: string;
@@ -761,14 +797,15 @@ export interface StepOptions {
     /** Text values for %name% placeholders. */
     variables?: Record<string, string>;
     /**
-     * Project secrets usable as %NAME% (scope "agent" or "all"), each only on its own sites and in the shell only with
-     * shell: true. The step's result never shows their values. In a session with a saved login's details,
-     * %login.username%, %login.password% and %login.otp% work too, on that login's site only.
+     * Credentials usable as placeholders (scope "agent" or "all"): `%NAME%` for a secret, `%NAME.username%`,
+     * `%NAME.password%` and `%NAME.otp%` for a password. Each is typed only on its own sites and, in the shell, only
+     * with `shell: true`. The step's result never shows their values. In a session whose profile links a password
+     * credential, that credential is offered too.
      */
-    secrets?: string[];
+    credentials?: string[];
     /**
-     * Allow `secrets` and saved login details in a session with Chrome extensions, which can read every typed value
-     * (secrets: VariablesWithExtensionsError otherwise; login details are not offered). Logs a warning in the session's events.
+     * Allow `credentials` in a session with Chrome extensions, which can read every typed value
+     * (VariablesWithExtensionsError otherwise). Logs a warning in the session's events.
      */
     allowWithExtensions?: boolean;
     provider?: AgentProvider;
@@ -780,8 +817,11 @@ export interface ExecOptions {
     cwd?: string;
     /** Variables for this command only (it may set PATH, HOME and the like for itself). */
     env?: Record<string, string>;
-    /** Project secrets as environment variables for this command only (scope "shell" or "all", or shell: true); hidden in the output. */
-    secrets?: string[];
+    /**
+     * Credentials as environment variables for this command only (scope "shell" or "all", or shell: true): a secret as
+     * `$NAME`, a password as `$NAME_USERNAME` and `$NAME_PASSWORD`, and `boxline-otp NAME` prints its 2FA code. Hidden in the output.
+     */
+    credentials?: string[];
     /** Named persistent shell (default "default"); false runs in a fresh process with no kept state. */
     shell?: string | false;
 }
@@ -816,14 +856,13 @@ export interface RunScriptOptions {
         model?: string;
     };
     /**
-     * Project secrets the script's step() calls may use as %NAME% (scope "agent" or "all"). The values never enter the
-     * machine: the platform fills them in when the step runs. The grant is for this run only.
+     * Credentials the script's step() calls may use as placeholders (scope "agent" or "all"). The values never enter the
+     * machine: the platform fills them in when the step runs. The grant is for this run only. A credential the
+     * session's profile links is used only when it is listed here.
      */
-    secrets?: string[];
-    /** Let step() use the session's saved login details (%login.username%, %login.password%, %login.otp%). */
-    login?: boolean;
+    credentials?: string[];
     /**
-     * Allow `secrets` and `login` in a session with Chrome extensions, which can read every typed value
+     * Allow `credentials` in a session with Chrome extensions, which can read every typed value
      * (VariablesWithExtensionsError otherwise); a warning goes into the session's events.
      */
     allowWithExtensions?: boolean;
@@ -883,7 +922,7 @@ export interface Recording {
     }[];
     durationMs: number;
 }
-export interface ContextInfo {
+export interface Profile {
     id: string;
     name: string;
     sizeBytes: number;
@@ -891,43 +930,22 @@ export interface ContextInfo {
     updatedAt: string;
     /** The running session using it. */
     inUseBy: string | null;
-    /** Its login details (contexts.setLogin), never the password or the 2FA secret; null without any. */
-    login?: ContextLogin | null;
-}
-/** What a saved login shows of its login details. */
-export interface ContextLogin {
-    origin: string;
-    username: string;
-    hasPassword: boolean;
-    hasTotp: boolean;
-    updatedAt?: string;
-}
-/**
- * A saved login's sign-in details (plan feature `loginDetails`). Agent runs, plain-English steps and scripts' step() in
- * a session started with that context get %login.username%, %login.password% and %login.otp% (a TOTP code made when it
- * is typed), filled in only into fields whose frame is on `origin`, never into shell commands, never shown to the model.
- */
-export interface LoginDetails {
-    /** The one site they may be typed on: "https://example.com" or "https://*.example.com" (any subdomain). */
-    origin: string;
-    /** At most 320 characters. */
-    username: string;
-    /** 1 to 1024 characters. */
-    password: string;
     /**
-     * The site's 2FA setup key (base32, any case, spaces allowed) or an otpauth://totp/ link from its QR code (SHA1,
-     * SHA256 or SHA512, 6 to 8 digits, a 15 to 120 s period; defaults SHA-1, 6 digits, 30 s).
+     * The name of the password credential it signs in with (profiles.update with `credential`), or null. Sessions with
+     * the profile, and agent runs, task runs and steps in them, get it as if it were listed in their `credentials`.
      */
-    totpSecret?: string;
+    credential: string | null;
 }
-/** contexts.updateLogin: any of the login details; what is not sent is kept. */
-export interface LoginDetailsUpdate {
-    /** A new site: needs `password` too (and `totpSecret` when the login has 2FA), or the call fails with 400. */
-    origin?: string;
-    username?: string;
-    password?: string;
-    /** A new 2FA setup key or otpauth://totp/ link; null removes 2FA. */
-    totpSecret?: string | null;
+/** profiles.update: any of these (at least one). */
+export interface ProfileUpdateParams {
+    /** 1 to 100 characters. */
+    name?: string;
+    /**
+     * Link the password credential this profile signs in with, so the AI can sign in again when its cookies have
+     * expired; null unlinks it. NotFoundError (404 `credential_not_found`) for a name the project does not have, 400 for a secret (only
+     * passwords sign in), FeatureNotInPlanError (402) without `loginDetails`.
+     */
+    credential?: string | null;
 }
 /** Options shared by fetch, screenshot and pdf. */
 export interface RenderOptions {
@@ -1197,15 +1215,17 @@ export interface AgentRunParams {
     /** Keep the run's own session after it finishes (until its expiresAt, with keepAlive on). */
     keepSession?: boolean;
     /**
-     * Project secrets as %NAME% placeholders, exactly like `variables`, each with the secret's own `origins` and `shell`
-     * rule (scope "agent" or "all"; SecretNotAllowedError for scope "shell"). An explicit variable with the same name wins.
+     * Credentials as placeholders, exactly like `variables`, each with the credential's own `origins` and `shell` rule
+     * (scope "agent" or "all"; CredentialNotAllowedError for scope "shell"): `%NAME%` for a secret, `%NAME.username%`,
+     * `%NAME.password%` and `%NAME.otp%` for a password. An explicit variable with the same name wins. A password
+     * credential linked to the session's profile is added for you.
      */
-    secrets?: string[];
+    credentials?: string[];
     /**
-     * For the run's own session: a saved login to start with. With login details the run also gets %login.username%,
-     * %login.password% and %login.otp% on the login's site.
+     * For the run's own session: a profile to start with. When it links a password credential (profiles.update), the
+     * run gets that credential as if it were listed in `credentials`.
      */
-    context?: {
+    profile?: {
         id: string;
         persist?: boolean;
     };
@@ -1291,7 +1311,8 @@ export interface AgentMessageSent {
 }
 export interface AgentStep {
     /** message: a message you sent (agent.sendMessage), recorded when the model received it. */
-    type: "text" | "tool" | "handover" | "handback" | "captcha" | "message";
+    /** code: the run waits for a password's 2FA code or sign-in link (`credentials.pushCode`, or your `codeUrl`), see `state`. */
+    type: "text" | "tool" | "handover" | "handback" | "captcha" | "message" | "code";
     at: string;
     /** message steps: who wrote it, its id, when it was sent (`at` is when the model got it). */
     from?: "user";
@@ -1309,9 +1330,14 @@ export interface AgentStep {
     output?: string;
     isError?: boolean;
     ms?: number;
-    /** captcha steps: "solving" (automatic solving), "waiting" (a person's turn), "solved" (the run goes on). */
-    state?: "solving" | "waiting" | "solved";
-    /** captcha steps: the CAPTCHA kind and the host of its page. */
+    /**
+     * captcha steps: "solving" (automatic solving), "waiting" (a person's turn), "solved" (the run goes on); code steps:
+     * "waiting" (a wait began: push the code or link now), then "received" or "timeout". Never the code or the link.
+     */
+    state?: "solving" | "waiting" | "solved" | "received" | "timeout";
+    /** code steps: the password credential whose code or link the run waits for. */
+    credential?: string;
+    /** captcha steps: the CAPTCHA kind and the host of its page; code steps: "code" or "link". */
     kind?: string;
     host?: string;
     /** captcha "waiting": why a person is asked. */
@@ -1436,7 +1462,7 @@ export interface TaskVariable {
 /**
  * The settings of each run's own session, as on sessions.create, checked when saved and again at each run. A custom
  * proxy's password is stored encrypted and never returned. `allowWithExtensions` is needed for a task with secret
- * variables and extensions (VariablesWithExtensionsError otherwise).
+ * variables or credentials and extensions (VariablesWithExtensionsError otherwise).
  */
 export interface TaskBrowser extends BrowserOptions {
     shell?: boolean;
@@ -1486,8 +1512,8 @@ export interface TaskLastRun {
     createdAt: string;
     finishedAt: string | null;
 }
-/** A saved login (context) each run's session starts with: its id, or `{id, persist}` (persist: keep what the run changes). */
-export type TaskSavedLogin = string | {
+/** A browser profile each run's session starts with: its id, or `{id, persist}` (persist: keep what the run changes). */
+export type TaskProfile = string | {
     id: string;
     persist?: boolean;
 };
@@ -1499,14 +1525,14 @@ export interface TaskCreateParams {
     /** Up to 50. */
     variables?: TaskVariable[];
     /**
-     * Project secrets (by name, up to 50) each run gets as %NAME%, as `secrets` on agent runs. They must exist with scope
-     * "agent" or "all"; a scheduled task may use them (secret variables cannot be scheduled).
+     * Credentials (by name, up to 50) each run gets as placeholders, as `credentials` on agent runs. They must exist with
+     * scope "agent" or "all"; a scheduled task may use them (secret variables cannot be scheduled).
      */
-    secrets?: string[];
+    credentials?: string[];
     /** Structured output for every run (see OutputSchema). */
     output?: OutputSchema;
     browser?: TaskBrowser;
-    savedLogin?: TaskSavedLogin;
+    profile?: TaskProfile;
     /** From agent.models() (default: the server's default model). */
     model?: {
         provider?: AgentProvider;
@@ -1527,10 +1553,10 @@ export interface TaskUpdateParams {
     instruction?: string;
     variables?: TaskVariable[];
     /** The whole new list; null or [] removes them. */
-    secrets?: string[] | null;
+    credentials?: string[] | null;
     output?: OutputSchema | null;
     browser?: TaskBrowser | null;
-    savedLogin?: TaskSavedLogin | null;
+    profile?: TaskProfile | null;
     model?: {
         provider?: AgentProvider;
         model?: string;
@@ -1549,11 +1575,11 @@ export interface Task {
     name: string;
     instruction: string;
     variables: TaskVariable[];
-    /** Names of the project secrets its runs get (never values). */
-    secrets: string[];
+    /** Names of the credentials its runs get (never values). */
+    credentials: string[];
     output: OutputSchema | null;
     browser: TaskBrowser | null;
-    savedLogin: {
+    profile: {
         id: string;
         persist: boolean;
     } | null;
@@ -1619,7 +1645,7 @@ export interface TaskRun<T = unknown> {
 export interface TaskRunParams {
     /** Values by name. Secret variables must be given on every run; plain ones fall back to their defaults. */
     variables?: Record<string, string | number | boolean>;
-    /** Work in this session (its own settings apply; the task's `browser` and `savedLogin` do not). */
+    /** Work in this session (its own settings apply; the task's `browser` and `profile` do not). */
     sessionId?: string;
 }
 export interface TaskRunListParams extends ListParams {
@@ -1716,7 +1742,7 @@ export interface Pricing {
  * The events an endpoint can subscribe to (`webhook.test` needs no subscription). New types may be added: an endpoint
  * subscribed to "*" gets them too, so a receiver should ignore types it does not know.
  */
-export type WebhookEventType = "session.started" | "session.expiring" | "session.ended" | "agent_run.started" | "agent_run.waiting" | "agent_run.resumed" | "agent_run.finished" | "captcha.waiting" | "captcha.solved" | "captcha.failed" | "crawl.finished" | "task_run.started" | "task_run.finished" | "task.schedule_paused" | "usage.limit_reached" | "api_key.created" | "api_key.revoked" | "secret.changed" | "webhook.changed" | "webhook.disabled" | "extension.uploaded" | "extension.deleted";
+export type WebhookEventType = "session.started" | "session.expiring" | "session.ended" | "agent_run.started" | "agent_run.waiting" | "agent_run.resumed" | "agent_run.finished" | "captcha.waiting" | "captcha.solved" | "captcha.failed" | "crawl.finished" | "task_run.started" | "task_run.finished" | "task.schedule_paused" | "usage.limit_reached" | "api_key.created" | "api_key.revoked" | "credential.code_needed" | "credential.changed" | "webhook.changed" | "webhook.disabled" | "extension.uploaded" | "extension.deleted";
 /** What an endpoint subscribes to: event types, or "*" for all of them (those added later too). */
 export type WebhookSubscription = WebhookEventType | "*";
 /** One entry of bx.webhooks.eventTypes(): a type, its group (for pickers) and what it says. */
@@ -1995,13 +2021,22 @@ export interface WebhookApiKeyData {
     name: string;
     by: WebhookActor;
 }
-export interface WebhookSecretChangedData {
-    /** The secret's name, or for a login the context's id. */
+export interface WebhookCredentialCodeNeededData {
+    /** The password credential whose code or sign-in link is awaited. */
+    credential: string;
+    /** What the site sends: a 2FA code or a sign-in link. Forward it now with `credentials.pushCode`. */
+    type: "code" | "link";
+    sessionId: string;
+    /** The agent run that waits; null for an action or `boxline-otp`. */
+    runId: string | null;
+}
+export interface WebhookCredentialChangedData {
+    /** The credential's name. */
     name: string;
     action: "created" | "updated" | "deleted";
-    kind: "secret" | "login";
+    type: CredentialType;
     by: WebhookActor;
-    /** Field names an update changed ("value", "origins", …). */
+    /** Field names an update changed ("password", "origins", …; "profiles" when it was linked to or unlinked from a profile). */
     changed?: string[];
 }
 export interface WebhookChangedData {
@@ -2048,7 +2083,8 @@ export interface WebhookEventDataMap {
     "usage.limit_reached": WebhookUsageLimitData;
     "api_key.created": WebhookApiKeyData;
     "api_key.revoked": WebhookApiKeyData;
-    "secret.changed": WebhookSecretChangedData;
+    "credential.code_needed": WebhookCredentialCodeNeededData;
+    "credential.changed": WebhookCredentialChangedData;
     "webhook.changed": WebhookChangedData;
     "webhook.disabled": WebhookDisabledData;
     "extension.uploaded": WebhookExtensionData;
@@ -2064,71 +2100,197 @@ export type WebhookEventPayload = {
         type: K;
     };
 }[keyof WebhookEventDataMap];
+/** A credential holds a website password (with an optional 2FA key) or a secret (one value). */
+export type CredentialType = "password" | "secret";
+/**
+ * Where a credential may be used: "agent" (default): only the AI, as placeholders in agent runs, plain-English steps,
+ * scripts' step() and the type action; "shell": only as environment variables in session shells and commands; "all": both.
+ */
+export type CredentialScope = "agent" | "shell" | "all";
+/**
+ * What `Session.typeCredential` types from a password credential: its user name, its password or its current 2FA code
+ * (with a `codeSource` of "push" or "url" it waits for a fresh one, up to `codeTimeoutSeconds`).
+ */
+export type CredentialField = "username" | "password" | "otp";
 /**
- * Where a project secret may be used: "agent" (default): only the AI, as %NAME% in agent runs, plain-English steps and
- * scripts' step(); "shell": only as an environment variable in session shells and commands; "all": both.
+ * Where a password's 2FA codes come from: "totp" (an authenticator key, `totpSecret`), "push" (your system sends each
+ * code or sign-in link the site emails or texts: `credentials.pushCode`) or "url" (the platform asks your endpoint
+ * `codeUrl`, signed like a webhook). A password without one has no 2FA (`codeSource: null`).
  */
-export type SecretScope = "agent" | "shell" | "all";
-/** A project secret. Its value is never returned. */
-export interface Secret {
+export type CredentialCodeSource = "totp" | "push" | "url";
+interface CredentialBase {
+    /** Also its placeholder (`%NAME%`, `%NAME.password%`) and its shell variable (`$NAME`, `$NAME_PASSWORD`). */
     name: string;
     description: string | null;
-    /** Sites where the AI may type it (null = any site). */
-    origins: string[] | null;
     /** The AI may use it in bash commands; this also allows exporting it into shells. */
     shell: boolean;
-    scope: SecretScope;
-    /** "••••1a2b": the last 4 characters of values of 24 characters or more; null for shorter values and secrets with origins. */
-    preview: string | null;
+    scope: CredentialScope;
     createdAt: string;
     updatedAt: string;
     lastUsedAt: string | null;
 }
-export interface SecretCreateParams {
+/** A website password. Neither the password nor the 2FA key is ever returned. */
+export interface PasswordCredential extends CredentialBase {
+    type: "password";
+    /** The sites where the AI may type it (1 to 20). */
+    origins: string[];
+    username: string;
+    /** It has a 2FA key (`codeSource` is "totp"): `%NAME.otp%` and `boxline-otp NAME` give the current code. */
+    hasTotp: boolean;
+    /** Where its 2FA codes come from; null: no 2FA. */
+    codeSource: CredentialCodeSource | null;
+    /** The endpoint the platform asks for codes (`codeSource` "url"); null otherwise. Its signing secret is never shown again. */
+    codeUrl: string | null;
+    /** How long a wait for a pushed or asked code or link lasts (5 to 900 s, default 300). */
+    codeTimeoutSeconds: number;
+}
+/** A secret (an API key, a token). Its value is never returned. */
+export interface SecretCredential extends CredentialBase {
+    type: "secret";
+    /** Sites where the AI may type it (null = any site). */
+    origins: string[] | null;
+    /** "••••1a2b": the last 4 characters of values of 24 characters or more; null for shorter values and secrets with origins. */
+    preview: string | null;
+}
+/** A credential without its values: `switch (c.type)` tells the two apart. */
+export type Credential = PasswordCredential | SecretCredential;
+/**
+ * A credential as `credentials.create` and `credentials.update` return it: when `codeUrl` was set or changed it also
+ * has `codeUrlSecret` (`whsec_…`), the key that signs the platform's requests to `codeUrl`, shown this once (a new one
+ * any time with `credentials.rotateCodeUrlSecret`).
+ */
+export type CredentialWritten<C extends Credential = Credential> = C & {
+    codeUrlSecret?: string;
+};
+interface CredentialCreateBase {
     /**
      * An environment variable name in capitals, [A-Z_][A-Z0-9_]*, at most 64 characters; not one the platform or bash
-     * sets (PATH, HOME, PWD, IFS, …, or starting with BOXLINE_, SANDBOXD_ or BASH_). One per project.
+     * sets (PATH, HOME, PWD, IFS, …, or starting with BOXLINE_, SANDBOXD_ or BASH_). One per project, whatever the type.
      */
     name: string;
-    /** 1 to 8000 characters, no NUL. Sealed when stored and never returned. */
-    value: string;
     /** Up to 500 characters. */
     description?: string;
-    /** Sites where the AI may type it, e.g. ["https://example.com"] (recommended for passwords); 1 to 20. */
-    origins?: string[];
     /** Let the AI use it in bash commands (and so export it into shells). Default false. */
     shell?: boolean;
     /** Default "agent". */
-    scope?: SecretScope;
+    scope?: CredentialScope;
+}
+/** A website password; needs the plan's `loginDetails`. */
+export interface PasswordCredentialCreateParams extends CredentialCreateBase {
+    type: "password";
+    /** The sites where the AI may type it, `"https://shop.example.com"` or `"https://*.example.com"` (any subdomain); 1 to 20. */
+    origins: string[];
+    /** 1 to 320 characters. */
+    username: string;
+    /** 1 to 1024 characters. Sealed when stored and never returned. */
+    password: string;
+    /**
+     * Where its 2FA codes come from: "totp" (with `totpSecret`; `totpSecret` alone means "totp"), "push" (send each code
+     * or link with `credentials.pushCode`), "url" (with `codeUrl`), or left out / null for no 2FA.
+     */
+    codeSource?: CredentialCodeSource | null;
+    /**
+     * The site's 2FA setup key (base32, any case, spaces allowed) or an otpauth://totp/ link from its QR code (SHA1,
+     * SHA256 or SHA512, 6 to 8 digits, a 15 to 120 s period; defaults SHA-1, 6 digits, 30 s). Only with "totp".
+     */
+    totpSecret?: string;
+    /**
+     * `codeSource` "url" (required then): a public HTTPS endpoint (never a private or internal address) the platform
+     * asks with a signed POST every 5 s while a run waits for a code; the answer has `codeUrlSecret` once.
+     */
+    codeUrl?: string;
+    /** How long a "push" or "url" wait lasts: 5 to 900 seconds, default 300. */
+    codeTimeoutSeconds?: number;
 }
-/** Any of these; `description: null` clears it, `origins: null` allows any site. Changes apply to new uses. */
-export interface SecretUpdateParams {
-    value?: string;
+/** A secret: one value. */
+export interface SecretCredentialCreateParams extends CredentialCreateBase {
+    type: "secret";
+    /** 1 to 8000 characters, no NUL. Sealed when stored and never returned. */
+    value: string;
+    /** Sites where the AI may type it, e.g. ["https://example.com"] (1 to 20); without, any site. */
+    origins?: string[];
+}
+export type CredentialCreateParams = PasswordCredentialCreateParams | SecretCredentialCreateParams;
+/**
+ * Changes to a password; what is not sent is kept. A change of `origins` that adds a site, or of `scope`/`shell` that
+ * makes an AI-only password readable by shells, needs `password` again in the same call (and `totpSecret`, a new one or
+ * null, when it has 2FA); so does a change of `codeSource` (removing 2FA included) or `codeUrl`.
+ */
+export interface PasswordCredentialUpdateParams {
+    origins?: string[];
+    username?: string;
+    password?: string;
+    /** Where the codes come from; null removes 2FA. Needs `password` again. */
+    codeSource?: CredentialCodeSource | null;
+    /** A new 2FA setup key or otpauth://totp/ link; null removes 2FA. */
+    totpSecret?: string | null;
+    /** The endpoint asked for codes ("url"). Needs `password` again; the answer has a new `codeUrlSecret`. */
+    codeUrl?: string;
+    /** 5 to 900 seconds. */
+    codeTimeoutSeconds?: number;
+    /** null clears it. */
     description?: string | null;
-    origins?: string[] | null;
     shell?: boolean;
-    scope?: SecretScope;
+    scope?: CredentialScope;
+    value?: never;
 }
-/** One entry of the secrets audit log: a change, or a use (once per session, command, agent run, step session or script). Never values. */
-export interface SecretAuditEntry {
+/**
+ * Changes to a secret; what is not sent is kept. A change of `origins` that adds a site, or null, or of `scope`/`shell`
+ * that makes an AI-only secret readable by shells, needs `value` again.
+ */
+export interface SecretCredentialUpdateParams {
+    value?: string;
+    /** null allows any site. */
+    origins?: string[] | null;
+    description?: string | null;
+    shell?: boolean;
+    scope?: CredentialScope;
+    username?: never;
+    password?: never;
+    codeSource?: never;
+    codeUrl?: never;
+    codeTimeoutSeconds?: never;
+    totpSecret?: never;
+}
+/** What credentials.update takes: the fields of a password or of a secret (the type cannot change). Changes apply to new uses. */
+export type CredentialUpdateParams = PasswordCredentialUpdateParams | SecretCredentialUpdateParams;
+/**
+ * One entry of the credentials audit log: a change, or a use (once per session, command, agent run, step session,
+ * script, task run, type action or boxline-otp session). Never values.
+ */
+export interface CredentialAuditEntry {
     at: string;
-    action: "create" | "update" | "delete" | "use";
-    /** "login": a saved login's details (`name` is the context id). */
-    kind: "secret" | "login";
+    /** "code": a pushed 2FA code or sign-in link (`details.kind`), never its value. */
+    action: "create" | "update" | "delete" | "use" | "code";
+    type: CredentialType;
     name: string;
     /** Who changed it: "user:<email>", "key:<api key id>", or "support" (Boxline support acting as a user). */
     actor: string | null;
-    /** What used it. */
+    /** What used it: `id` is the session, or for `agent_run` the run and for `task_run` the task run. Null for changes. */
     usedBy: {
-        type: "session" | "exec" | "agent_run" | "step" | "script" | "task_run";
+        type: "session" | "exec" | "agent_run" | "step" | "script" | "task_run" | "action" | "otp";
         id: string;
     } | null;
     details: Record<string, unknown>;
 }
-export interface SecretAuditParams extends ListParams {
-    /** One secret (or a context id, for login details). */
+export interface CredentialAuditParams extends ListParams {
+    /** One credential. */
     name?: string;
 }
+/** What `credentials.pushCode` sends: a 2FA code (1 to 64 characters, no spaces) or a sign-in link on one of the credential's sites. */
+export type CredentialCodePush = {
+    code: string;
+    link?: never;
+} | {
+    link: string;
+    code?: never;
+};
+/** What `credentials.pushCode` returns: the code or link is kept for a wait in progress (used once, at most 10 minutes). */
+export interface CredentialCodeAccepted {
+    accepted: true;
+    kind: "code" | "link";
+    expiresAt: string;
+}
 /** An uploaded Chrome extension (Manifest V3). */
 export interface ExtensionInfo {
     id: string;
@@ -2145,3 +2307,4 @@ export interface ExtensionInfo {
     sha256: string;
     createdAt: string;
 }
+export {};