@declaw/sdk 1.0.4 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.1]
+
+### Changed
+
+- **Process-wide HTTP client cache.** `Sandbox.create` / `.connect` /
+  `.list`, `Volumes.*`, and `Template.*` now share a single `ApiClient`
+  per `(apiKey, apiUrl, requestTimeout)` via the new `getSharedClient`
+  helper instead of constructing a fresh instance per call. Matches the
+  symmetry added on the Python side and removes unnecessary
+  `AbortController` churn. Node's global fetch / undici dispatcher was
+  already pooling TCP + TLS under the hood, so end-to-end latency is
+  unchanged for most callers — the user-visible win is that
+  `close()` on a returned `Sandbox` is now a no-op rather than
+  aborting an in-flight request on the shared client.
+- New exports from the package root: `getSharedClient`,
+  `resetSharedClients`. Use `resetSharedClients()` from tests or
+  long-running services that want to force a full teardown.
+- `Sandbox.close()` is now a no-op. `Sandbox.kill()` still kills the
+  VM and is unchanged.
+
+## [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,
@@ -68,6 +69,7 @@ __export(index_exports, {
   createToxicityConfig: () => createToxicityConfig,
   createTransformationRule: () => createTransformationRule,
   domainMatches: () => domainMatches,
+  getSharedClient: () => getSharedClient,
   invisibleTextConfigToJSON: () => invisibleTextConfigToJSON,
   isSensitive: () => isSensitive,
   networkPolicyToOpts: () => networkPolicyToOpts,
@@ -92,11 +94,14 @@ __export(index_exports, {
   parseSnapshotInfo: () => parseSnapshotInfo,
   parseTemplateBuildStatus: () => parseTemplateBuildStatus,
   parseToxicityConfig: () => parseToxicityConfig,
+  parseVolumeInfo: () => parseVolumeInfo,
   parseWriteInfo: () => parseWriteInfo,
   requiresTlsInterception: () => requiresTlsInterception,
+  resetSharedClients: () => resetSharedClients,
   securityPolicyToJSON: () => securityPolicyToJSON,
   toxicityConfigToJSON: () => toxicityConfigToJSON,
-  validateNetworkEntry: () => validateNetworkEntry
+  validateNetworkEntry: () => validateNetworkEntry,
+  volumeAttachmentToJSON: () => volumeAttachmentToJSON
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -273,6 +278,12 @@ var ApiClient = class {
   }
   /**
    * Abort all in-flight requests and release resources.
+   *
+   * Since 1.1.1 the SDK maintains a process-wide shared ApiClient cache
+   * for hot class-method paths (Sandbox.create, Volumes.*, Template.*).
+   * Calling `close()` on a shared instance aborts its AbortController,
+   * which would cancel any concurrent in-flight call. Prefer
+   * `resetSharedClients()` if you want to tear down every cached client.
    */
   close() {
     this.abortController.abort();
@@ -392,6 +403,28 @@ var ApiClient = class {
     await new Promise((resolve) => setTimeout(resolve, ms));
   }
 };
+var _sharedClients = /* @__PURE__ */ new Map();
+function sharedKey(config) {
+  return [config.apiKey ?? "", config.apiUrl, config.requestTimeout ?? ""].join("|");
+}
+function getSharedClient(config) {
+  const key = sharedKey(config);
+  let client = _sharedClients.get(key);
+  if (!client) {
+    client = new ApiClient(config);
+    _sharedClients.set(key, client);
+  }
+  return client;
+}
+function resetSharedClients() {
+  for (const client of _sharedClients.values()) {
+    try {
+      client.close();
+    } catch {
+    }
+  }
+  _sharedClients.clear();
+}
 
 // src/sandbox/network.ts
 var ALL_TRAFFIC = "0.0.0.0/0";
@@ -1795,6 +1828,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;
@@ -1924,51 +1974,49 @@ var Sandbox = class _Sandbox {
       apiUrl: opts?.apiUrl,
       requestTimeout: opts?.requestTimeout
     });
-    const client = new ApiClient(config);
-    try {
-      const body = {
-        template: opts?.template ?? DEFAULT_TEMPLATE,
-        timeout: opts?.timeout ?? DEFAULT_TIMEOUT,
-        secure: opts?.secure ?? true
-      };
-      if (opts?.metadata) {
-        body.metadata = opts.metadata;
-      }
-      if (opts?.envs) {
-        body.envs = opts.envs;
-      }
-      if (opts?.network) {
-        body.network = networkOptsToJSON(opts.network);
-      } else if (opts?.allowInternetAccess === false) {
-        body.network = { deny_out: [ALL_TRAFFIC] };
-      }
-      if (opts?.security) {
-        body.security = { policy_json: JSON.stringify(securityPolicyToJSON(opts.security)) };
-        if (opts.security.network && !body.network) {
-          body.network = typeof opts.security.network === "object" && "allowOut" in opts.security.network ? networkOptsToJSON(opts.security.network) : opts.security.network;
-        }
-      }
-      if (opts?.lifecycle) {
-        body.lifecycle = lifecycleToJSON(opts.lifecycle);
+    const client = getSharedClient(config);
+    const body = {
+      template: opts?.template ?? DEFAULT_TEMPLATE,
+      timeout: opts?.timeout ?? DEFAULT_TIMEOUT,
+      secure: opts?.secure ?? true
+    };
+    if (opts?.metadata) {
+      body.metadata = opts.metadata;
+    }
+    if (opts?.envs) {
+      body.envs = opts.envs;
+    }
+    if (opts?.network) {
+      body.network = networkOptsToJSON(opts.network);
+    } else if (opts?.allowInternetAccess === false) {
+      body.network = { deny_out: [ALL_TRAFFIC] };
+    }
+    if (opts?.security) {
+      body.security = { policy_json: JSON.stringify(securityPolicyToJSON(opts.security)) };
+      if (opts.security.network && !body.network) {
+        body.network = typeof opts.security.network === "object" && "allowOut" in opts.security.network ? networkOptsToJSON(opts.security.network) : opts.security.network;
       }
-      const data = await client.post("/sandboxes", {
-        json: body,
-        timeout: opts?.requestTimeout
-      });
-      const sandboxId = data.sandbox_id;
-      assertValidId(sandboxId, "sandbox ID (from server)");
-      return new _Sandbox(
-        sandboxId,
-        config,
-        client,
-        data.envd_access_token,
-        data.sandbox_domain,
-        data.traffic_access_token
-      );
-    } catch (error) {
-      client.close();
-      throw error;
     }
+    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
+    });
+    const sandboxId = data.sandbox_id;
+    assertValidId(sandboxId, "sandbox ID (from server)");
+    return new _Sandbox(
+      sandboxId,
+      config,
+      client,
+      data.envd_access_token,
+      data.sandbox_domain,
+      data.traffic_access_token
+    );
   }
   /**
    * Connect to an existing sandbox.
@@ -1985,23 +2033,18 @@ var Sandbox = class _Sandbox {
       apiUrl: opts?.apiUrl,
       requestTimeout: opts?.requestTimeout
     });
-    const client = new ApiClient(config);
-    try {
-      const data = await client.get(`/sandboxes/${sandboxId}`, {
-        timeout: opts?.requestTimeout
-      });
-      return new _Sandbox(
-        data.sandbox_id,
-        config,
-        client,
-        data.envd_access_token,
-        data.sandbox_domain,
-        data.traffic_access_token
-      );
-    } catch (error) {
-      client.close();
-      throw error;
-    }
+    const client = getSharedClient(config);
+    const data = await client.get(`/sandboxes/${sandboxId}`, {
+      timeout: opts?.requestTimeout
+    });
+    return new _Sandbox(
+      data.sandbox_id,
+      config,
+      client,
+      data.envd_access_token,
+      data.sandbox_domain,
+      data.traffic_access_token
+    );
   }
   /**
    * List sandboxes.
@@ -2018,35 +2061,31 @@ var Sandbox = class _Sandbox {
       apiUrl: opts?.apiUrl,
       requestTimeout: opts?.requestTimeout
     });
-    const client = new ApiClient(config);
-    try {
-      const params = {};
-      if (opts?.query) {
-        for (const [key, value] of Object.entries(opts.query)) {
-          params[key] = value;
-        }
-      }
-      if (opts?.limit !== void 0) {
-        params.limit = String(opts.limit);
-      }
-      if (opts?.nextToken) {
-        params.next_token = opts.nextToken;
+    const client = getSharedClient(config);
+    const params = {};
+    if (opts?.query) {
+      for (const [key, value] of Object.entries(opts.query)) {
+        params[key] = value;
       }
-      const data = await client.get("/sandboxes", {
-        params,
-        timeout: opts?.requestTimeout
-      });
-      const rawSandboxes = data.sandboxes ?? [];
-      const sandboxes = rawSandboxes.map(
-        (s) => parseSandboxInfo(s)
-      );
-      return {
-        sandboxes,
-        nextToken: data.next_token ?? void 0
-      };
-    } finally {
-      client.close();
     }
+    if (opts?.limit !== void 0) {
+      params.limit = String(opts.limit);
+    }
+    if (opts?.nextToken) {
+      params.next_token = opts.nextToken;
+    }
+    const data = await client.get("/sandboxes", {
+      params,
+      timeout: opts?.requestTimeout
+    });
+    const rawSandboxes = data.sandboxes ?? [];
+    const sandboxes = rawSandboxes.map(
+      (s) => parseSandboxInfo(s)
+    );
+    return {
+      sandboxes,
+      nextToken: data.next_token ?? void 0
+    };
   }
   /**
    * Kill this sandbox.
@@ -2198,33 +2237,31 @@ var Sandbox = class _Sandbox {
       apiUrl: options.apiUrl,
       requestTimeout: options.requestTimeout
     });
-    const client = new ApiClient(config);
-    try {
-      const query = options.snapshotId ? `?snapshot_id=${encodeURIComponent(options.snapshotId)}` : "";
-      await client.post(`/sandboxes/${sandboxId}/restore${query}`, {
-        timeout: options.requestTimeout
-      });
-      const data = await client.get(`/sandboxes/${sandboxId}`, {
-        timeout: options.requestTimeout
-      });
-      return new _Sandbox(
-        data.sandbox_id,
-        config,
-        client,
-        data.envd_access_token,
-        data.sandbox_domain,
-        data.traffic_access_token
-      );
-    } catch (error) {
-      client.close();
-      throw error;
-    }
+    const client = getSharedClient(config);
+    const query = options.snapshotId ? `?snapshot_id=${encodeURIComponent(options.snapshotId)}` : "";
+    await client.post(`/sandboxes/${sandboxId}/restore${query}`, {
+      timeout: options.requestTimeout
+    });
+    const data = await client.get(`/sandboxes/${sandboxId}`, {
+      timeout: options.requestTimeout
+    });
+    return new _Sandbox(
+      data.sandbox_id,
+      config,
+      client,
+      data.envd_access_token,
+      data.sandbox_domain,
+      data.traffic_access_token
+    );
   }
   /**
-   * Close the underlying HTTP client and release resources.
+   * Historically closed the sandbox's HTTP client; since 1.1.1 the SDK
+   * maintains a process-wide shared ApiClient (see `getSharedClient` in
+   * api/client.ts) so per-sandbox close no longer tears the connection
+   * pool down. Kept as a no-op for backwards compatibility — call
+   * `resetSharedClients()` if you want to force a full teardown.
    */
   close() {
-    this._client.close();
   }
   /**
    * Support `await using sandbox = await Sandbox.create(...)` for automatic cleanup.
@@ -2454,36 +2491,32 @@ var Template = class {
       domain: opts?.domain,
       requestTimeout: opts?.requestTimeout
     });
-    const client = new ApiClient(config);
-    try {
-      const body = {
-        template: template.toJSON(),
-        alias
-      };
-      if (opts?.cpuCount !== void 0) {
-        body.cpu_count = opts.cpuCount;
-      }
-      if (opts?.memoryMb !== void 0) {
-        body.memory_mb = opts.memoryMb;
-      }
-      if (opts?.diskMb !== void 0) {
-        body.disk_mb = opts.diskMb;
-      }
-      const data = await client.post("/templates/build", {
-        json: body,
-        timeout: opts?.requestTimeout
-      });
-      const response = data;
-      const result = parseBuildInfo(response);
-      if (opts?.onBuildLogs && Array.isArray(response.logs)) {
-        for (const log of response.logs) {
-          opts.onBuildLogs(log);
-        }
+    const client = getSharedClient(config);
+    const body = {
+      template: template.toJSON(),
+      alias
+    };
+    if (opts?.cpuCount !== void 0) {
+      body.cpu_count = opts.cpuCount;
+    }
+    if (opts?.memoryMb !== void 0) {
+      body.memory_mb = opts.memoryMb;
+    }
+    if (opts?.diskMb !== void 0) {
+      body.disk_mb = opts.diskMb;
+    }
+    const data = await client.post("/templates/build", {
+      json: body,
+      timeout: opts?.requestTimeout
+    });
+    const response = data;
+    const result = parseBuildInfo(response);
+    if (opts?.onBuildLogs && Array.isArray(response.logs)) {
+      for (const log of response.logs) {
+        opts.onBuildLogs(log);
       }
-      return result;
-    } finally {
-      client.close();
     }
+    return result;
   }
   /**
    * Start a template build in the background.
@@ -2496,30 +2529,26 @@ var Template = class {
       domain: opts?.domain,
       requestTimeout: opts?.requestTimeout
     });
-    const client = new ApiClient(config);
-    try {
-      const body = {
-        template: template.toJSON(),
-        alias,
-        background: true
-      };
-      if (opts?.cpuCount !== void 0) {
-        body.cpu_count = opts.cpuCount;
-      }
-      if (opts?.memoryMb !== void 0) {
-        body.memory_mb = opts.memoryMb;
-      }
-      if (opts?.diskMb !== void 0) {
-        body.disk_mb = opts.diskMb;
-      }
-      const data = await client.post("/templates/build", {
-        json: body,
-        timeout: opts?.requestTimeout
-      });
-      return parseBuildInfo(data);
-    } finally {
-      client.close();
+    const client = getSharedClient(config);
+    const body = {
+      template: template.toJSON(),
+      alias,
+      background: true
+    };
+    if (opts?.cpuCount !== void 0) {
+      body.cpu_count = opts.cpuCount;
+    }
+    if (opts?.memoryMb !== void 0) {
+      body.memory_mb = opts.memoryMb;
     }
+    if (opts?.diskMb !== void 0) {
+      body.disk_mb = opts.diskMb;
+    }
+    const data = await client.post("/templates/build", {
+      json: body,
+      timeout: opts?.requestTimeout
+    });
+    return parseBuildInfo(data);
   }
   /**
    * Get the status of a template build.
@@ -2533,15 +2562,86 @@ var Template = class {
       domain: opts?.domain,
       requestTimeout: opts?.requestTimeout
     });
-    const client = new ApiClient(config);
-    try {
-      const data = await client.get(`/templates/builds/${buildId}`, {
-        timeout: opts?.requestTimeout
-      });
-      return parseTemplateBuildStatus(data);
-    } finally {
-      client.close();
+    const client = getSharedClient(config);
+    const data = await client.get(`/templates/builds/${buildId}`, {
+      timeout: opts?.requestTimeout
+    });
+    return parseTemplateBuildStatus(data);
+  }
+};
+
+// 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 = getSharedClient(config);
+    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);
+  }
+  /** 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 = getSharedClient(config);
+    const resp = await client.get(`/volumes/${volumeId}`, {
+      timeout: opts?.requestTimeout
+    });
+    return parseVolumeInfo(resp);
+  }
+  /** 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 = getSharedClient(config);
+    const resp = await client.get("/volumes", {
+      timeout: opts?.requestTimeout
+    });
+    const rows = resp.volumes ?? [];
+    return rows.map(parseVolumeInfo);
+  }
+  /** 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 = getSharedClient(config);
+    await client.delete(`/volumes/${volumeId}`, { timeout: opts?.requestTimeout });
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -2580,6 +2680,7 @@ var Template = class {
   TemplateError,
   TimeoutError,
   TransformDirection,
+  Volumes,
   WatchHandle,
   applyTransformation,
   codeSecurityConfigToJSON,
@@ -2594,6 +2695,7 @@ var Template = class {
   createToxicityConfig,
   createTransformationRule,
   domainMatches,
+  getSharedClient,
   invisibleTextConfigToJSON,
   isSensitive,
   networkPolicyToOpts,
@@ -2618,10 +2720,13 @@ var Template = class {
   parseSnapshotInfo,
   parseTemplateBuildStatus,
   parseToxicityConfig,
+  parseVolumeInfo,
   parseWriteInfo,
   requiresTlsInterception,
+  resetSharedClients,
   securityPolicyToJSON,
   toxicityConfigToJSON,
-  validateNetworkEntry
+  validateNetworkEntry,
+  volumeAttachmentToJSON
 });
 //# sourceMappingURL=index.cjs.map