@hsuite/native-connect-client 1.0.0

package/src/reference-client.spec.ts

@@ -0,0 +1,408 @@
+/**
+ * @fileoverview Unit tests for ReferenceClient
+ * Tests RPC client functionality for SDK integration testing
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ReferenceClient, type ReferenceClientTransport } from './reference-client.js';
+import type {
+  RpcEnvelope,
+  RpcRequest,
+  RpcResponse,
+  RpcSuccess,
+} from '@hsuite/native-connect-types';
+import { RpcVersion } from '@hsuite/native-connect-types';
+
+/**
+ * @description Flushes the microtask queue to allow queued async work to start.
+ */
+const flushMicrotask = () => new Promise<void>((resolve) => queueMicrotask(() => resolve()));
+
+/**
+ * @description Ensures an RPC response is a success payload and narrows the type for result assertions.
+ * @throws Error when the response is an error variant.
+ */
+function assertRpcSuccess<T>(response: RpcResponse<T>): asserts response is RpcSuccess<T> {
+  if ('error' in response) {
+    throw new Error(`Expected RPC success response but received error: ${response.error.message}`);
+  }
+}
+
+/**
+ * Create a mock transport for testing.
+ * The transport simulates responses in the format that RpcCodec expects.
+ */
+function createMockTransport(): ReferenceClientTransport & {
+  listeners: Set<(message: RpcEnvelope) => void>;
+  serverListeners: Set<(message: RpcEnvelope) => void>;
+  sentMessages: RpcEnvelope[];
+  simulateResponse: (response: RpcResponse) => void;
+  simulateRequest: (request: RpcRequest) => void;
+} {
+  const listeners = new Set<(message: RpcEnvelope) => void>();
+  const serverListeners = new Set<(message: RpcEnvelope) => void>();
+  const sentMessages: RpcEnvelope[] = [];
+
+  return {
+    listeners,
+    serverListeners,
+    sentMessages,
+    send: vi.fn(async (message: RpcEnvelope) => {
+      sentMessages.push(message);
+    }),
+    onMessage: (listener) => {
+      listeners.add(listener);
+    },
+    offMessage: (listener) => {
+      listeners.delete(listener);
+    },
+    onServerMessage: (listener) => {
+      serverListeners.add(listener);
+    },
+    offServerMessage: (listener) => {
+      serverListeners.delete(listener);
+    },
+    /**
+     * Simulate a response in the format RpcCodec expects.
+     * The envelope id must be a UUID, separate from the payload id.
+     */
+    simulateResponse: (response: RpcResponse) => {
+      // Create envelope in the same format as RpcCodec.encodeResponse()
+      // Important: envelope.id is a UUID, while payload.id is the RPC request ID
+      const envelope: RpcEnvelope = {
+        id: crypto.randomUUID(), // Envelope ID is always a UUID
+        topic: 'rpc',
+        version: RpcVersion,
+        createdAt: Date.now(),
+        payload: {
+          ...response,
+          jsonrpc: '2.0',
+          timestamp: Date.now(),
+        },
+      } as RpcEnvelope;
+      listeners.forEach((listener) => listener(envelope));
+    },
+    /**
+     * Simulate a request in the format RpcCodec expects
+     */
+    simulateRequest: (request: RpcRequest) => {
+      const envelope: RpcEnvelope = {
+        id: crypto.randomUUID(),
+        topic: 'rpc',
+        version: RpcVersion,
+        createdAt: Date.now(),
+        payload: {
+          ...request,
+          id: request.id ?? crypto.randomUUID(),
+          jsonrpc: '2.0',
+          timestamp: Date.now(),
+        },
+      } as RpcEnvelope;
+      listeners.forEach((listener) => listener(envelope));
+    },
+  };
+}
+
+describe('ReferenceClient', () => {
+  let transport: ReturnType<typeof createMockTransport>;
+  let client: ReferenceClient;
+
+  beforeEach(() => {
+    transport = createMockTransport();
+    client = new ReferenceClient({
+      transport,
+      timeoutMs: 1000,
+    });
+  });
+
+  afterEach(() => {
+    client.destroy();
+    vi.restoreAllMocks();
+  });
+
+  describe('constructor', () => {
+    it('should create client with default timeout', () => {
+      const defaultClient = new ReferenceClient({ transport });
+      expect(defaultClient).toBeDefined();
+      defaultClient.destroy();
+    });
+
+    it('should register message listener on transport', () => {
+      expect(transport.listeners.size).toBe(1);
+    });
+  });
+
+  describe('send', () => {
+    it('should send request and receive response', async () => {
+      const request: RpcRequest = {
+        id: 'test-1',
+        jsonrpc: '2.0',
+        method: 'wallet/accounts',
+        params: {},
+      };
+
+      // Start send, then simulate response
+      const sendPromise = client.send(request);
+
+      // Use queueMicrotask to ensure send() has started
+      await flushMicrotask();
+
+      transport.simulateResponse({
+        id: 'test-1',
+        jsonrpc: '2.0',
+        result: { accounts: ['0.0.12345'] },
+      });
+
+      const response = await sendPromise;
+
+      assertRpcSuccess(response);
+      expect(response.id).toBe('test-1');
+      expect(response.result).toEqual({ accounts: ['0.0.12345'] });
+    });
+
+    it('should generate request ID if not provided', async () => {
+      const request: RpcRequest = {
+        jsonrpc: '2.0',
+        method: 'wallet/get-config',
+        params: {},
+      };
+
+      const sendPromise = client.send(request);
+
+      await flushMicrotask();
+
+      // Get the generated ID from the sent message
+      const sentMessage = transport.sentMessages[0];
+      const sentRequest = sentMessage.payload as RpcRequest;
+
+      transport.simulateResponse({
+        id: sentRequest.id,
+        jsonrpc: '2.0',
+        result: 'pong',
+      });
+
+      const response = await sendPromise;
+
+      assertRpcSuccess(response);
+      expect(response.result).toBe('pong');
+      expect(sentRequest.id).toBeDefined();
+    });
+
+    it('should timeout if no response received', async () => {
+      vi.useFakeTimers();
+
+      const shortTimeoutTransport = createMockTransport();
+      const shortTimeoutClient = new ReferenceClient({
+        transport: shortTimeoutTransport,
+        timeoutMs: 100,
+      });
+
+      const request: RpcRequest = {
+        id: 'timeout-test',
+        jsonrpc: '2.0',
+        method: 'wallet/get-config',
+        params: {},
+      };
+
+      const sendPromise = shortTimeoutClient.send(request);
+
+      // Advance time past timeout
+      vi.advanceTimersByTime(150);
+
+      await expect(sendPromise).rejects.toThrow('timed out');
+
+      shortTimeoutClient.destroy();
+      vi.useRealTimers();
+    });
+
+    it('should add timestamp if not provided', async () => {
+      const request: RpcRequest = {
+        id: 'timestamp-test',
+        jsonrpc: '2.0',
+        method: 'wallet/register-ledger',
+        params: {},
+      };
+
+      const sendPromise = client.send(request);
+
+      await flushMicrotask();
+
+      transport.simulateResponse({
+        id: 'timestamp-test',
+        jsonrpc: '2.0',
+        result: 'ok',
+      });
+
+      await sendPromise;
+
+      const sentMessage = transport.sentMessages[0];
+      const sentRequest = sentMessage.payload as RpcRequest;
+      expect(sentRequest.timestamp).toBeDefined();
+      expect(typeof sentRequest.timestamp).toBe('number');
+    });
+  });
+
+  describe('register', () => {
+    it('should register handler for method', async () => {
+      const handler = vi.fn().mockResolvedValue({ status: 'ok' });
+      client.register('wallet/accounts', handler);
+
+      // Simulate incoming request using proper format with valid method
+      transport.simulateRequest({
+        id: crypto.randomUUID(),
+        jsonrpc: '2.0',
+        method: 'wallet/accounts',
+        params: { data: 'test' },
+      });
+
+      // Give time for async handling
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(handler).toHaveBeenCalled();
+    });
+  });
+
+  describe('destroy', () => {
+    it('should clear pending requests', () => {
+      client.destroy();
+      // No way to directly check pending map, but destroy should complete without error
+      expect(true).toBe(true);
+    });
+
+    it('should remove message listener', () => {
+      client.destroy();
+      expect(transport.listeners.size).toBe(0);
+    });
+  });
+
+  describe('events', () => {
+    it('should emit request event for incoming requests', async () => {
+      const requestHandler = vi.fn();
+      client.on('request', requestHandler);
+
+      // Simulate incoming request using proper format with valid method
+      transport.simulateRequest({
+        id: crypto.randomUUID(),
+        jsonrpc: '2.0',
+        method: 'wallet/accounts',
+        params: {},
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(requestHandler).toHaveBeenCalled();
+    });
+
+    it('should emit response event for successful responses', async () => {
+      const responseHandler = vi.fn();
+      client.on('response', responseHandler);
+
+      const request: RpcRequest = {
+        id: 'response-event',
+        jsonrpc: '2.0',
+        method: 'wallet/get-config',
+        params: {},
+      };
+
+      const sendPromise = client.send(request);
+
+      await flushMicrotask();
+
+      transport.simulateResponse({
+        id: 'response-event',
+        jsonrpc: '2.0',
+        result: 'success',
+      });
+
+      await sendPromise;
+
+      expect(responseHandler).toHaveBeenCalled();
+    });
+
+    it('should emit response:error event for error responses', async () => {
+      const errorHandler = vi.fn();
+      client.on('response:error', errorHandler);
+
+      const request: RpcRequest = {
+        id: 'error-event',
+        jsonrpc: '2.0',
+        method: 'wallet/get-config',
+        params: {},
+      };
+
+      const sendPromise = client.send(request);
+
+      await flushMicrotask();
+
+      transport.simulateResponse({
+        id: 'error-event',
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: 'Test error',
+        },
+      });
+
+      await sendPromise;
+
+      expect(errorHandler).toHaveBeenCalled();
+    });
+
+    it('should emit error event on envelope handling failure', async () => {
+      const errorHandler = vi.fn();
+      client.on('error', errorHandler);
+
+      // Simulate malformed envelope (missing version)
+      const badEnvelope = {
+        type: 'invalid',
+        payload: null,
+        timestamp: Date.now(),
+      } as unknown as RpcEnvelope;
+
+      transport.listeners.forEach((listener) => listener(badEnvelope));
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(errorHandler).toHaveBeenCalled();
+    });
+  });
+
+  describe('onResponse callback', () => {
+    it('should call onResponse callback for responses', async () => {
+      const onResponse = vi.fn();
+      const newTransport = createMockTransport();
+      const clientWithCallback = new ReferenceClient({
+        transport: newTransport,
+        timeoutMs: 1000,
+        onResponse,
+      });
+
+      const request: RpcRequest = {
+        id: 'callback-test',
+        jsonrpc: '2.0',
+        method: 'wallet/get-config',
+        params: {},
+      };
+
+      const sendPromise = clientWithCallback.send(request);
+
+      await flushMicrotask();
+
+      newTransport.simulateResponse({
+        id: 'callback-test',
+        jsonrpc: '2.0',
+        result: 'callback result',
+      });
+
+      await sendPromise;
+
+      expect(onResponse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          id: 'callback-test',
+          result: 'callback result',
+        }),
+      );
+
+      clientWithCallback.destroy();
+    });
+  });
+});

package/src/reference-client.ts

@@ -0,0 +1,202 @@
+/**
+ * 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, RpcServer, RpcRouter, getLogger } from '@hsuite/native-connect-sdk';
+import type { RpcRequest, RpcResponse, RpcEnvelope } from '@hsuite/native-connect-types';
+import { RpcRequestSchema, RpcErrorSchema, RpcSuccessSchema } 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 class ReferenceClient extends EventEmitter<ReferenceClientEvent | string> {
+  private readonly rpc: RpcClient;
+  private readonly codec = new RpcCodec();
+  private readonly pending = new Map<string | number, (response: RpcResponse) => void>();
+  private readonly timeoutMs: number;
+  private readonly messageListener: (envelope: RpcEnvelope) => void;
+  private readonly server?: RpcServer;
+  private readonly router = new RpcRouter();
+  private readonly logger = getLogger().scoped?.('ReferenceClient') ?? getLogger();
+
+  constructor(private readonly options: ReferenceClientOptions) {
+    super();
+    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<T = unknown>(request: RpcRequest): Promise<RpcResponse<T>> {
+    const id = request.id ?? crypto.randomUUID();
+    const finalRequest: RpcRequest = { ...request, id, timestamp: request.timestamp ?? Date.now() };
+    this.logger.debug('Sending RPC request', { method: finalRequest.method, id: String(id) });
+    const promise = new Promise<RpcResponse<T>>((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 as RpcResponse<T>);
+      });
+    });
+
+    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: string, handler: Parameters<typeof RpcRouter.prototype.register>[1]): void {
+    this.router.register(method, handler);
+  }
+
+  /**
+   * @description Dispose client and cleanup listeners
+   */
+  destroy(): void {
+    this.pending.clear();
+    this.options.transport.offMessage?.(this.messageListener);
+  }
+
+  private async handleEnvelope(envelope: RpcEnvelope): Promise<void> {
+    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 as RpcResponse;
+      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 });
+    }
+  }
+
+  private isRequest(payload: unknown): payload is RpcRequest {
+    return RpcRequestSchema.safeParse(payload).success;
+  }
+
+  private isError(payload: RpcResponse): payload is ReturnType<typeof RpcErrorSchema.parse> {
+    return RpcErrorSchema.safeParse(payload).success;
+  }
+
+  private isSuccess<T>(payload: RpcResponse<T>): payload is RpcResponse<T> & { result: T } {
+    return RpcSuccessSchema.safeParse(payload).success;
+  }
+}

package/tests/e2e-harness.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest';
+import { EndToEndHarness } from '../src/protocol/e2e-harness';
+import { createChannelInvite, encodeChannelInvite } from '@hsuite/native-connect-sdk';
+
+const mockAdapter = {
+  manifest: {
+    metadata: {
+      id: 'mock-ledger',
+      displayName: 'Mock Ledger',
+      description: 'Test ledger adapter',
+      defaultNetworkId: 'mock:testnet',
+      capabilities: {
+        supportsMultiSign: false,
+        supportsScheduledTx: false,
+        supportsSmartContracts: false,
+      },
+    },
+    networks: [{ networkId: 'mock:testnet' }],
+  },
+  initialize: vi.fn(async () => undefined),
+  deriveAccounts: vi.fn(async () => []),
+  sign: vi.fn(async () => ({
+    signature: 'sign',
+    publicKey: 'pk',
+    payloadHash: 'hash',
+    algorithm: 'mock',
+  })),
+} as unknown as Parameters<EndToEndHarness['constructor']>[0]['ledgerAdapter'];
+
+/**
+ * Create a mock channel invite for testing
+ */
+function createMockInvite() {
+  return createChannelInvite({
+    type: 'session',
+    app: {
+      id: 'test-app',
+      name: 'Test App',
+    },
+    context: {
+      ledgerId: 'mock-ledger',
+      networkId: 'mock:testnet',
+    },
+    permissions: [],
+  });
+}
+
+describe('EndToEndHarness', () => {
+  it('establishes a session and allows RPC', async () => {
+    const invite = createMockInvite();
+    const encodedInvite = encodeChannelInvite(invite);
+
+    const harness = new EndToEndHarness({
+      ledgerAdapter: mockAdapter,
+      session: {
+        request: encodedInvite,
+      },
+    });
+
+    const sessionId = await harness.establishSession();
+    expect(sessionId).toBeTypeOf('string');
+    await harness.teardown();
+  });
+});