@sandboxrouter/sdk 0.3.2 → 0.3.4

package/dist/server.js

@@ -31,11 +31,11 @@ import { ProviderError, RouterError } from "./types.js";
  */
 export function createApp(router = new Router(), token = process.env.SANDBOXROUTER_TOKEN, 
 /** Browser origins allowed to call this server (e.g. the website's Playground). Off by default. */
-corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.trim()).filter(Boolean)) {
+corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.trim()).filter(Boolean), hooks = {}) {
     // With CORS on, any page open in a browser on this machine can call the server (Chrome even
     // lets a public page reach localhost, which the Private-Network header below allows), so it
     // would start sandboxes on these provider keys. A token is required for that.
-    if (corsOrigins.length && !token) {
+    if (corsOrigins.length && !token && !hooks.authorize) {
         throw new Error("CORS is on but SANDBOXROUTER_TOKEN is not set: browser pages could start sandboxes on your keys. Set a token, or turn CORS off.");
     }
     const expected = token ? Buffer.from(`Bearer ${token}`) : undefined;
@@ -71,11 +71,23 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         }
         if (url.pathname === "/health")
             return json(res, 200, { ok: true });
-        if (!authorized(req))
+        if (hooks.extra && (await hooks.extra(req, res, url)))
+            return;
+        let caller = null;
+        if (hooks.authorize) {
+            caller = await hooks.authorize(req);
+            if (caller === null)
+                return json(res, 401, { error: "unauthorized" });
+        }
+        else if (!authorized(req))
             return json(res, 401, { error: "unauthorized" });
         if (parts[0] !== "v1")
             return json(res, 404, { error: "not found" });
-        const box = async (id) => live.get(id) ?? router.get(id);
+        const box = async (id) => {
+            if (hooks.owns && !(await hooks.owns(caller, id)))
+                throw new HttpError(404, "no such sandbox");
+            return live.get(id) ?? router.get(id);
+        };
         // GET /v1/providers
         if (req.method === "GET" && parts[1] === "providers" && parts.length === 2) {
             return json(res, 200, {
@@ -91,14 +103,25 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
             const { spec, route } = splitBody(await readJson(req));
             return json(res, 200, { candidates: router.plan(spec, route) });
         }
-        if (parts[1] === "computers")
+        if (parts[1] === "computers") {
+            if (hooks.computers === false)
+                return json(res, 404, { error: "computers aren't available on this server" });
             return computers(req, res, url, parts);
+        }
         if (parts[1] !== "sandboxes")
             return json(res, 404, { error: "not found" });
         // POST /v1/sandboxes
         if (req.method === "POST" && parts.length === 2) {
             const { spec, route } = splitBody(await readJson(req));
+            await hooks.beforeCreate?.(caller, spec, route);
             const sbx = await router.create(spec, route);
+            try {
+                await hooks.afterCreate?.(caller, sbx, spec);
+            }
+            catch (err) {
+                await sbx.kill().catch(() => { });
+                throw err;
+            }
             live.set(sbx.id, sbx);
             return json(res, 201, {
                 id: sbx.id,
@@ -132,6 +155,8 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         }
         // POST /v1/sandboxes/:id/pause
         if (req.method === "POST" && parts[3] === "pause" && parts.length === 4) {
+            if (hooks.pause === false)
+                return json(res, 400, { error: "pause isn't available on this server" });
             await (await box(id)).pause();
             // Drop the cached handle so the next call reattaches through router.get(), which resumes.
             live.delete(id);
@@ -156,6 +181,7 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         if (req.method === "DELETE" && parts.length === 3) {
             await (await box(id)).kill();
             live.delete(id);
+            await hooks.afterKill?.(caller, id);
             return json(res, 200, { id, killed: true });
         }
         return json(res, 404, { error: "not found" });
@@ -227,7 +253,7 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         });
     });
 }
-class HttpError extends Error {
+export class HttpError extends Error {
     status;
     constructor(status, message) {
         super(message);

package/dist/types.d.ts

@@ -22,20 +22,24 @@ export interface SandboxSpec {
     metadata?: Record<string, string>;
 }
 /**
- * "cheapest" (and "default", the same thing): lowest list price for the spec, ties alphabetical.
+ * "verified" (and "default", the same thing): providers that passed the real-account check first
+ * (as of this release; `VERIFIED` in src/verified.ts), then the rest; cheapest first within each,
+ * ties alphabetical.
+ * "cheapest": lowest list price for the spec, tested or not, ties alphabetical.
  * "fastest": lowest median cold start you measured with `bench`, then cheapest.
  */
-export type Strategy = "default" | "cheapest" | "fastest";
+export type Strategy = "default" | "verified" | "cheapest" | "fastest";
 export interface RouteOptions {
     /** Pin to one provider, or give an ordered list to try. Omit to let the router choose. */
     provider?: ProviderId | ProviderId[];
-    /** How to order candidates when no explicit list is given. Default: cheapest. */
+    /** How to order candidates when no explicit list is given. Default: "verified" (tested providers first, then cheapest). */
     strategy?: Strategy;
     /**
      * What to do when a create fails. `true` (default): try the next candidate when the provider
-     * looks unavailable (timeout, network error, 429, 5xx, or an error without a status), but stop on
-     * a setup error (400, 401, 402, 403, 404, 422: a bad key, no billing, a bad image or request), so
-     * a mistake isn't hidden by quietly moving the work to another, maybe pricier, provider.
+     * looks unavailable (timeout, network error, 429, 5xx, or an error without a status) or can't bill
+     * (402: no balance, plan needed), but stop on a setup error (400, 401, 403, 404, 422: a bad key, a
+     * bad image or request), so a mistake isn't hidden by quietly moving the work to another, maybe
+     * pricier, provider. Every failed attempt is on `sandbox.attempts`.
      * `"any"`: try the next candidate on every error. `false`: only the first candidate.
      */
     fallback?: boolean | "any";

package/dist/verified.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderId } from "./types.js";
+export declare const VERIFIED: Partial<Record<ProviderId, string>>;

package/dist/verified.js

@@ -0,0 +1,7 @@
+export const VERIFIED = {
+    blaxel: "2026-11-10",
+    daytona: "2026-11-10",
+    e2b: "2026-11-10",
+    maritime: "2026-11-10",
+    sail: "2026-11-10",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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",