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

package/dist/index.mjs

@@ -21,6 +21,10 @@ const getSandboxResponseTransformer = async (data) => {
 	data = sandboxResponseSchemaResponseTransformer(data);
 	return data;
 };
+const updateSandboxResponseTransformer = async (data) => {
+	data = sandboxResponseSchemaResponseTransformer(data);
+	return data;
+};
 const startSandboxAppResponseTransformer = async (data) => {
 	data = sandboxResponseSchemaResponseTransformer(data);
 	return data;
@@ -34,6 +38,14 @@ const sandboxCommandViewSchemaResponseTransformer = (data) => {
 	if (data.finish_date) data.finish_date = new Date(data.finish_date);
 	return data;
 };
+const sandboxCommandsViewSchemaResponseTransformer = (data) => {
+	if (data.commands) data.commands = data.commands.map((item) => sandboxCommandViewSchemaResponseTransformer(item));
+	return data;
+};
+const getSandboxCommandsResponseTransformer = async (data) => {
+	data = sandboxCommandsViewSchemaResponseTransformer(data);
+	return data;
+};
 const executeSandboxCommandResponseTransformer = async (data) => {
 	data = sandboxCommandViewSchemaResponseTransformer(data);
 	return data;
@@ -70,6 +82,30 @@ const restartSandboxResponseTransformer = async (data) => {
 	data = sandboxResponseSchemaResponseTransformer(data);
 	return data;
 };
+const shortSnapshotViewSchemaResponseTransformer = (data) => {
+	if (data.create_date) data.create_date = new Date(data.create_date);
+	return data;
+};
+const snapshotsViewSchemaResponseTransformer = (data) => {
+	if (data.snapshots) data.snapshots = data.snapshots.map((item) => shortSnapshotViewSchemaResponseTransformer(item));
+	return data;
+};
+const getSandboxSnapshotsResponseTransformer = async (data) => {
+	data = snapshotsViewSchemaResponseTransformer(data);
+	return data;
+};
+const snapshotViewSchemaResponseTransformer = (data) => {
+	if (data.create_date) data.create_date = new Date(data.create_date);
+	return data;
+};
+const addSandboxSnapshotResponseTransformer = async (data) => {
+	data = snapshotViewSchemaResponseTransformer(data);
+	return data;
+};
+const getSandboxSnapshotResponseTransformer = async (data) => {
+	data = snapshotViewSchemaResponseTransformer(data);
+	return data;
+};
 const startSandboxResponseTransformer = async (data) => {
 	data = sandboxResponseSchemaResponseTransformer(data);
 	return data;
@@ -78,6 +114,10 @@ const stopSandboxResponseTransformer = async (data) => {
 	data = sandboxResponseSchemaResponseTransformer(data);
 	return data;
 };
+const getProjectSnapshotsResponseTransformer = async (data) => {
+	data = snapshotsViewSchemaResponseTransformer(data);
+	return data;
+};
 
 //#endregion
 //#region src/api/openapi/zod.gen.ts
@@ -317,94 +357,6 @@ const zPipelinePropertyView = z.object({
 	value: z.string().optional()
 });
 /**
-* MSSQL authentication credentials
-*/
-const zMssqlAuthView = z.object({
-	method: z.enum(["PASSWORD"]).optional(),
-	username: z.string(),
-	password: z.string()
-});
-/**
-* MongoDB authentication credentials
-*/
-const zMongoAuthView = z.object({
-	method: z.enum(["PASSWORD"]).optional(),
-	username: z.string(),
-	password: z.string()
-});
-/**
-* PostgreSQL authentication credentials
-*/
-const zPostgresqlAuthView = z.object({
-	method: z.enum(["PASSWORD"]).optional(),
-	username: z.string(),
-	password: z.string()
-});
-/**
-* MySQL authentication credentials
-*/
-const zMysqlAuthView = z.object({
-	method: z.enum(["PASSWORD"]).optional(),
-	username: z.string(),
-	password: z.string()
-});
-/**
-* Define proxy servers' authentication method using the following parameters
-*/
-const zSshAuthView = z.object({
-	method: z.enum([
-		"PASSWORD",
-		"SSH_KEY",
-		"ASSETS_KEY",
-		"PROXY_CREDENTIALS",
-		"PROXY_KEY"
-	]),
-	username: z.string().optional(),
-	password: z.string().optional(),
-	asset: z.string().optional(),
-	passphrase: z.string().optional(),
-	key: z.string().optional(),
-	key_path: z.string().optional()
-});
-/**
-* Kubernetes cluster authentication method
-*/
-const zK8sAuthView = z.object({
-	method: z.enum([
-		"PASS",
-		"CERT",
-		"TOKEN"
-	]),
-	username: z.string().optional(),
-	password: z.string().optional(),
-	certificate_authority: z.string().optional(),
-	client_certificate: z.string().optional(),
-	client_key: z.string().optional(),
-	token: z.string().optional()
-});
-/**
-* Authentication details
-*/
-const zGitAuthView = z.object({
-	method: z.enum([
-		"HTTP",
-		"SSH_KEY",
-		"ASSETS_KEY",
-		"CURRENT"
-	]),
-	username: z.string().optional(),
-	password: z.string().optional(),
-	asset: z.string().optional(),
-	key: z.string().optional()
-});
-/**
-* Authentication details
-*/
-const zFtpAuthView = z.object({
-	username: z.string(),
-	password: z.string()
-});
-/**
 * Defines how the target can be used (as deployment target, proxy, or both)
 */
 const zUseAsView = z.object({
@@ -516,6 +468,94 @@ const zShortProjectView = z.object({
 	access: z.enum(["PRIVATE", "PUBLIC"]).optional(),
 	create_date: z.iso.datetime().optional()
 });
+/**
+* MSSQL authentication credentials
+*/
+const zMssqlAuthView = z.object({
+	method: z.enum(["PASSWORD"]).optional(),
+	username: z.string(),
+	password: z.string()
+});
+/**
+* MongoDB authentication credentials
+*/
+const zMongoAuthView = z.object({
+	method: z.enum(["PASSWORD"]).optional(),
+	username: z.string(),
+	password: z.string()
+});
+/**
+* PostgreSQL authentication credentials
+*/
+const zPostgresqlAuthView = z.object({
+	method: z.enum(["PASSWORD"]).optional(),
+	username: z.string(),
+	password: z.string()
+});
+/**
+* MySQL authentication credentials
+*/
+const zMysqlAuthView = z.object({
+	method: z.enum(["PASSWORD"]).optional(),
+	username: z.string(),
+	password: z.string()
+});
+/**
+* Define proxy servers' authentication method using the following parameters
+*/
+const zSshAuthView = z.object({
+	method: z.enum([
+		"PASSWORD",
+		"SSH_KEY",
+		"ASSETS_KEY",
+		"PROXY_CREDENTIALS",
+		"PROXY_KEY"
+	]),
+	username: z.string().optional(),
+	password: z.string().optional(),
+	asset: z.string().optional(),
+	passphrase: z.string().optional(),
+	key: z.string().optional(),
+	key_path: z.string().optional()
+});
+/**
+* Kubernetes cluster authentication method
+*/
+const zK8sAuthView = z.object({
+	method: z.enum([
+		"PASS",
+		"CERT",
+		"TOKEN"
+	]),
+	username: z.string().optional(),
+	password: z.string().optional(),
+	certificate_authority: z.string().optional(),
+	client_certificate: z.string().optional(),
+	client_key: z.string().optional(),
+	token: z.string().optional()
+});
+/**
+* Authentication details
+*/
+const zGitAuthView = z.object({
+	method: z.enum([
+		"HTTP",
+		"SSH_KEY",
+		"ASSETS_KEY",
+		"CURRENT"
+	]),
+	username: z.string().optional(),
+	password: z.string().optional(),
+	asset: z.string().optional(),
+	key: z.string().optional()
+});
+/**
+* Authentication details
+*/
+const zFtpAuthView = z.object({
+	username: z.string(),
+	password: z.string()
+});
 const zIdsView = z.object({
 	url: z.string().readonly().optional(),
 	html_url: z.string().readonly().optional(),
@@ -2223,10 +2263,12 @@ const zGetSandboxPath = z.object({
 	id: z.string()
 });
 const zGetSandboxResponse = zSandboxResponse;
+const zUpdateSandboxBody = zUpdateSandboxRequestWritable;
 const zUpdateSandboxPath = z.object({
 	workspace_domain: z.string(),
 	id: z.string()
 });
+const zUpdateSandboxResponse = zSandboxResponse;
 const zGetSandboxAppLogsByIdPath = z.object({
 	workspace_domain: z.string(),
 	sandbox_id: z.string(),
@@ -2250,6 +2292,7 @@ const zGetSandboxCommandsPath = z.object({
 	workspace_domain: z.string(),
 	sandbox_id: z.string()
 });
+const zGetSandboxCommandsResponse = zSandboxCommandsView;
 const zExecuteSandboxCommandBody = zExecuteSandboxCommandRequest;
 const zExecuteSandboxCommandPath = z.object({
 	workspace_domain: z.string(),
@@ -2332,10 +2375,13 @@ const zGetSandboxSnapshotsPath = z.object({
 	workspace_domain: z.string(),
 	sandbox_id: z.string()
 });
+const zGetSandboxSnapshotsResponse = zSnapshotsView;
+const zAddSandboxSnapshotBody = zAddSnapshotRequest;
 const zAddSandboxSnapshotPath = z.object({
 	workspace_domain: z.string(),
 	sandbox_id: z.string()
 });
+const zAddSandboxSnapshotResponse = zSnapshotView;
 const zDeleteSandboxSnapshotPath = z.object({
 	workspace_domain: z.string(),
 	sandbox_id: z.string(),
@@ -2350,6 +2396,7 @@ const zGetSandboxSnapshotPath = z.object({
 	sandbox_id: z.string(),
 	id: z.string()
 });
+const zGetSandboxSnapshotResponse = zSnapshotView;
 const zStartSandboxPath = z.object({
 	workspace_domain: z.string(),
 	sandbox_id: z.string()
@@ -2370,6 +2417,7 @@ const zUpdateSandboxByYamlPath = z.object({
 });
 const zGetProjectSnapshotsPath = z.object({ workspace_domain: z.string() });
 const zGetProjectSnapshotsQuery = z.object({ project_name: z.string() });
+const zGetProjectSnapshotsResponse = zSnapshotsView;
 const zDeleteSnapshotPath = z.object({
 	workspace_domain: z.string(),
 	id: z.string()
@@ -2396,7 +2444,7 @@ const zUpdateIntegrationPath = z.object({
 //#endregion
 //#region package.json
 var name = "@buddy-works/sandbox-sdk";
-var version = "0.1.6-rc.0";
+var version = "0.1.6";
 
 //#endregion
 //#region src/utils/environment.ts
@@ -2706,6 +2754,10 @@ var HttpClient = class {
 	async delete(url, config) {
 		return this.#request("DELETE", url, void 0, config);
 	}
+	/** Perform a PATCH request with optional body data */
+	async patch(url, data, config) {
+		return this.#request("PATCH", url, data ?? {}, config);
+	}
 	/** Set the Bearer token for authenticated requests */
 	setAuthToken(token) {
 		this.#authToken = token;
@@ -2777,6 +2829,9 @@ var BuddyApiClient = class extends HttpClient {
 			case "DELETE":
 				request = this.delete(parameterizedUrl, requestConfig);
 				break;
+			case "PATCH":
+				request = this.patch(parameterizedUrl, validatedBody ?? {}, requestConfig);
+				break;
 		}
 		const response = await request;
 		return await this.#parseResponse(responseSchema, response);
@@ -2793,6 +2848,94 @@ var BuddyApiClient = class extends HttpClient {
 			responseSchema: zAddSandboxResponse.transform(addSandboxResponseTransformer)
 		});
 	}
+	/** Update an existing sandbox's configuration (timeout, apps, endpoints, etc.) */
+	async updateSandbox(data) {
+		return this.#requestWithValidation({
+			method: "PATCH",
+			data,
+			url: "/workspaces/{workspace_domain}/sandboxes/{id}",
+			bodySchema: zUpdateSandboxBody,
+			pathSchema: zUpdateSandboxPath,
+			responseSchema: zUpdateSandboxResponse.transform(updateSandboxResponseTransformer)
+		});
+	}
+	/** List snapshots for a sandbox */
+	async getSandboxSnapshots(data) {
+		return this.#requestWithValidation({
+			method: "GET",
+			data,
+			url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/snapshots",
+			pathSchema: zGetSandboxSnapshotsPath,
+			responseSchema: zGetSandboxSnapshotsResponse.transform(getSandboxSnapshotsResponseTransformer)
+		});
+	}
+	/** List all snapshots in the project (across all sandboxes, including orphans) */
+	async getProjectSnapshots(data) {
+		return this.#requestWithValidation({
+			method: "GET",
+			data,
+			url: "/workspaces/{workspace_domain}/sandboxes/snapshots",
+			pathSchema: zGetProjectSnapshotsPath,
+			querySchema: zGetProjectSnapshotsQuery,
+			responseSchema: zGetProjectSnapshotsResponse.transform(getProjectSnapshotsResponseTransformer)
+		});
+	}
+	/** Create a snapshot of a sandbox */
+	async addSandboxSnapshot(data) {
+		return this.#requestWithValidation({
+			method: "POST",
+			data,
+			url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/snapshots",
+			bodySchema: zAddSandboxSnapshotBody,
+			pathSchema: zAddSandboxSnapshotPath,
+			responseSchema: zAddSandboxSnapshotResponse.transform(addSandboxSnapshotResponseTransformer)
+		});
+	}
+	/** Get a single sandbox snapshot by ID */
+	async getSandboxSnapshot(data) {
+		return this.#requestWithValidation({
+			method: "GET",
+			data,
+			url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/snapshots/{id}",
+			pathSchema: zGetSandboxSnapshotPath,
+			responseSchema: zGetSandboxSnapshotResponse.transform(getSandboxSnapshotResponseTransformer)
+		});
+	}
+	/** Delete a sandbox snapshot by ID */
+	async deleteSandboxSnapshot(data) {
+		try {
+			return await this.#requestWithValidation({
+				method: "DELETE",
+				data,
+				url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/snapshots/{id}",
+				pathSchema: zDeleteSandboxSnapshotPath,
+				responseSchema: zDeleteSandboxSnapshotResponse,
+				skipRetry: true
+			});
+		} catch (error) {
+			if (error instanceof HttpError && error.status === 404) return;
+			throw error;
+		}
+	}
+	/**
+	* Delete a snapshot by ID at the project level (works for snapshots whose
+	* parent sandbox has been deleted).
+	*/
+	async deleteSnapshot(data) {
+		try {
+			return await this.#requestWithValidation({
+				method: "DELETE",
+				data,
+				url: "/workspaces/{workspace_domain}/sandboxes/snapshots/{id}",
+				pathSchema: zDeleteSnapshotPath,
+				responseSchema: zDeleteSnapshotResponse,
+				skipRetry: true
+			});
+		} catch (error) {
+			if (error instanceof HttpError && error.status === 404) return;
+			throw error;
+		}
+	}
 	/** Get a specific sandbox by its ID */
 	async getSandboxById(data) {
 		return this.#requestWithValidation({
@@ -2825,6 +2968,16 @@ var BuddyApiClient = class extends HttpClient {
 			responseSchema: zExecuteSandboxCommandResponse.transform(executeSandboxCommandResponseTransformer)
 		});
 	}
+	/** List all command executions in a sandbox (history) */
+	async getSandboxCommands(data) {
+		return this.#requestWithValidation({
+			method: "GET",
+			data,
+			url: "/workspaces/{workspace_domain}/sandboxes/{sandbox_id}/commands",
+			pathSchema: zGetSandboxCommandsPath,
+			responseSchema: zGetSandboxCommandsResponse.transform(getSandboxCommandsResponseTransformer)
+		});
+	}
 	/** Get a specific command execution details */
 	async getCommandDetails(data) {
 		return this.#requestWithValidation({
@@ -3461,6 +3614,86 @@ var FileSystem = class FileSystem {
 	}
 };
 
+//#endregion
+//#region src/entity/snapshot.ts
+const PRIVATE_CONSTRUCTOR_KEY$1 = Symbol("SnapshotConstructor");
+const INITIALIZE_INSTRUCTIONS$1 = "Snapshots are obtained via sandbox.createSnapshot(), sandbox.listSnapshots(), sandbox.getSnapshot(id), or Sandbox.getSnapshotById(sandboxId, snapshotId).";
+var Snapshot = class Snapshot {
+	#data;
+	#client;
+	#sandboxId;
+	/** The raw snapshot response data from the API */
+	get data() {
+		return this.#data;
+	}
+	/** The snapshot ID, throws if not present */
+	get id() {
+		const id = this.#data.id;
+		if (!id) throw new Error(`Snapshot ID is missing. ${INITIALIZE_INSTRUCTIONS$1}`);
+		return id;
+	}
+	/** ID of the sandbox this snapshot belongs to */
+	get sandboxId() {
+		return this.#sandboxId;
+	}
+	/**
+	* Refresh the snapshot data from the API
+	* Updates the internal state with the latest snapshot information
+	*/
+	async refresh() {
+		return withErrorHandler("Failed to refresh snapshot", async () => {
+			this.#data = await this.#client.getSandboxSnapshot({ path: {
+				sandbox_id: this.#sandboxId,
+				id: this.id
+			} });
+		});
+	}
+	/**
+	* 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))
+	*/
+	async waitUntilReady(pollIntervalMs = 2e3, maxWaitMs = 18e4) {
+		return withErrorHandler("Snapshot not ready", async () => {
+			const startTime = Date.now();
+			while (true) {
+				await this.refresh();
+				if (this.#data.status === "CREATED") return;
+				if (this.#data.status === "FAILED") throw new Error(`Snapshot ${this.id} failed. Status: ${this.#data.status}`);
+				if (Date.now() - startTime > maxWaitMs) throw new Error(`Timeout waiting for snapshot ${this.id} to be CREATED. Current: ${this.#data.status}`);
+				await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+			}
+		});
+	}
+	/**
+	* Delete this snapshot permanently
+	*/
+	async delete() {
+		return withErrorHandler("Failed to delete snapshot", async () => {
+			await this.#client.deleteSandboxSnapshot({ path: {
+				sandbox_id: this.#sandboxId,
+				id: this.id
+			} });
+		});
+	}
+	constructor(data, client, sandboxId, constructorKey) {
+		if (constructorKey !== PRIVATE_CONSTRUCTOR_KEY$1) throw new Error(`Cannot construct Snapshot directly. ${INITIALIZE_INSTRUCTIONS$1}`);
+		this.#data = data;
+		this.#client = client;
+		this.#sandboxId = sandboxId;
+	}
+	/**
+	* @internal Factory used by the Sandbox class to construct Snapshot instances.
+	*/
+	static _build(data, client, sandboxId) {
+		return new Snapshot(data, client, sandboxId, PRIVATE_CONSTRUCTOR_KEY$1);
+	}
+};
+
 //#endregion
 //#region src/entity/sandbox.ts
 const PRIVATE_CONSTRUCTOR_KEY = Symbol("SandboxConstructor");
@@ -3489,6 +3722,19 @@ var Sandbox = class Sandbox {
 		return this.#fs;
 	}
 	/**
+	* Create a Sandbox instance from an `addSandbox` response and wait for it
+	* to reach a RUNNING state. Shared between `create` and `createFromSnapshot`.
+	*/
+	static async #finalizeNewSandbox(sandboxResponse, client) {
+		const sandbox = new Sandbox(sandboxResponse, client, PRIVATE_CONSTRUCTOR_KEY);
+		logger_default.debug(`Waiting for sandbox ${sandbox.data.id} to be ready...`);
+		await sandbox.waitUntilReady();
+		logger_default.debug(`Sandbox ${sandbox.data.id} is ready (Setup status: ${sandbox.data.setup_status})`);
+		await sandbox.waitUntilRunning();
+		logger_default.debug(`Sandbox ${sandbox.data.id} is now running. Status: ${sandbox.data.status}`);
+		return sandbox;
+	}
+	/**
 	* Create a new sandbox
 	* @param config - Sandbox configuration including identifier, name, os, and optional connection settings
 	* @returns A ready-to-use Sandbox instance
@@ -3499,17 +3745,57 @@ var Sandbox = class Sandbox {
 			const client = createClient(connection);
 			const requestBody = {
 				name: `Sandbox ${(/* @__PURE__ */ new Date()).toISOString()}`,
-				identifier: config?.identifier || `sandbox_${String(Date.now())}`,
+				identifier: `sandbox_${String(Date.now())}`,
 				os: "ubuntu:24.04",
 				...sandboxConfig
 			};
-			const sandbox = new Sandbox(await client.addSandbox({ body: requestBody }), client, PRIVATE_CONSTRUCTOR_KEY);
-			logger_default.debug(`Waiting for sandbox ${sandbox.data.id} to be ready...`);
-			await sandbox.waitUntilReady();
-			logger_default.debug(`Sandbox ${sandbox.data.id} is ready (Setup status: ${sandbox.data.setup_status})`);
-			await sandbox.waitUntilRunning();
-			logger_default.debug(`Sandbox ${sandbox.data.id} is now running. Status: ${sandbox.data.status}`);
-			return sandbox;
+			const sandboxResponse = await client.addSandbox({ body: requestBody });
+			return Sandbox.#finalizeNewSandbox(sandboxResponse, client);
+		});
+	}
+	/**
+	* 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 async createFromSnapshot(snapshotId, config) {
+		return withErrorHandler("Failed to create sandbox from snapshot", async () => {
+			const { connection, ...snapshotConfig } = config ?? {};
+			const client = createClient(connection);
+			const requestBody = {
+				snapshot_id: snapshotId,
+				name: `Sandbox ${(/* @__PURE__ */ new Date()).toISOString()}`,
+				identifier: `sandbox_${String(Date.now())}`,
+				...snapshotConfig
+			};
+			const sandboxResponse = await client.addSandbox({ body: requestBody });
+			return Sandbox.#finalizeNewSandbox(sandboxResponse, client);
+		});
+	}
+	/**
+	* 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 async clone(sourceSandboxId, config) {
+		return withErrorHandler("Failed to clone sandbox", async () => {
+			const { connection, ...cloneConfig } = config ?? {};
+			const client = createClient(connection);
+			const requestBody = {
+				source_sandbox_id: sourceSandboxId,
+				name: `Sandbox ${(/* @__PURE__ */ new Date()).toISOString()}`,
+				identifier: `sandbox_${String(Date.now())}`,
+				...cloneConfig
+			};
+			const sandboxResponse = await client.addSandbox({ body: requestBody });
+			return Sandbox.#finalizeNewSandbox(sandboxResponse, client);
 		});
 	}
 	/**
@@ -3528,10 +3814,9 @@ var Sandbox = class Sandbox {
 					project: client.project_name,
 					sandbox: identifier
 				} })).sandbox_id;
-			} catch {}
-			if (!sandboxId) try {
-				sandboxId = (await client.getSandboxes({}))?.sandboxes?.find((s) => s.identifier === identifier)?.id;
-			} catch {}
+			} catch (error) {
+				if (!(error instanceof HttpError) || error.status !== 404) throw error;
+			}
 			if (!sandboxId) throw new Error(`Sandbox with identifier '${identifier}' not found`);
 			const sandboxResponse = await client.getSandboxById({ path: { id: sandboxId } });
 			if (!sandboxResponse) throw new Error(`Sandbox with ID '${sandboxId}' not found`);
@@ -3570,6 +3855,26 @@ var Sandbox = class Sandbox {
 		});
 	}
 	/**
+	* 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 async getSnapshotById(sandboxId, snapshotId, config) {
+		return withErrorHandler("Failed to get snapshot", async () => {
+			const { connection } = config ?? {};
+			const client = createClient(connection);
+			const data = await client.getSandboxSnapshot({ path: {
+				sandbox_id: sandboxId,
+				id: snapshotId
+			} });
+			return Snapshot._build(data, client, sandboxId);
+		});
+	}
+	/**
 	* Execute a command in the sandbox
 	* @returns Command instance (call wait() for blocking execution)
 	*/
@@ -3601,6 +3906,138 @@ var Sandbox = class Sandbox {
 		});
 	}
 	/**
+	* 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.
+	*/
+	async listCommands() {
+		const sandboxId = this.initializedId;
+		return withErrorHandler("Failed to list commands", async () => {
+			return ((await this.#client.getSandboxCommands({ path: { sandbox_id: sandboxId } }))?.commands ?? []).map((commandResponse) => new Command({
+				commandResponse,
+				client: this.#client,
+				sandboxId
+			}));
+		});
+	}
+	/**
+	* 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.
+	*/
+	async update(config) {
+		const sandboxId = this.initializedId;
+		return withErrorHandler("Failed to update sandbox", async () => {
+			this.#sandboxData = await this.#client.updateSandbox({
+				body: config,
+				path: { id: sandboxId }
+			});
+		});
+	}
+	/**
+	* 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, …)
+	*/
+	async createSnapshot(config) {
+		const sandboxId = this.initializedId;
+		return withErrorHandler("Failed to create snapshot", async () => {
+			const data = await this.#client.addSandboxSnapshot({
+				body: config ?? {},
+				path: { sandbox_id: sandboxId }
+			});
+			return Snapshot._build(data, this.#client, sandboxId);
+		});
+	}
+	/**
+	* 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 async listSnapshots(config) {
+		return withErrorHandler("Failed to list project snapshots", async () => {
+			const { connection } = config ?? {};
+			return (await createClient(connection).getProjectSnapshots({}))?.snapshots ?? [];
+		});
+	}
+	/**
+	* List snapshots of this sandbox
+	*/
+	async listSnapshots() {
+		const sandboxId = this.initializedId;
+		return withErrorHandler("Failed to list snapshots", async () => {
+			return ((await this.#client.getSandboxSnapshots({ path: { sandbox_id: sandboxId } }))?.snapshots ?? []).map((data) => Snapshot._build(data, this.#client, sandboxId));
+		});
+	}
+	/**
+	* Get a single snapshot of this sandbox by ID
+	*/
+	async getSnapshot(snapshotId) {
+		const sandboxId = this.initializedId;
+		return withErrorHandler("Failed to get snapshot", async () => {
+			const data = await this.#client.getSandboxSnapshot({ path: {
+				sandbox_id: sandboxId,
+				id: snapshotId
+			} });
+			return Snapshot._build(data, this.#client, sandboxId);
+		});
+	}
+	/**
+	* 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 async deleteSnapshot(snapshotId, config) {
+		return withErrorHandler("Failed to delete snapshot", async () => {
+			const { connection } = config ?? {};
+			await createClient(connection).deleteSnapshot({ path: { id: snapshotId } });
+		});
+	}
+	/**
+	* Delete a snapshot of this sandbox by ID
+	*/
+	async deleteSnapshot(snapshotId) {
+		const sandboxId = this.initializedId;
+		return withErrorHandler("Failed to delete snapshot", async () => {
+			await this.#client.deleteSandboxSnapshot({ path: {
+				sandbox_id: sandboxId,
+				id: snapshotId
+			} });
+		});
+	}
+	/**
+	* 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))
+	*/
+	async waitForSnapshotReady(snapshotId, pollIntervalMs = 2e3, maxWaitMs = 18e4) {
+		await (await this.getSnapshot(snapshotId)).waitUntilReady(pollIntervalMs, maxWaitMs);
+	}
+	/**
 	* Delete the sandbox permanently
 	*/
 	async destroy() {
@@ -3786,4 +4223,4 @@ var Sandbox = class Sandbox {
 };
 
 //#endregion
-export { API_URLS, BuddyApiClient, BuddySDKError, Command, ERROR_CODES, FileSystem, REGIONS, Sandbox };
+export { API_URLS, BuddyApiClient, BuddySDKError, Command, ERROR_CODES, FileSystem, REGIONS, Sandbox, Snapshot };