@hsuite/native-connect-angular 1.0.0

package/src/lib/transports/chrome-extension-transport.ts

@@ -0,0 +1,246 @@
+/**
+ * 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 chrome-extension-transport.ts
+ * @description
+ * Transport implementation for communicating with HSuite Wallet Chrome Extension.
+ *
+ * This transport uses chrome.runtime.sendMessage() to communicate with the
+ * extension's background service worker, which then routes messages to the wallet.
+ */
+
+import { getLogger } from '@hsuite/native-connect-sdk';
+import type { TransportProvider } from '@hsuite/native-connect-sdk';
+import type { MessageEnvelope } from '@hsuite/native-connect-types';
+
+const logger = getLogger().scoped?.('ChromeExtensionTransport') ?? getLogger();
+
+/**
+ * @interface ChromeExtensionTransportOptions
+ * Configuration options for Chrome Extension transport
+ */
+export interface ChromeExtensionTransportOptions {
+  /**
+   * Unique identifier for this transport instance
+   */
+  id: string;
+}
+
+/**
+ * @class ChromeExtensionTransport
+ *
+ * Transport layer for dApps to communicate with HSuite Wallet Chrome Extension.
+ *
+ * **How it works:**
+ * 1. dApp sends message via window.postMessage() to same-origin
+ * 2. Extension's content script listens and forwards to background via chrome.runtime
+ * 3. Background processes request and sends response back
+ * 4. Response flows back: background → content script → dApp
+ *
+ * **Important**: The dApp NEVER directly accesses chrome.runtime. Only the
+ * extension's content script has chrome.runtime access.
+ *
+ * **Advantages over window-based transport:**
+ * - No popup windows required
+ * - Faster communication (no cross-window messaging)
+ * - Better UX (uses extension popup/sidebar)
+ * - Works across all tabs
+ *
+ * **Detection:**
+ * The extension injects `window.__HSUITE_WALLET_EXTENSION__` flag that dApps
+ * can check before attempting to use this transport.
+ */
+export class ChromeExtensionTransport implements TransportProvider {
+  private readonly transportId: string;
+  private listeners = new Set<(message: MessageEnvelope<unknown>) => void>();
+  private disconnectHandler?: (reason?: any) => void;
+  private isConnected = false;
+  private messageHandler?: (event: MessageEvent) => void;
+
+  /**
+   *
+   * @param options
+   */
+  constructor(private readonly options: ChromeExtensionTransportOptions) {
+    this.transportId = options.id;
+  }
+
+  /**
+   *
+   */
+  get id(): string {
+    return this.transportId;
+  }
+
+  /**
+   * Connect to the extension. Sets up message listeners.
+   *
+   * NOTE: dApps communicate with extensions via window.postMessage() to the
+   * content script. The dApp NEVER directly accesses chrome.runtime - only
+   * the extension's content script has access to chrome.runtime.
+   *
+   * Flow: dApp (window.postMessage) → Content Script (chrome.runtime) → Background
+   */
+  async connect(): Promise<void> {
+    if (this.isConnected) {
+      logger.warn('Already connected', { id: this.transportId });
+      return;
+    }
+
+    // Set up window.postMessage listener for content script communication
+    logger.info('Connecting to extension via window.postMessage', { id: this.transportId });
+    this.setupWindowListener();
+
+    this.isConnected = true;
+    logger.info('Connected to extension', { id: this.transportId });
+  }
+
+  /**
+   * Send a message to the extension via window.postMessage
+   * @param message
+   */
+  async send(message: MessageEnvelope<unknown>): Promise<void> {
+    if (!this.isConnected) {
+      throw new Error('Transport not connected');
+    }
+
+    logger.debug('Sending message to extension via postMessage', {
+      id: this.transportId,
+      topic: message.topic,
+      method: (message.payload as { method?: string })?.method,
+    });
+
+    // Send to content script via postMessage
+    window.postMessage(message, window.location.origin);
+    logger.debug('Message posted to content script', { id: this.transportId });
+  }
+
+  /**
+   * Register a message listener
+   * @param listener
+   */
+  onMessage<TPayload = unknown>(listener: (message: MessageEnvelope<TPayload>) => void): void {
+    this.listeners.add(listener as (message: MessageEnvelope<unknown>) => void);
+  }
+
+  /**
+   * Register a disconnect listener
+   * @param handler
+   */
+  onDisconnect(handler: (reason?: any) => void): void {
+    this.disconnectHandler = handler;
+  }
+
+  /**
+   * Disconnect from the extension
+   */
+  async disconnect(): Promise<void> {
+    if (!this.isConnected) {
+      return;
+    }
+
+    // Remove window message listener
+    if (this.messageHandler) {
+      window.removeEventListener('message', this.messageHandler);
+      this.messageHandler = undefined;
+    }
+
+    this.listeners.clear();
+    this.isConnected = false;
+
+    logger.info('Disconnected from extension', { id: this.transportId });
+    this.disconnectHandler?.();
+  }
+
+  // ========== PRIVATE METHODS ==========
+
+  /**
+   * Set up listener for messages from content script via window.postMessage
+   */
+  private setupWindowListener(): void {
+    this.messageHandler = (event: MessageEvent) => {
+      if (!this.isConnected) {
+        return;
+      }
+
+      // Only process messages from same origin
+      if (event.origin !== window.location.origin) {
+        return;
+      }
+
+      // Only process RPC envelopes
+      const message = event.data;
+      if (!message || typeof message !== 'object' || message.topic !== 'rpc') {
+        return;
+      }
+
+      logger.debug('Received message from content script', {
+        id: this.transportId,
+        method: message.payload?.method,
+      });
+
+      // Deliver to all listeners
+      for (const listener of this.listeners) {
+        try {
+          listener(message);
+        } catch (error) {
+          logger.error('Listener failed', { error });
+        }
+      }
+    };
+
+    window.addEventListener('message', this.messageHandler);
+  }
+}
+
+/**
+ * @function isExtensionInstalled
+ *
+ * Check if HSuite Wallet extension is installed.
+ *
+ * The extension's content script injects a flag into the page that can be
+ * checked to determine if the extension is available.
+ *
+ * **IMPORTANT**: The dApp (web page) does NOT have access to chrome.runtime -
+ * only the extension's content script does. The dApp communicates with the
+ * extension via window.postMessage() → content script → chrome.runtime.
+ *
+ * @returns true if extension is installed and active
+ */
+export function isExtensionInstalled(): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  // Simply check if the extension injected its flag
+  // The flag is set by inject-flags.ts which runs in MAIN world
+  return (
+    (window as any as { __HSUITE_WALLET_EXTENSION__?: boolean }).__HSUITE_WALLET_EXTENSION__ ===
+    true
+  );
+}
+
+/**
+ * @function getExtensionVersion
+ *
+ * Get the version of the installed HSuite Wallet extension.
+ *
+ * @returns Extension version string, or null if not installed
+ */
+export function getExtensionVersion(): string | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  return (
+    (window as any as { __HSUITE_WALLET_VERSION__?: string }).__HSUITE_WALLET_VERSION__ || null
+  );
+}

package/src/lib/utils/index.ts

@@ -0,0 +1,14 @@
+/**
+ * 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
+ */
+
+/**
+ * Utility exports for @hsuite/native-connect-angular
+ */
+export * from './ledger-icons.util';

package/src/lib/utils/ledger-icons.util.ts

@@ -0,0 +1,78 @@
+/**
+ * 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
+ */
+
+/**
+ * @module LedgerIconsUtil
+ * Utilities for getting default icon URLs for ledgers and their native tokens.
+ *
+ * Uses CoinGecko's public CDN for reliable, high-quality token icons.
+ * Shared across wallet and dApp for consistency.
+ */
+
+/**
+ * Default icon URLs for native ledger tokens
+ */
+export const DEFAULT_LEDGER_ICONS: Record<string, string> = {
+  hedera: 'https://assets.coingecko.com/coins/images/3688/standard/hbar.png?1696504364',
+  xrpl: 'https://assets.coingecko.com/coins/images/44/standard/xrp-symbol-white-128.png?1696501442',
+};
+
+/**
+ * Brand colors for each ledger
+ */
+export const LEDGER_COLORS: Record<string, string> = {
+  hedera: '#8259ef',
+  xrpl: '#23292f',
+};
+
+/**
+ * Display names for each ledger
+ */
+export const LEDGER_NAMES: Record<string, string> = {
+  hedera: 'Hedera',
+  xrpl: 'XRP Ledger',
+};
+
+/**
+ * Get the default icon URL for a ledger
+ * @param ledgerId - Ledger identifier (e.g., 'hedera', 'xrpl')
+ * @returns Icon URL or empty string if not found
+ */
+export function getLedgerIcon(ledgerId: string): string {
+  return DEFAULT_LEDGER_ICONS[ledgerId?.toLowerCase()] || '';
+}
+
+/**
+ * Get the brand color for a ledger
+ * @param ledgerId - Ledger identifier
+ * @returns Hex color string or primary color fallback
+ */
+export function getLedgerColor(ledgerId: string): string {
+  return LEDGER_COLORS[ledgerId?.toLowerCase()] || 'var(--ion-color-primary)';
+}
+
+/**
+ * Get the display name for a ledger
+ * @param ledgerId - Ledger identifier
+ * @returns Human-readable ledger name
+ */
+export function getLedgerName(ledgerId: string): string {
+  return LEDGER_NAMES[ledgerId?.toLowerCase()] || ledgerId;
+}
+
+/**
+ * Get token icon URL, falling back to ledger default if not provided
+ * @param tokenIconUrl - Specific token icon URL (optional)
+ * @param ledgerId - Ledger identifier for fallback
+ * @returns Icon URL or empty string
+ */
+export function getTokenIcon(tokenIconUrl: string | undefined, ledgerId: string): string {
+  return tokenIconUrl || getLedgerIcon(ledgerId);
+}

package/test/test-setup.ts

@@ -0,0 +1,21 @@
+/**
+ * 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
+ */
+
+// This file is required by karma.conf.js and loads recursively all the .spec files
+import 'zone.js';
+import 'zone.js/testing';
+import { getTestBed } from '@angular/core/testing';
+import {
+  BrowserDynamicTestingModule,
+  platformBrowserDynamicTesting,
+} from '@angular/platform-browser-dynamic/testing';
+
+// First, initialize the Angular testing environment.
+getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting());

package/test-setup.ts

@@ -0,0 +1,63 @@
+/**
+ * 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
+ */
+
+/**
+ * Test setup for Angular SDK
+ *
+ * This file sets up the test environment for Vitest.
+ * It initializes Angular's TestBed and provides mocks for browser APIs.
+ */
+
+import 'zone.js';
+import 'zone.js/testing';
+
+import { getTestBed } from '@angular/core/testing';
+import {
+  BrowserDynamicTestingModule,
+  platformBrowserDynamicTesting,
+} from '@angular/platform-browser-dynamic/testing';
+import { vi } from 'vitest';
+
+// Initialize Angular test environment
+getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting());
+
+// Mock window.matchMedia for responsive tests
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: (query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(() => true),
+  }),
+});
+
+// Mock crypto if not available
+if (typeof window !== 'undefined' && !window.crypto) {
+  (window as { crypto: unknown }).crypto = {
+    getRandomValues: (arr: Uint8Array) => {
+      for (let i = 0; i < arr.length; i++) {
+        arr[i] = Math.floor(Math.random() * 256);
+      }
+      return arr;
+    },
+    randomUUID: () => {
+      return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+      });
+    },
+  };
+}

package/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.spec.ts", "**/*.test.ts"]
+}
+

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "moduleResolution": "node",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "allowSyntheticDefaultImports": true,
+    "types": ["jasmine", "node"]
+  },
+  "angularCompilerOptions": {
+    "skipLibCheck": true,
+    "strictTemplates": false
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
+}
+

package/tsconfig.spec.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+    "types": [
+      "jasmine",
+      "node"
+    ]
+  },
+  "include": [
+    "test/**/*.spec.ts",
+    "test/**/*.d.ts"
+  ]
+}
+

package/vitest.config.ts

@@ -0,0 +1,48 @@
+/**
+ * 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
+ */
+
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      // Force vitest to resolve to source files, not dist
+      '@hsuite/native-connect-angular': path.resolve(__dirname, 'src/index.ts'),
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    include: ['src/**/*.spec.ts'],
+    setupFiles: ['./test-setup.ts'],
+    deps: {
+      inline: [/@angular/, /@ionic/, /@ngneat/, /@walletconnect/],
+    },
+    server: {
+      deps: {
+        inline: [/@angular/, /@ionic/, /@ngneat/, /@walletconnect/],
+      },
+    },
+    coverage: {
+      enabled: true,
+      provider: 'v8',
+      reporter: ['text', 'lcov', 'html', 'json-summary'],
+      include: ['src/**/*.ts'],
+      // Angular services require TestBed for proper testing - current coverage reflects
+      // tested providers and transaction builders; other services need integration tests
+      statements: 30,
+      branches: 60,
+      functions: 60,
+      lines: 30,
+      exclude: ['**/node_modules/**', '**/dist/**', '**/*.spec.ts', '**/index.ts'],
+    },
+  },
+});