@sandbox-kit/sandbox 0.0.0-stage → 0.1.1

package/dist/contracts/sandbox_data_contracts.js

@@ -0,0 +1,22 @@
+// Portable sandbox data contracts come from standard protobuf generation.
+// These aliases keep the SDK entrypoint concise while ensuring one representation.
+import { EgressMode as ProtoEgressMode, IsolationKind as ProtoIsolationKind, LifecycleCapability as ProtoLifecycleCapability, PolicyMode as ProtoPolicyMode, PortTransport as ProtoPortTransport, SandboxState as ProtoSandboxState, SecretInjection as ProtoSecretInjection, SnapshotKind as ProtoSnapshotKind, ValueOrigin as ProtoValueOrigin, WaitCondition as ProtoWaitCondition, } 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 SnapshotKind = protoEnum(ProtoSnapshotKind);
+export const SnapshotKindNumber = SnapshotKind;
+export const IsolationKind = protoEnum(ProtoIsolationKind);
+export const IsolationKindNumber = IsolationKind;
+export const EgressMode = protoEnum(ProtoEgressMode);
+export const EgressModeNumber = EgressMode;
+export const PortTransport = protoEnum(ProtoPortTransport);
+export const PortTransportNumber = PortTransport;
+export const SecretInjection = protoEnum(ProtoSecretInjection);
+export const SecretInjectionNumber = SecretInjection;
+export const PolicyMode = protoEnum(ProtoPolicyMode);
+export const PolicyModeNumber = PolicyMode;
+export const WaitCondition = protoEnum(ProtoWaitCondition);
+export const WaitConditionNumber = WaitCondition;
+export const SandboxState = protoEnum(ProtoSandboxState);
+export const LifecycleCapability = protoEnum(ProtoLifecycleCapability);
+export const ValueOrigin = protoEnum(ProtoValueOrigin);

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "#contracts/sandbox_data_contracts.js";
+export * from "#contracts/field_paths.js";
+export * from "#contracts/config_paths.js";
+export * from "#metadata/metadata_object.js";
+export * from "#client/client.js";
+export { validCidr, validDomain, validEnvName, } from "#internal/net_validate.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "#contracts/sandbox_data_contracts.js";
+export * from "#contracts/field_paths.js";
+export * from "#contracts/config_paths.js";
+export * from "#metadata/metadata_object.js";
+export * from "#client/client.js";
+export { validCidr, validDomain, validEnvName, } from "#internal/net_validate.js";

package/dist/internal/duration_ms.d.ts

@@ -0,0 +1,15 @@
+import { type Duration } from "@bufbuild/protobuf/wkt";
+/** True when a value looks like a protobuf Duration message or init. */
+export declare function isDurationValue(value: unknown): value is Duration;
+type DurationFieldName = "timeout" | "queueTimeout" | "maximumLifetime" | "after";
+/**
+ * Recursively replace known protobuf Duration fields with millisecond numbers
+ * for public request construction. Field-name based so maps like `labels` are
+ * left alone. Public values are always milliseconds.
+ */
+export type DurationFieldsToMs<T> = T extends readonly (infer U)[] ? DurationFieldsToMs<U>[] : T extends object ? {
+    [K in keyof T]: K extends DurationFieldName ? undefined extends T[K] ? number | undefined : number : DurationFieldsToMs<T[K]>;
+} : T;
+/** Convert public ms numbers on known duration fields into protobuf Durations. */
+export declare function materializeDurationFields<T>(value: T): T;
+export {};

package/dist/internal/duration_ms.js

@@ -0,0 +1,41 @@
+import { durationFromMs } from "@bufbuild/protobuf/wkt";
+/** True when a value looks like a protobuf Duration message or init. */
+export function isDurationValue(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        ("seconds" in value || "nanos" in value) &&
+        !Array.isArray(value));
+}
+const durationFieldNames = new Set([
+    "timeout",
+    "queueTimeout",
+    "maximumLifetime",
+    "after",
+]);
+/** Convert public ms numbers on known duration fields into protobuf Durations. */
+export function materializeDurationFields(value) {
+    return materializeDurationFieldsAt(value, []);
+}
+function materializeDurationFieldsAt(value, path) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "number") {
+        const leaf = path[path.length - 1];
+        if (leaf !== undefined && durationFieldNames.has(leaf)) {
+            return durationFromMs(value);
+        }
+        return value;
+    }
+    if (typeof value !== "object")
+        return value;
+    if (isDurationValue(value))
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((item) => materializeDurationFieldsAt(item, path));
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        out[key] = materializeDurationFieldsAt(child, [...path, key]);
+    }
+    return out;
+}

package/dist/internal/input_remap.d.ts

@@ -0,0 +1,36 @@
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type PreserveOptional<Orig, New> = undefined extends Orig ? New | undefined : New;
+/**
+ * Replace selected fields with R[K], keeping each field's optionality from T.
+ * Prefer this over call-site `Omit<T, K> & { K?: New }`. Keys in R that are
+ * absent from T are ignored; only overlapping keys are rewritten.
+ */
+export type RemapFields<T, R> = Simplify<{
+    [K in keyof T]: K extends keyof R ? PreserveOptional<T[K], R[K]> : T[K];
+}>;
+type AllowlistField = "outboundCidrs" | "outboundDomains" | "inboundCidrs";
+/**
+ * Recursively unwrap StringAllowlist-shaped fields to plain `string[]`.
+ * Present empty arrays still mean deny-all after materialize.
+ */
+export type FlattenAllowlistFields<T> = T extends readonly (infer U)[] ? FlattenAllowlistFields<U>[] : T extends object ? {
+    [K in keyof T]: K extends AllowlistField ? PreserveOptional<T[K], string[]> : FlattenAllowlistFields<T[K]>;
+} : T;
+type EmptyMarkerField = "providerDefault";
+/**
+ * Recursively turn empty wire marker messages into `true` presence flags
+ * (e.g. `source.providerDefault?: true`).
+ */
+export type EmptyMarkersAsTrue<T> = T extends readonly (infer U)[] ? EmptyMarkersAsTrue<U>[] : T extends object ? {
+    [K in keyof T]: K extends EmptyMarkerField ? PreserveOptional<T[K], true> : EmptyMarkersAsTrue<T[K]>;
+} : T;
+type StringMapField = "environment" | "labels";
+/**
+ * Recursively replace noisy proto string maps with `Record<string, string>`.
+ */
+export type PlainStringMapFields<T> = T extends readonly (infer U)[] ? PlainStringMapFields<U>[] : T extends object ? {
+    [K in keyof T]: K extends StringMapField ? PreserveOptional<T[K], Record<string, string>> : PlainStringMapFields<T[K]>;
+} : T;
+export {};

package/dist/internal/input_remap.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/net_validate.d.ts

@@ -0,0 +1,4 @@
+/** Shared network / env name validators used by provider create checks. */
+export declare function validEnvName(value: string): boolean;
+export declare function validDomain(value: string): boolean;
+export declare function validCidr(value: string): boolean;

package/dist/internal/net_validate.js

@@ -0,0 +1,53 @@
+/** Shared network / env name validators used by provider create checks. */
+export function validEnvName(value) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+export function validDomain(value) {
+    const domain = value.startsWith("*.") ? value.slice(2) : value;
+    return (domain.length <= 253 &&
+        /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.?$/i.test(domain));
+}
+export function validCidr(value) {
+    const separator = value.lastIndexOf("/");
+    if (separator <= 0)
+        return false;
+    const address = value.slice(0, separator);
+    const prefix = Number(value.slice(separator + 1));
+    if (!Number.isInteger(prefix))
+        return false;
+    return address.includes(":")
+        ? prefix >= 0 && prefix <= 128 && validIpv6(address)
+        : prefix >= 0 && prefix <= 32 && validIpv4(address);
+}
+function validIpv4(value) {
+    const parts = value.split(".");
+    return (parts.length === 4 &&
+        parts.every((part) => /^(0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
+}
+function validIpv6(value) {
+    if ((value.match(/::/g)?.length ?? 0) > 1)
+        return false;
+    const halves = value.split("::");
+    if (halves.length > 2)
+        return false;
+    const count = (part) => {
+        if (part === "")
+            return 0;
+        const groups = part.split(":");
+        let total = 0;
+        for (const group of groups) {
+            if (/^[0-9a-f]{1,4}$/i.test(group))
+                total++;
+            else if (validIpv4(group))
+                total += 2;
+            else
+                return undefined;
+        }
+        return total;
+    };
+    const left = count(halves[0] ?? "");
+    const right = count(halves[1] ?? "");
+    return (left !== undefined &&
+        right !== undefined &&
+        (halves.length === 2 ? left + right < 8 : left === 8));
+}

package/dist/internal/oneof_input.d.ts

@@ -0,0 +1,32 @@
+import type { RemapFields } from "./input_remap.js";
+import type { StripProto } from "./strip_proto.js";
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type ProtoOneof = {
+    case: string | undefined;
+    value?: unknown;
+};
+/**
+ * Derive nested exclusive input fields from a protobuf-es `{ case, value }` oneof.
+ * Variant payloads are StripProto'd (no `$typeName` / `$unknown`).
+ */
+export type FlattenOneof<T extends ProtoOneof> = Simplify<{
+    [K in Exclude<T["case"], undefined>]?: StripProto<Exclude<Extract<T, {
+        case: K;
+    }>["value"], undefined>>;
+}>;
+/**
+ * Strip protobuf-es internals, then replace listed fields with flattened oneof
+ * bags. Use when a wire field is a carrier message whose oneof should surface
+ * as exclusive keys on the public input (e.g. `source.kind` → `source.image`).
+ *
+ * `Oneofs` maps each remapped field to the oneof union to flatten.
+ * Further public remaps (allowlists, ms durations, plain maps) compose outside.
+ */
+export type StripAndFlatten<T, Oneofs extends {
+    [K in keyof Oneofs]: K extends keyof T ? ProtoOneof : never;
+}> = RemapFields<StripProto<T>, {
+    [K in keyof Oneofs & string]: FlattenOneof<Oneofs[K]>;
+}>;
+export {};

package/dist/internal/oneof_input.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/proto_enum.d.ts

@@ -0,0 +1,25 @@
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** `ALLOW_ALL` → `AllowAll`, `HTTP2_TLS` → `Http2Tls`. */
+type SnakeToPascal<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Capitalize<Lowercase<Head>>}${SnakeToPascal<Tail>}` : Capitalize<Lowercase<S>>;
+/** Forward protobuf-es enum member names (skip reverse numeric keys). */
+type EnumMemberKeys<E> = {
+    [K in keyof E]: K extends string ? E[K] extends number ? K extends `${number}` ? never : K : never : never;
+}[keyof E];
+/**
+ * Public const object for a protobuf-es enum: PascalCase keys, same numeric
+ * values. Does not invent a second contract — only renames member keys.
+ */
+export type EnumConst<E> = Simplify<{
+    readonly [K in EnumMemberKeys<E> as SnakeToPascal<K & string>]: E[K];
+}>;
+/**
+ * Build an ergonomic enum const from a protobuf-es numeric enum object.
+ *
+ * @example
+ * export const EgressMode = protoEnum(ProtoEgressMode);
+ * // { Default: 0, AllowAll: 1, BlockAll: 2, Restricted: 3 }
+ */
+export declare function protoEnum<E extends Record<string, string | number>>(proto: E): EnumConst<E>;
+export {};

package/dist/internal/proto_enum.js

@@ -0,0 +1,25 @@
+function snakeToPascal(name) {
+    return name
+        .toLowerCase()
+        .split("_")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+/**
+ * Build an ergonomic enum const from a protobuf-es numeric enum object.
+ *
+ * @example
+ * export const EgressMode = protoEnum(ProtoEgressMode);
+ * // { Default: 0, AllowAll: 1, BlockAll: 2, Restricted: 3 }
+ */
+export function protoEnum(proto) {
+    const out = {};
+    for (const [key, value] of Object.entries(proto)) {
+        if (typeof value !== "number")
+            continue;
+        if (/^\d+$/.test(key))
+            continue;
+        out[snakeToPascal(key)] = value;
+    }
+    return out;
+}

package/dist/internal/strip_proto.d.ts

@@ -0,0 +1,46 @@
+import type { Duration, Timestamp } from "@bufbuild/protobuf/wkt";
+type ProtoKey = "$typeName" | "$unknown";
+/**
+ * True for proto3 map fields (`{ [key: string]: V }`), including non-string
+ * values such as `map<string, ValueOrigin>`. Not true for plain messages.
+ */
+type IsProtoMap<T> = T extends object ? string extends keyof T ? T extends readonly unknown[] ? false : true : false : false;
+/**
+ * Required proto3 maps/repeated/enums become optional for construction.
+ * protobuf-es enums are numeric, so required `number` fields soften too.
+ * Map *entry* keys (index signatures) are not softened — that would yield
+ * `Record<string, V | undefined>`.
+ */
+type SoftenField<V, K> = string extends K ? false : V extends readonly unknown[] ? true : IsProtoMap<V> extends true ? true : V extends number ? true : false;
+type OptionalKeys<T> = Exclude<{
+    [K in keyof T]-?: undefined extends T[K] ? K : never;
+}[keyof T], ProtoKey>;
+type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T> | ProtoKey>;
+type SoftenedKeys<T> = {
+    [K in RequiredKeys<T>]: SoftenField<T[K], K> extends true ? K : never;
+}[RequiredKeys<T>];
+type KeptRequiredKeys<T> = Exclude<RequiredKeys<T>, SoftenedKeys<T>>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type StripProtoObject<T> = Simplify<{
+    [K in OptionalKeys<T> & keyof T]?: StripProto<Exclude<T[K], undefined>>;
+} & {
+    [K in SoftenedKeys<T>]?: StripProto<T[K]>;
+} & {
+    [K in KeptRequiredKeys<T>]: StripProto<T[K]>;
+}>;
+/**
+ * Recursively drop protobuf-es message internals for public SDK types:
+ *
+ * - removes `$typeName` / `$unknown` at every level (including nested messages)
+ * - keeps normal field optionality
+ * - softens required proto3 maps/repeated/enums to optional
+ * - keeps wire `Duration` opaque for provider helpers
+ * - maps `Timestamp` to `Date`
+ *
+ * Nested messages are stripped in place, so aliases do not need `Omit` + remap
+ * just to clean child protobuf fields.
+ */
+export type StripProto<T> = T extends Duration ? Duration : T extends Timestamp ? Date : T extends string | number | boolean | bigint | null | undefined | symbol | Date | Uint8Array | ((...args: never[]) => unknown) ? T : T extends readonly (infer U)[] ? StripProto<U>[] : T extends object ? StripProtoObject<T> : T;
+export {};

package/dist/internal/strip_proto.js

@@ -0,0 +1 @@
+export {};

package/dist/metadata/metadata_object.d.ts

@@ -0,0 +1,7 @@
+import type { MetadataObject } from "#contracts/sandbox_data_contracts.js";
+import type { MetadataPlain } from "#metadata/metadata_plain.js";
+export type { MetadataPlain } from "#metadata/metadata_plain.js";
+/** Converts a declarative map into the protobuf metadata object. */
+export declare function metadataObjectFromMap(source: Record<string, MetadataPlain> | undefined): MetadataObject | undefined;
+/** Converts a protobuf metadata object into a declarative map. */
+export declare function metadataObjectAsMap(source: MetadataObject | undefined): Record<string, MetadataPlain> | undefined;

package/dist/metadata/metadata_object.js

@@ -0,0 +1,103 @@
+// Handwritten helpers for protobuf metadata objects (mirrors Go sandbox metadata helpers).
+import { create } from "@bufbuild/protobuf";
+import { MetadataListSchema, MetadataObjectSchema, MetadataValueSchema, } from "@sandbox-kit/contracts/sandbox";
+/** Converts a declarative map into the protobuf metadata object. */
+export function metadataObjectFromMap(source) {
+    if (source === undefined)
+        return undefined;
+    const values = {};
+    for (const [key, value] of Object.entries(source)) {
+        values[key] = metadataValueFromPlain(value);
+    }
+    return create(MetadataObjectSchema, { values });
+}
+/** Converts a protobuf metadata object into a declarative map. */
+export function metadataObjectAsMap(source) {
+    if (source === undefined)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(source.values ?? {})) {
+        out[key] = metadataValueAsPlain(value);
+    }
+    return out;
+}
+function metadataValueFromPlain(value) {
+    // create() returns a protobuf Message; public aliases are StripProto shapes.
+    if (value === null)
+        return create(MetadataValueSchema, {});
+    if (typeof value === "boolean")
+        return create(MetadataValueSchema, {
+            value: { case: "boolean", value },
+        });
+    if (typeof value === "string")
+        return create(MetadataValueSchema, {
+            value: { case: "text", value },
+        });
+    if (typeof value === "bigint") {
+        if (value < 0n)
+            return create(MetadataValueSchema, {
+                value: { case: "signedInteger", value },
+            });
+        return create(MetadataValueSchema, {
+            value: { case: "unsignedInteger", value },
+        });
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("sandbox-kit: metadata numbers must be finite");
+        }
+        if (Number.isInteger(value)) {
+            const asBigInt = BigInt(value);
+            if (value < 0)
+                return create(MetadataValueSchema, {
+                    value: { case: "signedInteger", value: asBigInt },
+                });
+            return create(MetadataValueSchema, {
+                value: { case: "unsignedInteger", value: asBigInt },
+            });
+        }
+        return create(MetadataValueSchema, {
+            value: { case: "number", value },
+        });
+    }
+    if (value instanceof Uint8Array)
+        return create(MetadataValueSchema, {
+            value: { case: "binary", value },
+        });
+    if (Array.isArray(value)) {
+        return create(MetadataValueSchema, {
+            value: {
+                case: "list",
+                value: create(MetadataListSchema, {
+                    values: value.map(metadataValueFromPlain),
+                }),
+            },
+        });
+    }
+    return create(MetadataValueSchema, {
+        value: {
+            case: "object",
+            value: metadataObjectFromMap(value),
+        },
+    });
+}
+function metadataValueAsPlain(value) {
+    switch (value.value?.case) {
+        case undefined:
+            return null;
+        case "boolean":
+        case "text":
+        case "number":
+        case "binary":
+            return value.value.value;
+        case "signedInteger":
+        case "unsignedInteger":
+            return value.value.value;
+        case "list":
+            return (value.value.value?.values ?? []).map(metadataValueAsPlain);
+        case "object":
+            return metadataObjectAsMap(value.value.value) ?? {};
+        default:
+            return null;
+    }
+}

package/dist/metadata/metadata_plain.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Plain JSON-like values accepted for public metadata / providerOptions maps.
+ * Nested objects use an interface so IDEs do not expand the recursive union.
+ */
+export type MetadataPlain = null | boolean | string | number | bigint | Uint8Array | MetadataPlain[] | MetadataPlainObject;
+/** Nested object branch of {@link MetadataPlain}. */
+export interface MetadataPlainObject {
+    [key: string]: MetadataPlain;
+}

package/dist/metadata/metadata_plain.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@sandbox-kit/sandbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "one pluggable sdk for all your sandbox providers",
+  "keywords": [
+    "sandbox-kit",
+    "sandbox",
+    "sdk"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "npm@11.19.0",
+  "engines": {
+    "node": "^20.0.0 || ^22.0.0 || >=24.15.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sandbox-kit/kit.git",
+    "directory": "sdks/typescript/sandbox"
+  },
+  "homepage": "https://github.com/sandbox-kit/kit/tree/main/sdks/typescript/sandbox",
+  "bugs": {
+    "url": "https://github.com/sandbox-kit/kit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "imports": {
+    "#client/*.js": {
+      "@sandbox-kit/source": "./src/client/*.ts",
+      "default": "./dist/client/*.js"
+    },
+    "#contracts/*.js": {
+      "@sandbox-kit/source": "./src/contracts/*.ts",
+      "default": "./dist/contracts/*.js"
+    },
+    "#metadata/*.js": {
+      "@sandbox-kit/source": "./src/metadata/*.ts",
+      "default": "./dist/metadata/*.js"
+    },
+    "#internal/*.js": {
+      "@sandbox-kit/source": "./src/internal/*.ts",
+      "default": "./dist/internal/*.js"
+    }
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "2.16.0",
+    "@bufbuild/protovalidate": "1.3.0",
+    "@sandbox-kit/contracts": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  }
+}