@declaw/sdk 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to the Declaw TypeScript / JavaScript SDK are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0]
+
+_2026-08 train: idempotent sandbox creation._
+
+### Added
+
+- `Sandbox.create` now sends an `Idempotency-Key`. A create that times out or is
+  retried no longer risks leaving a second running, billable sandbox the caller
+  has no handle for. The key is generated once per logical create and reused
+  across that call's retries.
+- A `409` carrying `idempotency_in_progress` is retried automatically, honoring
+  `Retry-After`.
+- `SandboxError.code` exposes the API's machine-readable error code, with the
+  `CODE_IDEMPOTENCY_IN_PROGRESS`, `CODE_IDEMPOTENCY_KEY_REUSED` and
+  `CODE_TEMPLATE_NOT_READY` constants exported. Branch on the code, never the
+  message.
+
+_(Retry backoff already carried jitter in this SDK; unlike the Go and Python
+clients it needed no change.)_
+
 ## [1.3.0]
 
 _2026-07 train: credential vault client + injection domain scoping._

package/dist/index.cjs

@@ -34,6 +34,9 @@ __export(index_exports, {
   ApiClient: () => ApiClient,
   AuthenticationError: () => AuthenticationError,
   BuildError: () => BuildError,
+  CODE_IDEMPOTENCY_IN_PROGRESS: () => CODE_IDEMPOTENCY_IN_PROGRESS,
+  CODE_IDEMPOTENCY_KEY_REUSED: () => CODE_IDEMPOTENCY_KEY_REUSED,
+  CODE_TEMPLATE_NOT_READY: () => CODE_TEMPLATE_NOT_READY,
   CommandExitError: () => CommandExitError,
   CommandHandle: () => CommandHandle,
   Commands: () => Commands,
@@ -170,13 +173,51 @@ var ConnectionConfig = class {
   }
 };
 
+// src/api/idempotency.ts
+var CODE_IDEMPOTENCY_IN_PROGRESS = "idempotency_in_progress";
+var CODE_IDEMPOTENCY_KEY_REUSED = "idempotency_key_reused";
+var CODE_TEMPLATE_NOT_READY = "template_not_ready";
+var MAX_RETRY_AFTER_MS = 6e4;
+function newIdempotencyKey() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) {
+    return c.randomUUID();
+  }
+  if (c?.getRandomValues) {
+    const b = c.getRandomValues(new Uint8Array(16));
+    b[6] = b[6] & 15 | 64;
+    b[8] = b[8] & 63 | 128;
+    const hex = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  }
+  return "";
+}
+function retryAfterMs(response) {
+  const raw = response.headers.get("Retry-After");
+  if (raw === null) return void 0;
+  const secs = Number(raw);
+  if (!Number.isFinite(secs) || secs < 0) return void 0;
+  return Math.min(secs * 1e3, MAX_RETRY_AFTER_MS);
+}
+
 // src/errors.ts
 var SandboxError = class extends Error {
   sandboxId;
+  /**
+   * Machine-readable error code from the API's `code` field, when present.
+   *
+   * Branch on this, never on `message`. Messages are prose and change; codes are
+   * contract. It matters most where one status means several unrelated things:
+   * a 409 from `POST /sandboxes` is either `idempotency_in_progress` (the
+   * original create is still running — retry the identical request) or
+   * `template_not_ready` (rebuild the template; retrying cannot help).
+   */
+  code;
   constructor(message, opts) {
     super(message);
     this.name = "SandboxError";
     this.sandboxId = opts?.sandboxId;
+    this.code = opts?.code;
   }
 };
 var TimeoutError = class extends SandboxError {
@@ -434,6 +475,15 @@ var ApiClient = class {
           await this.delay(attempt);
           continue;
         }
+        if (response.status === 409 && attempt < this.maxRetries - 1) {
+          const parsed = await this.readErrorBody(response);
+          if (parsed.code === CODE_IDEMPOTENCY_IN_PROGRESS) {
+            const after = retryAfterMs(response);
+            await (after !== void 0 ? new Promise((r) => setTimeout(r, after)) : this.delay(attempt));
+            continue;
+          }
+          throw this.errorFrom(response, parsed);
+        }
         if (!response.ok) {
           throw await this.buildError(response);
         }
@@ -459,20 +509,36 @@ var ApiClient = class {
       `Request failed after ${this.maxRetries} retries: ${lastError?.message ?? "unknown error"}`
     );
   }
-  async buildError(response) {
-    let message;
+  /**
+   * Read an error body ONCE.
+   *
+   * `Response` bodies are single-read streams, so the 409 path cannot inspect
+   * the code and then hand the response to a separate error builder — the
+   * second read yields nothing and the error loses its message. Everything that
+   * needs the body goes through here, and the parsed result is passed around
+   * instead of the response.
+   */
+  async readErrorBody(response) {
     try {
-      const body = await response.json();
+      const body = JSON.parse(await response.text());
       const bodyMsg = body.message ?? body.error ?? response.statusText;
-      message = `HTTP ${response.status}: ${bodyMsg}`;
+      return {
+        message: `HTTP ${response.status}: ${bodyMsg}`,
+        code: typeof body.code === "string" ? body.code : void 0
+      };
     } catch {
-      message = `HTTP ${response.status}: ${response.statusText}`;
+      return { message: `HTTP ${response.status}: ${response.statusText}` };
     }
+  }
+  errorFrom(response, parsed) {
     const ErrorClass = STATUS_ERROR_MAP[response.status];
     if (ErrorClass) {
-      return new ErrorClass(message);
+      return new ErrorClass(parsed.message, { code: parsed.code });
     }
-    return new SandboxError(message);
+    return new SandboxError(parsed.message, { code: parsed.code });
+  }
+  async buildError(response) {
+    return this.errorFrom(response, await this.readErrorBody(response));
   }
   async parseResponseBody(response) {
     const contentLength = response.headers.get("content-length");
@@ -2681,9 +2747,11 @@ var Sandbox = class _Sandbox {
     if (opts?.volumes && opts.volumes.length > 0) {
       body.volumes = opts.volumes.map(volumeAttachmentToJSON);
     }
+    const idempotencyKey = newIdempotencyKey();
     const data = await client.post("/sandboxes", {
       json: body,
-      timeout: opts?.requestTimeout
+      timeout: opts?.requestTimeout,
+      ...idempotencyKey ? { headers: { "Idempotency-Key": idempotencyKey } } : {}
     });
     const sandboxId = data.sandbox_id;
     assertValidId(sandboxId, "sandbox ID (from server)");
@@ -3865,6 +3933,9 @@ var Governance = class {
   ApiClient,
   AuthenticationError,
   BuildError,
+  CODE_IDEMPOTENCY_IN_PROGRESS,
+  CODE_IDEMPOTENCY_KEY_REUSED,
+  CODE_TEMPLATE_NOT_READY,
   CommandExitError,
   CommandHandle,
   Commands,