@boatdev/sdk 1.1.0 → 1.3.0

package/src/boat-helpers.ts

@@ -1,6 +1,6 @@
 
 import { BoatApi } from './apis/BoatApi';
-import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun } from './models';
+import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun, CommandStreamFrame } from './models';
 
 export type WaitOptions = {
   timeoutMs?: number;
@@ -185,3 +185,77 @@ export async function writeText(api: BoatApi, sandboxId: string, path: string, c
 export async function execCommand(api: BoatApi, sandboxId: string, command: string, cwd?: string, timeoutSeconds = 30) {
   return api.command({ sandboxId, commandRequest: { command, cwd, timeoutSeconds } });
 }
+
+/** One line of a streamed command, as sent (an `exit` frame also carries e.g. `signal`, `oomKilled`). */
+export type CommandFrame = CommandStreamFrame & Record<string, unknown>;
+
+export type StreamCommandOptions = {
+  cwd?: string;
+  timeoutSeconds?: number;
+  signal?: AbortSignal;
+};
+
+// A refusal that provably never ran the command (the sandbox is still restoring
+// its disk, `retryable: true` before `started`) is retried for this long.
+const STREAM_RETRY_MS = 60_000;
+
+async function* ndjsonFrames(response: Response): AsyncGenerator<CommandFrame> {
+  if (!response.body) throw new Error('The command stream has no body');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffered = '';
+  let done = false;
+  try {
+    while (!done) {
+      const chunk = await reader.read();
+      done = chunk.done;
+      buffered += done ? decoder.decode() : decoder.decode(chunk.value, { stream: true });
+      let newline = buffered.indexOf('\n');
+      while (newline !== -1) {
+        const line = buffered.slice(0, newline).trim();
+        buffered = buffered.slice(newline + 1);
+        if (line) yield JSON.parse(line);
+        newline = buffered.indexOf('\n');
+      }
+    }
+    if (buffered.trim()) yield JSON.parse(buffered);
+  } finally {
+    // The caller stopped early: drop the connection instead of reading the rest.
+    if (!done) await reader.cancel().catch(() => undefined);
+  }
+}
+
+/**
+ * Run a command and yield its output as the command writes it: `started`, then
+ * `stdout`/`stderr` chunks (`frame.data`), then exactly one `exit` (`exitCode`,
+ * `timedOut`, ...) or `error` (`error`, `message`).
+ *
+ * Safe to call right after `resume()`, without waiting: the API holds a command
+ * sent to a starting sandbox for up to 60 s instead of refusing it.
+ */
+export async function* streamCommand(
+  api: BoatApi,
+  sandboxId: string,
+  command: string,
+  options?: StreamCommandOptions,
+): AsyncGenerator<CommandFrame> {
+  const deadline = Date.now() + STREAM_RETRY_MS;
+  for (;;) {
+    const response = await api.commandRaw(
+      { sandboxId, commandRequest: { command, cwd: options?.cwd, timeoutSeconds: options?.timeoutSeconds, stream: true } },
+      { signal: options?.signal },
+    );
+    let started = false;
+    let retry = false;
+    for await (const frame of ndjsonFrames(response.raw)) {
+      started = started || frame.type === 'started';
+      if (!started && frame.type === 'error' && frame.retryable === true && Date.now() < deadline) {
+        retry = true;
+        break;
+      }
+      yield frame;
+    }
+    if (!retry) return;
+    await delay(1_000);
+  }
+}

package/src/models/CommandRequest.ts

@@ -43,6 +43,12 @@ export interface CommandRequest {
      * @memberof CommandRequest
      */
     detached?: boolean;
+    /**
+     * Stream the output as the command writes it: the response is newline-delimited JSON (application/x-ndjson), one CommandStreamFrame per line. Ignored with detached.
+     * @type {boolean}
+     * @memberof CommandRequest
+     */
+    stream?: boolean;
 }
 
 /**
@@ -67,6 +73,7 @@ export function CommandRequestFromJSONTyped(json: any, ignoreDiscriminator: bool
         'cwd': json['cwd'] == null ? undefined : json['cwd'],
         'timeoutSeconds': json['timeoutSeconds'] == null ? undefined : json['timeoutSeconds'],
         'detached': json['detached'] == null ? undefined : json['detached'],
+        'stream': json['stream'] == null ? undefined : json['stream'],
     };
 }
 
@@ -85,6 +92,7 @@ export function CommandRequestToJSONTyped(value?: CommandRequest | null, ignoreD
         'cwd': value['cwd'],
         'timeoutSeconds': value['timeoutSeconds'],
         'detached': value['detached'],
+        'stream': value['stream'],
     };
 }
 

package/src/models/CommandStreamFrame.ts

@@ -0,0 +1,136 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Boat Public API v1
+ * Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products.  The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1. 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+/**
+ * One line of a streamed command. `started` first, then `stdout`/`stderr` chunks, then exactly one `exit` (the synchronous result, without stdout/stderr) or `error`.
+ * @export
+ * @interface CommandStreamFrame
+ */
+export interface CommandStreamFrame {
+    /**
+     * 
+     * @type {CommandStreamFrameTypeEnum}
+     * @memberof CommandStreamFrame
+     */
+    type: CommandStreamFrameTypeEnum;
+    /**
+     * stdout/stderr: the chunk of output, UTF-8.
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    data?: string;
+    /**
+     * 
+     * @type {number}
+     * @memberof CommandStreamFrame
+     */
+    exitCode?: number | null;
+    /**
+     * 
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    success?: boolean;
+    /**
+     * 
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    timedOut?: boolean;
+    /**
+     * 
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    error?: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    message?: string;
+    /**
+     * error: true when the command provably never ran (the sandbox is still restoring its disk), so sending it again is safe.
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    retryable?: boolean;
+}
+
+
+/**
+ * @export
+ */
+export const CommandStreamFrameTypeEnum = {
+    Started: 'started',
+    Stdout: 'stdout',
+    Stderr: 'stderr',
+    Exit: 'exit',
+    Error: 'error'
+} as const;
+export type CommandStreamFrameTypeEnum = typeof CommandStreamFrameTypeEnum[keyof typeof CommandStreamFrameTypeEnum];
+
+
+/**
+ * Check if a given object implements the CommandStreamFrame interface.
+ */
+export function instanceOfCommandStreamFrame(value: object): value is CommandStreamFrame {
+    if (!('type' in value) || value['type'] === undefined) return false;
+    return true;
+}
+
+export function CommandStreamFrameFromJSON(json: any): CommandStreamFrame {
+    return CommandStreamFrameFromJSONTyped(json, false);
+}
+
+export function CommandStreamFrameFromJSONTyped(json: any, ignoreDiscriminator: boolean): CommandStreamFrame {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'type': json['type'],
+        'data': json['data'] == null ? undefined : json['data'],
+        'exitCode': json['exitCode'] == null ? undefined : json['exitCode'],
+        'success': json['success'] == null ? undefined : json['success'],
+        'timedOut': json['timedOut'] == null ? undefined : json['timedOut'],
+        'error': json['error'] == null ? undefined : json['error'],
+        'message': json['message'] == null ? undefined : json['message'],
+        'retryable': json['retryable'] == null ? undefined : json['retryable'],
+    };
+}
+
+export function CommandStreamFrameToJSON(json: any): CommandStreamFrame {
+    return CommandStreamFrameToJSONTyped(json, false);
+}
+
+export function CommandStreamFrameToJSONTyped(value?: CommandStreamFrame | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'type': value['type'],
+        'data': value['data'],
+        'exitCode': value['exitCode'],
+        'success': value['success'],
+        'timedOut': value['timedOut'],
+        'error': value['error'],
+        'message': value['message'],
+        'retryable': value['retryable'],
+    };
+}
+

package/src/models/CreateSandboxRequest.ts

@@ -49,6 +49,18 @@ export interface CreateSandboxRequest {
      * @memberof CreateSandboxRequest
      */
     noEnv?: boolean;
+    /**
+     * Pass `false` to never snapshot this sandbox. Nothing is captured in the background, so it pays no CPU or memory for it, and stopping it erases its disk the way zero data retention does. It cannot be resumed, forked, or saved as a named snapshot, and if its machine fails there is no backup to rebuild it from.
+     * @type {boolean}
+     * @memberof CreateSandboxRequest
+     */
+    snapshots?: boolean;
+    /**
+     * Pass `true` to get a sandbox only if a machine of this type is ready right now. The call answers within about 1.5 s: either the usual `202` with the sandbox, or `503` `no_ready_machine` with nothing created, billed, or counted against your start limits, so you can retry or fall back at once. Without it, a create waits for a machine to be built when none is ready. Not combinable with `from`.
+     * @type {boolean}
+     * @memberof CreateSandboxRequest
+     */
+    failFast?: boolean;
     /**
      * Shell script that runs on the sandbox after it is ready. Ready means "ready to accept the user", not "setup done": the script starts in the background once provisioning completes and never blocks the sandbox becoming usable. It runs as the sandbox user via `bash`, with the sandbox's environment applied, and its output goes to a log file on the sandbox. Observe the outcome as `setupStatus` (pending/running/done/failed) and `setupError` on the sandbox. Rejected with a 400 `invalid_setup_script` error when it is not a string or exceeds 64KB.
      * @type {string}
@@ -109,6 +121,8 @@ export function CreateSandboxRequestFromJSONTyped(json: any, ignoreDiscriminator
         'env': json['env'] == null ? undefined : json['env'],
         'environment': json['environment'] == null ? undefined : json['environment'],
         'noEnv': json['noEnv'] == null ? undefined : json['noEnv'],
+        'snapshots': json['snapshots'] == null ? undefined : json['snapshots'],
+        'failFast': json['failFast'] == null ? undefined : json['failFast'],
         'setupScript': json['setupScript'] == null ? undefined : json['setupScript'],
         'org': json['org'] == null ? undefined : json['org'],
         'teamId': json['teamId'] == null ? undefined : json['teamId'],
@@ -132,6 +146,8 @@ export function CreateSandboxRequestToJSONTyped(value?: CreateSandboxRequest | n
         'env': value['env'],
         'environment': value['environment'],
         'noEnv': value['noEnv'],
+        'snapshots': value['snapshots'],
+        'failFast': value['failFast'],
         'setupScript': value['setupScript'],
         'org': value['org'],
         'teamId': value['teamId'],

package/src/models/DataRetentionPolicyResponse.ts

@@ -55,6 +55,18 @@ export interface DataRetentionPolicyResponse {
      * @memberof DataRetentionPolicyResponse
      */
     acceptedDeletionOperationsIrreversible?: boolean;
+    /**
+     * When true, every new sandbox of this account is created with snapshots off.
+     * @type {boolean}
+     * @memberof DataRetentionPolicyResponse
+     */
+    snapshotsOff?: boolean;
+    /**
+     * 
+     * @type {Date}
+     * @memberof DataRetentionPolicyResponse
+     */
+    snapshotsOffAt?: Date | null;
 }
 
 
@@ -95,6 +107,8 @@ export function DataRetentionPolicyResponseFromJSONTyped(json: any, ignoreDiscri
         'enabledAt': (json['enabledAt'] == null ? null : new Date(json['enabledAt'])),
         'queuedSandboxes': json['queuedSandboxes'] == null ? undefined : json['queuedSandboxes'],
         'acceptedDeletionOperationsIrreversible': json['acceptedDeletionOperationsIrreversible'] == null ? undefined : json['acceptedDeletionOperationsIrreversible'],
+        'snapshotsOff': json['snapshotsOff'] == null ? undefined : json['snapshotsOff'],
+        'snapshotsOffAt': json['snapshotsOffAt'] == null ? undefined : (new Date(json['snapshotsOffAt'])),
     };
 }
 
@@ -115,6 +129,8 @@ export function DataRetentionPolicyResponseToJSONTyped(value?: DataRetentionPoli
         'enabledAt': value['enabledAt'] == null ? value['enabledAt'] : value['enabledAt'].toISOString(),
         'queuedSandboxes': value['queuedSandboxes'],
         'acceptedDeletionOperationsIrreversible': value['acceptedDeletionOperationsIrreversible'],
+        'snapshotsOff': value['snapshotsOff'],
+        'snapshotsOffAt': value['snapshotsOffAt'] == null ? value['snapshotsOffAt'] : value['snapshotsOffAt'].toISOString(),
     };
 }
 

package/src/models/DataRetentionUpdateRequest.ts

@@ -14,7 +14,7 @@
 
 import { mapValues } from '../runtime';
 /**
- * 
+ * Pass `enabled` to change zero data retention, or `snapshotsOff` alone to change the account's snapshots-off setting.
  * @export
  * @interface DataRetentionUpdateRequest
  */
@@ -24,7 +24,13 @@ export interface DataRetentionUpdateRequest {
      * @type {boolean}
      * @memberof DataRetentionUpdateRequest
      */
-    enabled: boolean;
+    enabled?: boolean;
+    /**
+     * Turn snapshots off for every sandbox created from now on. Existing sandboxes keep their setting. While on, a create or fork that passes `snapshots: true` is refused with 409 `snapshots_off_for_account`.
+     * @type {boolean}
+     * @memberof DataRetentionUpdateRequest
+     */
+    snapshotsOff?: boolean;
     /**
      * Required when enabling and must exactly equal `delete archived sandbox data`.
      * @type {DataRetentionUpdateRequestConfirmationEnum}
@@ -47,7 +53,6 @@ export type DataRetentionUpdateRequestConfirmationEnum = typeof DataRetentionUpd
  * Check if a given object implements the DataRetentionUpdateRequest interface.
  */
 export function instanceOfDataRetentionUpdateRequest(value: object): value is DataRetentionUpdateRequest {
-    if (!('enabled' in value) || value['enabled'] === undefined) return false;
     return true;
 }
 
@@ -61,7 +66,8 @@ export function DataRetentionUpdateRequestFromJSONTyped(json: any, ignoreDiscrim
     }
     return {
         
-        'enabled': json['enabled'],
+        'enabled': json['enabled'] == null ? undefined : json['enabled'],
+        'snapshotsOff': json['snapshotsOff'] == null ? undefined : json['snapshotsOff'],
         'confirmation': json['confirmation'] == null ? undefined : json['confirmation'],
     };
 }
@@ -78,6 +84,7 @@ export function DataRetentionUpdateRequestToJSONTyped(value?: DataRetentionUpdat
     return {
         
         'enabled': value['enabled'],
+        'snapshotsOff': value['snapshotsOff'],
         'confirmation': value['confirmation'],
     };
 }

package/src/models/Sandbox.ts

@@ -129,6 +129,12 @@ export interface Sandbox {
      * @memberof Sandbox
      */
     desktopUrl?: string | null;
+    /**
+     * False when the sandbox was created with snapshots off.
+     * @type {boolean}
+     * @memberof Sandbox
+     */
+    snapshots?: boolean;
     /**
      * 
      * @type {boolean}
@@ -298,6 +304,7 @@ export function SandboxFromJSONTyped(json: any, ignoreDiscriminator: boolean): S
         'archiveAfter': json['archiveAfter'] == null ? undefined : (new Date(json['archiveAfter'])),
         'desktopAvailable': json['desktopAvailable'],
         'desktopUrl': json['desktopUrl'] == null ? undefined : json['desktopUrl'],
+        'snapshots': json['snapshots'] == null ? undefined : json['snapshots'],
         'snapshotAvailable': json['snapshotAvailable'],
         'snapshotCompletedAt': json['snapshotCompletedAt'] == null ? undefined : (new Date(json['snapshotCompletedAt'])),
         'snapshotVerifiedAt': json['snapshotVerifiedAt'] == null ? undefined : (new Date(json['snapshotVerifiedAt'])),
@@ -340,6 +347,7 @@ export function SandboxToJSONTyped(value?: Sandbox | null, ignoreDiscriminator:
         'archiveAfter': value['archiveAfter'] == null ? value['archiveAfter'] : value['archiveAfter'].toISOString(),
         'desktopAvailable': value['desktopAvailable'],
         'desktopUrl': value['desktopUrl'],
+        'snapshots': value['snapshots'],
         'snapshotAvailable': value['snapshotAvailable'],
         'snapshotCompletedAt': value['snapshotCompletedAt'] == null ? value['snapshotCompletedAt'] : value['snapshotCompletedAt'].toISOString(),
         'snapshotVerifiedAt': value['snapshotVerifiedAt'] == null ? value['snapshotVerifiedAt'] : value['snapshotVerifiedAt'].toISOString(),

package/src/models/index.ts

@@ -22,6 +22,7 @@ export * from './CommandRequest';
 export * from './CommandResponse';
 export * from './CommandStartedResponse';
 export * from './CommandStatusResponse';
+export * from './CommandStreamFrame';
 export * from './CompletionEvent';
 export * from './Conversation';
 export * from './ConversationsResponse';