@lizard-build/sdk 0.1.83 → 1.0.1

package/README.md

@@ -106,9 +106,10 @@ if (result.exitCode !== 0) throw new Error(result.stderr)
 The `desktop` template runs an Openbox desktop with Chromium, streamed to a browser over WebRTC (with noVNC as the fallback). You can watch it, and an agent can drive it:
 
 ```ts
-import { Sandbox } from '@lizard-build/sdk'
+import { Lizard } from '@lizard-build/sdk'
 
-const sandbox = await Sandbox.create('desktop', { project: 'my-project' })
+const lizard = new Lizard({ project: 'my-project' })
+const sandbox = await lizard.create('desktop')
 try {
   const { url, viewOnlyUrl } = await sandbox.desktop.start() // open `url` in a browser
   await sandbox.desktop.openUrl('https://example.com')
@@ -128,11 +129,10 @@ Treat `url` like a credential: anyone with it can see and control the desktop. S
 Run Python with the `interpreter` template. Each process command starts a separate Python process, so Python variables do not survive between calls; use `CodeSandbox` when they should.
 
 ```ts
-import { Sandbox } from '@lizard-build/sdk'
+import { Lizard } from '@lizard-build/sdk'
 
-const sandbox = await Sandbox.create('interpreter', {
-  project: 'my-project', timeoutMs: 300_000,
-})
+const lizard = new Lizard({ project: 'my-project' })
+const sandbox = await lizard.create('interpreter', { timeoutMs: 300_000 })
 try {
   const result = await sandbox.process.exec("python -c 'print(2 ** 10)'")
   if (result.exitCode !== 0) throw new Error(result.stderr)
@@ -164,6 +164,14 @@ Command results contain stdout, stderr, and the exit code. Command timeouts are
 
 The SDK and CLI default to a five-minute lifetime. The raw API and dashboard default to no expiration. Set an explicit lifetime: `timeoutMs: 0` at creation disables expiration; a positive value sets a deadline. `setTimeout()` accepts 1000–2147483647 ms, not zero. Commands do not reset the deadline. This is not an idle timer.
 
+## Versions and API stability
+
+Lizard SDK follows [semantic versioning](https://semver.org) from 1.0.0. A change that breaks a documented method, option or return type ships only in a new major version. New features come in minor versions, fixes in patch versions. The npm and PyPI packages share one version number. The [changelog](https://github.com/lizard-build/lizard-sdk/blob/main/CHANGELOG.md) lists what changed, including the API changes made before 1.0.
+
+There are two ways to create a sandbox, and both are stable: `new Lizard({ project }).create(template)` and `Sandbox.create(template, { project })`. The client passes its project to `Sandbox.create()`, so both send the same request. The examples use the client because it also reaches volumes and the platform API. `CodeSandbox.create({ project })` takes the project the same way as `Sandbox.create()`.
+
+Platform facts such as prices, limits and templates can change without a new SDK version. See [current limits](https://lizard.build/docs/sandboxes/).
+
 ## Other SDK capabilities
 
 The SDK also manages apps, Managed Postgres, Managed Redis, Managed Object Storage and projects. See the [platform guide](https://github.com/lizard-build/lizard-sdk/blob/main/docs/platform.md).
@@ -176,6 +184,7 @@ The SDK also manages apps, Managed Postgres, Managed Redis, Managed Object Stora
 - [Sandbox reference](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md)
 - [Platform guide](https://github.com/lizard-build/lizard-sdk/blob/main/docs/platform.md)
 - [CLI coverage and migration](https://github.com/lizard-build/lizard-sdk/blob/main/docs/cli-parity.md)
+- [Changelog](https://github.com/lizard-build/lizard-sdk/blob/main/CHANGELOG.md)
 - [Source and issues](https://github.com/lizard-build/lizard-sdk)
 
 [Apache-2.0](https://github.com/lizard-build/lizard-sdk/blob/main/LICENSE)

package/dist/index.d.mts

@@ -1829,7 +1829,7 @@ interface SandboxOpts extends ConnectionOpts {
      * is not in is rejected with a 400 rather than silently moved — that combination
      * cannot be satisfied.
      *
-     * Defaults to the platform's default sandbox region.
+     * Defaults to `'us-east-1'`, or to the volume's or snapshot's region when one is given.
      */
     region?: string;
     /** Attach a persistent volume by id, mounted at `/workspace`. */

package/dist/index.d.ts

@@ -1829,7 +1829,7 @@ interface SandboxOpts extends ConnectionOpts {
      * is not in is rejected with a 400 rather than silently moved — that combination
      * cannot be satisfied.
      *
-     * Defaults to the platform's default sandbox region.
+     * Defaults to `'us-east-1'`, or to the volume's or snapshot's region when one is given.
      */
     region?: string;
     /** Attach a persistent volume by id, mounted at `/workspace`. */

package/dist/index.js

@@ -73,6 +73,7 @@ module.exports = __toCommonJS(index_exports);
 // src/config.ts
 var DEFAULT_API_URL = "https://lizard.build";
 var DEFAULT_SANDBOX_TIMEOUT_MS = 5 * 60 * 1e3;
+var DEFAULT_SANDBOX_REGION = "us-east-1";
 var ConnectionConfig = class {
   constructor(opts) {
     this.apiKey = opts?.apiKey ?? process.env.LIZARD_API_KEY ?? "";
@@ -1686,12 +1687,21 @@ function coord(n) {
 }
 
 // src/sandbox/client.ts
+async function regionUnavailable(res) {
+  try {
+    const body = await res.clone().json();
+    return body?.code === "region_unavailable";
+  } catch {
+    return false;
+  }
+}
 var SandboxClient = class {
   static async createSandbox(template, timeoutMs, opts) {
     const ref = requireProjectRef(opts);
     const config = new ConnectionConfig(opts);
     const projectId = ref.projectId ?? await resolveProjectId(ref.project, config);
-    const res = await fetch(`${config.apiUrl}/api/sandboxes`, {
+    const defaultRegion = !opts?.region && !opts?.volumeId && !opts?.volumeName && !opts?.snapshotId;
+    const post = (region) => fetch(`${config.apiUrl}/api/sandboxes`, {
       method: "POST",
       headers: config.headers,
       body: JSON.stringify({
@@ -1702,12 +1712,14 @@ var SandboxClient = class {
         projectId,
         metadata: opts?.metadata,
         envs: opts?.envs,
-        region: opts?.region,
+        region,
         volumeId: opts?.volumeId,
         volumeName: opts?.volumeName,
         lizardToken: opts?.lizardToken
       })
     });
+    let res = await post(opts?.region || (defaultRegion ? DEFAULT_SANDBOX_REGION : void 0));
+    if (defaultRegion && res.status === 503 && await regionUnavailable(res)) res = await post(void 0);
     if (!res.ok) await handleApiError(res);
     return res.json();
   }

package/dist/index.mjs

@@ -1,6 +1,7 @@
 // src/config.ts
 var DEFAULT_API_URL = "https://lizard.build";
 var DEFAULT_SANDBOX_TIMEOUT_MS = 5 * 60 * 1e3;
+var DEFAULT_SANDBOX_REGION = "us-east-1";
 var ConnectionConfig = class {
   constructor(opts) {
     this.apiKey = opts?.apiKey ?? process.env.LIZARD_API_KEY ?? "";
@@ -1614,12 +1615,21 @@ function coord(n) {
 }
 
 // src/sandbox/client.ts
+async function regionUnavailable(res) {
+  try {
+    const body = await res.clone().json();
+    return body?.code === "region_unavailable";
+  } catch {
+    return false;
+  }
+}
 var SandboxClient = class {
   static async createSandbox(template, timeoutMs, opts) {
     const ref = requireProjectRef(opts);
     const config = new ConnectionConfig(opts);
     const projectId = ref.projectId ?? await resolveProjectId(ref.project, config);
-    const res = await fetch(`${config.apiUrl}/api/sandboxes`, {
+    const defaultRegion = !opts?.region && !opts?.volumeId && !opts?.volumeName && !opts?.snapshotId;
+    const post = (region) => fetch(`${config.apiUrl}/api/sandboxes`, {
       method: "POST",
       headers: config.headers,
       body: JSON.stringify({
@@ -1630,12 +1640,14 @@ var SandboxClient = class {
         projectId,
         metadata: opts?.metadata,
         envs: opts?.envs,
-        region: opts?.region,
+        region,
         volumeId: opts?.volumeId,
         volumeName: opts?.volumeName,
         lizardToken: opts?.lizardToken
       })
     });
+    let res = await post(opts?.region || (defaultRegion ? DEFAULT_SANDBOX_REGION : void 0));
+    if (defaultRegion && res.status === 503 && await regionUnavailable(res)) res = await post(void 0);
     if (!res.ok) await handleApiError(res);
     return res.json();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.83",
+  "version": "1.0.1",
   "description": "TypeScript and JavaScript SDK for Lizard (lizard.build): cloud sandboxes for AI agents and code execution.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",