@scalebrowser/sdk 0.9.0 → 1.1.0

package/CHANGELOG.md

@@ -3,13 +3,53 @@
 The Node/TypeScript SDK for the Scalebrowser daemon.
 
 This file starts at 0.5.0, the oldest release still on npm when it was written
-(2026-09-09). What came before is in the repository's history. It was never
-published as release notes, and reconstructing it here would look like a record
-that had been kept all along.
+(2026-09-09). What came before was never published as release notes, and
+reconstructing it here would look like a record that had been kept all along.
 
 The daemon and the SDK version independently. An SDK release names the daemon
 version it was tested against wherever that matters.
 
+## 1.1.0 (2026-10-04)
+
+Three fields the daemon has sent since 0.20.0 now have types. All three are
+optional, so code written against 1.0.0 compiles unchanged.
+
+- `Profile.timezone_country`: the country the profile's clock places it in,
+  `null` for a zone the daemon has no country for. Read the country from here,
+  not from the language: Chrome sends the list of its interface language, so a
+  profile in Vienna sends `de-DE`.
+- `Account.plan_required`: the account has no active plan, and choosing one is
+  the only remedy. The daemon enrols the machine by itself on its next check
+  after that.
+- `Account.trial_available`: together with `plan_required`, the account still
+  has its free trial.
+
+## 1.0.0 (2026-09-27)
+
+The library works as in 0.9.0. What changes is the promise: from this release
+on, a breaking change to the client or its types arrives only as a new major
+version, with the reason written in this file.
+
+- The source is public at https://github.com/blackdiamond-labs/scalebrowser-node.
+  npm builds every release from a tagged commit there and publishes it with a
+  provenance attestation, so anyone can check which commit and which workflow
+  run produced the package.
+- The documentation comments you see in your editor no longer carry internal
+  planning references, and the video preset types are documented in English.
+
+## 0.9.0 (2026-09-20)
+
+- `checkProxy` answers the exit's operator (`asn`), its timezone (`timezone`)
+  and the kind of network it sits on (`exit_class`: `datacenter`,
+  `residential`, `mobile` or `unknown`).
+- `is_mobile` is derived from `exit_class` and has three states: `true`,
+  `false`, and `null` for "could not be classified". Before, it was `false` on
+  every answer, genuinely mobile exits included.
+- A proxy row carries `last_timezone`, the zone a profile on
+  `geo_mode: "follow_exit"` adopts at its next start.
+- The exit-address view names the IPv6 `/64` in use as `current_v6` when the
+  daemon measures IPv6; `current` holds the IPv4 address with its `v4:` prefix.
+
 ## 0.8.1 (2026-09-16)
 
 The published `package.json` no longer lists a `smoke` script. It pointed at a

package/README.md

@@ -15,7 +15,10 @@ npm install @scalebrowser/sdk
 ```
 
 Ships dual ESM + CJS with full type declarations, and needs Node ≥ 18. The SDK
-is MIT-licensed; the daemon it talks to is a separate, licensed product.
+is MIT-licensed, and its source is public at
+[blackdiamond-labs/scalebrowser-node](https://github.com/blackdiamond-labs/scalebrowser-node):
+npm builds every release there and publishes it with a provenance attestation.
+The daemon it talks to is a separate, licensed product.
 
 ## Quickstart
 

package/dist/index.cjs

@@ -17,22 +17,22 @@ var ErrorCode = {
   /** Retired: the removed Methode-D (VM) tier produced this. Reserved (never reused)
    * to match the server's append-only code contract; never returned now. */
   VmProvisionFailed: 4007,
-  /** The subscription's abo-wide concurrent-browser allowance is used up (DEC-012).
+  /** The subscription's abo-wide concurrent-browser allowance is used up.
    * Distinct from Capacity (4003 = this machine is full, wait): the caller's move
    * is to stop a running browser anywhere or upgrade the plan. */
   ConcurrencyLimit: 4008,
   Unauthorized: 4010,
-  /** No account is connected to this machine, so nothing may run (DEC-014).
+  /** No account is connected to this machine, so nothing may run.
    * Distinct from Unauthorized (4010 = the daemon's own bearer token is wrong, so
    * re-read the token): 4011 means the machine needs to be signed in, and no token
    * a client holds can substitute for that. Connect it in the desktop app. */
   NotSignedIn: 4011,
-  /** This ONE profile is open on another machine of the same account (DEC-015).
+  /** This ONE profile is open on another machine of the same account.
    * Distinct from ConcurrencyLimit (4008 = the plan is full, buy more or free any
    * browser): the caller's move here costs nothing. Close it on that machine, or
    * take it over from the app running there. */
   ProfileInUse: 4012,
-  /** The exit address this start drew belongs to another profile (DEC-017).
+  /** The exit address this start drew belongs to another profile.
    * Distinct from ProxyGeo (4002 = wrong country or wrong kind of exit, so change
    * the proxy): here the proxy is fine and the address is simply spoken for. Wait
    * for a term to run out, let the daemon draw again, or turn exclusivity off for
@@ -1217,7 +1217,7 @@ var CdpSession = class _CdpSession {
     });
     return executionContextId;
   }
-  // ── Humanized trusted input (routes through the daemon, G8) ────────────────
+  // ── Humanized trusted input (routes through the daemon) ────────────────────
   humanizeMove(x, y, opts = {}) {
     return this.#input({ action: "move", x, y, width: opts.width });
   }
@@ -1595,7 +1595,7 @@ var ScalebrowserClient = class extends ClientCore {
       signal
     });
   }
-  // ── Exit-address exclusivity (DEC-017) ──────────────────────────────────────
+  // ── Exit-address exclusivity ────────────────────────────────────────────────
   /** Which exit addresses this profile owns, and how far the rule reaches.
    *
    * `scope` is `'machine'` while this computer has no account key. That is the
@@ -1607,14 +1607,14 @@ var ScalebrowserClient = class extends ClientCore {
       signal
     });
   }
-  // ── Session bundles (AC-ST-002/003) ─────────────────────────────────────────
+  // ── Session bundles ─────────────────────────────────────────────────────────
   exportSession(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/session/export`, body);
   }
   importSession(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/session/import`, body);
   }
-  // ── Trusted input (G8, AC-API-003) ─────────────────────────────────────────
+  // ── Trusted input ──────────────────────────────────────────────────────────
   sendInput(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/input`, body);
   }
@@ -1738,7 +1738,7 @@ var PROXY_KINDS = ["http", "socks5", "gateway"];
 var ROTATIONS = ["sticky", "rotating"];
 
 // src/index.ts
-var VERSION = "0.9.0";
+var VERSION = "1.1.0";
 
 exports.ApiError = ApiError;
 exports.CdpError = CdpError;

package/dist/index.d.cts

@@ -423,19 +423,19 @@ interface ShareStatus extends ShareLinkLocal {
  * UNION of the Rust route shapes, never one serde struct (create/delete answer
  * the bare `Profile`, list/get the flattened `ProfileView`).
  */
-/** `RuntimeState` (AC-PR-004). */
+/** `RuntimeState`. */
 type RuntimeState = 'stopped' | 'starting' | 'running' | 'crashed';
 declare const RUNTIME_STATES: readonly RuntimeState[];
-/** `GeoMode` (AC-PX-002). Default `follow_exit`. */
+/** `GeoMode`. Default `follow_exit`. */
 type GeoMode = 'strict_expected' | 'follow_exit' | 'off';
 declare const GEO_MODES: readonly GeoMode[];
-/** `ProxyKind` (AC-PX-001). */
+/** `ProxyKind`. */
 type ProxyKind = 'http' | 'socks5' | 'gateway';
 declare const PROXY_KINDS: readonly ProxyKind[];
-/** `Rotation` (AC-PX-002). */
+/** `Rotation`. */
 type Rotation = 'sticky' | 'rotating';
 declare const ROTATIONS: readonly Rotation[];
-/** `SessionKind` (AC-ST-002). */
+/** `SessionKind`. */
 type SessionKind = 'cookies' | 'local_storage' | 'indexed_db' | 'service_worker';
 type OsFamily = 'windows' | 'macos' | 'linux';
 /** How protected a profile is right now, decided by the daemon WITHOUT starting a
@@ -467,7 +467,7 @@ interface Profile {
     expected_country: string | null;
     /**
      * Whether this profile claims its exit address for itself, so no other profile of
-     * the account starts on it (DEC-017). On for a new profile. Turn it off for a
+     * the account starts on it. On for a new profile. Turn it off for a
      * provider that hands out ONE address on purpose, a residential line you pay for
      * or a whitelisted office address, where the rule would refuse every start after
      * the first.
@@ -486,6 +486,14 @@ interface Profile {
      * Additive; a daemon predating the credential vault simply omits it.
      */
     platforms?: string[];
+    /**
+     * The country the persona's clock places it in (`persona.timezone`), `null` for
+     * a zone outside the daemon's cohort table. Never read the country out of the
+     * language: Chrome sends the list of its UI language, so a profile in Vienna
+     * speaks `de-DE` and one in Stockholm `en-US`. Additive; present on list/get
+     * (`ProfileView`), absent where `protection` is.
+     */
+    timezone_country?: string | null;
 }
 interface Group {
     id: string;
@@ -534,7 +542,7 @@ interface Preset {
     config: PresetConfig;
     created_at: number;
 }
-/** Was hinter der Seite liegt: ein Verlauf, eine Farbe, ein Bild, oder nichts. */
+/** What lies behind the page: a gradient, a colour, an image, or nothing. */
 type VideoBackground = {
     kind: 'gradient';
     colors: string[];
@@ -547,7 +555,7 @@ type VideoBackground = {
 } | {
     kind: 'none';
 };
-/** Intro und Outro. `hold_result` haelt das letzte Bild statt einer Karte. */
+/** Intro and outro. `hold_result` holds the last frame instead of a card. */
 type VideoCard = {
     style: 'title_card';
     seconds: number;
@@ -555,7 +563,7 @@ type VideoCard = {
     style: 'hold_result';
     seconds: number;
 };
-/** Wohin das fertige Video geht. */
+/** Where the finished video goes. */
 type VideoDestination = {
     kind: 'local';
 } | {
@@ -564,7 +572,7 @@ type VideoDestination = {
     download: boolean;
     passcode: boolean;
 };
-/** Eine Zusatz-Ausgabe mit eigenen Massen. Objekte, nie blosse Strings. */
+/** An additional output with its own dimensions. Objects, never bare strings. */
 interface ExtraOutput {
     preset: ExportPresetName;
     width?: number | null;
@@ -573,16 +581,16 @@ interface ExtraOutput {
     colors?: number | null;
     max_bytes?: number | null;
 }
-/** Hintergrundmusik, per Medien-Id, mit dem Pegel. */
+/** Background music, by media id, with its level. */
 interface MusicBed {
     media_id: string;
     gain_db: number;
 }
 /**
- * Das Rezept eines Videos: alles ueber die FORM, nichts ueber den Inhalt.
+ * The recipe of a video: everything about the FORM, nothing about the content.
  *
- * Schritte, Laenge, Titel und Sprechtext kommen aus dem Auftrag, nie von hier
- * (AC-CTL-001); das einzige freie Textfeld ist `ai_label.text`.
+ * Steps, length, title and narration come from the request, never from here;
+ * the only free text field is `ai_label.text`.
  */
 interface VideoPresetConfig {
     output: {
@@ -602,7 +610,7 @@ interface VideoPresetConfig {
         scale: number;
         style: 'arrow_dark' | 'arrow_light' | 'dot' | 'touch';
         click: 'ripple' | 'ring' | 'none';
-        /** `null` haelt den Zeiger fuer immer sichtbar. */
+        /** `null` keeps the pointer visible forever. */
         hide_after_ms: number | null;
         loop: boolean;
     };
@@ -614,7 +622,7 @@ interface VideoPresetConfig {
         zoom_scope: 'canvas' | 'card';
     };
     audio: {
-        /** `"<anbieter>:<stimme>"` oder `null` fuer ein stummes Video. */
+        /** `"<provider>:<voice>"`, or `null` for a silent video. */
         voice: string | null;
         language: string;
         subtitles: 'burned' | 'file' | 'off';
@@ -866,7 +874,7 @@ interface SessionImportBody {
     bundle: string;
 }
 /**
- * Trusted-input payload (`POST /v1/profiles/:id/input`, G8, AC-API-003). Only
+ * Trusted-input payload (`POST /v1/profiles/:id/input`). Only
  * `action` and `humanize` are fixed by the API contract; the per-action
  * coordinate fields below are the SDK's assumption about the daemon's input
  * layer.
@@ -1218,7 +1226,7 @@ type LifecycleEvent = {
  * notices this connection fell behind. `dropped` counts what it skipped.
  */
 /**
- * The exit-address guard's verdict for one running profile (DEC-017).
+ * The exit-address guard's verdict for one running profile.
  *
  * The whole state, like every other live row here: a display rebuilt from
  * parts is what makes it confidently wrong, and the one frame that matters
@@ -1257,7 +1265,7 @@ type StreamedEvent = LifecycleEvent & {
 };
 
 /**
- * Live lifecycle event stream (`GET /v1/events`, AC-API-003).
+ * Live lifecycle event stream (`GET /v1/events`).
  *
  * Read as `text/event-stream` over `fetch` (so the Bearer header is attached, which
  * the browser `EventSource` cannot do that) and reconnect with backoff. A
@@ -1417,7 +1425,7 @@ interface Account {
      *  machine connected to an account"; `signed_in` does. */
     licensed: boolean;
     /** Whether an account is connected to this machine. One without an account
-     *  starts no browser (DEC-014). */
+     *  starts no browser. */
     signed_in: boolean;
     plan?: string;
     status?: string;
@@ -1434,6 +1442,14 @@ interface Account {
     /** Unix seconds; when the cached entitlement stops being valid. */
     expires_at?: number;
     permits_launch: boolean;
+    /** The control plane refused this machine because the account has no active
+     *  plan. Choosing one on the pricing page is the only remedy; the daemon
+     *  enrols the machine by itself on its next check after that. Absent when
+     *  false. */
+    plan_required?: boolean;
+    /** With `plan_required`: the control plane said this account still has its
+     *  free trial. Absent when false. */
+    trial_available?: boolean;
 }
 interface HealthStatus {
     status: string;
@@ -1482,7 +1498,7 @@ interface ExitRuleStatus {
 interface ScalebrowserClientOptions {
     /** Daemon base URL. Default `http://127.0.0.1:8787`. */
     baseUrl?: string;
-    /** Bearer token (AC-API-002). */
+    /** Bearer token. */
     token?: string | null;
     /** Injectable `fetch` (for testing / custom agents). Default `globalThis.fetch`. */
     fetch?: FetchLike;
@@ -1638,7 +1654,7 @@ interface CreateProfileBody {
  */
 type UpdateProfileBody = Omit<Partial<CreateProfileBody>, "seed" | "persona_country"> & {
     /**
-     * Turn the exit-address rule off for this profile (DEC-017). Deliberately not
+     * Turn the exit-address rule off for this profile. Deliberately not
      * part of `CreateProfileBody`: a new profile always claims its address, and
      * switching that off is a later, deliberate act for a setup that needs it.
      */
@@ -1652,7 +1668,7 @@ interface StartProfileResult {
     cdp_ws: string;
     /** DevTools TCP port, parsed from `cdp_ws` (`null` if the URL has none). */
     debug_port: number | null;
-    /** Effective headless state of this launch (AC-OR-005). */
+    /** Effective headless state of this launch. */
     headless: boolean;
     pid: number | null;
     started_at: number;
@@ -1704,7 +1720,7 @@ type UpdateProxyBody = Partial<CreateProxyBody>;
  * Result of `POST /v1/proxies/:id/check` (health + geo).
  *
  * CONTRACT ASSUMPTION: the daemon returns the freshly-checked exit identity plus
- * the JA4↔JA4T coherence verdict (AC-FP-011). Fields beyond the persisted `Proxy`
+ * the JA4↔JA4T coherence verdict. Fields beyond the persisted `Proxy`
  * columns (`ja4`, `ja4t`, `ja4t_mismatch`, `warnings`) are optional; if the
  * daemon only echoes the updated `Proxy`, the JA4 verdict is simply absent.
  */
@@ -2425,7 +2441,7 @@ declare class VideosApi extends ClientCore {
 }
 
 /**
- * Direct-CDP driver (DEC-006, AC-FP-005): a minimal, nodriver-style Chrome
+ * Direct-CDP driver: a minimal, nodriver-style Chrome
  * DevTools Protocol client over a raw websocket. This is the recommended SDK
  * driver plane: it is NOT the Playwright/Puppeteer control plane (which is a
  * detection vector independent of patch quality). We never call `Runtime.enable`
@@ -2565,7 +2581,7 @@ interface CdpConnectOptions {
 declare function openCdpSession(url: string, options?: CdpConnectOptions): Promise<CdpSession>;
 
 /**
- * Dashboard/SDK metrics (AC-UI-002, M3). The daemon serves `GET /v1/metrics`
+ * Dashboard/SDK metrics. The daemon serves `GET /v1/metrics`
  * from a background sampler; each null-able figure is disambiguated by
  * {@link Metrics.availability} (`measured` vs `unsupported` vs `unavailable`).
  * Against an old daemon without the endpoint (404) the client falls back to
@@ -2827,22 +2843,22 @@ declare const ErrorCode: {
     /** Retired: the removed Methode-D (VM) tier produced this. Reserved (never reused)
      * to match the server's append-only code contract; never returned now. */
     readonly VmProvisionFailed: 4007;
-    /** The subscription's abo-wide concurrent-browser allowance is used up (DEC-012).
+    /** The subscription's abo-wide concurrent-browser allowance is used up.
      * Distinct from Capacity (4003 = this machine is full, wait): the caller's move
      * is to stop a running browser anywhere or upgrade the plan. */
     readonly ConcurrencyLimit: 4008;
     readonly Unauthorized: 4010;
-    /** No account is connected to this machine, so nothing may run (DEC-014).
+    /** No account is connected to this machine, so nothing may run.
      * Distinct from Unauthorized (4010 = the daemon's own bearer token is wrong, so
      * re-read the token): 4011 means the machine needs to be signed in, and no token
      * a client holds can substitute for that. Connect it in the desktop app. */
     readonly NotSignedIn: 4011;
-    /** This ONE profile is open on another machine of the same account (DEC-015).
+    /** This ONE profile is open on another machine of the same account.
      * Distinct from ConcurrencyLimit (4008 = the plan is full, buy more or free any
      * browser): the caller's move here costs nothing. Close it on that machine, or
      * take it over from the app running there. */
     readonly ProfileInUse: 4012;
-    /** The exit address this start drew belongs to another profile (DEC-017).
+    /** The exit address this start drew belongs to another profile.
      * Distinct from ProxyGeo (4002 = wrong country or wrong kind of exit, so change
      * the proxy): here the proxy is fine and the address is simply spoken for. Wait
      * for a term to run out, let the daemon draw again, or turn exclusivity off for
@@ -2891,7 +2907,7 @@ declare function errorMessage(err: unknown): string;
 /**
  * `@scalebrowser/sdk`: the official Node/TypeScript SDK for the Scalebrowser
  * daemon. A typed REST client plus a direct-CDP driver plane (nodriver-style,
- * NOT Playwright, DEC-006).
+ * NOT Playwright).
  *
  * ```ts
  * import { ScalebrowserClient } from '@scalebrowser/sdk';
@@ -2905,6 +2921,6 @@ declare function errorMessage(err: unknown): string;
  * ```
  */
 
-declare const VERSION = "0.9.0";
+declare const VERSION = "1.1.0";
 
 export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type BlockedExport, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type Connection, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitRuleStatus, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, type HealthStatus, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type ListTasksParams, type ListVideosParams, type MediaAsset, type MediaKind, type MusicBed, type NarrationLine, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PatchTaskBody, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type PreviewHidden, type PreviewMoment, type Profile, type ProfileActivity, type ProfileMemory, type ProfileTask, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, type ProxyRow, type ProxyUsage, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type Recording, type RecordingKind, type RecordingState, type RemoteStatus, type RenderProgress, type RenderRequestBody, type RenderStage, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type ShareLinkLocal, type ShareStatus, type ShotFocus, type ShotIntent, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TaskState, type TimestampState, type TranscriptWord, type TrustedInputBody, type TtsProviderView, type TtsVerifyResult, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, type Video, type VideoAccessGrant, type VideoAssetName, type VideoAssets, type VideoBackground, type VideoCard, type VideoDestination, type VideoFlags, type VideoPreset, type VideoPresetClip, type VideoPresetClipBody, type VideoPresetClipProgress, type VideoPresetClipStarted, type VideoPresetConfig, type VideoPresetPreview, type VideoPresetPreviewBody, type VideoState, type VideosPage, type VideosStorage, type WriteMemoryBody, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };

package/dist/index.d.ts

@@ -423,19 +423,19 @@ interface ShareStatus extends ShareLinkLocal {
  * UNION of the Rust route shapes, never one serde struct (create/delete answer
  * the bare `Profile`, list/get the flattened `ProfileView`).
  */
-/** `RuntimeState` (AC-PR-004). */
+/** `RuntimeState`. */
 type RuntimeState = 'stopped' | 'starting' | 'running' | 'crashed';
 declare const RUNTIME_STATES: readonly RuntimeState[];
-/** `GeoMode` (AC-PX-002). Default `follow_exit`. */
+/** `GeoMode`. Default `follow_exit`. */
 type GeoMode = 'strict_expected' | 'follow_exit' | 'off';
 declare const GEO_MODES: readonly GeoMode[];
-/** `ProxyKind` (AC-PX-001). */
+/** `ProxyKind`. */
 type ProxyKind = 'http' | 'socks5' | 'gateway';
 declare const PROXY_KINDS: readonly ProxyKind[];
-/** `Rotation` (AC-PX-002). */
+/** `Rotation`. */
 type Rotation = 'sticky' | 'rotating';
 declare const ROTATIONS: readonly Rotation[];
-/** `SessionKind` (AC-ST-002). */
+/** `SessionKind`. */
 type SessionKind = 'cookies' | 'local_storage' | 'indexed_db' | 'service_worker';
 type OsFamily = 'windows' | 'macos' | 'linux';
 /** How protected a profile is right now, decided by the daemon WITHOUT starting a
@@ -467,7 +467,7 @@ interface Profile {
     expected_country: string | null;
     /**
      * Whether this profile claims its exit address for itself, so no other profile of
-     * the account starts on it (DEC-017). On for a new profile. Turn it off for a
+     * the account starts on it. On for a new profile. Turn it off for a
      * provider that hands out ONE address on purpose, a residential line you pay for
      * or a whitelisted office address, where the rule would refuse every start after
      * the first.
@@ -486,6 +486,14 @@ interface Profile {
      * Additive; a daemon predating the credential vault simply omits it.
      */
     platforms?: string[];
+    /**
+     * The country the persona's clock places it in (`persona.timezone`), `null` for
+     * a zone outside the daemon's cohort table. Never read the country out of the
+     * language: Chrome sends the list of its UI language, so a profile in Vienna
+     * speaks `de-DE` and one in Stockholm `en-US`. Additive; present on list/get
+     * (`ProfileView`), absent where `protection` is.
+     */
+    timezone_country?: string | null;
 }
 interface Group {
     id: string;
@@ -534,7 +542,7 @@ interface Preset {
     config: PresetConfig;
     created_at: number;
 }
-/** Was hinter der Seite liegt: ein Verlauf, eine Farbe, ein Bild, oder nichts. */
+/** What lies behind the page: a gradient, a colour, an image, or nothing. */
 type VideoBackground = {
     kind: 'gradient';
     colors: string[];
@@ -547,7 +555,7 @@ type VideoBackground = {
 } | {
     kind: 'none';
 };
-/** Intro und Outro. `hold_result` haelt das letzte Bild statt einer Karte. */
+/** Intro and outro. `hold_result` holds the last frame instead of a card. */
 type VideoCard = {
     style: 'title_card';
     seconds: number;
@@ -555,7 +563,7 @@ type VideoCard = {
     style: 'hold_result';
     seconds: number;
 };
-/** Wohin das fertige Video geht. */
+/** Where the finished video goes. */
 type VideoDestination = {
     kind: 'local';
 } | {
@@ -564,7 +572,7 @@ type VideoDestination = {
     download: boolean;
     passcode: boolean;
 };
-/** Eine Zusatz-Ausgabe mit eigenen Massen. Objekte, nie blosse Strings. */
+/** An additional output with its own dimensions. Objects, never bare strings. */
 interface ExtraOutput {
     preset: ExportPresetName;
     width?: number | null;
@@ -573,16 +581,16 @@ interface ExtraOutput {
     colors?: number | null;
     max_bytes?: number | null;
 }
-/** Hintergrundmusik, per Medien-Id, mit dem Pegel. */
+/** Background music, by media id, with its level. */
 interface MusicBed {
     media_id: string;
     gain_db: number;
 }
 /**
- * Das Rezept eines Videos: alles ueber die FORM, nichts ueber den Inhalt.
+ * The recipe of a video: everything about the FORM, nothing about the content.
  *
- * Schritte, Laenge, Titel und Sprechtext kommen aus dem Auftrag, nie von hier
- * (AC-CTL-001); das einzige freie Textfeld ist `ai_label.text`.
+ * Steps, length, title and narration come from the request, never from here;
+ * the only free text field is `ai_label.text`.
  */
 interface VideoPresetConfig {
     output: {
@@ -602,7 +610,7 @@ interface VideoPresetConfig {
         scale: number;
         style: 'arrow_dark' | 'arrow_light' | 'dot' | 'touch';
         click: 'ripple' | 'ring' | 'none';
-        /** `null` haelt den Zeiger fuer immer sichtbar. */
+        /** `null` keeps the pointer visible forever. */
         hide_after_ms: number | null;
         loop: boolean;
     };
@@ -614,7 +622,7 @@ interface VideoPresetConfig {
         zoom_scope: 'canvas' | 'card';
     };
     audio: {
-        /** `"<anbieter>:<stimme>"` oder `null` fuer ein stummes Video. */
+        /** `"<provider>:<voice>"`, or `null` for a silent video. */
         voice: string | null;
         language: string;
         subtitles: 'burned' | 'file' | 'off';
@@ -866,7 +874,7 @@ interface SessionImportBody {
     bundle: string;
 }
 /**
- * Trusted-input payload (`POST /v1/profiles/:id/input`, G8, AC-API-003). Only
+ * Trusted-input payload (`POST /v1/profiles/:id/input`). Only
  * `action` and `humanize` are fixed by the API contract; the per-action
  * coordinate fields below are the SDK's assumption about the daemon's input
  * layer.
@@ -1218,7 +1226,7 @@ type LifecycleEvent = {
  * notices this connection fell behind. `dropped` counts what it skipped.
  */
 /**
- * The exit-address guard's verdict for one running profile (DEC-017).
+ * The exit-address guard's verdict for one running profile.
  *
  * The whole state, like every other live row here: a display rebuilt from
  * parts is what makes it confidently wrong, and the one frame that matters
@@ -1257,7 +1265,7 @@ type StreamedEvent = LifecycleEvent & {
 };
 
 /**
- * Live lifecycle event stream (`GET /v1/events`, AC-API-003).
+ * Live lifecycle event stream (`GET /v1/events`).
  *
  * Read as `text/event-stream` over `fetch` (so the Bearer header is attached, which
  * the browser `EventSource` cannot do that) and reconnect with backoff. A
@@ -1417,7 +1425,7 @@ interface Account {
      *  machine connected to an account"; `signed_in` does. */
     licensed: boolean;
     /** Whether an account is connected to this machine. One without an account
-     *  starts no browser (DEC-014). */
+     *  starts no browser. */
     signed_in: boolean;
     plan?: string;
     status?: string;
@@ -1434,6 +1442,14 @@ interface Account {
     /** Unix seconds; when the cached entitlement stops being valid. */
     expires_at?: number;
     permits_launch: boolean;
+    /** The control plane refused this machine because the account has no active
+     *  plan. Choosing one on the pricing page is the only remedy; the daemon
+     *  enrols the machine by itself on its next check after that. Absent when
+     *  false. */
+    plan_required?: boolean;
+    /** With `plan_required`: the control plane said this account still has its
+     *  free trial. Absent when false. */
+    trial_available?: boolean;
 }
 interface HealthStatus {
     status: string;
@@ -1482,7 +1498,7 @@ interface ExitRuleStatus {
 interface ScalebrowserClientOptions {
     /** Daemon base URL. Default `http://127.0.0.1:8787`. */
     baseUrl?: string;
-    /** Bearer token (AC-API-002). */
+    /** Bearer token. */
     token?: string | null;
     /** Injectable `fetch` (for testing / custom agents). Default `globalThis.fetch`. */
     fetch?: FetchLike;
@@ -1638,7 +1654,7 @@ interface CreateProfileBody {
  */
 type UpdateProfileBody = Omit<Partial<CreateProfileBody>, "seed" | "persona_country"> & {
     /**
-     * Turn the exit-address rule off for this profile (DEC-017). Deliberately not
+     * Turn the exit-address rule off for this profile. Deliberately not
      * part of `CreateProfileBody`: a new profile always claims its address, and
      * switching that off is a later, deliberate act for a setup that needs it.
      */
@@ -1652,7 +1668,7 @@ interface StartProfileResult {
     cdp_ws: string;
     /** DevTools TCP port, parsed from `cdp_ws` (`null` if the URL has none). */
     debug_port: number | null;
-    /** Effective headless state of this launch (AC-OR-005). */
+    /** Effective headless state of this launch. */
     headless: boolean;
     pid: number | null;
     started_at: number;
@@ -1704,7 +1720,7 @@ type UpdateProxyBody = Partial<CreateProxyBody>;
  * Result of `POST /v1/proxies/:id/check` (health + geo).
  *
  * CONTRACT ASSUMPTION: the daemon returns the freshly-checked exit identity plus
- * the JA4↔JA4T coherence verdict (AC-FP-011). Fields beyond the persisted `Proxy`
+ * the JA4↔JA4T coherence verdict. Fields beyond the persisted `Proxy`
  * columns (`ja4`, `ja4t`, `ja4t_mismatch`, `warnings`) are optional; if the
  * daemon only echoes the updated `Proxy`, the JA4 verdict is simply absent.
  */
@@ -2425,7 +2441,7 @@ declare class VideosApi extends ClientCore {
 }
 
 /**
- * Direct-CDP driver (DEC-006, AC-FP-005): a minimal, nodriver-style Chrome
+ * Direct-CDP driver: a minimal, nodriver-style Chrome
  * DevTools Protocol client over a raw websocket. This is the recommended SDK
  * driver plane: it is NOT the Playwright/Puppeteer control plane (which is a
  * detection vector independent of patch quality). We never call `Runtime.enable`
@@ -2565,7 +2581,7 @@ interface CdpConnectOptions {
 declare function openCdpSession(url: string, options?: CdpConnectOptions): Promise<CdpSession>;
 
 /**
- * Dashboard/SDK metrics (AC-UI-002, M3). The daemon serves `GET /v1/metrics`
+ * Dashboard/SDK metrics. The daemon serves `GET /v1/metrics`
  * from a background sampler; each null-able figure is disambiguated by
  * {@link Metrics.availability} (`measured` vs `unsupported` vs `unavailable`).
  * Against an old daemon without the endpoint (404) the client falls back to
@@ -2827,22 +2843,22 @@ declare const ErrorCode: {
     /** Retired: the removed Methode-D (VM) tier produced this. Reserved (never reused)
      * to match the server's append-only code contract; never returned now. */
     readonly VmProvisionFailed: 4007;
-    /** The subscription's abo-wide concurrent-browser allowance is used up (DEC-012).
+    /** The subscription's abo-wide concurrent-browser allowance is used up.
      * Distinct from Capacity (4003 = this machine is full, wait): the caller's move
      * is to stop a running browser anywhere or upgrade the plan. */
     readonly ConcurrencyLimit: 4008;
     readonly Unauthorized: 4010;
-    /** No account is connected to this machine, so nothing may run (DEC-014).
+    /** No account is connected to this machine, so nothing may run.
      * Distinct from Unauthorized (4010 = the daemon's own bearer token is wrong, so
      * re-read the token): 4011 means the machine needs to be signed in, and no token
      * a client holds can substitute for that. Connect it in the desktop app. */
     readonly NotSignedIn: 4011;
-    /** This ONE profile is open on another machine of the same account (DEC-015).
+    /** This ONE profile is open on another machine of the same account.
      * Distinct from ConcurrencyLimit (4008 = the plan is full, buy more or free any
      * browser): the caller's move here costs nothing. Close it on that machine, or
      * take it over from the app running there. */
     readonly ProfileInUse: 4012;
-    /** The exit address this start drew belongs to another profile (DEC-017).
+    /** The exit address this start drew belongs to another profile.
      * Distinct from ProxyGeo (4002 = wrong country or wrong kind of exit, so change
      * the proxy): here the proxy is fine and the address is simply spoken for. Wait
      * for a term to run out, let the daemon draw again, or turn exclusivity off for
@@ -2891,7 +2907,7 @@ declare function errorMessage(err: unknown): string;
 /**
  * `@scalebrowser/sdk`: the official Node/TypeScript SDK for the Scalebrowser
  * daemon. A typed REST client plus a direct-CDP driver plane (nodriver-style,
- * NOT Playwright, DEC-006).
+ * NOT Playwright).
  *
  * ```ts
  * import { ScalebrowserClient } from '@scalebrowser/sdk';
@@ -2905,6 +2921,6 @@ declare function errorMessage(err: unknown): string;
  * ```
  */
 
-declare const VERSION = "0.9.0";
+declare const VERSION = "1.1.0";
 
 export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type BlockedExport, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type Connection, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitRuleStatus, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, type HealthStatus, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type ListTasksParams, type ListVideosParams, type MediaAsset, type MediaKind, type MusicBed, type NarrationLine, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PatchTaskBody, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type PreviewHidden, type PreviewMoment, type Profile, type ProfileActivity, type ProfileMemory, type ProfileTask, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, type ProxyRow, type ProxyUsage, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type Recording, type RecordingKind, type RecordingState, type RemoteStatus, type RenderProgress, type RenderRequestBody, type RenderStage, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type ShareLinkLocal, type ShareStatus, type ShotFocus, type ShotIntent, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TaskState, type TimestampState, type TranscriptWord, type TrustedInputBody, type TtsProviderView, type TtsVerifyResult, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, type Video, type VideoAccessGrant, type VideoAssetName, type VideoAssets, type VideoBackground, type VideoCard, type VideoDestination, type VideoFlags, type VideoPreset, type VideoPresetClip, type VideoPresetClipBody, type VideoPresetClipProgress, type VideoPresetClipStarted, type VideoPresetConfig, type VideoPresetPreview, type VideoPresetPreviewBody, type VideoState, type VideosPage, type VideosStorage, type WriteMemoryBody, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };

package/dist/index.js

@@ -11,22 +11,22 @@ var ErrorCode = {
   /** Retired: the removed Methode-D (VM) tier produced this. Reserved (never reused)
    * to match the server's append-only code contract; never returned now. */
   VmProvisionFailed: 4007,
-  /** The subscription's abo-wide concurrent-browser allowance is used up (DEC-012).
+  /** The subscription's abo-wide concurrent-browser allowance is used up.
    * Distinct from Capacity (4003 = this machine is full, wait): the caller's move
    * is to stop a running browser anywhere or upgrade the plan. */
   ConcurrencyLimit: 4008,
   Unauthorized: 4010,
-  /** No account is connected to this machine, so nothing may run (DEC-014).
+  /** No account is connected to this machine, so nothing may run.
    * Distinct from Unauthorized (4010 = the daemon's own bearer token is wrong, so
    * re-read the token): 4011 means the machine needs to be signed in, and no token
    * a client holds can substitute for that. Connect it in the desktop app. */
   NotSignedIn: 4011,
-  /** This ONE profile is open on another machine of the same account (DEC-015).
+  /** This ONE profile is open on another machine of the same account.
    * Distinct from ConcurrencyLimit (4008 = the plan is full, buy more or free any
    * browser): the caller's move here costs nothing. Close it on that machine, or
    * take it over from the app running there. */
   ProfileInUse: 4012,
-  /** The exit address this start drew belongs to another profile (DEC-017).
+  /** The exit address this start drew belongs to another profile.
    * Distinct from ProxyGeo (4002 = wrong country or wrong kind of exit, so change
    * the proxy): here the proxy is fine and the address is simply spoken for. Wait
    * for a term to run out, let the daemon draw again, or turn exclusivity off for
@@ -1211,7 +1211,7 @@ var CdpSession = class _CdpSession {
     });
     return executionContextId;
   }
-  // ── Humanized trusted input (routes through the daemon, G8) ────────────────
+  // ── Humanized trusted input (routes through the daemon) ────────────────────
   humanizeMove(x, y, opts = {}) {
     return this.#input({ action: "move", x, y, width: opts.width });
   }
@@ -1589,7 +1589,7 @@ var ScalebrowserClient = class extends ClientCore {
       signal
     });
   }
-  // ── Exit-address exclusivity (DEC-017) ──────────────────────────────────────
+  // ── Exit-address exclusivity ────────────────────────────────────────────────
   /** Which exit addresses this profile owns, and how far the rule reaches.
    *
    * `scope` is `'machine'` while this computer has no account key. That is the
@@ -1601,14 +1601,14 @@ var ScalebrowserClient = class extends ClientCore {
       signal
     });
   }
-  // ── Session bundles (AC-ST-002/003) ─────────────────────────────────────────
+  // ── Session bundles ─────────────────────────────────────────────────────────
   exportSession(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/session/export`, body);
   }
   importSession(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/session/import`, body);
   }
-  // ── Trusted input (G8, AC-API-003) ─────────────────────────────────────────
+  // ── Trusted input ──────────────────────────────────────────────────────────
   sendInput(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/input`, body);
   }
@@ -1732,6 +1732,6 @@ var PROXY_KINDS = ["http", "socks5", "gateway"];
 var ROTATIONS = ["sticky", "rotating"];
 
 // src/index.ts
-var VERSION = "0.9.0";
+var VERSION = "1.1.0";
 
 export { ApiError, CdpError, CdpSession, DEFAULT_CAPACITY, ErrorCode, GEO_MODES, NetworkError, PROXY_KINDS, ROTATIONS, RUNTIME_STATES, ScalebrowserClient, ScalebrowserError, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@scalebrowser/sdk",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "description": "Official Node/TypeScript SDK for the Scalebrowser daemon: typed REST client plus a direct-CDP driver plane (nodriver-style, not Playwright).",
   "type": "module",
   "license": "MIT",
   "homepage": "https://scalebrowser.net",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/blackdiamond-labs/scalebrowser.git",
-    "directory": "sdks/node"
+    "url": "git+https://github.com/blackdiamond-labs/scalebrowser-node.git"
   },
   "bugs": {
     "email": "support@scalebrowser.net"