@hsuite/smart-engines-sdk 3.13.1 → 4.0.0

package/dist/nestjs/index.js

@@ -1021,9 +1021,11 @@ var ClusterDiscoveryClient = class {
   }
   /**
    * 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.
+   * active cluster. Feed this to `BaasClient` (the host BaaS tier) — e.g.
+   * `new BaasClient({ hostUrl, pathPrefix: '/host' })` or
+   * `BaasClient.connectToCluster({ network })`. Do NOT feed it to
+   * `SmartEngineClient`: that client's raw `/api/v3/*` tier is un-ingressed at
+   * the gateway and will 404 (it requires an explicit `validatorBaseUrl`).
    */
   async getRandomGatewayUrl(forceRefresh = false) {
     const cluster = await this.getRandomCluster(forceRefresh);
@@ -1149,6 +1151,13 @@ var SdkHttpError = class extends Error {
   }
   statusCode;
   details;
+  /**
+   * True for transient failures worth retrying: a 5xx, a 429 (rate limit), a 408
+   * (timeout), or a 0 (network/abort). Deterministic 4xx client errors are not.
+   */
+  get isRetryable() {
+    return this.statusCode === 0 || this.statusCode === 408 || this.statusCode === 429 || this.statusCode >= 500;
+  }
 };
 function createHttpClient(config) {
   const timeout = config.timeout ?? 3e4;
@@ -1166,6 +1175,10 @@ function createHttpClient(config) {
     if (opts?.customerToken) {
       headers["X-Customer-Session-Token"] = opts.customerToken;
     }
+    if (opts?.onBehalfOf) {
+      headers["Authorization"] = `Bearer ${opts.onBehalfOf}`;
+      headers["X-Customer-Session-Claim"] = opts.onBehalfOf;
+    }
     if (opts?.headers) {
       Object.assign(headers, opts.headers);
     }
@@ -1273,6 +1286,41 @@ function createHttpClient(config) {
       throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
     }
   }
+  async function getBinaryWithMeta(path, opts) {
+    const url = `${config.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: getHeaders(void 0, opts),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errBody = await response.json().catch(() => ({}));
+        throw new SdkHttpError(
+          errBody.message || `API error: ${response.status} ${response.statusText}`,
+          response.status,
+          errBody
+        );
+      }
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      const contentType = response.headers.get("content-type") ?? void 0;
+      const disposition = response.headers.get("content-disposition") ?? "";
+      const match = /filename\*?=(?:UTF-8'')?"?([^"\n;]+)"?/i.exec(disposition);
+      const filename = match ? decodeURIComponent(match[1].trim()) : void 0;
+      return { bytes, contentType, filename };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof SdkHttpError) throw error;
+      const err = error;
+      if (err.name === "AbortError") {
+        throw new SdkHttpError("Request timeout", 408);
+      }
+      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
+    }
+  }
   async function upload(path, file, filename, metadata, fieldName = "file", opts) {
     const url = `${config.baseUrl}${path}`;
     const controller = new AbortController();
@@ -1296,6 +1344,10 @@ function createHttpClient(config) {
       if (opts?.customerToken) {
         headers["X-Customer-Session-Token"] = opts.customerToken;
       }
+      if (opts?.onBehalfOf) {
+        headers["Authorization"] = `Bearer ${opts.onBehalfOf}`;
+        headers["X-Customer-Session-Claim"] = opts.onBehalfOf;
+      }
       if (opts?.headers) {
         Object.assign(headers, opts.headers);
       }
@@ -1353,6 +1405,7 @@ function createHttpClient(config) {
     delete: (path, opts) => withAuthRetry(path, () => request("DELETE", path, void 0, opts)),
     getText: (path, opts) => withAuthRetry(path, () => getText(path, opts)),
     getBinary: (path, opts) => withAuthRetry(path, () => getBinary(path, opts)),
+    getBinaryWithMeta: (path, opts) => withAuthRetry(path, () => getBinaryWithMeta(path, opts)),
     upload: ((path, file, filename, metadata, fieldName, opts) => withAuthRetry(path, () => upload(path, file, filename, metadata, fieldName, opts))),
     setAuthToken,
     getAuthToken
@@ -2992,9 +3045,12 @@ var AgentsClient = class {
     return this.http.get("/api/v3/baas/agents", opts);
   }
   /**
-   * Fund agent treasury (owner-only). Returns a
+   * Fund agent treasury (owner-only). Normally returns a
    * `PreparedTransactionResponse` wrapped in a `success: true` envelope —
-   * the caller is expected to sign and submit the prepared bytes.
+   * the caller is expected to sign and submit the prepared bytes. When the
+   * amount trips an approval-required rule the host instead returns an
+   * {@link AgentPendingApprovalResponse}; discriminate with
+   * {@link isAgentFundPending}.
    */
   async fund(agentId, request, opts) {
     return this.http.post(`/api/v3/baas/agents/${encodePathParam(agentId)}/fund`, request, opts);
@@ -3033,6 +3089,14 @@ var AgentsClient = class {
   async revoke(agentId, opts) {
     return this.http.post(`/api/v3/baas/agents/${encodePathParam(agentId)}/revoke`, {}, opts);
   }
+  /**
+   * Get an agent's certification snapshot (identity, rule refs, BLS group key,
+   * and recent on-chain activity). A 404 throws `SdkHttpError` via `http.get`
+   * — parity with {@link get}.
+   */
+  async certification(agentId, opts) {
+    return this.http.get(`/api/v3/baas/agents/${encodePathParam(agentId)}/certification`, opts);
+  }
   /**
    * Update agent rules.
    *
@@ -3541,7 +3605,7 @@ var SmartEngineClient = class _SmartEngineClient {
   discovery;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
-    this.baseUrl = validateClientUrl(config.baseUrl, this.allowInsecure);
+    this.baseUrl = validateClientUrl(config.validatorBaseUrl, this.allowInsecure);
     this.http = createHttpClient({
       baseUrl: `${this.baseUrl}/api/v3`,
       apiKey: config.apiKey,
@@ -3603,7 +3667,7 @@ var SmartEngineClient = class _SmartEngineClient {
     const timeoutRaw = env["REQUEST_TIMEOUT"];
     const timeout = timeoutRaw ? Number.parseInt(timeoutRaw, 10) : void 0;
     return new _SmartEngineClient({
-      baseUrl,
+      validatorBaseUrl: baseUrl,
       apiKey: env["VALIDATOR_API_KEY"],
       authToken: env["APP_TOKEN"],
       allowInsecure: env["ALLOW_INSECURE"] === "true",
@@ -3651,90 +3715,21 @@ var SmartEngineClient = class _SmartEngineClient {
       config.metadata
     );
     const client = new _SmartEngineClient({
-      baseUrl: validatorUrl,
+      validatorBaseUrl: validatorUrl,
       authToken: session.token,
       allowInsecure
     });
     return { client, validator, session };
   }
-  /**
-   * 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.
-   *
-   * 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({
-   *   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'],
-   *   chain: 'xrpl',
-   *   address: '...',
-   *   publicKey: '...',
-   *   signFn: async (challenge) => sign(challenge),
-   * });
-   * ```
-   */
-  static async connectToCluster(config) {
-    const allowInsecure = config.allowInsecure ?? false;
-    const resolved = await resolveClusterEndpoint({
-      bootstrap: config.bootstrap,
-      network: config.network,
-      allowInsecure,
-      trustAnchor: config.trustAnchor
-    });
-    if (!resolved.ok) {
-      if (resolved.reason === "no-seeds") {
-        throw new SmartEngineError(
-          "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
-          400
-        );
-      }
-      throw new SmartEngineError(
-        "No active clusters available via bootstrap seeds. Check bootstrap URLs and network reachability.",
-        503
-      );
-    }
-    const cluster = resolved.cluster;
-    const gatewayUrl = cluster.endpoints.gatewayUrl;
-    validateClientUrl(gatewayUrl, allowInsecure);
-    const auth = new ValidatorAuthClient({ security: { allowInsecure } });
-    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 };
-  }
+  // NOTE (SDK 4.0 type-fence): the former `SmartEngineClient.connectToCluster`
+  // was REMOVED. It resolved a cluster's `gatewayUrl` and fed it into
+  // `new SmartEngineClient({ baseUrl: gatewayUrl })` — a gateway-pointed
+  // validator-direct client whose raw `/api/v3/*` calls 404 (the raw tier is
+  // un-ingressed at the gateway). That was the footgun. To reach web3 through a
+  // cluster use `BaasClient.connectToCluster({ network })` (the host BaaS tier);
+  // for an explicit in-cluster validator origin use `new SmartEngineClient({
+  // validatorBaseUrl })` or `connectToNetwork` (which resolves a real validator
+  // `apiEndpoint` from the HCS registry, never a gateway URL).
   /** Get the current validator URL */
   getBaseUrl() {
     return this.baseUrl;
@@ -4406,6 +4401,20 @@ var StorageClient = class {
     const appId = this.getAppId();
     return this.http.getBinary(`/api/v3/baas/storage/${encodePathParam(appId)}/download/${encodePathParam(cid)}`, opts);
   }
+  /**
+   * Download a file by CID WITH its response metadata — the raw bytes plus the
+   * host-supplied `contentType` (derived from the stored file's metadata) and,
+   * when present, the `filename`. Use this instead of {@link download} when the
+   * caller must echo the content-type back to its own client; a bytes-only
+   * download cannot recover it.
+   */
+  async downloadWithMeta(cid, opts) {
+    const appId = this.getAppId();
+    return this.http.getBinaryWithMeta(
+      `/api/v3/baas/storage/${encodePathParam(appId)}/download/${encodePathParam(cid)}`,
+      opts
+    );
+  }
   /**
    * Get file metadata
    */
@@ -4528,6 +4537,16 @@ var FunctionsClient = class {
       opts
     );
   }
+  /**
+   * Get a function's source code
+   */
+  async getCode(functionId, opts) {
+    const appId = this.getAppId();
+    return this.http.get(
+      `/api/v3/baas/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}/code`,
+      opts
+    );
+  }
   /**
    * Update a function
    */
@@ -5109,6 +5128,44 @@ var EntitiesClient = class _EntitiesClient {
   async createAgent(req) {
     return this.http.post("/api/v3/baas/entities/createAgent", req);
   }
+  /**
+   * PREPARE half of the payer-funded agent-create flow.
+   *
+   * POSTs `/api/v3/baas/entities/prepare-create` with `entityType: 'agent'`. The cluster
+   * runs the per-entity DKG (persists the binding, submits nothing on-chain) and
+   * returns the unsigned payer-funding `Payment`(s) the caller signs + submits with
+   * their own wallet — mirroring `prepareCreateAccount`. The agent's primary chain
+   * is relayed as `chain` (the generic prepare/execute DTO key) so the host's
+   * chain-bound preparer runs; `name` / `agentType` / `ruleRef` ride along.
+   */
+  async prepareCreateAgent(req) {
+    const { primaryChain, ...rest } = req;
+    return this.http.post("/api/v3/baas/entities/prepare-create", {
+      entityType: "agent",
+      chain: primaryChain,
+      ...rest
+    });
+  }
+  /**
+   * EXECUTE half of the payer-funded agent-create flow.
+   *
+   * POSTs `/api/v3/baas/entities/execute-create` with `entityType: 'agent'`. The entity
+   * already exists (its DKG ran during prepare); pass `signedFundingBlob` for the
+   * validator to submit the payer's signed funding tx (XRPL/Stellar account-model
+   * relay), or omit it when the caller already submitted the funding tx themselves.
+   * `createTxId` is the Hedera receipt thread (the prepared create's
+   * `transactionId`); ignored for non-Hedera chains. Mirrors
+   * `executeCreateAccount` but tags `entityType: 'agent'`.
+   */
+  async executeCreateAgent(req) {
+    const { createTxId, signedFundingBlob, ...rest } = req;
+    return this.http.post("/api/v3/baas/entities/execute-create", {
+      ...rest,
+      ...createTxId !== void 0 ? { createTxId } : {},
+      ...signedFundingBlob !== void 0 ? { signedFundingBlob } : {},
+      entityType: "agent"
+    });
+  }
   /**
    * Mega-helper: build a token rule with a launchpad ModuleEntry attached,
    * publish it, create the token, and return the combined result in one HTTP
@@ -5126,6 +5183,96 @@ var EntitiesClient = class _EntitiesClient {
     const path = filter?.type ? `/api/v3/baas/entities?type=${encodeURIComponent(filter.type)}` : "/api/v3/baas/entities";
     return this.http.get(path);
   }
+  // ─── Value-movement (prepare-bytes only) ──────────────────────────────────
+  //
+  // Each method POSTs the host's entity-scoped value-movement route. The entity
+  // is the source / treasury / authority + fee-payer (resolved server-side from
+  // the entity record — never the body), so a caller can never name a foreign
+  // payer or drain another account. The host authorises the call (session
+  // caller identity + `loadOwnedEntity` ownership), delegates to the validator
+  // preparer, and returns prepared bytes for the caller to sign + submit; the
+  // host never submits and never pays. A rule-deny surfaces as an HTTP 403
+  // `rule_rejected` (use `isRuleRejected`), never as signed bytes.
+  //
+  // `opts` threads {@link HttpCallOptions} (`onBehalfOf` / `customerToken` /
+  // `headers`) so an app-as-proxy can act on behalf of an owner — the owner's
+  // Mode-1 customer-session JWT rides as both `Authorization: Bearer` and
+  // `X-Customer-Session-Claim`, exactly as `agents.execute` does.
+  /**
+   * Prepare a native or token transfer FROM an account entity.
+   *
+   * `POST /api/v3/baas/entities/:entityId/transfer`.
+   */
+  async transfer(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/transfer`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare a withdrawal FROM an account entity to a destination.
+   *
+   * `POST /api/v3/baas/entities/:entityId/withdraw`.
+   */
+  async withdraw(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/withdraw`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare a token/NFT mint whose supply authority is the account entity.
+   *
+   * `POST /api/v3/baas/entities/:entityId/mint`.
+   */
+  async mint(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/mint`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare a token/NFT burn from the account entity's treasury.
+   *
+   * `POST /api/v3/baas/entities/:entityId/burn`.
+   */
+  async burn(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/burn`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare a compliance action (pause / restrict / wipe) on a token whose
+   * compliance authority is the account entity. The body `account` is the
+   * per-account subject for restrict/wipe — never the payer.
+   *
+   * `POST /api/v3/baas/entities/:entityId/compliance`.
+   */
+  async compliance(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/compliance`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare an XRPL TrustSet authorising the account entity to hold a currency
+   * from an issuer.
+   *
+   * `POST /api/v3/baas/entities/:entityId/trustline`.
+   */
+  async trustline(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/trustline`,
+      body,
+      opts
+    );
+  }
 };
 
 // src/baas/client.ts
@@ -5136,13 +5283,6 @@ var BaasClient = class _BaasClient {
   timeout;
   allowInsecure;
   http;
-  /**
-   * Validator-routed HTTP client for the `/api/v3/transactions/*` prepare/execute
-   * surface — a SIBLING of `/host`, NOT under the `pathPrefix`. Rooted at the
-   * raw gateway/ingress origin (`hostUrl`) so transactions reach the validator
-   * even when BaaS traffic is gateway-routed at `/host/*`.
-   */
-  txHttp;
   /** Last HTTP error (for getHttpHealth) */
   lastHttpError;
   /**
@@ -5171,14 +5311,6 @@ var BaasClient = class _BaasClient {
   rules;
   /** Canonical entity authoring surface (token/account/topic/agent + launchpad). */
   entities;
-  /**
-   * Validator-routed transaction prepare/execute (sovereignty model). The
-   * prepare endpoints accept an explicit `payerAccountId` for the session-less
-   * payer path, OR carry the web3-auth session token for the JWT-wallet payer
-   * path (kept in sync with the main client's token — see {@link authenticate}).
-   * Targets `/api/v3/transactions/*`, a sibling of the `/host` BaaS surface.
-   */
-  transactions;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
     this.hostUrl = validateUrl2(config.hostUrl, this.allowInsecure);
@@ -5195,11 +5327,6 @@ var BaasClient = class _BaasClient {
       // been called (authContext set). Excludes /api/v3/{,baas/}auth/* (see http client).
       onUnauthorized: () => this.reauthenticate()
     });
-    this.txHttp = createHttpClient({
-      baseUrl: `${this.hostUrl.replace(/\/$/, "")}/api/v3/transactions`,
-      timeout: this.timeout,
-      onUnauthorized: () => this.reauthenticate()
-    });
     const getAppId = () => this.requireAppId();
     this.db = new DatabaseClient(this.http, getAppId);
     this.storage = new StorageClient(this.http, getAppId);
@@ -5210,7 +5337,6 @@ var BaasClient = class _BaasClient {
     this.customerSession = new CustomerSessionClient(baseUrlWithPrefix, this.timeout);
     this.rules = new RulesClient(this.http);
     this.entities = new EntitiesClient(this.http);
-    this.transactions = new TransactionsClient(this.txHttp);
   }
   /**
    * Connect to the Smart Engines BaaS via cluster auto-discovery.
@@ -5358,7 +5484,6 @@ var BaasClient = class _BaasClient {
       throw asBaasError(err);
     }
     this.http.setAuthToken(result.token);
-    this.txHttp.setAuthToken(result.token);
     return result;
   }
   /**
@@ -5384,7 +5509,6 @@ var BaasClient = class _BaasClient {
       publicKey: ctx.publicKey
     });
     this.http.setAuthToken(result.token);
-    this.txHttp.setAuthToken(result.token);
   }
   /** Validate the current session */
   async validateSession() {
@@ -5404,7 +5528,6 @@ var BaasClient = class _BaasClient {
       }
     }
     this.http.setAuthToken(void 0);
-    this.txHttp.setAuthToken(void 0);
   }
   // ========== HTTP Helpers ==========
   requireAuth() {
@@ -5493,10 +5616,12 @@ exports.SmartEngineService = class SmartEngineService {
    * Can be called manually if not using DI configuration
    */
   async initialize(config) {
-    this.logger.log(`Initializing SmartEngineService for ${config.baseUrl}`);
+    this.logger.log(`Initializing SmartEngineService for ${config.validatorBaseUrl}`);
     try {
       this.client = new SmartEngineClient({
-        baseUrl: config.baseUrl,
+        // SDK 4.0 validator-origin type-fence: the service config extends
+        // SmartEngineClientConfig, so it carries `validatorBaseUrl` directly.
+        validatorBaseUrl: config.validatorBaseUrl,
         apiKey: config.apiKey,
         authToken: config.authToken,
         timeout: config.timeout,
@@ -5725,7 +5850,10 @@ exports.SmartEngineModule = class SmartEngineModule {
       {
         provide: SDK_BAAS_CLIENT,
         useFactory: (config) => new BaasClient({
-          hostUrl: config.baseUrl,
+          // SDK 4.0: the service config carries a single origin field
+          // (`validatorBaseUrl`); the BaaS client uses it as its `hostUrl`,
+          // preserving the prior single-URL wiring.
+          hostUrl: config.validatorBaseUrl,
           timeout: config.timeout,
           allowInsecure: config.allowInsecure
         }),