@hsuite/smart-engines-sdk 3.4.0 → 3.5.0

package/dist/index.js

@@ -123,12 +123,12 @@ var require_lib = __commonJS({
       if (lengths.length > 0 && !lengths.includes(b.length))
         throw new Error("Uint8Array expected of length " + lengths + ", got length=" + b.length);
     }
-    function isArrayOf(isString, arr) {
+    function isArrayOf(isString2, arr) {
       if (!Array.isArray(arr))
         return false;
       if (arr.length === 0)
         return true;
-      if (isString) {
+      if (isString2) {
         return arr.every((item) => typeof item === "string");
       } else {
         return arr.every((item) => Number.isSafeInteger(item));
@@ -6008,7 +6008,8 @@ __export(discovery_exports, {
   MirrorNodeClient: () => MirrorNodeClient,
   MirrorNodeError: () => MirrorNodeError,
   PlatformImagesClient: () => PlatformImagesClient,
-  ValidatorDiscoveryClient: () => ValidatorDiscoveryClient
+  ValidatorDiscoveryClient: () => ValidatorDiscoveryClient,
+  resolveClusterEndpoint: () => resolveClusterEndpoint
 });
 
 // src/discovery/mirror-node.ts
@@ -6556,6 +6557,178 @@ 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, "");
+}
+function isRuleRejected(err) {
+  if (!(err instanceof SdkHttpError)) return false;
+  if (err.statusCode !== 403) return false;
+  const d = err.details;
+  if (d === null || typeof d !== "object") return false;
+  const obj = d;
+  if (obj.error !== "rule_rejected") return false;
+  if (typeof obj.reason !== "string") return false;
+  if (!Array.isArray(obj.ruleAtoms)) return false;
+  return obj.ruleAtoms.every((a) => typeof a === "string");
+}
+
 // src/discovery/discovery-client.ts
 var DiscoveryClient = class {
   constructor(http) {
@@ -6589,7 +6762,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 {
@@ -6619,7 +6792,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` —
@@ -6628,7 +6801,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)}`
     );
   }
   /**
@@ -6642,13 +6815,66 @@ 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;
+}
+function isKnownNetwork(name) {
+  return Object.prototype.hasOwnProperty.call(KNOWN_NETWORKS, name);
+}
+
+// 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/index.ts
 var auth_exports = {};
 __export(auth_exports, {
@@ -6665,6 +6891,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);
@@ -6864,275 +7094,90 @@ 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;
-    }
-    return Buffer.from(signature).toString("hex");
-  }
-  /**
-   * Complete authentication flow in one call
-   *
-   * @param validatorUrl - Validator API base URL
-   * @param chain - Blockchain type
-   * @param address - Wallet address
-   * @param publicKey - Public key (hex)
-   * @param signFn - Function to sign the challenge
-   * @param metadata - Optional metadata
-   * @returns Session token and info
-   */
-  async authenticateWithSigner(validatorUrl, chain, address, publicKey, signFn, metadata) {
-    const challengeResponse = await this.requestChallenge(validatorUrl, chain, address);
-    const signature = await signFn(challengeResponse.challenge);
-    return this.authenticate(validatorUrl, {
-      chain,
-      address,
-      publicKey,
-      signature,
-      challenge: challengeResponse.challenge,
-      metadata
-    });
-  }
-};
-var ValidatorAuthError = class extends Error {
-  constructor(message, statusCode, details) {
-    super(message);
-    this.statusCode = statusCode;
-    this.details = details;
-    this.name = "ValidatorAuthError";
-  }
-  statusCode;
-  details;
-};
-var { sign: rippleSign } = require_dist2();
-function createXrplWeb3Signer(seed) {
-  const wallet = xrpl.Wallet.fromSeed(seed);
-  return {
-    chain: "xrpl",
-    address: wallet.classicAddress,
-    publicKey: wallet.publicKey,
-    signFn: (challenge) => {
-      const messageHex = Buffer.from(challenge, "utf-8").toString("hex").toUpperCase();
-      return rippleSign(messageHex, wallet.privateKey);
-    },
-    wallet
-  };
-}
-
-// 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);
+    if (typeof signature === "string") {
+      if (/^[0-9A-Fa-f]+$/.test(signature)) return signature;
+      return Buffer.from(signature).toString("hex");
     }
+    return signature.signedTransaction;
   }
-  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, "");
-}
-function isRuleRejected(err) {
-  if (!(err instanceof SdkHttpError)) return false;
-  if (err.statusCode !== 403) return false;
-  const d = err.details;
-  if (d === null || typeof d !== "object") return false;
-  const obj = d;
-  if (obj.error !== "rule_rejected") return false;
-  if (typeof obj.reason !== "string") return false;
-  if (!Array.isArray(obj.ruleAtoms)) return false;
-  return obj.ruleAtoms.every((a) => typeof a === "string");
-}
-
-// 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"]
+  /**
+   * Complete authentication flow in one call
+   *
+   * @param validatorUrl - Validator API base URL
+   * @param chain - Blockchain type
+   * @param address - Wallet address
+   * @param publicKey - Public key (hex)
+   * @param signFn - Function to sign the challenge
+   * @param metadata - Optional metadata
+   * @returns Session token and info
+   */
+  async authenticateWithSigner(validatorUrl, chain, address, publicKey, signFn, metadata) {
+    const challengeResponse = await this.requestChallenge(validatorUrl, chain, address);
+    const signature = await signFn(challengeResponse.challenge);
+    return this.authenticate(validatorUrl, {
+      chain,
+      address,
+      publicKey,
+      signature,
+      challenge: challengeResponse.challenge,
+      metadata
+    });
   }
 };
-function resolveNetwork(name) {
-  const preset = KNOWN_NETWORKS[name];
-  if (!preset) {
-    throw new Error(
-      `Unknown network: "${name}". Known networks: ${Object.keys(KNOWN_NETWORKS).join(", ")}`
-    );
+var ValidatorAuthError = class extends Error {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "ValidatorAuthError";
   }
-  return preset;
-}
-function isKnownNetwork(name) {
-  return Object.prototype.hasOwnProperty.call(KNOWN_NETWORKS, name);
+  statusCode;
+  details;
+};
+var { sign: rippleSign } = require_dist2();
+function createXrplWeb3Signer(seed) {
+  const wallet = xrpl.Wallet.fromSeed(seed);
+  return {
+    chain: "xrpl",
+    address: wallet.classicAddress,
+    publicKey: wallet.publicKey,
+    signFn: (challenge) => {
+      const messageHex = Buffer.from(challenge, "utf-8").toString("hex").toUpperCase();
+      return rippleSign(messageHex, wallet.privateKey);
+    },
+    wallet
+  };
 }
 
 // src/subscription/index.ts
@@ -7156,13 +7201,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
@@ -7231,13 +7276,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 ────────────────────────────────────────────────
   /**
@@ -7269,19 +7314,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
@@ -7295,7 +7340,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}` : ""}`
     );
   }
   /**
@@ -7338,7 +7383,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.
@@ -7395,7 +7440,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}.
@@ -7419,7 +7464,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
@@ -7431,7 +7476,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);
   }
 };
 
@@ -7456,31 +7501,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
@@ -7538,7 +7583,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;
   /**
@@ -7549,10 +7594,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. */
@@ -7733,7 +7778,7 @@ var SnapshotsClient = class {
    */
   async generate(tokenId, options) {
     return this.http.post(
-      `/snapshots/generate/${encodeURIComponent(tokenId)}`,
+      `/snapshots/generate/${encodePathParam(tokenId)}`,
       options || {}
     );
   }
@@ -7741,7 +7786,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
@@ -7752,7 +7797,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}` : ""}`
     );
   }
   /**
@@ -7764,7 +7809,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}`
     );
   }
 };
@@ -7951,20 +7996,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)}`);
   }
 };
 
@@ -8020,39 +8065,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)}`
     );
   }
 };
@@ -8068,13 +8113,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) {
@@ -8355,7 +8400,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() {
@@ -8367,33 +8412,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.
@@ -8404,23 +8449,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)}`, {});
   }
 };
 
@@ -8459,7 +8504,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,
@@ -8473,20 +8518,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.
@@ -8498,31 +8543,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.
@@ -8549,7 +8594,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
     });
   }
@@ -8565,7 +8610,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).
@@ -8576,7 +8621,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`,
       {}
     );
   }
@@ -8590,7 +8635,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 }
     );
   }
@@ -8794,16 +8839,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/index.ts
@@ -9036,30 +9071,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 SmartEngineError2(
-        "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 SmartEngineError2(
+          "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
+          400
+        );
+      }
       throw new SmartEngineError2(
         "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 } });
@@ -9084,7 +9114,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
@@ -9315,7 +9345,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() {
@@ -9327,19 +9357,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) {
@@ -9355,7 +9385,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 });
   }
 };
 
@@ -9371,11 +9401,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) {
@@ -9388,47 +9418,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`, {});
   }
 };
 
@@ -9455,7 +9485,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) {
@@ -9463,38 +9493,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() {
@@ -10107,7 +10137,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
     );
   }
@@ -10125,7 +10155,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}` : ""}`
     );
   }
   /**
@@ -10134,7 +10164,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
     );
   }
@@ -10144,7 +10174,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)}`
     );
   }
   /**
@@ -10156,7 +10186,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.
@@ -10166,7 +10196,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.
@@ -10177,7 +10207,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 ==========
@@ -10186,7 +10216,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
@@ -10194,7 +10224,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`
     );
   }
   /**
@@ -10208,7 +10238,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}` : ""}`
     );
   }
   /**
@@ -10216,7 +10246,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`);
   }
 };
 
@@ -10233,28 +10263,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.
@@ -10263,7 +10293,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);
@@ -10281,21 +10311,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)}`);
   }
 };
 
@@ -10312,7 +10342,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
@@ -10320,7 +10350,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 ?? {}
     );
   }
@@ -10329,7 +10359,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
@@ -10337,7 +10367,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)}`
     );
   }
   /**
@@ -10346,7 +10376,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
     );
   }
@@ -10356,7 +10386,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)}`
     );
   }
   /**
@@ -10370,7 +10400,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}` : ""}`
     );
   }
   /**
@@ -10378,7 +10408,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`);
   }
 };
 
@@ -10395,28 +10425,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
@@ -10424,7 +10454,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 }
     );
   }
@@ -10439,7 +10469,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}` : ""}`
     );
   }
   /**
@@ -10453,7 +10483,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
     );
   }
@@ -10469,7 +10499,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)}`
     );
   }
   /**
@@ -10478,7 +10508,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`
     );
   }
   /**
@@ -10486,7 +10516,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`);
   }
 };
 
@@ -10574,7 +10604,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) {
@@ -10591,13 +10621,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`,
       {}
     );
   }
@@ -10635,7 +10665,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) {
@@ -10651,7 +10681,6 @@ var BaasClient = class _BaasClient {
   appId;
   timeout;
   allowInsecure;
-  authToken = null;
   http;
   /** Last HTTP error (for getHttpHealth) */
   lastHttpError;
@@ -10738,30 +10767,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,
@@ -10779,7 +10803,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() {
@@ -10825,93 +10849,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) {
@@ -10923,6 +10909,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);
@@ -11104,6 +11101,251 @@ async function verifyPqcAttestation(cert, payload, registrySnapshot) {
   };
 }
 
+// src/pqc-verify-envelope/index.ts
+var pqc_verify_envelope_exports = {};
+__export(pqc_verify_envelope_exports, {
+  KYBER_MIN_TIMESTAMP_MS: () => KYBER_MIN_TIMESTAMP_MS,
+  validateEnvelopeSchema: () => validateEnvelopeSchema,
+  verifyPqcEnvelope: () => verifyPqcEnvelope
+});
+
+// src/pqc-verify-envelope/envelope-schema-validator.ts
+var KEM_CT_LEN = {
+  "ml-kem-768": 1088,
+  "ml-kem-1024": 1568
+};
+var AES_IV_LEN = 12;
+var AES_TAG_LEN = 16;
+var KDF_SALT_LEN = 16;
+function tryDecodeBase64(s) {
+  if (typeof s !== "string" || s.length === 0) return null;
+  try {
+    const buf = Buffer.from(s, "base64");
+    if (buf.toString("base64").replace(/=+$/, "") !== s.replace(/=+$/, "")) {
+      return null;
+    }
+    return new Uint8Array(buf);
+  } catch {
+    return null;
+  }
+}
+function isString(v) {
+  return typeof v === "string";
+}
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.length > 0;
+}
+function isFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function validateEnvelopeSchema(envelope) {
+  if (!isPlainObject(envelope)) {
+    return { ok: false, reason: "envelope must be a JSON object" };
+  }
+  const version = envelope.version;
+  if (version === "kyber-aes-v1") {
+    return validateKyberAesV1(envelope);
+  }
+  if (version === "aes-v0") {
+    return validateAesV0(envelope);
+  }
+  return {
+    ok: false,
+    reason: `unknown envelope version: ${JSON.stringify(version)}`
+  };
+}
+function validateKyberAesV1(env) {
+  const kemAlgorithm = env.kemAlgorithm;
+  if (kemAlgorithm !== "ml-kem-768" && kemAlgorithm !== "ml-kem-1024") {
+    return {
+      ok: false,
+      reason: `kemAlgorithm must be 'ml-kem-768' or 'ml-kem-1024'`
+    };
+  }
+  if (!isNonEmptyString(env.kemCiphertext)) {
+    return { ok: false, reason: "kemCiphertext must be a non-empty base64 string" };
+  }
+  const kemCtBytes = tryDecodeBase64(env.kemCiphertext);
+  if (!kemCtBytes) {
+    return { ok: false, reason: "kemCiphertext is not valid base64" };
+  }
+  const expectedKemLen = KEM_CT_LEN[kemAlgorithm];
+  if (kemCtBytes.length !== expectedKemLen) {
+    return {
+      ok: false,
+      reason: `kemCiphertext length ${kemCtBytes.length} != expected ${expectedKemLen} for ${kemAlgorithm}`
+    };
+  }
+  if (!isString(env.recipientPkFingerprint) || !/^[0-9a-f]{32}$/i.test(env.recipientPkFingerprint)) {
+    return {
+      ok: false,
+      reason: "recipientPkFingerprint must be a 32-char hex string (16-byte sha384 prefix)"
+    };
+  }
+  if (env.aesAlgorithm !== "aes-256-gcm") {
+    return { ok: false, reason: `aesAlgorithm must be 'aes-256-gcm'` };
+  }
+  if (!isNonEmptyString(env.aesIv)) {
+    return { ok: false, reason: "aesIv must be a non-empty base64 string" };
+  }
+  const ivBytes = tryDecodeBase64(env.aesIv);
+  if (!ivBytes) return { ok: false, reason: "aesIv is not valid base64" };
+  if (ivBytes.length !== AES_IV_LEN) {
+    return {
+      ok: false,
+      reason: `aesIv length ${ivBytes.length} != expected ${AES_IV_LEN} (AES-GCM 96-bit nonce)`
+    };
+  }
+  if (typeof env.aesCiphertext !== "string") {
+    return { ok: false, reason: "aesCiphertext must be a base64 string" };
+  }
+  if (env.aesCiphertext.length > 0) {
+    const ctBytes = tryDecodeBase64(env.aesCiphertext);
+    if (!ctBytes) return { ok: false, reason: "aesCiphertext is not valid base64" };
+  }
+  if (!isNonEmptyString(env.aesAuthTag)) {
+    return { ok: false, reason: "aesAuthTag must be a non-empty base64 string" };
+  }
+  const tagBytes = tryDecodeBase64(env.aesAuthTag);
+  if (!tagBytes) return { ok: false, reason: "aesAuthTag is not valid base64" };
+  if (tagBytes.length !== AES_TAG_LEN) {
+    return {
+      ok: false,
+      reason: `aesAuthTag length ${tagBytes.length} != expected ${AES_TAG_LEN} (AES-GCM 128-bit tag)`
+    };
+  }
+  if (env.kdfAlgorithm !== "hkdf-sha384") {
+    return { ok: false, reason: `kdfAlgorithm must be 'hkdf-sha384'` };
+  }
+  if (!isNonEmptyString(env.kdfSalt)) {
+    return { ok: false, reason: "kdfSalt must be a non-empty base64 string" };
+  }
+  const saltBytes = tryDecodeBase64(env.kdfSalt);
+  if (!saltBytes) return { ok: false, reason: "kdfSalt is not valid base64" };
+  if (saltBytes.length !== KDF_SALT_LEN) {
+    return {
+      ok: false,
+      reason: `kdfSalt length ${saltBytes.length} != expected ${KDF_SALT_LEN}`
+    };
+  }
+  if (!isNonEmptyString(env.kdfLabel)) {
+    return { ok: false, reason: "kdfLabel must be a non-empty string" };
+  }
+  if (env.kdfLabel.length > 256) {
+    return {
+      ok: false,
+      reason: `kdfLabel length ${env.kdfLabel.length} exceeds 256-char limit`
+    };
+  }
+  if (!isFiniteNumber(env.encryptedAt)) {
+    return { ok: false, reason: "encryptedAt must be a finite number (millis epoch)" };
+  }
+  return { ok: true, version: "kyber-aes-v1" };
+}
+function validateAesV0(env) {
+  if (!isNonEmptyString(env.aesIv)) {
+    return { ok: false, reason: "aesIv must be a non-empty base64 string" };
+  }
+  const ivBytes = tryDecodeBase64(env.aesIv);
+  if (!ivBytes) return { ok: false, reason: "aesIv is not valid base64" };
+  if (ivBytes.length !== AES_IV_LEN) {
+    return {
+      ok: false,
+      reason: `aesIv length ${ivBytes.length} != expected ${AES_IV_LEN} (AES-GCM 96-bit nonce)`
+    };
+  }
+  if (typeof env.aesCiphertext !== "string") {
+    return { ok: false, reason: "aesCiphertext must be a base64 string" };
+  }
+  if (env.aesCiphertext.length > 0) {
+    const ctBytes = tryDecodeBase64(env.aesCiphertext);
+    if (!ctBytes) return { ok: false, reason: "aesCiphertext is not valid base64" };
+  }
+  if (!isNonEmptyString(env.aesAuthTag)) {
+    return { ok: false, reason: "aesAuthTag must be a non-empty base64 string" };
+  }
+  const tagBytes = tryDecodeBase64(env.aesAuthTag);
+  if (!tagBytes) return { ok: false, reason: "aesAuthTag is not valid base64" };
+  if (tagBytes.length !== AES_TAG_LEN) {
+    return {
+      ok: false,
+      reason: `aesAuthTag length ${tagBytes.length} != expected ${AES_TAG_LEN} (AES-GCM 128-bit tag)`
+    };
+  }
+  return { ok: true, version: "aes-v0" };
+}
+
+// src/pqc-verify-envelope/verify-pqc-envelope.ts
+var KYBER_MIN_TIMESTAMP_MS = 17040672e5;
+async function verifyPqcEnvelope(envelope, options = {}) {
+  const schema = validateEnvelopeSchema(envelope);
+  if (!schema.ok) {
+    return {
+      valid: false,
+      reason: `schema-invalid: ${schema.reason}`,
+      details: { schemaValid: false, base64Valid: false, timestampPlausible: false }
+    };
+  }
+  const env = envelope;
+  const version = schema.version;
+  const details = {
+    version,
+    schemaValid: true,
+    base64Valid: true,
+    // computed below for kyber-aes-v1; legacy has no encryptedAt so treat as plausible.
+    timestampPlausible: true
+  };
+  if (version === "kyber-aes-v1") {
+    details.kemAlgorithm = env.kemAlgorithm;
+    details.recipientPkFingerprint = env.recipientPkFingerprint;
+    details.kdfLabel = env.kdfLabel;
+    details.encryptedAt = env.encryptedAt;
+    const minTs = options.minTimestamp ?? KYBER_MIN_TIMESTAMP_MS;
+    const maxTs = options.maxTimestamp ?? Date.now();
+    const ts = details.encryptedAt;
+    if (ts < minTs) {
+      details.timestampPlausible = false;
+      return {
+        valid: false,
+        reason: `timestamp-before-minimum: encryptedAt=${ts} < min=${minTs}`,
+        details
+      };
+    }
+    if (ts > maxTs) {
+      details.timestampPlausible = false;
+      return {
+        valid: false,
+        reason: `timestamp-in-future: encryptedAt=${ts} > max=${maxTs}`,
+        details
+      };
+    }
+    if (options.expectedLabel !== void 0) {
+      if (details.kdfLabel !== options.expectedLabel) {
+        return {
+          valid: false,
+          reason: `label-mismatch: expected='${options.expectedLabel}' actual='${details.kdfLabel}'`,
+          details
+        };
+      }
+    }
+    if (options.expectedRecipientPkFingerprint !== void 0) {
+      const a = (details.recipientPkFingerprint ?? "").toLowerCase();
+      const b = options.expectedRecipientPkFingerprint.toLowerCase();
+      if (a !== b) {
+        return {
+          valid: false,
+          reason: `recipient-pk-fingerprint-mismatch: expected='${b}' actual='${a}'`,
+          details
+        };
+      }
+    }
+  }
+  return { valid: true, version, details };
+}
+
 // src/rules/atoms/index.ts
 var atom = {
   timeRange: (cfg) => ({
@@ -12543,6 +12785,7 @@ exports.HistoricalBalanceClient = HistoricalBalanceClient;
 exports.HistoricalBalanceClientError = HistoricalBalanceClientError;
 exports.IPFSClient = IPFSClient;
 exports.KNOWN_NETWORKS = KNOWN_NETWORKS;
+exports.KYBER_MIN_TIMESTAMP_MS = KYBER_MIN_TIMESTAMP_MS;
 exports.KeyConditionSchema = KeyConditionSchema;
 exports.MIRROR_NODE_URLS = MIRROR_NODE_URLS;
 exports.MessagingClient = MessagingClient;
@@ -12637,6 +12880,7 @@ exports.operator = operator_exports;
 exports.parsePqcCert = parsePqcCert;
 exports.personhood = personhood_exports;
 exports.pqcVerify = pqc_verify_exports;
+exports.pqcVerifyEnvelope = pqc_verify_envelope_exports;
 exports.resilientFetch = resilientFetch;
 exports.resolveNetwork = resolveNetwork;
 exports.resources = resources_exports;
@@ -12655,7 +12899,9 @@ exports.tradingAgent = tradingAgent;
 exports.utilityToken = utilityToken;
 exports.validate = validate;
 exports.validateAgentRules = validateAgentRules;
+exports.validateEnvelopeSchema = validateEnvelopeSchema;
 exports.verifyPqcAttestation = verifyPqcAttestation;
+exports.verifyPqcEnvelope = verifyPqcEnvelope;
 exports.vestingSchedule = vestingSchedule;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map