@declaw/sdk 1.0.4 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to the Declaw TypeScript / JavaScript SDK are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0]
+
+### Added
+
+- **Volumes API.** Upload a tarball once, attach it to one or many
+  sandboxes at create time. The server streams the blob from object
+  storage into each sandbox's overlay filesystem at boot — so N
+  parallel sandboxes share a dataset without N uploads.
+  - New `Volumes` class with static `create` / `get` / `list` /
+    `delete` methods. Body is a `Uint8Array` or `ArrayBuffer`;
+    streams end-to-end with no in-memory buffering on the server.
+  - New types: `VolumeInfo`, `VolumeAttachment`, `VolumeCreateOpts`,
+    `VolumeRequestOpts` — exported from the package root.
+  - `SandboxOpts.volumes?: VolumeAttachment[]` on `Sandbox.create` —
+    each attachment is `{ volumeId, mountPath }`. Multiple sandboxes
+    can attach the same `volumeId` in parallel.
+  - Helper functions `parseVolumeInfo` (wire → shape) and
+    `volumeAttachmentToJSON` (shape → wire).
+  - Phase 1 limits: upload body capped at 4 GiB; format must be
+    `application/gzip` (tar.gz); volumes are read-at-boot (sandbox
+    writes do not flow back). Symlinks, hardlinks, device nodes, and
+    entries containing `..` are dropped server-side for safety.
+
 ## [1.0.4]
 
 ### Changed

package/dist/index.cjs

@@ -54,6 +54,7 @@ __export(index_exports, {
   TemplateError: () => TemplateError,
   TimeoutError: () => TimeoutError,
   TransformDirection: () => TransformDirection,
+  Volumes: () => Volumes,
   WatchHandle: () => WatchHandle,
   applyTransformation: () => applyTransformation,
   codeSecurityConfigToJSON: () => codeSecurityConfigToJSON,
@@ -92,11 +93,13 @@ __export(index_exports, {
   parseSnapshotInfo: () => parseSnapshotInfo,
   parseTemplateBuildStatus: () => parseTemplateBuildStatus,
   parseToxicityConfig: () => parseToxicityConfig,
+  parseVolumeInfo: () => parseVolumeInfo,
   parseWriteInfo: () => parseWriteInfo,
   requiresTlsInterception: () => requiresTlsInterception,
   securityPolicyToJSON: () => securityPolicyToJSON,
   toxicityConfigToJSON: () => toxicityConfigToJSON,
-  validateNetworkEntry: () => validateNetworkEntry
+  validateNetworkEntry: () => validateNetworkEntry,
+  volumeAttachmentToJSON: () => volumeAttachmentToJSON
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1795,6 +1798,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;
@@ -1951,6 +1971,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
@@ -2544,6 +2567,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();
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALL_TRAFFIC,
@@ -2580,6 +2694,7 @@ var Template = class {
   TemplateError,
   TimeoutError,
   TransformDirection,
+  Volumes,
   WatchHandle,
   applyTransformation,
   codeSecurityConfigToJSON,
@@ -2618,10 +2733,12 @@ var Template = class {
   parseSnapshotInfo,
   parseTemplateBuildStatus,
   parseToxicityConfig,
+  parseVolumeInfo,
   parseWriteInfo,
   requiresTlsInterception,
   securityPolicyToJSON,
   toxicityConfigToJSON,
-  validateNetworkEntry
+  validateNetworkEntry,
+  volumeAttachmentToJSON
 });
 //# sourceMappingURL=index.cjs.map