@machine0/sdk 0.1.1 → 0.2.1

package/README.md

@@ -58,6 +58,7 @@ 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.)
+- `get()`, `getByName()` and `update()` return the machine's creation-time environment variables as `env` (`{}` when it has none, `null` if they could not be read) — with their values, so don't log whole responses. `list()` never includes them.
 - All date fields are ISO-8601 strings.
 
 ## Options

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ActionResult, Image, ImageDetail, Machine, MachineCreated, MachineCreateInput, MachineDetail, MachineMetrics, MachineMetricsRange, MachineUpdateInput, SshKey, SshKeyCreated, SshKeyCreatedManaged, SshKeyCreateInput, SshKeyWithFile } from "./types.js";
+import type { ActionResult, ImageDetail, ImageListItem, 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;
@@ -51,7 +51,7 @@ export declare function createClient(options: Machine0ClientOptions): {
         }) => Promise<MachineMetrics>;
     };
     images: {
-        list: () => Promise<Image[]>;
+        list: () => Promise<ImageListItem[]>;
         get: (input: {
             id: string;
         }) => Promise<ImageDetail>;

package/dist/types.d.ts

@@ -9,12 +9,21 @@
 export type Open<T extends string> = T | (string & {});
 export type MachineStatus = "DESTROYED" | "CREATING" | "RUNNING" | "STARTING" | "STOPPING" | "STOPPED" | "RESTARTING" | "ERRORED" | "SUSPENDING" | "SUSPENDED" | "UNAVAILABLE" | "ORDERED";
 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";
+/** Datacenter slugs (region IS the datacenter since the region flip). */
+export type MachineRegion = "nyc3" | "sfo3" | "lon1" | "ams3" | "sgp1" | "tor1" | "nyc2" | "atl1" | "fra1";
+/**
+ * Legacy region aliases still accepted on input, normalized server-side to
+ * their historical primary datacenter (us/us-east→nyc3, us-west→sfo3,
+ * uk→lon1, eu→ams3, asia→sgp1).
+ */
+export type LegacyMachineRegion = "us" | "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";
+/** Idle-detection action: what the server does after sustained inactivity. */
+export type MachineOnIdleAction = "suspend" | "destroy" | "none";
 /** Machine as returned by `machines.list`. */
 export interface Machine {
     id: string;
@@ -35,6 +44,10 @@ export interface Machine {
     totalCost: number | null;
     pricePerHour: number | null;
     metricsEnabled: boolean;
+    /** Idle-detection action; `"none"` = disabled. */
+    onIdle: Open<MachineOnIdleAction>;
+    /** Sustained-inactivity window (minutes) before `onIdle` fires. */
+    idleTimeoutMinutes: number;
     /**
      * Standing-order deadline (`machine0 order`): set while the machine is an
      * ORDERED (or expired) order, cleared once the order fills. Null for
@@ -48,7 +61,17 @@ export interface Machine {
  * `distribution` are absent — fetch the machine (`machines.get`) if you need
  * them immediately after creation.
  */
-export type MachineCreated = Omit<Machine, "image" | "distribution">;
+export type MachineCreated = Omit<Machine, "image" | "distribution"> & {
+    /**
+     * Whether a supplied `env` map was applied: `true` when `env` was passed and
+     * honored, `false` when no `env` was passed. Always present on a server that
+     * supports env overrides. A server that predates env support OMITS this field
+     * entirely (and silently creates the VM without the variables), so after
+     * passing `env` you can distinguish an applied override from an old server
+     * with `"envApplied" in created`.
+     */
+    envApplied: boolean;
+};
 /** Machine as returned by `machines.get`, `machines.getByName` and `machines.update`. */
 export interface MachineDetail {
     id: string;
@@ -69,6 +92,10 @@ export interface MachineDetail {
     defaultSSHUsername: string | null;
     sshClientInitialCommand: string | null;
     metricsEnabled: boolean;
+    /** See {@link Machine.onIdle}. */
+    onIdle: Open<MachineOnIdleAction>;
+    /** See {@link Machine.idleTimeoutMinutes}. */
+    idleTimeoutMinutes: number;
     distribution: Open<Distribution>;
     /** SSH key the machine was created with (null if since destroyed). */
     key: {
@@ -85,6 +112,14 @@ export interface MachineDetail {
     statusExplanation: string | null;
     /** See {@link Machine.orderExpiresAt}. */
     orderExpiresAt: string | null;
+    /**
+     * The environment variables the machine was created with
+     * ({@link MachineCreateInput.env}) — its own variables only, not those it
+     * inherits from a profile. `{}` when it was created without any; `null` when
+     * they are stored but could not be read. Treat the values as secrets: don't
+     * log a whole `MachineDetail`.
+     */
+    env: Record<string, string> | null;
 }
 export interface DiskMount {
     diskName: string;
@@ -93,14 +128,39 @@ export interface DiskMount {
 export interface MachineCreateInput {
     name: string;
     size: MachineSize;
-    /** `"us"` is a legacy alias for `"us-east"` accepted by the API. */
-    region: MachineRegion | "us";
+    /** Legacy aliases ("us-east", "eu", …) are accepted and normalized. */
+    region: MachineRegion | LegacyMachineRegion;
     imageName: string;
     sshKeyId?: string;
     imageVersion?: number;
     profileName?: string;
     mounts?: DiskMount[];
     metricsEnabled?: boolean;
+    /**
+     * Suspend or destroy the machine after sustained inactivity. Enabling
+     * (`"suspend"`/`"destroy"`) force-enables `metricsEnabled` and requires a
+     * managed SSH key.
+     *
+     * Requires a server that supports idle detection: an older server silently
+     * ignores this field (the machine is created WITHOUT the policy) and omits
+     * `onIdle`/`idleTimeoutMinutes` from responses. Published SDK versions
+     * always trail the production server, so this only matters against
+     * self-hosted/stale deployments — check `machine.onIdle !== undefined`
+     * after creating if you depend on the policy.
+     */
+    onIdle?: MachineOnIdleAction;
+    /** Minutes of inactivity before `onIdle` fires (10-2880; default 30). */
+    idleTimeoutMinutes?: number;
+    /**
+     * Environment variables set on the VM at creation, keyed by name. They
+     * override the chosen profile's variables on name collision and are applied
+     * on every provision/resume. Immutable after creation.
+     *
+     * Requires a server that supports machine env overrides: an older server
+     * silently ignores this field (the VM is created WITHOUT the variables, and
+     * with a `profileName` collision the profile's value is used instead).
+     */
+    env?: Record<string, string>;
 }
 export interface MachineUpdateInput {
     id: string;
@@ -108,6 +168,10 @@ export interface MachineUpdateInput {
     defaultSSHUsername?: string;
     sshClientInitialCommand?: string;
     metricsEnabled?: boolean;
+    /** See {@link MachineCreateInput.onIdle}. */
+    onIdle?: MachineOnIdleAction;
+    /** See {@link MachineCreateInput.idleTimeoutMinutes}. */
+    idleTimeoutMinutes?: number;
 }
 /** Returned by machine lifecycle mutations (start/stop/reboot/suspend/destroy). */
 export interface ActionResult {
@@ -144,12 +208,33 @@ export interface Image {
     minDiskGb: number | null;
     regions: string[];
     gpuOnly: boolean;
+    /**
+     * Branch-tracking source identity (github `--flake` builds). All null on
+     * non-tracked images. When set, pushes to `gitRepo`@`gitBranch` rebuild
+     * the image and auto-promote the new version.
+     */
+    gitRepo: string | null;
+    gitBranch: string | null;
+    flakeDir: string | null;
+    nixProfile: string | null;
     createdAt: string;
     updatedAt: string;
     ageMinutes: number;
     totalCost: number | null;
     pricePerHour: number | null;
 }
+/**
+ * Image as returned by `images.list` — adds the latest failed-build error of
+ * the image's current draft (owner/admin-visible only; null otherwise or
+ * when the latest build succeeded).
+ */
+export interface ImageListItem extends Image {
+    latestVersionError: {
+        version: number;
+        message: string;
+        at: string | null;
+    } | null;
+}
 /** Image as returned by `images.get`. */
 export interface ImageDetail extends Image {
     versionSnapshotStorageCost: number | null;
@@ -189,10 +274,11 @@ export interface SshKeyCreated extends SshKeyWithFile {
 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", "orderExpiresAt"];
-export declare const MACHINE_CREATED_KEYS: readonly ["id", "name", "url", "status", "ip", "size", "region", "provider", "createdAt", "firstStartedAt", "destroyedAt", "ageMinutes", "totalCost", "pricePerHour", "metricsEnabled", "orderExpiresAt"];
-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", "orderExpiresAt"];
-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 MACHINE_KEYS: readonly ["id", "name", "url", "status", "ip", "size", "region", "provider", "createdAt", "firstStartedAt", "destroyedAt", "image", "distribution", "ageMinutes", "totalCost", "pricePerHour", "metricsEnabled", "onIdle", "idleTimeoutMinutes", "orderExpiresAt"];
+export declare const MACHINE_CREATED_KEYS: readonly ["id", "name", "url", "status", "ip", "size", "region", "provider", "createdAt", "firstStartedAt", "destroyedAt", "ageMinutes", "totalCost", "pricePerHour", "metricsEnabled", "onIdle", "idleTimeoutMinutes", "orderExpiresAt", "envApplied"];
+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", "onIdle", "idleTimeoutMinutes", "distribution", "key", "ageMinutes", "totalCost", "pricePerHour", "mountPaths", "statusExplanation", "orderExpiresAt", "env"];
+export declare const IMAGE_KEYS: readonly ["id", "name", "description", "distribution", "type", "status", "provider", "sizeGb", "minDiskGb", "regions", "gpuOnly", "gitRepo", "gitBranch", "flakeDir", "nixProfile", "createdAt", "updatedAt", "ageMinutes", "totalCost", "pricePerHour"];
+export declare const IMAGE_LIST_KEYS: readonly ["id", "name", "description", "distribution", "type", "status", "provider", "sizeGb", "minDiskGb", "regions", "gpuOnly", "gitRepo", "gitBranch", "flakeDir", "nixProfile", "createdAt", "updatedAt", "ageMinutes", "totalCost", "pricePerHour", "latestVersionError"];
+export declare const IMAGE_DETAIL_KEYS: readonly ["id", "name", "description", "distribution", "type", "status", "provider", "sizeGb", "minDiskGb", "regions", "gpuOnly", "gitRepo", "gitBranch", "flakeDir", "nixProfile", "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

@@ -35,6 +35,8 @@ export const MACHINE_KEYS = [
     "totalCost",
     "pricePerHour",
     "metricsEnabled",
+    "onIdle",
+    "idleTimeoutMinutes",
     "orderExpiresAt",
 ];
 export const MACHINE_CREATED_KEYS = [
@@ -53,7 +55,10 @@ export const MACHINE_CREATED_KEYS = [
     "totalCost",
     "pricePerHour",
     "metricsEnabled",
+    "onIdle",
+    "idleTimeoutMinutes",
     "orderExpiresAt",
+    "envApplied",
 ];
 export const MACHINE_DETAIL_KEYS = [
     "id",
@@ -74,6 +79,8 @@ export const MACHINE_DETAIL_KEYS = [
     "defaultSSHUsername",
     "sshClientInitialCommand",
     "metricsEnabled",
+    "onIdle",
+    "idleTimeoutMinutes",
     "distribution",
     "key",
     "ageMinutes",
@@ -82,7 +89,10 @@ export const MACHINE_DETAIL_KEYS = [
     "mountPaths",
     "statusExplanation",
     "orderExpiresAt",
+    "env",
 ];
+// The shared Image keys — valid against BOTH images.list rows and images.get
+// (kept stable for existing consumers indexing either shape).
 export const IMAGE_KEYS = [
     "id",
     "name",
@@ -95,12 +105,21 @@ export const IMAGE_KEYS = [
     "minDiskGb",
     "regions",
     "gpuOnly",
+    "gitRepo",
+    "gitBranch",
+    "flakeDir",
+    "nixProfile",
     "createdAt",
     "updatedAt",
     "ageMinutes",
     "totalCost",
     "pricePerHour",
 ];
+// List rows additionally carry the computed latestVersionError; get does not.
+export const IMAGE_LIST_KEYS = [
+    ...IMAGE_KEYS,
+    "latestVersionError",
+];
 export const IMAGE_DETAIL_KEYS = [
     ...IMAGE_KEYS,
     "versionSnapshotStorageCost",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.1.1";
+export declare const SDK_VERSION = "0.2.1";

package/dist/version.js

@@ -1,4 +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.1";
+export const SDK_VERSION = "0.2.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@machine0/sdk",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Typed Node.js/TypeScript SDK for the machine0 API. Zero dependencies, fetch-based.",
   "homepage": "https://machine0.io",
   "author": "Barnaby Malet <barnaby@machine0.io>",