@metamask/snap-networks-utils 1.0.0 → 2.0.0

package/dist/utils/errors/syncError.d.cts

@@ -0,0 +1,60 @@
+/**
+ * A single account synchronization failure, with enough context to understand
+ * which account failed and why.
+ */
+export type AccountSyncFailure = {
+    /** The ID of the account that failed to synchronize. */
+    accountId: string;
+    /** The failure reason, as a human-readable string. */
+    reason: string;
+};
+/**
+ * Maps settled synchronization results to account synchronization failures:
+ * each rejection is attributed to the account ID at the same index
+ * (`Promise.allSettled` preserves order).
+ *
+ * Rejection reasons are stringified with {@link stringifyReason}, so wrapped
+ * errors report their cause as well.
+ *
+ * @param results - The settled synchronization results.
+ * @param accountIds - The account IDs, in the same order as `results`.
+ * @returns The collected failures, in results order.
+ */
+export declare function getSyncFailuresFromSettledResult(results: PromiseSettledResult<unknown>[], accountIds: string[]): AccountSyncFailure[];
+/**
+ * Formats account synchronization failures as a compact, single-line summary.
+ *
+ * The summary is intended to be embedded in the error message of a
+ * `SynchronizationError`: error tracking via `snap_trackError` serializes only
+ * the error's `name`, `message`, `stack`, and `cause`, so any details stored in
+ * other properties (e.g. a `data` field) are lost before reaching Sentry.
+ *
+ * @param failures - The account synchronization failures to format.
+ * @returns A single-line summary of the failures, truncated to keep the
+ * message readable.
+ */
+export declare function formatAccountSyncFailures(failures: AccountSyncFailure[]): string;
+/**
+ * Error thrown when one or more accounts fail to synchronize.
+ *
+ * The failure details are embedded in the message (not only in a property) so
+ * that they survive error tracking: `snap_trackError` serializes only the
+ * error's `name`, `message`, `stack`, and `cause`.
+ */
+export declare class SynchronizationError extends Error {
+    /**
+     * The structured list of account synchronization failures. Useful for logs;
+     * note that it is not preserved by error tracking.
+     */
+    readonly failures: AccountSyncFailure[];
+    /**
+     * Construct a new synchronization error.
+     *
+     * @param message - The error message, e.g. `'Account synchronization failures'`.
+     * @param failures - The per-account failures to append to the message.
+     * @param options - Additional error options.
+     * @param options.cause - The underlying error that caused the synchronization failure, if any.
+     */
+    constructor(message: string, failures?: AccountSyncFailure[], options?: ErrorOptions);
+}
+//# sourceMappingURL=syncError.d.cts.map

package/dist/utils/errors/syncError.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncError.d.cts","sourceRoot":"","sources":["../../../src/utils/errors/syncError.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,EACxC,UAAU,EAAE,MAAM,EAAE,GACnB,kBAAkB,EAAE,CActB;AAeD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,MAAM,CAeR;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAExC;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,kBAAkB,EAAO,EACnC,OAAO,CAAC,EAAE,YAAY;CAWzB"}

package/dist/utils/errors/syncError.d.mts

@@ -0,0 +1,60 @@
+/**
+ * A single account synchronization failure, with enough context to understand
+ * which account failed and why.
+ */
+export type AccountSyncFailure = {
+    /** The ID of the account that failed to synchronize. */
+    accountId: string;
+    /** The failure reason, as a human-readable string. */
+    reason: string;
+};
+/**
+ * Maps settled synchronization results to account synchronization failures:
+ * each rejection is attributed to the account ID at the same index
+ * (`Promise.allSettled` preserves order).
+ *
+ * Rejection reasons are stringified with {@link stringifyReason}, so wrapped
+ * errors report their cause as well.
+ *
+ * @param results - The settled synchronization results.
+ * @param accountIds - The account IDs, in the same order as `results`.
+ * @returns The collected failures, in results order.
+ */
+export declare function getSyncFailuresFromSettledResult(results: PromiseSettledResult<unknown>[], accountIds: string[]): AccountSyncFailure[];
+/**
+ * Formats account synchronization failures as a compact, single-line summary.
+ *
+ * The summary is intended to be embedded in the error message of a
+ * `SynchronizationError`: error tracking via `snap_trackError` serializes only
+ * the error's `name`, `message`, `stack`, and `cause`, so any details stored in
+ * other properties (e.g. a `data` field) are lost before reaching Sentry.
+ *
+ * @param failures - The account synchronization failures to format.
+ * @returns A single-line summary of the failures, truncated to keep the
+ * message readable.
+ */
+export declare function formatAccountSyncFailures(failures: AccountSyncFailure[]): string;
+/**
+ * Error thrown when one or more accounts fail to synchronize.
+ *
+ * The failure details are embedded in the message (not only in a property) so
+ * that they survive error tracking: `snap_trackError` serializes only the
+ * error's `name`, `message`, `stack`, and `cause`.
+ */
+export declare class SynchronizationError extends Error {
+    /**
+     * The structured list of account synchronization failures. Useful for logs;
+     * note that it is not preserved by error tracking.
+     */
+    readonly failures: AccountSyncFailure[];
+    /**
+     * Construct a new synchronization error.
+     *
+     * @param message - The error message, e.g. `'Account synchronization failures'`.
+     * @param failures - The per-account failures to append to the message.
+     * @param options - Additional error options.
+     * @param options.cause - The underlying error that caused the synchronization failure, if any.
+     */
+    constructor(message: string, failures?: AccountSyncFailure[], options?: ErrorOptions);
+}
+//# sourceMappingURL=syncError.d.mts.map

package/dist/utils/errors/syncError.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncError.d.mts","sourceRoot":"","sources":["../../../src/utils/errors/syncError.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,EACxC,UAAU,EAAE,MAAM,EAAE,GACnB,kBAAkB,EAAE,CActB;AAeD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,MAAM,CAeR;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAExC;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,kBAAkB,EAAO,EACnC,OAAO,CAAC,EAAE,YAAY;CAWzB"}

package/dist/utils/errors/syncError.mjs

@@ -0,0 +1,92 @@
+import { stringifyReason } from "./stringifyReason.mjs";
+/**
+ * Maps settled synchronization results to account synchronization failures:
+ * each rejection is attributed to the account ID at the same index
+ * (`Promise.allSettled` preserves order).
+ *
+ * Rejection reasons are stringified with {@link stringifyReason}, so wrapped
+ * errors report their cause as well.
+ *
+ * @param results - The settled synchronization results.
+ * @param accountIds - The account IDs, in the same order as `results`.
+ * @returns The collected failures, in results order.
+ */
+export function getSyncFailuresFromSettledResult(results, accountIds) {
+    const failures = [];
+    results.forEach((result, index) => {
+        const accountId = accountIds[index];
+        if (accountId && result.status === 'rejected') {
+            failures.push({
+                accountId,
+                reason: stringifyReason(result.reason),
+            });
+        }
+    });
+    return failures;
+}
+/**
+ * Maximum number of characters kept from each failure reason. Reasons can be
+ * arbitrarily long (e.g. full network error messages), so they are truncated
+ * to keep the error message readable in Sentry.
+ */
+const MAX_REASON_LENGTH = 300;
+/**
+ * Maximum number of failures listed in the error message. When more accounts
+ * fail, the remaining ones are summarized with a `+N more` suffix.
+ */
+const MAX_LISTED_FAILURES = 10;
+/**
+ * Formats account synchronization failures as a compact, single-line summary.
+ *
+ * The summary is intended to be embedded in the error message of a
+ * `SynchronizationError`: error tracking via `snap_trackError` serializes only
+ * the error's `name`, `message`, `stack`, and `cause`, so any details stored in
+ * other properties (e.g. a `data` field) are lost before reaching Sentry.
+ *
+ * @param failures - The account synchronization failures to format.
+ * @returns A single-line summary of the failures, truncated to keep the
+ * message readable.
+ */
+export function formatAccountSyncFailures(failures) {
+    const listed = failures.slice(0, MAX_LISTED_FAILURES);
+    const details = listed.map((failure) => {
+        const reason = failure.reason.length > MAX_REASON_LENGTH
+            ? `${failure.reason.slice(0, MAX_REASON_LENGTH)}…`
+            : failure.reason;
+        return `${failure.accountId}: ${reason}`;
+    });
+    const remaining = failures.length - listed.length;
+    const suffix = remaining > 0 ? `; +${remaining} more` : '';
+    return `${details.join('; ')}${suffix}`;
+}
+/**
+ * Error thrown when one or more accounts fail to synchronize.
+ *
+ * The failure details are embedded in the message (not only in a property) so
+ * that they survive error tracking: `snap_trackError` serializes only the
+ * error's `name`, `message`, `stack`, and `cause`.
+ */
+export class SynchronizationError extends Error {
+    /**
+     * The structured list of account synchronization failures. Useful for logs;
+     * note that it is not preserved by error tracking.
+     */
+    failures;
+    /**
+     * Construct a new synchronization error.
+     *
+     * @param message - The error message, e.g. `'Account synchronization failures'`.
+     * @param failures - The per-account failures to append to the message.
+     * @param options - Additional error options.
+     * @param options.cause - The underlying error that caused the synchronization failure, if any.
+     */
+    constructor(message, failures = [], options) {
+        const details = failures.length > 0
+            ? ` (${failures.length} failed): ${formatAccountSyncFailures(failures)}`
+            : '';
+        super(`${message}${details}`, options);
+        this.name = 'SynchronizationError';
+        this.failures = failures;
+    }
+}
+//# sourceMappingURL=syncError.mjs.map

package/dist/utils/errors/syncError.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncError.mjs","sourceRoot":"","sources":["../../../src/utils/errors/syncError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,8BAA0B;AAapD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gCAAgC,CAC9C,OAAwC,EACxC,UAAoB;IAEpB,MAAM,QAAQ,GAAyB,EAAE,CAAC;IAE1C,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QAChC,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC9C,QAAQ,CAAC,IAAI,CAAC;gBACZ,SAAS;gBACT,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC;aACvC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B;;;GAGG;AACH,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAA8B;IAE9B,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACrC,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,iBAAiB;YACvC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG;YAClD,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QAErB,OAAO,GAAG,OAAO,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClD,MAAM,MAAM,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAE3D,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C;;;OAGG;IACM,QAAQ,CAAuB;IAExC;;;;;;;OAOG;IACH,YACE,OAAe,EACf,WAAiC,EAAE,EACnC,OAAsB;QAEtB,MAAM,OAAO,GACX,QAAQ,CAAC,MAAM,GAAG,CAAC;YACjB,CAAC,CAAC,KAAK,QAAQ,CAAC,MAAM,aAAa,yBAAyB,CAAC,QAAQ,CAAC,EAAE;YACxE,CAAC,CAAC,EAAE,CAAC;QAET,KAAK,CAAC,GAAG,OAAO,GAAG,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF","sourcesContent":["import { stringifyReason } from './stringifyReason';\n\n/**\n * A single account synchronization failure, with enough context to understand\n * which account failed and why.\n */\nexport type AccountSyncFailure = {\n  /** The ID of the account that failed to synchronize. */\n  accountId: string;\n  /** The failure reason, as a human-readable string. */\n  reason: string;\n};\n\n/**\n * Maps settled synchronization results to account synchronization failures:\n * each rejection is attributed to the account ID at the same index\n * (`Promise.allSettled` preserves order).\n *\n * Rejection reasons are stringified with {@link stringifyReason}, so wrapped\n * errors report their cause as well.\n *\n * @param results - The settled synchronization results.\n * @param accountIds - The account IDs, in the same order as `results`.\n * @returns The collected failures, in results order.\n */\nexport function getSyncFailuresFromSettledResult(\n  results: PromiseSettledResult<unknown>[],\n  accountIds: string[],\n): AccountSyncFailure[] {\n  const failures: AccountSyncFailure[] = [];\n\n  results.forEach((result, index) => {\n    const accountId = accountIds[index];\n    if (accountId && result.status === 'rejected') {\n      failures.push({\n        accountId,\n        reason: stringifyReason(result.reason),\n      });\n    }\n  });\n\n  return failures;\n}\n\n/**\n * Maximum number of characters kept from each failure reason. Reasons can be\n * arbitrarily long (e.g. full network error messages), so they are truncated\n * to keep the error message readable in Sentry.\n */\nconst MAX_REASON_LENGTH = 300;\n\n/**\n * Maximum number of failures listed in the error message. When more accounts\n * fail, the remaining ones are summarized with a `+N more` suffix.\n */\nconst MAX_LISTED_FAILURES = 10;\n\n/**\n * Formats account synchronization failures as a compact, single-line summary.\n *\n * The summary is intended to be embedded in the error message of a\n * `SynchronizationError`: error tracking via `snap_trackError` serializes only\n * the error's `name`, `message`, `stack`, and `cause`, so any details stored in\n * other properties (e.g. a `data` field) are lost before reaching Sentry.\n *\n * @param failures - The account synchronization failures to format.\n * @returns A single-line summary of the failures, truncated to keep the\n * message readable.\n */\nexport function formatAccountSyncFailures(\n  failures: AccountSyncFailure[],\n): string {\n  const listed = failures.slice(0, MAX_LISTED_FAILURES);\n  const details = listed.map((failure) => {\n    const reason =\n      failure.reason.length > MAX_REASON_LENGTH\n        ? `${failure.reason.slice(0, MAX_REASON_LENGTH)}…`\n        : failure.reason;\n\n    return `${failure.accountId}: ${reason}`;\n  });\n\n  const remaining = failures.length - listed.length;\n  const suffix = remaining > 0 ? `; +${remaining} more` : '';\n\n  return `${details.join('; ')}${suffix}`;\n}\n\n/**\n * Error thrown when one or more accounts fail to synchronize.\n *\n * The failure details are embedded in the message (not only in a property) so\n * that they survive error tracking: `snap_trackError` serializes only the\n * error's `name`, `message`, `stack`, and `cause`.\n */\nexport class SynchronizationError extends Error {\n  /**\n   * The structured list of account synchronization failures. Useful for logs;\n   * note that it is not preserved by error tracking.\n   */\n  readonly failures: AccountSyncFailure[];\n\n  /**\n   * Construct a new synchronization error.\n   *\n   * @param message - The error message, e.g. `'Account synchronization failures'`.\n   * @param failures - The per-account failures to append to the message.\n   * @param options - Additional error options.\n   * @param options.cause - The underlying error that caused the synchronization failure, if any.\n   */\n  constructor(\n    message: string,\n    failures: AccountSyncFailure[] = [],\n    options?: ErrorOptions,\n  ) {\n    const details =\n      failures.length > 0\n        ? ` (${failures.length} failed): ${formatAccountSyncFailures(failures)}`\n        : '';\n\n    super(`${message}${details}`, options);\n    this.name = 'SynchronizationError';\n    this.failures = failures;\n  }\n}\n"]}

package/dist/utils/errors/trackError.cjs

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrackError = createTrackError;
+exports.createSnapErrorHandling = createSnapErrorHandling;
+const snaps_sdk_1 = require("@metamask/snaps-sdk");
+const utils_1 = require("@metamask/utils");
+const errors_1 = require("./errors.cjs");
+function defaultPrepareError(error) {
+    return error instanceof Error ? error : (0, utils_1.ensureError)(error);
+}
+function defaultShouldTrack(error) {
+    return !(error instanceof snaps_sdk_1.UserRejectedRequestError);
+}
+/**
+ * Creates a snap-bound error reporter for MetaMask Sentry (`snap_trackError`).
+ *
+ * RPC failures are caught and logged but never rethrown, so the returned function
+ * is safe to call from already-failing error-handling paths.
+ *
+ * @param options - Snap provider accessor, logger, and optional hooks.
+ * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.
+ * @param options.logError - Logger method used when the tracking RPC fails.
+ * @param options.prepareError - Optional error normalizer before Sentry serialization.
+ * @param options.shouldTrack - Optional filter; defaults to skipping `UserRejectedRequestError`.
+ * @returns A function that reports errors to Sentry when {@link ShouldTrackErrorFn} allows it.
+ */
+function createTrackError({ getSnapProvider, logError, prepareError = defaultPrepareError, shouldTrack = defaultShouldTrack, }) {
+    return async (error) => {
+        if (!shouldTrack(error)) {
+            return undefined;
+        }
+        const params = {
+            error: (0, snaps_sdk_1.getJsonError)(prepareError(error)),
+        };
+        try {
+            return await getSnapProvider().request({
+                method: 'snap_trackError',
+                params,
+            });
+        }
+        catch (trackingError) {
+            logError({ error: trackingError }, 'Failed to track error');
+            return undefined;
+        }
+    };
+}
+/**
+ * Creates snap error handling utilities wired with a shared transport and logger setup.
+ *
+ * @param options - Options for both {@link createTrackError} and
+ * {@link createWithCatchAndThrowSnapError}.
+ * @param options.logError - Logger method used for handler and tracking failures.
+ * @param options.normalizeErrorFn - Optional Snap RPC error normalizer for handler boundaries.
+ * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.
+ * @param options.prepareError - Optional error normalizer before Sentry serialization.
+ * @param options.shouldTrack - Optional tracking filter passed to {@link createTrackError}.
+ * @returns Bound {@link createTrackError trackError} and
+ * {@link createWithCatchAndThrowSnapError withCatchAndThrowSnapError} functions.
+ */
+function createSnapErrorHandling({ logError, normalizeErrorFn, getSnapProvider, prepareError, shouldTrack, }) {
+    const trackError = createTrackError({
+        getSnapProvider,
+        logError,
+        prepareError,
+        shouldTrack,
+    });
+    return {
+        trackError,
+        withCatchAndThrowSnapError: (0, errors_1.createWithCatchAndThrowSnapError)({
+            logError,
+            trackError,
+            normalizeErrorFn,
+        }),
+    };
+}
+//# sourceMappingURL=trackError.cjs.map

package/dist/utils/errors/trackError.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackError.cjs","sourceRoot":"","sources":["../../../src/utils/errors/trackError.ts"],"names":[],"mappings":";;AA0EA,4CAyBC;AAeD,0DA6BC;AA/ID,mDAA6E;AAE7E,2CAA8C;AAO9C,yCAA4D;AA4C5D,SAAS,mBAAmB,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAA,mBAAW,EAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,OAAO,CAAC,CAAC,KAAK,YAAY,oCAAwB,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,gBAAgB,CAA8C,EAC5E,eAAe,EACf,QAAQ,EACR,YAAY,GAAG,mBAAmB,EAClC,WAAW,GAAG,kBAAkB,GACG;IACnC,OAAO,KAAK,EAAE,KAAc,EAA+B,EAAE;QAC3D,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,MAAM,GAAqB;YAC/B,KAAK,EAAE,IAAA,wBAAY,EAAC,YAAY,CAAC,KAAK,CAAC,CAAC;SACzC,CAAC;QAEF,IAAI,CAAC;YACH,OAAO,MAAM,eAAe,EAAE,CAAC,OAAO,CAAC;gBACrC,MAAM,EAAE,iBAAiB;gBACzB,MAAM;aACP,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,aAAa,EAAE,CAAC;YACvB,QAAQ,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,uBAAuB,CAAC,CAAC;YAC5D,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,uBAAuB,CAErC,EACA,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,GAC+B;IAM1C,MAAM,UAAU,GAAG,gBAAgB,CAAC;QAClC,eAAe;QACf,QAAQ;QACR,YAAY;QACZ,WAAW;KACZ,CAAC,CAAC;IAEH,OAAO;QACL,UAAU;QACV,0BAA0B,EAAE,IAAA,yCAAgC,EAAC;YAC3D,QAAQ;YACR,UAAU;YACV,gBAAgB;SACjB,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["import { getJsonError, UserRejectedRequestError } from '@metamask/snaps-sdk';\nimport type { TrackErrorParams, TrackErrorResult } from '@metamask/snaps-sdk';\nimport { ensureError } from '@metamask/utils';\n\nimport type {\n  CreateWithCatchAndThrowSnapErrorOptions,\n  LogErrorFn,\n  TrackErrorFn,\n} from './errors';\nimport { createWithCatchAndThrowSnapError } from './errors';\n\n/**\n * Converts a caught value into an {@link Error} before Sentry serialization.\n */\nexport type PrepareErrorForTrackingFn = (error: unknown) => Error;\n\n/**\n * Determines whether an error should be reported through `snap_trackError`.\n */\nexport type ShouldTrackErrorFn = (error: unknown) => boolean;\n\n/**\n * `snap_trackError` request shape from `@metamask/snaps-sdk`.\n */\nexport type SnapTrackErrorRequest = {\n  method: 'snap_trackError';\n  params: TrackErrorParams;\n};\n\n/**\n * Snap provider surface required for {@link createTrackError}, derived from SDK\n * `snap_trackError` types.\n */\nexport type TrackErrorCapableProvider = {\n  request: (\n    args: SnapTrackErrorRequest,\n  ) => Promise<TrackErrorResult | undefined>;\n};\n\nexport type CreateTrackErrorOptions<\n  TProvider extends TrackErrorCapableProvider = TrackErrorCapableProvider,\n> = {\n  getSnapProvider: () => TProvider;\n  logError: LogErrorFn;\n  prepareError?: PrepareErrorForTrackingFn;\n  shouldTrack?: ShouldTrackErrorFn;\n};\n\nexport type CreateSnapErrorHandlingOptions<\n  TProvider extends TrackErrorCapableProvider = TrackErrorCapableProvider,\n> = Omit<CreateWithCatchAndThrowSnapErrorOptions, 'trackError'> &\n  CreateTrackErrorOptions<TProvider>;\n\nfunction defaultPrepareError(error: unknown): Error {\n  return error instanceof Error ? error : ensureError(error);\n}\n\nfunction defaultShouldTrack(error: unknown): boolean {\n  return !(error instanceof UserRejectedRequestError);\n}\n\n/**\n * Creates a snap-bound error reporter for MetaMask Sentry (`snap_trackError`).\n *\n * RPC failures are caught and logged but never rethrown, so the returned function\n * is safe to call from already-failing error-handling paths.\n *\n * @param options - Snap provider accessor, logger, and optional hooks.\n * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.\n * @param options.logError - Logger method used when the tracking RPC fails.\n * @param options.prepareError - Optional error normalizer before Sentry serialization.\n * @param options.shouldTrack - Optional filter; defaults to skipping `UserRejectedRequestError`.\n * @returns A function that reports errors to Sentry when {@link ShouldTrackErrorFn} allows it.\n */\nexport function createTrackError<TProvider extends TrackErrorCapableProvider>({\n  getSnapProvider,\n  logError,\n  prepareError = defaultPrepareError,\n  shouldTrack = defaultShouldTrack,\n}: CreateTrackErrorOptions<TProvider>): TrackErrorFn {\n  return async (error: unknown): Promise<string | undefined> => {\n    if (!shouldTrack(error)) {\n      return undefined;\n    }\n\n    const params: TrackErrorParams = {\n      error: getJsonError(prepareError(error)),\n    };\n\n    try {\n      return await getSnapProvider().request({\n        method: 'snap_trackError',\n        params,\n      });\n    } catch (trackingError) {\n      logError({ error: trackingError }, 'Failed to track error');\n      return undefined;\n    }\n  };\n}\n\n/**\n * Creates snap error handling utilities wired with a shared transport and logger setup.\n *\n * @param options - Options for both {@link createTrackError} and\n * {@link createWithCatchAndThrowSnapError}.\n * @param options.logError - Logger method used for handler and tracking failures.\n * @param options.normalizeErrorFn - Optional Snap RPC error normalizer for handler boundaries.\n * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.\n * @param options.prepareError - Optional error normalizer before Sentry serialization.\n * @param options.shouldTrack - Optional tracking filter passed to {@link createTrackError}.\n * @returns Bound {@link createTrackError trackError} and\n * {@link createWithCatchAndThrowSnapError withCatchAndThrowSnapError} functions.\n */\nexport function createSnapErrorHandling<\n  TProvider extends TrackErrorCapableProvider,\n>({\n  logError,\n  normalizeErrorFn,\n  getSnapProvider,\n  prepareError,\n  shouldTrack,\n}: CreateSnapErrorHandlingOptions<TProvider>): {\n  trackError: TrackErrorFn;\n  withCatchAndThrowSnapError: ReturnType<\n    typeof createWithCatchAndThrowSnapError\n  >;\n} {\n  const trackError = createTrackError({\n    getSnapProvider,\n    logError,\n    prepareError,\n    shouldTrack,\n  });\n\n  return {\n    trackError,\n    withCatchAndThrowSnapError: createWithCatchAndThrowSnapError({\n      logError,\n      trackError,\n      normalizeErrorFn,\n    }),\n  };\n}\n"]}

package/dist/utils/errors/trackError.d.cts

@@ -0,0 +1,64 @@
+import type { TrackErrorParams, TrackErrorResult } from "@metamask/snaps-sdk";
+import type { CreateWithCatchAndThrowSnapErrorOptions, LogErrorFn, TrackErrorFn } from "./errors.cjs";
+import { createWithCatchAndThrowSnapError } from "./errors.cjs";
+/**
+ * Converts a caught value into an {@link Error} before Sentry serialization.
+ */
+export type PrepareErrorForTrackingFn = (error: unknown) => Error;
+/**
+ * Determines whether an error should be reported through `snap_trackError`.
+ */
+export type ShouldTrackErrorFn = (error: unknown) => boolean;
+/**
+ * `snap_trackError` request shape from `@metamask/snaps-sdk`.
+ */
+export type SnapTrackErrorRequest = {
+    method: 'snap_trackError';
+    params: TrackErrorParams;
+};
+/**
+ * Snap provider surface required for {@link createTrackError}, derived from SDK
+ * `snap_trackError` types.
+ */
+export type TrackErrorCapableProvider = {
+    request: (args: SnapTrackErrorRequest) => Promise<TrackErrorResult | undefined>;
+};
+export type CreateTrackErrorOptions<TProvider extends TrackErrorCapableProvider = TrackErrorCapableProvider> = {
+    getSnapProvider: () => TProvider;
+    logError: LogErrorFn;
+    prepareError?: PrepareErrorForTrackingFn;
+    shouldTrack?: ShouldTrackErrorFn;
+};
+export type CreateSnapErrorHandlingOptions<TProvider extends TrackErrorCapableProvider = TrackErrorCapableProvider> = Omit<CreateWithCatchAndThrowSnapErrorOptions, 'trackError'> & CreateTrackErrorOptions<TProvider>;
+/**
+ * Creates a snap-bound error reporter for MetaMask Sentry (`snap_trackError`).
+ *
+ * RPC failures are caught and logged but never rethrown, so the returned function
+ * is safe to call from already-failing error-handling paths.
+ *
+ * @param options - Snap provider accessor, logger, and optional hooks.
+ * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.
+ * @param options.logError - Logger method used when the tracking RPC fails.
+ * @param options.prepareError - Optional error normalizer before Sentry serialization.
+ * @param options.shouldTrack - Optional filter; defaults to skipping `UserRejectedRequestError`.
+ * @returns A function that reports errors to Sentry when {@link ShouldTrackErrorFn} allows it.
+ */
+export declare function createTrackError<TProvider extends TrackErrorCapableProvider>({ getSnapProvider, logError, prepareError, shouldTrack, }: CreateTrackErrorOptions<TProvider>): TrackErrorFn;
+/**
+ * Creates snap error handling utilities wired with a shared transport and logger setup.
+ *
+ * @param options - Options for both {@link createTrackError} and
+ * {@link createWithCatchAndThrowSnapError}.
+ * @param options.logError - Logger method used for handler and tracking failures.
+ * @param options.normalizeErrorFn - Optional Snap RPC error normalizer for handler boundaries.
+ * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.
+ * @param options.prepareError - Optional error normalizer before Sentry serialization.
+ * @param options.shouldTrack - Optional tracking filter passed to {@link createTrackError}.
+ * @returns Bound {@link createTrackError trackError} and
+ * {@link createWithCatchAndThrowSnapError withCatchAndThrowSnapError} functions.
+ */
+export declare function createSnapErrorHandling<TProvider extends TrackErrorCapableProvider>({ logError, normalizeErrorFn, getSnapProvider, prepareError, shouldTrack, }: CreateSnapErrorHandlingOptions<TProvider>): {
+    trackError: TrackErrorFn;
+    withCatchAndThrowSnapError: ReturnType<typeof createWithCatchAndThrowSnapError>;
+};
+//# sourceMappingURL=trackError.d.cts.map

package/dist/utils/errors/trackError.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackError.d.cts","sourceRoot":"","sources":["../../../src/utils/errors/trackError.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,4BAA4B;AAG9E,OAAO,KAAK,EACV,uCAAuC,EACvC,UAAU,EACV,YAAY,EACb,qBAAiB;AAClB,OAAO,EAAE,gCAAgC,EAAE,qBAAiB;AAE5D;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,gBAAgB,CAAC;CAC1B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,CACP,IAAI,EAAE,qBAAqB,KACxB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,uBAAuB,CACjC,SAAS,SAAS,yBAAyB,GAAG,yBAAyB,IACrE;IACF,eAAe,EAAE,MAAM,SAAS,CAAC;IACjC,QAAQ,EAAE,UAAU,CAAC;IACrB,YAAY,CAAC,EAAE,yBAAyB,CAAC;IACzC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,8BAA8B,CACxC,SAAS,SAAS,yBAAyB,GAAG,yBAAyB,IACrE,IAAI,CAAC,uCAAuC,EAAE,YAAY,CAAC,GAC7D,uBAAuB,CAAC,SAAS,CAAC,CAAC;AAUrC;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,SAAS,yBAAyB,EAAE,EAC5E,eAAe,EACf,QAAQ,EACR,YAAkC,EAClC,WAAgC,GACjC,EAAE,uBAAuB,CAAC,SAAS,CAAC,GAAG,YAAY,CAoBnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,SAAS,yBAAyB,EAC3C,EACA,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,GACZ,EAAE,8BAA8B,CAAC,SAAS,CAAC,GAAG;IAC7C,UAAU,EAAE,YAAY,CAAC;IACzB,0BAA0B,EAAE,UAAU,CACpC,OAAO,gCAAgC,CACxC,CAAC;CACH,CAgBA"}

package/dist/utils/errors/trackError.d.mts

@@ -0,0 +1,64 @@
+import type { TrackErrorParams, TrackErrorResult } from "@metamask/snaps-sdk";
+import type { CreateWithCatchAndThrowSnapErrorOptions, LogErrorFn, TrackErrorFn } from "./errors.mjs";
+import { createWithCatchAndThrowSnapError } from "./errors.mjs";
+/**
+ * Converts a caught value into an {@link Error} before Sentry serialization.
+ */
+export type PrepareErrorForTrackingFn = (error: unknown) => Error;
+/**
+ * Determines whether an error should be reported through `snap_trackError`.
+ */
+export type ShouldTrackErrorFn = (error: unknown) => boolean;
+/**
+ * `snap_trackError` request shape from `@metamask/snaps-sdk`.
+ */
+export type SnapTrackErrorRequest = {
+    method: 'snap_trackError';
+    params: TrackErrorParams;
+};
+/**
+ * Snap provider surface required for {@link createTrackError}, derived from SDK
+ * `snap_trackError` types.
+ */
+export type TrackErrorCapableProvider = {
+    request: (args: SnapTrackErrorRequest) => Promise<TrackErrorResult | undefined>;
+};
+export type CreateTrackErrorOptions<TProvider extends TrackErrorCapableProvider = TrackErrorCapableProvider> = {
+    getSnapProvider: () => TProvider;
+    logError: LogErrorFn;
+    prepareError?: PrepareErrorForTrackingFn;
+    shouldTrack?: ShouldTrackErrorFn;
+};
+export type CreateSnapErrorHandlingOptions<TProvider extends TrackErrorCapableProvider = TrackErrorCapableProvider> = Omit<CreateWithCatchAndThrowSnapErrorOptions, 'trackError'> & CreateTrackErrorOptions<TProvider>;
+/**
+ * Creates a snap-bound error reporter for MetaMask Sentry (`snap_trackError`).
+ *
+ * RPC failures are caught and logged but never rethrown, so the returned function
+ * is safe to call from already-failing error-handling paths.
+ *
+ * @param options - Snap provider accessor, logger, and optional hooks.
+ * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.
+ * @param options.logError - Logger method used when the tracking RPC fails.
+ * @param options.prepareError - Optional error normalizer before Sentry serialization.
+ * @param options.shouldTrack - Optional filter; defaults to skipping `UserRejectedRequestError`.
+ * @returns A function that reports errors to Sentry when {@link ShouldTrackErrorFn} allows it.
+ */
+export declare function createTrackError<TProvider extends TrackErrorCapableProvider>({ getSnapProvider, logError, prepareError, shouldTrack, }: CreateTrackErrorOptions<TProvider>): TrackErrorFn;
+/**
+ * Creates snap error handling utilities wired with a shared transport and logger setup.
+ *
+ * @param options - Options for both {@link createTrackError} and
+ * {@link createWithCatchAndThrowSnapError}.
+ * @param options.logError - Logger method used for handler and tracking failures.
+ * @param options.normalizeErrorFn - Optional Snap RPC error normalizer for handler boundaries.
+ * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.
+ * @param options.prepareError - Optional error normalizer before Sentry serialization.
+ * @param options.shouldTrack - Optional tracking filter passed to {@link createTrackError}.
+ * @returns Bound {@link createTrackError trackError} and
+ * {@link createWithCatchAndThrowSnapError withCatchAndThrowSnapError} functions.
+ */
+export declare function createSnapErrorHandling<TProvider extends TrackErrorCapableProvider>({ logError, normalizeErrorFn, getSnapProvider, prepareError, shouldTrack, }: CreateSnapErrorHandlingOptions<TProvider>): {
+    trackError: TrackErrorFn;
+    withCatchAndThrowSnapError: ReturnType<typeof createWithCatchAndThrowSnapError>;
+};
+//# sourceMappingURL=trackError.d.mts.map

package/dist/utils/errors/trackError.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackError.d.mts","sourceRoot":"","sources":["../../../src/utils/errors/trackError.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,4BAA4B;AAG9E,OAAO,KAAK,EACV,uCAAuC,EACvC,UAAU,EACV,YAAY,EACb,qBAAiB;AAClB,OAAO,EAAE,gCAAgC,EAAE,qBAAiB;AAE5D;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,gBAAgB,CAAC;CAC1B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,CACP,IAAI,EAAE,qBAAqB,KACxB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,uBAAuB,CACjC,SAAS,SAAS,yBAAyB,GAAG,yBAAyB,IACrE;IACF,eAAe,EAAE,MAAM,SAAS,CAAC;IACjC,QAAQ,EAAE,UAAU,CAAC;IACrB,YAAY,CAAC,EAAE,yBAAyB,CAAC;IACzC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,8BAA8B,CACxC,SAAS,SAAS,yBAAyB,GAAG,yBAAyB,IACrE,IAAI,CAAC,uCAAuC,EAAE,YAAY,CAAC,GAC7D,uBAAuB,CAAC,SAAS,CAAC,CAAC;AAUrC;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,SAAS,yBAAyB,EAAE,EAC5E,eAAe,EACf,QAAQ,EACR,YAAkC,EAClC,WAAgC,GACjC,EAAE,uBAAuB,CAAC,SAAS,CAAC,GAAG,YAAY,CAoBnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,SAAS,yBAAyB,EAC3C,EACA,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,GACZ,EAAE,8BAA8B,CAAC,SAAS,CAAC,GAAG;IAC7C,UAAU,EAAE,YAAY,CAAC;IACzB,0BAA0B,EAAE,UAAU,CACpC,OAAO,gCAAgC,CACxC,CAAC;CACH,CAgBA"}

package/dist/utils/errors/trackError.mjs

@@ -0,0 +1,72 @@
+import { getJsonError, UserRejectedRequestError } from "@metamask/snaps-sdk";
+import { ensureError } from "@metamask/utils";
+import { createWithCatchAndThrowSnapError } from "./errors.mjs";
+function defaultPrepareError(error) {
+    return error instanceof Error ? error : ensureError(error);
+}
+function defaultShouldTrack(error) {
+    return !(error instanceof UserRejectedRequestError);
+}
+/**
+ * Creates a snap-bound error reporter for MetaMask Sentry (`snap_trackError`).
+ *
+ * RPC failures are caught and logged but never rethrown, so the returned function
+ * is safe to call from already-failing error-handling paths.
+ *
+ * @param options - Snap provider accessor, logger, and optional hooks.
+ * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.
+ * @param options.logError - Logger method used when the tracking RPC fails.
+ * @param options.prepareError - Optional error normalizer before Sentry serialization.
+ * @param options.shouldTrack - Optional filter; defaults to skipping `UserRejectedRequestError`.
+ * @returns A function that reports errors to Sentry when {@link ShouldTrackErrorFn} allows it.
+ */
+export function createTrackError({ getSnapProvider, logError, prepareError = defaultPrepareError, shouldTrack = defaultShouldTrack, }) {
+    return async (error) => {
+        if (!shouldTrack(error)) {
+            return undefined;
+        }
+        const params = {
+            error: getJsonError(prepareError(error)),
+        };
+        try {
+            return await getSnapProvider().request({
+                method: 'snap_trackError',
+                params,
+            });
+        }
+        catch (trackingError) {
+            logError({ error: trackingError }, 'Failed to track error');
+            return undefined;
+        }
+    };
+}
+/**
+ * Creates snap error handling utilities wired with a shared transport and logger setup.
+ *
+ * @param options - Options for both {@link createTrackError} and
+ * {@link createWithCatchAndThrowSnapError}.
+ * @param options.logError - Logger method used for handler and tracking failures.
+ * @param options.normalizeErrorFn - Optional Snap RPC error normalizer for handler boundaries.
+ * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.
+ * @param options.prepareError - Optional error normalizer before Sentry serialization.
+ * @param options.shouldTrack - Optional tracking filter passed to {@link createTrackError}.
+ * @returns Bound {@link createTrackError trackError} and
+ * {@link createWithCatchAndThrowSnapError withCatchAndThrowSnapError} functions.
+ */
+export function createSnapErrorHandling({ logError, normalizeErrorFn, getSnapProvider, prepareError, shouldTrack, }) {
+    const trackError = createTrackError({
+        getSnapProvider,
+        logError,
+        prepareError,
+        shouldTrack,
+    });
+    return {
+        trackError,
+        withCatchAndThrowSnapError: createWithCatchAndThrowSnapError({
+            logError,
+            trackError,
+            normalizeErrorFn,
+        }),
+    };
+}
+//# sourceMappingURL=trackError.mjs.map

package/dist/utils/errors/trackError.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackError.mjs","sourceRoot":"","sources":["../../../src/utils/errors/trackError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,4BAA4B;AAE7E,OAAO,EAAE,WAAW,EAAE,wBAAwB;AAO9C,OAAO,EAAE,gCAAgC,EAAE,qBAAiB;AA4C5D,SAAS,mBAAmB,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,OAAO,CAAC,CAAC,KAAK,YAAY,wBAAwB,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAA8C,EAC5E,eAAe,EACf,QAAQ,EACR,YAAY,GAAG,mBAAmB,EAClC,WAAW,GAAG,kBAAkB,GACG;IACnC,OAAO,KAAK,EAAE,KAAc,EAA+B,EAAE;QAC3D,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,MAAM,GAAqB;YAC/B,KAAK,EAAE,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;SACzC,CAAC;QAEF,IAAI,CAAC;YACH,OAAO,MAAM,eAAe,EAAE,CAAC,OAAO,CAAC;gBACrC,MAAM,EAAE,iBAAiB;gBACzB,MAAM;aACP,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,aAAa,EAAE,CAAC;YACvB,QAAQ,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,uBAAuB,CAAC,CAAC;YAC5D,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAErC,EACA,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,GAC+B;IAM1C,MAAM,UAAU,GAAG,gBAAgB,CAAC;QAClC,eAAe;QACf,QAAQ;QACR,YAAY;QACZ,WAAW;KACZ,CAAC,CAAC;IAEH,OAAO;QACL,UAAU;QACV,0BAA0B,EAAE,gCAAgC,CAAC;YAC3D,QAAQ;YACR,UAAU;YACV,gBAAgB;SACjB,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["import { getJsonError, UserRejectedRequestError } from '@metamask/snaps-sdk';\nimport type { TrackErrorParams, TrackErrorResult } from '@metamask/snaps-sdk';\nimport { ensureError } from '@metamask/utils';\n\nimport type {\n  CreateWithCatchAndThrowSnapErrorOptions,\n  LogErrorFn,\n  TrackErrorFn,\n} from './errors';\nimport { createWithCatchAndThrowSnapError } from './errors';\n\n/**\n * Converts a caught value into an {@link Error} before Sentry serialization.\n */\nexport type PrepareErrorForTrackingFn = (error: unknown) => Error;\n\n/**\n * Determines whether an error should be reported through `snap_trackError`.\n */\nexport type ShouldTrackErrorFn = (error: unknown) => boolean;\n\n/**\n * `snap_trackError` request shape from `@metamask/snaps-sdk`.\n */\nexport type SnapTrackErrorRequest = {\n  method: 'snap_trackError';\n  params: TrackErrorParams;\n};\n\n/**\n * Snap provider surface required for {@link createTrackError}, derived from SDK\n * `snap_trackError` types.\n */\nexport type TrackErrorCapableProvider = {\n  request: (\n    args: SnapTrackErrorRequest,\n  ) => Promise<TrackErrorResult | undefined>;\n};\n\nexport type CreateTrackErrorOptions<\n  TProvider extends TrackErrorCapableProvider = TrackErrorCapableProvider,\n> = {\n  getSnapProvider: () => TProvider;\n  logError: LogErrorFn;\n  prepareError?: PrepareErrorForTrackingFn;\n  shouldTrack?: ShouldTrackErrorFn;\n};\n\nexport type CreateSnapErrorHandlingOptions<\n  TProvider extends TrackErrorCapableProvider = TrackErrorCapableProvider,\n> = Omit<CreateWithCatchAndThrowSnapErrorOptions, 'trackError'> &\n  CreateTrackErrorOptions<TProvider>;\n\nfunction defaultPrepareError(error: unknown): Error {\n  return error instanceof Error ? error : ensureError(error);\n}\n\nfunction defaultShouldTrack(error: unknown): boolean {\n  return !(error instanceof UserRejectedRequestError);\n}\n\n/**\n * Creates a snap-bound error reporter for MetaMask Sentry (`snap_trackError`).\n *\n * RPC failures are caught and logged but never rethrown, so the returned function\n * is safe to call from already-failing error-handling paths.\n *\n * @param options - Snap provider accessor, logger, and optional hooks.\n * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.\n * @param options.logError - Logger method used when the tracking RPC fails.\n * @param options.prepareError - Optional error normalizer before Sentry serialization.\n * @param options.shouldTrack - Optional filter; defaults to skipping `UserRejectedRequestError`.\n * @returns A function that reports errors to Sentry when {@link ShouldTrackErrorFn} allows it.\n */\nexport function createTrackError<TProvider extends TrackErrorCapableProvider>({\n  getSnapProvider,\n  logError,\n  prepareError = defaultPrepareError,\n  shouldTrack = defaultShouldTrack,\n}: CreateTrackErrorOptions<TProvider>): TrackErrorFn {\n  return async (error: unknown): Promise<string | undefined> => {\n    if (!shouldTrack(error)) {\n      return undefined;\n    }\n\n    const params: TrackErrorParams = {\n      error: getJsonError(prepareError(error)),\n    };\n\n    try {\n      return await getSnapProvider().request({\n        method: 'snap_trackError',\n        params,\n      });\n    } catch (trackingError) {\n      logError({ error: trackingError }, 'Failed to track error');\n      return undefined;\n    }\n  };\n}\n\n/**\n * Creates snap error handling utilities wired with a shared transport and logger setup.\n *\n * @param options - Options for both {@link createTrackError} and\n * {@link createWithCatchAndThrowSnapError}.\n * @param options.logError - Logger method used for handler and tracking failures.\n * @param options.normalizeErrorFn - Optional Snap RPC error normalizer for handler boundaries.\n * @param options.getSnapProvider - Returns the Snap provider used for `snap_trackError`.\n * @param options.prepareError - Optional error normalizer before Sentry serialization.\n * @param options.shouldTrack - Optional tracking filter passed to {@link createTrackError}.\n * @returns Bound {@link createTrackError trackError} and\n * {@link createWithCatchAndThrowSnapError withCatchAndThrowSnapError} functions.\n */\nexport function createSnapErrorHandling<\n  TProvider extends TrackErrorCapableProvider,\n>({\n  logError,\n  normalizeErrorFn,\n  getSnapProvider,\n  prepareError,\n  shouldTrack,\n}: CreateSnapErrorHandlingOptions<TProvider>): {\n  trackError: TrackErrorFn;\n  withCatchAndThrowSnapError: ReturnType<\n    typeof createWithCatchAndThrowSnapError\n  >;\n} {\n  const trackError = createTrackError({\n    getSnapProvider,\n    logError,\n    prepareError,\n    shouldTrack,\n  });\n\n  return {\n    trackError,\n    withCatchAndThrowSnapError: createWithCatchAndThrowSnapError({\n      logError,\n      trackError,\n      normalizeErrorFn,\n    }),\n  };\n}\n"]}

package/dist/utils/handlers/wrapSnapHandlers.cjs

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopAssetHandlers = void 0;
+exports.wrapSnapHandlers = wrapSnapHandlers;
+/**
+ * Wraps each given Snap entrypoint handler with `withCatchAndThrowSnapError`.
+ *
+ * @param withCatchAndThrowSnapError - The Snap's bound error wrapper.
+ * @param handlers - Entrypoint handlers, keyed by their Snap export name.
+ * @param logError - Optional per-handler `logError` overrides, forwarded as
+ * the wrapper's second argument. Omitted handlers use the logger bound in the
+ * wrapper.
+ * @returns The wrapped handlers, under the same keys.
+ * @example
+ * import {
+ *   noopAssetHandlers,
+ *   wrapSnapHandlers,
+ * } from '@metamask/snap-networks-utils';
+ *
+ * import { clientRequestHandler, keyringHandler, keyringLogger } from './context';
+ * import { withCatchAndThrowSnapError } from './utils/errors';
+ *
+ * export const { onKeyringRequest, onClientRequest } = wrapSnapHandlers(
+ *   withCatchAndThrowSnapError,
+ *   {
+ *     onKeyringRequest: ({ origin, request }) =>
+ *       keyringHandler.handle(origin, request),
+ *     onClientRequest: ({ request }) => clientRequestHandler.handle(request),
+ *   },
+ *   { onKeyringRequest: keyringLogger.error.bind(keyringLogger) },
+ * );
+ *
+ * export const {
+ *   onAssetsLookup,
+ *   onAssetsConversion,
+ *   onAssetHistoricalPrice,
+ *   onAssetsMarketData,
+ * } = noopAssetHandlers;
+ */
+function wrapSnapHandlers(withCatchAndThrowSnapError, handlers, logError = {}) {
+    return Object.fromEntries(Object.entries(handlers).map(([name, handler]) => [
+        name,
+        async (args) => withCatchAndThrowSnapError(async () => handler(args), logError[name]),
+    ]));
+}
+/**
+ * No-op asset handlers that network Snaps must export to keep the
+ * `endowment:assets` permission, since assets are provided through the
+ * Assets API instead.
+ */
+exports.noopAssetHandlers = {
+    onAssetsLookup: async () => ({ assets: {} }),
+    onAssetsConversion: async () => ({ conversionRates: {} }),
+    onAssetHistoricalPrice: async () => null,
+    onAssetsMarketData: async () => ({ marketData: {} }),
+};
+//# sourceMappingURL=wrapSnapHandlers.cjs.map

package/dist/utils/handlers/wrapSnapHandlers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapSnapHandlers.cjs","sourceRoot":"","sources":["../../../src/utils/handlers/wrapSnapHandlers.ts"],"names":[],"mappings":";;;AA6FA,4CAeC;AAlDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,SAAgB,gBAAgB,CAC9B,0BAAsD,EACtD,QAAuD,EACvD,WAAqD,EAAE;IAEvD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;QAChD,IAAI;QACJ,KAAK,EAAE,IAAa,EAAoB,EAAE,CACxC,0BAA0B,CACxB,KAAK,IAAI,EAAE,CAAE,OAA+C,CAAC,IAAI,CAAC,EAClE,QAAQ,CAAC,IAAmB,CAAC,CAC9B;KACJ,CAAC,CACgC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACU,QAAA,iBAAiB,GAM1B;IACF,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC5C,kBAAkB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;IACzD,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;IACxC,kBAAkB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;CACrD,CAAC","sourcesContent":["import type {\n  OnActiveHandler,\n  OnAssetHistoricalPriceHandler,\n  OnAssetsConversionHandler,\n  OnAssetsLookupHandler,\n  OnAssetsMarketDataHandler,\n  OnClientRequestHandler,\n  OnCronjobHandler,\n  OnHomePageHandler,\n  OnInactiveHandler,\n  OnInstallHandler,\n  OnKeyringRequestHandler,\n  OnNameLookupHandler,\n  OnProtocolRequestHandler,\n  OnRpcRequestHandler,\n  OnSettingsPageHandler,\n  OnSignatureHandler,\n  OnStartHandler,\n  OnTransactionHandler,\n  OnUpdateHandler,\n  OnUserInputHandler,\n  OnWebSocketEventHandler,\n} from '@metamask/snaps-sdk';\n\nimport type { LogErrorFn } from '../errors/errors';\n\nexport type WithCatchAndThrowSnapError = <Response>(\n  handler: () => Promise<Response>,\n  logErrorOverride?: LogErrorFn,\n) => Promise<Response>;\n\n/**\n * Snap entrypoint names mapped to their SDK handler types.\n */\nexport type SnapHandlers = {\n  onActive: OnActiveHandler;\n  onAssetHistoricalPrice: OnAssetHistoricalPriceHandler;\n  onAssetsConversion: OnAssetsConversionHandler;\n  onAssetsLookup: OnAssetsLookupHandler;\n  onAssetsMarketData: OnAssetsMarketDataHandler;\n  onClientRequest: OnClientRequestHandler;\n  onCronjob: OnCronjobHandler;\n  onHomePage: OnHomePageHandler;\n  onInactive: OnInactiveHandler;\n  onInstall: OnInstallHandler;\n  onKeyringRequest: OnKeyringRequestHandler;\n  onNameLookup: OnNameLookupHandler;\n  onProtocolRequest: OnProtocolRequestHandler;\n  onRpcRequest: OnRpcRequestHandler;\n  onSettingsPage: OnSettingsPageHandler;\n  onSignature: OnSignatureHandler;\n  onStart: OnStartHandler;\n  onTransaction: OnTransactionHandler;\n  onUpdate: OnUpdateHandler;\n  onUserInput: OnUserInputHandler;\n  onWebSocketEvent: OnWebSocketEventHandler;\n};\n\n/**\n * Wraps each given Snap entrypoint handler with `withCatchAndThrowSnapError`.\n *\n * @param withCatchAndThrowSnapError - The Snap's bound error wrapper.\n * @param handlers - Entrypoint handlers, keyed by their Snap export name.\n * @param logError - Optional per-handler `logError` overrides, forwarded as\n * the wrapper's second argument. Omitted handlers use the logger bound in the\n * wrapper.\n * @returns The wrapped handlers, under the same keys.\n * @example\n * import {\n *   noopAssetHandlers,\n *   wrapSnapHandlers,\n * } from '@metamask/snap-networks-utils';\n *\n * import { clientRequestHandler, keyringHandler, keyringLogger } from './context';\n * import { withCatchAndThrowSnapError } from './utils/errors';\n *\n * export const { onKeyringRequest, onClientRequest } = wrapSnapHandlers(\n *   withCatchAndThrowSnapError,\n *   {\n *     onKeyringRequest: ({ origin, request }) =>\n *       keyringHandler.handle(origin, request),\n *     onClientRequest: ({ request }) => clientRequestHandler.handle(request),\n *   },\n *   { onKeyringRequest: keyringLogger.error.bind(keyringLogger) },\n * );\n *\n * export const {\n *   onAssetsLookup,\n *   onAssetsConversion,\n *   onAssetHistoricalPrice,\n *   onAssetsMarketData,\n * } = noopAssetHandlers;\n */\nexport function wrapSnapHandlers<HandlerName extends keyof SnapHandlers>(\n  withCatchAndThrowSnapError: WithCatchAndThrowSnapError,\n  handlers: { [Name in HandlerName]: SnapHandlers[Name] },\n  logError: Partial<Record<HandlerName, LogErrorFn>> = {},\n): Pick<SnapHandlers, HandlerName> {\n  return Object.fromEntries(\n    Object.entries(handlers).map(([name, handler]) => [\n      name,\n      async (args: unknown): Promise<unknown> =>\n        withCatchAndThrowSnapError(\n          async () => (handler as (args: unknown) => Promise<unknown>)(args),\n          logError[name as HandlerName],\n        ),\n    ]),\n  ) as Pick<SnapHandlers, HandlerName>;\n}\n\n/**\n * No-op asset handlers that network Snaps must export to keep the\n * `endowment:assets` permission, since assets are provided through the\n * Assets API instead.\n */\nexport const noopAssetHandlers: Pick<\n  SnapHandlers,\n  | 'onAssetsLookup'\n  | 'onAssetsConversion'\n  | 'onAssetHistoricalPrice'\n  | 'onAssetsMarketData'\n> = {\n  onAssetsLookup: async () => ({ assets: {} }),\n  onAssetsConversion: async () => ({ conversionRates: {} }),\n  onAssetHistoricalPrice: async () => null,\n  onAssetsMarketData: async () => ({ marketData: {} }),\n};\n"]}