@hsuite/native-connect-client 1.0.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hsuite/native-connect-client",
+  "version": "1.0.0",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "watch": "tsc -p tsconfig.build.json --watch",
+    "lint": "eslint 'src/**/*.ts'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ci": "vitest run --coverage",
+    "docs": "compodoc -p tsconfig.build.json -c ../../compodoc.tier3.json -d dist/docs --name 'Reference Client API' --includes docs"
+  },
+  "dependencies": {
+    "@hsuite/native-connect-sdk": "^1.0.0",
+    "@hsuite/native-connect-types": "^1.0.0",
+    "eventemitter3": "^5.0.1",
+    "@scure/base": "^1.2.6"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./messages": {
+      "types": "@hsuite/native-connect-types/dist/messages.d.ts",
+      "import": "@hsuite/native-connect-types/dist/messages.js"
+    }
+  },
+  "devDependencies": {
+    "@compodoc/compodoc": "^1.1.31",
+    "@types/node": "^22.7.6",
+    "@vitest/coverage-v8": "^1.6.0",
+    "vitest": "^1.6.0",
+    "eslint": "^9.16.0",
+    "typescript": "^5.8.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/handlers/session-handler.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 Session lifecycle RPC handler registration for reference client.
+ * Provides mock session request handling for testing dApp-wallet session flows.
+ *
+ * @module @hsuite/native-connect-client/handlers/session-handler
+ */
+
+import { RpcRouter, getLogger } from '@hsuite/native-connect-sdk';
+import { SessionRequestSchema } from '@hsuite/native-connect-types';
+
+/**
+ * @description Register session lifecycle RPC handlers
+ * @param router - RPC router to register handlers on
+ */
+export const registerSessionHandlers = (router: RpcRouter): void => {
+  const logger = getLogger().scoped?.('ReferenceClient:SessionHandler') ?? getLogger();
+
+  router.register('session/request', async (params) => {
+    const request = SessionRequestSchema.parse(params);
+
+    logger.info('Session request received', {
+      appId: request.appId,
+      appName: request.appName,
+      permissions: request.permissions,
+      timestamp: request.timestamp,
+    });
+
+    return {
+      approved: true,
+      accounts: [],
+      metadata: request.metadata ?? {},
+      ledgerId: request.ledgerId,
+      networkId: request.networkId,
+    };
+  });
+};

package/src/handlers/signing-handler.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 Mock signing RPC handler registration for reference client.
+ * Provides simulated signing responses for testing transaction signing flows.
+ *
+ * @module @hsuite/native-connect-client/handlers/signing-handler
+ */
+
+import { RpcRouter, getLogger } from '@hsuite/native-connect-sdk';
+import { SignPayloadSchema } from '@hsuite/native-connect-types';
+
+/**
+ * @description Register mock signing handlers for testing
+ * @param router - RPC router to register handlers on
+ */
+export const registerSigningHandlers = (router: RpcRouter): void => {
+  const logger = getLogger().scoped?.('ReferenceClient:SigningHandler') ?? getLogger();
+
+  router.register('ledger/sign', async (params) => {
+    const payload = SignPayloadSchema.parse(params);
+
+    logger.info('Simulated signing request', {
+      ledgerId: payload.ledgerId,
+      account: payload.accountAddress,
+      nonce: payload.nonce,
+    });
+
+    return {
+      signature: 'simulated-signature',
+      publicKey: payload.accountAddress,
+      payloadHash: 'hash',
+      algorithm: 'secp256k1',
+    };
+  });
+};

package/src/handlers/wallet-handler.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 Wallet RPC handler registration for reference client.
+ * Provides handlers for account and configuration query methods.
+ *
+ * @module @hsuite/native-connect-client/handlers/wallet-handler
+ */
+
+import { RpcRouter, getLogger } from '@hsuite/native-connect-sdk';
+
+/**
+ * @description Register wallet RPC handlers for account and config queries
+ * @param router - RPC router to register handlers on
+ */
+export const registerWalletHandlers = (router: RpcRouter): void => {
+  const logger = getLogger().scoped?.('ReferenceClient:WalletHandler') ?? getLogger();
+
+  router.register('wallet/accounts', async () => {
+    logger.info('wallet/accounts requested');
+    return { accounts: [] };
+  });
+
+  router.register('wallet/get-config', async () => {
+    logger.info('wallet/get-config requested');
+    return { network: 'xrpl:testnet' };
+  });
+};

package/src/harness/signing-harness.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 Test harness wiring reference client to in-memory transport.
+ * Provides complete RPC client/server setup for testing signing flows.
+ *
+ * @module @hsuite/native-connect-client/harness/signing-harness
+ */
+
+import { ReferenceClient } from '../reference-client';
+import { MemoryTransport } from '../memory-transport';
+import { RpcServer, RpcRouter, RpcCodec } from '@hsuite/native-connect-sdk';
+import type { RpcRequest, RpcResponse, RpcEnvelope } from '@hsuite/native-connect-types';
+
+/**
+ * @class SigningHarness
+ * @description Test harness wiring reference client to in-memory transport.
+ *
+ * Provides:
+ * - Complete RPC client/server setup for testing
+ * - Router-based request handling
+ * - Automatic transport wiring for bidirectional communication
+ */
+export class SigningHarness {
+  private readonly transport = new MemoryTransport();
+  private readonly server: RpcServer;
+  private readonly client: ReferenceClient;
+  private readonly serverListener: (envelope: RpcEnvelope) => void;
+
+  constructor(
+    private readonly router: RpcRouter,
+    onResponse?: (response: RpcResponse) => void,
+  ) {
+    this.server = new RpcServer({
+      codec: new RpcCodec(),
+      transport: {
+        send: (message) => this.transport.send(message, 'server'),
+      },
+      handler: (request) => this.router.handle(request),
+    });
+
+    this.serverListener = (envelope) => {
+      void this.server.handle(envelope);
+    };
+    this.transport.onServerMessage(this.serverListener);
+
+    this.client = new ReferenceClient({
+      transport: {
+        send: (message, from) => this.transport.send(message, from),
+        onMessage: (listener) => this.transport.onMessage(listener),
+        offMessage: (listener) => this.transport.offMessage(listener),
+        onServerMessage: (listener) => this.transport.onServerMessage(listener),
+        offServerMessage: (listener) => this.transport.offServerMessage(listener),
+      },
+      server: this.server,
+      timeoutMs: 2000,
+      onResponse,
+    });
+  }
+
+  get referenceClient(): ReferenceClient {
+    return this.client;
+  }
+
+  /**
+   * @description Send RPC request through harness
+   * @param request - RPC request payload
+   * @returns Promise resolving to RPC response
+   */
+  async send(request: RpcRequest): Promise<RpcResponse> {
+    return this.client.send({ ...request, timestamp: request.timestamp ?? Date.now() });
+  }
+
+  /**
+   * @description Cleanup harness resources
+   */
+  destroy(): void {
+    this.client.destroy();
+    this.transport.offServerMessage(this.serverListener);
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 Public API for the HSuite Connect Client package.
+ * Reference client implementation for HSuite Wallet SDK providing developer-facing
+ * RPC client, in-memory transport for testing, handler registration utilities,
+ * and end-to-end testing harnesses.
+ *
+ * @module @hsuite/native-connect-client
+ * @packageDocumentation
+ */
+export * from './reference-client';
+export * from './query-client';
+export * from './memory-transport';
+export * from './protocol';
+export { PostMessageTransport } from '@hsuite/native-connect-sdk';

package/src/memory-transport-options.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 Configuration options for MemoryTransport network simulation.
+ * Allows simulating real-world network conditions during testing.
+ *
+ * @module @hsuite/native-connect-client/memory-transport-options
+ */
+
+/**
+ * @description Configuration options for MemoryTransport network simulation
+ * @property {number} [latencyMs] - Base network latency in milliseconds
+ * @property {number} [jitterMs] - Random jitter added to latency
+ * @property {number} [dropRate] - Probability (0-1) of message drop
+ */
+export interface MemoryTransportOptions {
+  latencyMs?: number;
+  jitterMs?: number;
+  dropRate?: number;
+}

package/src/memory-transport.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 In-memory transport implementation for testing RPC communication.
+ * Provides isolated message delivery between client and server without network I/O.
+ *
+ * @module @hsuite/native-connect-client/memory-transport
+ */
+
+import { EventEmitter } from 'eventemitter3';
+import type { RpcEnvelope } from '@hsuite/native-connect-types';
+
+function cloneEnvelope(envelope: RpcEnvelope): RpcEnvelope {
+  return JSON.parse(JSON.stringify(envelope)) as RpcEnvelope;
+}
+
+/**
+ * @class MemoryTransport
+ * @description In-memory transport for testing RPC communication.
+ *
+ * Provides:
+ * - Synchronous message delivery between client and server emitters
+ * - Message isolation via deep cloning to prevent mutation
+ * - Pending promise queue for ordered delivery
+ */
+export class MemoryTransport {
+  private readonly clientEmitter = new EventEmitter();
+  private readonly serverEmitter = new EventEmitter();
+  private pending = Promise.resolve();
+
+  /**
+   * @description Send message from client or server
+   * @param message - RPC envelope to send
+   * @param from - Origin of message (client or server)
+   */
+  async send(message: RpcEnvelope, from: 'client' | 'server' = 'client'): Promise<void> {
+    const cloned = cloneEnvelope(message);
+    this.pending = this.pending.then(() => {
+      const target = from === 'client' ? this.serverEmitter : this.clientEmitter;
+      target.emit('message', cloned);
+    });
+    await this.pending;
+  }
+
+  /**
+   * @description Register listener for client-bound messages
+   * @param listener - Message callback
+   */
+  onMessage(listener: (message: RpcEnvelope) => void): void {
+    this.clientEmitter.on('message', listener);
+  }
+
+  /**
+   * @description Unregister client message listener
+   * @param listener - Message callback to remove
+   */
+  offMessage(listener: (message: RpcEnvelope) => void): void {
+    this.clientEmitter.off('message', listener);
+  }
+
+  /**
+   * @description Register listener for server-bound messages
+   * @param listener - Message callback
+   */
+  onServerMessage(listener: (message: RpcEnvelope) => void): void {
+    this.serverEmitter.on('message', listener);
+  }
+
+  /**
+   * @description Unregister server message listener
+   * @param listener - Message callback to remove
+   */
+  offServerMessage(listener: (message: RpcEnvelope) => void): void {
+    this.serverEmitter.off('message', listener);
+  }
+
+  /**
+   * @description Wait for all pending messages to be delivered
+   */
+  async drain(): Promise<void> {
+    await this.pending;
+  }
+}

package/src/protocol/e2e-harness.ts

@@ -0,0 +1,161 @@
+/**
+ * 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';
+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 class EndToEndHarness {
+  readonly client: ReferenceClient;
+  readonly wallet: WalletCore;
+  readonly transport: MemoryTransport;
+
+  constructor(private readonly options: HarnessOptions) {
+    this.transport = new MemoryTransport();
+    const registry = new LedgerRegistry({
+      context: {
+        secureRandom: (length: number) => crypto.getRandomValues(new Uint8Array(length)),
+        logger: () => undefined,
+        httpClient: {
+          async get<T>() {
+            return {} as T;
+          },
+          async post<T>() {
+            return {} as T;
+          },
+        },
+      },
+    });
+    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(): Promise<string> {
+    // 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
+   */
+  private createDefaultInvite(): ChannelInvite {
+    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(): Promise<void> {
+    this.client.destroy();
+    await this.transport.drain();
+  }
+}

package/src/protocol/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 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';

package/src/query-client.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 { RpcRequest, 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 class QueryClient {
+  constructor(private readonly client: ReferenceClient) {}
+
+  /**
+   * @description Retrieve wallet accounts
+   * @returns RPC response containing account list
+   */
+  async getAccounts(): Promise<RpcResponse> {
+    const request: RpcRequest = {
+      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(): Promise<RpcResponse> {
+    const request: RpcRequest = {
+      id: crypto.randomUUID(),
+      jsonrpc: '2.0',
+      method: 'wallet/get-config',
+      params: {},
+      timestamp: Date.now(),
+    };
+
+    return this.client.send(request);
+  }
+}