@sandbox-kit/sandbox 0.1.0 → 0.1.2

package/README.md

@@ -1,70 +1,130 @@
-# Sandbox Kit for TypeScript
+# `@sandbox-kit/sandbox`
 
-Core client package (`@sandbox-kit/sandbox`). Providers such as
-`@sandbox-kit/daytona` and `@sandbox-kit/modal` are published
-separately and plug into this module. Apps and providers share public
-`CreateOptions` / `ClientConfig` (`Config` plus `provider`): nested exclusive
-fields (`auth: { apiKey: … }`, `source: { image: … }`, `readiness: { command: … }`),
-plain maps/allowlists (`outboundCidrs: string[]`), and millisecond timeouts.
-`ErrorInfo.field` uses canonical protobuf paths (`CreateField*` / `ConfigField*` /
-`InfoField*`), matching Go. Closing the client releases local provider SDK
-resources only; it does not stop or delete cloud sandboxes.
+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.
 
-## Public input → wire boundary
+Closing a client or handle releases **local** SDK resources only. It does not
+stop, terminate, or delete the remote sandbox.
 
-Applications and provider backends speak the **public** shapes above. Inside
-`Client`, requests are converted before Protovalidate and provider mapping:
+## Install
 
-1. **Public input** — ms numbers, nested oneofs, `string[]` allowlists, plain
-   `providerOptions` maps.
-2. **`materialize*`** — package-private conversion to protobuf wire messages.
-3. **Validate** — shared Protovalidate rules (`secure_endpoint` stays handwritten),
-   then provider checks.
-4. **Provider mappings** — native SDK calls using the validated wire request.
+```sh
+npm install @sandbox-kit/sandbox @sandbox-kit/daytona
+# or
+npm install @sandbox-kit/sandbox @sandbox-kit/modal
+```
 
-Wire types stay package-private to the client.
+Requires Node.js 20, 22, or 24.15+.
 
-## Usage
+## Quick start
 
 ```ts
-import {
-  Client,
-  type ClientConfig,
-  type CreateOptions,
-} from "@sandbox-kit/sandbox";
 import { daytona } from "@sandbox-kit/daytona";
+import { Client } from "@sandbox-kit/sandbox";
 
-const config: ClientConfig = {
+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:
 
-const createOptions: CreateOptions = {
+| 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
 
-await using client = new Client(config);
-const sandbox = await client.create(createOptions);
-console.log(sandbox.id);
+```ts
+const attached = await client.attach(id); // provider must support attach
+const fetched = await client.get(id); // provider-verified lookup
 ```
 
-Prefer `await using` when the runtime supports explicit resource management;
-otherwise call `await client.close()` in `finally`. Both forms have identical
-cleanup semantics.
+## Sandbox handle
 
-## Examples
+| 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) |
 
-| Language   | Index                                                         |
-| ---------- | ------------------------------------------------------------- |
-| TypeScript | [examples/typescript](../../../examples/typescript/README.md) |
-| Go         | [examples/go](../../../examples/go/README.md)                 |
+Unsupported operations throw before the provider call. Use `supports(...)` when
+the sandbox class may differ (for example Daytona container vs VM).
 
-```sh
-npm install @sandbox-kit/sandbox @sandbox-kit/daytona
-# or: npm install @sandbox-kit/sandbox @sandbox-kit/modal
+## 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;
+  }
+}
 ```
 
-See the [root README](../../../README.md) for a full create snippet and the
-[TypeScript workspace README](../README.md) for local development.
+## 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

@@ -1,128 +1,10 @@
-import { type MessageInitShape } from "@bufbuild/protobuf";
-import { ConfigSchema, type APIKeyCredentials as WireAPIKeyCredentials, type AuthConfig, type BearerTokenCredentials as WireBearerTokenCredentials, type OAuthCredentials as WireOAuthCredentials, type TokenPairCredentials as WireTokenPairCredentials } from "@sandbox-kit/contracts/client";
-import { ErrorKind as ProtoErrorKind } from "@sandbox-kit/contracts/sandbox";
-import { type ArchiveOptions, type CreateOptions, type CreateResult, type DeleteOptions, type ErrorInfo, type ExitResult, type LifecycleCapability, type PauseOptions, type SandboxInfo, type StartOptions, type StopOptions, type TerminateOptions } from "#contracts/sandbox_data_contracts.js";
-import { type DurationFieldsToMs } from "#internal/duration_ms.js";
-import type { RemapFields } from "#internal/input_remap.js";
-import type { FlattenOneof } from "#internal/oneof_input.js";
-import type { StripProto } from "#internal/strip_proto.js";
-/** Public credential shapes (no protobuf `$typeName` / getters). */
-export type APIKeyCredentials = StripProto<WireAPIKeyCredentials>;
-export type TokenPairCredentials = StripProto<WireTokenPairCredentials>;
-export type BearerTokenCredentials = StripProto<WireBearerTokenCredentials>;
-export type OAuthCredentials = StripProto<WireOAuthCredentials>;
-export type Scope = StripProto<import("@sandbox-kit/contracts/client").Scope>;
-/** Public auth: set exactly one credential variant (no protobuf `{ case, value }`). */
-export type AuthInput = FlattenOneof<NonNullable<AuthConfig["credentials"]>>;
-/**
- * Public client settings (ms timeout, flat auth).
- * Prefer {@link ClientConfig} at construction (`Config` plus `provider`).
- */
-export type Config = DurationFieldsToMs<RemapFields<StripProto<MessageInitShape<typeof ConfigSchema>>, {
-    auth: AuthInput;
-}>>;
-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 interface OperationOptions {
-    readonly signal?: AbortSignal;
-    /** Operation deadline in milliseconds. */
-    readonly timeout?: number;
-}
-/** Public stop options: Kit call options plus optional force. */
-export type StopCallOptions = OperationOptions & {
-    readonly force?: boolean;
-};
-/** Public terminate options: Kit call options plus optional wait. */
-export type TerminateCallOptions = OperationOptions & {
-    readonly wait?: boolean;
-};
-/** Public delete options: Kit call options plus optional wait. */
-export type DeleteCallOptions = OperationOptions & {
-    readonly wait?: boolean;
-};
-export interface Backend {
-    readonly name: string;
-    create?(request: CreateOptions, options: OperationOptions): Promise<CreateResult>;
-    attach?(id: string, options: OperationOptions): Promise<SandboxInfo>;
-    refresh?(id: string, options: OperationOptions): Promise<SandboxInfo>;
-    start?(id: string, request: StartOptions, options: OperationOptions): Promise<SandboxInfo>;
-    stop?(id: string, request: StopOptions, options: OperationOptions): Promise<SandboxInfo>;
-    pause?(id: string, request: PauseOptions, options: OperationOptions): Promise<SandboxInfo>;
-    terminate?(id: string, request: TerminateOptions, options: OperationOptions): Promise<ExitResult>;
-    archive?(id: string, request: ArchiveOptions, options: OperationOptions): Promise<SandboxInfo>;
-    delete?(id: string, request: DeleteOptions, options: OperationOptions): Promise<SandboxInfo>;
-    close(options: OperationOptions): Promise<void>;
-    closeSandbox?(id: string, options: OperationOptions): Promise<void>;
-    capabilities?(info: SandboxInfo): readonly LifecycleCapability[];
-}
-export interface Provider {
-    readonly name: string;
-    /** Receives public {@link Config}. */
-    initialize(config: Config): Backend;
-}
-/** Provider selection stays handwritten and is never part of the portable Config message. */
-export type ClientConfig = Config & {
-    readonly provider: Provider;
-};
-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;
-/**
- * Rejects public {@link CreateOptions} the shared contract cannot represent.
- * Materializes wire form privately for Protovalidate. Provider-specific checks
- * remain in each provider adapter.
- */
-export declare function validateCreateOptions(value: CreateOptions, provider?: string, operation?: string): void;
-export declare function validateConfig(value: Config, provider?: string, operation?: string): void;
-interface ClientLifecycle {
-    begin(operation: string): () => void;
-    isClosed(): boolean;
-}
-declare const sandboxConstructorToken: unique symbol;
-export declare class Sandbox implements AsyncDisposable {
-    #private;
-    constructor(token: typeof sandboxConstructorToken, backend: Backend, owner: ClientLifecycle, info: SandboxInfo, timeout?: number);
-    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>;
-}
+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);
@@ -133,4 +15,3 @@ export declare class Client implements AsyncDisposable {
     close(options?: OperationOptions): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }
-export {};