@declaw/sdk 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.5.0]
+
+_2026-09 train: working template builds._
+
+### Added
+
+- The `buildTimeout` option on `Template.build()`, `BuildInfo.logs`,
+  `TemplateBuildStatus.templateId`, `buildId` / `logs` on `BuildError`, and
+  `TemplateBase.hasCopies()`.
+- Status checks that fail temporarily while waiting (5xx, 408, 429, network
+  errors) are retried for up to two minutes instead of ending the wait. The
+  server keeps the newest 2,000 lines of a build's output; if more arrive
+  between two status checks, a `... [earlier build output truncated]` line
+  marks the gap.
+
+### Changed
+
+- `Template.build()` now waits for the build to finish, as documented, and
+  resolves to a `BuildInfo` whose `logs` hold the output. A failed build
+  rejects with `BuildError` carrying its `buildId` and `logs`. A build still
+  running after `buildTimeout` milliseconds (default one hour) rejects with
+  `TimeoutError` naming it; the build keeps running, and
+  `Template.getBuildStatus()` follows it. To return immediately, use
+  `Template.buildInBackground()`.
+- A template that uses `copy()` now rejects with `InvalidArgumentError` when
+  built, before anything is sent. `copy()` never copied anything: a build
+  cannot upload local files, and the copies were silently dropped. Fetch files
+  in a `runCmd` step, or use `fromDockerfile()`.
+
+### Fixed
+
+- Packages added with `aptInstall()` were sent under a name the API ignores,
+  so builds succeeded without installing them. They are now installed.
+- `onBuildLogs` never fired. It now receives each new line of build output
+  while `Template.build()` waits.
+
+## [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 {
@@ -222,9 +263,15 @@ var TemplateError = class extends SandboxError {
   }
 };
 var BuildError = class extends TemplateError {
+  /** The failed build's ID, when the error comes from a build that ran (`Template.build`). */
+  buildId;
+  /** The failed build's full output, when the error comes from a build that ran. */
+  logs;
   constructor(message, opts) {
     super(message, opts);
     this.name = "BuildError";
+    this.buildId = opts?.buildId;
+    this.logs = opts?.logs ?? [];
   }
 };
 var FileUploadError = class extends SandboxError {
@@ -434,6 +481,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 +515,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 +2753,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)");
@@ -3180,7 +3254,13 @@ var TemplateBase = class {
     this._runCmds.push(cmds);
     return this;
   }
-  /** Add a file copy operation. */
+  /**
+   * Copy a local file into the template.
+   *
+   * Not supported yet: a template build cannot upload local files, so
+   * building a template that uses `copy()` throws `InvalidArgumentError`.
+   * Fetch the file in a `runCmd` step, or use `fromDockerfile`.
+   */
   copy(src, dst, mode) {
     this._copies.push({ src, dst, mode });
     return this;
@@ -3200,6 +3280,14 @@ var TemplateBase = class {
     this._startCmd = cmd;
     return this;
   }
+  /**
+   * Whether `copy()` was used. Builds reject such a template until builds can
+   * upload local files.
+   * @internal
+   */
+  hasCopies() {
+    return this._copies.length > 0;
+  }
   /** Serialize the template to a JSON-friendly object. */
   toJSON() {
     if (this._dockerfile !== void 0) {
@@ -3211,14 +3299,11 @@ var TemplateBase = class {
     if (this._runCmds.length > 0) {
       result.run_cmds = this._runCmds.map((c) => c.join(" "));
     }
-    if (this._copies.length > 0) {
-      result.copies = this._copies;
-    }
     if (Object.keys(this._envs).length > 0) {
       result.envs = this._envs;
     }
     if (this._aptPackages.length > 0) {
-      result.apt_packages = this._aptPackages;
+      result.packages = this._aptPackages;
     }
     if (this._startCmd !== void 0) {
       result.start_cmd = this._startCmd;
@@ -3230,19 +3315,70 @@ function parseBuildInfo(data) {
   return {
     buildId: data.build_id ?? data.buildId ?? "",
     status: data.status ?? "",
-    templateId: data.template_id ?? data.templateId ?? void 0
+    templateId: data.template_id ?? data.templateId ?? void 0,
+    logs: data.logs ?? []
   };
 }
 function parseTemplateBuildStatus(data) {
   return {
     buildId: data.build_id ?? data.buildId ?? "",
     status: data.status ?? "",
-    logs: data.logs ?? []
+    // A build with no output yet serializes its logs as null.
+    logs: data.logs ?? [],
+    templateId: data.template_id ?? data.templateId ?? void 0
   };
 }
 
 // src/template/template.ts
 var VALID_BUILD_ID_RE = /^[a-zA-Z0-9_-]+$/;
+var BUILD_STATUS_COMPLETED = "completed";
+var BUILD_STATUS_FAILED = "failed";
+var DEFAULT_BUILD_TIMEOUT_MS = 60 * 60 * 1e3;
+var FAILURE_LOG_LINES = 20;
+var buildPolling = {
+  /** How often a waiting build is re-read. */
+  intervalMs: 3e3,
+  /**
+   * How long status checks may keep failing temporarily (5xx, 408, 429, or no
+   * response) before the wait gives up. It rides out a sandbox-manager
+   * restart; the build itself keeps running.
+   */
+  errorWindowMs: 2 * 60 * 1e3
+};
+var BUILD_LOG_TRUNCATION_NOTICE = "... [earlier build output truncated]";
+var LOG_ANCHOR_LINES = 64;
+var REJECTIONS = [
+  AuthenticationError,
+  ConflictError,
+  InvalidArgumentError,
+  NotEnoughSpaceError,
+  NotFoundError
+];
+var LogCursor = class {
+  seen = 0;
+  tail = [];
+  newLines(logs) {
+    const fresh = logs.length === 0 || logs[0] !== BUILD_LOG_TRUNCATION_NOTICE ? logs.slice(this.seen) : this.afterTail(logs);
+    this.seen = logs.length;
+    this.tail = [...this.tail, ...fresh].slice(-LOG_ANCHOR_LINES);
+    return fresh;
+  }
+  afterTail(logs) {
+    const window = logs.slice(1);
+    const n = this.tail.length;
+    if (n > 0) {
+      for (let end = window.length; end >= n; end--) {
+        if (window[end - 1] === this.tail[n - 1] && this.tail.every((line, i) => window[end - n + i] === line)) {
+          return window.slice(end);
+        }
+      }
+    }
+    return logs;
+  }
+};
+function isTemporaryPollError(err) {
+  return err instanceof SandboxError && !REJECTIONS.some((Rejection) => err instanceof Rejection);
+}
 function assertValidBuildId(buildId) {
   if (!buildId || !VALID_BUILD_ID_RE.test(buildId)) {
     throw new InvalidArgumentError(
@@ -3250,72 +3386,131 @@ function assertValidBuildId(buildId) {
     );
   }
 }
+function buildRequestBody(template, alias, opts) {
+  if (template.hasCopies()) {
+    throw new InvalidArgumentError(
+      "TemplateBase.copy() is not supported yet: a template build cannot upload local files. Fetch them in a runCmd step, or use fromDockerfile()."
+    );
+  }
+  const body = {
+    template: template.toJSON(),
+    alias
+  };
+  if (opts?.cpuCount !== void 0) {
+    body.cpu_count = opts.cpuCount;
+  }
+  if (opts?.memoryMb !== void 0) {
+    body.memory_mb = opts.memoryMb;
+  }
+  if (opts?.diskMb !== void 0) {
+    body.disk_mb = opts.diskMb;
+  }
+  return body;
+}
+function buildFailedError(status) {
+  let message = `template build ${status.buildId} failed`;
+  const tail = status.logs.slice(-FAILURE_LOG_LINES);
+  if (tail.length > 0) {
+    message += ":\n" + tail.join("\n");
+  }
+  return new BuildError(message, { buildId: status.buildId, logs: status.logs });
+}
 var Template = class {
   /**
-   * Build a template and wait for completion.
+   * Build a template and wait for the build to finish.
+   *
+   * Builds usually take several minutes. While waiting, each new line of build
+   * output is passed to `onBuildLogs`. Sandboxes are created from the finished
+   * template by its alias: `Sandbox.create({ template: alias })`.
    *
-   * Sends POST /templates/build with the template definition.
-   * Invokes onBuildLogs for each log entry in the response.
+   * @throws {BuildError} The build failed; the error carries its logs.
+   * @throws {TimeoutError} The build was still running after `buildTimeout`.
+   *   It keeps running; follow it with `getBuildStatus()`.
+   * @throws {InvalidArgumentError} The template uses `copy()`, which is not
+   *   supported yet.
    */
   static async build(template, alias, opts) {
+    const body = buildRequestBody(template, alias, opts);
     const config = new ConnectionConfig({
       apiKey: opts?.apiKey,
       domain: opts?.domain,
       requestTimeout: opts?.requestTimeout
     });
     const client = getSharedClient(config);
-    const body = {
-      template: template.toJSON(),
-      alias
-    };
-    if (opts?.cpuCount !== void 0) {
-      body.cpu_count = opts.cpuCount;
-    }
-    if (opts?.memoryMb !== void 0) {
-      body.memory_mb = opts.memoryMb;
-    }
-    if (opts?.diskMb !== void 0) {
-      body.disk_mb = opts.diskMb;
-    }
     const data = await client.post("/templates/build", {
       json: body,
       timeout: opts?.requestTimeout
     });
-    const response = data;
-    const result = parseBuildInfo(response);
-    if (opts?.onBuildLogs && Array.isArray(response.logs)) {
-      for (const log of response.logs) {
-        opts.onBuildLogs(log);
+    const info = parseBuildInfo(data);
+    assertValidBuildId(info.buildId);
+    let status = {
+      buildId: info.buildId,
+      status: info.status,
+      logs: info.logs,
+      templateId: info.templateId
+    };
+    const buildTimeout = opts?.buildTimeout ?? DEFAULT_BUILD_TIMEOUT_MS;
+    const deadline = Date.now() + buildTimeout;
+    const timedOut = (cause) => new TimeoutError(
+      `template build ${info.buildId} was still running after ${buildTimeout}ms. It keeps running; follow it with Template.getBuildStatus('${info.buildId}').` + (cause instanceof Error ? ` Last status check: ${cause.message}` : "")
+    );
+    const cursor = new LogCursor();
+    for (; ; ) {
+      if (opts?.onBuildLogs) {
+        for (const line of cursor.newLines(status.logs)) {
+          opts.onBuildLogs(line);
+        }
+      }
+      if (status.status === BUILD_STATUS_COMPLETED) {
+        return {
+          buildId: status.buildId,
+          status: status.status,
+          templateId: status.templateId ?? info.templateId,
+          logs: status.logs
+        };
+      }
+      if (status.status === BUILD_STATUS_FAILED) {
+        throw buildFailedError(status);
+      }
+      if (Date.now() >= deadline) {
+        throw timedOut();
+      }
+      let failingSince;
+      for (; ; ) {
+        await new Promise((resolve) => setTimeout(resolve, buildPolling.intervalMs));
+        try {
+          const next = await client.get(`/templates/builds/${info.buildId}`, {
+            timeout: opts?.requestTimeout
+          });
+          status = parseTemplateBuildStatus(next);
+          break;
+        } catch (err) {
+          if (!isTemporaryPollError(err)) {
+            throw err;
+          }
+          failingSince ??= Date.now();
+          if (Date.now() - failingSince >= buildPolling.errorWindowMs) {
+            throw err;
+          }
+          if (Date.now() >= deadline) {
+            throw timedOut(err);
+          }
+        }
       }
     }
-    return result;
   }
   /**
-   * Start a template build in the background.
-   *
-   * Sends POST /templates/build with `background: true`.
+   * Start a template build and return as soon as the server has accepted it,
+   * with status `building`. Follow the build with `getBuildStatus()`.
    */
   static async buildInBackground(template, alias, opts) {
+    const body = buildRequestBody(template, alias, opts);
     const config = new ConnectionConfig({
       apiKey: opts?.apiKey,
       domain: opts?.domain,
       requestTimeout: opts?.requestTimeout
     });
     const client = getSharedClient(config);
-    const body = {
-      template: template.toJSON(),
-      alias,
-      background: true
-    };
-    if (opts?.cpuCount !== void 0) {
-      body.cpu_count = opts.cpuCount;
-    }
-    if (opts?.memoryMb !== void 0) {
-      body.memory_mb = opts.memoryMb;
-    }
-    if (opts?.diskMb !== void 0) {
-      body.disk_mb = opts.diskMb;
-    }
     const data = await client.post("/templates/build", {
       json: body,
       timeout: opts?.requestTimeout
@@ -3323,7 +3518,7 @@ var Template = class {
     return parseBuildInfo(data);
   }
   /**
-   * Get the status of a template build.
+   * Get the status of a template build, including its logs so far.
    *
    * Sends GET /templates/builds/:buildId.
    */
@@ -3865,6 +4060,9 @@ var Governance = class {
   ApiClient,
   AuthenticationError,
   BuildError,
+  CODE_IDEMPOTENCY_IN_PROGRESS,
+  CODE_IDEMPOTENCY_KEY_REUSED,
+  CODE_TEMPLATE_NOT_READY,
   CommandExitError,
   CommandHandle,
   Commands,