@run-cloud/sdk 0.22.0 → 0.23.0

package/README.md

@@ -245,6 +245,52 @@ const restored = await cloud.snapshots.restore(snap.id);
 Sandbox fields are returned in both the API's `snake_case` and camelCase
 (`milli_cpu` and `milliCpu` are both present).
 
+Read fleet history and per-sandbox resource metrics, or control a desktop-image
+sandbox through its short-lived viewer and computer-use endpoints:
+
+```ts
+const overview = await cloud.overview();
+const history = await cloud.sandboxes.history({ range: "24h" });
+const metrics = await cloud.sandboxes.metrics(sandbox.id, { range: "1h" });
+const desktop = await cloud.sandboxes.desktop(sandbox.id, { viewOnly: true });
+const screenshot = await cloud.sandboxes.computer(sandbox.id, {
+  action: "screenshot",
+});
+```
+
+Use `credential()` for a lightweight token/product-scope probe and `account()`
+for the caller's full profile and organization memberships. An API key can
+revoke itself:
+
+```ts
+const scope = await cloud.credential();
+const profile = await cloud.account();
+await cloud.revokeCurrentApiKey();
+```
+
+## Distributed tracing
+
+Every SDK-owned HTTP, multipart, byte-download, SSE, and WebSocket transport
+injects W3C trace context. An active OpenTelemetry context is propagated when
+one exists; otherwise the SDK starts the request with a fresh sampled
+`traceparent`. WebSocket exec carries the same context in both the upgrade
+headers and its first command frame.
+
+Applications that already use OpenTelemetry can install their preferred global
+propagator and start a span normally:
+
+```ts
+import { trace } from "@opentelemetry/api";
+
+await trace.getTracer("worker").startActiveSpan("provision", async (span) => {
+  try {
+    await cloud.sandboxes.create({ name: "traceable-job" });
+  } finally {
+    span.end();
+  }
+});
+```
+
 The client reads `RUN_CLOUD_API_KEY` first, then `RUN_CLOUD_API_TOKEN`. Override
 the API origin with `RUN_CLOUD_API_URL` or by passing `new Client({ apiUrl })`.
 
@@ -308,11 +354,31 @@ const result = await cloud.remotion.render({
 console.log(result.outputFile);
 ```
 
-`remotionVersion` selects Remotion's matching public, versioned renderer image;
-all Remotion packages in a project should use that exact version. You can pass
-`image` instead to use a custom compatible runtime. Signed URLs are written to
+`remotionVersion` selects Remotion's matching public runtime image and installs
+that exact renderer during sandbox startup; all Remotion packages in a project
+should use the same version. You can pass `image` instead to use a custom
+runtime that already includes the renderer. Signed URLs are written to
 a private guest file and are not included in command logs.
 
+For repeated renders, create a version-pinned snapshot once and persist its ID:
+
+```ts
+const runtime = await cloud.remotion.createRuntimeSnapshot({
+  remotionVersion: "4.0.507",
+});
+
+const result = await cloud.remotion.render({
+  serveUrl: "https://example.com/remotion-bundle",
+  composition: "ProductDemo",
+  snapshotId: runtime.id,
+  codec: "h264",
+  output: { uploadUrl: presignedPutUrl, downloadUrl: finalObjectUrl },
+});
+```
+
+The snapshot is private to the caller's run.cloud organization. Create one per
+Remotion version and delete obsolete snapshots with `cloud.snapshots.delete()`.
+
 For a smaller migration from `@remotion/lambda/client`, switch the import and
 add `s3Output`; existing `region` and `functionName` fields may remain while
 compute moves to run.cloud:
@@ -394,6 +460,15 @@ finite sandbox timeouts remain the cleanup backstop.
 
 `cloud.assets.upload(blob, options)` verifies the uploaded size and MD5 before
 returning a ready asset. Re-uploading the same bytes reuses the verified object.
+`cloud.assets.uploadDirect(blob, options)` uses the API's buffered multipart
+endpoint when a signed-storage transfer is not suitable, and
+`cloud.assets.download(id)` returns the owned asset as a `Uint8Array`:
+
+```ts
+const asset = await cloud.assets.uploadDirect(blob, { filename: "app.tar.gz" });
+await writeFile("app.tar.gz", await cloud.assets.download(asset.id));
+```
+
 For multipart archives, `cloud.assets.uploadBatch(parts, { uploadBatchId,
 uploadRunId })` numbers the parts, records per-part transfer telemetry, and
 limits direct storage transfers to six at a time.

package/dist/compat/remotion-lambda.d.ts

@@ -37,7 +37,7 @@ export interface RenderMediaOnLambdaInput extends CompatibilityClientOptions {
      * upload and download locations. run.cloud never owns the bucket.
      */
     s3Output: LambdaCompatibleS3Output;
-    runCloud?: Pick<RemotionRenderOptions, "image" | "remotionVersion" | "cpu" | "memory" | "disk" | "timeoutSeconds" | "startupTimeoutSeconds" | "region" | "name" | "idempotencyKey"> & {
+    runCloud?: Pick<RemotionRenderOptions, "image" | "snapshotId" | "remotionVersion" | "cpu" | "memory" | "disk" | "timeoutSeconds" | "startupTimeoutSeconds" | "region" | "name" | "idempotencyKey"> & {
         /**
          * Enables multi-sandbox rendering. createChunkOutput presigns temporary
          * video/audio objects in the customer's own S3 bucket.

package/dist/compat/remotion-lambda.js

@@ -33,7 +33,9 @@ export async function renderMediaOnLambda(input) {
         ...runCloud,
         distributed,
         remotionVersion: runCloud.remotionVersion ??
-            (runCloud.image ? undefined : remotionVersionFromFunctionName(input.functionName)),
+            (runCloud.image || runCloud.snapshotId
+                ? undefined
+                : remotionVersionFromFunctionName(input.functionName)),
     });
     return {
         renderId: handle.renderId,
@@ -61,7 +63,7 @@ export async function deleteRender(input) {
 export function remotionVersionFromFunctionName(functionName) {
     const match = functionName?.match(/^remotion-render-(\d+)-(\d+)-(\d+)(?:-|$)/);
     if (!match) {
-        throw new TypeError("functionName must use Remotion's naming convention, or runCloud.remotionVersion/image must be supplied");
+        throw new TypeError("functionName must use Remotion's naming convention, or runCloud.remotionVersion/image/snapshotId must be supplied");
     }
     return `${match[1]}.${match[2]}.${match[3]}`;
 }

package/dist/compat/remotion-lambda.js.map

@@ -1 +1 @@
-{"version":3,"file":"remotion-lambda.js","sourceRoot":"","sources":["../../src/compat/remotion-lambda.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"remotion-lambda.js","sourceRoot":"","sources":["../../src/compat/remotion-lambda.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -337,6 +337,34 @@ export interface Account {
     run_cloud_metering_status?: string;
     [key: string]: unknown;
 }
+/** Lightweight credential probe used by login and token-validation flows. */
+export interface CredentialAccount {
+    userId: string;
+    products: string[];
+    runCloud: boolean;
+    orgs: string[];
+}
+/** Organization-wide live sandbox capacity and estimated lifetime usage. */
+export interface RunCloudOverview {
+    total: number;
+    byState: Record<string, number>;
+    reservedMilliCpu: number;
+    reservedMemMb: number;
+    billedSeconds: number;
+    estimatedCostUsd: number;
+    actualCpuSeconds: number;
+}
+export type SandboxMetricRange = "1h" | "6h" | "24h" | "7d" | "30d" | "all";
+export type SandboxHistoryRange = SandboxMetricRange;
+export interface SandboxHistoryPoint {
+    timestamp: string;
+    count: number;
+}
+export interface SandboxHistory {
+    range: SandboxHistoryRange;
+    created: number;
+    points: SandboxHistoryPoint[];
+}
 export interface Asset {
     id: string;
     name: string;
@@ -565,6 +593,65 @@ export interface SandboxTunnel {
     expiresAt: string;
     createdAt: string;
 }
+export interface SandboxMetric {
+    timestamp: string;
+    state: string;
+    cpu_millicores: number;
+    cpu_throttled_millicores: number;
+    cpu_throttled_periods: number;
+    cpu_throttling_valid: boolean;
+    memory_bytes: number;
+    memory_oom_events: number;
+    memory_oom_kills: number;
+    memory_events_valid: boolean;
+    network_rx_bytes_per_second: number;
+    network_tx_bytes_per_second: number;
+    network_rx_bytes: number;
+    network_tx_bytes: number;
+    network_valid: boolean;
+    io_read_bytes_per_second: number;
+    io_write_bytes_per_second: number;
+    io_read_bytes: number;
+    io_write_bytes: number;
+    io_valid: boolean;
+    cpu_pressure_usec_per_second: number;
+    memory_pressure_usec_per_second: number;
+    io_pressure_usec_per_second: number;
+    pressure_valid: boolean;
+    disk_used_bytes: number;
+    disk_total_bytes: number;
+    disk_valid: boolean;
+}
+export interface SandboxMetrics {
+    range: SandboxMetricRange;
+    current: SandboxMetric | null;
+    history: SandboxMetric[];
+}
+export interface SandboxDesktop {
+    url: string;
+    expiresAt: string;
+    viewOnly: boolean;
+}
+export type SandboxComputerAction = {
+    action: "screenshot";
+} | {
+    action: "click";
+    x: number;
+    y: number;
+} | {
+    action: "type";
+    text: string;
+} | {
+    action: "key";
+    keys: string;
+};
+export interface SandboxComputerResult {
+    error?: string;
+    /** Base64-encoded PNG when action is screenshot. */
+    image?: string;
+    x?: number;
+    y?: number;
+}
 /**
  * A persistent published web app: a stable `<name>-box.run.cloud` hostname
  * routed to one port on an already-running, idle-pause-disabled sandbox.
@@ -824,12 +911,17 @@ export declare class Client {
     usage(options?: {
         orgId?: string;
     }): Promise<UsageReport>;
+    /** Validate the current credential and return its product/org scope. */
+    credential(): Promise<CredentialAccount>;
+    /** Revoke the API key making this request. Session credentials are a no-op. */
+    revokeCurrentApiKey(): Promise<void>;
+    /** Aggregate live fleet capacity and estimated usage for the caller's organizations. */
+    overview(): Promise<RunCloudOverview>;
     /**
      * The caller's profile, org memberships (with role), and sign-in
      * providers. Backed by `/run-cloud/me` — the richer, deliberately-designed
      * profile route, not the older `/run-cloud/account` (a thin credential
-     * probe the `newly` CLI still calls directly; nothing in this SDK targets
-     * it as of this method's repoint in 0.17.0).
+     * probe exposed separately through `credential()`).
      */
     account(): Promise<Account>;
     /**
@@ -977,6 +1069,20 @@ export declare class SandboxClient {
         name?: string;
     }): Promise<Sandbox[]>;
     get(id: string): Promise<Sandbox>;
+    /** Organization-scoped live sandbox counts over a bounded time range. */
+    history(options?: {
+        range?: SandboxHistoryRange;
+    }): Promise<SandboxHistory>;
+    /** Current and time-bucketed resource metrics for one owned sandbox. */
+    metrics(id: string, options?: {
+        range?: SandboxMetricRange;
+    }): Promise<SandboxMetrics>;
+    /** Mint a short-lived noVNC capability for a running desktop-image sandbox. */
+    desktop(id: string, options?: {
+        viewOnly?: boolean;
+    }): Promise<SandboxDesktop>;
+    /** Perform one owner-gated computer-use action in a desktop-image sandbox. */
+    computer(id: string, action: SandboxComputerAction): Promise<SandboxComputerResult>;
     /**
      * Halt a sandbox, keeping its disk and memory. Compute billing stops; a
      * `resume` brings back the same sandbox. Idle sandboxes pause themselves
@@ -1090,6 +1196,9 @@ export declare class SnapshotsClient {
         cpu?: number;
         memory?: number;
         disk?: number;
+        idlePauseSeconds?: number;
+        timeoutSeconds?: number;
+        idempotencyKey?: string;
     }): Promise<Sandbox>;
 }
 export declare class BoxClient {
@@ -1259,6 +1368,10 @@ export declare class AssetsClient {
     private readonly defaultUploadRunId;
     constructor(client: Client);
     list(): Promise<Asset[]>;
+    /** Upload through the buffered multipart endpoint instead of signed storage URLs. */
+    uploadDirect(file: Blob, options?: Pick<AssetUploadOptions, "name" | "filename">): Promise<Asset>;
+    /** Download an owned asset, following the API's short-lived signed redirect. */
+    download(id: string): Promise<Uint8Array>;
     upload(file: Blob, options?: AssetUploadOptions): Promise<Asset>;
     uploadBatch(items: AssetUploadItem[], options?: {
         uploadBatchId?: string;

package/dist/index.js

@@ -1,7 +1,22 @@
 import WebSocket from "ws";
-import { createHash, randomUUID } from "node:crypto";
+import { context, propagation } from "@opentelemetry/api";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { RemotionClient } from "./remotion.js";
 export * from "./remotion.js";
+function randomW3cId(bytes) {
+    const value = randomBytes(bytes);
+    if (value.every((byte) => byte === 0))
+        value[value.length - 1] = 1;
+    return value.toString("hex");
+}
+function outboundTraceHeaders() {
+    const carrier = {};
+    propagation.inject(context.active(), carrier);
+    if (!carrier.traceparent) {
+        carrier.traceparent = `00-${randomW3cId(16)}-${randomW3cId(8)}-01`;
+    }
+    return carrier;
+}
 export const SIMULATOR_KEYS = [
     "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m",
     "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z",
@@ -727,18 +742,29 @@ export class Client {
         this.secrets = new SecretsClient(this);
         this.ci = new CiClient(this);
         this.images = new ImageClient(this);
-        this.remotion = new RemotionClient(this.sandboxes);
+        this.remotion = new RemotionClient(this.sandboxes, this.snapshots);
     }
     async usage(options = {}) {
         const query = options.orgId ? `?orgId=${encodeURIComponent(options.orgId)}` : "";
         return await this.request("GET", `/run-cloud/usage${query}`);
     }
+    /** Validate the current credential and return its product/org scope. */
+    async credential() {
+        return await this.request("GET", "/run-cloud/account");
+    }
+    /** Revoke the API key making this request. Session credentials are a no-op. */
+    async revokeCurrentApiKey() {
+        await this.request("DELETE", "/run-cloud/api-keys/self");
+    }
+    /** Aggregate live fleet capacity and estimated usage for the caller's organizations. */
+    async overview() {
+        return await this.request("GET", "/run-cloud/overview");
+    }
     /**
      * The caller's profile, org memberships (with role), and sign-in
      * providers. Backed by `/run-cloud/me` — the richer, deliberately-designed
      * profile route, not the older `/run-cloud/account` (a thin credential
-     * probe the `newly` CLI still calls directly; nothing in this SDK targets
-     * it as of this method's repoint in 0.17.0).
+     * probe exposed separately through `credential()`).
      */
     async account() {
         const raw = await this.request("GET", "/run-cloud/me");
@@ -766,6 +792,7 @@ export class Client {
                     Authorization: `Bearer ${this.apiKey}`,
                     ...(body === undefined ? {} : { "Content-Type": "application/json" }),
                     ...headers,
+                    ...outboundTraceHeaders(),
                 },
                 body: body === undefined ? undefined : JSON.stringify(body),
                 signal: operation.signal,
@@ -810,7 +837,10 @@ export class Client {
     async uploadForm(path, form) {
         const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
             method: "POST",
-            headers: { Authorization: `Bearer ${this.apiKey}` },
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...outboundTraceHeaders(),
+            },
             body: form,
         });
         if (!response.ok)
@@ -825,6 +855,7 @@ export class Client {
                 headers: {
                     Authorization: `Bearer ${this.apiKey}`,
                     ...abortOptions.headers,
+                    ...outboundTraceHeaders(),
                 },
                 signal: operation.signal,
             });
@@ -863,6 +894,7 @@ export class Client {
             headers: {
                 Authorization: `Bearer ${this.apiKey}`,
                 Accept: "text/event-stream",
+                ...outboundTraceHeaders(),
             },
             signal,
         });
@@ -903,7 +935,10 @@ export class Client {
     async requestTextWithHeaders(path) {
         const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
             method: "GET",
-            headers: { Authorization: `Bearer ${this.apiKey}` },
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...outboundTraceHeaders(),
+            },
         });
         if (!response.ok)
             throw await apiError(response);
@@ -917,9 +952,13 @@ export class Client {
     async execStream(path, request, callbacks = {}) {
         const url = new URL(`${this.apiUrl}${path}`);
         url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        const traceHeaders = outboundTraceHeaders();
         return await new Promise((resolve, reject) => {
             const socket = this.webSocketFactory(url.toString(), {
-                headers: { Authorization: `Bearer ${this.apiKey}` },
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    ...traceHeaders,
+                },
             });
             const stdout = [];
             const stderr = [];
@@ -954,7 +993,10 @@ export class Client {
                 return;
             }
             callbacks.signal?.addEventListener("abort", abort, { once: true });
-            socket.once("open", () => socket.send(JSON.stringify(request)));
+            socket.once("open", () => socket.send(JSON.stringify({
+                ...request,
+                ...traceHeaders,
+            })));
             socket.on("message", (raw) => {
                 let frame;
                 try {
@@ -1483,6 +1525,24 @@ export class SandboxClient {
         const raw = await this.client.request("GET", `/run-cloud/sandboxes/${encodeURIComponent(id)}`);
         return normalizeSandbox(raw);
     }
+    /** Organization-scoped live sandbox counts over a bounded time range. */
+    async history(options = {}) {
+        const query = options.range ? `?range=${encodeURIComponent(options.range)}` : "";
+        return await this.client.request("GET", `/run-cloud/sandboxes/history${query}`);
+    }
+    /** Current and time-bucketed resource metrics for one owned sandbox. */
+    async metrics(id, options = {}) {
+        const query = options.range ? `?range=${encodeURIComponent(options.range)}` : "";
+        return await this.client.request("GET", `/run-cloud/sandboxes/${encodeURIComponent(id)}/metrics${query}`);
+    }
+    /** Mint a short-lived noVNC capability for a running desktop-image sandbox. */
+    async desktop(id, options = {}) {
+        return await this.client.request("POST", `/run-cloud/sandboxes/${encodeURIComponent(id)}/desktop`, options);
+    }
+    /** Perform one owner-gated computer-use action in a desktop-image sandbox. */
+    async computer(id, action) {
+        return await this.client.request("POST", `/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, action);
+    }
     /**
      * Halt a sandbox, keeping its disk and memory. Compute billing stops; a
      * `resume` brings back the same sandbox. Idle sandboxes pause themselves
@@ -1730,6 +1790,7 @@ export class SnapshotsClient {
         await this.client.request("DELETE", `/run-cloud/snapshots/${encodeURIComponent(id)}`);
     }
     async restore(id, options = {}) {
+        const { idempotencyKey } = options;
         const raw = await this.client.request("POST", `/run-cloud/snapshots/${encodeURIComponent(id)}/restore`, {
             ...(options.name === undefined ? {} : { name: options.name }),
             ...(options.region === undefined ? {} : { region: options.region }),
@@ -1737,7 +1798,13 @@ export class SnapshotsClient {
             ...(options.cpu === undefined ? {} : { cpu: options.cpu }),
             ...(options.memory === undefined ? {} : { memory: options.memory }),
             ...(options.disk === undefined ? {} : { disk: options.disk }),
-        });
+            ...(options.idlePauseSeconds === undefined
+                ? {}
+                : { idlePauseSeconds: options.idlePauseSeconds }),
+            ...(options.timeoutSeconds === undefined
+                ? {}
+                : { timeoutSeconds: options.timeoutSeconds }),
+        }, idempotencyKey ? { "Idempotency-Key": idempotencyKey } : undefined);
         return normalizeSandbox(raw);
     }
 }
@@ -1968,6 +2035,18 @@ export class AssetsClient {
     async list() {
         return await this.client.request("GET", "/run-cloud/assets");
     }
+    /** Upload through the buffered multipart endpoint instead of signed storage URLs. */
+    async uploadDirect(file, options = {}) {
+        const form = new FormData();
+        if (options.name !== undefined)
+            form.append("name", options.name);
+        form.append("file", file, options.filename ?? "app.bin");
+        return await this.client.uploadForm("/run-cloud/assets", form);
+    }
+    /** Download an owned asset, following the API's short-lived signed redirect. */
+    async download(id) {
+        return await this.client.requestBytes(`/run-cloud/assets/${encodeURIComponent(id)}/download`);
+    }
     async upload(file, options = {}) {
         return await this.withUploadSlot(async () => {
             const filename = options.filename ?? "app.bin";