@microsandbox/types

Shared task and wire contract types for microsandbox, as TypeScript.

This package is the type-only mirror of the cloud contract in the microsandbox-types Rust crate. It gives TypeScript consumers (the cloud front end and anything talking to the cloud API) the exact cloud wire shapes microsandbox uses, so a CloudSandboxSpec means the same thing on both sides of the wire. Only the domain types the cloud contract references are generated; the broader SDK/domain surface is not.

It contains no runtime code. Every export is a type; importing it adds nothing to your bundle.

Generated, Not Hand-Written

Two files are generated from the Rust crate with ts-rs, each carrying a // @generated header. Do not edit them:

• src/cloud.ts — the package entry: the cloud wire twins (CloudSandboxSpec, CloudVolumeMount, CloudSecretsConfig, …), which import and re-export their domain deps from ./domain.
• src/domain.ts — only the domain types the cloud twins transitively reference (EnvVar, Rlimit, NetworkPolicy, …).

To change a shape, edit the Rust type and regenerate from the repo root:

cargo run -p microsandbox-types --features ts --bin microsandbox-types-generate

Install

npm install @microsandbox/types

Usage

Import the shapes you need with import type:

import type { CloudSandboxSpec, CloudRootfsSource } from "@microsandbox/types";

const image: CloudRootfsSource = { type: "oci", reference: "python" };

function createSandbox(spec: CloudSandboxSpec) {
  // POST spec to the cloud API
}

Generated Shape Notes

The bindings follow ts-rs conventions, which mirror the Rust serde representation:

• Cloud enums are internally tagged with a type field: CloudRootfsSource is { type: "bind"; … } | { type: "oci"; reference: string } | { type: "disk_image"; … }, and CloudVolumeMount / CloudHostPattern / CloudViolationAction follow the same shape.
• Lowercase domain enums like StatVirtualization are string-literal unions ("strict" | "relaxed" | "off").
• Optional Rust fields are T | null; fields skipped when absent are ?: optional.
• The domain types the cloud references (EnvVar, Rlimit, NetworkPolicy, …) live in domain.ts and are re-exported from the package entry, so a single import from @microsandbox/types sees the whole cloud contract.

Build And Typecheck

npm run build       # tsc -> dist/
npm run typecheck   # tsc --noEmit