@scalebrowser/sdk 0.4.1 → 0.6.0

package/dist/index.js

@@ -25,7 +25,13 @@ var ErrorCode = {
    * 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
+  ProfileInUse: 4012,
+  /** The exit address this start drew belongs to another profile (DEC-017).
+   * 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
+   * this profile. */
+  ExitAddressTaken: 4013
 };
 var CODE_LABELS = {
   4001: "Not found",
@@ -37,7 +43,8 @@ var CODE_LABELS = {
   4008: "Concurrent-browser limit reached (subscription-wide)",
   4010: "Unauthorized",
   4011: "No account connected to this machine",
-  4012: "This profile is open on another machine"
+  4012: "This profile is open on another machine",
+  4013: "This exit address belongs to another profile"
 };
 var ScalebrowserError = class extends Error {
   constructor(message) {
@@ -248,7 +255,7 @@ var ControlApi = class extends ClientCore {
   /**
    * Hand the daemon a file so `interact action=upload` has something to attach.
    *
-   * The bytes are bound to the PROFILE, not to a reservation: set a file up
+   * The bytes are bound to the PROFILE, not to a lease: set a file up
    * before leasing, and a lease released mid-task does not destroy it.
    */
   putArtifact(profileId, bytes, name) {
@@ -566,6 +573,83 @@ var IdentityApi = class extends ClientCore {
   }
 };
 
+// src/client-tasks.ts
+var TasksApi = class extends ClientCore {
+  // -- Tasks ------------------------------------------------------------------
+  //
+  // Fleet-wide by default, and deliberately so: the question this surface exists
+  // for is "what is outstanding across my twenty accounts", and a per-profile
+  // route would make a client ask it twenty times and sort the answers itself.
+  //
+  // None of these starts a browser. A task is a row, so reading the whole fleet's
+  // list costs nothing from the plan's concurrent-browser allowance. Reserve only
+  // the profiles that turn out to have work.
+  /**
+   * What is still to be done. No filter means every task of every profile.
+   *
+   * Pass `state: 'open'` for what is outstanding; without it, tasks finished
+   * within the last day are included too.
+   */
+  listTasks(params, signal) {
+    return this.request("GET", "/v1/tasks", void 0, {
+      query: { ...params },
+      signal
+    });
+  }
+  /**
+   * Put the same task on one or many profiles, one row each.
+   *
+   * A task is a LINE, not a document: name the work and leave the material where
+   * it lives. `due_at` is a deadline, not a trigger; nothing runs by itself.
+   *
+   * Profiles that no longer exist come back in `missing` instead of failing the
+   * whole call.
+   */
+  createTasks(body) {
+    return this.request("POST", "/v1/tasks", body);
+  }
+  /**
+   * Call a task off.
+   *
+   * Only a task nobody has claimed can be cancelled here. One an agent is working
+   * on right now is stopped by telling that agent, which is a channel that already
+   * reaches it; this surface answers `409` for it rather than pretending.
+   */
+  cancelTask(id) {
+    return this.request("PATCH", `/v1/tasks/${enc(id)}`, { state: "cancelled" });
+  }
+  /** Remove a task outright. */
+  deleteTask(id) {
+    return this.request("DELETE", `/v1/tasks/${enc(id)}`);
+  }
+  // -- Profile memory ---------------------------------------------------------
+  /**
+   * A profile's durable memory, the `PROFILE.md` at the top of its directory.
+   *
+   * `content` is `null` while nobody has written one: a profile starts with no
+   * file, not with an empty one.
+   */
+  getProfileMemory(profileId, signal) {
+    return this.request("GET", `/v1/profiles/${enc(profileId)}/memory`, void 0, {
+      signal
+    });
+  }
+  /**
+   * Replace a profile's memory.
+   *
+   * Stored verbatim: no trimming, no appended newline, no line-ending
+   * translation. The last write wins and nothing warns, exactly as with a file
+   * two people can open.
+   */
+  putProfileMemory(profileId, content) {
+    return this.request("PUT", `/v1/profiles/${enc(profileId)}/memory`, { content });
+  }
+  /** Remove a profile's memory. Removing one that is not there is not an error. */
+  deleteProfileMemory(profileId) {
+    return this.request("DELETE", `/v1/profiles/${enc(profileId)}/memory`);
+  }
+};
+
 // src/client-runs.ts
 var RunsApi = class extends ClientCore {
   // ── Agent runs ─────────────────────────────────────────────────────────────
@@ -602,6 +686,205 @@ var RunsApi = class extends ClientCore {
   }
 };
 
+// src/client-videos.ts
+var VideosApi = class extends ClientCore {
+  // ── Videos ────────────────────────────────────────────────────────────────
+  /** One gallery page, newest first. Running renders are videos too. */
+  listVideos(params = {}, signal) {
+    return this.request("GET", "/v1/videos", void 0, {
+      query: {
+        q: params.q,
+        profile_id: params.profile_id,
+        run_id: params.run_id,
+        kind: params.kind,
+        preset: params.preset,
+        state: params.state,
+        page: params.page
+      },
+      signal
+    });
+  }
+  /** One video row, progress included while it renders. */
+  getVideo(videoId, signal) {
+    return this.request("GET", `/v1/videos/${enc(videoId)}`, void 0, { signal });
+  }
+  /** Rename. The title also lands in the MP4's metadata on the NEXT render. */
+  renameVideo(videoId, title, signal) {
+    return this.request("PATCH", `/v1/videos/${enc(videoId)}`, { title }, { signal });
+  }
+  /**
+   * Delete a video (`raw: true` also purges its recording's raw material).
+   * A live share link is revoked first; 409 `job_running` while it renders.
+   */
+  deleteVideo(videoId, opts = {}, signal) {
+    return this.request("DELETE", `/v1/videos/${enc(videoId)}`, void 0, {
+      query: { raw: opts.raw },
+      signal
+    });
+  }
+  /** Cancel a queued or rendering video. `done` stays done (409). */
+  cancelVideo(videoId, signal) {
+    return this.request("POST", `/v1/videos/${enc(videoId)}/cancel`, void 0, {
+      signal
+    });
+  }
+  /** Render a failed or cancelled video again: same id, new job. */
+  rerenderVideo(videoId, body = {}, signal) {
+    return this.request("POST", `/v1/videos/${enc(videoId)}/renders`, body, { signal });
+  }
+  /** A short-lived fetchable address for one asset (default the video). */
+  videoAccess(videoId, asset, signal) {
+    return this.request(
+      "POST",
+      `/v1/videos/${enc(videoId)}/access`,
+      asset ? { asset } : {},
+      { signal }
+    );
+  }
+  /** One asset's bytes, through a freshly minted grant. */
+  async downloadVideoFile(videoId, asset = "video", signal) {
+    const grant = await this.videoAccess(videoId, asset, signal);
+    const grantParam = new URL(grant.url, "http://x").searchParams.get("grant") ?? "";
+    return this.requestBytes("GET", `/v1/videos/${enc(videoId)}/file`, {
+      query: { asset, grant: grantParam },
+      signal
+    });
+  }
+  /** What recordings and videos cost on disk, plus the caps. */
+  videosStorage(signal) {
+    return this.request("GET", "/v1/videos/storage", void 0, { signal });
+  }
+  // ── Recordings ────────────────────────────────────────────────────────────
+  /** Recordings, newest first. The row outlives its raw bytes. */
+  listRecordings(params = {}, signal) {
+    return this.request("GET", "/v1/recordings", void 0, {
+      query: { profile_id: params.profile_id },
+      signal
+    });
+  }
+  getRecording(recordingId, signal) {
+    return this.request("GET", `/v1/recordings/${enc(recordingId)}`, void 0, {
+      signal
+    });
+  }
+  /**
+   * Purge a recording's RAW material; the row stays forever
+   * (`raw_purged_at`). 409 `job_running` while a render of it is open.
+   */
+  deleteRecordingRaw(recordingId, signal) {
+    return this.request("DELETE", `/v1/recordings/${enc(recordingId)}`, void 0, {
+      signal
+    });
+  }
+  /** A NEW video from this recording (the same body the `video` tool takes). */
+  renderRecording(recordingId, body = {}, signal) {
+    return this.request("POST", `/v1/recordings/${enc(recordingId)}/renders`, body, {
+      signal
+    });
+  }
+  // ── Codecs ────────────────────────────────────────────────────────────────
+  /** What this machine can encode with. The hardware list is PROBED, not read
+   *  off the binary: `h264_nvenc` is always listed and fails without a driver. */
+  getCodecs(signal) {
+    return this.request("GET", "/v1/codecs", void 0, { signal });
+  }
+  /** Turn Cisco's OpenH264 on or off. The hardware encoders are not switchable. */
+  setCodecEnabled(codec, enabled, signal) {
+    return this.request("PUT", `/v1/codecs/${enc(codec)}`, { enabled }, { signal });
+  }
+  // -- Sharing ----------------------------------------------------------------
+  /** Make a finished video public. Measures every file, asks the control plane
+   *  for permission, uploads, and has the result confirmed. */
+  share(videoId, body = {}, signal) {
+    return this.request("POST", `/v1/videos/${enc(videoId)}/share`, body, {
+      signal
+    });
+  }
+  /** The share ORDER as this machine knows it. How many people watched and
+   *  whether the link still lives is read from the control plane, not from
+   *  here: a number carried along would be wrong the moment another machine
+   *  revoked. */
+  shareStatus(videoId, signal) {
+    return this.request(
+      "GET",
+      `/v1/videos/${enc(videoId)}/share`,
+      void 0,
+      { signal }
+    );
+  }
+  /** Revoke the link. The files fall at once; the order stays until the control
+   *  plane confirms. */
+  revokeShare(videoId, signal) {
+    return this.request("DELETE", `/v1/videos/${enc(videoId)}/share`, void 0, {
+      signal
+    });
+  }
+  // -- Media ------------------------------------------------------------------
+  /** Files a preset points at: background image, music bed, subtitle font. */
+  listMedia(kind, signal) {
+    return this.request("GET", "/v1/media", void 0, {
+      query: { kind },
+      signal
+    });
+  }
+  /** Upload one file. The body IS the file; `name` and `mime` ride in the query. */
+  uploadMedia(kind, name, mime, bytes, signal) {
+    return this.request("POST", "/v1/media", bytes, {
+      query: { kind, name, mime },
+      signal
+    });
+  }
+  /** Remove a file. Refuses with 409 while a preset still points at it. */
+  deleteMedia(id, signal) {
+    return this.request("DELETE", `/v1/media/${enc(id)}`, void 0, { signal });
+  }
+  /** The file itself. */
+  mediaFile(id, signal) {
+    return this.requestBytes("GET", `/v1/media/${enc(id)}/file`, { signal });
+  }
+  // -- Voice providers --------------------------------------------------------
+  /** Which speech providers have a key. The key itself never comes back: the
+   *  answer carries a hint, and that is on purpose. */
+  listTtsProviders(signal) {
+    return this.request("GET", "/v1/tts-providers", void 0, { signal });
+  }
+  /** Store a key, or rename one. Leaving `apiKey` out keeps the stored key.
+   *
+   *  `apiKey` may also be a secret reference (`{{sb:...}}`), which is what an
+   *  agent gets back after fetching a key from the provider's own site: it is
+   *  not allowed to read the value. A reference needs `profileId`, because the
+   *  value belongs to one profile and there is nothing to open without it.
+   */
+  putTtsProvider(provider, body, signal) {
+    return this.request(
+      "PUT",
+      `/v1/tts-providers/${enc(provider)}`,
+      { api_key: body.apiKey, label: body.label, profile_id: body.profileId },
+      { signal }
+    );
+  }
+  /** Call the provider once for real, and record that the key works.
+   *
+   *  Costs one short sentence of the account's own quota. Until this runs, a
+   *  provider row says `verified_at: null`, which means untested rather than
+   *  broken.
+   */
+  verifyTtsProvider(provider, signal) {
+    return this.request(
+      "POST",
+      `/v1/tts-providers/${enc(provider)}/verify`,
+      void 0,
+      { signal }
+    );
+  }
+  /** Forget a provider's key. */
+  deleteTtsProvider(provider, signal) {
+    return this.request("DELETE", `/v1/tts-providers/${enc(provider)}`, void 0, {
+      signal
+    });
+  }
+};
+
 // src/events.ts
 var MAX_BACKOFF_MS = 15e3;
 function subscribeEvents(params, handlers) {
@@ -1105,6 +1388,15 @@ var ScalebrowserClient = class extends ClientCore {
   stopProfile(id) {
     return this.request("POST", `/v1/profiles/${enc(id)}/stop`, {});
   }
+  /** Drop the profile's lease, the operator's way out.
+   *
+   *  An agent releases with its handle; this call needs none. The daemon stops
+   *  the browser first when one is still up, then lets the lease go, so a dead
+   *  session cannot park the profile until its TTL runs out. `released: false`
+   *  is an honest no-op: there was nothing to let go. */
+  releaseProfile(id) {
+    return this.request("POST", `/v1/profiles/${enc(id)}/release`, {});
+  }
   /** Ask for a profile that is open on another machine of this account.
    *
    *  Closes nothing here and nothing there: the control plane revokes the holder's
@@ -1176,6 +1468,42 @@ var ScalebrowserClient = class extends ClientCore {
   deletePreset(id) {
     return this.request("DELETE", `/v1/presets/${enc(id)}`);
   }
+  // ── Video presets ──────────────────────────────────────────────────────────
+  listVideoPresets(signal) {
+    return this.request("GET", "/v1/video-presets", void 0, { signal });
+  }
+  getVideoPreset(id, signal) {
+    return this.request("GET", `/v1/video-presets/${enc(id)}`, void 0, { signal });
+  }
+  /** The daemon validates `config` strictly and names the failing field path. */
+  createVideoPreset(body) {
+    return this.request("POST", "/v1/video-presets", body);
+  }
+  /** A built-in preset refuses edits. Duplicate it and edit the copy. */
+  updateVideoPreset(id, body) {
+    return this.request("PATCH", `/v1/video-presets/${enc(id)}`, body);
+  }
+  /** The only way to make a built-in preset yours: copy, then edit the copy. */
+  duplicateVideoPreset(id, body = {}) {
+    return this.request("POST", `/v1/video-presets/${enc(id)}/duplicate`, body);
+  }
+  deleteVideoPreset(id) {
+    return this.request("DELETE", `/v1/video-presets/${enc(id)}`);
+  }
+  /** One still of the sample film under an UNSAVED config, drawn by the daemon's own renderer.
+   *  `moment` wins over `frame`; both absent means the daemon's default moment. */
+  previewVideoPreset(body, signal) {
+    return this.request("POST", "/v1/video-presets/preview", body, { signal });
+  }
+  /** A clip of the sample film, blocking until it is encoded (the editor uses the SSE form of the
+   *  same route; a script waits). Fetch the bytes with `downloadVideoPresetClip`. */
+  previewVideoPresetClip(body, signal) {
+    return this.request("POST", "/v1/video-presets/preview/clip", body, { signal });
+  }
+  /** The clip's MP4 bytes. */
+  downloadVideoPresetClip(id, signal) {
+    return this.requestBytes("GET", `/v1/video-presets/preview/clip/${enc(id)}`, { signal });
+  }
   /**
    * The values a preset's `constraints` may take. Ask rather than hardcode: the
    * region list comes from the daemon's embedded persona model, so a pinned copy
@@ -1232,6 +1560,18 @@ var ScalebrowserClient = class extends ClientCore {
       signal
     });
   }
+  // ── Exit-address exclusivity (DEC-017) ──────────────────────────────────────
+  /** 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
+   * ordinary state of a second machine until sync is unlocked there once, and it is
+   * reported rather than hidden: believing the rule spans three machines when it
+   * spans one is worse than knowing. */
+  getExitStatus(profileId, signal) {
+    return this.request("GET", `/v1/profiles/${enc(profileId)}/exit`, void 0, {
+      signal
+    });
+  }
   // ── Session bundles (AC-ST-002/003) ─────────────────────────────────────────
   exportSession(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/session/export`, body);
@@ -1254,6 +1594,21 @@ var ScalebrowserClient = class extends ClientCore {
       throw err;
     }
   }
+  // ── Remote access (the machine's own switch) ────────────────────────────────
+  /**
+   * Is remote access on for this machine?
+   *
+   * The switch is deliberately local: a chat service reaches this browser only
+   * once somebody at the machine has turned it on. On a headless install there
+   * is no UI to click, which is why it is here as well.
+   */
+  async getRemoteAccess(signal) {
+    return this.request("GET", "/v1/remote", void 0, { signal });
+  }
+  /** Turn remote access on or off for this machine. */
+  async setRemoteAccess(enabled, signal) {
+    return this.request("PUT", "/v1/remote", { enabled }, { signal });
+  }
   // ── Events (SSE) ───────────────────────────────────────────────────────────
   /** Subscribe to lifecycle events. Returns an unsubscribe function. */
   subscribeEvents(handlers) {
@@ -1311,7 +1666,14 @@ function deriveMetricsFromProfiles(profiles) {
     profiles: []
   };
 }
-applyMixins(ScalebrowserClient, [IdentityApi, RunsApi, ControlApi, ExtensionsApi]);
+applyMixins(ScalebrowserClient, [
+  IdentityApi,
+  RunsApi,
+  VideosApi,
+  ControlApi,
+  ExtensionsApi,
+  TasksApi
+]);
 
 // src/types.ts
 var RUNTIME_STATES = ["stopped", "starting", "running", "crashed"];
@@ -1321,6 +1683,6 @@ var PROXY_KINDS = ["http", "socks5", "gateway"];
 var ROTATIONS = ["sticky", "rotating"];
 
 // src/index.ts
-var VERSION = "0.4.1";
+var VERSION = "0.6.0";
 
 export { ApiError, CdpError, CdpSession, DEFAULT_CAPACITY, ErrorCode, GEO_MODES, HOST_MODES, NetworkError, PROXY_KINDS, ROTATIONS, RUNTIME_STATES, ScalebrowserClient, ScalebrowserError, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebrowser/sdk",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Official Node/TypeScript SDK for the Scalebrowser daemon — typed REST client + direct-CDP driver plane (nodriver-style, not Playwright).",
   "type": "module",
   "license": "MIT",