@hsuite/smart-engines-sdk 3.4.1 → 3.5.0

package/dist/nestjs/index.js

@@ -1100,6 +1100,167 @@ var ClusterDiscoveryClient = class {
   }
 };
 
+// src/http/index.ts
+var SdkHttpError = class extends Error {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "SdkHttpError";
+  }
+  statusCode;
+  details;
+};
+function createHttpClient(config) {
+  const timeout = config.timeout ?? 3e4;
+  function getHeaders(contentType) {
+    const headers = {};
+    if (contentType) {
+      headers["Content-Type"] = contentType;
+    }
+    if (config.authToken) {
+      headers["Authorization"] = `Bearer ${config.authToken}`;
+    }
+    if (config.apiKey) {
+      headers["X-API-Key"] = config.apiKey;
+    }
+    return headers;
+  }
+  function setAuthToken(token) {
+    config.authToken = token;
+  }
+  function getAuthToken() {
+    return config.authToken;
+  }
+  async function request(method, path, body) {
+    const url = `${config.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const init = {
+        method,
+        headers: getHeaders("application/json"),
+        signal: controller.signal
+      };
+      if (body !== void 0) {
+        init.body = JSON.stringify(body);
+      }
+      const response = await fetch(url, init);
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new SdkHttpError(
+          errorData.message || `API error: ${response.status} ${response.statusText}`,
+          response.status,
+          errorData
+        );
+      }
+      const text = await response.text();
+      if (!text) return void 0;
+      return JSON.parse(text);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof SdkHttpError) throw error;
+      const err = error;
+      if (err.name === "AbortError") {
+        throw new SdkHttpError("Request timeout", 408);
+      }
+      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
+    }
+  }
+  async function getText(path) {
+    const url = `${config.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: getHeaders(),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errBody = await response.json().catch(() => ({}));
+        throw new SdkHttpError(
+          errBody.message || `API error: ${response.status} ${response.statusText}`,
+          response.status,
+          errBody
+        );
+      }
+      return await response.text();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof SdkHttpError) throw error;
+      const err = error;
+      if (err.name === "AbortError") {
+        throw new SdkHttpError("Request timeout", 408);
+      }
+      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
+    }
+  }
+  async function upload(path, file, filename, metadata, fieldName = "file") {
+    const url = `${config.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout * 2);
+    try {
+      const formData = new FormData();
+      const blob = file instanceof Blob ? file : new Blob([new Uint8Array(file)]);
+      formData.append(fieldName, blob, filename);
+      if (metadata) {
+        for (const [key, value] of Object.entries(metadata)) {
+          formData.append(key, value);
+        }
+      }
+      const headers = {};
+      if (config.authToken) {
+        headers["Authorization"] = `Bearer ${config.authToken}`;
+      }
+      if (config.apiKey) {
+        headers["X-API-Key"] = config.apiKey;
+      }
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: formData,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new SdkHttpError(
+          errorData.message || `Upload error: ${response.status} ${response.statusText}`,
+          response.status,
+          errorData
+        );
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof SdkHttpError) throw error;
+      const err = error;
+      if (err.name === "AbortError") {
+        throw new SdkHttpError("Upload timeout", 408);
+      }
+      throw new SdkHttpError(`Upload error: ${err.message}`, 0, error);
+    }
+  }
+  const client = {
+    post: (path, body) => request("POST", path, body),
+    get: (path) => request("GET", path),
+    put: (path, body) => request("PUT", path, body),
+    patch: (path, body) => request("PATCH", path, body),
+    delete: (path) => request("DELETE", path),
+    getText,
+    upload: ((path, file, filename, metadata, fieldName) => upload(path, file, filename, metadata, fieldName)),
+    setAuthToken,
+    getAuthToken
+  };
+  return client;
+}
+function encodePathParam(param) {
+  return encodeURIComponent(param).replace(/%2F/gi, "");
+}
+
 // src/discovery/discovery-client.ts
 var DiscoveryClient = class {
   constructor(http) {
@@ -1133,7 +1294,7 @@ var DiscoveryClient = class {
    * try/catch.
    */
   async getClusterByNode(nodeId) {
-    return this.http.get(`/discovery/clusters/${encodeURIComponent(nodeId)}`);
+    return this.http.get(`/discovery/clusters/${encodePathParam(nodeId)}`);
   }
 };
 var PlatformImagesClient = class {
@@ -1163,7 +1324,7 @@ var PlatformImagesClient = class {
    * authorized?" queries.
    */
   async get(imageName) {
-    return this.http.get(`/discovery/platform-images/${encodeURIComponent(imageName)}`);
+    return this.http.get(`/discovery/platform-images/${encodePathParam(imageName)}`);
   }
   /**
    * `GET /api/v3/discovery/platform-images/:imageName/:version` —
@@ -1172,7 +1333,7 @@ var PlatformImagesClient = class {
    */
   async getVersion(imageName, version) {
     return this.http.get(
-      `/discovery/platform-images/${encodeURIComponent(imageName)}/${encodeURIComponent(version)}`
+      `/discovery/platform-images/${encodePathParam(imageName)}/${encodePathParam(version)}`
     );
   }
   /**
@@ -1186,13 +1347,63 @@ var PlatformImagesClient = class {
    */
   async verify(imageName, version, digest) {
     return this.http.get(
-      `/discovery/platform-images/${encodeURIComponent(imageName)}/${encodeURIComponent(
+      `/discovery/platform-images/${encodePathParam(imageName)}/${encodePathParam(
         version
       )}/verify?digest=${encodeURIComponent(digest)}`
     );
   }
 };
 
+// src/network-presets.ts
+var KNOWN_NETWORKS = {
+  testnet: {
+    bootstrap: ["https://gateway.testnet.hsuite.network"]
+  },
+  mainnet: {
+    // Mainnet entrypoint reserved. The SDK still resolves the name so
+    // upgrade-by-flipping-NETWORK works; the bootstrap URL is the
+    // pre-allocated DNS we own. If mainnet isn't deployed yet, the discovery
+    // fetch will fail at runtime with the same "no seed reachable" error
+    // any unreachable URL produces — the caller learns the network is not
+    // live, rather than getting a baffling "unknown network" TypeScript
+    // error at compile time.
+    bootstrap: ["https://gateway.hsuite.network"]
+  }
+};
+function resolveNetwork(name) {
+  const preset = KNOWN_NETWORKS[name];
+  if (!preset) {
+    throw new Error(
+      `Unknown network: "${name}". Known networks: ${Object.keys(KNOWN_NETWORKS).join(", ")}`
+    );
+  }
+  return preset;
+}
+
+// src/discovery/resolve-cluster.ts
+async function resolveClusterEndpoint(config) {
+  const allowInsecure = config.allowInsecure ?? false;
+  const bootstrap = config.bootstrap ? [...config.bootstrap] : config.network ? [...resolveNetwork(config.network).bootstrap] : [];
+  if (bootstrap.length === 0) {
+    return { ok: false, reason: "no-seeds" };
+  }
+  const discovery = new ClusterDiscoveryClient({
+    bootstrap,
+    allowInsecure,
+    trustAnchor: config.trustAnchor ? {
+      network: config.trustAnchor.network,
+      registryTopicId: config.trustAnchor.registryTopicId,
+      mirrorNodeUrl: config.trustAnchor.mirrorNodeUrl,
+      allowInsecure
+    } : void 0
+  });
+  const cluster = await discovery.getRandomCluster();
+  if (!cluster) {
+    return { ok: false, reason: "no-clusters" };
+  }
+  return { ok: true, cluster };
+}
+
 // src/auth/validator-auth.ts
 var SUPPORTED_AUTH_CHAINS = [
   "hedera",
@@ -1201,6 +1412,10 @@ var SUPPORTED_AUTH_CHAINS = [
   "stellar",
   "solana"
 ];
+function toBytes(value) {
+  if (value instanceof Uint8Array) return value;
+  return value.toBytes();
+}
 function validateValidatorUrl(url, allowInsecure = false) {
   try {
     const parsed = new URL(url);
@@ -1400,30 +1615,42 @@ var ValidatorAuthClient = class {
     }
   }
   /**
-   * Sign challenge with Hedera private key
+   * Sign challenge with Hedera private key.
+   *
+   * Structurally typed against the surface of `@hashgraph/sdk`'s
+   * `PrivateKey`. We don't `import` the SDK directly — pulling it into
+   * the smart-engine SDK's runtime would bloat browser bundles and bring
+   * peer-dep churn — but any object with a compatible `sign(...)` method
+   * works.
    *
    * @param challenge - Challenge string from validator
-   * @param privateKey - Hedera PrivateKey instance from @hashgraph/sdk
+   * @param privateKey - Hedera PrivateKey instance (or compatible signer)
    * @returns Hex-encoded signature
    */
   signChallengeHedera(challenge, privateKey) {
-    const messageBytes = Buffer.from(challenge, "utf-8");
+    const messageBytes = new Uint8Array(Buffer.from(challenge, "utf-8"));
     const signature = privateKey.sign(messageBytes);
-    return Buffer.from(signature).toString("hex");
+    return Buffer.from(toBytes(signature)).toString("hex");
   }
   /**
-   * Sign challenge with XRPL wallet
+   * Sign challenge with XRPL wallet.
+   *
+   * Structurally typed against the surface of xrpl's `Wallet` — see the
+   * comment on {@link HederaSigner} for the "no direct import" rationale.
+   * Accepts both the modern `{ signedTransaction }` envelope and the
+   * legacy bare-string return shape.
    *
    * @param challenge - Challenge string from validator
-   * @param wallet - XRPL Wallet instance from xrpl library
+   * @param wallet - XRPL Wallet instance (or compatible signer)
    * @returns Hex-encoded signature
    */
   signChallengeXRPL(challenge, wallet) {
     const signature = wallet.sign(challenge);
-    if (typeof signature === "string" && /^[0-9A-Fa-f]+$/.test(signature)) {
-      return signature;
+    if (typeof signature === "string") {
+      if (/^[0-9A-Fa-f]+$/.test(signature)) return signature;
+      return Buffer.from(signature).toString("hex");
     }
-    return Buffer.from(signature).toString("hex");
+    return signature.signedTransaction;
   }
   /**
    * Complete authentication flow in one call
@@ -1460,189 +1687,6 @@ var ValidatorAuthError = class extends Error {
   details;
 };
 
-// src/http/index.ts
-var SdkHttpError = class extends Error {
-  constructor(message, statusCode, details) {
-    super(message);
-    this.statusCode = statusCode;
-    this.details = details;
-    this.name = "SdkHttpError";
-  }
-  statusCode;
-  details;
-};
-function createHttpClient(config) {
-  const timeout = config.timeout ?? 3e4;
-  function getHeaders(contentType) {
-    const headers = {};
-    if (contentType) {
-      headers["Content-Type"] = contentType;
-    }
-    if (config.authToken) {
-      headers["Authorization"] = `Bearer ${config.authToken}`;
-    }
-    if (config.apiKey) {
-      headers["X-API-Key"] = config.apiKey;
-    }
-    return headers;
-  }
-  function setAuthToken(token) {
-    config.authToken = token;
-  }
-  async function request(method, path, body) {
-    const url = `${config.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-    try {
-      const init = {
-        method,
-        headers: getHeaders("application/json"),
-        signal: controller.signal
-      };
-      if (body !== void 0) {
-        init.body = JSON.stringify(body);
-      }
-      const response = await fetch(url, init);
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        throw new SdkHttpError(
-          errorData.message || `API error: ${response.status} ${response.statusText}`,
-          response.status,
-          errorData
-        );
-      }
-      const text = await response.text();
-      if (!text) return void 0;
-      return JSON.parse(text);
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof SdkHttpError) throw error;
-      const err = error;
-      if (err.name === "AbortError") {
-        throw new SdkHttpError("Request timeout", 408);
-      }
-      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
-    }
-  }
-  async function getText(path) {
-    const url = `${config.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-    try {
-      const response = await fetch(url, {
-        method: "GET",
-        headers: getHeaders(),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errBody = await response.json().catch(() => ({}));
-        throw new SdkHttpError(
-          errBody.message || `API error: ${response.status} ${response.statusText}`,
-          response.status,
-          errBody
-        );
-      }
-      return await response.text();
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof SdkHttpError) throw error;
-      const err = error;
-      if (err.name === "AbortError") {
-        throw new SdkHttpError("Request timeout", 408);
-      }
-      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
-    }
-  }
-  async function upload(path, file, filename, metadata, fieldName = "file") {
-    const url = `${config.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout * 2);
-    try {
-      const formData = new FormData();
-      const blob = file instanceof Blob ? file : new Blob([new Uint8Array(file)]);
-      formData.append(fieldName, blob, filename);
-      if (metadata) {
-        for (const [key, value] of Object.entries(metadata)) {
-          formData.append(key, value);
-        }
-      }
-      const headers = {};
-      if (config.authToken) {
-        headers["Authorization"] = `Bearer ${config.authToken}`;
-      }
-      if (config.apiKey) {
-        headers["X-API-Key"] = config.apiKey;
-      }
-      const response = await fetch(url, {
-        method: "POST",
-        headers,
-        body: formData,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        throw new SdkHttpError(
-          errorData.message || `Upload error: ${response.status} ${response.statusText}`,
-          response.status,
-          errorData
-        );
-      }
-      return response.json();
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof SdkHttpError) throw error;
-      const err = error;
-      if (err.name === "AbortError") {
-        throw new SdkHttpError("Upload timeout", 408);
-      }
-      throw new SdkHttpError(`Upload error: ${err.message}`, 0, error);
-    }
-  }
-  const client = {
-    post: (path, body) => request("POST", path, body),
-    get: (path) => request("GET", path),
-    put: (path, body) => request("PUT", path, body),
-    patch: (path, body) => request("PATCH", path, body),
-    delete: (path) => request("DELETE", path),
-    getText,
-    upload: ((path, file, filename, metadata, fieldName) => upload(path, file, filename, metadata, fieldName)),
-    setAuthToken
-  };
-  return client;
-}
-function encodePathParam(param) {
-  return encodeURIComponent(param).replace(/%2F/gi, "");
-}
-
-// src/network-presets.ts
-var KNOWN_NETWORKS = {
-  testnet: {
-    bootstrap: ["https://gateway.testnet.hsuite.network"]
-  },
-  mainnet: {
-    // Mainnet entrypoint reserved. The SDK still resolves the name so
-    // upgrade-by-flipping-NETWORK works; the bootstrap URL is the
-    // pre-allocated DNS we own. If mainnet isn't deployed yet, the discovery
-    // fetch will fail at runtime with the same "no seed reachable" error
-    // any unreachable URL produces — the caller learns the network is not
-    // live, rather than getting a baffling "unknown network" TypeScript
-    // error at compile time.
-    bootstrap: ["https://gateway.hsuite.network"]
-  }
-};
-function resolveNetwork(name) {
-  const preset = KNOWN_NETWORKS[name];
-  if (!preset) {
-    throw new Error(
-      `Unknown network: "${name}". Known networks: ${Object.keys(KNOWN_NETWORKS).join(", ")}`
-    );
-  }
-  return preset;
-}
-
 // src/subscription/index.ts
 var SubscriptionClient = class {
   constructor(http) {
@@ -1660,13 +1704,13 @@ var SubscriptionClient = class {
    * Get subscription status by app ID
    */
   async getStatus(appId) {
-    return this.http.get(`/subscription/status/${encodeURIComponent(appId)}`);
+    return this.http.get(`/subscription/status/${encodePathParam(appId)}`);
   }
   /**
    * Mint subscription NFT after deposit is confirmed
    */
   async mintNft(appId) {
-    return this.http.post(`/subscription/mint/${encodeURIComponent(appId)}`, {});
+    return this.http.post(`/subscription/mint/${encodePathParam(appId)}`, {});
   }
   /**
    * Renew subscription by extending period
@@ -1735,13 +1779,13 @@ var SubscriptionClient = class {
    * List subscriptions by status
    */
   async listByStatus(status) {
-    return this.http.get(`/subscription/list/status/${encodeURIComponent(status)}`);
+    return this.http.get(`/subscription/list/status/${encodePathParam(status)}`);
   }
   /**
    * Get subscription balance
    */
   async getBalance(appId) {
-    return this.http.get(`/subscription/balance/${encodeURIComponent(appId)}`);
+    return this.http.get(`/subscription/balance/${encodePathParam(appId)}`);
   }
   // ─── Tier-Change Endpoints ────────────────────────────────────────────────
   /**
@@ -1773,19 +1817,19 @@ var SubscriptionClient = class {
    */
   async getActiveFor(walletAddress) {
     return this.http.get(
-      `/subscription/active-for/${encodeURIComponent(walletAddress)}`
+      `/subscription/active-for/${encodePathParam(walletAddress)}`
     );
   }
   /** Today's consumption breakdown by category for an app. Owner-only. */
   async getUsage(appId) {
-    return this.http.get(`/subscription/usage/${encodeURIComponent(appId)}`);
+    return this.http.get(`/subscription/usage/${encodePathParam(appId)}`);
   }
   /**
    * Current usage with overage info: usage percent, grace status,
    * upgrade suggestion, projected days until limit. Owner-only.
    */
   async getUsageStatus(appId) {
-    return this.http.get(`/subscription/usage/status/${encodeURIComponent(appId)}`);
+    return this.http.get(`/subscription/usage/status/${encodePathParam(appId)}`);
   }
   /**
    * Subscription balance deduction history. Pagination + ISO-8601 range
@@ -1799,7 +1843,7 @@ var SubscriptionClient = class {
     if (options?.to) params.append("to", options.to);
     const qs = params.toString();
     return this.http.get(
-      `/subscription/billing/${encodeURIComponent(appId)}${qs ? `?${qs}` : ""}`
+      `/subscription/billing/${encodePathParam(appId)}${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -1842,7 +1886,7 @@ var TSSClient = class {
    * Get entity details by ID
    */
   async getEntity(entityId) {
-    return this.http.get(`/tss/entity/${encodeURIComponent(entityId)}`);
+    return this.http.get(`/tss/entity/${encodePathParam(entityId)}`);
   }
   /**
    * Sign a transaction using MPC.
@@ -1899,7 +1943,7 @@ var TSSClient = class {
    * Get multi-sig transaction status by transaction ID
    */
   async getMultiSigStatus(txId) {
-    return this.http.get(`/tss/multisig/transactions/${encodeURIComponent(txId)}`);
+    return this.http.get(`/tss/multisig/transactions/${encodePathParam(txId)}`);
   }
   /**
    * Async-job variant of {@link createEntity}.
@@ -1923,7 +1967,7 @@ var TSSClient = class {
    * {@link createEntityAsync} or {@link reshareClusterAsync}.
    */
   async getJob(jobId) {
-    return this.http.get(`/tss/jobs/${encodeURIComponent(jobId)}`);
+    return this.http.get(`/tss/jobs/${encodePathParam(jobId)}`);
   }
   /**
    * Sign a hex payload as smart-app entity `appId` via the cluster's TSS
@@ -1935,7 +1979,7 @@ var TSSClient = class {
    *   - ≥32 bytes, ≤8KB
    */
   async signForApp(appId, request) {
-    return this.http.post(`/tss/entity/${encodeURIComponent(appId)}/sign`, request);
+    return this.http.post(`/tss/entity/${encodePathParam(appId)}/sign`, request);
   }
 };
 
@@ -1960,31 +2004,31 @@ var IPFSClient = class {
    * Pin content by CID to ensure it persists
    */
   async pin(cid) {
-    return this.http.post(`/ipfs/pin/${encodeURIComponent(cid)}`, {});
+    return this.http.post(`/ipfs/pin/${encodePathParam(cid)}`, {});
   }
   /**
    * Unpin content by CID
    */
   async unpin(cid) {
-    return this.http.delete(`/ipfs/unpin/${encodeURIComponent(cid)}`);
+    return this.http.delete(`/ipfs/unpin/${encodePathParam(cid)}`);
   }
   /**
    * Get a file by CID
    */
   async getFile(cid) {
-    return this.http.get(`/ipfs/file/${encodeURIComponent(cid)}`);
+    return this.http.get(`/ipfs/file/${encodePathParam(cid)}`);
   }
   /**
    * Get raw content by CID
    */
   async getContent(cid) {
-    return this.http.get(`/ipfs/${encodeURIComponent(cid)}`);
+    return this.http.get(`/ipfs/${encodePathParam(cid)}`);
   }
   /**
    * Get file metadata by CID
    */
   async getMetadata(cid) {
-    return this.http.get(`/ipfs/metadata/${encodeURIComponent(cid)}`);
+    return this.http.get(`/ipfs/metadata/${encodePathParam(cid)}`);
   }
   /**
    * List all pinned content
@@ -2042,7 +2086,7 @@ var HederaTssClient = class {
 var HederaTransactionsClient = class {
   constructor(http, tssHttp) {
     this.http = http;
-    this.tss = new HederaTssClient(tssHttp ?? http);
+    this.tss = new HederaTssClient(tssHttp);
   }
   http;
   /**
@@ -2053,10 +2097,10 @@ var HederaTransactionsClient = class {
    *   - `client.hedera.tss.createTopic(...)` makes the cluster sign+submit in one call.
    *
    * `tssHttp` is the validator's `/api/v3`-rooted HTTP client (different from
-   * the `/api/transactions` one this class uses for prepare paths). When the
-   * legacy single-arg constructor is used (no tssHttp passed), `tss` falls
-   * back to the same `http` instance for backwards compatibility — callers
-   * outside `SmartEngineClient` rarely use the TSS surface.
+   * the `/api/transactions` one this class uses for prepare paths). Both
+   * clients are required — the previous single-arg fallback to `http` was
+   * unreachable through `SmartEngineClient` (the only call site always
+   * passes both).
    */
   tss;
   /** Prepare an HCS topic creation transaction. */
@@ -2237,7 +2281,7 @@ var SnapshotsClient = class {
    */
   async generate(tokenId, options) {
     return this.http.post(
-      `/snapshots/generate/${encodeURIComponent(tokenId)}`,
+      `/snapshots/generate/${encodePathParam(tokenId)}`,
       options || {}
     );
   }
@@ -2245,7 +2289,7 @@ var SnapshotsClient = class {
    * Get snapshot details by ID
    */
   async get(snapshotId) {
-    return this.http.get(`/snapshots/${encodeURIComponent(snapshotId)}`);
+    return this.http.get(`/snapshots/${encodePathParam(snapshotId)}`);
   }
   /**
    * List snapshots for a token
@@ -2256,7 +2300,7 @@ var SnapshotsClient = class {
     if (pagination?.limit !== void 0) params.set("limit", String(pagination.limit));
     const qs = params.toString();
     return this.http.get(
-      `/snapshots/token/${encodeURIComponent(tokenId)}${qs ? `?${qs}` : ""}`
+      `/snapshots/token/${encodePathParam(tokenId)}${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -2268,7 +2312,7 @@ var SnapshotsClient = class {
   async download(snapshotId, format) {
     const params = format ? `?format=${encodeURIComponent(format)}` : "";
     return this.http.get(
-      `/snapshots/${encodeURIComponent(snapshotId)}/download${params}`
+      `/snapshots/${encodePathParam(snapshotId)}/download${params}`
     );
   }
 };
@@ -2451,20 +2495,20 @@ var SettlementClient = class {
    * Get the current status of a settlement by ID.
    */
   async getStatus(settlementId) {
-    return this.http.get(`/settlement/${encodeURIComponent(settlementId)}/status`);
+    return this.http.get(`/settlement/${encodePathParam(settlementId)}/status`);
   }
   /**
    * Confirm that XRP has landed on the destination address.
    * Advances the settlement to the next processing step.
    */
   async confirmXrpLanded(settlementId) {
-    return this.http.post(`/settlement/${encodeURIComponent(settlementId)}/confirm-xrp`, {});
+    return this.http.post(`/settlement/${encodePathParam(settlementId)}/confirm-xrp`, {});
   }
   /**
    * Get settlement history for a given entity.
    */
   async getHistory(entityId) {
-    return this.http.get(`/settlement/history/${encodeURIComponent(entityId)}`);
+    return this.http.get(`/settlement/history/${encodePathParam(entityId)}`);
   }
 };
 
@@ -2507,39 +2551,39 @@ var DaoDashboardClient = class {
   /** Aggregated dashboard counters for a user's governance home screen. */
   async getStats(userAddress) {
     return this.http.get(
-      `/dao/dashboard/stats/${encodeURIComponent(userAddress)}`
+      `/dao/dashboard/stats/${encodePathParam(userAddress)}`
     );
   }
   /** Active proposals across every DAO the user belongs to, with vote state. */
   async getActiveProposals(userAddress) {
     return this.http.get(
-      `/dao/dashboard/active-proposals/${encodeURIComponent(userAddress)}`
+      `/dao/dashboard/active-proposals/${encodePathParam(userAddress)}`
     );
   }
   /** Paginated vote history across DAOs. */
   async getVoteHistory(userAddress, opts = {}) {
     const qs = buildQuery({ limit: opts.limit, offset: opts.offset });
     return this.http.get(
-      `/dao/dashboard/vote-history/${encodeURIComponent(userAddress)}${qs}`
+      `/dao/dashboard/vote-history/${encodePathParam(userAddress)}${qs}`
     );
   }
   /** Activity feed (proposal-created/vote-cast/etc.) across user's DAOs. */
   async getActivity(userAddress, opts = {}) {
     const qs = buildQuery({ limit: opts.limit, daoId: opts.daoId });
     return this.http.get(
-      `/dao/dashboard/activity/${encodeURIComponent(userAddress)}${qs}`
+      `/dao/dashboard/activity/${encodePathParam(userAddress)}${qs}`
     );
   }
   /** Items the user must act on (sign prepared messages, claim NFTs, …). */
   async getPendingActions(userAddress) {
     return this.http.get(
-      `/dao/dashboard/pending-actions/${encodeURIComponent(userAddress)}`
+      `/dao/dashboard/pending-actions/${encodePathParam(userAddress)}`
     );
   }
   /** Governance impact metrics — weight delivered, success rate, streak. */
   async getImpact(userAddress) {
     return this.http.get(
-      `/dao/dashboard/impact/${encodeURIComponent(userAddress)}`
+      `/dao/dashboard/impact/${encodePathParam(userAddress)}`
     );
   }
 };
@@ -2555,13 +2599,13 @@ function buildQuery2(params) {
   return qs ? `?${qs}` : "";
 }
 function encodeDaoId(daoId) {
-  return encodeURIComponent(daoId);
+  return encodePathParam(daoId);
 }
 function encodeProposalId(proposalId) {
-  return encodeURIComponent(proposalId);
+  return encodePathParam(proposalId);
 }
 function encodeAddress(address) {
-  return encodeURIComponent(address);
+  return encodePathParam(address);
 }
 var DaoClient = class {
   constructor(http) {
@@ -2767,7 +2811,7 @@ var AgentsClient = class {
   }
   /** Get agent details */
   async get(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}`);
+    return this.http.get(`/api/agents/${encodePathParam(agentId)}`);
   }
   /** List all agents */
   async list() {
@@ -2779,33 +2823,33 @@ var AgentsClient = class {
    * the caller is expected to sign and submit the prepared bytes.
    */
   async fund(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/fund`, request);
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/fund`, request);
   }
   /**
    * Execute a trade (agent-wallet OR owner). Returns a
    * `PreparedTransactionResponse` wrapped in a `success: true` envelope.
    */
   async trade(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/trade`, request);
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/trade`, request);
   }
   /**
    * Withdraw from agent treasury (owner-only). Returns a
    * `PreparedTransactionResponse` wrapped in a `success: true` envelope.
    */
   async withdraw(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/withdraw`, request);
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/withdraw`, request);
   }
   /** Pause an agent */
   async pause(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/pause`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/pause`, {});
   }
   /** Resume a paused agent */
   async resume(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/resume`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/resume`, {});
   }
   /** Revoke an agent (permanent) */
   async revoke(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/revoke`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/revoke`, {});
   }
   /**
    * Update agent rules.
@@ -2816,23 +2860,23 @@ var AgentsClient = class {
    * the verb mismatch.
    */
   async updateRules(agentId, rules) {
-    return this.http.patch(`/api/agents/${encodeURIComponent(agentId)}/rules`, rules);
+    return this.http.patch(`/api/agents/${encodePathParam(agentId)}/rules`, rules);
   }
   /** Get agent events */
   async getEvents(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}/events`);
+    return this.http.get(`/api/agents/${encodePathParam(agentId)}/events`);
   }
   /** Get agent balances across chains */
   async getBalances(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}/balances`);
+    return this.http.get(`/api/agents/${encodePathParam(agentId)}/balances`);
   }
   /** Approve a pending agent operation */
   async approve(agentId, operationId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/approve/${encodeURIComponent(operationId)}`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/approve/${encodePathParam(operationId)}`, {});
   }
   /** Reject a pending agent operation */
   async reject(agentId, operationId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/reject/${encodeURIComponent(operationId)}`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/reject/${encodePathParam(operationId)}`, {});
   }
 };
 
@@ -2871,7 +2915,7 @@ var DeploymentClient = class {
    */
   async uploadFrontend(appId, bundle, filename = "bundle.tar.gz") {
     return this.http.upload(
-      `/api/deployment/apps/${encodeURIComponent(appId)}/frontend`,
+      `/api/deployment/apps/${encodePathParam(appId)}/frontend`,
       bundle,
       filename,
       void 0,
@@ -2885,20 +2929,20 @@ var DeploymentClient = class {
    * until `runtime.runtimeState === 'RUNNING'` for the URL to be live.
    */
   async deploy(appId, request) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/deploy`, request);
+    return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/deploy`, request);
   }
   /**
    * Roll back to a previously-deployed image tag (must exist in
    * `runtime.deploymentHistory[]`).
    */
   async rollback(appId, request) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/rollback`, request);
+    return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/rollback`, request);
   }
   /**
    * Live combined lifecycle + runtime status of an app.
    */
   async status(appId) {
-    return this.http.get(`/api/deployment/apps/${encodeURIComponent(appId)}/status`);
+    return this.http.get(`/api/deployment/apps/${encodePathParam(appId)}/status`);
   }
   /**
    * List all deployed apps for the authenticated developer.
@@ -2910,31 +2954,31 @@ var DeploymentClient = class {
    * Get app details.
    */
   async get(appId) {
-    return this.http.get(`/api/deployment/apps/${encodeURIComponent(appId)}`);
+    return this.http.get(`/api/deployment/apps/${encodePathParam(appId)}`);
   }
   /**
    * Update app configuration. Runtime effect lands in PR-H.
    */
   async update(appId, updates) {
-    return this.http.put(`/api/deployment/apps/${encodeURIComponent(appId)}`, updates);
+    return this.http.put(`/api/deployment/apps/${encodePathParam(appId)}`, updates);
   }
   /**
    * Delete an app. Runtime effect (namespace teardown) lands in PR-H.
    */
   async delete(appId) {
-    return this.http.delete(`/api/deployment/apps/${encodeURIComponent(appId)}`);
+    return this.http.delete(`/api/deployment/apps/${encodePathParam(appId)}`);
   }
   /**
    * Suspend an app. Runtime effect (scale to zero) lands in PR-H.
    */
   async suspend(appId) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/suspend`, {});
+    return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/suspend`, {});
   }
   /**
    * Resume a suspended app. Runtime effect (scale back up) lands in PR-H.
    */
   async resume(appId) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/resume`, {});
+    return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/resume`, {});
   }
   /**
    * Get deployment statistics.
@@ -2961,7 +3005,7 @@ var DeploymentClient = class {
    * CGNAT / cloud metadata destinations (SSRF guard).
    */
   async setWebhook(appId, webhookUrl) {
-    return this.http.put(`/api/deployment/apps/${encodeURIComponent(appId)}/webhook`, {
+    return this.http.put(`/api/deployment/apps/${encodePathParam(appId)}/webhook`, {
       webhookUrl
     });
   }
@@ -2977,7 +3021,7 @@ var DeploymentClient = class {
    * exposition format.
    */
   async getMetrics(appId) {
-    return this.http.getText(`/api/deployment/apps/${encodeURIComponent(appId)}/metrics`);
+    return this.http.getText(`/api/deployment/apps/${encodePathParam(appId)}/metrics`);
   }
   /**
    * Rotate the smart-app's tenant-secret KEK (ADR-011 Phase 6).
@@ -2988,7 +3032,7 @@ var DeploymentClient = class {
    */
   async rotateKek(appId) {
     return this.http.post(
-      `/api/deployment/apps/${encodeURIComponent(appId)}/credentials/rotate-kek`,
+      `/api/deployment/apps/${encodePathParam(appId)}/credentials/rotate-kek`,
       {}
     );
   }
@@ -3002,7 +3046,7 @@ var DeploymentClient = class {
    */
   async revokeKek(appId, version) {
     return this.http.post(
-      `/api/deployment/apps/${encodeURIComponent(appId)}/credentials/revoke-kek`,
+      `/api/deployment/apps/${encodePathParam(appId)}/credentials/revoke-kek`,
       { version }
     );
   }
@@ -3182,16 +3226,6 @@ var TokensClient = class {
   async getMigrationsForToken(tokenId) {
     return this.http.get(`/tokens/${encodePathParam(tokenId)}/migrations`);
   }
-  /**
-   * Get token details. NOTE: collides with `client.getTokenInfo(...)` —
-   * see the class JSDoc above for the route-order details. Prefer
-   * `client.getTokenInfo(...)` unless you have a reason to call this one.
-   */
-  async getDetails(chain, tokenId) {
-    return this.http.get(
-      `/tokens/${encodePathParam(chain)}/${encodePathParam(tokenId)}`
-    );
-  }
 };
 
 // src/operator/operator-client.ts
@@ -3418,30 +3452,25 @@ var SmartEngineClient = class _SmartEngineClient {
    */
   static async connectToCluster(config) {
     const allowInsecure = config.allowInsecure ?? false;
-    const bootstrap = config.bootstrap ? [...config.bootstrap] : [...resolveNetwork(config.network).bootstrap];
-    if (bootstrap.length === 0) {
-      throw new SmartEngineError(
-        "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
-        400
-      );
-    }
-    const discovery = new ClusterDiscoveryClient({
-      bootstrap,
+    const resolved = await resolveClusterEndpoint({
+      bootstrap: config.bootstrap,
+      network: config.network,
       allowInsecure,
-      trustAnchor: config.trustAnchor ? {
-        network: config.trustAnchor.network,
-        registryTopicId: config.trustAnchor.registryTopicId,
-        mirrorNodeUrl: config.trustAnchor.mirrorNodeUrl,
-        allowInsecure
-      } : void 0
+      trustAnchor: config.trustAnchor
     });
-    const cluster = await discovery.getRandomCluster();
-    if (!cluster) {
+    if (!resolved.ok) {
+      if (resolved.reason === "no-seeds") {
+        throw new SmartEngineError(
+          "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
+          400
+        );
+      }
       throw new SmartEngineError(
         "No active clusters available via bootstrap seeds. Check bootstrap URLs and network reachability.",
         503
       );
     }
+    const cluster = resolved.cluster;
     const gatewayUrl = cluster.endpoints.gatewayUrl;
     validateClientUrl(gatewayUrl, allowInsecure);
     const auth = new ValidatorAuthClient({ security: { allowInsecure } });
@@ -3466,7 +3495,7 @@ var SmartEngineClient = class _SmartEngineClient {
   }
   /** Check if client has an auth token */
   isAuthenticated() {
-    return !!this.http.authToken;
+    return this.http.getAuthToken() !== void 0;
   }
   /**
    * Get HTTP resilience health information
@@ -3697,7 +3726,7 @@ var RoutingClient = class {
   }
   /** Unregister a host. */
   async unregisterHost(hostId) {
-    return this.http.delete(`/routing/hosts/${encodeURIComponent(hostId)}`);
+    return this.http.delete(`/routing/hosts/${encodePathParam(hostId)}`);
   }
   /** Get all registered hosts. */
   async getAllHosts() {
@@ -3709,19 +3738,19 @@ var RoutingClient = class {
   }
   /** Get a specific host by ID. */
   async getHost(hostId) {
-    return this.http.get(`/routing/hosts/${encodeURIComponent(hostId)}`);
+    return this.http.get(`/routing/hosts/${encodePathParam(hostId)}`);
   }
   /** Trigger host re-verification. */
   async verifyHost(hostId) {
-    return this.http.post(`/routing/hosts/${encodeURIComponent(hostId)}/verify`, {});
+    return this.http.post(`/routing/hosts/${encodePathParam(hostId)}/verify`, {});
   }
   /** Set routing configuration for an app. */
   async setRoutingConfig(appId, config) {
-    return this.http.put(`/routing/config/${encodeURIComponent(appId)}`, config);
+    return this.http.put(`/routing/config/${encodePathParam(appId)}`, config);
   }
   /** Get routing configuration for an app. */
   async getRoutingConfig(appId) {
-    return this.http.get(`/routing/config/${encodeURIComponent(appId)}`);
+    return this.http.get(`/routing/config/${encodePathParam(appId)}`);
   }
   /** Proxy a request through the gateway. */
   async proxyRequest(request) {
@@ -3737,7 +3766,7 @@ var RoutingClient = class {
    * field; treat `appId` as the success signal.
    */
   async mapDomainToApp(domain, appId) {
-    return this.http.post(`/routing/domains/${encodeURIComponent(domain)}/map`, { appId });
+    return this.http.post(`/routing/domains/${encodePathParam(domain)}/map`, { appId });
   }
 };
 
@@ -3753,11 +3782,11 @@ var DomainsClient = class {
   }
   /** Check domain availability */
   async checkAvailability(domain) {
-    return this.http.get(`/domains/check/${encodeURIComponent(domain)}`);
+    return this.http.get(`/domains/check/${encodePathParam(domain)}`);
   }
   /** Get domain information */
   async getInfo(domain) {
-    return this.http.get(`/domains/${encodeURIComponent(domain)}`);
+    return this.http.get(`/domains/${encodePathParam(domain)}`);
   }
   /** List domains, optionally filtered by owner */
   async list(owner) {
@@ -3770,47 +3799,47 @@ var DomainsClient = class {
    * `apps/smart-gateway/src/domains/domains.controller.ts:226-234`).
    */
   async generateVerificationToken(domain, method) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/verification`, { method });
+    return this.http.post(`/domains/${encodePathParam(domain)}/verification`, { method });
   }
   /** Verify domain ownership */
   async verifyOwnership(domain, token) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/verify`, { token });
+    return this.http.post(`/domains/${encodePathParam(domain)}/verify`, { token });
   }
   /** Configure DNS records for a domain */
   async configureDns(domain, records) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/dns`, { records });
+    return this.http.post(`/domains/${encodePathParam(domain)}/dns`, { records });
   }
   /** Enable DNSSEC for a domain */
   async enableDnssec(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/dnssec/enable`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/dnssec/enable`, {});
   }
   /** Disable DNSSEC for a domain */
   async disableDnssec(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/dnssec/disable`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/dnssec/disable`, {});
   }
   /** Renew a domain */
   async renew(domain, years) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/renew`, { years: years ?? 1 });
+    return this.http.post(`/domains/${encodePathParam(domain)}/renew`, { years: years ?? 1 });
   }
   /** Initiate a domain transfer */
   async transfer(domain, request) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/transfer`, request);
+    return this.http.post(`/domains/${encodePathParam(domain)}/transfer`, request);
   }
   /** Approve a pending domain transfer */
   async approveTransfer(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/transfer/approve`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/transfer/approve`, {});
   }
   /** Reject a pending domain transfer */
   async rejectTransfer(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/transfer/reject`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/transfer/reject`, {});
   }
   /** Suspend a domain */
   async suspend(domain, reason) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/suspend`, { reason });
+    return this.http.post(`/domains/${encodePathParam(domain)}/suspend`, { reason });
   }
   /** Unsuspend a domain */
   async unsuspend(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/unsuspend`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/unsuspend`, {});
   }
 };
 
@@ -3837,7 +3866,7 @@ var DnsClient = class {
   }
   /** Get a specific zone */
   async getZone(zoneName) {
-    return this.http.get(`/dns/zones/${encodeURIComponent(zoneName)}`);
+    return this.http.get(`/dns/zones/${encodePathParam(zoneName)}`);
   }
   /** Create a new DNS zone */
   async createZone(request) {
@@ -3845,38 +3874,38 @@ var DnsClient = class {
   }
   /** Delete a DNS zone */
   async deleteZone(zoneName) {
-    return this.http.delete(`/dns/zones/${encodeURIComponent(zoneName)}`);
+    return this.http.delete(`/dns/zones/${encodePathParam(zoneName)}`);
   }
   /** Add a record to a zone */
   async addRecord(zoneName, record) {
-    return this.http.post(`/dns/zones/${encodeURIComponent(zoneName)}/records`, record);
+    return this.http.post(`/dns/zones/${encodePathParam(zoneName)}/records`, record);
   }
   /** Update a record in a zone */
   async updateRecord(zoneName, recordId, updates) {
     return this.http.put(
-      `/dns/zones/${encodeURIComponent(zoneName)}/records/${encodeURIComponent(recordId)}`,
+      `/dns/zones/${encodePathParam(zoneName)}/records/${encodePathParam(recordId)}`,
       updates
     );
   }
   /** Delete a record from a zone */
   async deleteRecord(zoneName, recordId) {
     return this.http.delete(
-      `/dns/zones/${encodeURIComponent(zoneName)}/records/${encodeURIComponent(recordId)}`
+      `/dns/zones/${encodePathParam(zoneName)}/records/${encodePathParam(recordId)}`
     );
   }
   /** Generate DNSSEC keys for a zone */
   async generateDnssecKeys(zoneName, algorithm) {
-    return this.http.post(`/dns/zones/${encodeURIComponent(zoneName)}/dnssec/keys`, {
+    return this.http.post(`/dns/zones/${encodePathParam(zoneName)}/dnssec/keys`, {
       algorithm
     });
   }
   /** Get DNSSEC keys for a zone */
   async getDnssecKeys(zoneName) {
-    return this.http.get(`/dns/zones/${encodeURIComponent(zoneName)}/dnssec/keys`);
+    return this.http.get(`/dns/zones/${encodePathParam(zoneName)}/dnssec/keys`);
   }
   /** Get DS record for a zone (for registrar configuration) */
   async getDsRecord(zoneName) {
-    return this.http.get(`/dns/zones/${encodeURIComponent(zoneName)}/dnssec/ds`);
+    return this.http.get(`/dns/zones/${encodePathParam(zoneName)}/dnssec/ds`);
   }
   /** Clear DNS cache */
   async clearCache() {
@@ -3977,7 +4006,7 @@ var DatabaseClient = class {
   async insert(collection, document) {
     const appId = this.getAppId();
     return this.http.post(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(collection)}`,
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(collection)}`,
       document
     );
   }
@@ -3995,7 +4024,7 @@ var DatabaseClient = class {
     if (options?.sort) params.set("sort", options.sort);
     const qs = params.toString();
     return this.http.get(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(collection)}${qs ? `?${qs}` : ""}`
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(collection)}${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -4004,7 +4033,7 @@ var DatabaseClient = class {
   async update(collection, documentId, updates) {
     const appId = this.getAppId();
     return this.http.put(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(collection)}/${encodeURIComponent(documentId)}`,
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(collection)}/${encodePathParam(documentId)}`,
       updates
     );
   }
@@ -4014,7 +4043,7 @@ var DatabaseClient = class {
   async delete(collection, documentId) {
     const appId = this.getAppId();
     return this.http.delete(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(collection)}/${encodeURIComponent(documentId)}`
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(collection)}/${encodePathParam(documentId)}`
     );
   }
   /**
@@ -4026,7 +4055,7 @@ var DatabaseClient = class {
    */
   async listCollections() {
     const appId = this.getAppId();
-    return this.http.get(`/api/db/${encodeURIComponent(appId)}/collections`);
+    return this.http.get(`/api/db/${encodePathParam(appId)}/collections`);
   }
   /**
    * Create a new collection in the database.
@@ -4036,7 +4065,7 @@ var DatabaseClient = class {
    */
   async createCollection(name) {
     const appId = this.getAppId();
-    return this.http.post(`/api/db/${encodeURIComponent(appId)}/collections`, { name });
+    return this.http.post(`/api/db/${encodePathParam(appId)}/collections`, { name });
   }
   /**
    * Drop a collection and all its documents.
@@ -4047,7 +4076,7 @@ var DatabaseClient = class {
   async dropCollection(name) {
     const appId = this.getAppId();
     return this.http.delete(
-      `/api/db/${encodeURIComponent(appId)}/collections/${encodeURIComponent(name)}`
+      `/api/db/${encodePathParam(appId)}/collections/${encodePathParam(name)}`
     );
   }
   // ========== State Proofs ==========
@@ -4056,7 +4085,7 @@ var DatabaseClient = class {
    */
   async getStateRoot() {
     const appId = this.getAppId();
-    return this.http.get(`/api/db/${encodeURIComponent(appId)}/state/root`);
+    return this.http.get(`/api/db/${encodePathParam(appId)}/state/root`);
   }
   /**
    * Get a Merkle proof for a specific document
@@ -4064,7 +4093,7 @@ var DatabaseClient = class {
   async getDocumentProof(documentId) {
     const appId = this.getAppId();
     return this.http.get(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(documentId)}/proof`
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(documentId)}/proof`
     );
   }
   /**
@@ -4078,7 +4107,7 @@ var DatabaseClient = class {
     if (options?.limit !== void 0) params.set("limit", String(options.limit));
     const qs = params.toString();
     return this.http.get(
-      `/api/db/${encodeURIComponent(appId)}/state/transitions${qs ? `?${qs}` : ""}`
+      `/api/db/${encodePathParam(appId)}/state/transitions${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -4086,7 +4115,7 @@ var DatabaseClient = class {
    */
   async getDbStats() {
     const appId = this.getAppId();
-    return this.http.get(`/api/db/${encodeURIComponent(appId)}/stats`);
+    return this.http.get(`/api/db/${encodePathParam(appId)}/stats`);
   }
 };
 
@@ -4103,28 +4132,28 @@ var StorageClient = class {
    */
   async upload(file, filename, metadata) {
     const appId = this.getAppId();
-    return this.http.upload(`/api/storage/${encodeURIComponent(appId)}/upload`, file, filename, metadata);
+    return this.http.upload(`/api/storage/${encodePathParam(appId)}/upload`, file, filename, metadata);
   }
   /**
    * Download a file by CID
    */
   async download(cid) {
     const appId = this.getAppId();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/download/${encodeURIComponent(cid)}`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/download/${encodePathParam(cid)}`);
   }
   /**
    * Get file metadata
    */
   async getMetadata(cid) {
     const appId = this.getAppId();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/metadata/${encodeURIComponent(cid)}`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/metadata/${encodePathParam(cid)}`);
   }
   /**
    * Delete a file
    */
   async delete(cid) {
     const appId = this.getAppId();
-    return this.http.delete(`/api/storage/${encodeURIComponent(appId)}/${encodeURIComponent(cid)}`);
+    return this.http.delete(`/api/storage/${encodePathParam(appId)}/${encodePathParam(cid)}`);
   }
   /**
    * Get file info.
@@ -4133,7 +4162,7 @@ var StorageClient = class {
    * bare-CID metadata route — every metadata lookup must go through
    * `getMetadata(cid)` (`/api/storage/:appId/metadata/:cid`) or the
    * stream body via `download(cid)`. This alias forwards to `download`
-   * for back-compat; remove in the next major SDK release.
+   * for back-compat; **scheduled for removal in 4.0.0**.
    */
   async getFile(cid) {
     return this.download(cid);
@@ -4151,21 +4180,21 @@ var StorageClient = class {
     if (pagination?.limit !== void 0) params.set("limit", String(pagination.limit));
     if (pagination?.offset !== void 0) params.set("offset", String(pagination.offset));
     const qs = params.toString();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/files${qs ? `?${qs}` : ""}`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/files${qs ? `?${qs}` : ""}`);
   }
   /**
    * Get storage usage for the current app
    */
   async getUsage() {
     const appId = this.getAppId();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/usage`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/usage`);
   }
   /**
    * Check if a file exists
    */
   async exists(cid) {
     const appId = this.getAppId();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/exists/${encodeURIComponent(cid)}`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/exists/${encodePathParam(cid)}`);
   }
 };
 
@@ -4182,7 +4211,7 @@ var FunctionsClient = class {
    */
   async deploy(request) {
     const appId = this.getAppId();
-    return this.http.post(`/api/functions/${encodeURIComponent(appId)}`, request);
+    return this.http.post(`/api/functions/${encodePathParam(appId)}`, request);
   }
   /**
    * Invoke a function
@@ -4190,7 +4219,7 @@ var FunctionsClient = class {
   async invoke(functionId, payload) {
     const appId = this.getAppId();
     return this.http.post(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}/invoke`,
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}/invoke`,
       payload ?? {}
     );
   }
@@ -4199,7 +4228,7 @@ var FunctionsClient = class {
    */
   async list() {
     const appId = this.getAppId();
-    return this.http.get(`/api/functions/${encodeURIComponent(appId)}`);
+    return this.http.get(`/api/functions/${encodePathParam(appId)}`);
   }
   /**
    * Get function details
@@ -4207,7 +4236,7 @@ var FunctionsClient = class {
   async get(functionId) {
     const appId = this.getAppId();
     return this.http.get(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}`
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}`
     );
   }
   /**
@@ -4216,7 +4245,7 @@ var FunctionsClient = class {
   async update(functionId, updates) {
     const appId = this.getAppId();
     return this.http.put(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}`,
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}`,
       updates
     );
   }
@@ -4226,7 +4255,7 @@ var FunctionsClient = class {
   async delete(functionId) {
     const appId = this.getAppId();
     return this.http.delete(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}`
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}`
     );
   }
   /**
@@ -4240,7 +4269,7 @@ var FunctionsClient = class {
     if (options?.level) params.set("level", options.level);
     const qs = params.toString();
     return this.http.get(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}/logs${qs ? `?${qs}` : ""}`
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}/logs${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -4248,7 +4277,7 @@ var FunctionsClient = class {
    */
   async getStats() {
     const appId = this.getAppId();
-    return this.http.get(`/api/functions/${encodeURIComponent(appId)}/stats`);
+    return this.http.get(`/api/functions/${encodePathParam(appId)}/stats`);
   }
 };
 
@@ -4265,28 +4294,28 @@ var MessagingClient = class {
    */
   async createChannel(config) {
     const appId = this.getAppId();
-    return this.http.post(`/api/messaging/${encodeURIComponent(appId)}/channels`, config);
+    return this.http.post(`/api/messaging/${encodePathParam(appId)}/channels`, config);
   }
   /**
    * Delete a channel
    */
   async deleteChannel(channelId) {
     const appId = this.getAppId();
-    return this.http.delete(`/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channelId)}`);
+    return this.http.delete(`/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channelId)}`);
   }
   /**
    * Get a channel by ID
    */
   async getChannel(channelId) {
     const appId = this.getAppId();
-    return this.http.get(`/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channelId)}`);
+    return this.http.get(`/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channelId)}`);
   }
   /**
    * List all channels for the app
    */
   async listChannels() {
     const appId = this.getAppId();
-    return this.http.get(`/api/messaging/${encodeURIComponent(appId)}/channels`);
+    return this.http.get(`/api/messaging/${encodePathParam(appId)}/channels`);
   }
   /**
    * Publish a message to a channel
@@ -4294,7 +4323,7 @@ var MessagingClient = class {
   async publish(channel, message, metadata) {
     const appId = this.getAppId();
     return this.http.post(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/publish`,
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/publish`,
       { data: message, metadata }
     );
   }
@@ -4309,7 +4338,7 @@ var MessagingClient = class {
     if (options?.after) params.set("after", options.after);
     const qs = params.toString();
     return this.http.get(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/history${qs ? `?${qs}` : ""}`
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/history${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -4323,7 +4352,7 @@ var MessagingClient = class {
   async setPresence(channel, member) {
     const appId = this.getAppId();
     return this.http.post(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/presence`,
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/presence`,
       member
     );
   }
@@ -4339,7 +4368,7 @@ var MessagingClient = class {
   async removePresence(channel, clientId) {
     const appId = this.getAppId();
     return this.http.delete(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/presence/${encodeURIComponent(clientId)}`
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/presence/${encodePathParam(clientId)}`
     );
   }
   /**
@@ -4348,7 +4377,7 @@ var MessagingClient = class {
   async getPresence(channel) {
     const appId = this.getAppId();
     return this.http.get(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/presence`
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/presence`
     );
   }
   /**
@@ -4356,7 +4385,7 @@ var MessagingClient = class {
    */
   async getStats() {
     const appId = this.getAppId();
-    return this.http.get(`/api/messaging/${encodeURIComponent(appId)}/stats`);
+    return this.http.get(`/api/messaging/${encodePathParam(appId)}/stats`);
   }
 };
 
@@ -4444,7 +4473,7 @@ var RulesClient = class {
   }
   /** Fetch a published rule by its HCS consensus timestamp. */
   async get(consensusTimestamp) {
-    return this.http.get(`/api/rules/${encodeURIComponent(consensusTimestamp)}`);
+    return this.http.get(`/api/rules/${encodePathParam(consensusTimestamp)}`);
   }
   /** List rules owned by the authenticated entity, optionally filtered by type. */
   async listByOwner(filter) {
@@ -4461,13 +4490,13 @@ var RulesClient = class {
   /** Walk the version history of a published rule. */
   async getVersionHistory(consensusTimestamp) {
     return this.http.get(
-      `/api/rules/${encodeURIComponent(consensusTimestamp)}/versions`
+      `/api/rules/${encodePathParam(consensusTimestamp)}/versions`
     );
   }
   /** Deprecate a published rule (owner-only). */
   async deprecate(consensusTimestamp) {
     return this.http.post(
-      `/api/rules/${encodeURIComponent(consensusTimestamp)}/deprecate`,
+      `/api/rules/${encodePathParam(consensusTimestamp)}/deprecate`,
       {}
     );
   }
@@ -4505,7 +4534,7 @@ var EntitiesClient = class {
   }
   /** Fetch an entity by its canonical `entityId`. */
   async get(entityId) {
-    return this.http.get(`/api/entities/${encodeURIComponent(entityId)}`);
+    return this.http.get(`/api/entities/${encodePathParam(entityId)}`);
   }
   /** List entities owned by the authenticated wallet, optionally filtered by type. */
   async listByOwner(filter) {
@@ -4521,7 +4550,6 @@ var BaasClient = class _BaasClient {
   appId;
   timeout;
   allowInsecure;
-  authToken = null;
   http;
   /** Last HTTP error (for getHttpHealth) */
   lastHttpError;
@@ -4608,30 +4636,25 @@ var BaasClient = class _BaasClient {
    */
   static async connectToCluster(config) {
     const allowInsecure = config.allowInsecure ?? false;
-    const bootstrap = config.bootstrap ? [...config.bootstrap] : [...resolveNetwork(config.network).bootstrap];
-    if (bootstrap.length === 0) {
-      throw new BaasError(
-        "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
-        400
-      );
-    }
-    const discovery = new ClusterDiscoveryClient({
-      bootstrap,
+    const resolved = await resolveClusterEndpoint({
+      bootstrap: config.bootstrap,
+      network: config.network,
       allowInsecure,
-      trustAnchor: config.trustAnchor ? {
-        network: config.trustAnchor.network,
-        registryTopicId: config.trustAnchor.registryTopicId,
-        mirrorNodeUrl: config.trustAnchor.mirrorNodeUrl,
-        allowInsecure
-      } : void 0
+      trustAnchor: config.trustAnchor
     });
-    const cluster = await discovery.getRandomCluster();
-    if (!cluster) {
+    if (!resolved.ok) {
+      if (resolved.reason === "no-seeds") {
+        throw new BaasError(
+          "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
+          400
+        );
+      }
       throw new BaasError(
         "No active clusters available via bootstrap seeds. Check network reachability or bootstrap URLs.",
         503
       );
     }
+    const cluster = resolved.cluster;
     return new _BaasClient({
       hostUrl: cluster.endpoints.gatewayUrl,
       appId: config.appId,
@@ -4649,7 +4672,7 @@ var BaasClient = class _BaasClient {
   }
   /** Check if the client is authenticated */
   isAuthenticated() {
-    return this.authToken !== null;
+    return this.http.getAuthToken() !== void 0;
   }
   /** Get the current app ID */
   getAppId() {
@@ -4695,93 +4718,55 @@ var BaasClient = class _BaasClient {
    */
   async authenticate(options) {
     const { chain, walletAddress, publicKey, signFn } = options;
-    const challenge = await this.post("/api/auth/challenge", {
-      chain,
-      walletAddress,
-      appId: this.appId
-    });
+    let challenge;
+    try {
+      challenge = await this.http.post("/api/auth/challenge", {
+        chain,
+        walletAddress,
+        appId: this.appId
+      });
+    } catch (err) {
+      throw asBaasError(err);
+    }
     const signature = await signFn(challenge.message);
-    const result = await this.post("/api/auth/verify", {
-      challengeId: challenge.challengeId,
-      signature,
-      publicKey
-    });
-    this.authToken = result.token;
-    this.http.setAuthToken?.(result.token);
+    let result;
+    try {
+      result = await this.http.post("/api/auth/verify", {
+        challengeId: challenge.challengeId,
+        signature,
+        publicKey
+      });
+    } catch (err) {
+      throw asBaasError(err);
+    }
+    this.http.setAuthToken(result.token);
     return result;
   }
   /** Validate the current session */
   async validateSession() {
     this.requireAuth();
-    return this.get("/api/auth/session");
+    try {
+      return await this.http.get("/api/auth/session");
+    } catch (err) {
+      throw asBaasError(err);
+    }
   }
   /** Destroy the current session on server and clear local token */
   async logout() {
-    if (this.authToken) {
+    if (this.http.getAuthToken()) {
       try {
-        await this.post("/api/auth/logout", {});
+        await this.http.post("/api/auth/logout", {});
       } catch {
       }
     }
-    this.authToken = null;
+    this.http.setAuthToken(void 0);
   }
   // ========== HTTP Helpers ==========
   requireAuth() {
-    if (!this.authToken) {
+    if (!this.http.getAuthToken()) {
       throw new BaasError("Authentication required. Call authenticate() first.", 401);
     }
   }
-  getHeaders() {
-    const headers = {
-      "Content-Type": "application/json"
-    };
-    if (this.authToken) {
-      headers["Authorization"] = `Bearer ${this.authToken}`;
-    }
-    return headers;
-  }
-  async post(path, body) {
-    return this.request("POST", path, body);
-  }
-  async get(path) {
-    return this.request("GET", path);
-  }
-  async request(method, path, body) {
-    const url = `${this.hostUrl}${this.pathPrefix}${path}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const options = {
-        method,
-        headers: this.getHeaders(),
-        signal: controller.signal
-      };
-      if (body !== void 0) {
-        options.body = JSON.stringify(body);
-      }
-      const response = await fetch(url, options);
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        throw new BaasError(
-          errorData.message || `API error: ${response.status} ${response.statusText}`,
-          response.status,
-          errorData
-        );
-      }
-      const text = await response.text();
-      if (!text) return void 0;
-      return JSON.parse(text);
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof BaasError) throw error;
-      const err = error;
-      if (err.name === "AbortError") {
-        throw new BaasError("Request timeout", 408);
-      }
-      throw new BaasError(`Network error: ${err.message}`, 0, { originalError: err.message });
-    }
-  }
 };
 var BaasError = class extends Error {
   constructor(message, statusCode, details) {
@@ -4793,6 +4778,17 @@ var BaasError = class extends Error {
   statusCode;
   details;
 };
+function asBaasError(err) {
+  if (err instanceof BaasError) return err;
+  if (err instanceof SdkHttpError) {
+    const details = err.details ?? void 0;
+    return new BaasError(err.message, err.statusCode, details);
+  }
+  const e = err;
+  return new BaasError(`Network error: ${e?.message ?? String(err)}`, 0, {
+    originalError: e?.message ?? String(err)
+  });
+}
 function validateUrl2(url, allowInsecure = false) {
   try {
     const parsed = new URL(url);