@declaw/sdk 1.2.3 → 1.4.0

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. */
@@ -186,9 +228,15 @@ interface InjectionDefenseConfig {
     enabled: boolean;
     sensitivity: string;
     action: string;
-    /** Detection threshold (0.0–1.0). Defaults to 0.8. */
+    /** Detection threshold (0.0–1.0). Defaults to 0.95. */
     threshold: number;
-    /** Optional domain allowlist; when undefined, applies to all domains. */
+    /**
+     * Scopes injection scanning to these destination hosts. Injection is
+     * OPT-IN per domain: with an empty or omitted list NO injection scanning
+     * runs (unlike PII/toxicity, where an empty list means all egress).
+     * Entries support exact hosts (`"api.example.com"`), `"*.suffix.com"`
+     * wildcards, and `"~regex"` patterns.
+     */
     domains?: string[];
     /** Optional Tier-2 LLM judge. */
     judge?: InjectionJudgeConfig;
@@ -451,9 +499,13 @@ interface FullInjectionDefenseOptions {
     action?: string;
     /** Run the judge on EVERY egress (high-assurance, costlier). Default false. */
     alwaysJudge?: boolean;
-    /** Optional egress allowlist to scan; omit = all domains. */
+    /**
+     * Destination hosts to scan for injection. Injection is opt-in per domain:
+     * omit or leave empty to scan none. Entries support exact hosts,
+     * `"*.suffix.com"` wildcards, and `"~regex"` patterns.
+     */
     domains?: string[];
-    /** Tier-1 classifier confidence threshold (0.0–1.0). Default 0.8. */
+    /** Tier-1 classifier confidence threshold (0.0–1.0). Default 0.95. */
     threshold?: number;
 }
 /**
@@ -1191,6 +1243,10 @@ interface SandboxOpts {
     metadata?: Record<string, string>;
     /** Environment variables. */
     envs?: Record<string, string>;
+    /** Vault secret references: ENV_NAME -> "vault://team/env/secret". The real
+     *  value is resolved server+worker-side and injected at the egress proxy —
+     *  the sandbox only ever sees a placeholder, never the secret value. */
+    vaultRefs?: Record<string, string>;
     /** Whether to create a secure sandbox. Defaults to true. */
     secure?: boolean;
     /** If false, denies all outbound traffic. Defaults to true. */
@@ -1509,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;
     });
 }
 /**
@@ -1555,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. */
@@ -1870,8 +1948,17 @@ interface VolumeCreateOpts extends VolumeRequestOpts {
  * are dropped on the server for safety.
  */
 declare class Volumes {
-    /** Create a volume by streaming a tarball (gzip tar.gz) to the server. */
-    static create(name: string, data: Uint8Array | ArrayBuffer, opts?: VolumeCreateOpts): Promise<VolumeInfo>;
+    /**
+     * Create a volume named `name`, optionally populated with `data`.
+     *
+     * `POST /volumes` is the canonical create endpoint. With `data` (a gzip tar.gz)
+     * the body is ingested into a new file-granular volume (or a legacy tarball
+     * blob if no file-granular backend is configured). Creating an empty volume
+     * (no `data`, or an empty buffer) requires a file-granular backend.
+     * `empty(name)` / `ingest(name, data)` remain available for explicit,
+     * backend-specific control.
+     */
+    static create(name: string, data?: Uint8Array | ArrayBuffer, opts?: VolumeCreateOpts): Promise<VolumeInfo>;
     /**
      * Capture the attached volume's mount path in `sandboxId` into a NEW volume.
      *
@@ -1995,4 +2082,136 @@ declare class Governance {
     static getPack(name: string, opts?: GovernanceRequestOpts): Promise<GovernancePack>;
 }
 
-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, 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, 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, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, resetSharedClients, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, volumeAttachmentToJSON };
+/**
+ * One per-destination injection rule on a secret. The egress proxy matches
+ * a request host against domainRegex and injects the secret as injectionType
+ * (bearer|header|basic|query|sigv4|oidc|hmac|redis|postgres|mysql|smtp|mongodb).
+ * The optional fields express a provider's full contract.
+ */
+interface VaultScope {
+    domainRegex: string;
+    injectionType?: string;
+    headerName?: string;
+    valuePrefix?: string;
+    basicUsername?: string;
+    extraHeaders?: Record<string, string>;
+    queryParams?: Record<string, string>;
+}
+/**
+ * Metadata for a stored secret — never the value. The value lives
+ * server-side (OpenBao) and is not returned after create.
+ */
+interface VaultSecret {
+    secretId: string;
+    name: string;
+    scopes?: VaultScope[];
+    createdAt: string;
+    updatedAt: string;
+    rotatedAt?: string;
+    rotationIntervalDays?: number;
+    rotationDue?: boolean;
+}
+/**
+ * A built-in provider template (domain + injection rules). Used so a caller
+ * can store a credential by naming the provider and supplying only the value.
+ * Carries no secret material.
+ */
+interface VaultPreset {
+    key: string;
+    name: string;
+    category: string;
+    keyHint: string;
+    docsUrl?: string;
+    scopes: VaultScope[];
+}
+/** Parse a raw wire-format scope into a VaultScope. */
+declare function parseVaultScope(data: Record<string, unknown>): VaultScope;
+/** Parse a raw wire-format secret row into a VaultSecret. */
+declare function parseVaultSecret(data: Record<string, unknown>): VaultSecret;
+/** Parse a raw wire-format preset into a VaultPreset. */
+declare function parseVaultPreset(data: Record<string, unknown>): VaultPreset;
+/** Render a VaultScope in wire (snake_case) form for request bodies. */
+declare function vaultScopeToJSON(scope: VaultScope): Record<string, unknown>;
+
+/** Shared per-call options for Vault methods. */
+interface VaultRequestOpts {
+    /** API key override. */
+    apiKey?: string;
+    /** Domain override. */
+    domain?: string;
+    /** Full API URL override. */
+    apiUrl?: string;
+    /** Per-request timeout in milliseconds. */
+    requestTimeout?: number;
+}
+/**
+ * Input for creating a vault secret. The team and environment are resolved
+ * automatically (a single "default" team + "prod" environment per account) —
+ * those concepts are not part of the public API.
+ */
+interface CreateSecretInput {
+    /** The secret value (required; never returned after create). */
+    value: string;
+    /** Secret name. Defaults to provider when omitted. */
+    name?: string;
+    /** Optional preset provider key, e.g. "openai". Supplies scopes automatically. */
+    provider?: string;
+    /** Explicit injection scopes. Required unless provider is set. */
+    scopes?: VaultScope[];
+    /** Rotation policy in days. Omitted when 0 or not set. */
+    rotationIntervalDays?: number;
+}
+/**
+ * Vault secret management. All methods are static and derive their connection
+ * from the trailing VaultRequestOpts argument (or env vars when opts is
+ * omitted). The team/environment concepts are handled automatically — every
+ * secret lives under a single auto-provisioned "default" team and "prod"
+ * environment. Secrets are addressed by name only.
+ */
+declare class Vault {
+    /**
+     * Store a secret's value (server-side, in OpenBao) plus its injection
+     * scopes, under the auto-provisioned default team + "prod" environment.
+     * Returns metadata only — the value is never echoed.
+     *
+     * POST /teams/{teamId}/vault/secrets
+     */
+    static createSecret(input: CreateSecretInput, opts?: VaultRequestOpts): Promise<VaultSecret>;
+    /**
+     * List secret metadata for the default team. Returns an empty array if no
+     * default team has been provisioned yet.
+     *
+     * GET /teams/{teamId}/vault/secrets -> {secrets}
+     */
+    static listSecrets(opts?: VaultRequestOpts): Promise<VaultSecret[]>;
+    /**
+     * Replace a secret's value by name (server-side); scopes are unchanged.
+     *
+     * POST /teams/{teamId}/vault/secrets/{secretId}/rotate {value}
+     */
+    static rotateSecret(name: string, value: string, opts?: VaultRequestOpts): Promise<void>;
+    /**
+     * Delete a secret by name — metadata and stored value.
+     *
+     * DELETE /teams/{teamId}/vault/secrets/{secretId}
+     */
+    static deleteSecret(name: string, opts?: VaultRequestOpts): Promise<void>;
+    /**
+     * Replace a secret's injection scopes by name; the value is unchanged. Use
+     * this to change a secret's destination(s) or injection format in place
+     * instead of delete + recreate. At least one scope is required.
+     *
+     * POST /teams/{teamId}/vault/secrets/{secretId}/scopes
+     */
+    static updateScopes(name: string, scopes: VaultScope[], opts?: VaultRequestOpts): Promise<void>;
+    /**
+     * List built-in provider preset catalog (templates only, no secret material).
+     *
+     * GET /vault/presets -> {presets}
+     */
+    static listPresets(opts?: VaultRequestOpts): Promise<VaultPreset[]>;
+    /** Maps a secret name to its id within the given team. */
+    private static _resolveSecretId;
+}
+
+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 };