@hsuite/smart-engines-sdk 3.0.1 → 3.0.3

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 3.2.1 — 2026-05-16
+
+**Documentation-only fix.** No runtime behavior change.
+
+### Fixed
+- `DeploymentClient.init` JSDoc and `BaasInitResponse` type docs no longer
+  describe the registry as DOCR. The runtime arc routes pushes through a
+  per-tenant Harbor project (`hsuite-customers-<appId>`), and the credentials
+  returned in `registry.{server, username, password, repository}` are an
+  ephemeral project-scoped robot account whose secret is single-use and not
+  persisted server-side. README example aligned with the same wording.
+
+## 3.2.0 — undocumented (PR-A → PR-I, 2026-05-12 → 2026-05-13)
+
+Smart-app runtime arc surface — added `DeploymentClient` with the full
+init → push → uploadFrontend → deploy flow plus lifecycle (suspend/
+resume/update/rollback/delete) and ownership-gated metrics. See PRs
+#516 (PR-A), #523 (PR-C), and #530 (PR-H) for details.
+
+## 3.1.0 — undocumented (2026-05-12)
+
+Added `CustomerSessionClient` for NFT-gated customer→smart-app auth (PR #496).
+
+## 3.0.2 — undocumented (2026-05-12)
+
+Dropped `nestjs` re-exports from the root entry to keep tree-shaking clean for
+non-Nest consumers (PR #494).
+
 ## 3.0.0 — 2026-05-11
 
 **First publishable release.**

package/README.md

@@ -52,14 +52,24 @@ await baas.authenticate({
   },
 });
 
-// 4. Register a free_testnet smart-app (no HSUITE deposit on testnet; cluster runs DKG)
-const app = await baas.register({
-  name: 'My Smart App',
+// 4. Initialise a free_testnet smart-app via the four-step deploy flow
+//    (init → docker push → optional uploadFrontend → deploy). `init` runs
+//    the per-entity DKG ceremony on the cluster and returns the DKG entityId
+//    as `appId`, plus ephemeral push credentials for the cluster's per-tenant
+//    Harbor project (single-use secret — not persisted server-side).
+const init = await baas.deployment.init({
+  name: 'my-smart-app',
+  port: 3000,
   services: ['database', 'storage', 'messaging', 'functions'],
 });
 
-console.log(`Registered smart-app ${app.appId} — status: ${app.status}`);
-baas.setAppId(app.appId);
+console.log(`Allocated smart-app ${init.appId}`);
+console.log(`Push to: ${init.registry.server}/${init.registry.repository}:<tag>`);
+baas.setAppId(init.appId);
+
+// (out-of-band) docker login + docker push <init.registry.server>/<init.registry.repository>:v1
+// (optional)    await baas.deployment.uploadFrontend(init.appId, await fs.readFile('./bundle.tar.gz'));
+// (deploy)      await baas.deployment.deploy(init.appId, { tag: 'v1', replicas: 1 });
 ```
 
 **Why XRPL?** Per the Smart Engines V3 architecture, XRPL is canonical for
@@ -166,19 +176,40 @@ await baas.agents.resume(agent.agentId);
 const events = await baas.agents.getEvents(agent.agentId);
 ```
 
-### Deployment
+### Deployment (runtime orchestration — spec §6.1)
+
+The four-step deploy flow: **init → docker push → (optional) uploadFrontend → deploy**.
 
 ```ts
-const deployment = await baas.deployment.create({
-  name: 'My Smart App v2',
+// 1. init — allocate appId via DKG + receive ephemeral Harbor push credentials
+const init = await baas.deployment.init({
+  name: 'my-smart-app',
+  port: 3000,
   services: ['database', 'storage', 'messaging'],
-  config: { /* app-specific */ },
 });
 
+// 2. docker push — out-of-band, using the ephemeral creds returned above
+//    docker login -u <init.registry.username> -p <init.registry.password> <init.registry.server>
+//    docker push <init.registry.server>/<init.registry.repository>:v1
+
+// 3. uploadFrontend — optional SPA tarball (content-addressed, mounted read-only)
+await baas.deployment.uploadFrontend(init.appId, await fs.readFile('./bundle.tar.gz'));
+
+// 4. deploy — reconcile to k8s
+const deployed = await baas.deployment.deploy(init.appId, {
+  tag: 'v1',
+  replicas: 1,
+  env: { NODE_ENV: 'production' },
+});
+console.log(`live at ${deployed.url}`);
+
+// Lifecycle + listing
 const apps = await baas.deployment.list();
-const info = await baas.deployment.get(appId);
-await baas.deployment.suspend(appId);
-await baas.deployment.resume(appId);
+const info = await baas.deployment.get(init.appId);
+const status = await baas.deployment.status(init.appId);
+await baas.deployment.suspend(init.appId);
+await baas.deployment.resume(init.appId);
+await baas.deployment.rollback(init.appId, { toTag: 'v0' });
 ```
 
 ---

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { DynamicModule, OnModuleDestroy, OnModuleInit, Type } from '@nestjs/common';
 import { z } from 'zod';
 
 export type CircuitState = "closed" | "open" | "half_open";
@@ -1056,7 +1055,7 @@ export type HttpClient = {
 	get<T = any>(path: string): Promise<T>;
 	put<T = any>(path: string, body: unknown): Promise<T>;
 	delete<T = any>(path: string): Promise<T>;
-	upload<T = any>(path: string, file: Blob | Buffer, filename: string, metadata?: Record<string, string>): Promise<T>;
+	upload<T = any>(path: string, file: Blob | Buffer, filename: string, metadata?: Record<string, string>, fieldName?: string): Promise<T>;
 };
 export type HttpClientConfig = {
 	baseUrl: string;
@@ -1198,7 +1197,6 @@ export type EntityCreationResponse = {
 	success: boolean;
 	entityId: string;
 	publicKeys: string[];
-	signerIndices: number[];
 	threshold: number;
 	ceremonyIds: string[];
 };
@@ -1218,7 +1216,6 @@ export type ReshareResponse = {
 export type EntityDetails = {
 	success: boolean;
 	payload?: unknown;
-	signerIndices?: number[];
 	validators?: string[];
 	publicKeys?: string[];
 	error?: string;
@@ -2099,7 +2096,7 @@ declare function xlmToStroops(xlm: string | number): string;
 declare function validateBitcoinAddress(address: string): boolean;
 declare function satoshisToBtc(satoshis: string | number): string;
 declare function btcToSatoshis(btc: string | number): string;
-export type BaasService = "auth" | "database" | "storage" | "functions" | "messaging";
+export type BaasService = "auth" | "database" | "storage" | "functions" | "messaging" | "customer-session";
 export type BaasSupportedChain = "hedera" | "xrpl" | "polkadot" | "solana";
 export type BaasEndpoints = {
 	auth: string;
@@ -2194,24 +2191,6 @@ export type BaasSessionInfo = {
 	expiresAt?: number;
 	error?: string;
 };
-export type BaasRegisterRequest = {
-	name: string;
-	services: BaasService[];
-	environment?: Record<string, string>;
-	limits?: {
-		storage?: string;
-		functions?: number;
-		channels?: number;
-	};
-};
-export type BaasRegisterResponse = {
-	appId: string;
-	name: string;
-	status: DeployedAppStatus;
-	services: string[];
-	endpoints: BaasEndpoints;
-	createdAt: string;
-};
 export type BaasDocument = {
 	_id: string;
 	data: Record<string, unknown>;
@@ -2417,18 +2396,56 @@ export type BaasPublishResult = {
 	channel: string;
 	timestamp: string;
 };
-export type BaasDeployRequest = {
+export type BaasInitRequest = {
 	name: string;
+	port: number;
 	services: BaasService[];
-	config?: Record<string, unknown>;
+	limits?: {
+		cpu?: string;
+		memory?: string;
+	};
 };
-export type BaasDeployResult = {
+export type BaasInitResponse = {
 	appId: string;
-	name: string;
-	status: "active" | "deploying" | "error";
-	services: string[];
-	endpoints: BaasEndpoints;
-	createdAt: string;
+	registry: {
+		server: string;
+		username: string;
+		password: string;
+		repository: string;
+	};
+};
+export type BaasDeployRequest = {
+	tag: string;
+	replicas?: number;
+	env?: Record<string, string>;
+	resources?: {
+		cpu?: string;
+		memory?: string;
+	};
+	strategy?: "rolling" | "recreate";
+};
+export type BaasDeployResponse = {
+	appId: string;
+	status: string;
+	url: string;
+};
+export type BaasUploadFrontendResponse = {
+	bundleSha256: string;
+	bundleSizeBytes: number;
+};
+export type BaasRollbackRequest = {
+	toTag: string;
+};
+export type BaasRuntimeStatus = {
+	appId: string;
+	state: "PENDING_SUBSCRIPTION" | "ACTIVE" | "SUSPENDED" | "RETIRED";
+	runtime?: {
+		image: string;
+		runtimeState: "NOT_DEPLOYED" | "DEPLOYING" | "RUNNING" | "FAILED" | "DEGRADED";
+		replicas: number;
+		lastReconciledAt?: string;
+		lastError?: string;
+	};
 };
 export type BaasAppListResponse = {
 	apps: DeployedAppInfo[];
@@ -2572,7 +2589,11 @@ export declare class MessagingClient {
 export declare class DeploymentClient {
 	private readonly http;
 	constructor(http: HttpClient);
-	create(request: BaasDeployRequest): Promise<BaasDeployResult>;
+	init(request: BaasInitRequest): Promise<BaasInitResponse>;
+	uploadFrontend(appId: string, bundle: Blob | Buffer, filename?: string): Promise<BaasUploadFrontendResponse>;
+	deploy(appId: string, request: BaasDeployRequest): Promise<BaasDeployResponse>;
+	rollback(appId: string, request: BaasRollbackRequest): Promise<BaasDeployResponse>;
+	status(appId: string): Promise<BaasRuntimeStatus>;
 	list(): Promise<BaasAppListResponse>;
 	get(appId: string): Promise<DeployedAppInfo>;
 	update(appId: string, updates: Partial<BaasDeployRequest>): Promise<DeployedAppInfo>;
@@ -2587,7 +2608,11 @@ export declare class DeploymentClient {
 		success: boolean;
 		status: string;
 	}>;
-	getStats(): Promise<any>;
+	getStats(): Promise<{
+		totalApps: number;
+		activeApps: number;
+		totalOwners: number;
+	}>;
 }
 export type AgentStatus = "active" | "paused" | "revoked" | "pending";
 export type AgentRegisterRequest = {
@@ -2712,6 +2737,55 @@ export declare class AgentsClient {
 		success: boolean;
 	}>;
 }
+export type CustomerSessionChallenge = {
+	challenge: string;
+};
+export type CustomerSessionVerifyRequest = {
+	appId: string;
+	chain: string;
+	address: string;
+	publicKey?: string;
+	signature: string;
+	challenge: string;
+};
+export type CustomerSessionToken = {
+	token: string;
+	sessionId: string;
+	validatorId: string;
+	expiresAt: string;
+	sessionSecret: string;
+};
+export type CustomerSessionInfo = {
+	sessionId: string;
+	appId: string;
+	customerChain: string;
+	customerAddress: string;
+	subscriptionContext?: {
+		nftSerial: number;
+		tier: "free_testnet" | "starter" | "professional" | "enterprise";
+		expiresAt: string;
+		allowedAutomations?: string[];
+	};
+	createdAt: string;
+	expiresAt: string;
+	lastActivityAt: string;
+};
+export declare class CustomerSessionClient {
+	private readonly baseUrl;
+	private readonly timeoutMs;
+	constructor(baseUrl: string, timeoutMs?: number);
+	challenge(input: {
+		chain: string;
+		address: string;
+	}): Promise<CustomerSessionChallenge>;
+	verify(req: CustomerSessionVerifyRequest): Promise<CustomerSessionToken>;
+	validate(bearer: string): Promise<CustomerSessionInfo>;
+	end(bearer: string): Promise<{
+		revoked: boolean;
+		sessionId: string;
+	}>;
+	private fetch;
+}
 export type AuthenticateOptions = {
 	chain: BaasSupportedChain;
 	walletAddress: string;
@@ -2733,6 +2807,7 @@ export declare class BaasClient {
 	readonly messaging: MessagingClient;
 	readonly deployment: DeploymentClient;
 	readonly agents: AgentsClient;
+	readonly customerSession: CustomerSessionClient;
 	constructor(config: BaasClientConfig);
 	setAppId(appId: string): void;
 	isAuthenticated(): boolean;
@@ -2745,7 +2820,6 @@ export declare class BaasClient {
 	authenticate(options: AuthenticateOptions): Promise<BaasAuthResult>;
 	validateSession(): Promise<BaasSessionInfo>;
 	logout(): Promise<void>;
-	register(request: BaasRegisterRequest): Promise<BaasRegisterResponse>;
 	private requireAuth;
 	private getHeaders;
 	private post;
@@ -2757,77 +2831,7 @@ export declare class BaasError extends Error {
 	readonly details?: BaasErrorDetails | undefined;
 	constructor(message: string, statusCode: number, details?: BaasErrorDetails | undefined);
 }
-export interface SmartEngineServiceConfig extends SmartEngineClientConfig {
-	testConnection?: boolean;
-	autoReconnect?: boolean;
-	reconnectInterval?: number;
-	maxReconnectAttempts?: number;
-}
-export declare const SMART_ENGINE_CONFIG = "SMART_ENGINE_CONFIG";
-interface BaasClient$1 {
-	readonly client: SmartEngineClient;
-	isHealthy(): Promise<boolean>;
-	getBaseUrl(): string;
-}
-export declare class SmartEngineService implements OnModuleInit, OnModuleDestroy {
-	private readonly config?;
-	private readonly logger;
-	private client;
-	private baasClient;
-	private connected;
-	private reconnectTimer;
-	private reconnectAttempts;
-	constructor(config?: SmartEngineServiceConfig | undefined);
-	onModuleInit(): Promise<void>;
-	onModuleDestroy(): Promise<void>;
-	initialize(config: SmartEngineServiceConfig): Promise<void>;
-	shutdown(): Promise<void>;
-	getClient(): SmartEngineClient;
-	getBaasClient(): BaasClient$1;
-	isConnected(): boolean;
-	testConnection(): Promise<boolean>;
-	getStatus(): {
-		connected: boolean;
-		baseUrl: string | null;
-		authenticated: boolean;
-		reconnectAttempts: number;
-	};
-	createGatewayClient(config: {
-		baseUrl: string;
-		apiKey?: string;
-		authToken?: string;
-		timeout?: number;
-		allowInsecure?: boolean;
-	}): SmartGatewayClient;
-	createHostClient(config: {
-		hostUrl: string;
-		appId?: string;
-		timeout?: number;
-		allowInsecure?: boolean;
-	}): BaasClient;
-	private createBaasClient;
-	private scheduleReconnect;
-}
-export interface SmartEngineModuleAsyncOptions {
-	imports?: any[];
-	useFactory?: (...args: any[]) => Promise<SmartEngineServiceConfig> | SmartEngineServiceConfig;
-	inject?: any[];
-	useClass?: Type<SmartEngineOptionsFactory>;
-	useExisting?: Type<SmartEngineOptionsFactory>;
-	isGlobal?: boolean;
-}
-export interface SmartEngineOptionsFactory {
-	createSmartEngineOptions(): Promise<SmartEngineServiceConfig> | SmartEngineServiceConfig;
-}
-export declare class SmartEngineModule {
-	static forRoot(config: SmartEngineServiceConfig, isGlobal?: boolean): DynamicModule;
-	static forRootAsync(options: SmartEngineModuleAsyncOptions): DynamicModule;
-	private static createAsyncProviders;
-}
 
-declare namespace nestjs {
-	export { BaasClient$1 as BaasClient, SMART_ENGINE_CONFIG, SmartEngineModule, SmartEngineModuleAsyncOptions, SmartEngineOptionsFactory, SmartEngineService, SmartEngineServiceConfig };
-}
 declare namespace bitcoin {
 	export { btcToSatoshis, satoshisToBtc, validateBitcoinAddress };
 }
@@ -2846,6 +2850,9 @@ declare namespace solana {
 declare namespace stellar {
 	export { stroopsToXlm, validateStellarAddress, xlmToStroops };
 }
+declare namespace baas {
+	export { AgentBalance, AgentEvent, AgentFundRequest, AgentInfo, AgentOperation, AgentRegisterRequest, AgentRules, AgentRulesValidationResult, AgentStatus, AgentTradeRequest, AgentWithdrawRequest, AgentsClient, AuthenticateOptions, BaasAppListResponse, BaasAuthConfig, BaasAuthResult, BaasChallengeRequest, BaasChallengeResponse, BaasChannelConfig, BaasClient, BaasClientConfig, BaasDeleteResult, BaasDeployRequest, BaasDeployResponse, BaasDocument, BaasEndpoints, BaasError, BaasErrorDetails, BaasErrorResponse, BaasFileInfo, BaasFileMetadata, BaasFindResult, BaasFunctionDeployRequest, BaasFunctionDeployResult, BaasFunctionInfo, BaasFunctionLog, BaasFunctionLogOptions, BaasFunctionResources, BaasFunctionResult, BaasFunctionRuntime, BaasHistoryOptions, BaasInitRequest, BaasInitResponse, BaasInsertResult, BaasMerkleProof, BaasMessage, BaasPresenceInfo, BaasPresenceMember, BaasPublishResult, BaasQueryOptions, BaasRollbackRequest, BaasRuntimeStatus, BaasService, BaasSessionInfo, BaasStateTransition, BaasStorageUsage, BaasSupportedChain, BaasTriggerType, BaasUpdateResult, BaasUploadFrontendResponse, BaasUploadResult, BaasVerifyRequest, ChannelSubscription, DatabaseClient, DatabaseStatsResponse, DbComparisonOperator, DbDocument, DbQuery, DeployedApp, DeployedAppInfo, DeployedAppLimits, DeployedAppStatus, DeployedAppUsage, DeploymentClient, DocumentProofResponse, FunctionsClient, MessageHandler, MessagingClient, StateRootResponse, StateTransitionsResponse, StorageClient, validateAgentRules };
+}
 declare namespace discovery {
 	export { MIRROR_NODE_URLS, MirrorNodeClient, MirrorNodeConfig, MirrorNodeError, TopicMessage, TopicMessagesResponse, ValidatorDiscoveryClient, ValidatorDiscoveryConfig, ValidatorInfo, ValidatorMetadata, ValidatorNetworkEndpoints };
 }
@@ -2861,19 +2868,14 @@ declare namespace subscription {
 declare namespace settlement {
 	export { SettlementAsset, SettlementClient, SettlementHistoryEntry, SettlementInitiateRequest, SettlementPurpose, SettlementStatusResponse };
 }
-declare namespace baas {
-	export { AgentBalance, AgentEvent, AgentFundRequest, AgentInfo, AgentOperation, AgentRegisterRequest, AgentRules, AgentRulesValidationResult, AgentStatus, AgentTradeRequest, AgentWithdrawRequest, AgentsClient, AuthenticateOptions, BaasAppListResponse, BaasAuthConfig, BaasAuthResult, BaasChallengeRequest, BaasChallengeResponse, BaasChannelConfig, BaasClient, BaasClientConfig, BaasDeleteResult, BaasDeployRequest, BaasDeployResult, BaasDocument, BaasEndpoints, BaasError, BaasErrorDetails, BaasErrorResponse, BaasFileInfo, BaasFileMetadata, BaasFindResult, BaasFunctionDeployRequest, BaasFunctionDeployResult, BaasFunctionInfo, BaasFunctionLog, BaasFunctionLogOptions, BaasFunctionResources, BaasFunctionResult, BaasFunctionRuntime, BaasHistoryOptions, BaasInsertResult, BaasMerkleProof, BaasMessage, BaasPresenceInfo, BaasPresenceMember, BaasPublishResult, BaasQueryOptions, BaasRegisterRequest, BaasRegisterResponse, BaasService, BaasSessionInfo, BaasStateTransition, BaasStorageUsage, BaasSupportedChain, BaasTriggerType, BaasUpdateResult, BaasUploadResult, BaasVerifyRequest, ChannelSubscription, DatabaseClient, DatabaseStatsResponse, DbComparisonOperator, DbDocument, DbQuery, DeployedApp, DeployedAppInfo, DeployedAppLimits, DeployedAppStatus, DeployedAppUsage, DeploymentClient, DocumentProofResponse, FunctionsClient, MessageHandler, MessagingClient, StateRootResponse, StateTransitionsResponse, StorageClient, validateAgentRules };
-}
 
 export {
-	BaasClient$1 as NestJsBaasClient,
 	RetryConfig as ResilienceRetryConfig,
 	RetryConfig$1 as RetryConfig,
 	auth,
 	baas,
 	chains,
 	discovery,
-	nestjs,
 	settlement,
 	subscription,
 };