@hsuite/native-connect-client 1.0.0

package/dist/protocol/e2e-harness.d.ts

@@ -0,0 +1,65 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file End-to-end test harness with full wallet SDK integration.
+ * Provides complete WalletCore, ledger registration, and session management
+ * for comprehensive integration testing.
+ *
+ * @module @hsuite/native-connect-client/protocol/e2e-harness
+ */
+import { ReferenceClient } from '../reference-client';
+import { MemoryTransport } from '../memory-transport';
+import { WalletCore } from '@hsuite/native-connect-sdk';
+import type { LedgerAdapter, ChannelInvite } from '@hsuite/native-connect-sdk';
+/**
+ * @description Configuration options for end-to-end test harness
+ * @property {LedgerAdapter} ledgerAdapter - Ledger adapter to register
+ * @property {object} [session] - Optional session configuration
+ */
+export interface HarnessOptions {
+    ledgerAdapter: LedgerAdapter;
+    session?: {
+        /** Session request - ChannelInvite object */
+        request: ChannelInvite;
+        approval?: Parameters<WalletCore['approveSession']>[1];
+    };
+}
+/**
+ * @class EndToEndHarness
+ * @description End-to-end test harness with full wallet SDK integration.
+ *
+ * Provides:
+ * - Complete WalletCore instance with ledger registration
+ * - Reference client for RPC communication
+ * - In-memory transport for isolated testing
+ * - Session establishment utilities
+ */
+export declare class EndToEndHarness {
+    private readonly options;
+    readonly client: ReferenceClient;
+    readonly wallet: WalletCore;
+    readonly transport: MemoryTransport;
+    constructor(options: HarnessOptions);
+    /**
+     * @description Establish test session with wallet
+     * @returns Session identifier
+     */
+    establishSession(): Promise<string>;
+    /**
+     * @description Create a default channel invite for testing
+     * @returns ChannelInvite object
+     */
+    private createDefaultInvite;
+    /**
+     * @description Cleanup harness resources
+     */
+    teardown(): Promise<void>;
+}
+//# sourceMappingURL=e2e-harness.d.ts.map

package/dist/protocol/e2e-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"e2e-harness.d.ts","sourceRoot":"","sources":["../../src/protocol/e2e-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EACL,UAAU,EAMX,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,CAAC,EAAE;QACR,6CAA6C;QAC7C,OAAO,EAAE,aAAa,CAAC;QACvB,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACxD,CAAC;CACH;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAKd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;gBAEP,OAAO,EAAE,cAAc;IAyDpD;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAazC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAIhC"}

package/dist/protocol/e2e-harness.js

@@ -0,0 +1,130 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file End-to-end test harness with full wallet SDK integration.
+ * Provides complete WalletCore, ledger registration, and session management
+ * for comprehensive integration testing.
+ *
+ * @module @hsuite/native-connect-client/protocol/e2e-harness
+ */
+import { ReferenceClient } from '../reference-client';
+import { MemoryTransport } from '../memory-transport';
+import { WalletCore, LedgerRegistry, SessionManager, KeyVaultService, CryptoService, createChannelInvite, } from '@hsuite/native-connect-sdk';
+import { base64 } from '@scure/base';
+/**
+ * @class EndToEndHarness
+ * @description End-to-end test harness with full wallet SDK integration.
+ *
+ * Provides:
+ * - Complete WalletCore instance with ledger registration
+ * - Reference client for RPC communication
+ * - In-memory transport for isolated testing
+ * - Session establishment utilities
+ */
+export class EndToEndHarness {
+    options;
+    client;
+    wallet;
+    transport;
+    constructor(options) {
+        this.options = options;
+        this.transport = new MemoryTransport();
+        const registry = new LedgerRegistry({
+            context: {
+                secureRandom: (length) => crypto.getRandomValues(new Uint8Array(length)),
+                logger: () => undefined,
+                httpClient: {
+                    async get() {
+                        return {};
+                    },
+                    async post() {
+                        return {};
+                    },
+                },
+            },
+        });
+        const sessionManager = new SessionManager();
+        const keyVault = new KeyVaultService({
+            storage: {
+                async store() { },
+                async retrieve() {
+                    return undefined;
+                },
+                async remove() { },
+                async list() {
+                    return [];
+                },
+            },
+            encoder: {
+                async encrypt(data) {
+                    return base64.encode(data);
+                },
+                async decrypt(payload) {
+                    return base64.decode(payload);
+                },
+            },
+        });
+        this.wallet = new WalletCore({
+            registry,
+            sessionManager,
+            keyVault,
+            crypto: new CryptoService(),
+            secureMemory: {
+                async store() { },
+                async retrieve() {
+                    return undefined;
+                },
+                async remove() { },
+                async clear() { },
+            },
+        });
+        void this.wallet.registerLedger(options.ledgerAdapter);
+        this.client = new ReferenceClient({ transport: this.transport });
+    }
+    /**
+     * @description Establish test session with wallet
+     * @returns Session identifier
+     */
+    async establishSession() {
+        // Use provided request or create a default invite
+        const request = this.options.session?.request ?? this.createDefaultInvite();
+        const sessionId = await this.wallet.createSession(request);
+        if (this.options.session?.approval) {
+            await this.wallet.approveSession(sessionId, this.options.session.approval);
+        }
+        return sessionId;
+    }
+    /**
+     * @description Create a default channel invite for testing
+     * @returns ChannelInvite object
+     */
+    createDefaultInvite() {
+        return createChannelInvite({
+            type: 'session',
+            app: {
+                id: 'test-app',
+                name: 'Test App',
+            },
+            context: {
+                ledgerId: this.options.ledgerAdapter.manifest.metadata.id,
+                networkId: this.options.ledgerAdapter.manifest.metadata.defaultNetworkId,
+            },
+            permissions: [],
+        });
+    }
+    /**
+     * @description Cleanup harness resources
+     */
+    async teardown() {
+        this.client.destroy();
+        await this.transport.drain();
+    }
+}
+//# sourceMappingURL=e2e-harness.js.map

package/dist/protocol/e2e-harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"e2e-harness.js","sourceRoot":"","sources":["../../src/protocol/e2e-harness.ts"],"names":[],"mappings":"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"}

package/dist/protocol/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file Handler registration utilities and protocol exports for reference client.
+ * Re-exports all handler registration functions for convenient access.
+ *
+ * @module @hsuite/native-connect-client/protocol
+ */
+/**
+ * @description Handler registration utilities for reference client
+ */
+export { registerSessionHandlers } from '../handlers/session-handler';
+export { registerSigningHandlers } from '../handlers/signing-handler';
+export { registerWalletHandlers } from '../handlers/wallet-handler';
+//# sourceMappingURL=index.d.ts.map

package/dist/protocol/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AAEH;;GAEG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/protocol/index.js

@@ -0,0 +1,22 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file Handler registration utilities and protocol exports for reference client.
+ * Re-exports all handler registration functions for convenient access.
+ *
+ * @module @hsuite/native-connect-client/protocol
+ */
+/**
+ * @description Handler registration utilities for reference client
+ */
+export { registerSessionHandlers } from '../handlers/session-handler';
+export { registerSigningHandlers } from '../handlers/signing-handler';
+export { registerWalletHandlers } from '../handlers/wallet-handler';
+//# sourceMappingURL=index.js.map

package/dist/protocol/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AAEH;;GAEG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/query-client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file High-level query client for common wallet RPC methods.
+ * Provides convenience methods wrapping ReferenceClient for typical
+ * wallet operations like account discovery and configuration retrieval.
+ *
+ * @module @hsuite/native-connect-client/query-client
+ */
+import { ReferenceClient } from './reference-client';
+import type { RpcResponse } from '@hsuite/native-connect-types';
+/**
+ * @class QueryClient
+ * @description High-level query client for common wallet RPC methods.
+ *
+ * Provides convenience methods for:
+ * - Account discovery via `wallet/accounts` RPC method
+ * - Configuration retrieval via `wallet/get-config` RPC method
+ */
+export declare class QueryClient {
+    private readonly client;
+    constructor(client: ReferenceClient);
+    /**
+     * @description Retrieve wallet accounts
+     * @returns RPC response containing account list
+     */
+    getAccounts(): Promise<RpcResponse>;
+    /**
+     * @description Fetch wallet configuration metadata
+     * @returns RPC response containing configuration data
+     */
+    getConfig(): Promise<RpcResponse>;
+}
+//# sourceMappingURL=query-client.d.ts.map

package/dist/query-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-client.d.ts","sourceRoot":"","sources":["../src/query-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE5E;;;;;;;GAOG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,eAAe;IAEpD;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC;IAYzC;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC;CAWxC"}

package/dist/query-client.js

@@ -0,0 +1,52 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @class QueryClient
+ * @description High-level query client for common wallet RPC methods.
+ *
+ * Provides convenience methods for:
+ * - Account discovery via `wallet/accounts` RPC method
+ * - Configuration retrieval via `wallet/get-config` RPC method
+ */
+export class QueryClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * @description Retrieve wallet accounts
+     * @returns RPC response containing account list
+     */
+    async getAccounts() {
+        const request = {
+            id: crypto.randomUUID(),
+            jsonrpc: '2.0',
+            method: 'wallet/accounts',
+            params: {},
+            timestamp: Date.now(),
+        };
+        return this.client.send(request);
+    }
+    /**
+     * @description Fetch wallet configuration metadata
+     * @returns RPC response containing configuration data
+     */
+    async getConfig() {
+        const request = {
+            id: crypto.randomUUID(),
+            jsonrpc: '2.0',
+            method: 'wallet/get-config',
+            params: {},
+            timestamp: Date.now(),
+        };
+        return this.client.send(request);
+    }
+}
+//# sourceMappingURL=query-client.js.map

package/dist/query-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-client.js","sourceRoot":"","sources":["../src/query-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,MAAuB;QAAvB,WAAM,GAAN,MAAM,CAAiB;IAAG,CAAC;IAExD;;;OAGG;IACH,KAAK,CAAC,WAAW;QACf,MAAM,OAAO,GAAe;YAC1B,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;YACvB,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,iBAAiB;YACzB,MAAM,EAAE,EAAE;YACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS;QACb,MAAM,OAAO,GAAe;YAC1B,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;YACvB,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,mBAAmB;YAC3B,MAAM,EAAE,EAAE;YACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/reference-client.d.ts

@@ -0,0 +1,100 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file Reference client implementation for dApp developers.
+ * Provides a complete RPC client with bidirectional message routing,
+ * timeout protection, and event-driven lifecycle hooks.
+ *
+ * @module @hsuite/native-connect-client/reference-client
+ */
+import EventEmitter from 'eventemitter3';
+import { RpcServer, RpcRouter } from '@hsuite/native-connect-sdk';
+import type { RpcRequest, RpcResponse, RpcEnvelope } from '@hsuite/native-connect-types';
+/**
+ * @description Transport abstraction for RPC message exchange
+ * @property {function} send - Send RPC envelope to peer
+ * @property {function} onMessage - Register listener for incoming messages
+ * @property {function} [offMessage] - Unregister message listener
+ * @property {function} [onServerMessage] - Register listener for server-originated messages
+ * @property {function} [offServerMessage] - Unregister server message listener
+ */
+export interface ReferenceClientTransport {
+    send(message: RpcEnvelope, from?: 'client' | 'server'): Promise<void>;
+    onMessage(listener: (message: RpcEnvelope) => void): void;
+    offMessage?(listener: (message: RpcEnvelope) => void): void;
+    onServerMessage?(listener: (message: RpcEnvelope) => void): void;
+    offServerMessage?(listener: (message: RpcEnvelope) => void): void;
+}
+/**
+ * @description Configuration for reference client instantiation
+ * @property {ReferenceClientTransport} transport - Transport layer for message exchange
+ * @property {number} [timeoutMs] - Request timeout in milliseconds
+ * @property {RpcServer} [server] - Optional RPC server for bidirectional communication
+ * @property {function} [onResponse] - Callback invoked on response receipt
+ */
+export interface ReferenceClientOptions {
+    transport: ReferenceClientTransport;
+    timeoutMs?: number;
+    server?: RpcServer;
+    onResponse?(response: RpcResponse): void;
+}
+/**
+ * @description Events emitted by reference client
+ */
+export type ReferenceClientEvent = 'request' | 'response' | 'response:error' | 'error';
+/**
+ * @class ReferenceClient
+ * @augments EventEmitter
+ * @description Developer-facing RPC client for HSuite SDK integration testing.
+ *
+ * This is a reference implementation designed for dApp developers to understand
+ * and test wallet communication patterns. It demonstrates the complete RPC
+ * request/response lifecycle with proper timeout handling and error recovery.
+ *
+ * Features:
+ * - Request/response RPC communication with timeout protection
+ * - Bidirectional message routing for client-server scenarios
+ * - Event emission for request/response lifecycle hooks
+ * - Handler registration for incoming RPC methods
+ */
+export declare class ReferenceClient extends EventEmitter<ReferenceClientEvent | string> {
+    private readonly options;
+    private readonly rpc;
+    private readonly codec;
+    private readonly pending;
+    private readonly timeoutMs;
+    private readonly messageListener;
+    private readonly server?;
+    private readonly router;
+    private readonly logger;
+    constructor(options: ReferenceClientOptions);
+    /**
+     * @description Send RPC request and await response with timeout
+     * @param request - RPC request payload
+     * @returns Promise resolving to RPC response
+     * @throws Error if request times out
+     */
+    send<T = unknown>(request: RpcRequest): Promise<RpcResponse<T>>;
+    /**
+     * @description Register handler for incoming RPC method
+     * @param method - RPC method name
+     * @param handler - Handler function returning response data
+     */
+    register(method: string, handler: Parameters<typeof RpcRouter.prototype.register>[1]): void;
+    /**
+     * @description Dispose client and cleanup listeners
+     */
+    destroy(): void;
+    private handleEnvelope;
+    private isRequest;
+    private isError;
+    private isSuccess;
+}
+//# sourceMappingURL=reference-client.d.ts.map

package/dist/reference-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-client.d.ts","sourceRoot":"","sources":["../src/reference-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AAEH,OAAO,YAAY,MAAM,eAAe,CAAC;AACzC,OAAO,EAAuB,SAAS,EAAE,SAAS,EAAa,MAAM,4BAA4B,CAAC;AAClG,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGzF;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,UAAU,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAC;IAC5D,eAAe,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAC;IACjE,gBAAgB,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAC;CACnE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,wBAAwB,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,UAAU,CAAC,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,UAAU,GAAG,gBAAgB,GAAG,OAAO,CAAC;AAEvF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAgB,SAAQ,YAAY,CAAC,oBAAoB,GAAG,MAAM,CAAC;IAUlE,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+D;IACvF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;gBAEpD,OAAO,EAAE,sBAAsB;IAc5D;;;;;OAKG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAqBrE;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAI3F;;OAEG;IACH,OAAO,IAAI,IAAI;YAKD,cAAc;IAiD5B,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,SAAS;CAGlB"}

package/dist/reference-client.js

@@ -0,0 +1,149 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file Reference client implementation for dApp developers.
+ * Provides a complete RPC client with bidirectional message routing,
+ * timeout protection, and event-driven lifecycle hooks.
+ *
+ * @module @hsuite/native-connect-client/reference-client
+ */
+import EventEmitter from 'eventemitter3';
+import { RpcClient, RpcCodec, RpcRouter, getLogger } from '@hsuite/native-connect-sdk';
+import { RpcRequestSchema, RpcErrorSchema, RpcSuccessSchema } from '@hsuite/native-connect-types';
+/**
+ * @class ReferenceClient
+ * @augments EventEmitter
+ * @description Developer-facing RPC client for HSuite SDK integration testing.
+ *
+ * This is a reference implementation designed for dApp developers to understand
+ * and test wallet communication patterns. It demonstrates the complete RPC
+ * request/response lifecycle with proper timeout handling and error recovery.
+ *
+ * Features:
+ * - Request/response RPC communication with timeout protection
+ * - Bidirectional message routing for client-server scenarios
+ * - Event emission for request/response lifecycle hooks
+ * - Handler registration for incoming RPC methods
+ */
+export class ReferenceClient extends EventEmitter {
+    options;
+    rpc;
+    codec = new RpcCodec();
+    pending = new Map();
+    timeoutMs;
+    messageListener;
+    server;
+    router = new RpcRouter();
+    logger = getLogger().scoped?.('ReferenceClient') ?? getLogger();
+    constructor(options) {
+        super();
+        this.options = options;
+        this.timeoutMs = options.timeoutMs ?? 5000;
+        this.rpc = new RpcClient({
+            transport: options.transport,
+            codec: this.codec,
+            timeoutMs: this.timeoutMs,
+        });
+        this.server = options.server;
+        this.messageListener = (envelope) => this.handleEnvelope(envelope);
+        options.transport.onMessage(this.messageListener);
+        options.transport.onServerMessage?.((envelope) => this.handleEnvelope(envelope));
+    }
+    /**
+     * @description Send RPC request and await response with timeout
+     * @param request - RPC request payload
+     * @returns Promise resolving to RPC response
+     * @throws Error if request times out
+     */
+    async send(request) {
+        const id = request.id ?? crypto.randomUUID();
+        const finalRequest = { ...request, id, timestamp: request.timestamp ?? Date.now() };
+        this.logger.debug('Sending RPC request', { method: finalRequest.method, id: String(id) });
+        const promise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`RPC request ${String(id)} timed out after ${this.timeoutMs}ms`));
+            }, this.timeoutMs);
+            this.pending.set(id, (response) => {
+                clearTimeout(timeout);
+                this.logger.debug('RPC response received', { id: String(id), method: finalRequest.method });
+                resolve(response);
+            });
+        });
+        await this.rpc.send(finalRequest);
+        return promise;
+    }
+    /**
+     * @description Register handler for incoming RPC method
+     * @param method - RPC method name
+     * @param handler - Handler function returning response data
+     */
+    register(method, handler) {
+        this.router.register(method, handler);
+    }
+    /**
+     * @description Dispose client and cleanup listeners
+     */
+    destroy() {
+        this.pending.clear();
+        this.options.transport.offMessage?.(this.messageListener);
+    }
+    async handleEnvelope(envelope) {
+        try {
+            const decoded = await this.codec.decode(envelope);
+            const payload = decoded.payload;
+            if (this.isRequest(payload)) {
+                const handled = this.server ? await this.server.handle(decoded) : undefined;
+                if (!handled) {
+                    const response = await this.router.handle(payload);
+                    const responseEnvelope = await this.codec.encodeResponse(response);
+                    await this.options.transport.send(responseEnvelope, 'server');
+                    this.logger.debug('RPC response sent from local router', {
+                        method: payload.method,
+                        id: String(payload.id),
+                    });
+                }
+                this.emit('request', payload);
+                this.logger.info('RPC request handled locally', {
+                    method: payload.method,
+                    id: String(payload.id),
+                });
+                return;
+            }
+            const result = payload;
+            const id = typeof result.id === 'string' || typeof result.id === 'number' ? result.id : 'unknown';
+            const callback = this.pending.get(id);
+            if (callback) {
+                callback(result);
+                this.pending.delete(id);
+            }
+            this.options.onResponse?.(result);
+            this.emit(this.isError(result) ? 'response:error' : 'response', result);
+            this.logger.info('RPC response processed', {
+                id: String(result.id),
+                status: this.isError(result) ? 'error' : 'success',
+            });
+        }
+        catch (error) {
+            this.emit('error', error);
+            this.logger.error('RPC envelope handling failed', { error });
+        }
+    }
+    isRequest(payload) {
+        return RpcRequestSchema.safeParse(payload).success;
+    }
+    isError(payload) {
+        return RpcErrorSchema.safeParse(payload).success;
+    }
+    isSuccess(payload) {
+        return RpcSuccessSchema.safeParse(payload).success;
+    }
+}
+//# sourceMappingURL=reference-client.js.map

package/dist/reference-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-client.js","sourceRoot":"","sources":["../src/reference-client.ts"],"names":[],"mappings":"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"}