@boxline/sdk 1.2.0 → 2.0.0

package/dist/types.d.ts

@@ -1,7 +1,8 @@
 /**
  * The API's objects, as in docs/openapi.yaml (and docs/CONTRACT.md). Dates are ISO 8601 strings.
  */
-export type SessionStatus = "RUNNING" | "PAUSED" | "COMPLETED" | "ERROR";
+/** RUNNING; STOPPED (saved, no machine, free: resume it); DELETED (ended for good); ERROR (never started). */
+export type SessionStatus = "RUNNING" | "STOPPED" | "DELETED" | "ERROR";
 /** What happens when a CAPTCHA waits for a person: "ask" (default) pauses and hands over, "ignore" carries on, "solve" tries to solve it first. */
 export type CaptchaMode = "ask" | "ignore" | "solve";
 /** A CAPTCHA provider the platform recognises. */
@@ -42,7 +43,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" | "profiles" | "recording" | "realisticBrowser" | "residentialProxy" | "datacenterProxy" | "customProxy" | "captchaSolving" | "agentRuns" | "steps" | "extract" | "quickApis" | "crawl" | "extensions" | "webSearch" | "loginDetails"
+export type PlanFeature = "shell" | "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. */
@@ -255,14 +256,20 @@ export interface SessionData {
     keepAlive: boolean;
     /** Seconds. */
     timeout: number;
-    /** Seconds without activity after which the session ends (endReason "idle"); null: off. */
+    /** Seconds without activity after which the session stops (stopReason "idle"); null: off. */
     idleTimeout?: number | null;
     createdAt: string;
     startedAt: string | null;
-    endedAt: string | null;
     expiresAt: string;
-    endReason: SessionEndReason | null;
-    /** CDP WebSocket for Playwright/Puppeteer (null without a browser or once ended). Treat it like a password. */
+    /** When it stopped (null while it runs; a resume clears it). */
+    stoppedAt: string | null;
+    stopReason: SessionStopReason | null;
+    /** When a stopped session is deleted automatically: `stoppedAt` plus the plan's `retentionDays`, fixed when it stops. */
+    deletesAt: string | null;
+    /** When it was deleted, and by whom: `requested` (sessions.delete) or `retention` (its `deletesAt` passed). */
+    deletedAt: string | null;
+    deleteReason: SessionDeleteReason | null;
+    /** CDP WebSocket for Playwright/Puppeteer (null without a browser or unless the session is running). Treat it like a password. */
     connectUrl: string | null;
     /** The live view page. Treat it like a password. */
     liveUrl: string | null;
@@ -281,7 +288,7 @@ export interface SessionData {
     attention: CaptchaAttention | null;
     workspacePath: string;
     profileId: string | null;
-    /** Whether the session saves its sign-ins back to `profileId` when it ends. */
+    /** Whether the session saves its sign-ins back to `profileId` when it stops. */
     profilePersist?: boolean;
     userMetadata: Record<string, unknown>;
     moves: number;
@@ -292,8 +299,6 @@ export interface SessionData {
     error: string | null;
     recordSession: boolean;
     hasRecording: boolean;
-    /** When the recording, logs and agent-run steps were deleted under the plan's `retentionDays` (null until then). */
-    dataDeletedAt?: string | null;
     setup: string[];
     setupStatus: "none" | "running" | "done" | "failed";
     setupError: string | null;
@@ -315,11 +320,21 @@ export interface SessionData {
     };
 }
 /**
- * Why a session ended. "idle": its idleTimeout passed without activity; "disconnected": a browser-only session without
- * keepAlive whose last client left, with no agent run, script or step working in it; "agent_finished": its agent run's
- * own session, released when the run ended (or when a run's continue window passed unused).
+ * Why a session stopped. "requested": sessions.stop; "idle": its idleTimeout passed without activity; "no_clients": a
+ * browser-only session without keepAlive whose last client left, with no agent run, script or step working in it;
+ * "agent_run" / "task": the session an agent run (a task's run) started, stopped when the run ended (or when its continue
+ * window passed unused); "machine_lost": its machine failed and could not be replaced (its last checkpoint is what it saved);
+ * "suspended": an admin suspended the organization.
  */
-export type SessionEndReason = "released" | "timeout" | "idle" | "disconnected" | "agent_finished" | "api_restart" | "paused_expired" | "machine_lost" | "account_recovered" | (string & {});
+export type SessionStopReason = "requested" | "timeout" | "idle" | "no_clients" | "agent_run" | "task" | "api_restart" | "machine_lost" | "account_recovered"
+/** The organization was suspended: its running sessions stopped. */
+ | "suspended"
+/** The organization or the project reached its monthly spending limit. */
+ | "spend_limit"
+/** The organization had no credit left (only where the platform enforces credit). */
+ | "out_of_credit" | (string & {});
+/** Why a session was deleted: `requested` (sessions.delete) or `retention` (its `deletesAt` passed). */
+export type SessionDeleteReason = "requested" | "retention";
 /** "reject" (the default for new sessions): answer consent banners with "Reject all" or "Necessary only" (never accept), else hide them. */
 export type CookieBanners = "reject" | "off";
 export interface CreateSessionParams {
@@ -330,7 +345,7 @@ export interface CreateSessionParams {
     /** Seconds (default 300), up to the plan's maxTimeoutSeconds. */
     timeout?: number;
     /**
-     * Opt-in: the session ends (endReason "idle") after this many seconds without activity, 30 to `timeout`. Activity:
+     * Opt-in: the session stops (stopReason "idle") after this many seconds without activity, 30 to `timeout`. Activity:
      * CDP commands, live-view input, terminal keys, exec, files, actions and steps, scripts, agent steps and messages;
      * an agent run working in it (or one that can still be continued) counts the whole time. Protects keepAlive and
      * shell sessions whose client crashed.
@@ -401,7 +416,7 @@ export interface UpdateSessionParams {
     cookieBanners?: CookieBanners;
 }
 export interface SessionListParams {
-    /** One status or several, e.g. ["RUNNING", "PAUSED"]. */
+    /** One status or several, e.g. ["RUNNING", "STOPPED"]. */
     status?: SessionStatus | SessionStatus[];
     /** "browser" (no shell), "combined" (browser and shell) or "shell" (no browser). */
     kind?: "browser" | "combined" | "shell";
@@ -633,6 +648,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;
@@ -644,10 +669,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;
@@ -1268,7 +1301,7 @@ export interface AgentRunStarted {
  * its session ended another way (`error` names how); "output_invalid": the answer did not match the output schema;
  * "internal": an error on the platform's side. Other codes are those of the platform error that stopped it.
  */
-export type AgentRunErrorCode = "spend_limit" | "max_steps" | "max_cost" | "too_many_errors" | "no_progress" | "server_restarted" | "session_timeout" | "session_ended" | "output_invalid" | "internal" | "spend_limit" | "captcha_timeout" | "handover_timeout" | (string & {});
+export type AgentRunErrorCode = "spend_limit" | "max_steps" | "max_cost" | "too_many_errors" | "no_progress" | "server_restarted" | "session_timeout" | "session_ended" | "output_invalid" | "internal" | "spend_limit" | "out_of_credit" | "captcha_timeout" | "handover_timeout" | (string & {});
 /** The body of agent.continueRun. */
 export interface ContinueRunParams {
     /** 1–1000, or null for no step limit (default: the run's own). */
@@ -1293,7 +1326,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";
@@ -1311,9 +1345,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. */
@@ -1691,9 +1730,9 @@ export interface Pricing {
         gib: number;
         perHour: number;
     };
-    pausedSessions: {
-        freeHours: number;
-        perGbMonthAfter: number;
+    /** A stopped session is free: `perHour` is 0. */
+    stoppedSessions: {
+        perHour: number;
     };
     proxies: {
         residentialPerGb: number;
@@ -1718,7 +1757,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" | "credential.changed" | "webhook.changed" | "webhook.disabled" | "extension.uploaded" | "extension.deleted";
+export type WebhookEventType = "session.started" | "session.expiring" | "session.stopped" | "session.deleted" | "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. */
@@ -1827,7 +1866,7 @@ export interface WebhookEvent<T = Record<string, unknown>> {
 }
 /** Who made a change: "user:<email>" (a console login), "key:<api key id>", "support" (support acting as you) or "platform". */
 export type WebhookActor = string;
-/** session.started and session.ended: the session as sessions.get returns it, with every URL (and attention) null. */
+/** session.started, session.stopped and session.deleted: the session as sessions.get returns it, with every URL (and attention) null. */
 export type WebhookSessionData = Omit<SessionData, "setup" | "setupError"> & {
     userMetadataTruncated?: true;
 };
@@ -1981,8 +2020,12 @@ export interface WebhookSchedulePausedData {
     pausedAt: string;
 }
 export interface WebhookUsageLimitData {
-    kind: "model_spend" | "proxy_gb" | "captcha_solves" | "searches" | "concurrency";
-    /** The plan's limit: USD, GB, a count, or sessions at once. */
+    /**
+     * The plan's limits, or the organization's money: its monthly spending limit (`spend_limit`), the project's own
+     * (`project_spend_limit`), or its credit used up (`credit`).
+     */
+    kind: "model_spend" | "proxy_gb" | "captcha_solves" | "searches" | "concurrency" | "spend_limit" | "project_spend_limit" | "credit";
+    /** The limit: USD (model spend, spending limits; for `credit` the credit used this month), GB, a count, or sessions at once. */
     limit: number;
     used: number;
     /** "2026-09" (a UTC month), or "2026-09-30T14" (a UTC hour) for concurrency. */
@@ -1997,6 +2040,15 @@ export interface WebhookApiKeyData {
     name: string;
     by: WebhookActor;
 }
+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;
@@ -2033,7 +2085,8 @@ export interface WebhookExtensionData {
 export interface WebhookEventDataMap {
     "session.started": WebhookSessionData;
     "session.expiring": WebhookSessionExpiringData;
-    "session.ended": WebhookSessionData;
+    "session.stopped": WebhookSessionData;
+    "session.deleted": WebhookSessionData;
     "agent_run.started": WebhookAgentRunStartedData;
     "agent_run.waiting": WebhookAgentRunWaitingData;
     "agent_run.resumed": WebhookAgentRunResumedData;
@@ -2050,6 +2103,7 @@ export interface WebhookEventDataMap {
     "usage.limit_reached": WebhookUsageLimitData;
     "api_key.created": WebhookApiKeyData;
     "api_key.revoked": WebhookApiKeyData;
+    "credential.code_needed": WebhookCredentialCodeNeededData;
     "credential.changed": WebhookCredentialChangedData;
     "webhook.changed": WebhookChangedData;
     "webhook.disabled": WebhookDisabledData;
@@ -2073,8 +2127,17 @@ export type CredentialType = "password" | "secret";
  * 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. */
+/**
+ * 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 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 CredentialCodeSource = "totp" | "push" | "url";
 interface CredentialBase {
     /** Also its placeholder (`%NAME%`, `%NAME.password%`) and its shell variable (`$NAME`, `$NAME_PASSWORD`). */
     name: string;
@@ -2092,8 +2155,14 @@ export interface PasswordCredential extends CredentialBase {
     /** The sites where the AI may type it (1 to 20). */
     origins: string[];
     username: string;
-    /** It has a 2FA key: `%NAME.otp%` and `boxline-otp NAME` give the current code. */
+    /** 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 {
@@ -2105,6 +2174,14 @@ export interface SecretCredential extends CredentialBase {
 }
 /** 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
@@ -2127,11 +2204,23 @@ export interface PasswordCredentialCreateParams extends CredentialCreateBase {
     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).
+     * 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;
 }
 /** A secret: one value. */
 export interface SecretCredentialCreateParams extends CredentialCreateBase {
@@ -2145,14 +2234,20 @@ export type CredentialCreateParams = PasswordCredentialCreateParams | SecretCred
 /**
  * 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).
+ * 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;
     shell?: boolean;
@@ -2172,6 +2267,9 @@ export interface SecretCredentialUpdateParams {
     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. */
@@ -2182,7 +2280,8 @@ export type CredentialUpdateParams = PasswordCredentialUpdateParams | SecretCred
  */
 export interface CredentialAuditEntry {
     at: string;
-    action: "create" | "update" | "delete" | "use";
+    /** "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). */
@@ -2198,6 +2297,20 @@ 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;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** The SDK's version, sent to the API as `Boxline-SDK: node/<version>`. Keep it equal to package.json. */
-export declare const VERSION = "1.2.0";
+export declare const VERSION = "2.0.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 /** The SDK's version, sent to the API as `Boxline-SDK: node/<version>`. Keep it equal to package.json. */
-export const VERSION = "1.2.0";
+export const VERSION = "2.0.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxline/sdk",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Node and TypeScript SDK for Boxline: cloud browsers and shell sandboxes for AI agents, with retries, cursor pages and typed errors.",
   "keywords": [
     "boxline",