@hsuite/smart-engines-sdk 3.14.0 → 4.1.0

package/dist/nestjs/index.d.ts

@@ -1619,19 +1619,6 @@ export interface ValidatorInfo {
 	registeredAt: string;
 	messageType?: "validator.join" | "validator.leave" | "validator.update";
 }
-export interface ClusterEndpointsView {
-	clusterId: string;
-	gatewayUrl: string;
-	harborUrl?: string;
-	natsUrl?: string;
-	publicIp?: string;
-	region?: string;
-}
-export interface ClusterInfo {
-	clusterId: string;
-	endpoints: ClusterEndpointsView;
-	nodeIds: string[];
-}
 export type HttpCallOptions = {
 	customerToken?: string;
 	onBehalfOf?: string;
@@ -3353,6 +3340,7 @@ export type AgentRegisterRequest = {
 	description?: string;
 	capabilities: string[];
 	rules: AgentRules;
+	primaryChain?: string;
 	fundingConfig?: {
 		chain: string;
 		maxAmount: string;
@@ -4168,7 +4156,7 @@ declare class OperatorClient {
 	getTopup(chain: OperatorChain, accountId: string): Promise<OperatorTopUpResponse>;
 }
 export interface SmartEngineClientConfig {
-	baseUrl: string;
+	validatorBaseUrl: string;
 	apiKey?: string;
 	authToken?: string;
 	timeout?: number;
@@ -4188,35 +4176,6 @@ export interface NetworkConnectionConfig {
 	mirrorNodeUrl?: string;
 	allowInsecure?: boolean;
 }
-export interface ClusterConnectionAuth {
-	chain: AuthChain;
-	address: string;
-	publicKey: string;
-	signFn: (challenge: string) => string | Promise<string>;
-	metadata?: {
-		appId?: string;
-		appName?: string;
-	};
-	trustAnchor?: {
-		network: "mainnet" | "testnet" | "previewnet";
-		registryTopicId: string;
-		mirrorNodeUrl?: string;
-	};
-	allowInsecure?: boolean;
-}
-export type ClusterConnectionSeed = {
-	bootstrap: string[];
-	network?: never;
-} | {
-	bootstrap?: never;
-	network: NetworkName;
-};
-export type ClusterConnectionConfig = ClusterConnectionSeed & ClusterConnectionAuth;
-export interface ClusterConnectionResult {
-	client: SmartEngineClient;
-	cluster: ClusterInfo;
-	session: AuthenticateResponse;
-}
 export interface NetworkConnectionResult {
 	client: SmartEngineClient;
 	validator: ValidatorInfo;
@@ -4254,7 +4213,6 @@ declare class SmartEngineClient {
 	constructor(config: SmartEngineClientConfig);
 	static fromEnv(env: Record<string, string | undefined>): SmartEngineClient;
 	static connectToNetwork(config: NetworkConnectionConfig): Promise<NetworkConnectionResult>;
-	static connectToCluster(config: ClusterConnectionConfig): Promise<ClusterConnectionResult>;
 	getBaseUrl(): string;
 	isAuthenticated(): boolean;
 	getHttpHealth(): {
@@ -12477,6 +12435,56 @@ export type LaunchpadEntityResult = {
 	tokenId: string;
 	chainAccounts: Record<string, string>;
 };
+export type TransferEntityRequest = {
+	chain: ChainType;
+	to: string;
+	amount: string;
+	tokenId?: string;
+	memo?: string;
+};
+export type WithdrawEntityRequest = {
+	chain: ChainType;
+	destination: string;
+	amount: string;
+	tokenId?: string;
+	memo?: string;
+};
+export type MintEntityRequest = {
+	chain: ChainType;
+	tokenId: string;
+	amount: string;
+	memo?: string;
+};
+export type BurnEntityRequest = {
+	chain: ChainType;
+	tokenId: string;
+	amount: string;
+	memo?: string;
+};
+export type ComplianceAction = "pause" | "restrict" | "wipe";
+export type ComplianceEntityRequest = {
+	action: ComplianceAction;
+	chain: ChainType;
+	tokenId: string;
+	account?: string;
+	amount?: string;
+	memo?: string;
+};
+export type TrustlineEntityRequest = {
+	chain: ChainType;
+	currency: string;
+	issuerAddress: string;
+	limit?: string;
+};
+export type PreparedEntityTransactionResult = {
+	chain: string;
+	transactionId: string;
+	transactionBytes: string;
+	transactionType?: string;
+	payerAccountId?: string;
+	expiresAt?: string;
+	metadata?: Record<string, unknown>;
+};
 export declare class EntitiesClient {
 	private readonly http;
 	constructor(http: HttpClient);
@@ -12521,6 +12529,12 @@ export declare class EntitiesClient {
 	launchpad(req: LaunchpadEntityRequest): Promise<LaunchpadEntityResult>;
 	get(entityId: string): Promise<EntityInfo>;
 	listByOwner(filter?: ListEntitiesFilter): Promise<ListEntitiesResponse>;
+	transfer(entityId: string, body: TransferEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	withdraw(entityId: string, body: WithdrawEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	mint(entityId: string, body: MintEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	burn(entityId: string, body: BurnEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	compliance(entityId: string, body: ComplianceEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	trustline(entityId: string, body: TrustlineEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
 }
 export type AuthenticateOptions = {
 	chain: BaasSupportedChain;
@@ -12554,7 +12568,6 @@ declare class BaasClient {
 	private readonly timeout;
 	private readonly allowInsecure;
 	private readonly http;
-	private readonly txHttp;
 	private lastHttpError?;
 	private authContext?;
 	readonly db: DatabaseClient;
@@ -12566,7 +12579,6 @@ declare class BaasClient {
 	readonly customerSession: CustomerSessionClient;
 	readonly rules: RulesClient;
 	readonly entities: EntitiesClient;
-	readonly transactions: TransactionsClient;
 	constructor(config: BaasClientConfig);
 	static connectToCluster(config: BaasConnectToClusterConfig): Promise<BaasClient>;
 	setAppId(appId: string): void;

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);
@@ -3603,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,
@@ -3665,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",
@@ -3713,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;
@@ -5250,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
@@ -5260,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;
   /**
@@ -5295,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);
@@ -5319,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);
@@ -5334,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.
@@ -5482,7 +5484,6 @@ var BaasClient = class _BaasClient {
       throw asBaasError(err);
     }
     this.http.setAuthToken(result.token);
-    this.txHttp.setAuthToken(result.token);
     return result;
   }
   /**
@@ -5508,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() {
@@ -5528,7 +5528,6 @@ var BaasClient = class _BaasClient {
       }
     }
     this.http.setAuthToken(void 0);
-    this.txHttp.setAuthToken(void 0);
   }
   // ========== HTTP Helpers ==========
   requireAuth() {
@@ -5617,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,
@@ -5849,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
         }),