@tarkahq/sdk 0.0.0-stage → 0.3.0

package/dist/cjs/resources/sandboxes.js

@@ -0,0 +1,732 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrganizationSandboxes = exports.SandboxTemplates = exports.SandboxTemplate = exports.Sandbox = exports.Executions = exports.Execution = exports.ResourceStateError = exports.ExecutionOperationError = exports.TemplateOperationError = exports.SandboxOperationError = exports.OperationError = void 0;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:timers/promises");
+const errors_js_1 = require("../errors.js");
+/**
+ * A transient failure with explicit recovery for the original operation.
+ *
+ * No mutation is automatically retried. `resume()` returns the same entity type as the interrupted operation.
+ * @typeParam T - The result type of the original operation.
+ */
+class OperationError extends errors_js_1.TarkaError {
+    /** Frozen recovery context containing available IDs and the original idempotency key, without the request payload. */
+    recovery;
+    #resume;
+    constructor(cause, recovery, resume) {
+        const error = (0, errors_js_1.normalizeError)(cause);
+        super(error.message, error.code, {
+            cause: error,
+            metadata: error.metadata,
+        });
+        this.name = "OperationError";
+        this.recovery = Object.freeze({ ...recovery });
+        this.#resume = resume;
+    }
+    /**
+     * Resume the original operation with a fresh timeout and cancellation scope.
+     *
+     * Known execution IDs are polled without resubmitting code. Unacknowledged mutations replay the preserved input and idempotency key; resume within the API's 24-hour deduplication window.
+     * Previous deadlines and aborted signals are discarded. Metadata and polling interval are retained unless overridden. A further transient failure carries another resumable error.
+     * @param options - New request/wait settings. Waits default to 60 seconds; submission-only operations use the client timeout unless overridden.
+     * @returns The original operation's entity type. Resuming `run()` waits for completion; resuming `execute()` only completes submission.
+     * @example
+     * if (error instanceof ExecutionOperationError) {
+     *   const execution = await error.resume({ timeoutMs: 60_000 });
+     * }
+     */
+    resume(options) {
+        return this.#resume(options);
+    }
+}
+exports.OperationError = OperationError;
+/** Interrupted sandbox creation or readiness wait. `resume()` returns a Sandbox handle. */
+class SandboxOperationError extends OperationError {
+    name = "SandboxOperationError";
+}
+exports.SandboxOperationError = SandboxOperationError;
+/** Interrupted template creation or readiness wait. `resume()` returns a SandboxTemplate handle. */
+class TemplateOperationError extends OperationError {
+    name = "TemplateOperationError";
+}
+exports.TemplateOperationError = TemplateOperationError;
+/** Interrupted code submission, run, or execution wait. `resume()` returns an Execution handle and preserves the original operation. */
+class ExecutionOperationError extends OperationError {
+    name = "ExecutionOperationError";
+}
+exports.ExecutionOperationError = ExecutionOperationError;
+function recoverable(error) {
+    if (error instanceof TypeError)
+        return false;
+    return [
+        "deadline_exceeded",
+        "cancelled",
+        "unavailable",
+        "aborted",
+        "unknown",
+        "internal",
+    ].includes((0, errors_js_1.normalizeError)(error).code);
+}
+function idempotencyKey(value) {
+    if (value === undefined)
+        return (0, node_crypto_1.randomUUID)();
+    (0, errors_js_1.requireText)(value, "idempotencyKey");
+    return value;
+}
+// Keep request context, but never inherit an expired deadline or aborted signal.
+function resumeOptions(previous, next) {
+    return {
+        metadata: previous?.metadata,
+        pollIntervalMs: previous?.pollIntervalMs,
+        ...next,
+    };
+}
+/** A resource cannot reach the requested state. Includes its snapshot in `info`; unknown statuses use `data_loss`, other terminal states use `failed_precondition`. */
+class ResourceStateError extends errors_js_1.TarkaError {
+    resource;
+    info;
+    constructor(
+    /** Kind of resource whose state prevents this operation. */
+    resource, 
+    /** Latest snapshot, including the status and available failure details. */
+    info) {
+        super(`${resource} ${info.id} is ${info.status}`, info.status === "unknown" ? "data_loss" : "failed_precondition");
+        this.resource = resource;
+        this.info = info;
+        this.name = "ResourceStateError";
+    }
+}
+exports.ResourceStateError = ResourceStateError;
+const sandboxStatuses = [
+    "unknown",
+    "starting",
+    "ready",
+    "busy",
+    "stopping",
+    "stopped",
+    "failed",
+    "expired",
+    "deleted",
+];
+const templateStatuses = [
+    "unknown",
+    "pending",
+    "building",
+    "ready",
+    "failed",
+    "deleting",
+    "deleted",
+];
+const executionStatuses = [
+    "unknown",
+    "running",
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+];
+const runtime = (value) => value === 1
+    ? "python"
+    : value === 2
+        ? "node"
+        : "unknown";
+const sandboxData = (value) => ({
+    ...value,
+    status: sandboxStatuses[value.status] ?? "unknown",
+    runtime: runtime(value.runtime),
+});
+const templateData = (value) => ({
+    ...value,
+    status: templateStatuses[value.status] ?? "unknown",
+    runtime: runtime(value.runtime),
+});
+const executionData = (value) => ({
+    ...value,
+    status: executionStatuses[value.status] ?? "unknown",
+});
+function budget(options) {
+    const { timeoutMs = 60_000, pollIntervalMs = 1000, ...rest } = options;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        throw new TypeError("timeoutMs must be a finite, non-negative number");
+    if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0)
+        throw new TypeError("pollIntervalMs must be a finite, positive number");
+    const deadline = Math.min(Date.now() + timeoutMs, options.deadline ?? Infinity);
+    return {
+        pollIntervalMs,
+        deadline,
+        options: { ...rest, timeoutMs, deadline, pollIntervalMs },
+    };
+}
+function check(wait) {
+    if (wait.options.signal?.aborted)
+        throw new errors_js_1.TarkaError("Operation cancelled", "cancelled");
+    if (Date.now() >= wait.deadline)
+        throw new errors_js_1.TarkaError("Timed out waiting for operation", "deadline_exceeded");
+}
+async function pause(wait) {
+    check(wait);
+    try {
+        await (0, promises_1.setTimeout)(Math.min(wait.pollIntervalMs, wait.deadline - Date.now(), 2 ** 31 - 1), undefined, { signal: wait.options.signal });
+    }
+    catch (error) {
+        if (wait.options.signal?.aborted)
+            throw new errors_js_1.TarkaError("Operation cancelled", "cancelled", {
+                cause: error,
+            });
+        throw error;
+    }
+    check(wait);
+}
+/** A code execution with retained output. Returned by submission, retrieval, and waiting; call `refresh()` or `wait()` to update its snapshot. */
+class Execution {
+    orgId;
+    sandboxId;
+    idempotencyKey;
+    #rpc;
+    /** Stable execution identifier; use `sandbox.executions.get(id)` to reattach later. */
+    id;
+    #info;
+    constructor(rpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId, 
+    /** Sandbox identifier retained by this execution or collection. */
+    sandboxId, info, 
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    idempotencyKey) {
+        this.orgId = orgId;
+        this.sandboxId = sandboxId;
+        this.idempotencyKey = idempotencyKey;
+        this.#rpc = rpc;
+        this.id = info.id;
+        this.#info = executionData(info);
+    }
+    /** Latest fetched execution snapshot. Reading it makes no network request. */
+    get info() {
+        return this.#info;
+    }
+    /** Latest known execution status. A terminal `failed`, `timed_out`, or `cancelled` result is returned for inspection. */
+    get status() {
+        return this.#info.status;
+    }
+    /** Retained standard output from the latest snapshot; may be empty after server-side output retention expires. */
+    get stdout() {
+        return this.#info.stdout;
+    }
+    /** Retained standard error from the latest snapshot; inspect alongside status and exitCode. */
+    get stderr() {
+        return this.#info.stderr;
+    }
+    /** Process exit code from the latest snapshot. Inspect it after the execution has reached a terminal status. */
+    get exitCode() {
+        return this.#info.exitCode;
+    }
+    /** Whether the server truncated retained execution output. */
+    get outputTruncated() {
+        return this.#info.outputTruncated;
+    }
+    /** Return the latest snapshot for serialization, without making a network request or including client internals. */
+    toJSON() {
+        return this.#info;
+    }
+    /**
+     * Fetch the latest execution snapshot and update this handle.
+     *
+     * @returns This same handle.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async refresh(options) {
+        this.#info = executionData(await this.#rpc.getExecution({ orgId: this.orgId, sandboxId: this.sandboxId, executionId: this.id }, options));
+        return this;
+    }
+    /**
+     * Poll this execution until it reaches a terminal status.
+     *
+     * Code failures and server execution timeouts return this handle for inspection; they are not transport errors. An already terminal handle is returned without another request.
+     * @param options - One total wait budget in `timeoutMs` (default 60,000), `pollIntervalMs` (default 1,000), cancellation, and metadata.
+     * @returns This same handle with updated output and status.
+     * @throws ExecutionOperationError on a transient failure; `resume()` polls the same execution.
+     * @throws ResourceStateError for an unknown execution status.
+     * @example
+     * const execution = await sandbox.executions.get(executionId);
+     * await execution.wait({ timeoutMs: 60_000 });
+     */
+    async wait(options = {}) {
+        const wait = budget(options);
+        try {
+            while (this.status === "running") {
+                check(wait);
+                await this.refresh(wait.options);
+                if (this.status === "running")
+                    await pause(wait);
+            }
+            if (this.status === "unknown")
+                throw new ResourceStateError("execution", this.#info);
+            return this;
+        }
+        catch (error) {
+            if (!recoverable(error))
+                throw error;
+            throw new ExecutionOperationError(error, {
+                operation: "execution.wait",
+                orgId: this.orgId,
+                sandboxId: this.sandboxId,
+                executionId: this.id,
+                idempotencyKey: this.idempotencyKey,
+            }, (next) => this.wait(resumeOptions(options, next)));
+        }
+    }
+}
+exports.Execution = Execution;
+/** Execution submission and retrieval bound to one sandbox. Access through `sandbox.executions`. */
+class Executions {
+    orgId;
+    sandboxId;
+    #rpc;
+    constructor(rpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId, 
+    /** Sandbox identifier retained by this execution or collection. */
+    sandboxId) {
+        this.orgId = orgId;
+        this.sandboxId = sandboxId;
+        this.#rpc = rpc;
+    }
+    /**
+     * Retrieve an execution handle without waiting for completion.
+     *
+     * @param id - Execution identifier within this sandbox.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async get(id, options) {
+        (0, errors_js_1.requireText)(id, "execution id");
+        return new Execution(this.#rpc, this.orgId, this.sandboxId, await this.#rpc.getExecution({ orgId: this.orgId, sandboxId: this.sandboxId, executionId: id }, options));
+    }
+    /**
+     * Submit code without readiness or completion polling.
+     *
+     * @param input - Source `code`, optional stdin, server `timeoutSeconds`, and optional idempotency key. A key is generated when omitted.
+     * @returns An Execution handle; call `wait()` to await completion.
+     * @throws ExecutionOperationError on a transient failure; recovery repeats the preserved request and key within the 24-hour deduplication window.
+     * @example
+     * const execution = await sandbox.executions.create({ code: "print(1)" });
+     * await execution.wait();
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        if (typeof input?.code !== "string")
+            throw new TypeError("code must be a string");
+        const request = {
+            ...input,
+            orgId: this.orgId,
+            sandboxId: this.sandboxId,
+            idempotencyKey: idempotencyKey(input.idempotencyKey),
+        };
+        try {
+            return new Execution(this.#rpc, this.orgId, this.sandboxId, await this.#rpc.execute(request, options), request.idempotencyKey);
+        }
+        catch (error) {
+            if (!recoverable(error))
+                throw error;
+            throw new ExecutionOperationError(error, {
+                operation: "execution.submit",
+                orgId: this.orgId,
+                sandboxId: this.sandboxId,
+                idempotencyKey: request.idempotencyKey,
+            }, (next) => this.create(request, resumeOptions(options, next)));
+        }
+    }
+}
+exports.Executions = Executions;
+/** An organization-bound sandbox handle. Lists, gets, and creates return this same type; local properties reflect the latest fetched snapshot. */
+class Sandbox {
+    orgId;
+    idempotencyKey;
+    #rpc;
+    /** Stable sandbox identifier; save it to reattach with `org.sandboxes.get(id)`. */
+    id;
+    /** Submit code and retrieve executions within this sandbox. */
+    executions;
+    #info;
+    constructor(rpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId, info, 
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    idempotencyKey) {
+        this.orgId = orgId;
+        this.idempotencyKey = idempotencyKey;
+        this.#rpc = rpc;
+        this.id = info.id;
+        this.#info = sandboxData(info);
+        this.executions = new Executions(rpc, orgId, this.id);
+    }
+    /** Latest fetched sandbox snapshot, including lifetime, runtime, and failure details. Reading it makes no request. */
+    get info() {
+        return this.#info;
+    }
+    /** Latest known lifecycle status, such as `starting`, `ready`, or `failed`. */
+    get status() {
+        return this.#info.status;
+    }
+    /** Return the latest snapshot for serialization, without client internals or a network request. */
+    toJSON() {
+        return this.#info;
+    }
+    /**
+     * Fetch the latest sandbox snapshot and update this handle.
+     *
+     * @returns This same handle.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async refresh(options) {
+        this.#info = sandboxData(await this.#rpc.getSandbox({ orgId: this.orgId, sandboxId: this.id }, options));
+        return this;
+    }
+    /**
+     * Poll while the sandbox is starting or busy, until it becomes ready.
+     *
+     * @param options - One total wait budget in `timeoutMs` (default 60,000), `pollIntervalMs` (default 1,000), cancellation, and metadata.
+     * @returns This same handle. An already ready snapshot returns immediately.
+     * @throws SandboxOperationError on a transient failure; `resume()` continues waiting on this sandbox.
+     * @throws ResourceStateError when the sandbox cannot become ready.
+     * Cancellation stops waiting; it does not delete the sandbox.
+     */
+    async waitUntilReady(options = {}) {
+        const wait = budget(options);
+        try {
+            while (this.status !== "ready") {
+                if (this.status !== "starting" && this.status !== "busy")
+                    throw new ResourceStateError("sandbox", this.#info);
+                check(wait);
+                await this.refresh(wait.options);
+                if (this.status === "starting" || this.status === "busy")
+                    await pause(wait);
+            }
+            return this;
+        }
+        catch (error) {
+            if (!recoverable(error))
+                throw error;
+            throw new SandboxOperationError(error, {
+                operation: "sandbox.wait",
+                orgId: this.orgId,
+                sandboxId: this.id,
+                idempotencyKey: this.idempotencyKey,
+            }, (next) => this.waitUntilReady(resumeOptions(options, next)));
+        }
+    }
+    /**
+     * Submit code and return an Execution handle without waiting for readiness or completion.
+     *
+     * @param code - Source interpreted by the sandbox template's runtime.
+     * @param input - Optional stdin, server execution limit in `timeoutSeconds`, and idempotency key; a key is generated when omitted.
+     * @throws ExecutionOperationError on a transient failure; `resume()` recovers submission with the original input and key.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    execute(code, input = {}, options) {
+        return this.executions.create({ ...input, code }, options);
+    }
+    /**
+     * Wait for readiness, submit code, then wait for completion within one total budget.
+     *
+     * @param code - Source interpreted by the sandbox template's runtime.
+     * @param input - Optional stdin, server execution limit in `timeoutSeconds`, and idempotency key. Pass `undefined` when supplying only wait settings.
+     * @param options - Total client wait in `timeoutMs` (default 60,000), polling interval (default 1,000), cancellation, and metadata. This overrides the client timeout.
+     * @returns The completed Execution handle, including code failures and server timeouts; inspect `status`, `exitCode`, and `stderr`.
+     * @throws ExecutionOperationError on a transient failure. `resume()` polls a known execution or replays an unacknowledged submission with the same key.
+     * @throws ResourceStateError if readiness is impossible or the execution status is unknown.
+     * Client timeout/cancellation does not necessarily stop remotely running code. Keep the sandbox available while recovering.
+     * @example
+     * const result = await sandbox.run("print(1)", { timeoutSeconds: 30 }, { timeoutMs: 60_000 });
+     * console.log(result.status, result.stdout);
+     */
+    async run(code, input = {}, options = {}) {
+        if (typeof code !== "string")
+            throw new TypeError("code must be a string");
+        const request = {
+            ...input,
+            idempotencyKey: idempotencyKey(input.idempotencyKey),
+        };
+        const wait = budget(options);
+        try {
+            check(wait);
+            await this.waitUntilReady(wait.options);
+            const execution = await this.execute(code, request, wait.options);
+            return await execution.wait(wait.options);
+        }
+        catch (error) {
+            // Once we know the execution ID, resume only reads its state.
+            if (error instanceof ExecutionOperationError &&
+                error.recovery.executionId)
+                throw error;
+            if (!recoverable(error))
+                throw error;
+            throw new ExecutionOperationError(error, {
+                operation: "execution.run",
+                orgId: this.orgId,
+                sandboxId: this.id,
+                idempotencyKey: request.idempotencyKey,
+            }, (next) => this.run(code, request, resumeOptions(options, next)));
+        }
+    }
+    /**
+     * Stop and delete this sandbox, updating the local snapshot from the server response.
+     *
+     * @returns Resolves without a value after acknowledgement. Finish recovery before deleting the sandbox.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async delete(options) {
+        this.#info = sandboxData(await this.#rpc.deleteSandbox({ orgId: this.orgId, sandboxId: this.id }, options));
+    }
+}
+exports.Sandbox = Sandbox;
+/** A reusable sandbox template handle with build-state polling. Obtain from `org.sandboxes.templates`. */
+class SandboxTemplate {
+    orgId;
+    idempotencyKey;
+    #rpc;
+    /** Stable template identifier, accepted by sandbox creation. */
+    id;
+    #info;
+    constructor(rpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId, info, 
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    idempotencyKey) {
+        this.orgId = orgId;
+        this.idempotencyKey = idempotencyKey;
+        this.#rpc = rpc;
+        this.id = info.id;
+        this.#info = templateData(info);
+    }
+    /** Latest fetched template snapshot, including runtime, manifest digest, and build error code. */
+    get info() {
+        return this.#info;
+    }
+    /** Latest known template lifecycle status, such as `building`, `ready`, or `failed`. */
+    get status() {
+        return this.#info.status;
+    }
+    /** Template alias from the latest snapshot; also accepted by sandbox creation. */
+    get alias() {
+        return this.#info.alias;
+    }
+    /** Return the latest snapshot for serialization without client internals or a network request. */
+    toJSON() {
+        return this.#info;
+    }
+    /**
+     * Fetch the latest template snapshot and update this handle.
+     *
+     * @returns This same handle.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async refresh(options) {
+        this.#info = templateData(await this.#rpc.getSandboxTemplate({ orgId: this.orgId, templateId: this.id }, options));
+        return this;
+    }
+    /**
+     * Poll a pending or building template until it is ready for sandbox creation.
+     *
+     * @param options - One total wait budget in `timeoutMs` (default 60,000), `pollIntervalMs` (default 1,000), cancellation, and metadata. Builds may need a larger budget.
+     * @returns This same handle. An already ready snapshot returns immediately.
+     * @throws TemplateOperationError on a transient failure; `resume()` continues polling this template.
+     * @throws ResourceStateError when the template cannot become ready.
+     * Cancelling a wait stops polling; it does not delete the template or cancel its build.
+     */
+    async waitUntilReady(options = {}) {
+        const wait = budget(options);
+        try {
+            while (this.status !== "ready") {
+                if (this.status !== "pending" && this.status !== "building")
+                    throw new ResourceStateError("template", this.#info);
+                check(wait);
+                await this.refresh(wait.options);
+                if (this.status === "pending" || this.status === "building")
+                    await pause(wait);
+            }
+            return this;
+        }
+        catch (error) {
+            if (!recoverable(error))
+                throw error;
+            throw new TemplateOperationError(error, {
+                operation: "template.wait",
+                orgId: this.orgId,
+                templateId: this.id,
+                idempotencyKey: this.idempotencyKey,
+            }, (next) => this.waitUntilReady(resumeOptions(options, next)));
+        }
+    }
+    /**
+     * Request deletion of this template and update its local snapshot.
+     *
+     * @returns Resolves without a value after acknowledgement; inspect the snapshot for lifecycle state.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async delete(options) {
+        this.#info = templateData(await this.#rpc.deleteSandboxTemplate({ orgId: this.orgId, templateId: this.id }, options));
+    }
+}
+exports.SandboxTemplate = SandboxTemplate;
+/** Organization-visible reusable templates, including platform built-ins. Access through `org.sandboxes.templates`. */
+class SandboxTemplates {
+    orgId;
+    #rpc;
+    constructor(rpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId) {
+        this.orgId = orgId;
+        this.#rpc = rpc;
+    }
+    /**
+     * List visible templates as SandboxTemplate handles, including platform built-ins.
+     *
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async list(options) {
+        return (await this.#rpc.listSandboxTemplates({ orgId: this.orgId }, options)).templates.map((info) => new SandboxTemplate(this.#rpc, this.orgId, info));
+    }
+    /**
+     * Retrieve a template handle without waiting for build completion.
+     *
+     * @param id - Organization-visible template identifier.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async get(id, options) {
+        (0, errors_js_1.requireText)(id, "template id");
+        return new SandboxTemplate(this.#rpc, this.orgId, await this.#rpc.getSandboxTemplate({ orgId: this.orgId, templateId: id }, options));
+    }
+    /**
+     * Create a dependency-pinned template and return its handle without build polling.
+     *
+     * @param input - Alias, built-in base template alias, and exactly one manifest string: `requirementsTxt`, `packageJson`, or `pyprojectToml`. An omitted idempotency key is generated.
+     * @returns A SandboxTemplate handle; call `waitUntilReady()` before using a building template.
+     * @throws TemplateOperationError on a transient failure; `resume()` preserves the manifest and idempotency key.
+     * @example
+     * const template = await org.sandboxes.templates.create({
+     *   alias: "custom-python", baseTemplateAlias, requirementsTxt: "numpy==2.0.0",
+     * });
+     * await template.waitUntilReady({ timeoutMs: 300_000 });
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        (0, errors_js_1.requireText)(input?.alias, "alias");
+        (0, errors_js_1.requireText)(input?.baseTemplateAlias, "baseTemplateAlias");
+        const fields = ["requirementsTxt", "packageJson", "pyprojectToml"];
+        const selected = fields.filter((field) => input[field] !== undefined);
+        if (selected.length !== 1 || typeof input[selected[0]] !== "string")
+            throw new TypeError("Provide exactly one dependency manifest: requirementsTxt, packageJson, or pyprojectToml");
+        const field = selected[0];
+        const replay = {
+            ...input,
+            idempotencyKey: idempotencyKey(input.idempotencyKey),
+        };
+        const request = {
+            orgId: this.orgId,
+            alias: input.alias,
+            baseTemplateAlias: input.baseTemplateAlias,
+            displayName: input.displayName,
+            idempotencyKey: replay.idempotencyKey,
+            dependencyFile: { $case: field, value: input[field] },
+        };
+        try {
+            return new SandboxTemplate(this.#rpc, this.orgId, await this.#rpc.createSandboxTemplate(request, options), replay.idempotencyKey);
+        }
+        catch (error) {
+            if (!recoverable(error))
+                throw error;
+            throw new TemplateOperationError(error, {
+                operation: "template.create",
+                orgId: this.orgId,
+                idempotencyKey: replay.idempotencyKey,
+            }, (next) => this.create(replay, resumeOptions(options, next)));
+        }
+    }
+    /**
+     * Request deletion of an organization-owned template.
+     *
+     * @param id - Template identifier.
+     * @returns Resolves without a value after acknowledgement.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async delete(id, options) {
+        (0, errors_js_1.requireText)(id, "template id");
+        await this.#rpc.deleteSandboxTemplate({ orgId: this.orgId, templateId: id }, options);
+    }
+}
+exports.SandboxTemplates = SandboxTemplates;
+/** Sandbox lifecycle and templates bound to one organization. Access through `client.org(orgId).sandboxes`. */
+class OrganizationSandboxes {
+    orgId;
+    #rpc;
+    /** Visible reusable templates and custom template creation. */
+    templates;
+    constructor(rpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId) {
+        this.orgId = orgId;
+        this.#rpc = rpc;
+        (0, errors_js_1.requireText)(orgId, "organization id");
+        this.templates = new SandboxTemplates(rpc, orgId);
+    }
+    /**
+     * List non-deleted sandboxes, newest first, as Sandbox handles.
+     *
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async list(options) {
+        return (await this.#rpc.listSandboxes({ orgId: this.orgId }, options)).sandboxes.map((info) => new Sandbox(this.#rpc, this.orgId, info));
+    }
+    /**
+     * Retrieve a Sandbox handle without waiting for readiness.
+     *
+     * @param id - Sandbox identifier within this organization.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async get(id, options) {
+        (0, errors_js_1.requireText)(id, "sandbox id");
+        return new Sandbox(this.#rpc, this.orgId, await this.#rpc.getSandbox({ orgId: this.orgId, sandboxId: id }, options));
+    }
+    /**
+     * Start a sandbox from a ready template and return its handle.
+     *
+     * @param input - Visible template ID or alias, optional server lifetime in `timeoutSeconds`, and optional idempotency key. A key is generated when omitted.
+     * @returns A Sandbox handle without readiness polling; `run()` waits for readiness automatically.
+     * @throws SandboxOperationError on a transient failure; `resume()` repeats the original request and key within the 24-hour deduplication window.
+     * @example
+     * const sandbox = await client.org(orgId).sandboxes.create({ template, timeoutSeconds: 600 });
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        (0, errors_js_1.requireText)(input?.template, "template");
+        const replay = {
+            ...input,
+            idempotencyKey: idempotencyKey(input.idempotencyKey),
+        };
+        try {
+            return new Sandbox(this.#rpc, this.orgId, await this.#rpc.createSandbox({ ...replay, orgId: this.orgId }, options), replay.idempotencyKey);
+        }
+        catch (error) {
+            if (!recoverable(error))
+                throw error;
+            throw new SandboxOperationError(error, {
+                operation: "sandbox.create",
+                orgId: this.orgId,
+                idempotencyKey: replay.idempotencyKey,
+            }, (next) => this.create(replay, resumeOptions(options, next)));
+        }
+    }
+    /**
+     * Stop and delete an organization sandbox.
+     *
+     * @param id - Sandbox identifier.
+     * @returns Resolves without a value after acknowledgement.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async delete(id, options) {
+        (0, errors_js_1.requireText)(id, "sandbox id");
+        await this.#rpc.deleteSandbox({ orgId: this.orgId, sandboxId: id }, options);
+    }
+}
+exports.OrganizationSandboxes = OrganizationSandboxes;