@sandboxrouter/sdk 0.3.5 → 0.5.0

package/dist/util.js

@@ -28,7 +28,8 @@ export function wrapCommand(cmd, opts = {}) {
 }
 /** The one error every adapter throws when a command outlives ExecOptions.timeoutSeconds. */
 export function timeoutError(provider, seconds) {
-    return new ProviderError(provider, `command timed out after ${seconds}s`);
+    // 504 for the HTTP API: the command ran out of time, not the server.
+    return new ProviderError(provider, `command timed out after ${seconds}s`, 504);
 }
 /**
  * True when an exit code is the one left behind by a timeout kill and the command really ran

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+import { type RouteOptions, type SandboxSpec, type Strategy } from "./types.js";
+/** Every key a SandboxSpec can have. Anything else in a request is a mistake (e.g. "memory" for "memoryGb"). */
+export declare const SPEC_KEYS: readonly ["vcpu", "memoryGb", "gpu", "env", "timeoutMinutes", "image", "metadata"];
+/** Every key RouteOptions can have. */
+export declare const ROUTE_KEYS: readonly ["provider", "strategy", "fallback", "require", "createTimeoutSeconds", "deadlineSeconds"];
+export declare const STRATEGIES: readonly Strategy[];
+/**
+ * Throws RouterError("bad_request") for a spec or route a provider couldn't make sense of: sizes and
+ * times that aren't positive numbers, an unknown strategy or fallback, maps that aren't string maps.
+ * Called by `plan()`, so every create, route and CLI command goes through it.
+ */
+export declare function validate(spec?: SandboxSpec, route?: RouteOptions): void;
+/** Split a flat request body into spec and route options, refusing keys that are neither. */
+export declare function splitRequest(body: Record<string, unknown>): {
+    spec: SandboxSpec;
+    route: RouteOptions;
+};

package/dist/validate.js

@@ -0,0 +1,66 @@
+import { CATALOG } from "./catalog.js";
+import { RouterError } from "./types.js";
+/** Every key a SandboxSpec can have. Anything else in a request is a mistake (e.g. "memory" for "memoryGb"). */
+export const SPEC_KEYS = ["vcpu", "memoryGb", "gpu", "env", "timeoutMinutes", "image", "metadata"];
+/** Every key RouteOptions can have. */
+export const ROUTE_KEYS = ["provider", "strategy", "fallback", "require", "createTimeoutSeconds", "deadlineSeconds"];
+export const STRATEGIES = ["default", "balanced", "verified", "cheapest", "fastest"];
+const bad = (msg) => new RouterError(msg, [], "bad_request");
+const positive = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
+/** How a bad value is shown: numbers as-is (NaN, Infinity), anything else as JSON. */
+const show = (v) => (typeof v === "number" ? String(v) : JSON.stringify(v));
+const stringMap = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
+/**
+ * Throws RouterError("bad_request") for a spec or route a provider couldn't make sense of: sizes and
+ * times that aren't positive numbers, an unknown strategy or fallback, maps that aren't string maps.
+ * Called by `plan()`, so every create, route and CLI command goes through it.
+ */
+export function validate(spec = {}, route = {}) {
+    for (const k of ["vcpu", "memoryGb", "timeoutMinutes"]) {
+        if (spec[k] !== undefined && !positive(spec[k]))
+            throw bad(`${k} must be a positive number, got ${show(spec[k])}`);
+    }
+    if (spec.gpu !== undefined && (typeof spec.gpu !== "string" || !spec.gpu))
+        throw bad(`gpu must be a GPU type such as "T4", got ${JSON.stringify(spec.gpu)}`);
+    for (const k of ["env", "image", "metadata"]) {
+        if (spec[k] !== undefined && !stringMap(spec[k]))
+            throw bad(`${k} must be an object of strings`);
+    }
+    if (route.strategy !== undefined && !STRATEGIES.includes(route.strategy)) {
+        throw bad(`unknown strategy ${JSON.stringify(route.strategy)}: use one of ${STRATEGIES.filter((s) => s !== "default").join(", ")}`);
+    }
+    if (route.fallback !== undefined && route.fallback !== true && route.fallback !== false && route.fallback !== "any") {
+        throw bad(`fallback must be true, false or "any", got ${JSON.stringify(route.fallback)}`);
+    }
+    for (const k of ["createTimeoutSeconds", "deadlineSeconds"]) {
+        if (route[k] !== undefined && !positive(route[k]))
+            throw bad(`${k} must be a positive number, got ${show(route[k])}`);
+    }
+    if (route.require !== undefined && (!Array.isArray(route.require) || !route.require.every((r) => typeof r === "string"))) {
+        throw bad("require must be a list of capabilities, e.g. [\"pause\"]");
+    }
+    if (route.provider !== undefined) {
+        const ids = [].concat(route.provider);
+        const unknown = ids.filter((id) => typeof id !== "string" || !CATALOG.some((c) => c.id === id));
+        if (unknown.length || ids.length === 0)
+            throw bad(`unknown provider: ${unknown.map((u) => JSON.stringify(u)).join(", ") || "(empty list)"}`);
+    }
+}
+/** Split a flat request body into spec and route options, refusing keys that are neither. */
+export function splitRequest(body) {
+    const spec = {};
+    const route = {};
+    const unknown = [];
+    for (const [k, v] of Object.entries(body ?? {})) {
+        if (ROUTE_KEYS.includes(k))
+            route[k] = v;
+        else if (SPEC_KEYS.includes(k))
+            spec[k] = v;
+        else
+            unknown.push(k);
+    }
+    if (unknown.length)
+        throw bad(`unknown field${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}: a sandbox takes ${SPEC_KEYS.join(", ")}; routing takes ${ROUTE_KEYS.join(", ")}`);
+    validate(spec, route);
+    return { spec: spec, route: route };
+}

package/dist/verified.d.ts

@@ -1,2 +1,4 @@
 import type { ProviderId } from "./types.js";
 export declare const VERIFIED: Partial<Record<ProviderId, string>>;
+/** Providers whose last saved real-account check failed a step. The default strategy tries them last. */
+export declare const FAILING: Partial<Record<ProviderId, string>>;

package/dist/verified.js

@@ -16,3 +16,5 @@ export const VERIFIED = {
     superserve: "2026-11-11",
     vercel: "2026-11-11",
 };
+/** Providers whose last saved real-account check failed a step. The default strategy tries them last. */
+export const FAILING = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.3.5",
+  "version": "0.5.0",
   "description": "One API for every sandbox provider: route AI agents' code by price, speed or capability, with automatic fallback. Free and open source.",
   "type": "module",
   "main": "dist/index.js",