@sandbox-kit/sandbox 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sandbox-kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# `@sandbox-kit/sandbox`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create and manage cloud sandboxes from one TypeScript API. Pick a provider
+package (`@sandbox-kit/daytona` or `@sandbox-kit/modal`), construct a client,
+then create or open sandboxes through the same methods.
+
+Closing a client or handle releases **local** SDK resources only. It does not
+stop, terminate, or delete the remote sandbox.
+
+## Install
+
+```sh
+npm install @sandbox-kit/sandbox @sandbox-kit/daytona
+# or
+npm install @sandbox-kit/sandbox @sandbox-kit/modal
+```
+
+Requires Node.js 20, 22, or 24.15+.
+
+## Quick start
+
+```ts
+import { daytona } from "@sandbox-kit/daytona";
+import { Client } from "@sandbox-kit/sandbox";
+
+await using client = new Client({
+  provider: daytona(),
+  auth: { apiKey: { key: process.env.DAYTONA_API_KEY! } },
+  timeout: 120_000,
+});
+
+const sandbox = await client.create();
+console.log(sandbox.id, client.providerName);
+```
+
+Prefer `await using` when available. Otherwise call `await client.close()` in a
+`finally` block.
+
+## Client configuration
+
+Pass the provider on `ClientConfig`, then shared settings:
+
+| Field      | Purpose                                                         |
+| ---------- | --------------------------------------------------------------- |
+| `provider` | Provider factory (`daytona()`, `modal()`, …)                    |
+| `auth`     | One credential shape (`apiKey`, `bearerToken`, `tokenPair`, …)  |
+| `scope`    | App, environment, organization, or project (provider-dependent) |
+| `endpoint` | API URL when the provider supports it                           |
+| `region`   | Target or placement preference                                  |
+| `timeout`  | Default operation deadline in **milliseconds**                  |
+
+Omit `auth` when the provider SDK should resolve credentials from its own
+environment. Provider-specific auth and scope rules live in each provider
+package README.
+
+## Create a sandbox
+
+```ts
+const sandbox = await client.create({
+  source: { image: { reference: "daytonaio/playground:latest" } },
+  provisioning: { timeout: 120_000 },
+});
+```
+
+`create()` with no options uses the provider default when that is valid (for
+example Daytona's default snapshot). Timeouts and delays are millisecond
+numbers. Nested exclusive fields use shapes like `source: { image: … }` or
+`auth: { apiKey: … }`.
+
+## Open an existing sandbox
+
+```ts
+const attached = await client.attach(id); // provider must support attach
+const fetched = await client.get(id); // provider-verified lookup
+```
+
+## Sandbox handle
+
+| Method           | Purpose                                       |
+| ---------------- | --------------------------------------------- |
+| `id`             | Sandbox identifier                            |
+| `info()`         | Copied metadata                               |
+| `capabilities()` | Lifecycle operations this handle can run      |
+| `supports(...)`  | Check one capability                          |
+| `refresh`        | Refresh metadata from the provider            |
+| `start`          | Start                                         |
+| `stop`           | Stop (`force` when supported)                 |
+| `pause`          | Pause                                         |
+| `archive`        | Archive                                       |
+| `delete`         | Delete (`wait` when supported)                |
+| `terminate`      | Terminate (`wait` when supported)             |
+| `close`          | Drop the local handle (not the cloud sandbox) |
+
+Unsupported operations throw before the provider call. Use `supports(...)` when
+the sandbox class may differ (for example Daytona container vs VM).
+
+## Errors
+
+Failures throw `SandboxError` with `kind`, `provider`, `operation`, `field`,
+and `message`:
+
+```ts
+import { Client, SandboxError } from "@sandbox-kit/sandbox";
+
+try {
+  await client.create({ resources: { cpuCores: -1 } });
+} catch (error) {
+  if (error instanceof SandboxError) {
+    console.error(error.kind, error.field, error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Providers
+
+| Package                | Role              |
+| ---------------------- | ----------------- |
+| `@sandbox-kit/daytona` | Daytona sandboxes |
+| `@sandbox-kit/modal`   | Modal sandboxes   |
+
+## Examples
+
+Runnable projects:
+[examples/typescript](https://github.com/sandbox-kit/kit/tree/main/examples/typescript).
+
+## License
+
+MIT

package/dist/client/client.d.ts

@@ -0,0 +1,17 @@
+import type { CreateOptions } from "#contracts/sandbox_data_contracts.js";
+import { Sandbox } from "#client/sandbox.js";
+import type { ClientConfig, OperationOptions } from "#client/types.js";
+export type { APIKeyCredentials, AuthInput, Backend, BearerTokenCredentials, ClientConfig, Config, DeleteCallOptions, OAuthCredentials, OperationOptions, Provider, Scope, StopCallOptions, TerminateCallOptions, TokenPairCredentials, } from "#client/types.js";
+export { ErrorKind, SandboxError, sandboxError } from "#client/errors.js";
+export { Sandbox } from "#client/sandbox.js";
+export { validateConfig, validateCreateOptions } from "#client/validation.js";
+export declare class Client implements AsyncDisposable {
+    #private;
+    constructor(config: ClientConfig);
+    get providerName(): string;
+    attach(id: string, options?: OperationOptions): Promise<Sandbox>;
+    get(id: string, options?: OperationOptions): Promise<Sandbox>;
+    create(request?: CreateOptions, options?: OperationOptions): Promise<Sandbox>;
+    close(options?: OperationOptions): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/client/client.js

@@ -0,0 +1,222 @@
+// Client runtime behavior is handwritten. Portable request and response data
+// remain generated from protobuf. This module owns construction and create /
+// attach / get / close; validation, errors, and the Sandbox handle live beside it.
+import { InfoFieldId } from "#contracts/field_paths.js";
+import { ConfigFieldProvider } from "#contracts/config_paths.js";
+import { ErrorKind, sandboxError, unsupported, withContext, } from "#client/errors.js";
+import { awaitWithSignal, operationOptions, operationSignal, } from "#client/operation.js";
+import { Sandbox, sandboxConstructorToken, } from "#client/sandbox.js";
+import { validateConfig, validateCreateOptions } from "#client/validation.js";
+export { ErrorKind, SandboxError, sandboxError } from "#client/errors.js";
+export { Sandbox } from "#client/sandbox.js";
+export { validateConfig, validateCreateOptions } from "#client/validation.js";
+export class Client {
+    #backend;
+    #providerName;
+    #timeout;
+    #lifecycle;
+    #active = 0;
+    #closing = false;
+    #closed = false;
+    #closePromise;
+    #drain;
+    #resolveDrain;
+    constructor(config) {
+        if (!config.provider?.name?.trim())
+            throw sandboxError({
+                kind: ErrorKind.InvalidArgument,
+                provider: "",
+                operation: "initialize",
+                field: ConfigFieldProvider,
+                message: "sandbox-kit: provider is required",
+            });
+        validateConfig(config, config.provider.name, "initialize");
+        this.#providerName = config.provider.name;
+        this.#timeout = config.timeout;
+        this.#lifecycle = {
+            begin: (operation) => this.#begin(operation),
+            isClosed: () => this.#closing || this.#closed,
+        };
+        try {
+            const { provider: _provider, ...shared } = config;
+            this.#backend = config.provider.initialize(shared);
+        }
+        catch (error) {
+            throw withContext(error, config.provider.name, "initialize");
+        }
+        if (!this.#backend)
+            throw sandboxError({
+                kind: ErrorKind.InvalidResponse,
+                provider: config.provider.name,
+                operation: "initialize",
+                field: ConfigFieldProvider,
+                message: "sandbox-kit: provider returned no backend",
+            });
+        if (this.#backend.name !== this.#providerName) {
+            void this.#backend.close({}).catch(() => { });
+            throw sandboxError({
+                kind: ErrorKind.InvalidResponse,
+                provider: this.#providerName,
+                operation: "initialize",
+                field: ConfigFieldProvider,
+                message: "sandbox-kit: initialized backend identity differs from selected provider",
+            });
+        }
+    }
+    get providerName() {
+        return this.#providerName;
+    }
+    async attach(id, options = {}) {
+        return this.#openById("attach", id, options, (fetchOptions) => {
+            if (!this.#backend.attach)
+                unsupported(this.providerName, "attach");
+            return this.#backend.attach(id, fetchOptions);
+        });
+    }
+    async get(id, options = {}) {
+        return this.#openById("get", id, options, (fetchOptions) => {
+            if (!this.#backend.refresh)
+                unsupported(this.providerName, "get");
+            return this.#backend.refresh(id, fetchOptions);
+        });
+    }
+    async #openById(operation, id, options, fetch) {
+        const release = this.#begin(operation);
+        let scoped;
+        try {
+            scoped = operationSignal(options, this.#timeout);
+            if (!id.trim())
+                throw sandboxError({
+                    kind: ErrorKind.InvalidArgument,
+                    provider: this.providerName,
+                    operation,
+                    field: InfoFieldId,
+                    message: "sandbox-kit: sandbox ID must not be blank",
+                });
+            const info = await awaitWithSignal(() => fetch(operationOptions(options, scoped?.signal)), scoped.signal);
+            return new Sandbox(sandboxConstructorToken, {
+                backend: this.#backend,
+                owner: this.#lifecycle,
+                info: { ...info, id, provider: this.providerName },
+                ...(this.#timeout === undefined ? {} : { timeout: this.#timeout }),
+            });
+        }
+        catch (error) {
+            throw withContext(error, this.providerName, operation);
+        }
+        finally {
+            scoped?.dispose();
+            release();
+        }
+    }
+    async create(request = {}, options = {}) {
+        const release = this.#begin("create");
+        const timeout = options.timeout ?? request.provisioning?.timeout ?? this.#timeout;
+        let scoped;
+        try {
+            // Validate the wire projection first; providers receive the public request.
+            validateCreateOptions(request, this.providerName, "create");
+            scoped = operationSignal(options, timeout);
+            const create = this.#backend.create;
+            if (!create)
+                unsupported(this.providerName, "create");
+            const providerRequest = {
+                ...request,
+                ...(timeout === undefined
+                    ? {}
+                    : {
+                        provisioning: {
+                            ...request.provisioning,
+                            timeout,
+                        },
+                    }),
+            };
+            const result = await awaitWithSignal(() => create.call(this.#backend, providerRequest, operationOptions({ ...(timeout === undefined ? {} : { timeout: timeout }) }, scoped?.signal)), scoped.signal);
+            if (!result.sandbox?.id)
+                throw sandboxError({
+                    kind: ErrorKind.InvalidResponse,
+                    provider: this.providerName,
+                    operation: "create",
+                    field: InfoFieldId,
+                    message: "sandbox-kit: provider returned no sandbox identity",
+                });
+            if (result.sandbox.provider &&
+                result.sandbox.provider !== this.providerName)
+                throw sandboxError({
+                    kind: ErrorKind.InvalidResponse,
+                    provider: this.providerName,
+                    operation: "create",
+                    field: ConfigFieldProvider,
+                    message: "sandbox-kit: response provider differs from selected provider",
+                });
+            return new Sandbox(sandboxConstructorToken, {
+                backend: this.#backend,
+                owner: this.#lifecycle,
+                info: { ...result.sandbox, provider: this.providerName },
+                ...(this.#timeout === undefined ? {} : { timeout: this.#timeout }),
+            });
+        }
+        catch (error) {
+            throw withContext(error, this.providerName, "create");
+        }
+        finally {
+            scoped?.dispose();
+            release();
+        }
+    }
+    close(options = {}) {
+        if (this.#closePromise)
+            return this.#closePromise;
+        this.#closing = true;
+        this.#closePromise = this.#close(options);
+        return this.#closePromise;
+    }
+    async #close(options) {
+        let scoped;
+        try {
+            scoped = operationSignal(options, this.#timeout);
+            if (this.#active > 0) {
+                this.#drain ??= new Promise((resolve) => {
+                    this.#resolveDrain = resolve;
+                });
+                await awaitWithSignal(() => this.#drain, scoped.signal);
+            }
+            await awaitWithSignal(() => this.#backend.close(operationOptions(options, scoped?.signal)), scoped.signal);
+            this.#closed = true;
+        }
+        catch (error) {
+            this.#closePromise = undefined;
+            this.#closing = false;
+            throw withContext(error, this.providerName, "close");
+        }
+        finally {
+            scoped?.dispose();
+        }
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    #begin(operation) {
+        if (this.#closing || this.#closed)
+            throw sandboxError({
+                kind: ErrorKind.FailedPrecondition,
+                provider: this.providerName,
+                operation,
+                field: "client",
+                message: "sandbox-kit: client is closed",
+            });
+        this.#active++;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.#active--;
+            if (this.#active === 0) {
+                this.#resolveDrain?.();
+                this.#resolveDrain = undefined;
+                this.#drain = undefined;
+            }
+        };
+    }
+}

package/dist/client/errors.d.ts

@@ -0,0 +1,35 @@
+import { ErrorKind as ProtoErrorKind } from "@sandbox-kit/contracts/sandbox";
+import type { ErrorInfo } from "#contracts/sandbox_data_contracts.js";
+export declare const ErrorKind: {
+    readonly Unknown: ProtoErrorKind.UNKNOWN;
+    readonly InvalidArgument: ProtoErrorKind.INVALID_ARGUMENT;
+    readonly Unsupported: ProtoErrorKind.UNSUPPORTED;
+    readonly Authentication: ProtoErrorKind.AUTHENTICATION;
+    readonly PermissionDenied: ProtoErrorKind.PERMISSION_DENIED;
+    readonly NotFound: ProtoErrorKind.NOT_FOUND;
+    readonly AlreadyExists: ProtoErrorKind.ALREADY_EXISTS;
+    readonly Conflict: ProtoErrorKind.CONFLICT;
+    readonly RateLimited: ProtoErrorKind.RATE_LIMITED;
+    readonly ResourceExhausted: ProtoErrorKind.RESOURCE_EXHAUSTED;
+    readonly Timeout: ProtoErrorKind.TIMEOUT;
+    readonly Canceled: ProtoErrorKind.CANCELED;
+    readonly Unavailable: ProtoErrorKind.UNAVAILABLE;
+    readonly InvalidResponse: ProtoErrorKind.INVALID_RESPONSE;
+    readonly Internal: ProtoErrorKind.INTERNAL;
+    readonly FailedPrecondition: ProtoErrorKind.FAILED_PRECONDITION;
+};
+export type ErrorKind = (typeof ErrorKind)[keyof typeof ErrorKind];
+export declare class SandboxError extends Error {
+    readonly kind: ErrorInfo["kind"];
+    readonly provider: string;
+    readonly operation: string;
+    readonly field: string;
+    readonly rule: string | undefined;
+    readonly statusCode: number | undefined;
+    readonly providerCode: string | undefined;
+    readonly providerSource: string | undefined;
+    constructor(info: ErrorInfo, options?: ErrorOptions);
+}
+export declare function sandboxError(info: ErrorInfo, cause?: unknown): SandboxError;
+export declare function unsupported(provider: string, operation: string): never;
+export declare function withContext(error: unknown, provider: string, operation: string): SandboxError;

package/dist/client/errors.js

@@ -0,0 +1,88 @@
+// Portable error wrappers are handwritten. ErrorInfo / ErrorKind remain
+// protobuf-owned contract data.
+import { ErrorKind as ProtoErrorKind } from "@sandbox-kit/contracts/sandbox";
+import { protoEnum } from "#internal/proto_enum.js";
+// Ergonomic PascalCase names over protobuf enum values; not a second contract.
+export const ErrorKind = protoEnum(ProtoErrorKind);
+export class SandboxError extends Error {
+    kind;
+    provider;
+    operation;
+    field;
+    rule;
+    statusCode;
+    providerCode;
+    providerSource;
+    constructor(info, options) {
+        super(info.message, options);
+        this.name = "SandboxError";
+        this.kind = info.kind;
+        this.provider = info.provider;
+        this.operation = info.operation;
+        this.field = info.field;
+        this.rule = info.rule;
+        this.statusCode = info.statusCode;
+        this.providerCode = info.providerCode;
+        this.providerSource = info.providerSource;
+    }
+}
+export function sandboxError(info, cause) {
+    return new SandboxError(info, cause === undefined ? undefined : { cause });
+}
+export function unsupported(provider, operation) {
+    throw sandboxError({
+        kind: ErrorKind.Unsupported,
+        provider,
+        operation,
+        field: "",
+        message: "sandbox-kit: provider does not support " + operation,
+    });
+}
+export function withContext(error, provider, operation) {
+    if (error instanceof SandboxError) {
+        if (error.provider === provider && error.operation === operation)
+            return error;
+        return sandboxError({
+            kind: error.kind,
+            provider: error.provider || provider,
+            operation: error.operation || operation,
+            field: error.field,
+            message: error.message,
+            ...(error.rule === undefined ? {} : { rule: error.rule }),
+            ...(error.statusCode === undefined
+                ? {}
+                : { statusCode: error.statusCode }),
+            ...(error.providerCode === undefined
+                ? {}
+                : { providerCode: error.providerCode }),
+            ...(error.providerSource === undefined
+                ? {}
+                : { providerSource: error.providerSource }),
+        }, error.cause);
+    }
+    if (error instanceof DOMException && error.name === "AbortError")
+        return sandboxError({
+            kind: ErrorKind.Canceled,
+            provider,
+            operation,
+            field: "",
+            message: error.message,
+        }, error);
+    if (error instanceof DOMException && error.name === "TimeoutError")
+        return sandboxError({
+            kind: ErrorKind.Timeout,
+            provider,
+            operation,
+            field: "",
+            message: error.message,
+        }, error);
+    return sandboxError({
+        kind: ErrorKind.Unknown,
+        provider,
+        operation,
+        field: "",
+        message: error instanceof Error
+            ? error.message
+            : "sandbox-kit: provider operation failed",
+    }, error);
+}

package/dist/client/operation.d.ts

@@ -0,0 +1,12 @@
+import type { OperationOptions } from "#client/types.js";
+export declare function clone<T>(value: T): T;
+export declare function operationSignal(options: OperationOptions, inheritedTimeoutMs?: number): {
+    signal?: AbortSignal;
+    dispose(): void;
+};
+export declare function operationOptions(options: OperationOptions, signal: AbortSignal | undefined): OperationOptions;
+export declare function awaitWithSignal<T>(operation: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+/** Lifecycle request timeouts stay milliseconds for Backend / providers. */
+export declare function publicTimeoutOptions(options: OperationOptions): {
+    timeout?: number;
+};

package/dist/client/operation.js

@@ -0,0 +1,73 @@
+// Operation deadline / AbortSignal helpers shared by Client and Sandbox.
+import { ConfigFieldTimeout } from "#contracts/config_paths.js";
+import { ErrorKind, sandboxError } from "#client/errors.js";
+export function clone(value) {
+    return structuredClone(value);
+}
+export function operationSignal(options, inheritedTimeoutMs) {
+    const timeout = options.timeout ?? inheritedTimeoutMs;
+    if (timeout !== undefined && (!Number.isFinite(timeout) || timeout < 0)) {
+        throw sandboxError({
+            kind: ErrorKind.InvalidArgument,
+            provider: "",
+            operation: "",
+            field: ConfigFieldTimeout,
+            message: "sandbox-kit: timeout must be a finite non-negative number",
+        });
+    }
+    if ((timeout === undefined || timeout === 0) && options.signal === undefined)
+        return { dispose() { } };
+    const controller = new AbortController();
+    const abort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted)
+        abort();
+    else
+        options.signal?.addEventListener("abort", abort, { once: true });
+    const timer = timeout !== undefined && timeout > 0
+        ? setTimeout(() => controller.abort(new DOMException("The operation timed out", "TimeoutError")), timeout)
+        : undefined;
+    return {
+        signal: controller.signal,
+        dispose() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+        },
+    };
+}
+export function operationOptions(options, signal) {
+    return {
+        ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+        ...(signal === undefined ? {} : { signal }),
+    };
+}
+function abortReason(signal) {
+    const reason = signal.reason;
+    return reason instanceof DOMException &&
+        (reason.name === "AbortError" || reason.name === "TimeoutError")
+        ? reason
+        : new DOMException("The operation was aborted", "AbortError");
+}
+export async function awaitWithSignal(operation, signal) {
+    if (signal?.aborted)
+        throw abortReason(signal);
+    const pending = operation();
+    if (signal === undefined)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const aborted = () => reject(abortReason(signal));
+        const cleanup = () => signal.removeEventListener("abort", aborted);
+        signal.addEventListener("abort", aborted, { once: true });
+        pending.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+/** Lifecycle request timeouts stay milliseconds for Backend / providers. */
+export function publicTimeoutOptions(options) {
+    return options.timeout === undefined ? {} : { timeout: options.timeout };
+}

package/dist/client/sandbox.d.ts

@@ -0,0 +1,33 @@
+import { type ExitResult, type LifecycleCapability, type SandboxInfo } from "#contracts/sandbox_data_contracts.js";
+import type { Backend, DeleteCallOptions, OperationOptions, StopCallOptions, TerminateCallOptions } from "#client/types.js";
+/** Coordinates sandbox operations with client closure. */
+export interface ClientLifecycle {
+    begin(operation: string): () => void;
+    isClosed(): boolean;
+}
+export declare const sandboxConstructorToken: unique symbol;
+/** Internal construction inputs for {@link Sandbox}; only Client may call. */
+export interface SandboxInit {
+    backend: Backend;
+    owner: ClientLifecycle;
+    info: SandboxInfo;
+    timeout?: number;
+}
+export declare class Sandbox implements AsyncDisposable {
+    #private;
+    constructor(token: typeof sandboxConstructorToken, init: SandboxInit);
+    get id(): string;
+    get providerName(): string;
+    info(): SandboxInfo;
+    capabilities(): readonly LifecycleCapability[];
+    supports(capability: LifecycleCapability): boolean;
+    refresh(options?: OperationOptions): Promise<SandboxInfo>;
+    start(options?: OperationOptions): Promise<SandboxInfo>;
+    stop(options?: StopCallOptions): Promise<SandboxInfo>;
+    pause(options?: OperationOptions): Promise<SandboxInfo>;
+    terminate(options?: TerminateCallOptions): Promise<ExitResult>;
+    archive(options?: OperationOptions): Promise<SandboxInfo>;
+    delete(options?: DeleteCallOptions): Promise<SandboxInfo>;
+    close(options?: OperationOptions): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}