@rango-dev/wallets-react 0.0.0-experimental-c6bea4d8-20260930 → 0.0.0-experimental-2938686c-20261012

package/src/events.ts

@@ -0,0 +1,99 @@
+import type { WalletType } from '@hub3js/core';
+import type { Namespace } from '@hub3js/namespaces';
+import type { BlockchainMeta } from 'rango-types';
+
+import { getBlockChainNameFromId } from '@rango-dev/internal-blockchains';
+
+import { WALLET_DETECTED_SKIPPED_IDS } from './hub/constants.js';
+
+export const WalletEventChannel = 'walletEvent';
+
+export enum WalletEventTypes {
+  WALLET_DETECTED = 'walletDetected',
+  WALLET_CONNECT_INITIATED = 'walletConnectInitiated',
+  WALLET_CONNECTED = 'walletConnected',
+  WALLET_CONNECT_FAILED = 'walletConnectFailed',
+  WALLET_DISCONNECTED = 'walletDisconnected',
+}
+
+export type WalletConnectOrigin = 'manual' | 'auto';
+
+type WalletConnectEventPayload = {
+  /** Wallet type id, e.g. `metamask`. */
+  walletName: WalletType;
+  namespace: Namespace;
+  /** Rango blockchain name (e.g. `ETH`), or `null` when it isn't known. */
+  chain: string | null;
+  origin: WalletConnectOrigin;
+};
+
+export type WalletDetectedEventPayload = {
+  walletName: WalletType;
+};
+export type WalletConnectInitiatedEventPayload = WalletConnectEventPayload;
+export type WalletConnectedEventPayload = WalletConnectEventPayload;
+export type WalletConnectFailedEventPayload = WalletConnectEventPayload;
+export type WalletDisconnectedEventPayload = {
+  walletName: WalletType;
+  namespace: Namespace;
+};
+
+type EventData<T extends WalletEventTypes, U> = { type: T; payload: U };
+
+export type WalletEventData =
+  | EventData<WalletEventTypes.WALLET_DETECTED, WalletDetectedEventPayload>
+  | EventData<
+      WalletEventTypes.WALLET_CONNECT_INITIATED,
+      WalletConnectInitiatedEventPayload
+    >
+  | EventData<WalletEventTypes.WALLET_CONNECTED, WalletConnectedEventPayload>
+  | EventData<
+      WalletEventTypes.WALLET_CONNECT_FAILED,
+      WalletConnectFailedEventPayload
+    >
+  | EventData<
+      WalletEventTypes.WALLET_DISCONNECTED,
+      WalletDisconnectedEventPayload
+    >;
+
+export type WalletEvents = {
+  [WalletEventChannel]: WalletEventData;
+};
+
+export interface Emitter<Events extends Record<string, unknown>> {
+  emit<K extends keyof Events>(type: K, event: Events[K]): void;
+}
+
+export type WalletEventEmitter = Emitter<WalletEvents>;
+
+const detectedWallets = new Set<WalletType>();
+
+export function emitWalletDetectedOnce(
+  walletName: WalletType,
+  emitter?: WalletEventEmitter
+): void {
+  if (
+    detectedWallets.has(walletName) ||
+    WALLET_DETECTED_SKIPPED_IDS.includes(walletName)
+  ) {
+    return;
+  }
+  detectedWallets.add(walletName);
+  emitter?.emit(WalletEventChannel, {
+    type: WalletEventTypes.WALLET_DETECTED,
+    payload: { walletName },
+  });
+}
+
+/**
+ * Connect results may carry an EVM chain id (e.g. `0x1`); events always carry a Rango blockchain name.
+ */
+export function toBlockchainName(
+  network: string | null | undefined,
+  allBlockChains: BlockchainMeta[] | undefined
+): string | null {
+  if (!network) {
+    return null;
+  }
+  return getBlockChainNameFromId(network, allBlockChains || []);
+}

package/src/hub/autoConnect.test.ts

@@ -1,6 +1,6 @@
 import type { Hub } from '@hub3js/core';
 
-import { ConnectionErrorType, WalletConnectionError } from '@hub3js/std/utils';
+import { Hub3Error } from '@hub3js/core';
 import { error as logError } from '@rango-dev/logging-core';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
@@ -19,9 +19,8 @@ type FakeNamespace = {
   connect: () => Promise<string[]>;
 };
 
-function unknownConnectionError() {
-  return new WalletConnectionError('Something went wrong', {
-    type: ConnectionErrorType.Unknown,
+function unexpectedError() {
+  return new Hub3Error('PROVIDER_UNEXPECTED', 'Something went wrong', {
     cause: new Error('Something went wrong'),
   });
 }
@@ -79,8 +78,8 @@ describe('autoConnect', () => {
     vi.restoreAllMocks();
   });
 
-  it('report a saved namespace that fails to reconnect with an unknown connection error', async () => {
-    const error = unknownConnectionError();
+  it('report a saved namespace that fails to reconnect with an unexpected error', async () => {
+    const error = unexpectedError();
     const solana = fakeNamespace('Solana', {
       connect: vi.fn(async () => Promise.reject(error)),
     });
@@ -92,8 +91,8 @@ describe('autoConnect', () => {
     expect(logError).toHaveBeenCalledOnce();
     expect(logError).toHaveBeenCalledWith(error, {
       tags: {
-        name: 'WalletConnectionError',
-        type: ConnectionErrorType.Unknown,
+        name: 'Hub3Error',
+        type: 'PROVIDER_UNEXPECTED',
         walletType: WALLET,
         namespace: 'Solana',
         origin: 'auto',
@@ -101,11 +100,45 @@ describe('autoConnect', () => {
     });
   });
 
+  it('report a plain error with the auto origin and no type', async () => {
+    const error = new Error('Before hook failed');
+    const solana = fakeNamespace('Solana', {
+      connect: vi.fn(async () => Promise.reject(error)),
+    });
+    const sui = fakeNamespace('Sui');
+
+    runAutoConnect([solana, sui]);
+    await settle(() => expect(sui.connect).toHaveBeenCalled());
+
+    expect(logError).toHaveBeenCalledOnce();
+    expect(logError).toHaveBeenCalledWith(error, {
+      tags: {
+        name: 'Error',
+        walletType: WALLET,
+        namespace: 'Solana',
+        origin: 'auto',
+      },
+    });
+  });
+
+  it.each(['PROVIDER_USER_REJECTED_REQUEST', 'PROVIDER_LOCKED'] as const)(
+    'skip a namespace that fails with %s',
+    async (type) => {
+      const solana = fakeNamespace('Solana', {
+        connect: vi.fn(async () => Promise.reject(new Hub3Error(type))),
+      });
+      const sui = fakeNamespace('Sui');
+
+      runAutoConnect([solana, sui]);
+      await settle(() => expect(sui.connect).toHaveBeenCalled());
+
+      expect(logError).not.toHaveBeenCalled();
+    }
+  );
+
   it('skip a namespace that fails its eager connect check', async () => {
     const solana = fakeNamespace('Solana', {
-      canEagerConnect: vi.fn(async () =>
-        Promise.reject(unknownConnectionError())
-      ),
+      canEagerConnect: vi.fn(async () => Promise.reject(unexpectedError())),
     });
     const sui = fakeNamespace('Sui');
 
@@ -117,11 +150,11 @@ describe('autoConnect', () => {
   });
 
   it('report only the namespace failure when no namespace connects', async () => {
-    const solana = fakeNamespace('Solana', {
-      connect: vi.fn(async () => Promise.reject(unknownConnectionError())),
-    });
-
-    runAutoConnect([solana]);
+    runAutoConnect([
+      fakeNamespace('Solana', {
+        connect: vi.fn(async () => Promise.reject(unexpectedError())),
+      }),
+    ]);
     await settle(() =>
       expect(console.warn).toHaveBeenCalledWith(
         new Error(`No namespace connected for ${WALLET}`)
@@ -130,9 +163,9 @@ describe('autoConnect', () => {
 
     expect(logError).toHaveBeenCalledOnce();
     expect(logError).toHaveBeenCalledWith(
-      expect.any(WalletConnectionError),
+      expect.any(Hub3Error),
       expect.objectContaining({
-        tags: expect.objectContaining({ namespace: 'Solana' }),
+        tags: expect.objectContaining({ namespace: 'Solana', origin: 'auto' }),
       })
     );
   });

package/src/hub/autoConnect.ts

@@ -7,6 +7,13 @@ import type { Accounts, AccountsWithActiveChain } from '@hub3js/std/types';
 
 import { Result } from 'ts-results';
 
+import {
+  toBlockchainName,
+  WalletEventChannel,
+  type WalletEventEmitter,
+  WalletEventTypes,
+} from '../events.js';
+
 import { HUB_LAST_CONNECTED_WALLETS } from './constants.js';
 import { reportConnectionFailure } from './errors.js';
 import { runSequentiallyWithoutFailure } from './helpers.js';
@@ -14,8 +21,21 @@ import { LastConnectedWalletsFromStorage } from './lastConnectedWallets.js';
 import {
   convertNamespaceNetworkToEvmChainId,
   isEvmNamespace,
+  transformHubResultToLegacyResult,
 } from './utils.js';
 
+function createAutoConnectEventPayload(
+  walletName: WalletType,
+  namespaceInput: NamespaceInputForConnect
+) {
+  return {
+    walletName,
+    namespace: namespaceInput.namespace,
+    chain: namespaceInput.network || null,
+    origin: 'auto' as const,
+  };
+}
+
 function isEvmNamespaceInput(
   namespace: NamespaceInputForConnect
 ): namespace is NamespaceInputForConnect<'EVM'> {
@@ -36,9 +56,10 @@ async function eagerConnect(
   params: {
     getHub: () => Hub;
     allBlockChains: UseAdapterParams['allBlockChains'];
+    emitter?: WalletEventEmitter;
   }
 ) {
-  const { getHub, allBlockChains } = params;
+  const { getHub, allBlockChains, emitter } = params;
   const wallet = getHub().get(type);
   if (!wallet) {
     throw new Error(
@@ -82,8 +103,19 @@ async function eagerConnect(
         } else {
           connectNamespacePromise = async () => namespace.connect();
         }
+        const eventPayload = createAutoConnectEventPayload(type, info);
         try {
-          await connectNamespacePromise();
+          const result = await connectNamespacePromise();
+          emitter?.emit(WalletEventChannel, {
+            type: WalletEventTypes.WALLET_CONNECTED,
+            payload: {
+              ...eventPayload,
+              chain: toBlockchainName(
+                transformHubResultToLegacyResult(result).network,
+                allBlockChains
+              ),
+            },
+          });
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
         } catch (e: any) {
           reportConnectionFailure(e, {
@@ -91,6 +123,10 @@ async function eagerConnect(
             namespace: info.namespace,
             origin: 'auto',
           });
+          emitter?.emit(WalletEventChannel, {
+            type: WalletEventTypes.WALLET_CONNECT_FAILED,
+            payload: eventPayload,
+          });
           /*
            * Since we check for connect failures using `instanceof Error`
            * this check is added here to make sure the thrown error always is an instance of `Error`
@@ -188,8 +224,9 @@ export async function autoConnect(deps: {
   getHub: () => Hub;
   allBlockChains: UseAdapterParams['allBlockChains'];
   wallets?: (WalletType | Provider)[];
+  emitter?: WalletEventEmitter;
 }): Promise<void> {
-  const { getHub, allBlockChains, wallets } = deps;
+  const { getHub, allBlockChains, wallets, emitter } = deps;
   const lastConnectedWallets = lastConnectedWalletsFromStorage.list();
   const walletIds = Object.keys(lastConnectedWallets);
 
@@ -225,9 +262,23 @@ export async function autoConnect(deps: {
         return;
       }
 
+      lastConnectedNamespaces.forEach((namespace) => {
+        emitter?.emit(WalletEventChannel, {
+          type: WalletEventTypes.WALLET_CONNECT_INITIATED,
+          payload: createAutoConnectEventPayload(providerName, namespace),
+        });
+      });
+
       const { successNamespaces, failedNamespaces } =
         await tryRunCanEagerConnect(lastConnectedNamespaces, wallet);
 
+      failedNamespaces.forEach((namespace) => {
+        emitter?.emit(WalletEventChannel, {
+          type: WalletEventTypes.WALLET_CONNECT_FAILED,
+          payload: createAutoConnectEventPayload(providerName, namespace),
+        });
+      });
+
       if (!successNamespaces.length) {
         walletsToRemoveFromPersistence.push(providerName);
         return;
@@ -241,6 +292,7 @@ export async function autoConnect(deps: {
         eagerConnect(providerName, successNamespaces, {
           allBlockChains,
           getHub,
+          emitter,
         }).catch((error) => console.warn(error))
       );
     });

package/src/hub/constants.ts

@@ -1 +1,13 @@
+import { WalletTypes } from '@rango-dev/provider-all';
+
 export const HUB_LAST_CONNECTED_WALLETS = 'hub-v1-last-connected-wallets';
+
+// Wallets that always report themselves installed (hardware wallets and connection protocols).
+export const WALLET_DETECTED_SKIPPED_IDS: string[] = [
+  WalletTypes.LEDGER,
+  WalletTypes.TREZOR,
+  WalletTypes.LEDGER_WALLET,
+  WalletTypes.WALLET_CONNECT_2,
+  WalletTypes.TON_CONNECT,
+  WalletTypes.DEFAULT,
+];

package/src/hub/errors.test.ts

@@ -1,8 +1,4 @@
-import {
-  CONNECTION_ERROR_MESSAGES,
-  ConnectionErrorType,
-  WalletConnectionError,
-} from '@hub3js/std/utils';
+import { Hub3Error } from '@hub3js/core';
 import { error as logError } from '@rango-dev/logging-core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
@@ -18,26 +14,27 @@ describe('reportConnectionFailure', () => {
     namespace: 'EVM',
     origin: 'manual',
   } as const;
+  const context = {
+    walletType: 'metamask',
+    namespace: 'EVM',
+    origin: 'manual',
+  };
 
   beforeEach(() => {
     vi.mocked(logError).mockClear();
   });
 
-  it.each([ConnectionErrorType.Rejected, ConnectionErrorType.Locked])(
-    'drop a %s connection error',
+  it.each(['PROVIDER_USER_REJECTED_REQUEST', 'PROVIDER_LOCKED'] as const)(
+    'drop a %s error',
     (type) => {
-      reportConnectionFailure(
-        new WalletConnectionError(CONNECTION_ERROR_MESSAGES[type], { type }),
-        options
-      );
+      reportConnectionFailure(new Hub3Error(type, 'Declined'), options);
 
       expect(logError).not.toHaveBeenCalled();
     }
   );
 
-  it('log an unknown connection error tagged only with its name, type, wallet, namespace and origin', () => {
-    const error = new WalletConnectionError('Something went wrong', {
-      type: ConnectionErrorType.Unknown,
+  it('log a PROVIDER_UNEXPECTED error tagged only with its name, type, wallet, namespace and origin', () => {
+    const error = new Hub3Error('PROVIDER_UNEXPECTED', 'Something went wrong', {
       cause: new Error('Something went wrong'),
     });
 
@@ -45,26 +42,50 @@ describe('reportConnectionFailure', () => {
 
     expect(logError).toHaveBeenCalledOnce();
     expect(logError).toHaveBeenCalledWith(error, {
-      tags: {
-        name: 'WalletConnectionError',
-        type: ConnectionErrorType.Unknown,
-        walletType: 'metamask',
-        namespace: 'EVM',
-        origin: 'manual',
-      },
+      tags: { name: 'Hub3Error', type: 'PROVIDER_UNEXPECTED', ...context },
     });
   });
 
-  it('drop a plain error', () => {
-    reportConnectionFailure(new Error('Something went wrong'), options);
+  it('log a plain error with its name and no type', () => {
+    const error = new TypeError('Something went wrong');
 
-    expect(logError).not.toHaveBeenCalled();
+    reportConnectionFailure(error, options);
+
+    expect(logError).toHaveBeenCalledOnce();
+    expect(logError).toHaveBeenCalledWith(error, {
+      tags: { name: 'TypeError', ...context },
+    });
   });
 
-  it('drop a thrown value that is not an error', () => {
-    reportConnectionFailure({ code: 4001, message: 'rejected' }, options);
-    reportConnectionFailure('Something went wrong', options);
+  it.each([
+    ['a string', 'Something went wrong', 'Something went wrong'],
+    [
+      "an object's own message",
+      { code: 4001, message: 'rejected' },
+      'rejected',
+    ],
+    [
+      'the fixed message for an object without one',
+      { code: 4001 },
+      'Non-Error value thrown during connect.',
+    ],
+    [
+      'the fixed message for anything else',
+      undefined,
+      'Non-Error value thrown during connect.',
+    ],
+  ])(
+    'wrap a non-error as NonErrorThrown and log it, using %s',
+    (_, value, message) => {
+      reportConnectionFailure(value, options);
 
-    expect(logError).not.toHaveBeenCalled();
-  });
+      expect(logError).toHaveBeenCalledOnce();
+      const [logged, data] = vi.mocked(logError).mock.calls[0];
+      expect(logged).toBeInstanceOf(Error);
+      expect(logged.name).toBe('NonErrorThrown');
+      expect(logged.message).toBe(message);
+      expect(logged.cause).toBe(value);
+      expect(data).toEqual({ tags: { name: 'NonErrorThrown', ...context } });
+    }
+  );
 });

package/src/hub/errors.ts

@@ -1,39 +1,45 @@
+import type { WalletConnectOrigin } from '../events.js';
 import type { WalletType } from '@hub3js/core';
 import type { Namespace } from '@hub3js/namespaces';
 
-import { ConnectionErrorType, WalletConnectionError } from '@hub3js/std/utils';
+import { getErrorMessage, Hub3Error } from '@hub3js/core';
 import { error as logError } from '@rango-dev/logging-core';
 
-type ConnectionOrigin = 'manual' | 'auto';
+const NON_ERROR_THROWN_NAME = 'NonErrorThrown';
+const NON_ERROR_THROWN_MESSAGE = 'Non-Error value thrown during connect.';
 
-// The user caused these failures. It's a drop list, so a type added later is reported.
-const UNREPORTED_CONNECTION_ERROR_TYPES: ConnectionErrorType[] = [
-  ConnectionErrorType.Rejected,
-  ConnectionErrorType.Locked,
-];
+function wrapNonError(value: unknown): Error {
+  const message =
+    typeof value === 'string'
+      ? value
+      : getErrorMessage(value) ?? NON_ERROR_THROWN_MESSAGE;
+  const wrapper = new Error(message, { cause: value });
+  wrapper.name = NON_ERROR_THROWN_NAME;
+  return wrapper;
+}
 
+/*
+ * An allow list: among `Hub3Error`s only `PROVIDER_UNEXPECTED` is logged, so a type added later
+ * (something the user can act on, like a rejection or a locked wallet) stays out of the logs.
+ */
 export function reportConnectionFailure(
   error: unknown,
   options: {
     walletType: WalletType;
     namespace: Namespace;
-    origin: ConnectionOrigin;
+    origin: WalletConnectOrigin;
   }
 ): void {
-  if (
-    !(error instanceof WalletConnectionError) ||
-    UNREPORTED_CONNECTION_ERROR_TYPES.includes(error.type)
-  ) {
+  if (error instanceof Hub3Error) {
+    if (error.type !== 'PROVIDER_UNEXPECTED') {
+      return;
+    }
+    logError(error, {
+      tags: { name: error.name, type: error.type, ...options },
+    });
     return;
   }
 
-  logError(error, {
-    tags: {
-      name: error.name,
-      type: error.type,
-      walletType: options.walletType,
-      namespace: options.namespace,
-      origin: options.origin,
-    },
-  });
+  const reported = error instanceof Error ? error : wrapNonError(error);
+  logError(reported, { tags: { name: reported.name, ...options } });
 }

package/src/hub/helpers.ts

@@ -10,7 +10,6 @@ import {
   CAIP_LITECOIN_CHAIN_ID,
   CAIP_ZCASH_CHAIN_ID,
 } from '@hub3js/bip122';
-import { ConnectionErrorType, WalletConnectionError } from '@hub3js/std/utils';
 import { CAIP_TRON_CHAIN_ID } from '@hub3js/tron';
 import { CAIP_NAMESPACE as CAIP_TON_NAMESPACE } from '@hub3js/tvm';
 import { formatAddressWithNetwork } from '@rango-dev/internal-blockchains';
@@ -182,19 +181,6 @@ export function createQueue(options?: {
   return queueTask;
 }
 
-// Once the user rejects one of a wallet's namespaces, its remaining queued namespaces are abandoned.
-export function removeQueuedNamespacesOnRejection(
-  error: unknown,
-  actions: { removeCurrentKeyFromQueue: () => void }
-) {
-  if (
-    error instanceof WalletConnectionError &&
-    error.type === ConnectionErrorType.Rejected
-  ) {
-    actions.removeCurrentKeyFromQueue();
-  }
-}
-
 export function shouldTryAutoConnect(
   props: Pick<ProviderProps, 'allBlockChains' | 'autoConnect'>
 ): boolean {