@hsuite/smart-engines-sdk 3.2.0 → 3.3.0

package/dist/nestjs/index.js

@@ -35,29 +35,6 @@ zod.z.object({
   blockTime: zod.z.number().optional(),
   rpcEndpoint: zod.z.string().url().optional()
 });
-var NetworkMembershipTypeSchema = zod.z.enum(["validator", "host", "gateway"]);
-var MembershipStatusSchema = zod.z.enum(["pending", "active", "exiting", "exited", "banned"]);
-zod.z.object({
-  nodeId: zod.z.string().min(1),
-  networkType: NetworkMembershipTypeSchema,
-  chain: zod.z.enum(["hedera", "xrpl", "polkadot", "solana"]),
-  endpoint: zod.z.string().url(),
-  publicKey: zod.z.string().min(1),
-  joinedAt: zod.z.string().datetime(),
-  depositTxId: zod.z.string().min(1),
-  status: MembershipStatusSchema,
-  networkConfig: zod.z.record(zod.z.unknown()).optional()
-});
-var NetworkDepositRequirementsSchema = zod.z.object({
-  depositAmount: zod.z.string().min(1),
-  lockDurationDays: zod.z.number().int().positive(),
-  renewalWindowDays: zod.z.number().int().positive().optional()
-});
-zod.z.object({
-  validator: NetworkDepositRequirementsSchema,
-  host: NetworkDepositRequirementsSchema,
-  gateway: NetworkDepositRequirementsSchema
-});
 var TokenCapabilitiesSchema = zod.z.object({
   /**
    * Pause all token operations globally
@@ -126,19 +103,16 @@ zod.z.object({
   ).optional(),
   timestamp: zod.z.date()
 });
-var SecurityModeSchema = zod.z.enum(["none", "partial", "full"]);
+var SecurityModeSchema = zod.z.enum(["partial", "full"]);
 var sovereigntyRefinePredicate = (v) => {
   if (v.securityMode === "partial") {
     return !!v.entityId && !!v.appOwnerPublicKey;
   }
-  if (v.securityMode === "full") {
-    return !!v.entityId;
-  }
-  return true;
+  return !!v.entityId;
 };
 var SOVEREIGNTY_REFINE_MESSAGE = "securityMode='partial' requires entityId+appOwnerPublicKey; 'full' requires entityId";
 var SovereigntyFieldsRawSchema = zod.z.object({
-  securityMode: SecurityModeSchema.default("none"),
+  securityMode: SecurityModeSchema.default("full"),
   entityId: zod.z.string().optional(),
   appOwnerPublicKey: zod.z.string().optional()
 });
@@ -212,7 +186,6 @@ var PreparedTransactionAuthorizationSetSchema = zod.z.discriminatedUnion("chain"
   PolkadotAuthorizationSetShapeSchema
 ]);
 var PreparedTransactionSovereigntySchema = zod.z.discriminatedUnion("mode", [
-  zod.z.object({ mode: zod.z.literal("none") }),
   zod.z.object({
     mode: zod.z.literal("partial"),
     entityId: zod.z.string(),
@@ -226,74 +199,6 @@ var PreparedTransactionSovereigntySchema = zod.z.discriminatedUnion("mode", [
     authorizationSet: PreparedTransactionAuthorizationSetSchema.optional()
   })
 ]);
-var TransactionStatusSchema = zod.z.enum(["pending", "success", "failed", "expired"]);
-var TransactionTypeSchema = zod.z.enum([
-  "transfer",
-  "token_transfer",
-  "account_create",
-  "token_create",
-  "token_mint",
-  "token_burn",
-  "contract_call",
-  "contract_create",
-  "topic_message",
-  "other"
-]);
-zod.z.object({
-  id: zod.z.string(),
-  chain: ChainTypeSchema,
-  type: TransactionTypeSchema,
-  status: TransactionStatusSchema,
-  timestamp: zod.z.date(),
-  from: AccountIdSchema,
-  to: AccountIdSchema.optional(),
-  amount: zod.z.string().optional(),
-  fee: zod.z.string(),
-  memo: zod.z.string().optional(),
-  metadata: zod.z.record(zod.z.any()).optional()
-});
-zod.z.object({
-  transactionId: zod.z.string(),
-  chain: ChainTypeSchema,
-  status: TransactionStatusSchema,
-  blockNumber: zod.z.number().optional(),
-  blockHash: zod.z.string().optional(),
-  timestamp: zod.z.date(),
-  gasUsed: zod.z.string().optional(),
-  effectiveFee: zod.z.string(),
-  logs: zod.z.array(zod.z.any()).optional(),
-  metadata: zod.z.record(zod.z.any()).optional()
-});
-var TokenTypeSchema = zod.z.enum(["fungible", "nft", "semi_fungible"]);
-var TokenSchema = zod.z.object({
-  tokenId: zod.z.string(),
-  chain: ChainTypeSchema,
-  name: zod.z.string(),
-  symbol: zod.z.string(),
-  decimals: zod.z.number().int().min(0),
-  totalSupply: zod.z.string(),
-  type: TokenTypeSchema,
-  creator: AccountIdSchema.optional(),
-  metadata: zod.z.record(zod.z.any()).optional(),
-  createdAt: zod.z.date().optional()
-});
-zod.z.object({
-  name: zod.z.string(),
-  description: zod.z.string().optional(),
-  image: zod.z.string().url().optional(),
-  attributes: zod.z.array(
-    zod.z.object({
-      trait_type: zod.z.string(),
-      value: zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()])
-    })
-  ).optional(),
-  external_url: zod.z.string().url().optional()
-});
-TokenSchema.extend({
-  holders: zod.z.number().optional(),
-  transferCount: zod.z.number().optional(),
-  circulatingSupply: zod.z.string().optional()
-});
 var CreateAccountRequestSchema = zod.z.object({
   chain: ChainTypeSchema,
   initialBalance: zod.z.string(),
@@ -323,12 +228,11 @@ var CreateAccountRequestSchema = zod.z.object({
   immutable: zod.z.boolean().default(true),
   /**
    * Smart node security mode for the account key structure.
-   * - 'none': Owner-only key (no validator involvement)
    * - 'partial': threshold(2, [appOwnerKey, tssKeyList]) — co-control
    * - 'full': TSS KeyList only — full validator network control
-   * Default: 'none' for basic account creation via SDK.
+   * Default: 'full' (Arc 5 §7.5.2: 'none' removed).
    */
-  securityMode: zod.z.enum(["none", "partial", "full"]).default("none"),
+  securityMode: zod.z.enum(["partial", "full"]).default("full"),
   /**
    * App owner's public key (required for 'partial' security mode).
    * The owner key + TSS network key form a threshold-2 multi-sig.
@@ -541,7 +445,7 @@ var SolanaPreparedMetadataSchema = zod.z.object({
   /** Whether the multisig was created in this call (vs already existed) */
   multisigCreated: zod.z.boolean().optional(),
   /** Security mode used to prepare this transaction */
-  securityMode: zod.z.enum(["none", "partial", "full"]).optional(),
+  securityMode: zod.z.enum(["partial", "full"]).optional(),
   /** SPL Token mint address (token-create and all SPL operations) */
   splMint: zod.z.string().optional()
 });
@@ -647,12 +551,7 @@ zod.z.object({
   validatorTimestamp: zod.z.string().min(1),
   validatorTopicId: zod.z.string().min(1)
 }).merge(SovereigntyFieldsRawSchema).refine(
-  (v) => {
-    if (v.securityMode === "partial" || v.securityMode === "full") {
-      return !!v.entityId;
-    }
-    return true;
-  },
+  (v) => !!v.entityId,
   { message: "securityMode='partial'/'full' requires entityId" }
 );
 
@@ -1593,6 +1492,32 @@ function encodePathParam(param) {
   return encodeURIComponent(param).replace(/%2F/gi, "");
 }
 
+// src/network-presets.ts
+var KNOWN_NETWORKS = {
+  testnet: {
+    bootstrap: ["https://gateway.testnet.hsuite.network"]
+  },
+  mainnet: {
+    // Mainnet entrypoint reserved. The SDK still resolves the name so
+    // upgrade-by-flipping-NETWORK works; the bootstrap URL is the
+    // pre-allocated DNS we own. If mainnet isn't deployed yet, the discovery
+    // fetch will fail at runtime with the same "no seed reachable" error
+    // any unreachable URL produces — the caller learns the network is not
+    // live, rather than getting a baffling "unknown network" TypeScript
+    // error at compile time.
+    bootstrap: ["https://gateway.hsuite.network"]
+  }
+};
+function resolveNetwork(name) {
+  const preset = KNOWN_NETWORKS[name];
+  if (!preset) {
+    throw new Error(
+      `Unknown network: "${name}". Known networks: ${Object.keys(KNOWN_NETWORKS).join(", ")}`
+    );
+  }
+  return preset;
+}
+
 // src/subscription/index.ts
 var SubscriptionClient = class {
   constructor(http) {
@@ -2271,6 +2196,178 @@ var PersonhoodClient = class {
   }
 };
 
+// src/baas/agents/index.ts
+var AgentsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Register a new agent */
+  async register(request) {
+    return this.http.post("/api/agents/register", request);
+  }
+  /** Get agent details */
+  async get(agentId) {
+    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}`);
+  }
+  /** List all agents */
+  async list() {
+    return this.http.get("/api/agents");
+  }
+  /** Fund an agent */
+  async fund(agentId, request) {
+    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/fund`, request);
+  }
+  /** Execute a trade */
+  async trade(agentId, request) {
+    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/trade`, request);
+  }
+  /** Withdraw funds from agent */
+  async withdraw(agentId, request) {
+    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/withdraw`, request);
+  }
+  /** Pause an agent */
+  async pause(agentId) {
+    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/pause`, {});
+  }
+  /** Resume a paused agent */
+  async resume(agentId) {
+    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/resume`, {});
+  }
+  /** Revoke an agent (permanent) */
+  async revoke(agentId) {
+    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/revoke`, {});
+  }
+  /** Update agent rules */
+  async updateRules(agentId, rules) {
+    return this.http.put(`/api/agents/${encodeURIComponent(agentId)}/rules`, rules);
+  }
+  /** Get agent events */
+  async getEvents(agentId) {
+    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}/events`);
+  }
+  /** Get agent balances across chains */
+  async getBalances(agentId) {
+    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}/balances`);
+  }
+  /** Approve a pending agent operation */
+  async approve(agentId, operationId) {
+    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/approve/${encodeURIComponent(operationId)}`, {});
+  }
+  /** Reject a pending agent operation */
+  async reject(agentId, operationId) {
+    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/reject/${encodeURIComponent(operationId)}`, {});
+  }
+};
+
+// src/baas/deployment/index.ts
+var DeploymentClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * 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 deploy(appId, request) {
+    return this.http.post(`/api/deployment/apps/${encodeURIComponent(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);
+  }
+  /**
+   * 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.
+   */
+  async get(appId) {
+    return this.http.get(`/api/deployment/apps/${encodeURIComponent(appId)}`);
+  }
+  /**
+   * 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. Runtime effect (namespace teardown) lands in PR-H.
+   */
+  async delete(appId) {
+    return this.http.delete(`/api/deployment/apps/${encodeURIComponent(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`, {});
+  }
+  /**
+   * 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.
+   */
+  async getStats() {
+    return this.http.get("/api/deployment/stats");
+  }
+};
+
 // src/client.ts
 var SmartEngineClient = class _SmartEngineClient {
   baseUrl;
@@ -2307,6 +2404,10 @@ var SmartEngineClient = class _SmartEngineClient {
   governance;
   /** Personhood verification (HPP one-human-one-member) */
   personhood;
+  /** BaaS smart-agent lifecycle (register/fund/trade/withdraw/pause/resume/revoke/...) */
+  agents;
+  /** BaaS smart-app deployment lifecycle (init/uploadFrontend/deploy/rollback/status/...) */
+  deployments;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
     this.baseUrl = validateClientUrl(config.baseUrl, this.allowInsecure);
@@ -2335,6 +2436,40 @@ var SmartEngineClient = class _SmartEngineClient {
     this.settlement = new SettlementClient(this.http);
     this.governance = new GovernanceClient(this.http);
     this.personhood = new PersonhoodClient(this.http);
+    const rootHttp = createHttpClient({
+      baseUrl: this.baseUrl,
+      apiKey: config.apiKey,
+      authToken: config.authToken,
+      timeout: config.timeout
+    });
+    this.agents = new AgentsClient(rootHttp);
+    this.deployments = new DeploymentClient(rootHttp);
+  }
+  /**
+   * Build a `SmartEngineClient` from a plain env object. Reads:
+   *   - `VALIDATOR_URL`     (required) — gateway/validator base URL
+   *   - `VALIDATOR_API_KEY` (optional) — API key for authenticated calls
+   *   - `APP_TOKEN`         (optional) — session JWT from prior auth
+   *   - `ALLOW_INSECURE`    (optional, `'true'`) — only for local dev
+   *   - `REQUEST_TIMEOUT`   (optional, ms)
+   *
+   * Throws if `VALIDATOR_URL` is missing or invalid. Designed for BaaS
+   * scheduled functions: `const client = SmartEngineClient.fromEnv(ctx.env)`.
+   */
+  static fromEnv(env) {
+    const baseUrl = env["VALIDATOR_URL"];
+    if (!baseUrl) {
+      throw new SmartEngineError("VALIDATOR_URL is required to build a SmartEngineClient", 500);
+    }
+    const timeoutRaw = env["REQUEST_TIMEOUT"];
+    const timeout = timeoutRaw ? Number.parseInt(timeoutRaw, 10) : void 0;
+    return new _SmartEngineClient({
+      baseUrl,
+      apiKey: env["VALIDATOR_API_KEY"],
+      authToken: env["APP_TOKEN"],
+      allowInsecure: env["ALLOW_INSECURE"] === "true",
+      timeout: Number.isFinite(timeout) ? timeout : void 0
+    });
   }
   /**
    * Connect to the smart-engines network with auto-discovery and authentication
@@ -2354,7 +2489,7 @@ var SmartEngineClient = class _SmartEngineClient {
     });
     const validator = await discovery.getRandomValidator();
     if (!validator || !validator.networkEndpoints?.apiEndpoint) {
-      throw new SmartEngineError2(
+      throw new SmartEngineError(
         "No validators available. Check registry topic and network configuration.",
         503
       );
@@ -2392,7 +2527,18 @@ var SmartEngineClient = class _SmartEngineClient {
    *   2. (Optional) HCS trust-anchor membership cross-check.
    *   3. Random-pick over the verified set.
    *
-   * @example
+   * @example Zero-config (recommended for smart-app callers)
+   * ```ts
+   * const { client, cluster, session } = await SmartEngineClient.connectToCluster({
+   *   network: 'testnet',          // resolves canonical gateway entrypoint
+   *   chain: 'xrpl',
+   *   address: '...',
+   *   publicKey: '...',
+   *   signFn: async (challenge) => sign(challenge),
+   * });
+   * ```
+   *
+   * @example Custom seeds (private deployments / local dev)
    * ```ts
    * const { client, cluster, session } = await SmartEngineClient.connectToCluster({
    *   bootstrap: ['https://sn1.testnet.hsuite.network', 'https://sn2.testnet.hsuite.network'],
@@ -2405,8 +2551,15 @@ var SmartEngineClient = class _SmartEngineClient {
    */
   static async connectToCluster(config) {
     const allowInsecure = config.allowInsecure ?? false;
+    const bootstrap = config.bootstrap ? [...config.bootstrap] : [...resolveNetwork(config.network).bootstrap];
+    if (bootstrap.length === 0) {
+      throw new SmartEngineError(
+        "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
+        400
+      );
+    }
     const discovery = new ClusterDiscoveryClient({
-      bootstrap: config.bootstrap,
+      bootstrap,
       allowInsecure,
       trustAnchor: config.trustAnchor ? {
         network: config.trustAnchor.network,
@@ -2417,7 +2570,7 @@ var SmartEngineClient = class _SmartEngineClient {
     });
     const cluster = await discovery.getRandomCluster();
     if (!cluster) {
-      throw new SmartEngineError2(
+      throw new SmartEngineError(
         "No active clusters available via bootstrap seeds. Check bootstrap URLs and network reachability.",
         503
       );
@@ -2529,7 +2682,7 @@ var SmartEngineClient = class _SmartEngineClient {
   async restrictAccount(request) {
     const validated = TokenActionRequestSchema.parse(request);
     if (!validated.accountId) {
-      throw new SmartEngineError2("accountId is required for restrictAccount", 400);
+      throw new SmartEngineError("accountId is required for restrictAccount", 400);
     }
     return this.http.post("/tokens/restrict", validated);
   }
@@ -2537,7 +2690,7 @@ var SmartEngineClient = class _SmartEngineClient {
   async unrestrictAccount(request) {
     const validated = TokenActionRequestSchema.parse(request);
     if (!validated.accountId) {
-      throw new SmartEngineError2("accountId is required for unrestrictAccount", 400);
+      throw new SmartEngineError("accountId is required for unrestrictAccount", 400);
     }
     return this.http.post("/tokens/unrestrict", validated);
   }
@@ -2545,7 +2698,7 @@ var SmartEngineClient = class _SmartEngineClient {
   async enableCompliance(request) {
     const validated = TokenActionRequestSchema.parse(request);
     if (!validated.accountId) {
-      throw new SmartEngineError2("accountId is required for enableCompliance", 400);
+      throw new SmartEngineError("accountId is required for enableCompliance", 400);
     }
     return this.http.post("/tokens/compliance/enable", validated);
   }
@@ -2553,7 +2706,7 @@ var SmartEngineClient = class _SmartEngineClient {
   async disableCompliance(request) {
     const validated = TokenActionRequestSchema.parse(request);
     if (!validated.accountId) {
-      throw new SmartEngineError2("accountId is required for disableCompliance", 400);
+      throw new SmartEngineError("accountId is required for disableCompliance", 400);
     }
     return this.http.post("/tokens/compliance/disable", validated);
   }
@@ -2561,10 +2714,10 @@ var SmartEngineClient = class _SmartEngineClient {
   async wipeFromAccount(request) {
     const validated = TokenActionRequestSchema.parse(request);
     if (!validated.accountId) {
-      throw new SmartEngineError2("accountId is required for wipeFromAccount", 400);
+      throw new SmartEngineError("accountId is required for wipeFromAccount", 400);
     }
     if (!validated.amount) {
-      throw new SmartEngineError2("amount is required for wipeFromAccount", 400);
+      throw new SmartEngineError("amount is required for wipeFromAccount", 400);
     }
     return this.http.post("/tokens/wipe", validated);
   }
@@ -2585,7 +2738,7 @@ var SmartEngineClient = class _SmartEngineClient {
   /** Submit a message to consensus */
   async submitMessage(chain, topicId, message) {
     if (message.length > 1024 * 1024) {
-      throw new SmartEngineError2("Message too large (max 1MB)", 400);
+      throw new SmartEngineError("Message too large (max 1MB)", 400);
     }
     return this.http.post(`/messages/${encodePathParam(chain)}/${encodePathParam(topicId)}`, {
       message
@@ -2619,7 +2772,7 @@ var SmartEngineClient = class _SmartEngineClient {
     return this.http.post("/auth/verify-signature", request);
   }
 };
-var SmartEngineError2 = class extends Error {
+var SmartEngineError = class extends Error {
   constructor(message, statusCode, details) {
     super(message);
     this.statusCode = statusCode;
@@ -2633,18 +2786,18 @@ function validateClientUrl(url, allowInsecure = false) {
   try {
     const parsed = new URL(url);
     if (!["http:", "https:"].includes(parsed.protocol)) {
-      throw new SmartEngineError2(`Invalid protocol: ${parsed.protocol}`, 400);
+      throw new SmartEngineError(`Invalid protocol: ${parsed.protocol}`, 400);
     }
     if (!allowInsecure && parsed.protocol !== "https:") {
-      throw new SmartEngineError2(
+      throw new SmartEngineError(
         "HTTPS is required for secure connections. Set allowInsecure=true for local development.",
         400
       );
     }
     return parsed.origin;
   } catch (error) {
-    if (error instanceof SmartEngineError2) throw error;
-    throw new SmartEngineError2(`Invalid URL: ${url}`, 400);
+    if (error instanceof SmartEngineError) throw error;
+    throw new SmartEngineError(`Invalid URL: ${url}`, 400);
   }
 }
 
@@ -3210,178 +3363,6 @@ var MessagingClient = class {
   }
 };
 
-// src/baas/deployment/index.ts
-var DeploymentClient = class {
-  constructor(http) {
-    this.http = http;
-  }
-  http;
-  /**
-   * 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 deploy(appId, request) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(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);
-  }
-  /**
-   * 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.
-   */
-  async get(appId) {
-    return this.http.get(`/api/deployment/apps/${encodeURIComponent(appId)}`);
-  }
-  /**
-   * 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. Runtime effect (namespace teardown) lands in PR-H.
-   */
-  async delete(appId) {
-    return this.http.delete(`/api/deployment/apps/${encodeURIComponent(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`, {});
-  }
-  /**
-   * 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.
-   */
-  async getStats() {
-    return this.http.get("/api/deployment/stats");
-  }
-};
-
-// src/baas/agents/index.ts
-var AgentsClient = class {
-  constructor(http) {
-    this.http = http;
-  }
-  http;
-  /** Register a new agent */
-  async register(request) {
-    return this.http.post("/api/agents/register", request);
-  }
-  /** Get agent details */
-  async get(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}`);
-  }
-  /** List all agents */
-  async list() {
-    return this.http.get("/api/agents");
-  }
-  /** Fund an agent */
-  async fund(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/fund`, request);
-  }
-  /** Execute a trade */
-  async trade(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/trade`, request);
-  }
-  /** Withdraw funds from agent */
-  async withdraw(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/withdraw`, request);
-  }
-  /** Pause an agent */
-  async pause(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/pause`, {});
-  }
-  /** Resume a paused agent */
-  async resume(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/resume`, {});
-  }
-  /** Revoke an agent (permanent) */
-  async revoke(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/revoke`, {});
-  }
-  /** Update agent rules */
-  async updateRules(agentId, rules) {
-    return this.http.put(`/api/agents/${encodeURIComponent(agentId)}/rules`, rules);
-  }
-  /** Get agent events */
-  async getEvents(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}/events`);
-  }
-  /** Get agent balances across chains */
-  async getBalances(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}/balances`);
-  }
-  /** Approve a pending agent operation */
-  async approve(agentId, operationId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/approve/${encodeURIComponent(operationId)}`, {});
-  }
-  /** Reject a pending agent operation */
-  async reject(agentId, operationId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/reject/${encodeURIComponent(operationId)}`, {});
-  }
-};
-
 // src/baas/customer-session/index.ts
 var CustomerSessionClient = class {
   constructor(baseUrl, timeoutMs = 3e4) {
@@ -3454,8 +3435,90 @@ var CustomerSessionClient = class {
   }
 };
 
+// src/baas/rules/client.ts
+var RulesClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Publish a canonical ValidatorRules document to HCS. */
+  async publish(rule) {
+    return this.http.post("/api/rules/publish", rule);
+  }
+  /** Fetch a published rule by its HCS consensus timestamp. */
+  async get(consensusTimestamp) {
+    return this.http.get(`/api/rules/${encodeURIComponent(consensusTimestamp)}`);
+  }
+  /** List rules owned by the authenticated entity, optionally filtered by type. */
+  async listByOwner(filter) {
+    const path = filter?.type ? `/api/rules?type=${encodeURIComponent(filter.type)}` : "/api/rules";
+    return this.http.get(path);
+  }
+  /**
+   * Simulate cluster-side evaluation of an action against a rule. Either
+   * `ruleRef` (published) or `rule` (inline) must be supplied by the caller.
+   */
+  async simulate(params) {
+    return this.http.post("/api/rules/simulate", params);
+  }
+  /** Walk the version history of a published rule. */
+  async getVersionHistory(consensusTimestamp) {
+    return this.http.get(
+      `/api/rules/${encodeURIComponent(consensusTimestamp)}/versions`
+    );
+  }
+  /** Deprecate a published rule (owner-only). */
+  async deprecate(consensusTimestamp) {
+    return this.http.post(
+      `/api/rules/${encodeURIComponent(consensusTimestamp)}/deprecate`,
+      {}
+    );
+  }
+};
+
+// src/baas/entities/client.ts
+var EntitiesClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Create a canonical token entity bound to a published rule. */
+  async createToken(req) {
+    return this.http.post("/api/entities/createToken", req);
+  }
+  /** Create a canonical account entity bound to a published rule. */
+  async createAccount(req) {
+    return this.http.post("/api/entities/createAccount", req);
+  }
+  /** Create a canonical topic entity bound to a published rule. */
+  async createTopic(req) {
+    return this.http.post("/api/entities/createTopic", req);
+  }
+  /** Create a canonical agent entity bound to a published rule. */
+  async createAgent(req) {
+    return this.http.post("/api/entities/createAgent", req);
+  }
+  /**
+   * Mega-helper: build a token rule with a launchpad ModuleEntry attached,
+   * publish it, create the token, and return the combined result in one HTTP
+   * round-trip.
+   */
+  async launchpad(req) {
+    return this.http.post("/api/entities/launchpad", req);
+  }
+  /** Fetch an entity by its canonical `entityId`. */
+  async get(entityId) {
+    return this.http.get(`/api/entities/${encodeURIComponent(entityId)}`);
+  }
+  /** List entities owned by the authenticated wallet, optionally filtered by type. */
+  async listByOwner(filter) {
+    const path = filter?.type ? `/api/entities?type=${encodeURIComponent(filter.type)}` : "/api/entities";
+    return this.http.get(path);
+  }
+};
+
 // src/baas/client.ts
-var BaasClient = class {
+var BaasClient = class _BaasClient {
   hostUrl;
   pathPrefix;
   appId;
@@ -3480,6 +3543,10 @@ var BaasClient = class {
   agents;
   /** Customer→smart-app session bridge (TokenGate Face B). */
   customerSession;
+  /** Canonical validator-rules authoring surface (publish/get/list/simulate). */
+  rules;
+  /** Canonical entity authoring surface (token/account/topic/agent + launchpad). */
+  entities;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
     this.hostUrl = validateUrl2(config.hostUrl, this.allowInsecure);
@@ -3500,6 +3567,84 @@ var BaasClient = class {
     this.deployment = new DeploymentClient(this.http);
     this.agents = new AgentsClient(this.http);
     this.customerSession = new CustomerSessionClient(baseUrlWithPrefix, this.timeout);
+    this.rules = new RulesClient(this.http);
+    this.entities = new EntitiesClient(this.http);
+  }
+  /**
+   * Connect to the Smart Engines BaaS via cluster auto-discovery.
+   *
+   * Zero-config entrypoint flow:
+   *
+   *   1. Resolves the bootstrap seed list:
+   *      - `network: 'testnet' | 'mainnet'` → canonical Cloudflare-fronted
+   *        gateway via {@link KNOWN_NETWORKS}.
+   *      - `bootstrap: string[]` → explicit seed list (private deployments).
+   *   2. Fetches `GET /api/v3/discovery/clusters` from the first reachable
+   *      seed; the response carries every active cluster's gateway URL.
+   *   3. Random-picks one active cluster.
+   *   4. Returns a `BaasClient` pointed at that cluster's gatewayUrl, with
+   *      `pathPrefix: '/host'` so all BaaS sub-clients (db / storage /
+   *      functions / messaging / agents / rules / entities) route through
+   *      the gateway's `/host/*` rewrite.
+   *
+   * @example Zero-config (recommended)
+   * ```ts
+   * const baas = await BaasClient.connectToCluster({
+   *   network: 'testnet',
+   *   appId: 'app_abc',
+   * });
+   *
+   * await baas.db.insert('users', { name: 'Alice' });
+   * ```
+   *
+   * @example Custom seeds (private deployments)
+   * ```ts
+   * const baas = await BaasClient.connectToCluster({
+   *   bootstrap: ['https://gateway.my-private-net.example'],
+   *   appId: 'app_abc',
+   * });
+   * ```
+   *
+   * @throws {BaasError} `503` when no cluster is reachable via any seed.
+   * @throws {BaasError} `400` when bootstrap resolution yields an empty list
+   *   (only possible when the caller passes an empty array explicitly).
+   */
+  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,
+      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 BaasError(
+        "No active clusters available via bootstrap seeds. Check network reachability or bootstrap URLs.",
+        503
+      );
+    }
+    return new _BaasClient({
+      hostUrl: cluster.endpoints.gatewayUrl,
+      appId: config.appId,
+      appName: config.appName,
+      timeout: config.timeout,
+      allowInsecure,
+      // BaaS traffic is gateway-routed at `/host/*` by default. Callers
+      // pointing at a bare host can override with `pathPrefix: ''`.
+      pathPrefix: config.pathPrefix ?? "/host"
+    });
   }
   /** Set the app ID (for newly registered apps) */
   setAppId(appId) {
@@ -3513,6 +3658,16 @@ var BaasClient = class {
   getAppId() {
     return this.appId;
   }
+  /**
+   * Get the configured host URL. After
+   * {@link BaasClient.connectToCluster} this is the gateway URL of the
+   * cluster the SDK landed on after random-pick — useful for logging,
+   * "behind the curtain" UIs, or debugging which cluster is serving a
+   * given request.
+   */
+  getHostUrl() {
+    return this.hostUrl;
+  }
   /**
    * Get HTTP resilience health information
    * @returns Object with circuit breaker state and last error (if any)
@@ -3662,6 +3817,9 @@ function validateUrl2(url, allowInsecure = false) {
 
 // src/nestjs/smart-engine.service.ts
 var SMART_ENGINE_CONFIG = "SMART_ENGINE_CONFIG";
+var SDK_BAAS_CLIENT = "SDK_BAAS_CLIENT";
+var RULES_CLIENT = "RULES_CLIENT";
+var ENTITIES_CLIENT = "ENTITIES_CLIENT";
 exports.SmartEngineService = class SmartEngineService {
   constructor(config) {
     this.config = config;
@@ -3744,7 +3902,7 @@ exports.SmartEngineService = class SmartEngineService {
    */
   getClient() {
     if (!this.client) {
-      throw new SmartEngineError2(
+      throw new SmartEngineError(
         "SmartEngineClient not initialized. Ensure SmartEngineService is configured properly.",
         500
       );
@@ -3761,7 +3919,7 @@ exports.SmartEngineService = class SmartEngineService {
    */
   getBaasClient() {
     if (!this.baasClient) {
-      throw new SmartEngineError2(
+      throw new SmartEngineError(
         "BaasClient not initialized. Ensure SmartEngineService is configured properly.",
         500
       );
@@ -3875,9 +4033,15 @@ exports.SmartEngineModule = class SmartEngineModule {
           provide: SMART_ENGINE_CONFIG,
           useValue: config
         },
-        exports.SmartEngineService
+        exports.SmartEngineService,
+        ...this.createBaasProviders()
       ],
-      exports: [exports.SmartEngineService]
+      exports: [
+        exports.SmartEngineService,
+        SDK_BAAS_CLIENT,
+        RULES_CLIENT,
+        ENTITIES_CLIENT
+      ]
     };
   }
   /**
@@ -3893,10 +4057,48 @@ exports.SmartEngineModule = class SmartEngineModule {
       module: exports.SmartEngineModule,
       global: options.isGlobal ?? true,
       imports: options.imports || [],
-      providers: [...asyncProviders, exports.SmartEngineService],
-      exports: [exports.SmartEngineService]
+      providers: [
+        ...asyncProviders,
+        exports.SmartEngineService,
+        ...this.createBaasProviders()
+      ],
+      exports: [
+        exports.SmartEngineService,
+        SDK_BAAS_CLIENT,
+        RULES_CLIENT,
+        ENTITIES_CLIENT
+      ]
     };
   }
+  /**
+   * Build the BaaS SDK providers — the full `BaasClient` and its `rules` /
+   * `entities` sub-clients — all bound to dedicated injection tokens. Wired
+   * into both `forRoot` and `forRootAsync` so consumers can
+   * `@Inject(RULES_CLIENT) rules: RulesClient` directly.
+   */
+  static createBaasProviders() {
+    return [
+      {
+        provide: SDK_BAAS_CLIENT,
+        useFactory: (config) => new BaasClient({
+          hostUrl: config.baseUrl,
+          timeout: config.timeout,
+          allowInsecure: config.allowInsecure
+        }),
+        inject: [SMART_ENGINE_CONFIG]
+      },
+      {
+        provide: RULES_CLIENT,
+        useFactory: (baas) => baas.rules,
+        inject: [SDK_BAAS_CLIENT]
+      },
+      {
+        provide: ENTITIES_CLIENT,
+        useFactory: (baas) => baas.entities,
+        inject: [SDK_BAAS_CLIENT]
+      }
+    ];
+  }
   /**
    * Create async providers based on configuration options
    */
@@ -3941,6 +4143,12 @@ exports.SmartEngineModule = __decorateClass([
   common.Module({})
 ], exports.SmartEngineModule);
 
+exports.ENTITIES_CLIENT = ENTITIES_CLIENT;
+exports.EntitiesClient = EntitiesClient;
+exports.RULES_CLIENT = RULES_CLIENT;
+exports.RulesClient = RulesClient;
+exports.SDK_BAAS_CLIENT = SDK_BAAS_CLIENT;
 exports.SMART_ENGINE_CONFIG = SMART_ENGINE_CONFIG;
+exports.SdkBaasClient = BaasClient;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map