@hsuite/smart-engines-sdk 3.2.1 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,196 @@
 # Changelog
 
+## 3.4.0 — 2026-05-31
+
+**Production-readiness arc.** Closes the audit gap identified after 3.3.0 shipped: ~55 of ~110 third-party-facing server endpoints were wrapped; this release brings coverage to ~95/110 (the remaining ~15 are intentionally internal — operator / DKG ceremony / harbor admin). SDK test suite grew from 477 → 637 (+160 tests).
+
+Shipped as 7 stacked PRs (#995, #997, #998, #999, #1000, #1002, #1003).
+
+### Breaking changes
+
+- **`baas.messaging.setPresence` / `getPresence` / `removePresence`** — signatures now take `channel` as the first argument. The previous appId-scoped paths returned 404 server-side, so behaviourally the breakage is `404 → works`.
+- **`baas.storage.listFiles`** — pagination option renamed `skip` → `offset` to match the server query-string. The previous `skip` value was silently dropped.
+- **`baas.storage.getFile`** — `@deprecated`, now forwards to `download`. The previous endpoint never resolved server-side.
+- **Gateway response types realigned** — `HealthResponse`, `GatewayStatusResponse`, `GatewayReadinessResponse`, `GatewayMetricsResponse`, `HostInfo`, `RegisterHostRequest`, `VerificationMethod`, `DnsRecordType` all rewritten to match what `apps/smart-gateway` actually returns. Compile-time errors surface latent caller bugs; previous types were fabricated.
+- **`baas.agents.fund` / `trade` / `withdraw`** — return type changed from `{ success; txId? }` to `PreparedTransactionResponse` envelope (sovereignty flow). Callers can now reach the prepared transaction bytes; previously unreachable through the declared type.
+- **`tss.signMPC`** — `chain` parameter restricted to literal `'hedera'`. Other chains were never wired server-side and silently 404'd.
+- **`Rules.module.agent`** — removed. Server retired `AgentOrganism` in Arc 6 Phase 6.5; SDK module factory was silently no-op'ing on the cluster.
+
+### Fixed — BaaS endpoint paths that 404'd in production (PR #995)
+
+`apps/smart-host` requires `:appId` in every BaaS path; the SDK omitted it on 9 methods plus used the wrong verb on one:
+
+- `storage.download` / `getMetadata` / `exists` / `getUsage` — all now correctly prefixed with `:appId`.
+- `functions.invoke` / `get` / `update` / `delete` / `getLogs` / `list` — same fix.
+- `messaging.setPresence` / `getPresence` / `removePresence` — channel-scoped per server.
+- `agents.updateRules` — verb corrected `PUT` → `PATCH`.
+- `db.listCollections` — path corrected to `/collections`.
+- `db.createCollection` / `dropCollection` — new wrappers for endpoints that lacked SDK methods.
+
+Regression spec `libs/smartengine-sdk/src/baas/endpoint-paths.spec.ts` pins every fixed URL + verb.
+
+Plumbing: `HttpClient` gained a `patch` method (previously missing) to unblock all PATCH-based endpoints across the SDK.
+
+### Added — `client.dao` (PR #998)
+
+Full typed wrapper over the ~30 endpoints registered by `apps/smart-validator/src/dao/dao.controller.ts`. The largest single missing surface from the audit.
+
+- **Lifecycle** — `create`, `list`, `get`, `getWithProposals`.
+- **Proposals** — `listProposals`, `createProposal`, `prepareProposal`, `signProposal`, `prepareVote`, `submitVote`, `vote`, `execute`, plus `getVotes` / `getResults` / `getVoteCounts` / `getVoterRecord`.
+- **Treasury** — `getTreasury`, `getTreasuryHistory`.
+- **Members** — `listMembers`, `addMember`, `removeMember`, `claimMemberNft`, `getMemberNft`.
+- **`client.dao.dashboard`** — per-user rollups (`getStats`, `getActiveProposals`, `getVoteHistory`, `getActivity`, `getPendingActions`, `getImpact`).
+
+### Added — Hedera TSS + Async TSS + NFT prepare paths (PR #999)
+
+- **`client.hedera.tss`** — six TSS-signed immediate-execute endpoints (cluster signs + submits in one round-trip): `createAccount`, `updateMemo`, `createTopic`, `submitMessage`, `createToken`, `mintToken`.
+- **`client.tss`** — async workflow: `createEntityAsync`, `reshareClusterAsync`, `getJob(jobId)`, `signForApp(appId, ...)`.
+- **`client.transactions`** — four NFT prepare paths for Polkadot pallet-nfts + Solana Metaplex: `prepareNftCollectionCreate`, `prepareNftSetMetadata`, `prepareNftCollectionSetMetadata`, `prepareNftCollectionLock`.
+- **`client.xrpl`** — `prepareAccountSetup` (two-step `SignerListSet` + `DisableMaster` for XRPL sovereignty).
+
+### Added — Six new sub-clients (PR #1000)
+
+- **`client.bridge`** — 8 cross-chain bridge endpoints (`create`, `list`, `get`, `port`, `return`, `getStatus`, `getSupply`, `listClaims`).
+- **`client.resources`** — quota / consumption / nodes: 8 endpoints (`getSummary`, `getConsumption`, `getHistory`, `getLedger`, `getStatus`, `getBreakdown`, `listNodes`, `getNode`).
+- **`client.envelope`** — `encrypt` / `decrypt` (third-party crypto utility).
+- **`client.tokens`** — token-migration: `migrate`, `listMigrations`, `getMigration`, `getMigrationsForToken`, `getDetails`. The last collides with `client.getTokenInfo` at Nest route registration; documented as a known limitation.
+- **`client.operator`** — read-only operator-funding: `getBalance`, `getTopup`.
+- **`client.subscription`** — extended with `downgrade`, `upgrade`, `cancelTierChange`, `getActiveFor`, `getUsage`, `getUsageStatus`, `getBilling`, `mintCustomer`.
+
+### Added — Rules-engine parity (PR #1002)
+
+- **8 canonical server-mirror templates** field-for-field with `libs/validator-rules-builder/src/templates`: `Rules.template.utilityToken`, `daoGovernedToken`, `soulboundNft`, `subscriptionNft`, `membershipNft`, `managedAccount`, `systemTopic`, `appTopic`. Sits alongside the existing higher-altitude composers (`fairLaunch`, `tradingAgent`, etc.) so devs pick altitude.
+- **12 fluent builder methods** on `BaseRuleBuilder`: `withLimits`, `withRateLimiter`, `withSnapshot`, `withCooldown`, `withApprovalThreshold` (canonical atoms now first-class on token/account/topic); molecule shortcuts `withSwap`, `withAirdrop`, `withVesting`, `withStreaming`, `withGovernanceModule`; plus Phase-6.6 AI atoms `withMaxTradesPerWindow` and `withRequireStructuredOutput` on `AgentRulesBuilder`.
+- **`baas.rules.simulate(req)`** confirmed present and tested against `POST /api/rules/simulate`.
+
+**Server-side follow-up required**: the 12 new molecule module types (`swap`, `airdrop`, `vesting`, `streaming`, `governance`, `max-trades-per-window`, `require-structured-output`, etc.) will **fail-closed** at the cluster until `libs/rules-engine/src/modules/builtin-modules.ts` registers them. Today only `launchpad / dex / dao / staking-pool` are registered.
+
+### Added — Discovery extras + Deployment KEK / webhook / metrics (PR #1003)
+
+- **`client.discovery`** — `listAllClusters` (full set, not just active), `getClusterByNode(nodeId)`, plus `client.discovery.platformImages` sub-namespace: `list`, `listEnvelopes`, `get`, `getVersion`, `verify`.
+- **`baas.deployment`** — `setWebhook(appId, url)` (returns per-tenant HMAC secret), `getMetrics(appId)` (Prometheus text/plain — `HttpClient.getText` plumbing added to bypass JSON.parse), `rotateKek(appId)`, `revokeKek(appId, version)` (ADR-011 Phase 6 KEK rotation surface).
+
+### Verified
+
+- `yarn jest`: 637 passing + 1 skipped = 638 total (was 477 in 3.3.0).
+- `yarn build:tsc`: clean (`tsc --skipLibCheck --declaration`).
+
+## 3.3.0 — 2026-05-29
+
+**Smart-App Rules SDK arc.** Adds a complete canonical-rule authoring surface
+so smart-app devs can compose, locally validate, publish, and reference
+canonical `ValidatorRules` from a single SDK — the prerequisite for entity
+creation since the cluster requires a `ruleRef` on every binding.
+
+No breaking changes. Bundle grows ~260 KB (vendored Zod schemas mirroring
+`libs/shared/src/dto/validator.dto.ts` + builder/composer/template factories).
+`sideEffects: false` added — tree-shaking excludes any sub-namespace a
+consumer doesn't import.
+
+### Added — `Rules` namespace (`import { Rules } from '@hsuite/smart-engines-sdk'`)
+
+- **Fluent builders** — `Rules.forToken()` / `.forAccount()` / `.forTopic()` /
+  `.forAgent()` with shared `withSecurity` / `withController` / `withOperations` /
+  `withTokenGates` / `withGovernance` / `withInvariants` / `withMetadata` /
+  `addModule` / `build()` flow. Throws `RuleBuildError` with dot-path messages
+  on schema failure.
+- **Composer factories** — 100% coverage of `libs/rules-engine`:
+  - `Rules.atom.*` — 17 atoms (timeRange, limits, permissionList, rateLimiter,
+    cooldown, approvalThreshold, approvedPairs, tradeLimit, snapshot,
+    cronSchedule, countApproval, externalEvidence, fieldValues,
+    registryReference, schemaValidation, stopLoss, workflowState)
+  - `Rules.molecule.*` — 6 molecules (tokenGate, swap, airdrop, vesting,
+    streaming, governance)
+  - `Rules.module.*` — 5 organism wrappers as canonical `ModuleEntry`
+    (launchpad, stakingPool, dao, dex, agent)
+- **Templates** — 8 one-call factories producing schema-conformant rules:
+  `Rules.template.fairLaunch`, `tieredIDO`, `simpleStaking`, `tokenDAO`,
+  `multisigDAO`, `simpleAMM`, `vestingSchedule`, `tradingAgent`.
+- **Preflight** — `Rules.validate(rule)` routes by `type` discriminator for
+  path-rich error messages (`operations.mint.enabled: Expected boolean`).
+- **Vendored Zod schemas** — `ValidatorRulesSchema`, `TokenValidatorRulesSchema`,
+  `AccountValidatorRulesSchema`, `TopicValidatorRulesSchema`,
+  `AgentValidatorRulesSchema`, plus every sub-schema (governance, invariants,
+  modules, payloadSchema, soulbound, etc.). Mirrors `libs/shared` verbatim;
+  re-vendor on schema upgrades.
+
+### Added — `BaasClient` sub-clients
+
+- **`baas.rules: RulesClient`** — publish a canonical rule and get back a
+  cluster-stamped `ruleRef`:
+  - `publish(rule)` → `{ ruleRef: { chain, topicId, consensusTimestamp } }`
+  - `get(consensusTimestamp)` → `PublishedRule`
+  - `listByOwner({ type? })` → `{ rules, count }`
+  - `simulate({ ruleRef? | rule?, action, context })` → `ValidationResult`
+  - `getVersionHistory(consensusTimestamp)` → `{ versions }`
+  - `deprecate(consensusTimestamp)` → `{ deprecated: true, consensusTimestamp }`
+- **`baas.entities: EntitiesClient`** — ruleRef-gated entity creation. The
+  cluster's mandatory creation gate enforces that every entity references a
+  published rule:
+  - `createToken({ chain, name, symbol, decimals?, initialSupply?, ruleRef, memo? })`
+  - `createAccount({ chain, ruleRef, initialBalance?, publicKey? })`
+  - `createTopic({ chain, ruleRef, memo? })`
+  - `createAgent({ primaryChain, ruleRef, name, agentType? })`
+  - `launchpad({ chain, name, symbol, launchpad })` — mega-helper: publishes
+    a token rule with a `launchpad` ModuleEntry attached + creates the token
+    entity referencing the new ruleRef. Single round-trip.
+  - `get(entityId)` → `EntityInfo`
+  - `listByOwner({ type? })` → `{ entities, count }`
+
+### Added — NestJS providers (subpath: `@hsuite/smart-engines-sdk/nestjs`)
+
+`SmartEngineModule.forRoot` / `.forRootAsync` now expose three injection
+tokens consumers can `@Inject(...)`:
+
+- `SDK_BAAS_CLIENT` — shared `BaasClient` instance
+- `RULES_CLIENT` — `RulesClient` (alias for `baasClient.rules`)
+- `ENTITIES_CLIENT` — `EntitiesClient` (alias for `baasClient.entities`)
+
+```ts
+class MyService {
+  constructor(
+    @Inject(RULES_CLIENT)    private readonly rules:    RulesClient,
+    @Inject(ENTITIES_CLIENT) private readonly entities: EntitiesClient,
+  ) {}
+}
+```
+
+`SmartEngineService` provider unchanged.
+
+### Documentation
+
+- Package README extended with a `## Rules — author + publish canonical
+  ValidatorRules` section, two new rows in the "Available clients" table,
+  and a pointer to the full developer guide.
+- Complete developer guide added at
+  `docs/developers/libs/rules-engine.md#smart-app-sdk-guide` — covers
+  authoring paths, composer reference tables, publish + entity-create
+  end-to-end flow, `baas.rules.*` + `baas.entities.*` reference, and 7
+  common pitfalls.
+
+### Cluster-side (FYI for SDK consumers — not in this package)
+
+This SDK release lights up server-side endpoints already shipped on the
+`smart-engines-multichain` cluster:
+
+- Smart-host: `POST /api/rules/publish`, `GET /api/rules/:ts`,
+  `GET /api/rules` (listByOwner), `POST /api/rules/simulate`,
+  `GET /api/rules/:ts/versions`, `POST /api/rules/:ts/deprecate`,
+  `POST /api/entities/{createToken|createAccount|createTopic|createAgent|launchpad}`,
+  `GET /api/entities/:id`, `GET /api/entities` (PRs #949, #950).
+- Smart-validator: `POST /api/v3/entities/create` wrapping
+  `EntityCreationOrchestrator.createMultisigEntity` for cluster-internal
+  service-mesh calls from smart-host (PR #956).
+
+### Build
+
+- tsup CJS bundle: `dist/index.js` 396 KB, `dist/nestjs/index.js` 326 KB,
+  `dist/pqc-verify/index.js` 8 KB.
+- `dts-bundle-generator` outputs preserved for all three subpaths.
+- `sideEffects: false` declared so consumers can tree-shake unused
+  sub-namespaces (`baas.rules` excludable if you don't use canonical rules,
+  etc.).
+
 ## 3.2.1 — 2026-05-16
 
 **Documentation-only fix.** No runtime behavior change.

package/README.md

@@ -88,6 +88,8 @@ from the dev wallet used to authenticate.
 | Client | Purpose |
 |---|---|
 | `BaasClient` | Authentication + database + storage + functions + messaging + deployment + agents |
+| `baas.rules.*` | Publish / get / list / simulate / deprecate canonical `ValidatorRules` documents on HCS |
+| `baas.entities.*` | Create canonical token / account / topic / agent entities (plus launchpad mega-helper), each bound to a published `ruleRef` |
 | `SmartEngineClient` | Chain operations: account create, token create / mint / burn / freeze / wipe, transfers, HCS topics, TSS, IPFS |
 | `SmartGatewayClient` | Gateway operations: routing, domains, DNS |
 | `ValidatorAuthClient` | Standalone Web3 challenge-response auth (lower-level than `BaasClient.authenticate`) |
@@ -100,6 +102,55 @@ the cluster gateway. Set `pathPrefix: ''` for direct host access.
 
 ---
 
+## Rules — author + publish canonical ValidatorRules
+
+`ValidatorRules` are the canonical, HCS-pinned policy documents the cluster
+quorum evaluates before signing any entity action (mint, burn, transfer,
+trade, …). Smart-apps author rules locally (via templates or a fluent
+builder), publish them to HCS via `baas.rules.publish`, and bind the
+returned `ruleRef` into the entity at creation time via `baas.entities.*`.
+Every action against the entity is then rules-checked + TSS-signed.
+
+```ts
+import { BaasClient, Rules } from '@hsuite/smart-engines-sdk';
+
+// Template — opinionated fair-launch token with all knobs pre-set.
+const rule = Rules.template.fairLaunch({
+  maxSupply: '1000000000',
+  mintWindow: { startsAt: '2026-06-01T00:00:00Z', endsAt: '2026-06-08T00:00:00Z' },
+});
+
+const { ruleRef } = await baas.rules.publish(rule);
+
+const token = await baas.entities.createToken({
+  chain: 'hedera',
+  name: 'Fair Launch Token',
+  symbol: 'FAIR',
+  decimals: 6,
+  ruleRef,
+});
+```
+
+```ts
+// Fluent builder — when you want to compose the rule yourself.
+const rule = Rules.forToken()
+  .withSecurity('full')                            // 'none' | 'partial' | 'full'
+  .withOperations({
+    mint: { enabled: true, limits: { dailyLimit: '1000000' } },
+    burn: { enabled: true },
+  })
+  .withInvariants({ maxSupply: '1000000000' })
+  .build();
+
+const { ruleRef } = await baas.rules.publish(rule);
+const sim = await baas.rules.simulate({ ruleRef, action: 'mint', context: { amount: '500' } });
+// sim.isValid === true | false (+ reason)
+```
+
+Full reference: [Smart-App SDK Guide](../../docs/developers/libs/rules-engine.md#smart-app-sdk-guide)
+
+---
+
 ## BaaS sub-clients
 
 Once authenticated, every BaaS sub-client is reachable from a single