@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

Three 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 types, which import and re-export their domain and snapshot dependencies.
• src/domain.ts — only the domain types the cloud twins transitively reference (EnvVar, Rlimit, NetworkPolicy, …).
• src/snapshot.ts — the canonical snapshot manifest schema embedded by cloud snapshot resources.

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 {
  CloudCreateSandboxRequest,
  CloudSnapshot,
  CloudSnapshotOperation,
} from "@microsandbox/types";

function createSandbox(request: CloudCreateSandboxRequest) {
  // POST the source-tagged request to the cloud API
}

CloudCreateSnapshotRequest and CloudSnapshot are unions discriminated by kind; the current public variant is "disk". CloudSnapshotOperation carries that same kind and exposes only the public statuses queued, in_progress, succeeded, and failed. Both snapshot creation results and disk-snapshot restore requests use CloudSnapshotLocation to distinguish a managed artifact ID from a host-volume path.

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.
• CloudCreateSandboxRequest is a flat union discriminated by source: "oci" | "bind" | "disk_image" | "disk_snapshot". Common sandbox fields stay flat on every variant; source-specific fields such as reference, path, and disk_snapshot_ref appear only where they apply. Servers also accept the legacy image request shape without source during migration.
• CloudCreateSnapshotRequest and CloudSnapshot are flat unions discriminated by the current kind: "disk"; common snapshot fields stay flat beside the discriminator.
• Lowercase domain enums like StatVirtualization are string-literal unions ("strict" | "relaxed" | "off").
• Optional Rust fields are T | null; fields skipped when absent are ?: optional.
• Referenced domain and snapshot types live in domain.ts and snapshot.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