@enclave-run/sdk 0.0.0-dev.4 → 0.0.0

package/README.md

@@ -36,14 +36,14 @@ await sandbox.kill();
 
 ## Core surface
 
-| Area | API |
-|------|-----|
-| Lifecycle | `Sandbox.create`, `sandbox.connect`, `sandbox.pause`, `sandbox.kill` |
-| Filesystem | `sandbox.files.{read, write, list, exists, remove, makeDir, watch}` |
-| Commands | `sandbox.commands.{run, start, list, kill, sendStdin}` |
-| PTY | `sandbox.pty.{create, sendInput, resize}` |
-| Snapshots | `Sandbox.createSnapshot`, `Sandbox.list` |
-| Templates | `Template().fromImage(...).copy(...)`, `Template.build`, `Template.exists` |
+| Area       | API                                                                                       |
+| ---------- | ----------------------------------------------------------------------------------------- |
+| Lifecycle  | `Sandbox.create`, `Sandbox.inRegion`, `sandbox.connect`, `sandbox.pause`, `sandbox.kill`  |
+| Filesystem | `sandbox.files.{read, write, list, exists, remove, makeDir, watch}`                       |
+| Commands   | `sandbox.commands.{run, start, list, kill, sendStdin}`                                    |
+| PTY        | `sandbox.pty.{create, sendInput, resize}`                                                 |
+| Snapshots  | `Sandbox.createSnapshot`, `Sandbox.list`                                                  |
+| Templates  | `Template().fromImage(...).copy(...)`, `Template.build`, `Template.exists`                |
 
 ## Runtimes
 
@@ -61,10 +61,30 @@ const sandbox = await Sandbox.create("base", { region: "yyz" });
 console.log(sandbox.sandboxRegion); // "yyz"
 ```
 
+For several operations in one region, create an immutable regional scope once:
+
+```ts
+const yyz = Sandbox.inRegion("yyz");
+
+const sandbox = await yyz.create("base");
+const sameSandbox = await yyz.connect(sandbox.sandboxId);
+await yyz.pause(sandbox.sandboxId);
+```
+
+Persist `sandbox.ref` when a later process needs to reconnect without relying
+on a configured default:
+
+```ts
+await save(sandbox.ref); // { sandboxId: "sbx-...", region: "yyz" }
+const sameSandbox = await Sandbox.connect(await load());
+```
+
 You can override the client default once with `ENCLAVE_REGION=yyz`. Static
 lifecycle helpers can take `region`; an instance returned by `create` or
-`connect` already carries its owner. SDK releases from before the regional
-default continue through the bounded global compatibility endpoint.
+`connect` already carries its owner. A saved reference is authoritative; a
+conflicting regional scope or explicit option fails locally. SDK releases from
+before the regional default continue through the bounded global compatibility
+endpoint.
 
 Every logical create has an idempotency key (generated by the SDK unless you
 provide one). A timeout or lost response raises `OutcomeUnknownError` with the
@@ -72,6 +92,19 @@ same-region recovery URL. Only an explicit pre-admission capacity rejection can
 be considered for another region; a transport timeout must never be retried
 elsewhere.
 
+Recover without rebuilding or resending the original create request:
+
+```ts
+try {
+  return await Sandbox.create("base", { idempotencyKey: "job-123" })
+} catch (error) {
+  if (error instanceof OutcomeUnknownError) {
+    return Sandbox.recoverCreate(error.recovery)
+  }
+  throw error
+}
+```
+
 The chosen region is also part of the sandbox host:
 
 ```
@@ -80,14 +113,14 @@ sbx-{id}-{port}.{region}.onenclave.com
 
 ## Env vars
 
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| `ENCLAVE_API_KEY` | API authentication | — |
-| `ENCLAVE_DOMAIN` | API/sandbox apex | `onenclave.com` |
-| `ENCLAVE_API_URL` | Override API URL | — |
-| `ENCLAVE_REGION` | Regional API used for create/lifecycle | `yyz` |
-| `ENCLAVE_ACCESS_TOKEN` | Alternative auth (user tokens) | — |
-| `ENCLAVE_DEBUG` | Debug logging | `false` |
+| Variable               | Purpose                                | Default         |
+| ---------------------- | -------------------------------------- | --------------- |
+| `ENCLAVE_API_KEY`      | API authentication                     | —               |
+| `ENCLAVE_DOMAIN`       | API/sandbox apex                       | `onenclave.com` |
+| `ENCLAVE_API_URL`      | Override API URL                       | —               |
+| `ENCLAVE_REGION`       | Regional API used for create/lifecycle | `yyz`           |
+| `ENCLAVE_ACCESS_TOKEN` | Alternative auth (user tokens)         | —               |
+| `ENCLAVE_DEBUG`        | Debug logging                          | `false`         |
 
 ## Docs