@machine0/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @machine0/sdk
 
-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.
+Typed Node.js/TypeScript SDK for the [machine0](https://machine0.io) API — cloud VMs from code.
+
+- **Zero dependencies.** A thin client over the global `fetch`. Works in plain Node ≥ 20.12, serverless runtimes (nodejs:22), and any modern bundler.
+- **Fully typed.** Inputs and outputs are compile-time checked against the live API's router inside the machine0 monorepo, plus runtime response-shape tests — the published types cannot silently drift from the server.
+- **ESM.** `import` works everywhere; `require("@machine0/sdk")` needs Node ≥ 20.19 / ≥ 22.12 (`require(esm)` support).
+
+## Install
+
+```bash
+npm install @machine0/sdk
+# or
+bun add @machine0/sdk
+```
+
+## Quickstart
+
+1. Create an API key: dashboard → **Account → API Tokens** ([app.machine0.io/account/tokens](https://app.machine0.io/account/tokens)).
+2. Keep it server-side. **Never ship an API key to a browser** — it grants full control of your machines.
+
+```ts
+import { createClient } from "@machine0/sdk";
+
+const m0 = createClient({ apiKey: process.env.MACHINE0_API_KEY! });
+
+// List machines
+const machines = await m0.machines.list();
+
+// Create one
+const created = await m0.machines.create({
+  name: "worker-1",
+  size: "large",
+  region: "us-east",
+  imageName: "ubuntu-25-04-x64",
+});
+
+// Fetch full details (IP appears once it's RUNNING)
+const machine = await m0.machines.getByName({ name: "worker-1" });
+console.log(machine.status, machine.ip, machine.url);
+
+// Metrics (if created with metricsEnabled: true)
+const { points } = await m0.machines.metrics({ id: created.id, range: "1h" });
+
+// Destroy it
+await m0.machines.destroy({ id: created.id });
+```
+
+## API surface (v1)
+
+| Resource | Methods |
+|---|---|
+| `machines` | `list()`, `get({id})`, `getByName({name})`, `create(input)`, `update(input)`, `start/stop/reboot/suspend/destroy({id})`, `metrics({id, range: "1h" \| "24h" \| "7d"})` |
+| `images` | `list()`, `get({id})` |
+| `sshKeys` | `list()`, `get({name})`, `create(input)`, `update({name, isDefault})`, `destroy({id})` |
+
+Notes:
+- Lifecycle mutations (`start`, `stop`, `reboot`, `suspend`, `destroy`) are asynchronous on the server — they return `{success: true}` immediately and the machine transitions through states (`STARTING`, `STOPPING`, …). Poll `get()` to observe progress.
+- `machines.create` responds before the image join exists, so the created machine lacks `image`/`distribution` — call `get()` if you need them right away.
+- `sshKeys.create({type: "MANAGED", name})` returns the plaintext `privateKey` — store it. (Managed keys are retrievable later through the CLI's `machine0 keys get <name> --download`; this SDK deliberately never requests the private key after creation.)
+- All date fields are ISO-8601 strings.
+
+## Options
+
+```ts
+createClient({
+  apiKey: "m0_...",                      // required
+  apiUrl: "https://app.machine0.io",     // default; point at a dev server to test locally
+  timeoutMs: 30_000,                     // per-request timeout, default 30s
+});
+```
+
+## Error handling
+
+Three distinct error classes, deliberately not collapsed:
+
+```ts
+import { Machine0ApiError } from "@machine0/sdk/errors";
+
+try {
+  await m0.machines.start({ id });
+} catch (err) {
+  // Prefer the name check if your bundle may contain duplicate copies of the
+  // SDK (instanceof fails across copies): err.name === "Machine0ApiError".
+  if (err instanceof Machine0ApiError) {
+    // The API answered with an error.
+    err.status;              // HTTP status (401, 404, 429, ...)
+    err.code;                // tRPC code: "UNAUTHORIZED" | "NOT_FOUND" | "TOO_MANY_REQUESTS" | ... | "UNKNOWN"
+    err.appErrorCode;        // machine0 code when provided, e.g. "INVALID_MACHINE_STATE",
+                             // "MACHINE_LIMIT_REACHED", "INSUFFICIENT_FUNDS", "SIZE_UNAVAILABLE"
+    err.providerRateLimited; // true when the cloud provider throttled — retry later
+  } else if (err instanceof Error && err.name === "TimeoutError") {
+    // Request exceeded timeoutMs.
+  } else {
+    // Native network error (DNS, connection refused) — propagated unwrapped.
+  }
+}
+```
+
+- **No retries in v1.** The SDK makes exactly one attempt per call; bring your own retry policy if you need one (respect `providerRateLimited` and 429s).
+- **A timeout aborts the request, not the operation.** The server may still complete a mutation whose response you never saw (e.g. a `create` that timed out can still create — and bill — the machine). After a timeout on a mutation, check state with `list()`/`get()` before retrying.
+- `code: "UNKNOWN"` means the response wasn't a machine0 API error envelope (e.g. a gateway 502 HTML page).
+
+## Rate limits
+
+API keys are rate-limited per user (default 3000 requests per window). Exceeding it yields `code: "TOO_MANY_REQUESTS"` (HTTP 429). The SDK sends one HTTP request per call and does not batch, unlike the web dashboard's client.
+
+## Stability
+
+Responses are typed for regular user accounts: admin-role API keys (SUPERUSER/IMAGEADMIN) receive additional fields the types do not declare — treat extra properties as possible.
+
+Enum-ish response fields (`status`, `size`, `region`, `distribution`, …) are **open sets**: the platform adds sizes, regions and statuses between SDK releases, so their types are `KnownValue | string`. Always handle unknown values with a default arm instead of exhaustive narrowing. Input types are closed — the server validates them.
+
+Pre-1.0 (`0.x`): the surface is small and intentionally conservative, but minor versions may adjust types as the API's public contract firms up. Pin a minor (`"@machine0/sdk": "~0.1.0"`) if you need strict stability. Procedures consumed by this SDK are treated as a public contract on the server side — breaking wire changes follow a two-phase deprecation discipline.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+import type { ActionResult, Image, ImageDetail, Machine, MachineCreated, MachineCreateInput, MachineDetail, MachineMetrics, MachineMetricsRange, MachineUpdateInput, SshKey, SshKeyCreated, SshKeyCreatedManaged, SshKeyCreateInput, SshKeyWithFile } from "./types.js";
+export interface Machine0ClientOptions {
+    /** machine0 API key (dashboard → Account → API Tokens, https://app.machine0.io/account/tokens). Sent as the `x-api-key` header. */
+    apiKey: string;
+    /**
+     * API base URL. Defaults to https://app.machine0.io. The key is sent on
+     * every request — only point this at `http://` for loopback dev servers,
+     * never a remote host (the key would travel in cleartext).
+     */
+    apiUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+}
+/**
+ * Create a typed machine0 API client.
+ *
+ * Zero dependencies: speaks the tRPC HTTP wire format over global fetch
+ * (queries are GETs with a URL-encoded JSON `input` param, mutations are
+ * POSTs with a JSON body). One HTTP request per call, no batching, no
+ * retries — see the README for the full error-handling contract.
+ */
+export declare function createClient(options: Machine0ClientOptions): {
+    machines: {
+        list: () => Promise<Machine[]>;
+        get: (input: {
+            id: string;
+        }) => Promise<MachineDetail>;
+        getByName: (input: {
+            name: string;
+        }) => Promise<MachineDetail>;
+        create: (input: MachineCreateInput) => Promise<MachineCreated>;
+        update: (input: MachineUpdateInput) => Promise<MachineDetail>;
+        start: (input: {
+            id: string;
+        }) => Promise<ActionResult>;
+        stop: (input: {
+            id: string;
+        }) => Promise<ActionResult>;
+        reboot: (input: {
+            id: string;
+        }) => Promise<ActionResult>;
+        suspend: (input: {
+            id: string;
+        }) => Promise<ActionResult>;
+        destroy: (input: {
+            id: string;
+        }) => Promise<ActionResult>;
+        metrics: (input: {
+            id: string;
+            range: MachineMetricsRange;
+        }) => Promise<MachineMetrics>;
+    };
+    images: {
+        list: () => Promise<Image[]>;
+        get: (input: {
+            id: string;
+        }) => Promise<ImageDetail>;
+    };
+    sshKeys: {
+        list: () => Promise<SshKey[]>;
+        get: (input: {
+            name: string;
+        }) => Promise<SshKeyWithFile>;
+        create: <T extends SshKeyCreateInput>(input: T) => Promise<T extends {
+            type: "MANAGED";
+        } ? SshKeyCreatedManaged : SshKeyCreated>;
+        update: (input: {
+            name: string;
+            isDefault?: boolean;
+        }) => Promise<SshKeyWithFile>;
+        destroy: (input: {
+            id: string;
+        }) => Promise<ActionResult>;
+    };
+};
+export type Machine0Client = ReturnType<typeof createClient>;

package/dist/client.js

@@ -0,0 +1,132 @@
+import { errorFromTrpcEnvelope, Machine0ApiError } from "./errors.js";
+const DEFAULT_API_URL = "https://app.machine0.io";
+const DEFAULT_TIMEOUT_MS = 30_000;
+// Computed key: a literal `"x-api-key": <value>` assignment trips secret
+// scanners (gstack-redact env.kv) on every ship even though the value is a
+// variable reference, never a credential.
+const API_KEY_HEADER = "x-api-key";
+/**
+ * Create a typed machine0 API client.
+ *
+ * Zero dependencies: speaks the tRPC HTTP wire format over global fetch
+ * (queries are GETs with a URL-encoded JSON `input` param, mutations are
+ * POSTs with a JSON body). One HTTP request per call, no batching, no
+ * retries — see the README for the full error-handling contract.
+ */
+export function createClient(options) {
+    if (typeof options.apiKey !== "string" || options.apiKey.trim() === "") {
+        throw new TypeError("@machine0/sdk: apiKey is required — create one in the dashboard at https://app.machine0.io/account/tokens");
+    }
+    const rawApiUrl = options.apiUrl ?? DEFAULT_API_URL;
+    try {
+        new URL(rawApiUrl);
+    }
+    catch {
+        throw new TypeError(`@machine0/sdk: apiUrl must be an absolute URL (got ${JSON.stringify(rawApiUrl)})`);
+    }
+    // Strip trailing slashes with a loop, not /\/+$/ — that regex backtracks
+    // polynomially on caller-supplied strings (CodeQL js/polynomial-redos).
+    let baseUrl = rawApiUrl;
+    while (baseUrl.endsWith("/")) {
+        baseUrl = baseUrl.slice(0, -1);
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const baseHeaders = {
+        [API_KEY_HEADER]: options.apiKey,
+        "x-machine0-client": "sdk",
+    };
+    async function request(url, init) {
+        const response = await fetch(url, {
+            ...init,
+            signal: AbortSignal.timeout(timeoutMs),
+            // The API never redirects, and fetch does NOT strip custom headers like
+            // x-api-key on cross-origin redirects — fail loudly instead of
+            // forwarding the key to whatever host a Location header names.
+            redirect: "error",
+        });
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (error) {
+            // Only a JSON parse failure means "the API sent non-JSON" (gateway 502
+            // HTML, proxy corruption on a 2xx). A timeout or network failure DURING
+            // the body read must keep its native identity — the documented error
+            // contract routes those to the caller's timeout/network branches, not
+            // to a Machine0ApiError that could claim status 200.
+            if (!(error instanceof SyntaxError)) {
+                throw error;
+            }
+            throw new Machine0ApiError({
+                status: response.status,
+                code: "UNKNOWN",
+                message: `machine0 API returned a non-JSON response (HTTP ${response.status})`,
+            });
+        }
+        if (body && typeof body === "object" && "error" in body) {
+            throw errorFromTrpcEnvelope(response.status, body);
+        }
+        if (!response.ok) {
+            throw new Machine0ApiError({
+                status: response.status,
+                code: "UNKNOWN",
+                message: `machine0 API request failed (HTTP ${response.status})`,
+            });
+        }
+        // A 2xx JSON body that is not a tRPC result envelope (middlebox/proxy
+        // JSON, wrong endpoint) must not silently resolve `undefined`. Every
+        // SDK-consumed procedure returns data, so `result` must be an object
+        // carrying a `data` property (which may legitimately be null).
+        const result = body && typeof body === "object" && "result" in body
+            ? body.result
+            : undefined;
+        if (!result || typeof result !== "object" || !("data" in result)) {
+            throw new Machine0ApiError({
+                status: response.status,
+                code: "UNKNOWN",
+                message: `machine0 API returned an unexpected response shape (HTTP ${response.status})`,
+            });
+        }
+        return result.data;
+    }
+    function query(path, input) {
+        const url = input === undefined
+            ? `${baseUrl}/trpc/${path}`
+            : `${baseUrl}/trpc/${path}?input=${encodeURIComponent(JSON.stringify(input))}`;
+        // No content-type on GET: the tRPC server rejects unexpected media types.
+        return request(url, { method: "GET", headers: baseHeaders });
+    }
+    function mutate(path, input) {
+        return request(`${baseUrl}/trpc/${path}`, {
+            method: "POST",
+            headers: { ...baseHeaders, "content-type": "application/json" },
+            body: JSON.stringify(input),
+        });
+    }
+    return {
+        machines: {
+            list: () => query("machines.list"),
+            get: (input) => query("machines.get", input),
+            getByName: (input) => query("machines.getByName", input),
+            create: (input) => mutate("machines.create", input),
+            update: (input) => mutate("machines.update", input),
+            start: (input) => mutate("machines.start", input),
+            stop: (input) => mutate("machines.stop", input),
+            reboot: (input) => mutate("machines.reboot", input),
+            suspend: (input) => mutate("machines.suspend", input),
+            destroy: (input) => mutate("machines.destroy", input),
+            metrics: (input) => query("machines.metrics", input),
+        },
+        images: {
+            list: () => query("images.list"),
+            get: (input) => query("images.get", input),
+        },
+        sshKeys: {
+            list: () => query("keys.list"),
+            get: (input) => query("keys.get", input),
+            create: (input) => mutate("keys.create", input),
+            update: (input) => mutate("keys.update", input),
+            destroy: (input) => mutate("keys.destroy", input),
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Error thrown for every non-successful machine0 API response.
+ *
+ * Not thrown for transport-level failures: network errors (DNS failure,
+ * connection refused) propagate as the runtime's native `TypeError`, and
+ * timeouts as a `DOMException` named "TimeoutError" — see the README's
+ * error-handling section.
+ */
+export declare class Machine0ApiError extends Error {
+    /** HTTP status code of the response. */
+    readonly status: number;
+    /** tRPC error code string (e.g. "NOT_FOUND", "UNAUTHORIZED", "TOO_MANY_REQUESTS"), or "UNKNOWN" when the response was not a tRPC error envelope. */
+    readonly code: string;
+    /** machine0 application error code (e.g. "INVALID_MACHINE_STATE", "MACHINE_LIMIT_REACHED"), when the server provided one. */
+    readonly appErrorCode?: string;
+    /** True when the failure was caused by cloud-provider rate limiting (retrying later may succeed). */
+    readonly providerRateLimited?: boolean;
+    constructor(params: {
+        status: number;
+        code: string;
+        message: string;
+        appErrorCode?: string;
+        providerRateLimited?: boolean;
+    });
+}
+/**
+ * Build a Machine0ApiError from a parsed tRPC error envelope
+ * (`{error: {message, data: {code, appErrorCode, ...}}}`). Published via the
+ * `@machine0/sdk/errors` subpath because the client module imports it, but
+ * the supported public surface of this module is `Machine0ApiError`; this
+ * helper's signature may change in any release.
+ */
+export declare function errorFromTrpcEnvelope(status: number, envelope: unknown): Machine0ApiError;

package/dist/errors.js

@@ -0,0 +1,64 @@
+/**
+ * Error thrown for every non-successful machine0 API response.
+ *
+ * Not thrown for transport-level failures: network errors (DNS failure,
+ * connection refused) propagate as the runtime's native `TypeError`, and
+ * timeouts as a `DOMException` named "TimeoutError" — see the README's
+ * error-handling section.
+ */
+export class Machine0ApiError extends Error {
+    /** HTTP status code of the response. */
+    status;
+    /** tRPC error code string (e.g. "NOT_FOUND", "UNAUTHORIZED", "TOO_MANY_REQUESTS"), or "UNKNOWN" when the response was not a tRPC error envelope. */
+    code;
+    /** machine0 application error code (e.g. "INVALID_MACHINE_STATE", "MACHINE_LIMIT_REACHED"), when the server provided one. */
+    appErrorCode;
+    /** True when the failure was caused by cloud-provider rate limiting (retrying later may succeed). */
+    providerRateLimited;
+    constructor(params) {
+        super(params.message);
+        this.name = "Machine0ApiError";
+        this.status = params.status;
+        this.code = params.code;
+        this.appErrorCode = params.appErrorCode;
+        this.providerRateLimited = params.providerRateLimited;
+    }
+}
+/**
+ * Build a Machine0ApiError from a parsed tRPC error envelope
+ * (`{error: {message, data: {code, appErrorCode, ...}}}`). Published via the
+ * `@machine0/sdk/errors` subpath because the client module imports it, but
+ * the supported public surface of this module is `Machine0ApiError`; this
+ * helper's signature may change in any release.
+ */
+export function errorFromTrpcEnvelope(status, envelope) {
+    const error = envelope && typeof envelope === "object" && "error" in envelope
+        ? envelope.error
+        : undefined;
+    let message = `machine0 API error (HTTP ${status})`;
+    let code = "UNKNOWN";
+    let appErrorCode;
+    let providerRateLimited;
+    if (error && typeof error === "object") {
+        const e = error;
+        if (typeof e.message === "string" && e.message.length > 0) {
+            message = e.message;
+        }
+        if (typeof e.data?.code === "string") {
+            code = e.data.code;
+        }
+        if (typeof e.data?.appErrorCode === "string") {
+            appErrorCode = e.data.appErrorCode;
+        }
+        if (typeof e.data?.providerRateLimited === "boolean") {
+            providerRateLimited = e.data.providerRateLimited;
+        }
+    }
+    return new Machine0ApiError({
+        status,
+        code,
+        message,
+        appErrorCode,
+        providerRateLimited,
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Response-side enum fields are OPEN sets: the server adds sizes, regions and
+ * statuses between SDK releases, and an already-installed SDK must not make
+ * exhaustive narrowing silently fall through when it meets a value newer than
+ * its types. `Open<T>` keeps autocomplete for the known members while telling
+ * the compiler unknown strings are possible — always include a default arm.
+ * INPUT types stay closed unions (the server validates them).
+ */
+export type Open<T extends string> = T | (string & {});
+export type MachineStatus = "DESTROYED" | "CREATING" | "RUNNING" | "STARTING" | "STOPPING" | "STOPPED" | "RESTARTING" | "ERRORED" | "SUSPENDING" | "SUSPENDED" | "UNAVAILABLE";
+export type MachineSize = "small" | "medium" | "large" | "xl" | "xxl" | "large-nvme" | "xl-nvme" | "xxl-nvme" | "xl-premium" | "xxl-premium" | "xxxl" | "4xl" | "5xl" | "6xl" | "gpu-4000ada-1" | "gpu-l40s-1" | "gpu-6000ada-1" | "gpu-mi300x-1" | "gpu-h100-1" | "gpu-h200-1" | "gpu-mi300x-8" | "gpu-h100-8" | "gpu-h200-8";
+export type MachineRegion = "us-east" | "us-west" | "uk" | "eu" | "asia";
+export type Distribution = "ubuntu" | "nixos";
+export type ImageStatus = "DESTROYED" | "CREATING" | "READY" | "TRANSFERRING" | "ERRORED";
+export type ImageType = "USER" | "SYSTEM";
+export type SshKeyType = "MANAGED" | "PUBLIC";
+export type MachineMetricsRange = "1h" | "24h" | "7d";
+/** Machine as returned by `machines.list`. */
+export interface Machine {
+    id: string;
+    name: string;
+    /** Proxy URL of the machine (`https://<name>.mac0.io`). */
+    url: string;
+    status: Open<MachineStatus>;
+    ip: string | null;
+    size: Open<MachineSize>;
+    region: Open<MachineRegion>;
+    provider: string;
+    createdAt: string;
+    firstStartedAt: string | null;
+    destroyedAt: string | null;
+    image: string | null;
+    distribution: Open<Distribution> | null;
+    ageMinutes: number | null;
+    totalCost: number | null;
+    pricePerHour: number | null;
+    metricsEnabled: boolean;
+}
+/**
+ * Machine as returned by `machines.create`. The create path responds from
+ * the freshly-inserted row before the image join exists, so `image` and
+ * `distribution` are absent — fetch the machine (`machines.get`) if you need
+ * them immediately after creation.
+ */
+export type MachineCreated = Omit<Machine, "image" | "distribution">;
+/** Machine as returned by `machines.get`, `machines.getByName` and `machines.update`. */
+export interface MachineDetail {
+    id: string;
+    name: string;
+    url: string;
+    status: Open<MachineStatus>;
+    ip: string | null;
+    size: Open<MachineSize>;
+    vcpu: number | null;
+    ram: number | null;
+    disk: number | null;
+    region: Open<MachineRegion>;
+    provider: string;
+    createdAt: string;
+    firstStartedAt: string | null;
+    image: string | null;
+    imageVersion: number | null;
+    defaultSSHUsername: string | null;
+    sshClientInitialCommand: string | null;
+    metricsEnabled: boolean;
+    distribution: Open<Distribution>;
+    /** SSH key the machine was created with (null if since destroyed). */
+    key: {
+        id: string;
+        name: string;
+        type: Open<SshKeyType>;
+        fileName: string;
+        publicKey: string;
+    } | null;
+    ageMinutes: number | null;
+    totalCost: number | null;
+    pricePerHour: number | null;
+    mountPaths: string[];
+    statusExplanation: string | null;
+}
+export interface DiskMount {
+    diskName: string;
+    path: string;
+}
+export interface MachineCreateInput {
+    name: string;
+    size: MachineSize;
+    /** `"us"` is a legacy alias for `"us-east"` accepted by the API. */
+    region: MachineRegion | "us";
+    imageName: string;
+    sshKeyId?: string;
+    imageVersion?: number;
+    profileName?: string;
+    mounts?: DiskMount[];
+    metricsEnabled?: boolean;
+}
+export interface MachineUpdateInput {
+    id: string;
+    name?: string;
+    defaultSSHUsername?: string;
+    sshClientInitialCommand?: string;
+    metricsEnabled?: boolean;
+}
+/** Returned by machine lifecycle mutations (start/stop/reboot/suspend/destroy). */
+export interface ActionResult {
+    success: boolean;
+}
+export interface MachineMetricsPoint {
+    /** Bucket timestamp (ISO-8601). */
+    t: string;
+    cpuPct: number | null;
+    memPct: number | null;
+    rxBps: number | null;
+    txBps: number | null;
+    load1: number | null;
+    load5: number | null;
+    load15: number | null;
+    diskPct: number | null;
+    diskReadBps: number | null;
+    diskWriteBps: number | null;
+    gpuPct: number | null;
+}
+export interface MachineMetrics {
+    points: MachineMetricsPoint[];
+}
+/** Image as returned by `images.list`. */
+export interface Image {
+    id: string;
+    name: string;
+    description: string | null;
+    distribution: Open<Distribution>;
+    type: Open<ImageType>;
+    status: Open<ImageStatus>;
+    provider: string;
+    sizeGb: number | null;
+    minDiskGb: number | null;
+    regions: string[];
+    gpuOnly: boolean;
+    createdAt: string;
+    updatedAt: string;
+    ageMinutes: number;
+    totalCost: number | null;
+    pricePerHour: number | null;
+}
+/** Image as returned by `images.get`. */
+export interface ImageDetail extends Image {
+    versionSnapshotStorageCost: number | null;
+}
+/** SSH key as returned by `sshKeys.list`. */
+export interface SshKey {
+    id: string;
+    name: string;
+    type: Open<SshKeyType>;
+    publicKey: string;
+    isDefault: boolean;
+    createdAt: string;
+}
+/** SSH key as returned by `sshKeys.get` and `sshKeys.update` (adds the key's file name). */
+export interface SshKeyWithFile extends SshKey {
+    fileName: string;
+}
+export type SshKeyCreateInput = {
+    type: "PUBLIC";
+    name: string;
+    fileName: string;
+    publicKey: string;
+    isDefault?: boolean;
+} | {
+    type: "MANAGED";
+    name: string;
+    isDefault?: boolean;
+};
+/** Result of `sshKeys.create` for PUBLIC keys. */
+export interface SshKeyCreated extends SshKeyWithFile {
+}
+/**
+ * Result of `sshKeys.create` for MANAGED keys: includes the plaintext
+ * private key — store it. This SDK never requests the private key again
+ * (the platform can re-issue managed keys via the CLI's `keys get --download`).
+ */
+export interface SshKeyCreatedManaged extends SshKeyWithFile {
+    privateKey: string;
+}
+export declare const MACHINE_KEYS: readonly ["id", "name", "url", "status", "ip", "size", "region", "provider", "createdAt", "firstStartedAt", "destroyedAt", "image", "distribution", "ageMinutes", "totalCost", "pricePerHour", "metricsEnabled"];
+export declare const MACHINE_CREATED_KEYS: readonly ["id", "name", "url", "status", "ip", "size", "region", "provider", "createdAt", "firstStartedAt", "destroyedAt", "ageMinutes", "totalCost", "pricePerHour", "metricsEnabled"];
+export declare const MACHINE_DETAIL_KEYS: readonly ["id", "name", "url", "status", "ip", "size", "vcpu", "ram", "disk", "region", "provider", "createdAt", "firstStartedAt", "image", "imageVersion", "defaultSSHUsername", "sshClientInitialCommand", "metricsEnabled", "distribution", "key", "ageMinutes", "totalCost", "pricePerHour", "mountPaths", "statusExplanation"];
+export declare const IMAGE_KEYS: readonly ["id", "name", "description", "distribution", "type", "status", "provider", "sizeGb", "minDiskGb", "regions", "gpuOnly", "createdAt", "updatedAt", "ageMinutes", "totalCost", "pricePerHour"];
+export declare const IMAGE_DETAIL_KEYS: readonly ["id", "name", "description", "distribution", "type", "status", "provider", "sizeGb", "minDiskGb", "regions", "gpuOnly", "createdAt", "updatedAt", "ageMinutes", "totalCost", "pricePerHour", "versionSnapshotStorageCost"];
+export declare const SSH_KEY_KEYS: readonly ["id", "name", "type", "publicKey", "isDefault", "createdAt"];
+export declare const SSH_KEY_WITH_FILE_KEYS: readonly ["id", "name", "type", "publicKey", "isDefault", "createdAt", "fileName"];

package/dist/types.js

@@ -0,0 +1,116 @@
+// Hand-written wire types for the machine0 API.
+//
+// These deliberately do NOT import anything from the server: the published
+// artifact must be dependency-free. Honesty is enforced two ways instead:
+//  - src/type-tests.ts (repo-only, never published) asserts every type here
+//    against the real AppRouter via inferRouterInputs/inferRouterOutputs —
+//    drift breaks `turbo typecheck` in CI.
+//  - The *_KEYS constants below bridge compile time and runtime: type-tests
+//    assert each constant is exhaustive over its type's keys, and the
+//    integration test (apps/api/src/sdk-client.test.ts) asserts the server's
+//    actual response keys equal the constant. A field declared here that the
+//    server never sends cannot survive both checks.
+//
+// All date fields are ISO-8601 strings: the API serializes plain JSON (no
+// superjson transformer).
+// Runtime key constants — the compile-time/runtime bridge (see file header).
+// `satisfies` guarantees no phantom keys; type-tests.ts asserts exhaustiveness
+// (every key of the type is listed); the integration test asserts the server's
+// actual responses carry exactly these keys.
+export const MACHINE_KEYS = [
+    "id",
+    "name",
+    "url",
+    "status",
+    "ip",
+    "size",
+    "region",
+    "provider",
+    "createdAt",
+    "firstStartedAt",
+    "destroyedAt",
+    "image",
+    "distribution",
+    "ageMinutes",
+    "totalCost",
+    "pricePerHour",
+    "metricsEnabled",
+];
+export const MACHINE_CREATED_KEYS = [
+    "id",
+    "name",
+    "url",
+    "status",
+    "ip",
+    "size",
+    "region",
+    "provider",
+    "createdAt",
+    "firstStartedAt",
+    "destroyedAt",
+    "ageMinutes",
+    "totalCost",
+    "pricePerHour",
+    "metricsEnabled",
+];
+export const MACHINE_DETAIL_KEYS = [
+    "id",
+    "name",
+    "url",
+    "status",
+    "ip",
+    "size",
+    "vcpu",
+    "ram",
+    "disk",
+    "region",
+    "provider",
+    "createdAt",
+    "firstStartedAt",
+    "image",
+    "imageVersion",
+    "defaultSSHUsername",
+    "sshClientInitialCommand",
+    "metricsEnabled",
+    "distribution",
+    "key",
+    "ageMinutes",
+    "totalCost",
+    "pricePerHour",
+    "mountPaths",
+    "statusExplanation",
+];
+export const IMAGE_KEYS = [
+    "id",
+    "name",
+    "description",
+    "distribution",
+    "type",
+    "status",
+    "provider",
+    "sizeGb",
+    "minDiskGb",
+    "regions",
+    "gpuOnly",
+    "createdAt",
+    "updatedAt",
+    "ageMinutes",
+    "totalCost",
+    "pricePerHour",
+];
+export const IMAGE_DETAIL_KEYS = [
+    ...IMAGE_KEYS,
+    "versionSnapshotStorageCost",
+];
+export const SSH_KEY_KEYS = [
+    "id",
+    "name",
+    "type",
+    "publicKey",
+    "isDefault",
+    "createdAt",
+];
+export const SSH_KEY_WITH_FILE_KEYS = [
+    ...SSH_KEY_KEYS,
+    "fileName",
+];

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,4 @@
+// Must match the "version" field in package.json — version.test.ts enforces
+// the sync, and the deploy-sdk workflow compares this constant (imported from
+// the built dist under plain Node) against package.json before publishing.
+export const SDK_VERSION = "0.1.0";

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@machine0/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Typed Node.js/TypeScript SDK for the machine0 API. Zero dependencies, fetch-based.",
+  "homepage": "https://machine0.io",
+  "author": "Barnaby Malet <barnaby@machine0.io>",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./version": {
+      "types": "./dist/version.d.ts",
+      "default": "./dist/version.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "clean": "rm -rf .turbo dist",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.4",
+    "@machine0/api": "workspace:*",
+    "@trpc/server": "^11.7.1",
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}