@hsuite/smart-engines-sdk 3.5.0 → 3.6.1

package/dist/nestjs/index.js

@@ -230,7 +230,7 @@ var CreateAccountRequestSchema = zod.z.object({
    * Smart node security mode for the account key structure.
    * - 'partial': threshold(2, [appOwnerKey, tssKeyList]) — co-control
    * - 'full': TSS KeyList only — full validator network control
-   * Default: 'full' (Arc 5 §7.5.2: 'none' removed).
+   * @defaultValue 'full'
    */
   securityMode: zod.z.enum(["partial", "full"]).default("full"),
   /**
@@ -1244,14 +1244,34 @@ function createHttpClient(config) {
       throw new SdkHttpError(`Upload error: ${err.message}`, 0, error);
     }
   }
+  let reauthInFlight = null;
+  async function withAuthRetry(path, op) {
+    try {
+      return await op();
+    } catch (error) {
+      const refreshable = !!config.onUnauthorized && !path.startsWith("/api/auth/") && error instanceof SdkHttpError && error.statusCode === 401;
+      if (!refreshable) throw error;
+      if (!reauthInFlight) {
+        reauthInFlight = Promise.resolve(config.onUnauthorized()).finally(() => {
+          reauthInFlight = null;
+        });
+      }
+      try {
+        await reauthInFlight;
+      } catch {
+        throw error;
+      }
+      return await op();
+    }
+  }
   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)),
+    post: (path, body) => withAuthRetry(path, () => request("POST", path, body)),
+    get: (path) => withAuthRetry(path, () => request("GET", path)),
+    put: (path, body) => withAuthRetry(path, () => request("PUT", path, body)),
+    patch: (path, body) => withAuthRetry(path, () => request("PATCH", path, body)),
+    delete: (path) => withAuthRetry(path, () => request("DELETE", path)),
+    getText: (path) => withAuthRetry(path, () => getText(path)),
+    upload: ((path, file, filename, metadata, fieldName) => withAuthRetry(path, () => upload(path, file, filename, metadata, fieldName))),
     setAuthToken,
     getAuthToken
   };
@@ -1637,8 +1657,8 @@ var ValidatorAuthClient = class {
    *
    * 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.
+   * Accepts both the `{ signedTransaction }` envelope and the bare-string
+   * return shapes that xrpl signer libraries expose.
    *
    * @param challenge - Challenge string from validator
    * @param wallet - XRPL Wallet instance (or compatible signer)
@@ -1863,6 +1883,40 @@ var SubscriptionClient = class {
   }
 };
 
+// src/faucet/index.ts
+var FaucetClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Request a signing challenge for a recipient address. The returned
+   * `message` must be signed by the key controlling `recipientAddress`.
+   */
+  async requestChallenge(chain, recipientAddress) {
+    return this.http.post("/faucet/hsuite/challenge", { chain, recipientAddress });
+  }
+  /**
+   * Submit a signed challenge to dispense HST. The result is a discriminated
+   * union on `status` — branch on `'dispensed' | 'trustline_required' |
+   * 'rate_limited'`. On `'trustline_required'`, set the returned trust line on
+   * the recipient and re-dispense with a fresh challenge.
+   */
+  async dispense(req) {
+    return this.http.post("/faucet/hsuite", req);
+  }
+  /**
+   * Get today's dispense status for a recipient (e.g. amount already
+   * dispensed today).
+   */
+  async getStatus(chain, recipientAddress) {
+    const params = new URLSearchParams();
+    params.append("chain", chain);
+    params.append("recipientAddress", recipientAddress);
+    return this.http.get(`/faucet/hsuite/status?${params.toString()}`);
+  }
+};
+
 // src/tss/index.ts
 var TSSClient = class {
   constructor(http) {
@@ -1870,20 +1924,29 @@ var TSSClient = class {
   }
   http;
   /**
-   * Create a multi-sig entity with TSS
+   * Create a multi-sig entity via a synchronous DKG ceremony.
+   *
+   * @param options Entity-creation parameters (chain, threshold, participants).
+   * @returns The created entity's identity (ids + group public keys).
    */
   async createEntity(options) {
     return this.http.post("/tss/entity/create", options);
   }
   /**
-   * Reshare keys when cluster membership changes.
-   * Redistributes secret shares WITHOUT changing public keys.
+   * Reshare keys when cluster membership changes. Redistributes secret shares
+   * WITHOUT changing public keys.
+   *
+   * @param request The new membership / threshold to reshare to.
+   * @returns The reshare outcome.
    */
   async reshareCluster(request) {
     return this.http.post("/tss/cluster/reshare", request);
   }
   /**
-   * Get entity details by ID
+   * Get entity details by id.
+   *
+   * @param entityId The entity id to look up.
+   * @returns The entity's details.
    */
   async getEntity(entityId) {
     return this.http.get(`/tss/entity/${encodePathParam(entityId)}`);
@@ -1892,55 +1955,71 @@ var TSSClient = class {
    * Sign a transaction using MPC.
    *
    * Routes to `POST /api/v3/tss/hedera/sign-mpc`. Only `'hedera'` is wired
-   * server-side today (see
-   * `apps/smart-validator/src/tss/tss.controller.ts:279`); other chain
-   * signing paths run via their own controllers (XRPL multisig, Polkadot
-   * MPC) and are not exposed through this sub-client. The `chain` field is
-   * carried into the request body so the validator can log + route, but
-   * any non-`'hedera'` value will 404.
+   * server-side; other chain signing paths run via their own controllers (XRPL
+   * multisig, Polkadot MPC) and are not exposed through this sub-client. The
+   * `chain` field is carried into the request body so the validator can log +
+   * route, but any non-`'hedera'` value will 404.
+   *
+   * @param request The MPC signing request; `chain` is forced to `'hedera'`.
+   * @returns The MPC signing result.
    */
   async signMPC(request) {
     const chain = "hedera";
     return this.http.post(`/tss/${chain}/sign-mpc`, { ...request, chain });
   }
   /**
-   * Get known validators and their public keys
+   * Get known validators and their public keys.
+   *
+   * @returns The validator list with public keys.
    */
   async getValidators() {
     return this.http.get("/tss/validators");
   }
   /**
-   * Force announcement of this node's public key
+   * Force announcement of this node's public key.
+   *
+   * @returns Whether the announcement was accepted, plus a status message.
    */
   async announceKey() {
     return this.http.post("/tss/announce", {});
   }
   /**
-   * Get TSS statistics
+   * Get TSS statistics.
+   *
+   * @returns Aggregate TSS statistics.
    */
   async getStats() {
     return this.http.get("/tss/stats");
   }
   /**
-   * List all TSS entities
+   * List all TSS entities.
+   *
+   * @returns The full entity list.
    */
   async listEntities() {
     return this.http.get("/tss/entities");
   }
   /**
-   * TSS health check
+   * TSS health check.
+   *
+   * @returns The TSS subsystem health report.
    */
   async getHealth() {
     return this.http.get("/tss/health");
   }
   /**
-   * List DKG ceremonies and their statistics
+   * List DKG ceremonies and their statistics.
+   *
+   * @returns The ceremony list.
    */
   async listCeremonies() {
     return this.http.get("/tss/multisig/ceremonies");
   }
   /**
-   * Get multi-sig transaction status by transaction ID
+   * Get multi-sig transaction status by transaction id.
+   *
+   * @param txId The multi-sig transaction id.
+   * @returns The current status of that transaction.
    */
   async getMultiSigStatus(txId) {
     return this.http.get(`/tss/multisig/transactions/${encodePathParam(txId)}`);
@@ -1951,6 +2030,9 @@ var TSSClient = class {
    * Server returns 202 + `{ jobId, statusUrl, status: 'pending' }` immediately;
    * the DKG ceremony runs in the background. Poll {@link getJob} until the
    * status reaches `'success'` or `'failed'`.
+   *
+   * @param options Entity-creation parameters.
+   * @returns A job descriptor (`jobId`, `statusUrl`, initial status).
    */
   async createEntityAsync(options) {
     return this.http.post("/tss/entity/create/async", options);
@@ -1958,6 +2040,9 @@ var TSSClient = class {
   /**
    * Async-job variant of {@link reshareCluster}. Returns 202 + a polling
    * descriptor; resharing runs in the background.
+   *
+   * @param request The new membership / threshold to reshare to.
+   * @returns A job descriptor to poll via {@link getJob}.
    */
   async reshareClusterAsync(request) {
     return this.http.post("/tss/cluster/reshare/async", request);
@@ -1965,6 +2050,9 @@ var TSSClient = class {
   /**
    * Poll the status of an async TSS-ceremony job kicked off via
    * {@link createEntityAsync} or {@link reshareClusterAsync}.
+   *
+   * @param jobId The job id returned by the async kickoff call.
+   * @returns The job's current status (and result once terminal).
    */
   async getJob(jobId) {
     return this.http.get(`/tss/jobs/${encodePathParam(jobId)}`);
@@ -1977,6 +2065,10 @@ var TSSClient = class {
    * Payload constraints (enforced server-side):
    *   - even-length lowercase hex
    *   - ≥32 bytes, ≤8KB
+   *
+   * @param appId The smart-app entity id to sign as.
+   * @param request The hex payload to sign.
+   * @returns The aggregate signature over the payload.
    */
   async signForApp(appId, request) {
     return this.http.post(`/tss/entity/${encodePathParam(appId)}/sign`, request);
@@ -2957,25 +3049,29 @@ var DeploymentClient = class {
     return this.http.get(`/api/deployment/apps/${encodePathParam(appId)}`);
   }
   /**
-   * Update app configuration. Runtime effect lands in PR-H.
+   * Update app configuration.
+   *
+   * @param appId - The app to update.
+   * @param updates - Partial deploy-request fields to apply.
+   * @returns The updated app info.
    */
   async update(appId, updates) {
     return this.http.put(`/api/deployment/apps/${encodePathParam(appId)}`, updates);
   }
   /**
-   * Delete an app. Runtime effect (namespace teardown) lands in PR-H.
+   * Delete an app (runtime effect: namespace teardown).
    */
   async delete(appId) {
     return this.http.delete(`/api/deployment/apps/${encodePathParam(appId)}`);
   }
   /**
-   * Suspend an app. Runtime effect (scale to zero) lands in PR-H.
+   * Suspend an app (runtime effect: scale to zero).
    */
   async suspend(appId) {
     return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/suspend`, {});
   }
   /**
-   * Resume a suspended app. Runtime effect (scale back up) lands in PR-H.
+   * Resume a suspended app (runtime effect: scale back up).
    */
   async resume(appId) {
     return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/resume`, {});
@@ -3024,7 +3120,7 @@ var DeploymentClient = class {
     return this.http.getText(`/api/deployment/apps/${encodePathParam(appId)}/metrics`);
   }
   /**
-   * Rotate the smart-app's tenant-secret KEK (ADR-011 Phase 6).
+   * Rotate the smart-app's tenant-secret KEK.
    *
    * Re-encrypts every `runtime.env` envelope at the new KEK version
    * transparently. Previous versions remain valid until explicitly
@@ -3037,7 +3133,7 @@ var DeploymentClient = class {
     );
   }
   /**
-   * Revoke a tenant-secret KEK version (ADR-011 Phase 6 emergency burn).
+   * Revoke a tenant-secret KEK version (emergency burn).
    *
    * Envelopes at the revoked version become operationally dead —
    * decryption inside the smart-app pod fails. Owner-only and
@@ -3260,6 +3356,8 @@ var SmartEngineClient = class _SmartEngineClient {
   // ========== Sub-Clients ==========
   /** Application subscription management */
   subscription;
+  /** Testnet HST faucet (challenge -> sign -> dispense) */
+  faucet;
   /** Threshold Signature Scheme — chain-agnostic MPC operations */
   tss;
   /** IPFS decentralized file storage */
@@ -3318,6 +3416,7 @@ var SmartEngineClient = class _SmartEngineClient {
       timeout: config.timeout
     });
     this.subscription = new SubscriptionClient(this.http);
+    this.faucet = new FaucetClient(this.http);
     this.tss = new TSSClient(this.http);
     this.ipfs = new IPFSClient(this.http);
     this.transactions = new TransactionsClient(this.txHttp);
@@ -3373,13 +3472,17 @@ var SmartEngineClient = class _SmartEngineClient {
     });
   }
   /**
-   * Connect to the smart-engines network with auto-discovery and authentication
+   * Connect to the smart-engines network with auto-discovery and authentication.
    *
-   * This method:
-   * 1. Discovers validators via HCS registry topic
-   * 2. Selects a random validator with API endpoint
-   * 3. Authenticates with Web3-style challenge-response
-   * 4. Returns a configured client ready to use
+   * Steps:
+   * 1. Discovers validators via the HCS registry topic.
+   * 2. Selects a random validator with an API endpoint.
+   * 3. Authenticates with Web3-style challenge-response.
+   * 4. Returns a configured client ready to use.
+   *
+   * @param config - Network, registry topic, and auth signer config.
+   * @returns The configured client, the chosen validator, and the auth session.
+   * @throws SmartEngineError 503 if no validator with an API endpoint is found.
    */
   static async connectToNetwork(config) {
     const allowInsecure = config.allowInsecure ?? false;
@@ -3416,18 +3519,22 @@ 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.
+   * Connect to the smart-engines network via the **service-registry**.
+   * 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):
+   * Resolution ladder:
    *   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.
    *
+   * @param config - Seed + auth config. See {@link ClusterConnectionConfig}.
+   * @returns The configured client, the selected cluster, and the auth session.
+   * @throws SmartEngineError 400 if neither `bootstrap` nor `network` is given.
+   * @throws SmartEngineError 503 if no active cluster can be reached.
+   *
    * @example Zero-config (recommended for smart-app callers)
    * ```ts
    * const { client, cluster, session } = await SmartEngineClient.connectToCluster({
@@ -3556,17 +3663,11 @@ var SmartEngineClient = class _SmartEngineClient {
     return this.http.post("/tokens/mint", validated);
   }
   /**
-   * Get token information.
+   * Get token information for a token on the given chain.
    *
-   * Route `GET /api/v3/tokens/:chain/:tokenId` is registered twice on the
-   * validator: by `ValidatorController` at
-   * `apps/smart-validator/src/validator.controller.ts:497` and by
-   * `TokenMigrationController` at
-   * `apps/smart-validator/src/token-migration/token-migration.controller.ts:173`.
-   * Nest resolves routes in `controllers: [...]` order — `ValidatorController`
-   * is registered first (`apps/smart-validator/src/smart-validator.module.ts:1222`),
-   * so `multiChain.getTokenInfo(chain, tokenId)` wins and the
-   * token-migration handler is unreachable via this path.
+   * @param chain - Chain identifier (e.g. `'hedera'`, `'xrpl'`).
+   * @param tokenId - Chain-native token identifier.
+   * @returns Token metadata and supply information.
    */
   async getTokenInfo(chain, tokenId) {
     return this.http.get(`/tokens/${encodePathParam(chain)}/${encodePathParam(tokenId)}`);
@@ -3795,8 +3896,7 @@ var DomainsClient = class {
   }
   /**
    * Generate a verification token. Server accepts one of `dns-txt`,
-   * `dns-cname`, `http-file`, `email` (see controller Swagger enum at
-   * `apps/smart-gateway/src/domains/domains.controller.ts:226-234`).
+   * `dns-cname`, `http-file`, `email`.
    */
   async generateVerificationToken(domain, method) {
     return this.http.post(`/domains/${encodePathParam(domain)}/verification`, { method });
@@ -3920,10 +4020,8 @@ var HealthClient = class {
   }
   http;
   /**
-   * Per-cluster aggregate health probe. Wraps
-   * `GET /api/v3/cluster/health` — see
-   * `apps/smart-gateway/src/health/health.controller.ts:213-263`. Returns
-   * local validator + host + genesis state in a single payload.
+   * Per-cluster aggregate health probe. Wraps `GET /api/v3/cluster/health`.
+   * Returns local validator + host + genesis state in a single payload.
    */
   async getCluster() {
     return this.http.get("/cluster/health");
@@ -3967,11 +4065,28 @@ var SmartGatewayClient = class {
     return this.http.get("/status");
   }
   /**
-   * Check gateway readiness. Returns either `{ status: 'ready', ... }` with
-   * a verified host count or `{ status: 'not_ready', reason, ... }`.
+   * Check gateway readiness. Resolves to either `{ status: 'ready', ... }`
+   * with a verified host count or `{ status: 'not_ready', reason, ... }`.
+   *
+   * NOTE: `/api/v3/ready` returns **HTTP 503** when not ready (so load
+   * balancers / k8s probes drain the origin). This method unwraps that 503's
+   * body and still RESOLVES to a `GatewayReadinessResponse` — it does not
+   * throw for a not-ready gateway. Genuine errors (non-readiness 503s, 5xx,
+   * network) still throw.
    */
   async getReadiness() {
-    return this.http.get("/ready");
+    try {
+      return await this.http.get("/ready");
+    } catch (err) {
+      if (err instanceof SdkHttpError && err.statusCode === 503) {
+        const d = err.details;
+        const body = d?.context ?? d;
+        if (body?.status === "not_ready") {
+          return body;
+        }
+      }
+      throw err;
+    }
   }
   /** Check gateway liveness. */
   async getLiveness() {
@@ -4156,23 +4271,11 @@ var StorageClient = class {
     return this.http.delete(`/api/storage/${encodePathParam(appId)}/${encodePathParam(cid)}`);
   }
   /**
-   * Get file info.
-   *
-   * @deprecated The smart-host storage controller does not expose a
-   * 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; **scheduled for removal in 4.0.0**.
-   */
-  async getFile(cid) {
-    return this.download(cid);
-  }
-  /**
-   * List all files for the app
+   * List all files for the app.
    *
-   * @param pagination.offset Server reads `offset`; the legacy `skip`
-   *   option was a client-only synonym that the server silently ignored.
-   *   Use `offset` going forward.
+   * @param pagination - Optional `limit` and `offset` (the server reads
+   *   `offset` for pagination).
+   * @returns The file list and total count.
    */
   async listFiles(pagination) {
     const appId = this.getAppId();
@@ -4553,6 +4656,13 @@ var BaasClient = class _BaasClient {
   http;
   /** Last HTTP error (for getHttpHealth) */
   lastHttpError;
+  /**
+   * Auth options from the last {@link authenticate} call, retained so the
+   * client can transparently re-authenticate when the session token expires
+   * (the http client invokes {@link reauthenticate} on a 401). Undefined until
+   * the first successful authenticate.
+   */
+  authContext;
   // ========== Sub-Clients ==========
   /** Trustless database with state proofs and Merkle verification */
   db;
@@ -4582,7 +4692,11 @@ var BaasClient = class _BaasClient {
     const baseUrlWithPrefix = this.pathPrefix ? this.hostUrl.replace(/\/$/, "") + this.pathPrefix : this.hostUrl;
     this.http = createHttpClient({
       baseUrl: baseUrlWithPrefix,
-      timeout: this.timeout
+      timeout: this.timeout,
+      // Transparent session refresh: on a 401, re-run the challenge-response
+      // with the retained signer and retry once. No-op until authenticate() has
+      // been called (authContext set). Excludes /api/auth/* (see http client).
+      onUnauthorized: () => this.reauthenticate()
     });
     const getAppId = () => this.requireAppId();
     this.db = new DatabaseClient(this.http, getAppId);
@@ -4718,6 +4832,7 @@ var BaasClient = class _BaasClient {
    */
   async authenticate(options) {
     const { chain, walletAddress, publicKey, signFn } = options;
+    this.authContext = options;
     let challenge;
     try {
       challenge = await this.http.post("/api/auth/challenge", {
@@ -4742,6 +4857,30 @@ var BaasClient = class _BaasClient {
     this.http.setAuthToken(result.token);
     return result;
   }
+  /**
+   * Re-run the challenge-response with the retained signer to mint a fresh
+   * session token. Invoked by the http client's `onUnauthorized` hook when a
+   * request 401s because the token expired — so long-lived clients keep working
+   * without the caller re-implementing refresh. No-op if {@link authenticate}
+   * was never called. The `/api/auth/*` calls below are excluded from the http
+   * client's 401-retry path, so this can never recurse.
+   */
+  async reauthenticate() {
+    const ctx = this.authContext;
+    if (!ctx) return;
+    const challenge = await this.http.post("/api/auth/challenge", {
+      chain: ctx.chain,
+      walletAddress: ctx.walletAddress,
+      appId: this.appId
+    });
+    const signature = await ctx.signFn(challenge.message);
+    const result = await this.http.post("/api/auth/verify", {
+      challengeId: challenge.challengeId,
+      signature,
+      publicKey: ctx.publicKey
+    });
+    this.http.setAuthToken(result.token);
+  }
   /** Validate the current session */
   async validateSession() {
     this.requireAuth();
@@ -5012,10 +5151,12 @@ exports.SmartEngineService = __decorateClass([
 // src/nestjs/smart-engine.module.ts
 exports.SmartEngineModule = class SmartEngineModule {
   /**
-   * Configure the module with static configuration
+   * Configure the module with static configuration.
    *
-   * @param config - SmartEngine service configuration
-   * @param isGlobal - Whether to make the module global (default: true)
+   * @param config - SmartEngine service configuration.
+   * @param isGlobal - Whether to make the module global. @defaultValue true
+   * @returns A `DynamicModule` exporting {@link SmartEngineService} plus the
+   *   BaaS / rules / entities clients.
    */
   static forRoot(config, isGlobal = true) {
     return {
@@ -5038,11 +5179,15 @@ exports.SmartEngineModule = class SmartEngineModule {
     };
   }
   /**
-   * Configure the module with async configuration
+   * Configure the module with async configuration.
    *
    * Supports factory functions, configuration classes, and existing providers.
    *
-   * @param options - Async configuration options
+   * @param options - Async configuration options.
+   * @returns A `DynamicModule` exporting {@link SmartEngineService} plus the
+   *   BaaS / rules / entities clients.
+   * @throws Error if `options` provides none of `useFactory`, `useClass`, or
+   *   `useExisting`.
    */
   static forRootAsync(options) {
     const asyncProviders = this.createAsyncProviders(options);