@metamask/connect-multichain 0.13.0 → 0.15.0

package/dist/src/multichain/utils/analytics.js

@@ -10,27 +10,257 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 /* eslint-disable @typescript-eslint/naming-convention */
 /* eslint-disable @typescript-eslint/no-unused-vars -- Scope type used in JSDoc */
 import { getDappId } from '.';
-import { getPlatformType } from '../../domain';
+import { getPlatformType, RPCInvokeMethodErr } from '../../domain';
+/**
+ * Maximum length of `error_message_sample` after sanitisation. Mirrors the
+ * `maxLength: 200` constraint declared in the analytics-api `api.spec.yml`.
+ */
+const ERROR_MESSAGE_SAMPLE_MAX_LENGTH = 200;
+/**
+ * Patterns scrubbed from `error_message_sample` before it leaves the SDK.
+ * The goal is to surface enough error context for triage in Mixpanel
+ * without leaking PII / wallet addresses / RPC endpoints / large numeric
+ * quantities, across any chain the SDK might route to.
+ *
+ * Order matters. URLs are stripped early so address-shaped path segments
+ * inside URLs aren't re-mangled by later passes. Specific patterns run
+ * before broad ones (e.g. EVM `0x{40}` before the generic long-hex pass)
+ * so the longer / more specific match wins. Bech32 runs before generic
+ * Base58 because the two alphabets partially overlap — Bech32 includes
+ * `0` (which Base58 excludes) and Base58 includes `o`/`i`/`b`/`l` (which
+ * Bech32 excludes) — so running Base58 first can chop off the tail of an
+ * HRP-prefixed Bech32 address at the first `l`/`i`/`o`/`b` and leave the
+ * suffix unscrubbed. Decimal-number scrubbing runs last so it doesn't
+ * fragment hex / Base58 tokens that contain digit runs.
+ */
+const 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>' },
+];
+/**
+ * Sanitises an error message for inclusion in analytics. Strips wallet
+ * addresses (EVM hex, Solana / Bitcoin Base58, Bech32), long hex blobs,
+ * URLs, and large decimal numbers, then truncates to
+ * {@link ERROR_MESSAGE_SAMPLE_MAX_LENGTH} characters. Returns `undefined`
+ * if there's no message to sample.
+ *
+ * @param message - Raw error message
+ * @returns A safe-to-emit short string, or `undefined`
+ */
+export function sanitiseErrorMessage(message) {
+    if (!message) {
+        return undefined;
+    }
+    let sanitised = message;
+    for (const { pattern, replacement } of SANITISE_PATTERNS) {
+        sanitised = sanitised.replace(pattern, replacement);
+    }
+    if (sanitised.length > ERROR_MESSAGE_SAMPLE_MAX_LENGTH) {
+        // Trim and mark as truncated so consumers can tell vs. naturally short
+        // messages. The trailing ellipsis fits inside the maxLength budget.
+        sanitised = `${sanitised.slice(0, ERROR_MESSAGE_SAMPLE_MAX_LENGTH - 1)}…`;
+    }
+    return sanitised;
+}
+/**
+ * Pulls the most informative `code` / `message` pair out of an error,
+ * unwrapping `RPCInvokeMethodErr` so the wallet-side code (e.g. 4001) is
+ * visible to classifiers instead of being hidden behind the SDK's static
+ * `code: 53`. Falls back to the outer error if there is no inner wallet code.
+ *
+ * @param error - The error object to inspect
+ * @returns The most relevant `{ code, message }` pair we can extract
+ */
+function getUnwrappedErrorDetails(error) {
+    var _a, _b, _c, _d;
+    if (typeof error !== 'object' || error === null) {
+        return { code: undefined, message: '' };
+    }
+    if (error instanceof RPCInvokeMethodErr) {
+        return {
+            code: (_a = error.rpcCode) !== null && _a !== void 0 ? _a : error.code,
+            message: (_c = (_b = error.rpcMessage) !== null && _b !== void 0 ? _b : error.message) !== null && _c !== void 0 ? _c : '',
+        };
+    }
+    const errorObj = error;
+    return {
+        code: errorObj.code,
+        message: (_d = errorObj.message) !== null && _d !== void 0 ? _d : '',
+    };
+}
 /**
  * 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
  */
 export function isRejectionError(error) {
-    var _a, _b;
     if (typeof error !== 'object' || error === null) {
         return false;
     }
-    const errorObj = error;
-    const errorCode = errorObj.code;
-    const errorMessage = (_b = (_a = errorObj.message) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== null && _b !== void 0 ? _b : '';
-    return (errorCode === 4001 || // User rejected request (common EIP-1193 code)
-        errorCode === 4100 || // Unauthorized (common rejection code)
+    const { code, message } = getUnwrappedErrorDetails(error);
+    const errorMessage = message.toLowerCase();
+    // EIP-1193 4001 "User Rejected Request" is the canonical rejection code.
+    // Note: 4100 "Unauthorized" is deliberately NOT matched here. On multichain
+    // sessions it's what the CAIP-25 permission layer returns when a method
+    // isn't in the granted scope (the layer rejects it before the method
+    // handler runs). That's a permission/support signal, not a user-driven
+    // rejection — misclassifying it as `_rejected` hides genuine permission
+    // issues from `_failed`.
+    return (code === 4001 ||
         errorMessage.includes('reject') ||
         errorMessage.includes('denied') ||
         errorMessage.includes('cancel') ||
-        errorMessage.includes('user'));
+        // 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'));
+}
+/**
+ * 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
+ */
+export function classifyFailureReason(error) {
+    var _a, _b;
+    if (typeof error !== 'object' || error === null) {
+        return 'unknown';
+    }
+    const errorObj = error;
+    const errorName = (_a = errorObj.name) !== null && _a !== void 0 ? _a : '';
+    const errorMessageRaw = (_b = errorObj.message) !== null && _b !== void 0 ? _b : '';
+    const errorMessage = errorMessageRaw.toLowerCase();
+    // Wallet-side JSON-RPC / EIP-1193 code is the strongest signal we have —
+    // check it before any message-substring heuristics so a wallet error like
+    // `{ code: 4900, message: 'Disconnected' }` doesn't get caught by the
+    // transport-disconnect text match below. Unwraps `RPCInvokeMethodErr` so
+    // the wallet's actual error code is visible.
+    const { code } = getUnwrappedErrorDetails(error);
+    if (typeof code === 'number') {
+        // JSON-RPC 2.0 + EIP-1474 standard codes.
+        if (code === -32601) {
+            return 'wallet_method_unsupported';
+        }
+        if (code === -32602) {
+            return 'wallet_invalid_params';
+        }
+        if (code === -32603) {
+            return 'wallet_internal_error';
+        }
+        // Standard JSON-RPC server error range.
+        if (code <= -32000 && code >= -32099) {
+            return 'wallet_internal_error';
+        }
+        // EIP-1193 named provider codes — handled individually. Codes in the
+        // 1000–4999 range that aren't matched here fall through to `unknown`.
+        if (code === 4100) {
+            // Unauthorized — most commonly fires when a method isn't in the
+            // CAIP-25 scope's granted methods list (the multichain permission
+            // layer rejects it before the method handler runs). Distinct from
+            // a user rejection (4001) and worth tracking separately.
+            return 'wallet_unauthorized';
+        }
+        if (code === 4200) {
+            // Unsupported method — wallet handler exists but explicitly refuses.
+            return 'wallet_method_unsupported';
+        }
+        if (code === 4902) {
+            // Unrecognized chain ID — `wallet_switchEthereumChain` to a chain the
+            // wallet hasn't been told about. MetaMask (extension + mobile) always
+            // sets code 4902 on this error, so we don't need a message-substring
+            // fallback below.
+            return 'unrecognized_chain';
+        }
+        // Anything else in the EIP-1193 / EIP-1474 provider-defined range
+        // (1000–4999) falls through to `unknown` — we can promote specific codes
+        // into their own buckets later as the distribution stabilises, without a
+        // schema migration. Two buckets for "we don't know what this is" adds
+        // noise without insight.
+    }
+    // Transport-layer errors. Two shapes exist:
+    // - `TransportTimeoutError` from `@metamask/multichain-api-client` (used by
+    //   MWP and the warmup paths of the default extension transport). It's a
+    //   subclass of `TransportError` so we match on the name field rather than
+    //   importing the symbol (the type lives in a runtime dependency that the
+    //   analytics utils shouldn't pull in directly).
+    // - A plain `new Error('Request timeout')` thrown by `DefaultTransport`'s
+    //   own setTimeout. Indistinguishable from other errors without the message.
+    if (errorName === 'TransportTimeoutError' ||
+        errorMessageRaw === 'Request timeout' ||
+        errorMessage.includes('timed out') ||
+        errorMessage.includes('timeout')) {
+        return 'transport_timeout';
+    }
+    // Transport disconnect. Narrowed substring set so we don't snag wallet
+    // error messages that happen to contain "disconnect" (e.g. EIP-1193
+    // `4900 Disconnected`, which the wallet-code branch above already routed
+    // to `unknown` per policy).
+    if (errorName === 'TransportError' ||
+        errorMessage.includes('not connected') ||
+        errorMessage.includes('transport disconnect') ||
+        errorMessage.includes('connection lost') ||
+        errorMessage.includes('socket closed')) {
+        return 'transport_disconnect';
+    }
+    return 'unknown';
+}
+/**
+ * Computes the full set of diagnostic properties to attach to a
+ * `mmconnect_*_failed` event from a single error. Combines
+ * {@link classifyFailureReason}, the unwrapped wallet code, and a
+ * sanitised message sample so producer call sites stay a single line.
+ *
+ * @param error - The error to inspect
+ * @returns Diagnostics ready to spread into the event properties
+ */
+export function extractErrorDiagnostics(error) {
+    const failureReason = classifyFailureReason(error);
+    const { code, message } = getUnwrappedErrorDetails(error);
+    const messageSample = sanitiseErrorMessage(message);
+    return Object.assign(Object.assign({ failure_reason: failureReason }, (typeof code === 'number' ? { error_code: code } : {})), (messageSample ? { error_message_sample: messageSample } : {}));
 }
 /**
  * Gets base analytics properties that are common across all events.
@@ -60,21 +290,26 @@ export function getBaseAnalyticsProperties(options, storage) {
  * @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
  */
-export function getWalletActionAnalyticsProperties(options, storage, invokeOptions, transportType) {
+export function getWalletActionAnalyticsProperties(options, storage, invokeOptions, transportType, extra) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a;
         const dappId = getDappId(options.dapp);
         const anonId = yield storage.getAnonId();
-        return {
-            mmconnect_versions: (_a = options.versions) !== null && _a !== void 0 ? _a : {},
-            dapp_id: dappId,
-            method: invokeOptions.request.method,
-            caip_chain_id: invokeOptions.scope,
-            anon_id: anonId,
-            transport_type: transportType,
-        };
+        return Object.assign(Object.assign(Object.assign({ mmconnect_versions: (_a = options.versions) !== null && _a !== void 0 ? _a : {}, dapp_id: dappId, method: invokeOptions.request.method, caip_chain_id: invokeOptions.scope, anon_id: anonId, transport_type: transportType }, ((extra === null || extra === void 0 ? void 0 : extra.failure_reason) ? { failure_reason: extra.failure_reason } : {})), (typeof (extra === null || extra === void 0 ? void 0 : extra.error_code) === 'number'
+            ? { error_code: extra.error_code }
+            : {})), ((extra === null || extra === void 0 ? void 0 : extra.error_message_sample)
+            ? { error_message_sample: extra.error_message_sample }
+            : {}));
     });
 }
 //# sourceMappingURL=analytics.js.map

package/dist/src/multichain/utils/analytics.js.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../../../src/multichain/utils/analytics.ts"],"names":[],"mappings":";;;;;;;;;AAAA,yDAAyD;AACzD,kFAAkF;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,CAAC;AAS9B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,KAA4C,CAAC;IAC9D,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC;IAChC,MAAM,YAAY,GAAG,MAAA,MAAA,QAAQ,CAAC,OAAO,0CAAE,WAAW,EAAE,mCAAI,EAAE,CAAC;IAE3D,OAAO,CACL,SAAS,KAAK,IAAI,IAAI,+CAA+C;QACrE,SAAS,KAAK,IAAI,IAAI,uCAAuC;QAC7D,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC/B,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC/B,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC/B,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAC9B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAgB,0BAA0B,CAC9C,OAA0B,EAC1B,OAAoB;;;QAOpB,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC;QAEzC,OAAO;YACL,kBAAkB,EAAE,MAAA,OAAO,CAAC,QAAQ,mCAAI,EAAE;YAC1C,OAAO,EAAE,MAAM;YACf,QAAQ;YACR,OAAO,EAAE,MAAM;SAChB,CAAC;IACJ,CAAC;CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,UAAgB,kCAAkC,CACtD,OAA0B,EAC1B,OAAoB,EACpB,aAAkC,EAClC,aAA4B;;;QAS5B,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC;QAEzC,OAAO;YACL,kBAAkB,EAAE,MAAA,OAAO,CAAC,QAAQ,mCAAI,EAAE;YAC1C,OAAO,EAAE,MAAM;YACf,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM;YACpC,aAAa,EAAE,aAAa,CAAC,KAAK;YAClC,OAAO,EAAE,MAAM;YACf,cAAc,EAAE,aAAa;SAC9B,CAAC;IACJ,CAAC;CAAA"}
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../../../src/multichain/utils/analytics.ts"],"names":[],"mappings":"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"}

package/dist/types/connect-multichain.d.ts

@@ -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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask/connect-multichain",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Multichain package for MetaMask Connect",
   "keywords": [
     "MetaMask",
@@ -68,7 +68,7 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@metamask/analytics": "^0.4.0",
+    "@metamask/analytics": "^0.6.0",
     "@metamask/mobile-wallet-protocol-core": "^0.4.0",
     "@metamask/mobile-wallet-protocol-dapp-client": "^0.3.0",
     "@metamask/multichain-api-client": "^0.10.1",