@hsuite/smart-engines-sdk 3.0.2 → 3.1.0

package/dist/nestjs/index.js

@@ -1022,6 +1022,185 @@ function normalizeRegistryEntry(raw) {
   return null;
 }
 
+// src/discovery/cluster-discovery.ts
+var ClusterDiscoveryClient = class {
+  bootstrap;
+  cacheTtlMs;
+  fetchTimeoutMs;
+  allowInsecure;
+  trustAnchorClient;
+  cache = null;
+  constructor(config) {
+    if (!config.bootstrap || config.bootstrap.length === 0) {
+      throw new Error("ClusterDiscoveryClient: bootstrap must list at least one seed URL");
+    }
+    if (!config.allowInsecure) {
+      for (const seed of config.bootstrap) {
+        if (!seed.startsWith("https://")) {
+          throw new Error(
+            `ClusterDiscoveryClient: bootstrap seed "${seed}" is not HTTPS. Set allowInsecure=true for local development only.`
+          );
+        }
+      }
+    }
+    this.bootstrap = config.bootstrap;
+    this.cacheTtlMs = config.cacheTtlMs ?? 6e4;
+    this.fetchTimeoutMs = config.fetchTimeoutMs ?? 5e3;
+    this.allowInsecure = config.allowInsecure ?? false;
+    this.trustAnchorClient = config.trustAnchor ? new ValidatorDiscoveryClient(config.trustAnchor) : null;
+  }
+  /**
+   * Fetch the active-cluster set, with caching.
+   *
+   * Tries each bootstrap seed in order until one returns HTTP 200 with a
+   * parseable cluster list. If all seeds fail, throws — callers can
+   * handle by falling back to a previously-cached value if they want,
+   * or by initializing with multiple seeds.
+   */
+  async getClusters(forceRefresh = false) {
+    if (!forceRefresh && this.cache && this.isCacheValid()) {
+      return this.cache.clusters;
+    }
+    const fetched = await this.fetchFromFirstAvailableSeed();
+    const verified = this.trustAnchorClient ? await this.verifyAgainstTrustAnchor(fetched) : fetched;
+    this.cache = { clusters: verified, lastUpdated: Date.now() };
+    return verified;
+  }
+  /**
+   * Random pick over the active-cluster set. Returns `null` when no
+   * cluster passes verification (empty registry / all-rejected anchor).
+   *
+   * Uses `crypto.getRandomValues` when available (browsers, Deno, modern
+   * Node) for cryptographic-strength randomness; `Math.random` is a
+   * fallback for older runtimes where `globalThis.crypto` is undefined.
+   * Discovery isn't cryptographically sensitive — load distribution is
+   * the goal here.
+   */
+  async getRandomCluster(forceRefresh = false) {
+    const clusters = await this.getClusters(forceRefresh);
+    if (clusters.length === 0) return null;
+    return clusters[this.pickRandomIndex(clusters.length)];
+  }
+  /**
+   * Convenience wrapper returning just the gateway URL of a random
+   * active cluster. The single most-used SDK entry point — most
+   * downstream callers want `new SmartEngineClient({ baseUrl: ... })`
+   * and don't care about the rest of the metadata.
+   */
+  async getRandomGatewayUrl(forceRefresh = false) {
+    const cluster = await this.getRandomCluster(forceRefresh);
+    return cluster?.endpoints.gatewayUrl ?? null;
+  }
+  /** Per-clusterId lookup, useful for "stick the SDK to cluster X" flows. */
+  async getClusterById(clusterId, forceRefresh = false) {
+    const clusters = await this.getClusters(forceRefresh);
+    return clusters.find((c) => c.clusterId === clusterId) ?? null;
+  }
+  clearCache() {
+    this.cache = null;
+  }
+  isCacheValid() {
+    if (!this.cache) return false;
+    return Date.now() - this.cache.lastUpdated < this.cacheTtlMs;
+  }
+  async fetchFromFirstAvailableSeed() {
+    const errors = [];
+    for (const seed of this.bootstrap) {
+      try {
+        return await this.fetchClustersFromSeed(seed);
+      } catch (err) {
+        errors.push(`${seed}: ${err.message}`);
+      }
+    }
+    throw new Error(
+      `ClusterDiscoveryClient: no bootstrap seed reachable. Attempts:
+  ${errors.join("\n  ")}`
+    );
+  }
+  async fetchClustersFromSeed(seed) {
+    const url = `${seed.replace(/\/$/, "")}/api/v3/discovery/clusters`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.fetchTimeoutMs);
+    try {
+      const res = await fetch(url, { signal: ctrl.signal });
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      const body = await res.json();
+      if (!Array.isArray(body.clusters)) {
+        throw new Error("response missing clusters[]");
+      }
+      return body.clusters.map((c) => this.normalizeClusterEntry(c)).filter((c) => c !== null);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  normalizeClusterEntry(raw) {
+    if (typeof raw.clusterId !== "string" || !raw.clusterId) return null;
+    if (!raw.endpoints || typeof raw.endpoints !== "object") return null;
+    const ep = raw.endpoints;
+    if (typeof ep.gatewayUrl !== "string" || !ep.gatewayUrl) return null;
+    if (!this.allowInsecure && !ep.gatewayUrl.startsWith("https://")) {
+      return null;
+    }
+    const nodeIds = Array.isArray(raw.nodeIds) ? raw.nodeIds.filter((n) => typeof n === "string") : [];
+    return {
+      clusterId: raw.clusterId,
+      endpoints: {
+        clusterId: raw.clusterId,
+        gatewayUrl: ep.gatewayUrl,
+        harborUrl: typeof ep.harborUrl === "string" ? ep.harborUrl : void 0,
+        natsUrl: typeof ep.natsUrl === "string" ? ep.natsUrl : void 0,
+        publicIp: typeof ep.publicIp === "string" ? ep.publicIp : void 0,
+        region: typeof ep.region === "string" ? ep.region : void 0
+      },
+      nodeIds
+    };
+  }
+  /**
+   * Cross-check the HTTP-fetched cluster set against the HCS validator
+   * registry. Clusters whose nodeIds are not on-chain are dropped.
+   *
+   * Two failure modes are deliberately silent here:
+   *   - the HCS read itself throws → original list is returned
+   *     un-verified. Trust-anchor is advisory; a network partition
+   *     between SDK and Hedera mirror shouldn't strand the SDK.
+   *   - the HCS read returns empty (mirror node lag, wrong topicId)
+   *     → original list is returned. Better to keep working off
+   *     possibly-stale-but-real data than reject every cluster.
+   *
+   * Both behaviors are why this is called "trust *anchor*", not
+   * "trust gate". Crypto-strong gating is a follow-up.
+   */
+  async verifyAgainstTrustAnchor(clusters) {
+    if (!this.trustAnchorClient || clusters.length === 0) return clusters;
+    let onChainNodeIds;
+    try {
+      const validators = await this.trustAnchorClient.getValidators();
+      if (validators.length === 0) return clusters;
+      onChainNodeIds = new Set(validators.map((v) => v.nodeId));
+    } catch {
+      return clusters;
+    }
+    return clusters.filter((c) => {
+      if (c.nodeIds.length === 0) {
+        return false;
+      }
+      return c.nodeIds.some((id) => onChainNodeIds.has(id));
+    });
+  }
+  pickRandomIndex(n) {
+    if (n <= 1) return 0;
+    const g = globalThis.crypto;
+    if (g?.getRandomValues) {
+      const buf = new Uint32Array(1);
+      g.getRandomValues(buf);
+      return buf[0] % n;
+    }
+    return Math.floor(Math.random() * n);
+  }
+};
+
 // src/auth/validator-auth.ts
 var SUPPORTED_AUTH_CHAINS = [
   "hedera",
@@ -1354,14 +1533,14 @@ function createHttpClient(config) {
       throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
     }
   }
-  async function upload(path, file, filename, metadata) {
+  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("file", blob, filename);
+      formData.append(fieldName, blob, filename);
       if (metadata) {
         for (const [key, value] of Object.entries(metadata)) {
           formData.append(key, value);
@@ -1405,7 +1584,7 @@ function createHttpClient(config) {
     get: (path) => request("GET", path),
     put: (path, body) => request("PUT", path, body),
     delete: (path) => request("DELETE", path),
-    upload,
+    upload: ((path, file, filename, metadata, fieldName) => upload(path, file, filename, metadata, fieldName)),
     setAuthToken
   };
   return client;
@@ -1832,6 +2011,167 @@ var SnapshotsClient = class {
   }
 };
 
+// src/historical-balance/historical-balance-client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var ENDPOINT_PATH = "/api/v3/historical-balance/query";
+var HistoricalBalanceClientError = class extends Error {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "HistoricalBalanceClientError";
+  }
+  statusCode;
+  details;
+};
+var HistoricalBalanceClient = class _HistoricalBalanceClient {
+  // Standalone-mode fields (set when the client builds its own fetch).
+  baseUrl;
+  authToken;
+  apiKey;
+  timeoutMs;
+  fetchImpl;
+  // Sub-client-mode field (set when wired via SmartEngineClient).
+  http;
+  constructor(config) {
+    if ("http" in config) {
+      this.http = config.http;
+      this.timeoutMs = DEFAULT_TIMEOUT_MS;
+      return;
+    }
+    if (!config.baseUrl) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient: baseUrl is required for standalone construction",
+        400
+      );
+    }
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.authToken = config.authToken;
+    this.apiKey = config.apiKey;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = config.fetchImpl;
+  }
+  /**
+   * Factory used by `SmartEngineClient` to wire this sub-client onto the
+   * parent's shared `HttpClient` (which already carries auth + baseUrl + a
+   * `/api/v3` prefix). Routes through `/historical-balance/query` since the
+   * parent's HttpClient is rooted at `/api/v3`.
+   */
+  static fromHttp(http) {
+    return new _HistoricalBalanceClient({ http });
+  }
+  /**
+   * Query a point-in-time balance.
+   *
+   * The validator returns the on-chain bigint as a base-10 decimal string.
+   * Callers needing arithmetic precision should wrap the result:
+   *
+   * ```ts
+   * const { balance } = await client.historicalBalance.getBalance({ ... });
+   * const value = BigInt(balance);
+   * ```
+   */
+  async getBalance(params) {
+    this.validateParams(params);
+    if (this.http) {
+      return this.http.post("/historical-balance/query", params);
+    }
+    return this.standaloneFetch(params);
+  }
+  validateParams(params) {
+    if (!params || typeof params !== "object") {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient.getBalance: params object is required",
+        400
+      );
+    }
+    const { chain, entityId, account, atTimestamp } = params;
+    if (chain !== "hedera" && chain !== "xrpl" && chain !== "polkadot") {
+      throw new HistoricalBalanceClientError(
+        `HistoricalBalanceClient.getBalance: unsupported chain "${String(chain)}" (expected hedera | xrpl | polkadot)`,
+        400
+      );
+    }
+    if (typeof entityId !== "string" || entityId.length === 0) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient.getBalance: entityId must be a non-empty string",
+        400
+      );
+    }
+    if (typeof account !== "string" || account.length === 0) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient.getBalance: account must be a non-empty string",
+        400
+      );
+    }
+    if (typeof atTimestamp !== "number" || !Number.isInteger(atTimestamp) || atTimestamp <= 0) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient.getBalance: atTimestamp must be a positive integer (unix seconds)",
+        400
+      );
+    }
+  }
+  async standaloneFetch(params) {
+    const url = `${this.baseUrl}${ENDPOINT_PATH}`;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (this.authToken) headers.Authorization = `Bearer ${this.authToken}`;
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    const fetchFn = this.fetchImpl ?? (typeof fetch !== "undefined" ? fetch : void 0);
+    if (!fetchFn) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient: no fetch implementation available (provide fetchImpl)",
+        500
+      );
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await fetchFn(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(params),
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      const message = err instanceof Error ? err.message : String(err);
+      throw new HistoricalBalanceClientError(
+        `HistoricalBalanceClient: transport error: ${message}`,
+        0,
+        err
+      );
+    }
+    clearTimeout(timer);
+    let body;
+    const text = await response.text();
+    if (text.length > 0) {
+      try {
+        body = JSON.parse(text);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new HistoricalBalanceClientError(
+          `HistoricalBalanceClient: non-JSON response (status=${response.status}): ${message}`,
+          response.status,
+          { raw: text }
+        );
+      }
+    }
+    if (!response.ok) {
+      const detail = body && typeof body === "object" && "message" in body ? String(body.message) : `HTTP ${response.status}`;
+      throw new HistoricalBalanceClientError(
+        `HistoricalBalanceClient: ${detail}`,
+        response.status,
+        body
+      );
+    }
+    return body;
+  }
+};
+
 // src/settlement/index.ts
 var SettlementClient = class {
   constructor(http) {
@@ -1866,6 +2206,53 @@ var SettlementClient = class {
   }
 };
 
+// src/governance/governance-client.ts
+var GovernanceClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Dry-run a governance proposal/vote/etc. against `GovernanceMolecule.validate(...)`.
+   *
+   * Returns whatever `ValidationResult` the molecule produced. A `false`
+   * `isValid` is **not** an error — it is a successful "this proposal is
+   * invalid" outcome and is surfaced via the normal return value.
+   *
+   * HTTP errors (400 malformed body, 500 unexpected) bubble up as
+   * `SdkHttpError` via the shared `HttpClient` layer.
+   */
+  async simulate(params) {
+    return this.http.post("/governance/simulate", params);
+  }
+};
+
+// src/personhood/personhood-client.ts
+var PersonhoodClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Verify a personhood proof for `candidate`.
+   *
+   * Returns the issued cert on accept, `null` on clean rejection. All
+   * other failure modes (validation, transport, 5xx) propagate as
+   * `SdkHttpError`.
+   */
+  async verify(params) {
+    const result = await this.http.post(
+      "/personhood/verify",
+      {
+        candidate: params.candidate,
+        proof: params.proof
+      }
+    );
+    if (result === void 0) return null;
+    return result;
+  }
+};
+
 // src/client.ts
 var SmartEngineClient = class _SmartEngineClient {
   baseUrl;
@@ -1886,8 +2273,14 @@ var SmartEngineClient = class _SmartEngineClient {
   transactions;
   /** Token holder snapshot generation and retrieval */
   snapshots;
+  /** Historical balance archive reads (chain-native bigint, returned as decimal string) */
+  historicalBalance;
   /** Cross-chain settlement operations */
   settlement;
+  /** Governance proposal dry-run (simulate-only) */
+  governance;
+  /** Personhood verification (HPP one-human-one-member) */
+  personhood;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
     this.baseUrl = validateClientUrl(config.baseUrl, this.allowInsecure);
@@ -1908,7 +2301,10 @@ var SmartEngineClient = class _SmartEngineClient {
     this.ipfs = new IPFSClient(this.http);
     this.transactions = new TransactionsClient(this.txHttp);
     this.snapshots = new SnapshotsClient(this.http);
+    this.historicalBalance = HistoricalBalanceClient.fromHttp(this.http);
     this.settlement = new SettlementClient(this.http);
+    this.governance = new GovernanceClient(this.http);
+    this.personhood = new PersonhoodClient(this.http);
   }
   /**
    * Connect to the smart-engines network with auto-discovery and authentication
@@ -1953,6 +2349,67 @@ var SmartEngineClient = class _SmartEngineClient {
     });
     return { client, validator, session };
   }
+  /**
+   * Connect to the smart-engines network via the **service-registry**
+   * (PR-1 of the cluster-discovery arc). Preferred over
+   * {@link connectToNetwork} once the validator pods in the target network
+   * have published their cluster endpoints — the SDK auto-balances across
+   * the active cluster set and rides permissionless cluster join/leave
+   * without code edits.
+   *
+   * Fallback ladder (per `docs/ops/HANDOFF-service-registry-distribution-layer.md` §6):
+   *   1. HTTP fetch `/api/v3/discovery/clusters` from each bootstrap seed.
+   *   2. (Optional) HCS trust-anchor membership cross-check.
+   *   3. Random-pick over the verified set.
+   *
+   * @example
+   * ```ts
+   * const { client, cluster, session } = await SmartEngineClient.connectToCluster({
+   *   bootstrap: ['https://sn1.testnet.hsuite.network', 'https://sn2.testnet.hsuite.network'],
+   *   chain: 'xrpl',
+   *   address: '...',
+   *   publicKey: '...',
+   *   signFn: async (challenge) => sign(challenge),
+   * });
+   * ```
+   */
+  static async connectToCluster(config) {
+    const allowInsecure = config.allowInsecure ?? false;
+    const discovery = new ClusterDiscoveryClient({
+      bootstrap: config.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) {
+      throw new SmartEngineError2(
+        "No active clusters available via bootstrap seeds. Check bootstrap URLs and network reachability.",
+        503
+      );
+    }
+    const gatewayUrl = cluster.endpoints.gatewayUrl;
+    validateClientUrl(gatewayUrl, allowInsecure);
+    const auth = new ValidatorAuthClient({ security: { allowInsecure } });
+    const session = await auth.authenticateWithSigner(
+      gatewayUrl,
+      config.chain,
+      config.address,
+      config.publicKey,
+      config.signFn,
+      config.metadata
+    );
+    const client = new _SmartEngineClient({
+      baseUrl: gatewayUrl,
+      authToken: session.token,
+      allowInsecure
+    });
+    return { client, cluster, session };
+  }
   /** Get the current validator URL */
   getBaseUrl() {
     return this.baseUrl;
@@ -2730,49 +3187,101 @@ var DeploymentClient = class {
   }
   http;
   /**
-   * Create (deploy) a new app
+   * Step 1 — allocate appId + receive ephemeral push credentials for
+   * the cluster's per-tenant Harbor project.
+   *
+   * Each app gets its own Harbor project (`hsuite-customers-<appId>`)
+   * isolated by Harbor's RBAC. The push robot returned in
+   * `registry.{username, password}` is scoped to that project only —
+   * it cannot read or write any other tenant's images.
+   *
+   * **Single-use secret discipline:** `registry.password` is returned
+   * exactly once and is NOT persisted server-side. Store it locally
+   * for the `docker push` and discard. To rotate, call `init` again
+   * (issues a new robot under the same project).
+   *
+   * Use the credentials to `docker login` + `docker push`, then call
+   * {@link deploy} with the pushed image tag.
+   */
+  async init(request) {
+    return this.http.post("/api/deployment/apps/init", request);
+  }
+  /**
+   * Step 3 (optional) — upload the SPA tarball.
+   *
+   * The tarball is content-addressed (SHA-256) and mounted read-only
+   * into the customer's pod alongside the backend container. Returns
+   * the hash + size so the caller can verify the upload.
+   */
+  async uploadFrontend(appId, bundle, filename = "bundle.tar.gz") {
+    return this.http.upload(
+      `/api/deployment/apps/${encodeURIComponent(appId)}/frontend`,
+      bundle,
+      filename,
+      void 0,
+      "bundle"
+    );
+  }
+  /**
+   * Step 4 — reconcile the runtime to k8s.
+   *
+   * Returns immediately with `status: 'deploying'`. Poll {@link status}
+   * until `runtime.runtimeState === 'RUNNING'` for the URL to be live.
    */
-  async create(request) {
-    return this.http.post("/api/deployment/apps", request);
+  async deploy(appId, request) {
+    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/deploy`, request);
   }
   /**
-   * List all deployed apps
+   * 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);
+  }
+  /**
+   * Live combined lifecycle + runtime status of an app.
+   */
+  async status(appId) {
+    return this.http.get(`/api/deployment/apps/${encodeURIComponent(appId)}/status`);
+  }
+  /**
+   * List all deployed apps for the authenticated developer.
    */
   async list() {
     return this.http.get("/api/deployment/apps");
   }
   /**
-   * Get app details
+   * Get app details.
    */
   async get(appId) {
     return this.http.get(`/api/deployment/apps/${encodeURIComponent(appId)}`);
   }
   /**
-   * Update app configuration
+   * Update app configuration. Runtime effect lands in PR-H.
    */
   async update(appId, updates) {
     return this.http.put(`/api/deployment/apps/${encodeURIComponent(appId)}`, updates);
   }
   /**
-   * Delete an app
+   * Delete an app. Runtime effect (namespace teardown) lands in PR-H.
    */
   async delete(appId) {
     return this.http.delete(`/api/deployment/apps/${encodeURIComponent(appId)}`);
   }
   /**
-   * Suspend an app
+   * 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`, {});
   }
   /**
-   * Resume a suspended app
+   * 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`, {});
   }
   /**
-   * Get deployment statistics
+   * Get deployment statistics.
    */
   async getStats() {
     return this.http.get("/api/deployment/stats");
@@ -2843,6 +3352,78 @@ var AgentsClient = class {
   }
 };
 
+// src/baas/customer-session/index.ts
+var CustomerSessionClient = class {
+  constructor(baseUrl, timeoutMs = 3e4) {
+    this.baseUrl = baseUrl;
+    this.timeoutMs = timeoutMs;
+  }
+  baseUrl;
+  timeoutMs;
+  /**
+   * Step 1: ask the host to issue a fresh challenge for the customer to sign.
+   */
+  async challenge(input) {
+    return this.fetch("POST", "/api/customer-session/challenge", input);
+  }
+  /**
+   * Step 2: submit the customer's signed challenge. On success returns a
+   * short-lived bearer JWT scoped to {appId, chain, address}.
+   */
+  async verify(req) {
+    return this.fetch("POST", "/api/customer-session/verify", req);
+  }
+  /**
+   * Validate a customer bearer + return the decoded session info. Used by
+   * smart-app backends to authorise incoming customer requests.
+   */
+  async validate(bearer) {
+    return this.fetch("GET", "/api/customer-session/validate", void 0, bearer);
+  }
+  /**
+   * Revoke a customer session. Idempotent.
+   */
+  async end(bearer) {
+    return this.fetch(
+      "POST",
+      "/api/customer-session/end",
+      void 0,
+      bearer
+    );
+  }
+  async fetch(method, path, body, bearer) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const headers = { "Content-Type": "application/json" };
+      if (bearer) headers["Authorization"] = `Bearer ${bearer}`;
+      const init = { method, headers, signal: controller.signal };
+      if (body !== void 0) init.body = JSON.stringify(body);
+      const response = await fetch(url, init);
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errBody = await response.json().catch(() => ({}));
+        const err = new Error(
+          errBody.message ?? `customer-session ${path} failed: ${response.status} ${response.statusText}`
+        );
+        err.status = response.status;
+        throw err;
+      }
+      const text = await response.text();
+      if (!text) return void 0;
+      return JSON.parse(text);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      const e = error;
+      if (e.name === "AbortError") {
+        throw new Error(`customer-session ${path} timeout`);
+      }
+      throw error;
+    }
+  }
+};
+
 // src/baas/client.ts
 var BaasClient = class {
   hostUrl;
@@ -2867,6 +3448,8 @@ var BaasClient = class {
   deployment;
   /** Autonomous smart agent management */
   agents;
+  /** Customer→smart-app session bridge (TokenGate Face B). */
+  customerSession;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
     this.hostUrl = validateUrl2(config.hostUrl, this.allowInsecure);
@@ -2886,6 +3469,7 @@ var BaasClient = class {
     this.messaging = new MessagingClient(this.http, getAppId);
     this.deployment = new DeploymentClient(this.http);
     this.agents = new AgentsClient(this.http);
+    this.customerSession = new CustomerSessionClient(baseUrlWithPrefix, this.timeout);
   }
   /** Set the app ID (for newly registered apps) */
   setAppId(appId) {
@@ -2912,7 +3496,7 @@ var BaasClient = class {
   requireAppId() {
     if (!this.appId) {
       throw new BaasError(
-        "App ID required. Either provide appId in config or call register() first.",
+        "App ID required. Provide appId in config (e.g. from a prior deployment.init() call).",
         400
       );
     }
@@ -2959,12 +3543,6 @@ var BaasClient = class {
     }
     this.authToken = null;
   }
-  // ========== App Registration ==========
-  /** Register a new app on the BaaS host */
-  async register(request) {
-    this.requireAuth();
-    return this.post("/api/deployment/apps", request);
-  }
   // ========== HTTP Helpers ==========
   requireAuth() {
     if (!this.authToken) {