@declaw/sdk 1.3.0 → 1.5.0

package/dist/index.d.cts

@@ -88,6 +88,17 @@ declare class ApiClient {
     private buildUrl;
     private buildHeaders;
     private requestWithRetry;
+    /**
+     * 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.
+     */
+    private readErrorBody;
+    private errorFrom;
     private buildError;
     private parseResponseBody;
     /**
@@ -98,6 +109,37 @@ declare class ApiClient {
 declare function getSharedClient(config: ConnectionConfig): ApiClient;
 declare function resetSharedClients(): void;
 
+/**
+ * Idempotency keys and retry pacing for `POST /sandboxes`.
+ *
+ * Note this SDK already jitters its backoff (see `ApiClient.delay` —
+ * exponential with an equal-jitter multiplier), unlike the Go and Python
+ * clients which used a deterministic `delay * attempt`. Only the key and the
+ * response-code handling are new here.
+ */
+/**
+ * Machine-readable error codes returned by `POST /sandboxes`.
+ *
+ * Branch on these, never on the message. It matters most where one status means
+ * several unrelated things, and only one of them is retryable.
+ */
+/**
+ * 409 — the original create carrying this key is still running. Retrying the
+ * IDENTICAL request is correct, and is how a caller recovers the sandbox ID
+ * after a lost response. `Retry-After` is set.
+ */
+declare const CODE_IDEMPOTENCY_IN_PROGRESS = "idempotency_in_progress";
+/**
+ * 422 — the key was already used with different parameters. Not retryable; the
+ * caller must generate a fresh key per logical create.
+ */
+declare const CODE_IDEMPOTENCY_KEY_REUSED = "idempotency_key_reused";
+/**
+ * 409 — unrelated to idempotency; the template needs a rebuild. Retrying the
+ * request unchanged cannot fix it.
+ */
+declare const CODE_TEMPLATE_NOT_READY = "template_not_ready";
+
 /** CIDR for all traffic. */
 declare const ALL_TRAFFIC = "0.0.0.0/0";
 /** Network configuration options for a sandbox. */
@@ -1523,38 +1565,54 @@ declare class Sandbox {
  */
 declare class SandboxError extends Error {
     sandboxId?: string;
+    /**
+     * 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?: string;
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when an operation exceeds its timeout. */
 declare class TimeoutError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when a sandbox or resource is not found. */
 declare class NotFoundError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when authentication fails. */
 declare class AuthenticationError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when an argument is invalid. */
 declare class InvalidArgumentError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when there is not enough disk space. */
 declare class NotEnoughSpaceError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /**
@@ -1569,36 +1627,48 @@ declare class NotEnoughSpaceError extends SandboxError {
 declare class ConflictError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown for template-related errors. */
 declare class TemplateError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** 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. */
 declare class FileUploadError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when git authentication fails inside a sandbox. */
 declare class GitAuthError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when a git upstream operation fails. */
 declare class GitUpstreamError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when a command exits with a non-zero exit code. */
@@ -1705,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;
@@ -1713,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;
@@ -1741,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. */
@@ -1767,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.
      */
@@ -2150,4 +2249,4 @@ declare class Vault {
     private static _resolveSecretId;
 }
 
-export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConflictError, ConnectionConfig, type ConnectionConfigOptions, type ContentGateConfig, type CopyItem, type CreateSecretInput, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, type FileEntry, type FileInfo, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type FullInjectionDefenseOptions, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, Governance, type GovernanceAdvisory, type GovernanceControl, type GovernancePack, type GovernanceRequestOpts, InjectionAction, type InjectionDefenseConfig, type InjectionJudgeConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type LockLease, type LockStatus, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyConnectOpts, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtyResult, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, Stdio, StdioProcess, type StdioResult, type StdioStartOpts, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, Vault, type VaultPreset, type VaultRequestOpts, type VaultScope, type VaultSecret, type VolumeAttachMode, type VolumeAttachment, type VolumeCreateOpts, VolumeFiles, type VolumeInfo, VolumeLocks, type VolumeRemoveOpts, type VolumeRequestOpts, type VolumeWriteOpts, Volumes, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, contentGateConfigToJSON, createAuditConfig, createCodeSecurityConfig, createContentGateConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, fullInjectionDefensePolicy, getSharedClient, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseContentGateConfig, parseEntryInfo, parseEnvSecurityConfig, parseFileEntry, parseFileInfo, parseFilesystemEvent, parseGovernancePack, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseLockLease, parseLockStatus, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseVaultPreset, parseVaultScope, parseVaultSecret, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, resetSharedClients, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, vaultScopeToJSON, volumeAttachmentToJSON };
+export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, CODE_IDEMPOTENCY_IN_PROGRESS, CODE_IDEMPOTENCY_KEY_REUSED, CODE_TEMPLATE_NOT_READY, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConflictError, ConnectionConfig, type ConnectionConfigOptions, type ContentGateConfig, type CopyItem, type CreateSecretInput, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, type FileEntry, type FileInfo, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type FullInjectionDefenseOptions, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, Governance, type GovernanceAdvisory, type GovernanceControl, type GovernancePack, type GovernanceRequestOpts, InjectionAction, type InjectionDefenseConfig, type InjectionJudgeConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type LockLease, type LockStatus, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyConnectOpts, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtyResult, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, Stdio, StdioProcess, type StdioResult, type StdioStartOpts, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, Vault, type VaultPreset, type VaultRequestOpts, type VaultScope, type VaultSecret, type VolumeAttachMode, type VolumeAttachment, type VolumeCreateOpts, VolumeFiles, type VolumeInfo, VolumeLocks, type VolumeRemoveOpts, type VolumeRequestOpts, type VolumeWriteOpts, Volumes, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, contentGateConfigToJSON, createAuditConfig, createCodeSecurityConfig, createContentGateConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, fullInjectionDefensePolicy, getSharedClient, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseContentGateConfig, parseEntryInfo, parseEnvSecurityConfig, parseFileEntry, parseFileInfo, parseFilesystemEvent, parseGovernancePack, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseLockLease, parseLockStatus, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseVaultPreset, parseVaultScope, parseVaultSecret, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, resetSharedClients, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, vaultScopeToJSON, volumeAttachmentToJSON };

package/dist/index.d.ts

@@ -88,6 +88,17 @@ declare class ApiClient {
     private buildUrl;
     private buildHeaders;
     private requestWithRetry;
+    /**
+     * 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.
+     */
+    private readErrorBody;
+    private errorFrom;
     private buildError;
     private parseResponseBody;
     /**
@@ -98,6 +109,37 @@ declare class ApiClient {
 declare function getSharedClient(config: ConnectionConfig): ApiClient;
 declare function resetSharedClients(): void;
 
+/**
+ * Idempotency keys and retry pacing for `POST /sandboxes`.
+ *
+ * Note this SDK already jitters its backoff (see `ApiClient.delay` —
+ * exponential with an equal-jitter multiplier), unlike the Go and Python
+ * clients which used a deterministic `delay * attempt`. Only the key and the
+ * response-code handling are new here.
+ */
+/**
+ * Machine-readable error codes returned by `POST /sandboxes`.
+ *
+ * Branch on these, never on the message. It matters most where one status means
+ * several unrelated things, and only one of them is retryable.
+ */
+/**
+ * 409 — the original create carrying this key is still running. Retrying the
+ * IDENTICAL request is correct, and is how a caller recovers the sandbox ID
+ * after a lost response. `Retry-After` is set.
+ */
+declare const CODE_IDEMPOTENCY_IN_PROGRESS = "idempotency_in_progress";
+/**
+ * 422 — the key was already used with different parameters. Not retryable; the
+ * caller must generate a fresh key per logical create.
+ */
+declare const CODE_IDEMPOTENCY_KEY_REUSED = "idempotency_key_reused";
+/**
+ * 409 — unrelated to idempotency; the template needs a rebuild. Retrying the
+ * request unchanged cannot fix it.
+ */
+declare const CODE_TEMPLATE_NOT_READY = "template_not_ready";
+
 /** CIDR for all traffic. */
 declare const ALL_TRAFFIC = "0.0.0.0/0";
 /** Network configuration options for a sandbox. */
@@ -1523,38 +1565,54 @@ declare class Sandbox {
  */
 declare class SandboxError extends Error {
     sandboxId?: string;
+    /**
+     * 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?: string;
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when an operation exceeds its timeout. */
 declare class TimeoutError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when a sandbox or resource is not found. */
 declare class NotFoundError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when authentication fails. */
 declare class AuthenticationError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when an argument is invalid. */
 declare class InvalidArgumentError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when there is not enough disk space. */
 declare class NotEnoughSpaceError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /**
@@ -1569,36 +1627,48 @@ declare class NotEnoughSpaceError extends SandboxError {
 declare class ConflictError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown for template-related errors. */
 declare class TemplateError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** 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. */
 declare class FileUploadError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when git authentication fails inside a sandbox. */
 declare class GitAuthError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when a git upstream operation fails. */
 declare class GitUpstreamError extends SandboxError {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: string;
     });
 }
 /** Thrown when a command exits with a non-zero exit code. */
@@ -1705,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;
@@ -1713,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;
@@ -1741,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. */
@@ -1767,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.
      */
@@ -2150,4 +2249,4 @@ declare class Vault {
     private static _resolveSecretId;
 }
 
-export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConflictError, ConnectionConfig, type ConnectionConfigOptions, type ContentGateConfig, type CopyItem, type CreateSecretInput, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, type FileEntry, type FileInfo, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type FullInjectionDefenseOptions, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, Governance, type GovernanceAdvisory, type GovernanceControl, type GovernancePack, type GovernanceRequestOpts, InjectionAction, type InjectionDefenseConfig, type InjectionJudgeConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type LockLease, type LockStatus, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyConnectOpts, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtyResult, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, Stdio, StdioProcess, type StdioResult, type StdioStartOpts, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, Vault, type VaultPreset, type VaultRequestOpts, type VaultScope, type VaultSecret, type VolumeAttachMode, type VolumeAttachment, type VolumeCreateOpts, VolumeFiles, type VolumeInfo, VolumeLocks, type VolumeRemoveOpts, type VolumeRequestOpts, type VolumeWriteOpts, Volumes, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, contentGateConfigToJSON, createAuditConfig, createCodeSecurityConfig, createContentGateConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, fullInjectionDefensePolicy, getSharedClient, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseContentGateConfig, parseEntryInfo, parseEnvSecurityConfig, parseFileEntry, parseFileInfo, parseFilesystemEvent, parseGovernancePack, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseLockLease, parseLockStatus, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseVaultPreset, parseVaultScope, parseVaultSecret, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, resetSharedClients, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, vaultScopeToJSON, volumeAttachmentToJSON };
+export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, CODE_IDEMPOTENCY_IN_PROGRESS, CODE_IDEMPOTENCY_KEY_REUSED, CODE_TEMPLATE_NOT_READY, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConflictError, ConnectionConfig, type ConnectionConfigOptions, type ContentGateConfig, type CopyItem, type CreateSecretInput, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, type FileEntry, type FileInfo, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type FullInjectionDefenseOptions, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, Governance, type GovernanceAdvisory, type GovernanceControl, type GovernancePack, type GovernanceRequestOpts, InjectionAction, type InjectionDefenseConfig, type InjectionJudgeConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type LockLease, type LockStatus, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyConnectOpts, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtyResult, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, Stdio, StdioProcess, type StdioResult, type StdioStartOpts, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, Vault, type VaultPreset, type VaultRequestOpts, type VaultScope, type VaultSecret, type VolumeAttachMode, type VolumeAttachment, type VolumeCreateOpts, VolumeFiles, type VolumeInfo, VolumeLocks, type VolumeRemoveOpts, type VolumeRequestOpts, type VolumeWriteOpts, Volumes, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, contentGateConfigToJSON, createAuditConfig, createCodeSecurityConfig, createContentGateConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, fullInjectionDefensePolicy, getSharedClient, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseContentGateConfig, parseEntryInfo, parseEnvSecurityConfig, parseFileEntry, parseFileInfo, parseFilesystemEvent, parseGovernancePack, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseLockLease, parseLockStatus, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseVaultPreset, parseVaultScope, parseVaultSecret, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, resetSharedClients, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, vaultScopeToJSON, volumeAttachmentToJSON };