@declaw/sdk 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.2]
+
+### Fixed
+
+- **Binary-safe `files.read`.** `sandbox.files.read(path, { format: "bytes" })`
+  now returns a `Uint8Array` with the raw bytes. Previously the
+  `format` option was silently ignored: every read went through the
+  `text/plain` accept path and was UTF-8 decoded, so any byte with the
+  high bit set collapsed to the replacement character `U+FFFD` and the
+  buffer came back short of the real file length. Binary writes were
+  already routed through `PUT /files/raw` (1.0.1); this patch closes
+  the read side so PNGs, compressed archives, and other non-text blobs
+  round-trip unmodified.
+
+## [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

package/dist/index.cjs

@@ -69,6 +69,7 @@ __export(index_exports, {
   createToxicityConfig: () => createToxicityConfig,
   createTransformationRule: () => createTransformationRule,
   domainMatches: () => domainMatches,
+  getSharedClient: () => getSharedClient,
   invisibleTextConfigToJSON: () => invisibleTextConfigToJSON,
   isSensitive: () => isSensitive,
   networkPolicyToOpts: () => networkPolicyToOpts,
@@ -96,6 +97,7 @@ __export(index_exports, {
   parseVolumeInfo: () => parseVolumeInfo,
   parseWriteInfo: () => parseWriteInfo,
   requiresTlsInterception: () => requiresTlsInterception,
+  resetSharedClients: () => resetSharedClients,
   securityPolicyToJSON: () => securityPolicyToJSON,
   toxicityConfigToJSON: () => toxicityConfigToJSON,
   validateNetworkEntry: () => validateNetworkEntry,
@@ -244,6 +246,12 @@ var ApiClient = class {
   async get(path, opts) {
     return this.requestWithRetry("GET", path, opts);
   }
+  /** Send a GET request and return the response body as raw bytes. */
+  async getBytes(path, opts) {
+    const response = await this.requestWithRetry("GET", path, opts, true);
+    const buf = await response.arrayBuffer();
+    return new Uint8Array(buf);
+  }
   /** Send a POST request and return parsed JSON. */
   async post(path, opts) {
     return this.requestWithRetry("POST", path, opts);
@@ -276,6 +284,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();
@@ -395,6 +409,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";
@@ -1340,15 +1376,18 @@ var Filesystem = class {
     this.sandboxId = sandboxId;
     this.client = client;
   }
-  /**
-   * Read a file's contents as a string.
-   *
-   * @param path - Absolute path to the file.
-   * @param opts - Optional user and request timeout.
-   * @returns The file contents as a string.
-   */
   async read(path, opts) {
     const user = opts?.user ?? DEFAULT_USER;
+    if (opts?.format === "bytes") {
+      return this.client.getBytes(
+        `/sandboxes/${this.sandboxId}/files`,
+        {
+          params: { path, username: user },
+          headers: { "Accept": "application/octet-stream" },
+          timeout: opts?.requestTimeout
+        }
+      );
+    }
     const result = await this.client.get(
       `/sandboxes/${this.sandboxId}/files`,
       {
@@ -1944,54 +1983,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);
-      }
-      if (opts?.volumes && opts.volumes.length > 0) {
-        body.volumes = opts.volumes.map(volumeAttachmentToJSON);
+    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.
@@ -2008,23 +2042,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.
@@ -2041,35 +2070,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.
@@ -2221,33 +2246,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.
@@ -2477,36 +2500,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.
@@ -2519,30 +2538,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.
@@ -2556,15 +2571,11 @@ 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);
   }
 };
 
@@ -2589,19 +2600,15 @@ var Volumes = class {
       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();
-    }
+    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) {
@@ -2612,15 +2619,11 @@ var Volumes = class {
       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();
-    }
+    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) {
@@ -2630,16 +2633,12 @@ var Volumes = class {
       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();
-    }
+    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) {
@@ -2650,12 +2649,8 @@ var Volumes = class {
       apiUrl: opts?.apiUrl,
       requestTimeout: opts?.requestTimeout
     });
-    const client = new ApiClient(config);
-    try {
-      await client.delete(`/volumes/${volumeId}`, { timeout: opts?.requestTimeout });
-    } finally {
-      client.close();
-    }
+    const client = getSharedClient(config);
+    await client.delete(`/volumes/${volumeId}`, { timeout: opts?.requestTimeout });
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -2709,6 +2704,7 @@ var Volumes = class {
   createToxicityConfig,
   createTransformationRule,
   domainMatches,
+  getSharedClient,
   invisibleTextConfigToJSON,
   isSensitive,
   networkPolicyToOpts,
@@ -2736,6 +2732,7 @@ var Volumes = class {
   parseVolumeInfo,
   parseWriteInfo,
   requiresTlsInterception,
+  resetSharedClients,
   securityPolicyToJSON,
   toxicityConfigToJSON,
   validateNetworkEntry,