@buddy-works/sandbox-sdk 0.1.6-rc.0 → 0.1.6-rc.1

package/README.md

@@ -95,6 +95,57 @@ await Sandbox.create({
 });
 ```
 
+## Updating a sandbox
+
+Use `sandbox.update()` to change configuration after creation - `timeout`, `apps`, `endpoints`, `variables`, `tags`, etc. The internal state is updated with the API's response.
+
+```typescript
+const sandbox = await Sandbox.getByIdentifier("my-sandbox");
+
+await sandbox.update({
+    timeout: 1200,
+    tags: ["staging", "feature-x"],
+});
+```
+
+## Snapshots
+
+Take point-in-time snapshots of a sandbox and restore from them later. Each snapshot is returned as a `Snapshot` instance with its own methods.
+
+```typescript
+const sandbox = await Sandbox.getByIdentifier("my-sandbox");
+
+// Create a snapshot. Returns immediately with status "CREATING".
+const snapshot = await sandbox.createSnapshot({ name: "before-deploy" });
+
+// Wait until the snapshot is "CREATED" before using it.
+await snapshot.waitUntilReady();
+
+// Create a new sandbox from the snapshot.
+const restored = await Sandbox.createFromSnapshot(snapshot.id, {
+    name: "restored-sandbox",
+});
+
+// List all snapshots for this sandbox.
+const snapshots = await sandbox.listSnapshots();
+
+// Delete a snapshot.
+await snapshot.delete();
+```
+
+If you already have a snapshot ID from elsewhere (e.g. persisted in your own storage), get the entity directly:
+
+```typescript
+const snapshot = await Sandbox.getSnapshotById(sandboxId, snapshotId);
+```
+
+Equivalent convenience methods on `Sandbox` are available when you only have an ID and don't want to fetch the `Snapshot` first:
+
+```typescript
+await sandbox.waitForSnapshotReady(snapshotId);
+await sandbox.deleteSnapshot(snapshotId);
+```
+
 ## Regions
 
 Configure the API region:

package/dist/index.d.mts

@@ -531,6 +531,17 @@ type SandboxContentItem = {
        */
   size?: bigint;
 };
+type SandboxCommandsView = {
+  /**
+       * API endpoint to GET this object
+       */
+  readonly url?: string;
+  /**
+       * Web URL to view this object in Buddy.works
+       */
+  readonly html_url?: string;
+  commands?: Array<SandboxCommandView>;
+};
 type SandboxCommandView = {
   /**
        * API endpoint to GET this object
@@ -601,6 +612,50 @@ type SandboxAppLogsView = {
        */
   logs?: Array<string>;
 };
+type SnapshotsView = {
+  /**
+       * API endpoint to GET this object
+       */
+  readonly url?: string;
+  /**
+       * Web URL to view this object in Buddy.works
+       */
+  readonly html_url?: string;
+  /**
+       * Collection of snapshots
+       */
+  snapshots?: Array<ShortSnapshotView>;
+};
+type ShortSnapshotView = {
+  /**
+       * API endpoint to GET this object
+       */
+  readonly url?: string;
+  /**
+       * Web URL to view this object in Buddy.works
+       */
+  readonly html_url?: string;
+  /**
+       * The ID of the snapshot
+       */
+  id?: string;
+  /**
+       * Snapshot name
+       */
+  name?: string;
+  /**
+       * Snapshot size in GB
+       */
+  size?: number;
+  /**
+       * Snapshot status
+       */
+  status?: "CREATING" | "CREATED" | "DELETING" | "FAILED";
+  /**
+       * Snapshot creation date
+       */
+  create_date?: Date;
+};
 type ExecuteSandboxCommandRequest = {
   /**
        * Command to execute in the sandbox
@@ -611,6 +666,43 @@ type ExecuteSandboxCommandRequest = {
        */
   runtime?: "BASH" | "JAVASCRIPT" | "TYPESCRIPT" | "PYTHON";
 };
+type AddSnapshotRequest = {
+  /**
+       * Snapshot name
+       */
+  name?: string;
+};
+type SnapshotView = {
+  /**
+       * API endpoint to GET this object
+       */
+  readonly url?: string;
+  /**
+       * Web URL to view this object in Buddy.works
+       */
+  readonly html_url?: string;
+  /**
+       * The ID of the snapshot
+       */
+  id?: string;
+  /**
+       * Snapshot name
+       */
+  name?: string;
+  /**
+       * Snapshot size in GB
+       */
+  size?: number;
+  /**
+       * Snapshot status
+       */
+  status?: "CREATING" | "CREATED" | "DELETING" | "FAILED";
+  /**
+       * Snapshot creation date
+       */
+  create_date?: Date;
+  created_by?: MemberView;
+};
 type EnvironmentVariableView = {
   /**
        * The ID of the variable
@@ -795,6 +887,53 @@ type SandboxResponse = {
        */
   variables?: Array<EnvironmentVariableView>;
 };
+type UpdateSandboxRequestWritable = {
+  /**
+       * The name of the sandbox
+       */
+  name?: string;
+  /**
+       * A human-readable ID. Alphanumeric characters, underscores, and hyphens (hyphens cannot appear at the start or end).
+       */
+  identifier?: string;
+  /**
+       * The resource configuration of the sandbox (CPU x RAM)
+       */
+  resources?: "1x2" | "2x4" | "3x6" | "4x8" | "5x10" | "6x12" | "7x14" | "8x16" | "9x18" | "10x20" | "11x22" | "12x24" | "CUSTOM";
+  /**
+       * The commands to run during first boot of the sandbox
+       */
+  first_boot_commands?: string;
+  /**
+       * The application directory of the sandbox
+       */
+  app_dir?: string;
+  /**
+       * The list of apps (run commands) for the sandbox
+       */
+  apps?: Array<SandboxAppView>;
+  /**
+       * The list of items (repositories and artifacts) to fetch into the sandbox
+       */
+  fetch?: Array<SandboxFetchView>;
+  /**
+       * The timeout in seconds after which the sandbox will be automatically stopped
+       */
+  timeout?: number;
+  /**
+       * The list of tags associated with the sandbox
+       */
+  tags?: Array<string>;
+  /**
+       * The tunnel endpoints of the sandbox
+       */
+  endpoints?: Array<TunnelViewWritable>;
+  /**
+       * The environment variables of the sandbox
+       */
+  variables?: Array<AddVariableInObjectRequestWritable>;
+  permissions?: PermissionsView;
+};
 /**
  * The environment variables of the sandbox
  */
@@ -1209,6 +1348,21 @@ type GetSandboxResponses = {
   200: SandboxResponse;
 };
 type GetSandboxResponse = GetSandboxResponses[keyof GetSandboxResponses];
+type UpdateSandboxData = {
+  body?: UpdateSandboxRequestWritable;
+  path: {
+    /**
+             * The human-readable ID of the workspace
+             */
+    workspace_domain: string;
+    /**
+             * The ID of the sandbox
+             */
+    id: string;
+  };
+  query?: never;
+  url: "/workspaces/{workspace_domain}/sandboxes/{id}";
+};
 type GetSandboxAppLogsByIdData = {
   body?: never;
   path: {
@@ -1275,6 +1429,21 @@ type StopSandboxAppData = {
   query?: never;
   url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/apps/{app_id}/stop";
 };
+type GetSandboxCommandsData = {
+  body?: never;
+  path: {
+    /**
+             * The human-readable ID of the workspace
+             */
+    workspace_domain: string;
+    /**
+             * The ID of the sandbox
+             */
+    sandbox_id: string;
+  };
+  query?: never;
+  url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/commands";
+};
 type ExecuteSandboxCommandData = {
   body?: ExecuteSandboxCommandRequest;
   path: {
@@ -1456,6 +1625,74 @@ type RestartSandboxData = {
   query?: never;
   url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/restart";
 };
+type GetSandboxSnapshotsData = {
+  body?: never;
+  path: {
+    /**
+             * The human-readable ID of the workspace
+             */
+    workspace_domain: string;
+    /**
+             * The ID of the sandbox
+             */
+    sandbox_id: string;
+  };
+  query?: never;
+  url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/snapshots";
+};
+type AddSandboxSnapshotData = {
+  body?: AddSnapshotRequest;
+  path: {
+    /**
+             * The human-readable ID of the workspace
+             */
+    workspace_domain: string;
+    /**
+             * The ID of the sandbox
+             */
+    sandbox_id: string;
+  };
+  query?: never;
+  url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/snapshots";
+};
+type DeleteSandboxSnapshotData = {
+  body?: never;
+  path: {
+    /**
+             * The human-readable ID of the workspace
+             */
+    workspace_domain: string;
+    /**
+             * The ID of the sandbox
+             */
+    sandbox_id: string;
+    /**
+             * The ID of the snapshot
+             */
+    id: string;
+  };
+  query?: never;
+  url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/snapshots/{id}";
+};
+type GetSandboxSnapshotData = {
+  body?: never;
+  path: {
+    /**
+             * The human-readable ID of the workspace
+             */
+    workspace_domain: string;
+    /**
+             * The ID of the sandbox
+             */
+    sandbox_id: string;
+    /**
+             * The ID of the snapshot
+             */
+    id: string;
+  };
+  query?: never;
+  url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/snapshots/{id}";
+};
 type StartSandboxData = {
   body?: never;
   path: {
@@ -1486,6 +1723,37 @@ type StopSandboxData = {
   query?: never;
   url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/stop";
 };
+type GetProjectSnapshotsData = {
+  body?: never;
+  path: {
+    /**
+             * The human-readable ID of the workspace
+             */
+    workspace_domain: string;
+  };
+  query: {
+    /**
+             * The human-readable ID of the project to filter sandboxes
+             */
+    project_name: string;
+  };
+  url: "/workspaces/{workspace_domain}/sandboxes/snapshots";
+};
+type DeleteSnapshotData = {
+  body?: never;
+  path: {
+    /**
+             * The human-readable ID of the workspace
+             */
+    workspace_domain: string;
+    /**
+             * The ID of the snapshot
+             */
+    id: string;
+  };
+  query?: never;
+  url: "/workspaces/{workspace_domain}/sandboxes/snapshots/{id}";
+};
 //#endregion
 //#region src/core/http-client.d.ts
 /** Configuration options for creating an HttpClient instance */
@@ -1533,6 +1801,8 @@ declare class HttpClient {
   post<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>;
   /** Perform a DELETE request */
   delete<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+  /** Perform a PATCH request with optional body data */
+  patch<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>;
   /** Set the Bearer token for authenticated requests */
   setAuthToken(token: string): void;
 }
@@ -1584,12 +1854,31 @@ declare class BuddyApiClient extends HttpClient {
   readonly project_name: BuddyApiConfig["project_name"];
   /** Create a new sandbox */
   addSandbox<const Data$1 extends AddSandboxData>(data: ClientData<Data$1>): Promise<SandboxResponse>;
+  /** Update an existing sandbox's configuration (timeout, apps, endpoints, etc.) */
+  updateSandbox<const Data$1 extends UpdateSandboxData>(data: ClientData<Data$1>): Promise<SandboxResponse>;
+  /** List snapshots for a sandbox */
+  getSandboxSnapshots<const Data$1 extends GetSandboxSnapshotsData>(data: ClientData<Data$1>): Promise<SnapshotsView>;
+  /** List all snapshots in the project (across all sandboxes, including orphans) */
+  getProjectSnapshots<const Data$1 extends GetProjectSnapshotsData>(data: ClientData<Data$1>): Promise<SnapshotsView>;
+  /** Create a snapshot of a sandbox */
+  addSandboxSnapshot<const Data$1 extends AddSandboxSnapshotData>(data: ClientData<Data$1>): Promise<SnapshotView>;
+  /** Get a single sandbox snapshot by ID */
+  getSandboxSnapshot<const Data$1 extends GetSandboxSnapshotData>(data: ClientData<Data$1>): Promise<SnapshotView>;
+  /** Delete a sandbox snapshot by ID */
+  deleteSandboxSnapshot<const Data$1 extends DeleteSandboxSnapshotData>(data: ClientData<Data$1>): Promise<void>;
+  /**
+       * Delete a snapshot by ID at the project level (works for snapshots whose
+       * parent sandbox has been deleted).
+       */
+  deleteSnapshot<const Data$1 extends DeleteSnapshotData>(data: ClientData<Data$1>): Promise<void>;
   /** Get a specific sandbox by its ID */
   getSandboxById<const Data$1 extends GetSandboxData>(data: ClientData<Data$1>): Promise<SandboxResponse>;
   /** Get a specific sandbox by its ID */
   getIdentifiers<const Data$1 extends GetIdentifiersData>(data: ClientData<Data$1>): Promise<IdsView>;
   /** Execute a command in a sandbox */
   executeCommand<const Data$1 extends ExecuteSandboxCommandData>(data: ClientData<Data$1>): Promise<SandboxCommandView>;
+  /** List all command executions in a sandbox (history) */
+  getSandboxCommands<const Data$1 extends GetSandboxCommandsData>(data: ClientData<Data$1>): Promise<SandboxCommandsView>;
   /** Get a specific command execution details */
   getCommandDetails<const Data$1 extends GetSandboxCommandData>(data: ClientData<Data$1>): Promise<SandboxCommandView>;
   /** Terminate a running command in a sandbox */
@@ -1799,6 +2088,41 @@ declare class FileSystem {
   uploadFile(source: Buffer | string, remotePath: string): Promise<void>;
 }
 //#endregion
+//#region src/entity/snapshot.d.ts
+declare class Snapshot {
+  #private;
+  /** The raw snapshot response data from the API */
+  get data(): SnapshotView;
+  /** The snapshot ID, throws if not present */
+  get id(): NonNullable<SnapshotView["id"]>;
+  /** ID of the sandbox this snapshot belongs to */
+  get sandboxId(): string;
+  /**
+       * Refresh the snapshot data from the API
+       * Updates the internal state with the latest snapshot information
+       */
+  refresh(): Promise<void>;
+  /**
+       * Wait until the snapshot reaches CREATED state.
+       *
+       * `sandbox.createSnapshot()` returns immediately with `status: "CREATING"`.
+       * The snapshot cannot be restored until it transitions to `"CREATED"`.
+       *
+       * @param pollIntervalMs - How often to check the status (default: 2000ms (2s))
+       * @param maxWaitMs - Maximum time to wait before timing out (default: 180000ms (180s))
+       */
+  waitUntilReady(pollIntervalMs?: number, maxWaitMs?: number): Promise<void>;
+  /**
+       * Delete this snapshot permanently
+       */
+  delete(): Promise<void>;
+  private constructor();
+  /**
+       * @internal Factory used by the Sandbox class to construct Snapshot instances.
+       */
+  static _build(data: SnapshotView, client: BuddyApiClient, sandboxId: string): Snapshot;
+}
+//#endregion
 //#region src/entity/sandbox.d.ts
 /**
  * Configuration for creating a new sandbox
@@ -1821,6 +2145,20 @@ interface ListSandboxesConfig {
   /** Optional connection configuration to override defaults */
   connection?: ConnectionConfig;
 }
+/**
+ * Configuration for creating a sandbox from an existing snapshot
+ */
+interface CreateFromSnapshotConfig extends Partial<Omit<CreateFromSnapshotRequestWritable, "snapshot_id">> {
+  /** Optional connection configuration to override defaults */
+  connection?: ConnectionConfig;
+}
+/**
+ * Configuration for cloning an existing sandbox
+ */
+interface CloneSandboxConfig extends Partial<Omit<CloneSandboxRequest, "source_sandbox_id">> {
+  /** Optional connection configuration to override defaults */
+  connection?: ConnectionConfig;
+}
 /**
  * Options for running a command in the sandbox
  */
@@ -1849,6 +2187,25 @@ declare class Sandbox {
        * @returns A ready-to-use Sandbox instance
        */
   static create(config?: CreateSandboxConfig): Promise<Sandbox>;
+  /**
+       * Create a new sandbox from an existing snapshot
+       *
+       * @param snapshotId - ID of the snapshot to create from
+       * @param config - Optional sandbox configuration overrides (name, identifier, …)
+       * @returns A ready-to-use Sandbox instance restored from the snapshot
+       */
+  static createFromSnapshot(snapshotId: string, config?: CreateFromSnapshotConfig): Promise<Sandbox>;
+  /**
+       * Clone an existing sandbox by ID into a new one.
+       *
+       * Differs from `createFromSnapshot` in that it copies the current state of
+       * a live sandbox directly, without going through a snapshot.
+       *
+       * @param sourceSandboxId - ID of the sandbox to clone
+       * @param config - Optional sandbox configuration overrides (name, identifier)
+       * @returns A ready-to-use Sandbox instance cloned from the source
+       */
+  static clone(sourceSandboxId: string, config?: CloneSandboxConfig): Promise<Sandbox>;
   /**
        * Get an existing sandbox by its identifier
        * @param identifier - Identifier of the sandbox to retrieve
@@ -1874,11 +2231,93 @@ declare class Sandbox {
        * @returns Array of simplified sandbox objects
        */
   static list(config?: ListSandboxesConfig): Promise<SandboxIdView[]>;
+  /**
+       * Get a single snapshot by its sandbox + snapshot ID without first fetching
+       * the parent sandbox. Useful when you already have both IDs (e.g. from a
+       * persisted reference).
+       *
+       * @param sandboxId - ID of the sandbox the snapshot belongs to
+       * @param snapshotId - ID of the snapshot to fetch
+       * @param config - Optional configuration including connection settings
+       */
+  static getSnapshotById(sandboxId: string, snapshotId: NonNullable<SnapshotView["id"]>, config?: GetSandboxConfig): Promise<Snapshot>;
   /**
        * Execute a command in the sandbox
        * @returns Command instance (call wait() for blocking execution)
        */
   runCommand(options: RunCommandOptions): Promise<Command>;
+  /**
+       * List all command executions in this sandbox (history).
+       *
+       * Returns one `Command` instance per past execution. Useful for inspecting
+       * previous runs, fetching their logs, or killing still-running detached
+       * commands.
+       */
+  listCommands(): Promise<Command[]>;
+  /**
+       * Update the sandbox configuration in place
+       *
+       * Accepts a partial update of any mutable sandbox field (`timeout`, `apps`,
+       * `endpoints`, `variables`, `tags`, `resources`, …). Updates the internal
+       * state with the API's response.
+       *
+       * @remarks Changing `first_boot_commands` leaves the sandbox in
+       * `setup_status: STALE` — the new commands only apply on first boot, so
+       * the sandbox must be recreated to take effect.
+       */
+  update(config: Partial<UpdateSandboxRequestWritable>): Promise<void>;
+  /**
+       * Create a snapshot of the current sandbox
+       *
+       * Returns immediately with a snapshot whose `status` is `"CREATING"`. Call
+       * `snapshot.waitUntilReady()` (or `sandbox.waitForSnapshotReady(snapshot.id)`)
+       * before restoring from it.
+       *
+       * @param config - Optional snapshot configuration (name, description, …)
+       */
+  createSnapshot(config?: AddSnapshotRequest): Promise<Snapshot>;
+  /**
+       * List all snapshots in the project across every sandbox, including
+       * snapshots whose parent sandbox has been deleted.
+       *
+       * Use `Sandbox.createFromSnapshot(snapshot.id, …)` to provision a new
+       * sandbox from any item in the list.
+       *
+       * @param config - Optional configuration including connection settings
+       */
+  static listSnapshots(config?: ListSandboxesConfig): Promise<ShortSnapshotView[]>;
+  /**
+       * List snapshots of this sandbox
+       */
+  listSnapshots(): Promise<Snapshot[]>;
+  /**
+       * Get a single snapshot of this sandbox by ID
+       */
+  getSnapshot(snapshotId: NonNullable<SnapshotView["id"]>): Promise<Snapshot>;
+  /**
+       * Delete a snapshot by ID without needing the parent sandbox. Useful for
+       * cleaning up snapshots whose parent sandbox has already been deleted.
+       *
+       * @param snapshotId - ID of the snapshot to delete
+       * @param config - Optional configuration including connection settings
+       */
+  static deleteSnapshot(snapshotId: NonNullable<SnapshotView["id"]>, config?: GetSandboxConfig): Promise<void>;
+  /**
+       * Delete a snapshot of this sandbox by ID
+       */
+  deleteSnapshot(snapshotId: NonNullable<SnapshotView["id"]>): Promise<void>;
+  /**
+       * Wait until a snapshot reaches CREATED state.
+       *
+       * `createSnapshot()` returns immediately with `status: "CREATING"`. The
+       * snapshot cannot be used as input to `Sandbox.createFromSnapshot()` until
+       * it transitions to `"CREATED"`. Use this method to block until it does.
+       *
+       * @param snapshotId - ID of the snapshot to wait for
+       * @param pollIntervalMs - How often to check the status (default: 2000ms (2s))
+       * @param maxWaitMs - Maximum time to wait before timing out (default: 180000ms (180s))
+       */
+  waitForSnapshotReady(snapshotId: NonNullable<SnapshotView["id"]>, pollIntervalMs?: number, maxWaitMs?: number): Promise<void>;
   /**
        * Delete the sandbox permanently
        */
@@ -1971,4 +2410,4 @@ declare class BuddySDKError extends Error {
   });
 }
 //#endregion
-export { API_URLS, BuddyApiClient, BuddySDKError, Command, type ConnectionConfig, type CreateSandboxConfig, ERROR_CODES, type ErrorCode, type FileInfo, FileSystem, type GetFileSystemConfig, type GetSandboxConfig, type ListSandboxesConfig, REGIONS, type Region, Sandbox, type SandboxAppView, type SandboxIdView };
+export { API_URLS, type AddSnapshotRequest, BuddyApiClient, BuddySDKError, type CloneSandboxConfig, type CloneSandboxRequest, Command, type ConnectionConfig, type CreateFromSnapshotConfig, type CreateSandboxConfig, ERROR_CODES, type ErrorCode, type FileInfo, FileSystem, type GetFileSystemConfig, type GetSandboxConfig, type ListSandboxesConfig, REGIONS, type Region, Sandbox, type SandboxAppView, type SandboxIdView, type ShortSnapshotView, Snapshot, type SnapshotView };