@declaw/sdk 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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._

package/dist/index.cjs

@@ -263,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 {
@@ -3248,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;
@@ -3268,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) {
@@ -3279,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;
@@ -3298,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(
@@ -3318,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
@@ -3391,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.
    */