@metamask/connect-multichain 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0]
+
+### Added
+
+- Add an `analytics.enabled` option to `createMultichainClient()`. Set it to `false` to disable dapp-side analytics events and omit `analytics.remote_session_id` connection metadata. ([#303](https://github.com/MetaMask/connect-monorepo/pull/303))
+
+## [0.14.0]
+
+### Added
+
+- Attach a `failure_reason` tag to `mmconnect_wallet_action_failed` and `mmconnect_connection_failed` events via a new `classifyFailureReason` helper, distinguishing transport timeouts, transport disconnects, EIP-1193 wallet errors (`4100 wallet_unauthorized`, `4200 wallet_method_unsupported`, `4902 unrecognized_chain`), and JSON-RPC wallet errors (`-32601`, `-32602`, `-32603`, plus the `-32000…-32099` server-error range), with an `unknown` fallback. Schema-side: [`metamask-sdk-analytics-api#31`](https://github.com/consensys-vertical-apps/metamask-sdk-analytics-api/pull/31). ([#290](https://github.com/MetaMask/connect-monorepo/pull/290))
+- Attach `error_code` and `error_message_sample` companion properties to `mmconnect_wallet_action_failed` and `mmconnect_connection_failed`. `error_code` preserves the raw wallet-side JSON-RPC / EIP-1193 code (e.g. `4001`, `-32603`). `error_message_sample` is a sanitised, 200-char-max preview of the original error message, with wallet addresses, long hex blobs, URLs, and large decimal numbers scrubbed. Both fields are optional and only set on the two `*_failed` events. Schema-side: [`metamask-sdk-analytics-api#32`](https://github.com/consensys-vertical-apps/metamask-sdk-analytics-api/pull/32). ([#290](https://github.com/MetaMask/connect-monorepo/pull/290))
+
+### Changed
+
+- Improves QR code scanning reliability. The QR code MWP flow (desktop web and Node.js) now omits the initial `wallet_createSession` request from the deeplink URI, instead sending it as a separate request after the wallet completes the MWP handshake. This results in a shorter deeplink URI and a less dense QR code. The native deeplink (non-QR MWP) flow used on mobile web and React Native is unchanged. ([#295](https://github.com/MetaMask/connect-monorepo/pull/295))
+
+### Fixed
+
+- Tightened `isRejectionError` so `mmconnect_wallet_action_rejected` more accurately reflects user-driven cancellations: it now unwraps `RPCInvokeMethodErr` (so wallet-side codes survive the router's transport-boundary wrapping rather than being masked by the wrapper's `code: 53`), no longer classifies EIP-1193 `4100 Unauthorized` as a rejection (it's a CAIP-25 permission denial, not a user decision), and narrows the bare `"user"` substring match to four explicit phrases — `"user rejected"` / `"user denied"` / `"user cancelled"` / `"user canceled"` — so unrelated messages like Account Abstraction's `"user operation reverted"` no longer count. Net effect: `_rejected` becomes more precise; `_failed` picks up everything `4100` was previously hiding. ([#292](https://github.com/MetaMask/connect-monorepo/pull/292))
+
 ## [0.13.0]
 
 ### Uncategorized
@@ -262,7 +283,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release
 
-[Unreleased]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.13.0...HEAD
+[Unreleased]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.15.0...HEAD
+[0.15.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.14.0...@metamask/connect-multichain@0.15.0
+[0.14.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.13.0...@metamask/connect-multichain@0.14.0
 [0.13.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.12.1...@metamask/connect-multichain@0.13.0
 [0.12.1]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.12.0...@metamask/connect-multichain@0.12.1
 [0.12.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.11.1...@metamask/connect-multichain@0.12.0

package/README.md

@@ -138,25 +138,26 @@ Factory function to create a new Multichain SDK instance.
 
 #### Parameters
 
-| Option                      | Type                                          | Required | Description                                                                                                     |
-| --------------------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| `dapp.name`                 | `string`                                      | Yes      | Name of your dApp                                                                                               |
-| `api.supportedNetworks`     | `RpcUrlsMap`                                  | Yes      | Map of [CAIP-2 chain IDs](https://chainagnostic.org/CAIPs/caip-2) to RPC URLs                                   |
-| `dapp.url`                  | `string`                                      | No       | URL of your dApp                                                                                                |
-| `dapp.iconUrl`              | `string`                                      | No       | Icon URL for your dApp                                                                                          |
-| `dapp.base64Icon`           | `string`                                      | No       | Base64-encoded icon (alternative to iconUrl)                                                                    |
-| `storage`                   | `StoreClient`                                 | No       | Custom storage adapter                                                                                          |
-| `ui.factory`                | `BaseModalFactory`                            | No       | Custom modal factory                                                                                            |
-| `ui.headless`               | `boolean`                                     | No       | Run without UI (for custom QR implementations)                                                                  |
-| `ui.preferExtension`        | `boolean`                                     | No       | Prefer browser extension (default: true)                                                                        |
-| `ui.showInstallModal`       | `boolean`                                     | No       | Show installation modal                                                                                         |
-| `mobile.preferredOpenLink`  | `(deeplink: string, target?: string) => void` | No       | Custom deeplink handler                                                                                         |
-| `mobile.useDeeplink`        | `boolean`                                     | No       | Use `metamask://` instead of universal links                                                                    |
-| `analytics.integrationType` | `string`                                      | No       | Integration type for analytics                                                                                  |
-| `transport.extensionId`     | `string`                                      | No       | Custom extension ID                                                                                             |
-| `transport.onNotification`  | `(notification: unknown) => void`             | No       | Notification handler                                                                                            |
-| `versions`                  | `Partial<ConnectVersions>`                    | No       | Internal: set automatically by `createEVMClient` / `createSolanaClient`. Consumers do not need to provide this. |
-| `debug`                     | `boolean`                                     | No       | Enable debug logging                                                                                            |
+| Option                      | Type                                          | Required | Description                                                                                                                  |
+| --------------------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `dapp.name`                 | `string`                                      | Yes      | Name of your dApp                                                                                                            |
+| `api.supportedNetworks`     | `RpcUrlsMap`                                  | Yes      | Map of [CAIP-2 chain IDs](https://chainagnostic.org/CAIPs/caip-2) to RPC URLs                                                |
+| `dapp.url`                  | `string`                                      | No       | URL of your dApp                                                                                                             |
+| `dapp.iconUrl`              | `string`                                      | No       | Icon URL for your dApp                                                                                                       |
+| `dapp.base64Icon`           | `string`                                      | No       | Base64-encoded icon (alternative to iconUrl)                                                                                 |
+| `storage`                   | `StoreClient`                                 | No       | Custom storage adapter                                                                                                       |
+| `ui.factory`                | `BaseModalFactory`                            | No       | Custom modal factory                                                                                                         |
+| `ui.headless`               | `boolean`                                     | No       | Run without UI (for custom QR implementations)                                                                               |
+| `ui.preferExtension`        | `boolean`                                     | No       | Prefer browser extension (default: true)                                                                                     |
+| `ui.showInstallModal`       | `boolean`                                     | No       | Show installation modal                                                                                                      |
+| `mobile.preferredOpenLink`  | `(deeplink: string, target?: string) => void` | No       | Custom deeplink handler                                                                                                      |
+| `mobile.useDeeplink`        | `boolean`                                     | No       | Use `metamask://` instead of universal links                                                                                 |
+| `analytics.enabled`         | `boolean`                                     | No       | Enables dapp-side analytics. Defaults to `true`; set to `false` to disable analytics events and wallet correlation metadata. |
+| `analytics.integrationType` | `string`                                      | No       | Integration type for analytics                                                                                               |
+| `transport.extensionId`     | `string`                                      | No       | Custom extension ID                                                                                                          |
+| `transport.onNotification`  | `(notification: unknown) => void`             | No       | Notification handler                                                                                                         |
+| `versions`                  | `Partial<ConnectVersions>`                    | No       | Internal: set automatically by `createEVMClient` / `createSolanaClient`. Consumers do not need to provide this.              |
+| `debug`                     | `boolean`                                     | No       | Enable debug logging                                                                                                         |
 
 #### Returns
 

package/dist/browser/es/connect-multichain.d.mts

@@ -406,6 +406,19 @@ type ConnectionRequest = {
 type ConnectVersions = {
     'connect-multichain': string;
 } & Partial<Record<'connect-evm' | 'connect-solana', string>>;
+type AnalyticsOptions = {
+    /**
+     * Whether to enable analytics tracking. Defaults to `true` when omitted.
+     * Set to `false` to disable all analytics event collection.
+     */
+    enabled?: boolean;
+    /**
+     * Identifies the integration surface that instantiated the SDK (e.g. `'direct'`,
+     * `'wagmi'`). Recorded as the `integration_types` global analytics property.
+     * Defaults to `'direct'` when omitted or empty.
+     */
+    integrationType?: string;
+};
 /**
  * Constructor options for creating a Multichain SDK instance.
  *
@@ -422,9 +435,7 @@ type MultichainOptions = {
         supportedNetworks: RpcUrlsMap;
     };
     /** Analytics configuration */
-    analytics?: {
-        integrationType: string;
-    };
+    analytics?: AnalyticsOptions;
     /** Storage client for persisting SDK data */
     storage: StoreClient;
     /** UI configuration options */
@@ -464,6 +475,7 @@ type MultiChainFNOptions = Omit<MultichainOptions, 'storage' | 'ui'> & {
  * with an existing singleton.
  */
 type MergeableMultichainOptions = Omit<MultichainOptions, 'dapp' | 'analytics' | 'storage' | 'api' | 'ui' | 'transport' | 'versions'> & {
+    analytics?: AnalyticsOptions;
     api?: MultichainOptions['api'];
     ui?: Pick<MultichainOptions['ui'], 'headless' | 'preferExtension' | 'showInstallModal'>;
     transport?: Pick<NonNullable<MultichainOptions['transport']>, 'extensionId'>;
@@ -553,7 +565,7 @@ declare abstract class MultichainCore extends EventEmitter<SDKEvents> {
     constructor(options: MultichainOptions);
     /**
      * Merges the given options into the current instance options.
-     * Only the mergeable keys are updated (api.supportedNetworks, versions, ui.*, mobile.*, transport.extensionId, debug).
+     * Only the mergeable keys are updated (api.supportedNetworks, analytics, versions, ui.*, mobile.*, transport.extensionId, debug).
      * The main thing to note is that the value for `dapp` is not merged as it does not make sense for
      * subsequent calls to `createMultichainClient` to have a different `dapp` value.
      * Used when createMultichainClient is called with an existing singleton.
@@ -679,13 +691,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 +734,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 +769,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 AnalyticsOptions, 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 };