@declaw/sdk 1.4.0 → 1.5.0

package/dist/index.d.cts

@@ -1639,9 +1639,15 @@ declare class TemplateError extends SandboxError {
 }
 /** Thrown when a template build fails. */
 declare class BuildError extends TemplateError {
+    /** The failed build's ID, when the error comes from a build that ran (`Template.build`). */
+    buildId?: string;
+    /** The failed build's full output, when the error comes from a build that ran. */
+    logs: string[];
     constructor(message: string, opts?: {
         sandboxId?: string;
         code?: string;
+        buildId?: string;
+        logs?: string[];
     });
 }
 /** Thrown when a file upload fails. */
@@ -1769,7 +1775,13 @@ declare class TemplateBase {
     fromDockerfile(content: string): this;
     /** Add a run command (as array of command + args). */
     runCmd(cmds: string[]): 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: string, dst: string, mode?: number): this;
     /** Set environment variables. */
     setEnvs(envs: Record<string, string>): this;
@@ -1777,22 +1789,37 @@ declare class TemplateBase {
     aptInstall(...packages: string[]): this;
     /** Set the start command. */
     setStartCmd(cmd: string): this;
+    /**
+     * Whether `copy()` was used. Builds reject such a template until builds can
+     * upload local files.
+     * @internal
+     */
+    hasCopies(): boolean;
     /** Serialize the template to a JSON-friendly object. */
     toJSON(): Record<string, any>;
 }
 /** Information about a template build. */
 interface BuildInfo {
     buildId: string;
+    /** `building`, then `completed` or `failed`. */
     status: string;
     templateId?: string;
+    /**
+     * Build output. Empty in the response to starting a build; filled when
+     * `Template.build()` returns a finished build.
+     */
+    logs: string[];
 }
 /** Parse raw JSON data into BuildInfo. */
 declare function parseBuildInfo(data: Record<string, any>): BuildInfo;
 /** Status of a template build. */
 interface TemplateBuildStatus {
     buildId: string;
+    /** `building`, then `completed` or `failed`. */
     status: string;
+    /** Build output so far. */
     logs: string[];
+    templateId?: string;
 }
 /** Parse raw JSON data into TemplateBuildStatus. */
 declare function parseTemplateBuildStatus(data: Record<string, any>): TemplateBuildStatus;
@@ -1805,8 +1832,10 @@ interface TemplateBuildOpts {
     memoryMb?: number;
     /** Disk size in MB for the build (128–102400). */
     diskMb?: number;
-    /** Callback invoked for each build log entry. */
+    /** Called with each new line of build output while `build()` waits. */
     onBuildLogs?: (log: string) => void;
+    /** How long `build()` waits for the build to finish, in milliseconds. Defaults to one hour. */
+    buildTimeout?: number;
     /** API key override. */
     apiKey?: string;
     /** Domain override. */
@@ -1831,20 +1860,26 @@ interface GetBuildStatusOpts {
  */
 declare class Template {
     /**
-     * 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 build(template: TemplateBase, alias: string, opts?: TemplateBuildOpts): Promise<BuildInfo>;
     /**
-     * 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 buildInBackground(template: TemplateBase, alias: string, opts?: Omit<TemplateBuildOpts, 'onBuildLogs'>): Promise<BuildInfo>;
+    static buildInBackground(template: TemplateBase, alias: string, opts?: Omit<TemplateBuildOpts, 'onBuildLogs' | 'buildTimeout'>): Promise<BuildInfo>;
     /**
-     * Get the status of a template build.
+     * Get the status of a template build, including its logs so far.
      *
      * Sends GET /templates/builds/:buildId.
      */

package/dist/index.d.ts

@@ -1639,9 +1639,15 @@ declare class TemplateError extends SandboxError {
 }
 /** Thrown when a template build fails. */
 declare class BuildError extends TemplateError {
+    /** The failed build's ID, when the error comes from a build that ran (`Template.build`). */
+    buildId?: string;
+    /** The failed build's full output, when the error comes from a build that ran. */
+    logs: string[];
     constructor(message: string, opts?: {
         sandboxId?: string;
         code?: string;
+        buildId?: string;
+        logs?: string[];
     });
 }
 /** Thrown when a file upload fails. */
@@ -1769,7 +1775,13 @@ declare class TemplateBase {
     fromDockerfile(content: string): this;
     /** Add a run command (as array of command + args). */
     runCmd(cmds: string[]): 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: string, dst: string, mode?: number): this;
     /** Set environment variables. */
     setEnvs(envs: Record<string, string>): this;
@@ -1777,22 +1789,37 @@ declare class TemplateBase {
     aptInstall(...packages: string[]): this;
     /** Set the start command. */
     setStartCmd(cmd: string): this;
+    /**
+     * Whether `copy()` was used. Builds reject such a template until builds can
+     * upload local files.
+     * @internal
+     */
+    hasCopies(): boolean;
     /** Serialize the template to a JSON-friendly object. */
     toJSON(): Record<string, any>;
 }
 /** Information about a template build. */
 interface BuildInfo {
     buildId: string;
+    /** `building`, then `completed` or `failed`. */
     status: string;
     templateId?: string;
+    /**
+     * Build output. Empty in the response to starting a build; filled when
+     * `Template.build()` returns a finished build.
+     */
+    logs: string[];
 }
 /** Parse raw JSON data into BuildInfo. */
 declare function parseBuildInfo(data: Record<string, any>): BuildInfo;
 /** Status of a template build. */
 interface TemplateBuildStatus {
     buildId: string;
+    /** `building`, then `completed` or `failed`. */
     status: string;
+    /** Build output so far. */
     logs: string[];
+    templateId?: string;
 }
 /** Parse raw JSON data into TemplateBuildStatus. */
 declare function parseTemplateBuildStatus(data: Record<string, any>): TemplateBuildStatus;
@@ -1805,8 +1832,10 @@ interface TemplateBuildOpts {
     memoryMb?: number;
     /** Disk size in MB for the build (128–102400). */
     diskMb?: number;
-    /** Callback invoked for each build log entry. */
+    /** Called with each new line of build output while `build()` waits. */
     onBuildLogs?: (log: string) => void;
+    /** How long `build()` waits for the build to finish, in milliseconds. Defaults to one hour. */
+    buildTimeout?: number;
     /** API key override. */
     apiKey?: string;
     /** Domain override. */
@@ -1831,20 +1860,26 @@ interface GetBuildStatusOpts {
  */
 declare class Template {
     /**
-     * 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 build(template: TemplateBase, alias: string, opts?: TemplateBuildOpts): Promise<BuildInfo>;
     /**
-     * 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 buildInBackground(template: TemplateBase, alias: string, opts?: Omit<TemplateBuildOpts, 'onBuildLogs'>): Promise<BuildInfo>;
+    static buildInBackground(template: TemplateBase, alias: string, opts?: Omit<TemplateBuildOpts, 'onBuildLogs' | 'buildTimeout'>): Promise<BuildInfo>;
     /**
-     * Get the status of a template build.
+     * Get the status of a template build, including its logs so far.
      *
      * Sends GET /templates/builds/:buildId.
      */

package/dist/index.js

@@ -123,9 +123,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 {
@@ -3108,7 +3114,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;
@@ -3128,6 +3140,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) {
@@ -3139,14 +3159,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;
@@ -3158,19 +3175,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(
@@ -3178,72 +3246,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.
    *
-   * Sends POST /templates/build with the template definition.
-   * Invokes onBuildLogs for each log entry in the response.
+   * 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 })`.
+   *
+   * @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
@@ -3251,7 +3378,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.
    */