@metamask/connect-multichain 0.13.0 → 0.14.0

package/dist/browser/umd/connect-multichain.d.ts

@@ -679,13 +679,42 @@ declare abstract class Modal<Options, Data extends DataType = DataType> {
     set data(data: Data);
 }
 
+/**
+ * Tag describing the cause of a failed wallet action / connection. Surfaced
+ * as the `failure_reason` property on `mmconnect_wallet_action_failed` and
+ * `mmconnect_connection_failed` events so we can distinguish e.g. a transport
+ * timeout from a wallet-side internal error in Mixpanel.
+ *
+ * Intentionally a string union (not a const enum) so callers stay free to
+ * pass through a new bucket; the schema-side property is an open string for
+ * the same reason.
+ */
+type FailureReason = 'transport_timeout' | 'transport_disconnect' | 'wallet_method_unsupported' | 'wallet_invalid_params' | 'wallet_internal_error' | 'wallet_unauthorized' | 'unrecognized_chain' | 'unknown';
 /**
  * Checks if an error represents a user rejection.
  *
+ * Unwraps `RPCInvokeMethodErr` so the wallet's `code: 4001` survives the
+ * SDK's transport-boundary wrapping (the outer error otherwise reports
+ * `code: 53`, which would never match the heuristics here).
+ *
  * @param error - The error object to check
  * @returns True if the error indicates a user rejection, false otherwise
  */
 declare function isRejectionError(error: unknown): boolean;
+/**
+ * Classifies a failed wallet action / connection error into a short tag for
+ * the `failure_reason` analytics property. Caller is expected to have already
+ * established that the error is *not* a user rejection (use `isRejectionError`
+ * for that branching).
+ *
+ * The taxonomy is deliberately producer-side-only — the schema accepts any
+ * string — so we can add buckets here without an API migration. Once the
+ * distribution stabilises we may convert the schema field to a closed enum.
+ *
+ * @param error - The error to classify
+ * @returns A short, snake_case tag describing why the operation failed
+ */
+declare function classifyFailureReason(error: unknown): FailureReason;
 /**
  * Gets analytics properties specific to wallet action events.
  *
@@ -693,15 +722,30 @@ declare function isRejectionError(error: unknown): boolean;
  * @param storage - Storage client for getting anonymous ID
  * @param invokeOptions - The invoke method options containing method and scope
  * @param transportType - The transport type to use for the analytics event
+ * @param extra - Optional event-specific diagnostic properties. Used by
+ * `mmconnect_wallet_action_failed` to attach the {@link ErrorDiagnostics}
+ * bundle (`failure_reason`, `error_code`, `error_message_sample`).
+ * @param extra.failure_reason - A short tag describing why the operation
+ * failed; see `classifyFailureReason` and the `FailureReason` union.
+ * @param extra.error_code - The raw wallet-side error code, if present.
+ * @param extra.error_message_sample - A sanitised, truncated sample of the
+ * original error message.
  * @returns Wallet action analytics properties
  */
-declare function getWalletActionAnalyticsProperties(options: MultichainOptions, storage: StoreClient, invokeOptions: InvokeMethodOptions, transportType: TransportType): Promise<{
+declare function getWalletActionAnalyticsProperties(options: MultichainOptions, storage: StoreClient, invokeOptions: InvokeMethodOptions, transportType: TransportType, extra?: {
+    failure_reason?: FailureReason;
+    error_code?: number;
+    error_message_sample?: string;
+}): Promise<{
     mmconnect_versions: Record<string, string>;
     dapp_id: string;
     method: string;
     caip_chain_id: string;
     anon_id: string;
     transport_type: TransportType;
+    failure_reason?: FailureReason;
+    error_code?: number;
+    error_message_sample?: string;
 }>;
 
 /**
@@ -713,4 +757,4 @@ declare function getVersion(): string;
 
 declare const createMultichainClient: CreateMultichainFN;
 
-export { type ConnectVersions, type ConnectionRequest, type ConnectionStatus, type CreateMultichainFN, type DappSettings, type DataType, type DomainErrorCodes, type Enumerate, type ErrorCodeRange, type ErrorCodes, EventEmitter, type EventTypes, type ExtendedTransport, type InstallWidgetProps, type InvokeMethodOptions, type LoggerNameSpaces, type MergeableMultichainOptions, Modal, type ModalFactoryConnectOptions, type ModalFactoryOptions, MultichainCore, type MultichainOptions, type NotificationCallback, type OTPCode, type OTPCodeWidgetProps, PlatformType, type QRLink, type RPCAPI, type RPCErrorCodes, RPCHttpErr, RPCInvokeMethodErr, RPCReadonlyRequestErr, RPCReadonlyResponseErr, type RPCResponse, RPC_HANDLED_METHODS, type RpcMethod, type RpcUrlsMap, type SDKEvents, SDK_HANDLED_METHODS, type Scope, type StorageErrorCodes, StoreAdapter, StoreClient, type StoreOptions, TransportType, createLogger, createMultichainClient, enableDebug, getInfuraRpcUrls, getPlatformType, getTransportType, getVersion, getWalletActionAnalyticsProperties, hasExtension, infuraRpcUrls, isEnabled, isMetamaskExtensionInstalled, isRejectionError, isSecure };
+export { type ConnectVersions, type ConnectionRequest, type ConnectionStatus, type CreateMultichainFN, type DappSettings, type DataType, type DomainErrorCodes, type Enumerate, type ErrorCodeRange, type ErrorCodes, EventEmitter, type EventTypes, type ExtendedTransport, type FailureReason, type InstallWidgetProps, type InvokeMethodOptions, type LoggerNameSpaces, type MergeableMultichainOptions, Modal, type ModalFactoryConnectOptions, type ModalFactoryOptions, MultichainCore, type MultichainOptions, type NotificationCallback, type OTPCode, type OTPCodeWidgetProps, PlatformType, type QRLink, type RPCAPI, type RPCErrorCodes, RPCHttpErr, RPCInvokeMethodErr, RPCReadonlyRequestErr, RPCReadonlyResponseErr, type RPCResponse, RPC_HANDLED_METHODS, type RpcMethod, type RpcUrlsMap, type SDKEvents, SDK_HANDLED_METHODS, type Scope, type StorageErrorCodes, StoreAdapter, StoreClient, type StoreOptions, TransportType, classifyFailureReason, createLogger, createMultichainClient, enableDebug, getInfuraRpcUrls, getPlatformType, getTransportType, getVersion, getWalletActionAnalyticsProperties, hasExtension, infuraRpcUrls, isEnabled, isMetamaskExtensionInstalled, isRejectionError, isSecure };

package/dist/browser/umd/connect-multichain.js

@@ -700,17 +700,94 @@ var init_ui = __esm({
 });
 
 // src/multichain/utils/analytics.ts
+function sanitiseErrorMessage(message) {
+  if (!message) {
+    return void 0;
+  }
+  let sanitised = message;
+  for (const { pattern, replacement } of SANITISE_PATTERNS) {
+    sanitised = sanitised.replace(pattern, replacement);
+  }
+  if (sanitised.length > ERROR_MESSAGE_SAMPLE_MAX_LENGTH) {
+    sanitised = `${sanitised.slice(0, ERROR_MESSAGE_SAMPLE_MAX_LENGTH - 1)}\u2026`;
+  }
+  return sanitised;
+}
+function getUnwrappedErrorDetails(error) {
+  var _a3, _b, _c, _d;
+  if (typeof error !== "object" || error === null) {
+    return { code: void 0, message: "" };
+  }
+  if (error instanceof RPCInvokeMethodErr) {
+    return {
+      code: (_a3 = error.rpcCode) != null ? _a3 : error.code,
+      message: (_c = (_b = error.rpcMessage) != null ? _b : error.message) != null ? _c : ""
+    };
+  }
+  const errorObj = error;
+  return {
+    code: errorObj.code,
+    message: (_d = errorObj.message) != null ? _d : ""
+  };
+}
 function isRejectionError(error) {
-  var _a3, _b;
   if (typeof error !== "object" || error === null) {
     return false;
   }
+  const { code, message } = getUnwrappedErrorDetails(error);
+  const errorMessage = message.toLowerCase();
+  return code === 4001 || errorMessage.includes("reject") || errorMessage.includes("denied") || errorMessage.includes("cancel") || // Narrow "user …" matches — bare "user" is too greedy (catches Account
+  // Abstraction errors like "user operation reverted").
+  errorMessage.includes("user rejected") || errorMessage.includes("user denied") || errorMessage.includes("user cancelled") || errorMessage.includes("user canceled");
+}
+function classifyFailureReason(error) {
+  var _a3, _b;
+  if (typeof error !== "object" || error === null) {
+    return "unknown";
+  }
   const errorObj = error;
-  const errorCode = errorObj.code;
-  const errorMessage = (_b = (_a3 = errorObj.message) == null ? void 0 : _a3.toLowerCase()) != null ? _b : "";
-  return errorCode === 4001 || // User rejected request (common EIP-1193 code)
-  errorCode === 4100 || // Unauthorized (common rejection code)
-  errorMessage.includes("reject") || errorMessage.includes("denied") || errorMessage.includes("cancel") || errorMessage.includes("user");
+  const errorName = (_a3 = errorObj.name) != null ? _a3 : "";
+  const errorMessageRaw = (_b = errorObj.message) != null ? _b : "";
+  const errorMessage = errorMessageRaw.toLowerCase();
+  const { code } = getUnwrappedErrorDetails(error);
+  if (typeof code === "number") {
+    if (code === -32601) {
+      return "wallet_method_unsupported";
+    }
+    if (code === -32602) {
+      return "wallet_invalid_params";
+    }
+    if (code === -32603) {
+      return "wallet_internal_error";
+    }
+    if (code <= -32e3 && code >= -32099) {
+      return "wallet_internal_error";
+    }
+    if (code === 4100) {
+      return "wallet_unauthorized";
+    }
+    if (code === 4200) {
+      return "wallet_method_unsupported";
+    }
+    if (code === 4902) {
+      return "unrecognized_chain";
+    }
+  }
+  if (errorName === "TransportTimeoutError" || errorMessageRaw === "Request timeout" || errorMessage.includes("timed out") || errorMessage.includes("timeout")) {
+    return "transport_timeout";
+  }
+  if (errorName === "TransportError" || errorMessage.includes("not connected") || errorMessage.includes("transport disconnect") || errorMessage.includes("connection lost") || errorMessage.includes("socket closed")) {
+    return "transport_disconnect";
+  }
+  return "unknown";
+}
+function extractErrorDiagnostics(error) {
+  const failureReason = classifyFailureReason(error);
+  const { code, message } = getUnwrappedErrorDetails(error);
+  const messageSample = sanitiseErrorMessage(message);
+  return __spreadValues(__spreadValues({
+    failure_reason: failureReason
+  }, typeof code === "number" ? { error_code: code } : {}), messageSample ? { error_message_sample: messageSample } : {});
 }
 function getBaseAnalyticsProperties(options, storage) {
   return __async(this, null, function* () {
@@ -726,26 +803,61 @@ function getBaseAnalyticsProperties(options, storage) {
     };
   });
 }
-function getWalletActionAnalyticsProperties(options, storage, invokeOptions, transportType) {
+function getWalletActionAnalyticsProperties(options, storage, invokeOptions, transportType, extra) {
   return __async(this, null, function* () {
     var _a3;
     const dappId = getDappId(options.dapp);
     const anonId = yield storage.getAnonId();
-    return {
+    return __spreadValues(__spreadValues(__spreadValues({
       mmconnect_versions: (_a3 = options.versions) != null ? _a3 : {},
       dapp_id: dappId,
       method: invokeOptions.request.method,
       caip_chain_id: invokeOptions.scope,
       anon_id: anonId,
       transport_type: transportType
-    };
+    }, (extra == null ? void 0 : extra.failure_reason) ? { failure_reason: extra.failure_reason } : {}), typeof (extra == null ? void 0 : extra.error_code) === "number" ? { error_code: extra.error_code } : {}), (extra == null ? void 0 : extra.error_message_sample) ? { error_message_sample: extra.error_message_sample } : {});
   });
 }
+var ERROR_MESSAGE_SAMPLE_MAX_LENGTH, SANITISE_PATTERNS;
 var init_analytics = __esm({
   "src/multichain/utils/analytics.ts"() {
     "use strict";
     init_utils2();
     init_domain();
+    ERROR_MESSAGE_SAMPLE_MAX_LENGTH = 200;
+    SANITISE_PATTERNS = [
+      // EVM-style 20-byte hex addresses (e.g. `0x` + 40 hex chars).
+      { pattern: /0x[a-fA-F0-9]{40}/gu, replacement: "<addr>" },
+      // Other long hex blobs: tx hashes, signatures, raw byte strings, large
+      // hex amounts. 16+ hex chars catches 32-byte hashes/signatures without
+      // snagging EVM method selectors (8 chars) or short hex codes.
+      { pattern: /(?:0x)?[a-fA-F0-9]{16,}/gu, replacement: "<hex>" },
+      // URLs of any scheme up to the first whitespace / quote / closing paren.
+      // Catches RPC endpoints, dapp deeplinks, query strings with secrets.
+      { pattern: /https?:\/\/[^\s"')]+/gu, replacement: "<url>" },
+      // Bech32 addresses: short HRP (1-10 lowercase chars) + `1` separator +
+      // ≥38 chars of Bech32 data alphabet `[ac-hj-np-z02-9]` (excludes the
+      // look-alike chars `b`, `i`, `o`, `1`). Covers Bitcoin SegWit
+      // (`bc1…`/`tb1…`) and Cosmos-SDK chains (`cosmos1…`, `osmo1…`,
+      // `juno1…`, `inj1…`, etc.) without enumerating every HRP. Runs before
+      // the Base58 pattern below — see header comment for why.
+      {
+        pattern: /\b[a-z]{1,10}1[ac-hj-np-z02-9]{38,}\b/gu,
+        replacement: "<addr>"
+      },
+      // Base58 tokens (32+ chars, Base58 alphabet `[1-9A-HJ-NP-Za-km-z]`).
+      // Covers Solana pubkeys (32-44 chars), Solana tx signatures (~88 chars),
+      // and Bitcoin Base58 addresses ≥32 chars. The 32-char floor and `\b`
+      // word boundary keep English words and shorter alphanumerics safe.
+      {
+        pattern: /\b[1-9A-HJ-NP-Za-km-z]{32,}\b/gu,
+        replacement: "<addr>"
+      },
+      // Long decimal numbers — token amounts, gas units, timestamps, lamports.
+      // 10+ digits catches typical chain quantities without affecting JSON-RPC
+      // codes (-32601, 4001, etc.) or short numeric IDs.
+      { pattern: /\d{10,}/gu, replacement: "<num>" }
+    ];
   }
 });
 
@@ -1402,13 +1514,24 @@ var init_mwp = __esm({
                     return resolveConnection();
                   });
                   this.dappClient.on("message", initialConnectionMessageHandler);
+                  const platformType = getPlatformType();
+                  const isQRCodeFlow = [
+                    "web-desktop" /* DesktopWeb */,
+                    "nodejs" /* NonBrowser */
+                  ].includes(platformType);
+                  const initialPayload = {
+                    name: MULTICHAIN_PROVIDER_STREAM_NAME,
+                    data: request
+                  };
                   dappClient.connect({
                     mode: "trusted",
-                    initialPayload: {
-                      name: MULTICHAIN_PROVIDER_STREAM_NAME,
-                      data: request
+                    initialPayload: isQRCodeFlow ? void 0 : initialPayload
+                  }).then(() => __async(this, null, function* () {
+                    if (isQRCodeFlow) {
+                      return dappClient.sendRequest(initialPayload);
                     }
-                  }).catch((error) => {
+                    return void 0;
+                  })).catch((error) => {
                     if (initialConnectionMessageHandler) {
                       this.dappClient.off(
                         "message",
@@ -2068,6 +2191,7 @@ __export(index_browser_exports, {
   StoreAdapter: () => StoreAdapter,
   StoreClient: () => StoreClient,
   TransportType: () => TransportType,
+  classifyFailureReason: () => classifyFailureReason,
   createLogger: () => createLogger,
   createMultichainClient: () => createMultichainClient,
   enableDebug: () => enableDebug,
@@ -2337,7 +2461,7 @@ withAnalyticsTracking_fn = function(options, execute) {
       if (isRejection) {
         yield __privateMethod(this, _RequestRouter_instances, trackWalletActionRejected_fn).call(this, options);
       } else {
-        yield __privateMethod(this, _RequestRouter_instances, trackWalletActionFailed_fn).call(this, options);
+        yield __privateMethod(this, _RequestRouter_instances, trackWalletActionFailed_fn).call(this, options, error);
       }
       if (error instanceof RPCInvokeMethodErr) {
         throw error;
@@ -2372,13 +2496,14 @@ trackWalletActionSucceeded_fn = function(options) {
     import_analytics2.analytics.track("mmconnect_wallet_action_succeeded", props);
   });
 };
-trackWalletActionFailed_fn = function(options) {
+trackWalletActionFailed_fn = function(options, error) {
   return __async(this, null, function* () {
     const props = yield getWalletActionAnalyticsProperties(
       this.config,
       this.config.storage,
       options,
-      this.transportType
+      this.transportType,
+      extractErrorDiagnostics(error)
     );
     import_analytics2.analytics.track("mmconnect_wallet_action_failed", props);
   });
@@ -2822,7 +2947,7 @@ var _MetaMaskConnectMultichain = class _MetaMaskConnectMultichain extends Multic
       versions: __spreadValues({
         // typeof guard needed: Metro (React Native) bundles TS source directly,
         // bypassing the tsup build that substitutes __PACKAGE_VERSION__.
-        "connect-multichain": false ? "unknown" : "0.13.0"
+        "connect-multichain": false ? "unknown" : "0.14.0"
       }, (_f = options.versions) != null ? _f : {})
     });
     super(allOptions);
@@ -3524,9 +3649,9 @@ handleConnection_fn = function(promise, scopes, transportType) {
             transport_type: transportType
           }));
         } else {
-          import_analytics4.analytics.track("mmconnect_connection_failed", __spreadProps(__spreadValues({}, baseProps), {
+          import_analytics4.analytics.track("mmconnect_connection_failed", __spreadValues(__spreadProps(__spreadValues({}, baseProps), {
             transport_type: transportType
-          }));
+          }), extractErrorDiagnostics(error)));
         }
       } catch (e) {
         logger2("Error tracking connection failed/rejected event", error);