@tarkahq/sdk 0.0.0-stage → 0.3.0

package/dist/cjs/resources/sandboxes.d.ts

@@ -0,0 +1,360 @@
+import type { SandboxRpc } from "../rpc-types.js";
+import type * as wire from "../generated/tarka/provisioning/v1/sandbox.js";
+import { TarkaError } from "../errors.js";
+import type { RequestOptions, WaitOptions, SandboxInput, TemplateInput, ExecutionInput, SandboxData, TemplateData, ExecutionData, SandboxStatus, TemplateStatus, ExecutionStatus } from "../types.js";
+/** Identifiers and idempotency context for an interrupted operation. Request code, stdin, and manifests are kept out of this object. */
+export interface RecoveryDetails {
+    /** The interrupted phase. A resumed `execution.run` still waits for completion; `execution.submit` only submits. */
+    operation: "sandbox.create" | "sandbox.wait" | "template.create" | "template.wait" | "execution.submit" | "execution.wait" | "execution.run";
+    /** Organization in which the operation was started. */
+    orgId: string;
+    /** Sandbox identifier when it is known. */
+    sandboxId?: string;
+    /** Template identifier when creation was acknowledged. */
+    templateId?: string;
+    /** Acknowledged execution identifier. When present, recovery only reads this execution and never submits code again. */
+    executionId?: string;
+    /** Original mutation key. Replaying an unacknowledged request requires unchanged input within the API's 24-hour deduplication window. */
+    idempotencyKey?: string;
+}
+/**
+ * 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.
+ */
+export declare class OperationError<T> extends TarkaError {
+    #private;
+    /** Frozen recovery context containing available IDs and the original idempotency key, without the request payload. */
+    readonly recovery: Readonly<RecoveryDetails>;
+    constructor(cause: unknown, recovery: RecoveryDetails, resume: (options?: WaitOptions) => Promise<T>);
+    /**
+     * 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?: WaitOptions): Promise<T>;
+}
+/** Interrupted sandbox creation or readiness wait. `resume()` returns a Sandbox handle. */
+export declare class SandboxOperationError extends OperationError<Sandbox> {
+    name: string;
+}
+/** Interrupted template creation or readiness wait. `resume()` returns a SandboxTemplate handle. */
+export declare class TemplateOperationError extends OperationError<SandboxTemplate> {
+    name: string;
+}
+/** Interrupted code submission, run, or execution wait. `resume()` returns an Execution handle and preserves the original operation. */
+export declare class ExecutionOperationError extends OperationError<Execution> {
+    name: string;
+}
+/** A resource cannot reach the requested state. Includes its snapshot in `info`; unknown statuses use `data_loss`, other terminal states use `failed_precondition`. */
+export declare class ResourceStateError extends TarkaError {
+    /** Kind of resource whose state prevents this operation. */
+    readonly resource: "sandbox" | "template" | "execution";
+    /** Latest snapshot, including the status and available failure details. */
+    readonly info: SandboxData | TemplateData | ExecutionData;
+    constructor(
+    /** Kind of resource whose state prevents this operation. */
+    resource: "sandbox" | "template" | "execution", 
+    /** Latest snapshot, including the status and available failure details. */
+    info: SandboxData | TemplateData | ExecutionData);
+}
+/** A code execution with retained output. Returned by submission, retrieval, and waiting; call `refresh()` or `wait()` to update its snapshot. */
+export declare class Execution {
+    #private;
+    /** Organization identifier retained by this handle or collection. */
+    readonly orgId: string;
+    /** Sandbox identifier retained by this execution or collection. */
+    readonly sandboxId: string;
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    readonly idempotencyKey?: string | undefined;
+    /** Stable execution identifier; use `sandbox.executions.get(id)` to reattach later. */
+    readonly id: string;
+    constructor(rpc: SandboxRpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId: string, 
+    /** Sandbox identifier retained by this execution or collection. */
+    sandboxId: string, info: wire.Execution, 
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    idempotencyKey?: string | undefined);
+    /** Latest fetched execution snapshot. Reading it makes no network request. */
+    get info(): Readonly<ExecutionData>;
+    /** Latest known execution status. A terminal `failed`, `timed_out`, or `cancelled` result is returned for inspection. */
+    get status(): ExecutionStatus;
+    /** Retained standard output from the latest snapshot; may be empty after server-side output retention expires. */
+    get stdout(): string;
+    /** Retained standard error from the latest snapshot; inspect alongside status and exitCode. */
+    get stderr(): string;
+    /** Process exit code from the latest snapshot. Inspect it after the execution has reached a terminal status. */
+    get exitCode(): number;
+    /** Whether the server truncated retained execution output. */
+    get outputTruncated(): boolean;
+    /** Return the latest snapshot for serialization, without making a network request or including client internals. */
+    toJSON(): ExecutionData;
+    /**
+     * Fetch the latest execution snapshot and update this handle.
+     *
+     * @returns This same handle.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    refresh(options?: RequestOptions): Promise<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 });
+     */
+    wait(options?: WaitOptions): Promise<this>;
+}
+/** Execution submission and retrieval bound to one sandbox. Access through `sandbox.executions`. */
+export declare class Executions {
+    #private;
+    /** Organization identifier retained by this handle or collection. */
+    readonly orgId: string;
+    /** Sandbox identifier retained by this execution or collection. */
+    readonly sandboxId: string;
+    constructor(rpc: SandboxRpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId: string, 
+    /** Sandbox identifier retained by this execution or collection. */
+    sandboxId: string);
+    /**
+     * 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.
+     */
+    get(id: string, options?: RequestOptions): Promise<Execution>;
+    /**
+     * 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.
+     */
+    create(input: ExecutionInput & {
+        code: string;
+    }, options?: RequestOptions): Promise<Execution>;
+}
+/** An organization-bound sandbox handle. Lists, gets, and creates return this same type; local properties reflect the latest fetched snapshot. */
+export declare class Sandbox {
+    #private;
+    /** Organization identifier retained by this handle or collection. */
+    readonly orgId: string;
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    readonly idempotencyKey?: string | undefined;
+    /** Stable sandbox identifier; save it to reattach with `org.sandboxes.get(id)`. */
+    readonly id: string;
+    /** Submit code and retrieve executions within this sandbox. */
+    readonly executions: Executions;
+    constructor(rpc: SandboxRpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId: string, info: wire.CodeSandbox, 
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    idempotencyKey?: string | undefined);
+    /** Latest fetched sandbox snapshot, including lifetime, runtime, and failure details. Reading it makes no request. */
+    get info(): Readonly<SandboxData>;
+    /** Latest known lifecycle status, such as `starting`, `ready`, or `failed`. */
+    get status(): SandboxStatus;
+    /** Return the latest snapshot for serialization, without client internals or a network request. */
+    toJSON(): SandboxData;
+    /**
+     * Fetch the latest sandbox snapshot and update this handle.
+     *
+     * @returns This same handle.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    refresh(options?: RequestOptions): Promise<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.
+     */
+    waitUntilReady(options?: WaitOptions): Promise<this>;
+    /**
+     * 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: string, input?: ExecutionInput, options?: RequestOptions): Promise<Execution>;
+    /**
+     * 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);
+     */
+    run(code: string, input?: ExecutionInput, options?: WaitOptions): Promise<Execution>;
+    /**
+     * 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.
+     */
+    delete(options?: RequestOptions): Promise<void>;
+}
+/** A reusable sandbox template handle with build-state polling. Obtain from `org.sandboxes.templates`. */
+export declare class SandboxTemplate {
+    #private;
+    /** Organization identifier retained by this handle or collection. */
+    readonly orgId: string;
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    readonly idempotencyKey?: string | undefined;
+    /** Stable template identifier, accepted by sandbox creation. */
+    readonly id: string;
+    constructor(rpc: SandboxRpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId: string, info: wire.SandboxTemplate, 
+    /** Original mutation key on created/submitted handles; absent on handles fetched by ID or listed. */
+    idempotencyKey?: string | undefined);
+    /** Latest fetched template snapshot, including runtime, manifest digest, and build error code. */
+    get info(): Readonly<TemplateData>;
+    /** Latest known template lifecycle status, such as `building`, `ready`, or `failed`. */
+    get status(): TemplateStatus;
+    /** Template alias from the latest snapshot; also accepted by sandbox creation. */
+    get alias(): string;
+    /** Return the latest snapshot for serialization without client internals or a network request. */
+    toJSON(): TemplateData;
+    /**
+     * Fetch the latest template snapshot and update this handle.
+     *
+     * @returns This same handle.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    refresh(options?: RequestOptions): Promise<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.
+     */
+    waitUntilReady(options?: WaitOptions): Promise<this>;
+    /**
+     * 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.
+     */
+    delete(options?: RequestOptions): Promise<void>;
+}
+/** Organization-visible reusable templates, including platform built-ins. Access through `org.sandboxes.templates`. */
+export declare class SandboxTemplates {
+    #private;
+    /** Organization identifier retained by this handle or collection. */
+    readonly orgId: string;
+    constructor(rpc: SandboxRpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId: string);
+    /**
+     * List visible templates as SandboxTemplate handles, including platform built-ins.
+     *
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    list(options?: RequestOptions): Promise<SandboxTemplate[]>;
+    /**
+     * 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.
+     */
+    get(id: string, options?: RequestOptions): Promise<SandboxTemplate>;
+    /**
+     * 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.
+     */
+    create(input: TemplateInput, options?: RequestOptions): Promise<SandboxTemplate>;
+    /**
+     * 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.
+     */
+    delete(id: string, options?: RequestOptions): Promise<void>;
+}
+/** Sandbox lifecycle and templates bound to one organization. Access through `client.org(orgId).sandboxes`. */
+export declare class OrganizationSandboxes {
+    #private;
+    /** Organization identifier retained by this handle or collection. */
+    readonly orgId: string;
+    /** Visible reusable templates and custom template creation. */
+    readonly templates: SandboxTemplates;
+    constructor(rpc: SandboxRpc, 
+    /** Organization identifier retained by this handle or collection. */
+    orgId: string);
+    /**
+     * List non-deleted sandboxes, newest first, as Sandbox handles.
+     *
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    list(options?: RequestOptions): Promise<Sandbox[]>;
+    /**
+     * 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.
+     */
+    get(id: string, options?: RequestOptions): Promise<Sandbox>;
+    /**
+     * 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.
+     */
+    create(input: SandboxInput, options?: RequestOptions): Promise<Sandbox>;
+    /**
+     * 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.
+     */
+    delete(id: string, options?: RequestOptions): Promise<void>;
+}