@sandbox-kit/sandbox 0.0.0-stage → 0.1.0

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,70 @@
-# Temporary Holding Version
+# Sandbox Kit for TypeScript
 
-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.
+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.
+
+## Public input → wire boundary
+
+Applications and provider backends speak the **public** shapes above. Inside
+`Client`, requests are converted before Protovalidate and provider mapping:
+
+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.
+
+Wire types stay package-private to the client.
+
+## Usage
+
+```ts
+import {
+  Client,
+  type ClientConfig,
+  type CreateOptions,
+} from "@sandbox-kit/sandbox";
+import { daytona } from "@sandbox-kit/daytona";
+
+const config: ClientConfig = {
+  provider: daytona(),
+  auth: { apiKey: { key: process.env.DAYTONA_API_KEY! } },
+  timeout: 120_000,
+};
+
+const createOptions: CreateOptions = {
+  source: { image: { reference: "daytonaio/playground:latest" } },
+  provisioning: { timeout: 120_000 },
+};
+
+await using client = new Client(config);
+const sandbox = await client.create(createOptions);
+console.log(sandbox.id);
+```
+
+Prefer `await using` when the runtime supports explicit resource management;
+otherwise call `await client.close()` in `finally`. Both forms have identical
+cleanup semantics.
+
+## Examples
+
+| Language   | Index                                                         |
+| ---------- | ------------------------------------------------------------- |
+| TypeScript | [examples/typescript](../../../examples/typescript/README.md) |
+| Go         | [examples/go](../../../examples/go/README.md)                 |
+
+```sh
+npm install @sandbox-kit/sandbox @sandbox-kit/daytona
+# or: npm install @sandbox-kit/sandbox @sandbox-kit/modal
+```
+
+See the [root README](../../../README.md) for a full create snippet and the
+[TypeScript workspace README](../README.md) for local development.

package/dist/client/client.d.ts

@@ -0,0 +1,136 @@
+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>;
+}
+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>;
+}
+export {};