@prized/sdk 0.0.0-stage → 0.1.1

package/dist/esm/types.d.ts

@@ -0,0 +1,111 @@
+/** A sandbox's lifecycle state. */
+export type SandboxState = 'starting' | 'running' | 'pausing' | 'paused' | 'resizing' | 'deleting' | 'deleted' | 'error';
+/** A sandbox shape. Memory travels in MiB; `memoryGb` is the same number in GiB. */
+export interface Resources {
+    vcpu: number;
+    memoryMb: number;
+    memoryGb: number;
+    diskGb: number;
+}
+/** What a create asks for. Every field is optional: the template's default fills the gaps. */
+export interface ResourcesInput {
+    vcpu?: number;
+    /** Memory in GiB (`memoryGb: 4` is 4096 MiB). Give this or `memoryMb`, not both. */
+    memoryGb?: number;
+    /** Memory in MiB. */
+    memoryMb?: number;
+    diskGb?: number;
+}
+/** What the API says about a sandbox. */
+export interface SandboxInfo {
+    id: string;
+    state: SandboxState;
+    template: string | null;
+    resources: Resources;
+    labels: Record<string, string>;
+    /** Idle minutes before a running sandbox pauses itself (null: never). */
+    autoPauseMin: number | null;
+    /** Minutes after pausing before the sandbox deletes itself (null: never). */
+    autoDeleteMin: number | null;
+    /**
+     * When the sandbox's run time ends and it is deleted. Null while a paused
+     * sandbox's clock is stopped: a resume on a paid plan starts a fresh one;
+     * on the free tier it carries on the running time left.
+     */
+    expiresAt: Date | null;
+    createdAt: Date | null;
+    lastActiveAt: Date | null;
+    /** Why the sandbox is in `error`, when it is. */
+    errorReason: string | null;
+    /** The base URL its exec and files calls go to. */
+    toolboxBase: string | null;
+    /** The document exactly as the API sent it. */
+    raw: Record<string, unknown>;
+}
+/** One entry of `Sandbox.templates()`. */
+export interface Template {
+    id: string;
+    defaults: Resources;
+    min: Resources;
+    max: Resources;
+    durability: string;
+    /** The run time a sandbox gets when its create gives no `maxRuntimeMin` (for your workspace's plan). */
+    defaultMaxRuntimeMin: number;
+}
+/** What one command produced. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    /** The command's exit code; -1 when it timed out or ended without reporting one. */
+    exitCode: number;
+    /** How long the command ran, in ms. */
+    durationMs: number;
+    /**
+     * True when the command hit its timeout and was killed (`exitCode` is then
+     * -1). `exec()` and `wait()` throw CommandTimeoutError with such a result
+     * rather than return it.
+     */
+    timedOut: boolean;
+    /**
+     * True when stdout or stderr reached the 4 MiB per-stream cap of a single
+     * call: the command kept running, the rest of that stream was dropped.
+     * Pass `fullOutput: true` for commands that may print more (it keeps up
+     * to 100 MiB of each stream, and sets this past that). `truncatedReason`
+     * says why.
+     */
+    truncated: boolean;
+    /**
+     * Why `truncated` is true; absent when it is false. `output_limit`: a
+     * stream reached its cap (4 MiB in one call, 100 MiB with `fullOutput`).
+     * `write_failed` (`fullOutput` only): the sandbox could not save a stream
+     * as the command printed it, most often because its disk is full, so that
+     * stream stops where the write failed, however short; free some space and
+     * run it again.
+     */
+    truncatedReason?: TruncatedReason;
+}
+/** Why a command's output was cut: ExecResult.truncatedReason. */
+export type TruncatedReason = 'output_limit' | 'write_failed';
+/** One directory entry, as `sandbox.files.list()` returns it. */
+export interface FileInfo {
+    name: string;
+    path: string;
+    /** Size in bytes. */
+    size: number;
+    isDir: boolean;
+    isSymlink: boolean;
+    /** Permissions as `ls -l` prints them, e.g. `-rw-r--r--`. */
+    mode: string;
+    modified: Date | null;
+}
+/** What a write or an upload reports. */
+export interface WriteInfo {
+    path: string;
+    size: number;
+}
+export declare function parseTime(value: unknown): Date | null;
+export declare function parseResources(value: unknown): Resources;
+export declare function parseSandbox(doc: unknown): SandboxInfo;
+export declare function parseTemplate(entry: unknown): Template | null;
+/** The wire shape of a create's `resources`: memory in MiB, integers only. */
+export declare function resourcesToWire(input: ResourcesInput): Record<string, number>;

package/dist/esm/types.js

@@ -0,0 +1,95 @@
+// Public types and the parsers that turn API documents into them.
+import { PrizedError } from './errors.js';
+function int(value, fallback = 0) {
+    return typeof value === 'number' && Number.isInteger(value) ? value : fallback;
+}
+function optInt(value) {
+    return typeof value === 'number' && Number.isInteger(value) ? value : null;
+}
+function optString(value) {
+    return typeof value === 'string' ? value : null;
+}
+export function parseTime(value) {
+    if (typeof value !== 'string' || value === '')
+        return null;
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? null : new Date(at);
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+export function parseResources(value) {
+    const r = record(value);
+    const memoryMb = int(r.memoryMb);
+    return { vcpu: int(r.vcpu), memoryMb, memoryGb: memoryMb / 1024, diskGb: int(r.diskGb) };
+}
+export function parseSandbox(doc) {
+    const d = record(doc);
+    if (typeof d.id !== 'string' || d.id === '') {
+        throw new PrizedError('bad_response', 'The API answered without a sandbox document.');
+    }
+    const labels = {};
+    for (const [key, value] of Object.entries(record(d.labels))) {
+        if (typeof value === 'string')
+            labels[key] = value;
+    }
+    return {
+        id: d.id,
+        state: (typeof d.state === 'string' ? d.state : 'error'),
+        template: optString(d.template),
+        resources: parseResources(d.resources),
+        labels,
+        autoPauseMin: optInt(d.autoPauseMin),
+        autoDeleteMin: optInt(d.autoDeleteMin),
+        expiresAt: parseTime(d.expiresAt),
+        createdAt: parseTime(d.createdAt),
+        lastActiveAt: parseTime(d.lastActiveAt),
+        errorReason: optString(d.errorReason),
+        toolboxBase: optString(d.toolboxBase),
+        raw: d,
+    };
+}
+export function parseTemplate(entry) {
+    const e = record(entry);
+    if (typeof e.id !== 'string' || e.id === '')
+        return null;
+    const resources = record(e.resources);
+    return {
+        id: e.id,
+        defaults: parseResources(resources.defaults),
+        min: parseResources(resources.min),
+        max: parseResources(resources.max),
+        durability: optString(e.durability) ?? 'ephemeral',
+        defaultMaxRuntimeMin: int(e.defaultMaxRuntimeMin),
+    };
+}
+/** The wire shape of a create's `resources`: memory in MiB, integers only. */
+export function resourcesToWire(input) {
+    const out = {};
+    const whole = (name, value) => {
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new PrizedError('invalid_argument', `resources.${name} must be a positive whole number (got ${value})`);
+        }
+        return value;
+    };
+    if (input.vcpu !== undefined)
+        out.vcpu = whole('vcpu', input.vcpu);
+    if (input.memoryGb !== undefined && input.memoryMb !== undefined) {
+        if (Math.round(input.memoryGb * 1024) !== input.memoryMb) {
+            throw new PrizedError('invalid_argument', 'Give resources.memoryGb or resources.memoryMb, not both');
+        }
+    }
+    if (input.memoryMb !== undefined) {
+        out.memoryMb = whole('memoryMb', input.memoryMb);
+    }
+    else if (input.memoryGb !== undefined) {
+        const mb = input.memoryGb * 1024;
+        if (!Number.isInteger(mb) || mb <= 0) {
+            throw new PrizedError('invalid_argument', `resources.memoryGb must be a whole number of MiB (got ${input.memoryGb} GiB)`);
+        }
+        out.memoryMb = mb;
+    }
+    if (input.diskGb !== undefined)
+        out.diskGb = whole('diskGb', input.diskGb);
+    return out;
+}

package/dist/esm/version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version; test/version.test.ts holds it equal to package.json. */
+export declare const VERSION = "0.1.1";

package/dist/esm/version.js

@@ -0,0 +1,2 @@
+/** This package's version; test/version.test.ts holds it equal to package.json. */
+export const VERSION = '0.1.1';

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@prized/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Prized Sandboxes (beta): create microVM sandboxes, run commands, move files, pause, resume and fork them from TypeScript.",
+  "homepage": "https://prized.dev/docs/sandboxes",
+  "license": "Apache-2.0",
+  "keywords": [
+    "prized",
+    "sandbox",
+    "sandboxes",
+    "microvm",
+    "agents",
+    "code-execution"
+  ],
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "node scripts/build.mjs",
+    "test": "node scripts/test.mjs",
+    "prepublishOnly": "node scripts/build.mjs",
+    "pack-check": "node scripts/pack-check.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.4",
+    "typescript": "5.9.3"
+  }
+}