@declaw/sdk 1.3.0 → 1.4.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,42 @@ 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 {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: 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. */
@@ -2150,4 +2214,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,42 @@ 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 {
     constructor(message: string, opts?: {
         sandboxId?: string;
+        code?: 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. */
@@ -2150,4 +2214,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.js

@@ -33,13 +33,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 {
@@ -297,6 +335,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);
         }
@@ -322,20 +369,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");
@@ -2544,9 +2607,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)");
@@ -3727,6 +3792,9 @@ export {
   ApiClient,
   AuthenticationError,
   BuildError,
+  CODE_IDEMPOTENCY_IN_PROGRESS,
+  CODE_IDEMPOTENCY_KEY_REUSED,
+  CODE_TEMPLATE_NOT_READY,
   CommandExitError,
   CommandHandle,
   Commands,