@declaw/sdk 1.0.4 → 1.1.0

package/dist/index.d.cts

@@ -924,6 +924,27 @@ declare class Pty {
     resize(pid: number, size: PtySize, requestTimeout?: number): Promise<void>;
 }
 
+/** Request-side shape of a volume attachment on Sandbox.create. */
+interface VolumeAttachment {
+    volumeId: string;
+    mountPath: string;
+}
+/** Server-side metadata for a single volume. */
+interface VolumeInfo {
+    volumeId: string;
+    ownerId: string;
+    name: string;
+    blobKey: string;
+    sizeBytes: number;
+    contentType: string;
+    metadata: Record<string, string>;
+    createdAt: string;
+}
+/** Convert a wire-format volume row into a VolumeInfo. */
+declare function parseVolumeInfo(data: Record<string, unknown>): VolumeInfo;
+/** Render a VolumeAttachment in wire (snake_case) form. */
+declare function volumeAttachmentToJSON(att: VolumeAttachment): Record<string, string>;
+
 /** Options for creating a sandbox. */
 interface SandboxOpts {
     /** Template to use. Defaults to 'base'. */
@@ -944,6 +965,11 @@ interface SandboxOpts {
     security?: SecurityPolicy;
     /** Lifecycle configuration. */
     lifecycle?: SandboxLifecycle;
+    /** Volumes to attach at sandbox-boot time. Each {volumeId, mountPath}
+     *  references a blob uploaded via `Volumes.create`; the orchestrator
+     *  materializes its contents under `mountPath` before the first command
+     *  is dispatched. */
+    volumes?: VolumeAttachment[];
     /** API key override. */
     apiKey?: string;
     /** Domain override (supports "host:port" format, e.g. "104.198.24.180:8080"). */
@@ -1407,4 +1433,35 @@ declare class Template {
     static getBuildStatus(buildId: string, opts?: GetBuildStatusOpts): Promise<TemplateBuildStatus>;
 }
 
-export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, 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, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseWriteInfo, requiresTlsInterception, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry };
+/** Shared per-call options. */
+interface VolumeRequestOpts {
+    apiKey?: string;
+    domain?: string;
+    apiUrl?: string;
+    requestTimeout?: number;
+}
+/** Options for Volumes.create. */
+interface VolumeCreateOpts extends VolumeRequestOpts {
+    /** Override the Content-Type header. Defaults to application/gzip. */
+    contentType?: string;
+}
+/**
+ * Volumes: upload a tarball once and attach it to one or many sandboxes.
+ *
+ * Phase 1: the body must be a gzip-compressed tar archive; the server
+ * materializes regular-file entries inside the sandbox filesystem under
+ * the attachment's mount_path. Symlinks, hardlinks, and device nodes
+ * are dropped on the server for safety.
+ */
+declare class Volumes {
+    /** Create a volume by streaming a tarball to the server. */
+    static create(name: string, data: Uint8Array | ArrayBuffer, opts?: VolumeCreateOpts): Promise<VolumeInfo>;
+    /** Fetch metadata for a single volume. */
+    static get(volumeId: string, opts?: VolumeRequestOpts): Promise<VolumeInfo>;
+    /** List all volumes owned by the caller, newest first. */
+    static list(opts?: VolumeRequestOpts): Promise<VolumeInfo[]>;
+    /** Delete a volume and its blob. Idempotent on the wire. */
+    static delete(volumeId: string, opts?: VolumeRequestOpts): Promise<void>;
+}
+
+export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, 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, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, type VolumeAttachment, type VolumeCreateOpts, type VolumeInfo, type VolumeRequestOpts, Volumes, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, volumeAttachmentToJSON };

package/dist/index.d.ts

@@ -924,6 +924,27 @@ declare class Pty {
     resize(pid: number, size: PtySize, requestTimeout?: number): Promise<void>;
 }
 
+/** Request-side shape of a volume attachment on Sandbox.create. */
+interface VolumeAttachment {
+    volumeId: string;
+    mountPath: string;
+}
+/** Server-side metadata for a single volume. */
+interface VolumeInfo {
+    volumeId: string;
+    ownerId: string;
+    name: string;
+    blobKey: string;
+    sizeBytes: number;
+    contentType: string;
+    metadata: Record<string, string>;
+    createdAt: string;
+}
+/** Convert a wire-format volume row into a VolumeInfo. */
+declare function parseVolumeInfo(data: Record<string, unknown>): VolumeInfo;
+/** Render a VolumeAttachment in wire (snake_case) form. */
+declare function volumeAttachmentToJSON(att: VolumeAttachment): Record<string, string>;
+
 /** Options for creating a sandbox. */
 interface SandboxOpts {
     /** Template to use. Defaults to 'base'. */
@@ -944,6 +965,11 @@ interface SandboxOpts {
     security?: SecurityPolicy;
     /** Lifecycle configuration. */
     lifecycle?: SandboxLifecycle;
+    /** Volumes to attach at sandbox-boot time. Each {volumeId, mountPath}
+     *  references a blob uploaded via `Volumes.create`; the orchestrator
+     *  materializes its contents under `mountPath` before the first command
+     *  is dispatched. */
+    volumes?: VolumeAttachment[];
     /** API key override. */
     apiKey?: string;
     /** Domain override (supports "host:port" format, e.g. "104.198.24.180:8080"). */
@@ -1407,4 +1433,35 @@ declare class Template {
     static getBuildStatus(buildId: string, opts?: GetBuildStatusOpts): Promise<TemplateBuildStatus>;
 }
 
-export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, 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, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseWriteInfo, requiresTlsInterception, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry };
+/** Shared per-call options. */
+interface VolumeRequestOpts {
+    apiKey?: string;
+    domain?: string;
+    apiUrl?: string;
+    requestTimeout?: number;
+}
+/** Options for Volumes.create. */
+interface VolumeCreateOpts extends VolumeRequestOpts {
+    /** Override the Content-Type header. Defaults to application/gzip. */
+    contentType?: string;
+}
+/**
+ * Volumes: upload a tarball once and attach it to one or many sandboxes.
+ *
+ * Phase 1: the body must be a gzip-compressed tar archive; the server
+ * materializes regular-file entries inside the sandbox filesystem under
+ * the attachment's mount_path. Symlinks, hardlinks, and device nodes
+ * are dropped on the server for safety.
+ */
+declare class Volumes {
+    /** Create a volume by streaming a tarball to the server. */
+    static create(name: string, data: Uint8Array | ArrayBuffer, opts?: VolumeCreateOpts): Promise<VolumeInfo>;
+    /** Fetch metadata for a single volume. */
+    static get(volumeId: string, opts?: VolumeRequestOpts): Promise<VolumeInfo>;
+    /** List all volumes owned by the caller, newest first. */
+    static list(opts?: VolumeRequestOpts): Promise<VolumeInfo[]>;
+    /** Delete a volume and its blob. Idempotent on the wire. */
+    static delete(volumeId: string, opts?: VolumeRequestOpts): Promise<void>;
+}
+
+export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, 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, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, type VolumeAttachment, type VolumeCreateOpts, type VolumeInfo, type VolumeRequestOpts, Volumes, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, volumeAttachmentToJSON };

package/dist/index.js

@@ -1693,6 +1693,23 @@ var Pty = class {
   }
 };
 
+// src/volumes/models.ts
+function parseVolumeInfo(data) {
+  return {
+    volumeId: String(data.volume_id ?? ""),
+    ownerId: String(data.owner_id ?? ""),
+    name: String(data.name ?? ""),
+    blobKey: String(data.blob_key ?? ""),
+    sizeBytes: Number(data.size_bytes ?? 0),
+    contentType: String(data.content_type ?? ""),
+    metadata: data.metadata ?? {},
+    createdAt: String(data.created_at ?? "")
+  };
+}
+function volumeAttachmentToJSON(att) {
+  return { volume_id: att.volumeId, mount_path: att.mountPath };
+}
+
 // src/sandbox/sandbox.ts
 var DEFAULT_TEMPLATE = "base";
 var DEFAULT_TIMEOUT = 300;
@@ -1849,6 +1866,9 @@ var Sandbox = class _Sandbox {
       if (opts?.lifecycle) {
         body.lifecycle = lifecycleToJSON(opts.lifecycle);
       }
+      if (opts?.volumes && opts.volumes.length > 0) {
+        body.volumes = opts.volumes.map(volumeAttachmentToJSON);
+      }
       const data = await client.post("/sandboxes", {
         json: body,
         timeout: opts?.requestTimeout
@@ -2442,6 +2462,97 @@ var Template = class {
     }
   }
 };
+
+// src/volumes/volumes.ts
+var VALID_VOLUME_ID_RE = /^[a-zA-Z0-9_-]+$/;
+function assertValidVolumeId(id) {
+  if (!id || !VALID_VOLUME_ID_RE.test(id)) {
+    throw new InvalidArgumentError(
+      `Invalid volume ID: "${id}". Must be alphanumeric with hyphens/underscores only.`
+    );
+  }
+}
+var Volumes = class {
+  /** Create a volume by streaming a tarball to the server. */
+  static async create(name, data, opts) {
+    if (!name) {
+      throw new InvalidArgumentError("volume name is required");
+    }
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = new ApiClient(config);
+    try {
+      const body = data instanceof Uint8Array ? data : new Uint8Array(data);
+      const resp = await client.post("/volumes", {
+        params: { name },
+        body,
+        headers: { "Content-Type": opts?.contentType ?? "application/gzip" },
+        timeout: opts?.requestTimeout
+      });
+      return parseVolumeInfo(resp);
+    } finally {
+      client.close();
+    }
+  }
+  /** Fetch metadata for a single volume. */
+  static async get(volumeId, opts) {
+    assertValidVolumeId(volumeId);
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = new ApiClient(config);
+    try {
+      const resp = await client.get(`/volumes/${volumeId}`, {
+        timeout: opts?.requestTimeout
+      });
+      return parseVolumeInfo(resp);
+    } finally {
+      client.close();
+    }
+  }
+  /** List all volumes owned by the caller, newest first. */
+  static async list(opts) {
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = new ApiClient(config);
+    try {
+      const resp = await client.get("/volumes", {
+        timeout: opts?.requestTimeout
+      });
+      const rows = resp.volumes ?? [];
+      return rows.map(parseVolumeInfo);
+    } finally {
+      client.close();
+    }
+  }
+  /** Delete a volume and its blob. Idempotent on the wire. */
+  static async delete(volumeId, opts) {
+    assertValidVolumeId(volumeId);
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = new ApiClient(config);
+    try {
+      await client.delete(`/volumes/${volumeId}`, { timeout: opts?.requestTimeout });
+    } finally {
+      client.close();
+    }
+  }
+};
 export {
   ALL_TRAFFIC,
   ApiClient,
@@ -2477,6 +2588,7 @@ export {
   TemplateError,
   TimeoutError,
   TransformDirection,
+  Volumes,
   WatchHandle,
   applyTransformation,
   codeSecurityConfigToJSON,
@@ -2515,10 +2627,12 @@ export {
   parseSnapshotInfo,
   parseTemplateBuildStatus,
   parseToxicityConfig,
+  parseVolumeInfo,
   parseWriteInfo,
   requiresTlsInterception,
   securityPolicyToJSON,
   toxicityConfigToJSON,
-  validateNetworkEntry
+  validateNetworkEntry,
+  volumeAttachmentToJSON
 };
 //# sourceMappingURL=index.js.map