@rango-dev/widget-embedded 0.0.0-experimental-1624fbb4-20260708 → 0.0.0-experimental-99f1781b-20260920

package/src/libs/connectLogging/connectLogging.ts

@@ -0,0 +1,359 @@
+import type {
+  ConnectFailureCategory,
+  ConnectionAttempt,
+  ConnectionFailureDetails,
+  ConnectLogContext,
+  ConnectLogEvent,
+  ConnectLogTags,
+  FailureCategory,
+  LoggedConnectionAttempt,
+} from './connectLogging.types';
+import type { WalletType } from '@hub3js/core';
+import type { WalletErrorCode } from '@hub3js/std/utils';
+import type {
+  ConnectResult,
+  NamespaceInputForConnect,
+} from '@rango-dev/wallets-react';
+
+import {
+  USER_REJECTION_ERROR_CODE,
+  WALLET_LOCKED_ERROR_CODE,
+} from '@hub3js/std/utils';
+import { error as logError } from '@rango-dev/logging-core';
+import {
+  AutoConnectionAttemptError,
+  WalletConnectionAttemptError,
+} from '@rango-dev/wallets-react';
+
+import {
+  ATTEMPT_ERROR_NAMES,
+  CONNECT_TIMEOUT,
+  CONNECT_TIMEOUT_MESSAGE,
+  CONNECTION_ERROR_NAME,
+  UNREADABLE_FAILURE_MESSAGE,
+  UNREADABLE_FAILURE_NAME,
+} from './connectLogging.constants';
+
+/** An attempt, as read from what it failed with. */
+type FailedAttempt = Omit<LoggedConnectionAttempt, 'requestedNamespaces'> & {
+  errors: unknown[];
+  /** Read from the failure, so any value at all. */
+  requestedNamespaces: unknown[];
+};
+
+/**
+ * Failures come from wallet bundles the widget doesn't control, so any read can
+ * throw. Each field is read on its own, so one nobody can read costs only itself.
+ */
+function readOrStandIn<Value>(read: () => Value, standIn: Value): Value {
+  try {
+    return read();
+  } catch {
+    return standIn;
+  }
+}
+
+/** A field of any value at all, or `standIn` when reading it throws. */
+function readField(value: unknown, field: string, standIn?: unknown): unknown {
+  return readOrStandIn(
+    () =>
+      typeof value === 'object' && value !== null
+        ? (value as Record<string, unknown>)[field]
+        : undefined,
+    standIn
+  );
+}
+
+/** The field when it's a string, `standIn` when it can't be read as one. */
+function readString(value: unknown, field: string): string | undefined;
+function readString(value: unknown, field: string, standIn: string): string;
+function readString(
+  value: unknown,
+  field: string,
+  standIn?: string
+): string | undefined {
+  const found = readField(value, field, standIn);
+
+  return typeof found === 'string' ? found : standIn;
+}
+
+function readCode(value: unknown): WalletErrorCode | undefined {
+  const code = readField(value, 'code');
+
+  return typeof code === 'number' || typeof code === 'string'
+    ? code
+    : undefined;
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+// By name, not `instanceof`: a host may bundle more than one copy of the packages.
+function isConnectionError(failure: unknown): boolean {
+  return readString(failure, 'name') === CONNECTION_ERROR_NAME;
+}
+
+/**
+ * Anything other than an attempt error is read as an attempt with that value as
+ * its only failure, requesting what the caller asked for.
+ */
+function readAttempt(
+  thrown: unknown,
+  attempt: LoggedConnectionAttempt
+): FailedAttempt {
+  const errors = ATTEMPT_ERROR_NAMES.includes(readString(thrown, 'name') ?? '')
+    ? readField(thrown, 'errors')
+    : undefined;
+  if (!Array.isArray(errors)) {
+    return { ...attempt, errors: [thrown] };
+  }
+
+  const requested = readField(thrown, 'requestedNamespaces');
+
+  return {
+    ...attempt,
+    errors,
+    requestedNamespaces: Array.isArray(requested)
+      ? requested
+      : attempt.requestedNamespaces,
+  };
+}
+
+function classifyFailure(failure: unknown): FailureCategory {
+  if (!isConnectionError(failure)) {
+    return 'unknown';
+  }
+
+  // A failure nobody can check against the ignored kinds is worth seeing.
+  const code = readCode(failure);
+  if (code === USER_REJECTION_ERROR_CODE) {
+    return 'rejected';
+  }
+  if (code === WALLET_LOCKED_ERROR_CODE) {
+    return 'locked';
+  }
+
+  return 'wallet';
+}
+
+/**
+ * The category of an attempt's event, or `null` when it has no logged failures.
+ */
+function resolveCategory(
+  categories: FailureCategory[]
+): Exclude<ConnectFailureCategory, 'timeout'> | null {
+  if (categories.includes('unknown')) {
+    return 'unknown';
+  }
+  if (categories.includes('wallet')) {
+    return 'wallet';
+  }
+
+  return null;
+}
+
+/** Sorted, deduplicated and comma-joined. An empty string counts as none. */
+function joinSorted(values: (string | undefined)[]): string | undefined {
+  const present = new Set(values.filter((value): value is string => !!value));
+
+  return present.size ? [...present].sort().join(',') : undefined;
+}
+
+function buildTags(params: {
+  attempt: FailedAttempt;
+  category: ConnectFailureCategory;
+  /** Absent when no namespace can be blamed: the requested ones are tagged. */
+  blamedFailures?: unknown[];
+}): ConnectLogTags {
+  const { attempt, category, blamedFailures } = params;
+  const requested = attempt.requestedNamespaces.map((request) => ({
+    namespace: readString(request, 'namespace'),
+    network: readString(request, 'network'),
+  }));
+  const namespaces = blamedFailures
+    ? blamedFailures.map((failure) => readString(failure, 'namespace'))
+    : requested.map(({ namespace }) => namespace);
+  const networks = requested
+    .filter(({ namespace }) => !!namespace && namespaces.includes(namespace))
+    .map(({ network }) => network);
+
+  const namespacesTag = joinSorted(namespaces);
+  const networkTag = joinSorted(networks);
+
+  return {
+    walletType: attempt.walletType,
+    ...(namespacesTag ? { namespaces: namespacesTag } : {}),
+    ...(networkTag ? { network: networkTag } : {}),
+    trigger: attempt.trigger,
+    category,
+  };
+}
+
+function describeFailure(failure: unknown): ConnectionFailureDetails {
+  const namespace = isConnectionError(failure)
+    ? readString(failure, 'namespace')
+    : undefined;
+  const code = readCode(failure);
+
+  return {
+    ...(namespace !== undefined ? { namespace } : {}),
+    name: readString(failure, 'name', UNREADABLE_FAILURE_NAME),
+    message: readString(failure, 'message', UNREADABLE_FAILURE_MESSAGE),
+    ...(code !== undefined ? { code } : {}),
+  };
+}
+
+function buildContext(attempt: FailedAttempt): ConnectLogContext {
+  return {
+    failures: attempt.errors.map(describeFailure),
+    requestedNamespaces: attempt.requestedNamespaces
+      .map((request) => readString(request, 'namespace'))
+      .filter(isString),
+  };
+}
+
+/**
+ * What the attempt failed with, unchanged. `connect` and auto-connect only ever
+ * fail with errors, but logging-core takes nothing else, so any other value is
+ * logged as the one-failure attempt it's read as.
+ */
+function toLoggedError(
+  thrown: unknown,
+  attempt: LoggedConnectionAttempt
+): Error {
+  if (thrown instanceof Error) {
+    return thrown;
+  }
+
+  const AttemptError =
+    attempt.trigger === 'auto-connect'
+      ? AutoConnectionAttemptError
+      : WalletConnectionAttemptError;
+
+  return new AttemptError({
+    errors: [thrown],
+    requestedNamespaces: attempt.requestedNamespaces,
+  });
+}
+
+/**
+ * Builds the event for an attempt that failed with `thrown`, or `null` when
+ * every failure is a rejection or a locked wallet.
+ */
+function buildConnectFailureEvent(
+  thrown: unknown,
+  attempt: LoggedConnectionAttempt
+): ConnectLogEvent | null {
+  const failedAttempt = readAttempt(thrown, attempt);
+  const categories = failedAttempt.errors.map(classifyFailure);
+  const category = resolveCategory(categories);
+  if (!category) {
+    return null;
+  }
+
+  return {
+    error: toLoggedError(thrown, attempt),
+    tags: buildTags({
+      attempt: failedAttempt,
+      category,
+      blamedFailures:
+        category === 'wallet'
+          ? failedAttempt.errors.filter(
+              (_, index) => categories[index] === 'wallet'
+            )
+          : undefined,
+    }),
+    context: buildContext(failedAttempt),
+  };
+}
+
+function buildTimeoutError(
+  requestedNamespaces: NamespaceInputForConnect[]
+): WalletConnectionAttemptError {
+  return new WalletConnectionAttemptError({
+    errors: [],
+    requestedNamespaces: requestedNamespaces.map(({ namespace, network }) => ({
+      namespace,
+      network,
+    })),
+    message: CONNECT_TIMEOUT_MESSAGE,
+  });
+}
+
+function buildConnectTimeoutEvent(attempt: ConnectionAttempt): ConnectLogEvent {
+  const error = buildTimeoutError(attempt.requestedNamespaces);
+  const timedOut: FailedAttempt = {
+    ...attempt,
+    errors: [],
+    requestedNamespaces: error.requestedNamespaces,
+  };
+
+  return {
+    error,
+    tags: buildTags({ attempt: timedOut, category: 'timeout' }),
+    context: buildContext(timedOut),
+  };
+}
+
+// Logging must never change what the caller sees, so an event that can't be built or sent is dropped.
+function dropIfItThrows(send: () => void): void {
+  try {
+    send();
+  } catch {
+    // Dropped on purpose.
+  }
+}
+
+/** Logs an attempt that failed with `thrown`, unless it's ignored. Never throws. */
+function logConnectFailure(
+  thrown: unknown,
+  attempt: LoggedConnectionAttempt
+): void {
+  dropIfItThrows(() => {
+    const event = buildConnectFailureEvent(thrown, attempt);
+    if (event) {
+      logError(event.error, { tags: event.tags, context: event.context });
+    }
+  });
+}
+
+/** Logs the error of an `AUTO_CONNECT_FAILED` event. Never throws. */
+export function logAutoConnectFailure(
+  walletType: WalletType,
+  thrown: unknown
+): void {
+  logConnectFailure(thrown, {
+    walletType,
+    trigger: 'auto-connect',
+    requestedNamespaces: [],
+  });
+}
+
+/**
+ * Runs an attempt, logs whatever it fails with, and logs a timeout if it's
+ * still pending after 3 minutes. The timer follows the attempt, not a
+ * component, and never cancels it. What `connect` throws is rethrown unchanged.
+ */
+export async function runConnectWithLogging(
+  attempt: ConnectionAttempt,
+  connect: () => Promise<ConnectResult[]>
+): Promise<ConnectResult[]> {
+  const timeoutId = setTimeout(
+    () =>
+      dropIfItThrows(() => {
+        const { error, tags, context } = buildConnectTimeoutEvent(attempt);
+        logError(error, { tags, context });
+      }),
+    CONNECT_TIMEOUT
+  );
+
+  try {
+    return await connect();
+  } catch (thrown) {
+    logConnectFailure(thrown, attempt);
+    throw thrown;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/libs/connectLogging/connectLogging.types.ts

@@ -0,0 +1,70 @@
+import type { WalletType } from '@hub3js/core';
+import type { WalletErrorCode } from '@hub3js/std/utils';
+import type { NamespaceInputForConnect } from '@rango-dev/wallets-react';
+
+/** Where in the widget the user started a connection attempt from. */
+export type ConnectTrigger =
+  | 'wallets-page'
+  | 'confirm-wallets-modal'
+  | 'swap-details-reconnect'
+  | 'swap-details-switch-network'
+  | 'queue-switch-network';
+
+/**
+ * The trigger a logged attempt is tagged with. `auto-connect` is kept out of
+ * `ConnectTrigger`, so nothing can start a timed attempt as auto-connect.
+ */
+export type ConnectLogTrigger = ConnectTrigger | 'auto-connect';
+
+/** The trigger as a prop, declared once for every layer it travels through. */
+export type WithConnectTrigger = { trigger?: ConnectTrigger };
+
+/**
+ * What one connection failure of an attempt is. Rejected and locked failures
+ * are set aside; the others are the attempt's logged failures: `wallet` is a
+ * wallet connection error worth logging, `unknown` is anything else.
+ */
+export type FailureCategory = 'rejected' | 'locked' | 'wallet' | 'unknown';
+
+export type ConnectFailureCategory = 'wallet' | 'unknown' | 'timeout';
+
+/** What the caller knows about an attempt before it settles. */
+export type ConnectionAttempt<Trigger = ConnectTrigger> = {
+  walletType: WalletType;
+  trigger: Trigger;
+  /** In request order. */
+  requestedNamespaces: NamespaceInputForConnect[];
+};
+
+export type LoggedConnectionAttempt = ConnectionAttempt<ConnectLogTrigger>;
+
+/**
+ * One connection failure of an attempt, without anything that identifies the
+ * user.
+ */
+export type ConnectionFailureDetails = {
+  namespace?: string;
+  name?: string;
+  message: string;
+  code?: WalletErrorCode;
+};
+
+export type ConnectLogTags = {
+  walletType: WalletType;
+  namespaces?: string;
+  network?: string;
+  trigger: ConnectLogTrigger;
+  category: ConnectFailureCategory;
+};
+
+export type ConnectLogContext = {
+  failures: ConnectionFailureDetails[];
+  requestedNamespaces: string[];
+};
+
+/** What is logged for one failed connection attempt. */
+export type ConnectLogEvent = {
+  error: Error;
+  tags: ConnectLogTags;
+  context: ConnectLogContext;
+};

package/src/libs/connectLogging/index.ts

@@ -0,0 +1,5 @@
+export { logAutoConnectFailure, runConnectWithLogging } from './connectLogging';
+export type {
+  ConnectTrigger,
+  WithConnectTrigger,
+} from './connectLogging.types';

package/src/pages/WalletsPage.tsx

@@ -99,6 +99,7 @@ export function WalletsPage() {
           <StatefulConnectModal
             id="widget-state-full-connect-modal"
             wallet={selectedWalletToConnect}
+            trigger="wallets-page"
             onClose={() => {
               setSelectedWalletToConnect(undefined);
             }}

package/src/store/AppStore.tsx

@@ -1,4 +1,4 @@
-import type { WidgetConfig } from '../types';
+import type { WidgetConfigWithoutLegacyProviders } from '../types';
 import type { PropsWithChildren } from 'react';
 
 import React, { createContext, useContext, useEffect, useRef } from 'react';
@@ -6,7 +6,9 @@ import React, { createContext, useContext, useEffect, useRef } from 'react';
 import { createAppStore } from './app';
 
 type AppStore = ReturnType<typeof createAppStore>;
-type AppStoreProviderProps = PropsWithChildren<{ config?: WidgetConfig }>;
+type AppStoreProviderProps = PropsWithChildren<{
+  config?: WidgetConfigWithoutLegacyProviders;
+}>;
 
 export const AppStoreContext = createContext<AppStore | null>(null);
 

package/src/store/app.ts

@@ -1,4 +1,7 @@
-import type { WidgetConfig } from '../types';
+import type {
+  WidgetConfig,
+  WidgetConfigWithoutLegacyProviders,
+} from '../types';
 import type { AppStoreState } from './slices/types';
 import type { StateCreator } from 'zustand';
 
@@ -21,7 +24,9 @@ export type StateCreatorWithInitialData<
 
 export type { AppStoreState };
 
-export function createAppStore(initialData?: WidgetConfig) {
+export function createAppStore(
+  initialData?: WidgetConfigWithoutLegacyProviders
+) {
   return create<AppStoreState>()(
     persist(
       (...a) => ({

package/src/store/slices/config.ts

@@ -1,13 +1,20 @@
 import type { DataSlice } from './data';
 import type { SettingsSlice } from './settings';
-import type { WidgetConfig } from '../../types';
+import type {
+  WidgetConfig,
+  WidgetConfigWithoutLegacyProviders,
+} from '../../types';
 import type { StateCreatorWithInitialData } from '../app';
 import type { VersionedProviders } from '@hub3js/core/utils';
 
-import { allProviders as getAllProviders } from '@rango-dev/provider-all';
+import {
+  allProviders as getAllProviders,
+  WalletTypes,
+} from '@rango-dev/provider-all';
 
 import { cacheService } from '../../services/cacheService';
 import {
+  configWalletsToWalletName,
   matchAndGenerateProviders,
   type ProvidersOptions,
 } from '../../utils/providers';
@@ -27,7 +34,7 @@ function makeProvidersOptionsFromConfig(
   return options;
 }
 
-export const DEFAULT_CONFIG: WidgetConfig = {
+export const DEFAULT_CONFIG: WidgetConfigWithoutLegacyProviders = {
   apiKey: '',
   title: undefined,
   multiWallets: true,
@@ -62,13 +69,13 @@ const DEFAULT_CAMPAIGN_MODE: CampaignMode = {
 
 export interface ConfigSlice {
   // What user can set directly.
-  config: WidgetConfig;
+  config: WidgetConfigWithoutLegacyProviders;
   campaignMode: CampaignMode;
   isInCampaignMode: () => boolean;
   getLiquiditySources: () => string[];
   getDisabledLiquiditySources: () => string[];
   excludeLiquiditySources: () => boolean;
-  updateConfig: (config: WidgetConfig) => void;
+  updateConfig: (config: WidgetConfigWithoutLegacyProviders) => void;
   updateCampaignMode: <K extends keyof CampaignMode>(
     name: K,
     value: CampaignMode[K]
@@ -84,36 +91,40 @@ export interface ConfigSlice {
   getAvailableProviders: () => VersionedProviders[];
 }
 
-function generateProviders(config: WidgetConfig) {
-  const options = makeProvidersOptionsFromConfig(config);
-  const envs = {
-    walletconnect2: {
-      WC_PROJECT_ID: options?.walletConnectProjectId || '',
-      DISABLE_MODAL_AND_OPEN_LINK:
-        options?.walletConnectListedDesktopWalletLink,
-    },
-    selectedProviders: config.wallets,
-    tonConnect: options?.tonConnect?.manifestUrl
-      ? { manifestUrl: options?.tonConnect.manifestUrl }
-      : undefined,
-  };
-  const allProviders = getAllProviders(envs);
+function generateProviders(
+  config: WidgetConfigWithoutLegacyProviders
+): VersionedProviders[] {
+  const allProviders = getAllProviders();
   const allBuiltProviders = allProviders.map((build) => build());
 
-  return allBuiltProviders;
+  const providerNames = configWalletsToWalletName(allBuiltProviders);
+
+  const filteredProviders = allBuiltProviders.filter((_, index) => {
+    if (
+      providerNames[index] === WalletTypes.LEDGER_WALLET &&
+      (!config.ledgerWallet?.apiKey || !config.ledgerWallet?.dAppIdentifier)
+    ) {
+      return false;
+    }
+
+    return true;
+  });
+
+  return filteredProviders;
 }
 
 export const createConfigSlice: StateCreatorWithInitialData<
-  WidgetConfig,
+  WidgetConfigWithoutLegacyProviders,
   ConfigSlice & SettingsSlice & DataSlice,
   ConfigSlice
 > = (initialData, set, get) => {
-  const allBuiltProviders = generateProviders({
+  const config: WidgetConfigWithoutLegacyProviders = {
     ...DEFAULT_CONFIG,
     ...initialData,
-  });
+  };
+  const allBuiltProviders = generateProviders(config);
   return {
-    config: { ...DEFAULT_CONFIG, ...initialData },
+    config,
     iframe: DEFAULT_IFRAME_CONFIGS,
     campaignMode: DEFAULT_CAMPAIGN_MODE,
     allProviders: allBuiltProviders,
@@ -141,7 +152,7 @@ export const createConfigSlice: StateCreatorWithInitialData<
     },
 
     // Actions
-    updateConfig: (nextConfig: WidgetConfig) => {
+    updateConfig: (nextConfig: WidgetConfigWithoutLegacyProviders) => {
       const currentConfig = get().config;
       const {
         _tokensMapByTokenHash: tokensMapByTokenHash,

package/src/store/slices/data.test.ts

@@ -1,4 +1,4 @@
-import type { WidgetConfig } from '../../types';
+import type { WidgetConfigWithoutLegacyProviders } from '../../types';
 import type { AppStoreState } from '../app';
 import type { EvmBlockchainMeta, Token } from 'rango-sdk';
 
@@ -18,7 +18,7 @@ let appStoreState: AppStoreState;
 let customTokens: [Token, Token, Token];
 let rangoBlockchain: EvmBlockchainMeta;
 
-const DEFAULT_CONFIG: WidgetConfig = {
+const DEFAULT_CONFIG: WidgetConfigWithoutLegacyProviders = {
   apiKey: '',
   walletConnectProjectId: 'e24844c5deb5193c1c14840a7af6a40b',
   title: undefined,

package/src/test-utils/fixtures.ts

@@ -1,5 +1,9 @@
 import type { AppStoreState } from '../store/app';
-import type { Blockchain, TokenHash, WidgetConfig } from '../types';
+import type {
+  Blockchain,
+  TokenHash,
+  WidgetConfigWithoutLegacyProviders,
+} from '../types';
 import type { BlockchainMeta, EvmBlockchainMeta, Token } from 'rango-sdk';
 
 import { faker } from '@faker-js/faker';
@@ -216,7 +220,7 @@ export function createInitialAppStore() {
 
 export function updateAppStoreConfig(
   appStoreState: AppStoreState,
-  config: Partial<WidgetConfig>
+  config: Partial<WidgetConfigWithoutLegacyProviders>
 ): AppStoreState {
   appStoreState.config = {
     ...appStoreState.config,

package/src/types/config.ts

@@ -1,7 +1,6 @@
-import type { Provider } from '@hub3js/core';
+import type { Provider, WalletType } from '@hub3js/core';
 import type { Language, theme } from '@rango-dev/ui';
-import type { LegacyProviderInterface } from '@rango-dev/wallets-core/legacy';
-import type { WalletType } from '@rango-dev/wallets-shared';
+import type { ProviderInterface } from '@rango-dev/wallets-react';
 import type { Asset } from 'rango-sdk';
 import type { ReactElement } from 'react';
 
@@ -186,6 +185,21 @@ export type TonConnectConfig = {
   manifestUrl?: string;
 };
 
+/**
+ * Configuration for the Ledger wallet integration.
+ *
+ * @property {string} dAppIdentifier - Unique identifier of your dApp, registered with Ledger to authorize the integration.
+ * @property {string} apiKey - API key issued by Ledger, used to authenticate requests from your dApp.
+ * @property {'fatal' | 'error' | 'warn' | 'info' | 'debug'} [loggerLevel] - Verbosity of the Ledger logger.
+ * @property {boolean} [hideButton] - When `true`, hides the built-in Ledger floating button.
+ */
+export type LedgerWalletConfig = {
+  dAppIdentifier: string;
+  apiKey: string;
+  loggerLevel?: 'fatal' | 'error' | 'warn' | 'info' | 'debug';
+  hideButton?: boolean;
+};
+
 /**
  * The type WidgetConfig defines the configuration options for a widget, including API key, affiliate
  * reference, amount, blockchain and token configurations, liquidity sources, wallet types, language,
@@ -254,13 +268,18 @@ export type WidgetConfig = {
   title?: string;
   walletConnectProjectId?: string;
   trezorManifest?: TrezorManifest;
+  ledgerWallet?: LedgerWalletConfig;
   tonConnect?: TonConnectConfig;
   affiliate?: WidgetAffiliate;
   amount?: number;
   from?: BlockchainAndTokenConfig;
   to?: BlockchainAndTokenConfig;
   liquiditySources?: string[];
-  wallets?: (WalletType | LegacyProviderInterface | Provider)[];
+  /**
+   * Passing a `ProviderInterface` is deprecated. Pass a hub `Provider` instead.
+   * Legacy providers will be removed in future versions.
+   */
+  wallets?: (WalletType | ProviderInterface | Provider)[];
   multiWallets?: boolean;
   customDestination?: boolean;
   defaultCustomDestinations?: { [blockchain: string]: string };
@@ -289,3 +308,11 @@ export type WidgetConfig = {
   };
   routing?: Routing;
 };
+
+// TODO: remove this when ProviderInterface gets removed
+export type WidgetConfigWithoutLegacyProviders = WidgetConfig & {
+  wallets?: Exclude<
+    NonNullable<WidgetConfig['wallets']>[number],
+    ProviderInterface
+  >[];
+};