@metamask/snap-networks-utils 1.0.0 → 2.0.0

package/dist/utils/handlers/wrapSnapHandlers.d.cts

@@ -0,0 +1,74 @@
+import type { OnActiveHandler, OnAssetHistoricalPriceHandler, OnAssetsConversionHandler, OnAssetsLookupHandler, OnAssetsMarketDataHandler, OnClientRequestHandler, OnCronjobHandler, OnHomePageHandler, OnInactiveHandler, OnInstallHandler, OnKeyringRequestHandler, OnNameLookupHandler, OnProtocolRequestHandler, OnRpcRequestHandler, OnSettingsPageHandler, OnSignatureHandler, OnStartHandler, OnTransactionHandler, OnUpdateHandler, OnUserInputHandler, OnWebSocketEventHandler } from "@metamask/snaps-sdk";
+import type { LogErrorFn } from "../errors/errors.cjs";
+export type WithCatchAndThrowSnapError = <Response>(handler: () => Promise<Response>, logErrorOverride?: LogErrorFn) => Promise<Response>;
+/**
+ * Snap entrypoint names mapped to their SDK handler types.
+ */
+export type SnapHandlers = {
+    onActive: OnActiveHandler;
+    onAssetHistoricalPrice: OnAssetHistoricalPriceHandler;
+    onAssetsConversion: OnAssetsConversionHandler;
+    onAssetsLookup: OnAssetsLookupHandler;
+    onAssetsMarketData: OnAssetsMarketDataHandler;
+    onClientRequest: OnClientRequestHandler;
+    onCronjob: OnCronjobHandler;
+    onHomePage: OnHomePageHandler;
+    onInactive: OnInactiveHandler;
+    onInstall: OnInstallHandler;
+    onKeyringRequest: OnKeyringRequestHandler;
+    onNameLookup: OnNameLookupHandler;
+    onProtocolRequest: OnProtocolRequestHandler;
+    onRpcRequest: OnRpcRequestHandler;
+    onSettingsPage: OnSettingsPageHandler;
+    onSignature: OnSignatureHandler;
+    onStart: OnStartHandler;
+    onTransaction: OnTransactionHandler;
+    onUpdate: OnUpdateHandler;
+    onUserInput: OnUserInputHandler;
+    onWebSocketEvent: OnWebSocketEventHandler;
+};
+/**
+ * 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;
+ */
+export declare function wrapSnapHandlers<HandlerName extends keyof SnapHandlers>(withCatchAndThrowSnapError: WithCatchAndThrowSnapError, handlers: {
+    [Name in HandlerName]: SnapHandlers[Name];
+}, logError?: Partial<Record<HandlerName, LogErrorFn>>): Pick<SnapHandlers, HandlerName>;
+/**
+ * No-op asset handlers that network Snaps must export to keep the
+ * `endowment:assets` permission, since assets are provided through the
+ * Assets API instead.
+ */
+export declare const noopAssetHandlers: Pick<SnapHandlers, 'onAssetsLookup' | 'onAssetsConversion' | 'onAssetHistoricalPrice' | 'onAssetsMarketData'>;
+//# sourceMappingURL=wrapSnapHandlers.d.cts.map

package/dist/utils/handlers/wrapSnapHandlers.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapSnapHandlers.d.cts","sourceRoot":"","sources":["../../../src/utils/handlers/wrapSnapHandlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,6BAA6B,EAC7B,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACxB,4BAA4B;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,6BAAyB;AAEnD,MAAM,MAAM,0BAA0B,GAAG,CAAC,QAAQ,EAChD,OAAO,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,EAChC,gBAAgB,CAAC,EAAE,UAAU,KAC1B,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,sBAAsB,EAAE,6BAA6B,CAAC;IACtD,kBAAkB,EAAE,yBAAyB,CAAC;IAC9C,cAAc,EAAE,qBAAqB,CAAC;IACtC,kBAAkB,EAAE,yBAAyB,CAAC;IAC9C,eAAe,EAAE,sBAAsB,CAAC;IACxC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,YAAY,EAAE,mBAAmB,CAAC;IAClC,iBAAiB,EAAE,wBAAwB,CAAC;IAC5C,YAAY,EAAE,mBAAmB,CAAC;IAClC,cAAc,EAAE,qBAAqB,CAAC;IACtC,WAAW,EAAE,kBAAkB,CAAC;IAChC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,EAAE,oBAAoB,CAAC;IACpC,QAAQ,EAAE,eAAe,CAAC;IAC1B,WAAW,EAAE,kBAAkB,CAAC;IAChC,gBAAgB,EAAE,uBAAuB,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,SAAS,MAAM,YAAY,EACrE,0BAA0B,EAAE,0BAA0B,EACtD,QAAQ,EAAE;KAAG,IAAI,IAAI,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC;CAAE,EACvD,QAAQ,GAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAAM,GACtD,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAWjC;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,IAAI,CAClC,YAAY,EACV,gBAAgB,GAChB,oBAAoB,GACpB,wBAAwB,GACxB,oBAAoB,CAMvB,CAAC"}

package/dist/utils/handlers/wrapSnapHandlers.d.mts

@@ -0,0 +1,74 @@
+import type { OnActiveHandler, OnAssetHistoricalPriceHandler, OnAssetsConversionHandler, OnAssetsLookupHandler, OnAssetsMarketDataHandler, OnClientRequestHandler, OnCronjobHandler, OnHomePageHandler, OnInactiveHandler, OnInstallHandler, OnKeyringRequestHandler, OnNameLookupHandler, OnProtocolRequestHandler, OnRpcRequestHandler, OnSettingsPageHandler, OnSignatureHandler, OnStartHandler, OnTransactionHandler, OnUpdateHandler, OnUserInputHandler, OnWebSocketEventHandler } from "@metamask/snaps-sdk";
+import type { LogErrorFn } from "../errors/errors.mjs";
+export type WithCatchAndThrowSnapError = <Response>(handler: () => Promise<Response>, logErrorOverride?: LogErrorFn) => Promise<Response>;
+/**
+ * Snap entrypoint names mapped to their SDK handler types.
+ */
+export type SnapHandlers = {
+    onActive: OnActiveHandler;
+    onAssetHistoricalPrice: OnAssetHistoricalPriceHandler;
+    onAssetsConversion: OnAssetsConversionHandler;
+    onAssetsLookup: OnAssetsLookupHandler;
+    onAssetsMarketData: OnAssetsMarketDataHandler;
+    onClientRequest: OnClientRequestHandler;
+    onCronjob: OnCronjobHandler;
+    onHomePage: OnHomePageHandler;
+    onInactive: OnInactiveHandler;
+    onInstall: OnInstallHandler;
+    onKeyringRequest: OnKeyringRequestHandler;
+    onNameLookup: OnNameLookupHandler;
+    onProtocolRequest: OnProtocolRequestHandler;
+    onRpcRequest: OnRpcRequestHandler;
+    onSettingsPage: OnSettingsPageHandler;
+    onSignature: OnSignatureHandler;
+    onStart: OnStartHandler;
+    onTransaction: OnTransactionHandler;
+    onUpdate: OnUpdateHandler;
+    onUserInput: OnUserInputHandler;
+    onWebSocketEvent: OnWebSocketEventHandler;
+};
+/**
+ * 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;
+ */
+export declare function wrapSnapHandlers<HandlerName extends keyof SnapHandlers>(withCatchAndThrowSnapError: WithCatchAndThrowSnapError, handlers: {
+    [Name in HandlerName]: SnapHandlers[Name];
+}, logError?: Partial<Record<HandlerName, LogErrorFn>>): Pick<SnapHandlers, HandlerName>;
+/**
+ * No-op asset handlers that network Snaps must export to keep the
+ * `endowment:assets` permission, since assets are provided through the
+ * Assets API instead.
+ */
+export declare const noopAssetHandlers: Pick<SnapHandlers, 'onAssetsLookup' | 'onAssetsConversion' | 'onAssetHistoricalPrice' | 'onAssetsMarketData'>;
+//# sourceMappingURL=wrapSnapHandlers.d.mts.map

package/dist/utils/handlers/wrapSnapHandlers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapSnapHandlers.d.mts","sourceRoot":"","sources":["../../../src/utils/handlers/wrapSnapHandlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,6BAA6B,EAC7B,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACxB,4BAA4B;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,6BAAyB;AAEnD,MAAM,MAAM,0BAA0B,GAAG,CAAC,QAAQ,EAChD,OAAO,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,EAChC,gBAAgB,CAAC,EAAE,UAAU,KAC1B,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,sBAAsB,EAAE,6BAA6B,CAAC;IACtD,kBAAkB,EAAE,yBAAyB,CAAC;IAC9C,cAAc,EAAE,qBAAqB,CAAC;IACtC,kBAAkB,EAAE,yBAAyB,CAAC;IAC9C,eAAe,EAAE,sBAAsB,CAAC;IACxC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,YAAY,EAAE,mBAAmB,CAAC;IAClC,iBAAiB,EAAE,wBAAwB,CAAC;IAC5C,YAAY,EAAE,mBAAmB,CAAC;IAClC,cAAc,EAAE,qBAAqB,CAAC;IACtC,WAAW,EAAE,kBAAkB,CAAC;IAChC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,EAAE,oBAAoB,CAAC;IACpC,QAAQ,EAAE,eAAe,CAAC;IAC1B,WAAW,EAAE,kBAAkB,CAAC;IAChC,gBAAgB,EAAE,uBAAuB,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,SAAS,MAAM,YAAY,EACrE,0BAA0B,EAAE,0BAA0B,EACtD,QAAQ,EAAE;KAAG,IAAI,IAAI,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC;CAAE,EACvD,QAAQ,GAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAAM,GACtD,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAWjC;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,IAAI,CAClC,YAAY,EACV,gBAAgB,GAChB,oBAAoB,GACpB,wBAAwB,GACxB,oBAAoB,CAMvB,CAAC"}

package/dist/utils/handlers/wrapSnapHandlers.mjs

@@ -0,0 +1,53 @@
+/**
+ * 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;
+ */
+export 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.
+ */
+export const noopAssetHandlers = {
+    onAssetsLookup: async () => ({ assets: {} }),
+    onAssetsConversion: async () => ({ conversionRates: {} }),
+    onAssetHistoricalPrice: async () => null,
+    onAssetsMarketData: async () => ({ marketData: {} }),
+};
+//# sourceMappingURL=wrapSnapHandlers.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wrapSnapHandlers.mjs","sourceRoot":"","sources":["../../../src/utils/handlers/wrapSnapHandlers.ts"],"names":[],"mappings":"AA0DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,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;AACH,MAAM,CAAC,MAAM,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"]}

package/dist/utils/keyringAccount/keyringAccount.cjs

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asStrictKeyringAccount = asStrictKeyringAccount;
+/**
+ * Converts an extended snap account to the Keyring API shape.
+ *
+ * Snaps persist `entropySource`, `derivationPath`, and `index` on the account
+ * object. The Keyring API must not receive those fields, so this copies only
+ * the six `KeyringAccount` properties.
+ *
+ * @param account - A snap keyring account with derivation fields.
+ * @returns A `KeyringAccount` with no extra properties.
+ */
+function asStrictKeyringAccount(account) {
+    const { id, address, type, options, methods, scopes } = account;
+    return {
+        id,
+        address,
+        type,
+        options,
+        methods,
+        scopes,
+    };
+}
+//# sourceMappingURL=keyringAccount.cjs.map

package/dist/utils/keyringAccount/keyringAccount.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyringAccount.cjs","sourceRoot":"","sources":["../../../src/utils/keyringAccount/keyringAccount.ts"],"names":[],"mappings":";;AA8BA,wDAYC;AAtBD;;;;;;;;;GASG;AACH,SAAgB,sBAAsB,CACpC,OAA+B;IAE/B,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAChE,OAAO;QACL,EAAE;QACF,OAAO;QACP,IAAI;QACJ,OAAO;QACP,OAAO;QACP,MAAM;KACP,CAAC;AACJ,CAAC","sourcesContent":["import type { EntropySourceId, KeyringAccount } from '@metamask/keyring-api';\n\n/**\n * Keyring account fields snaps persist in addition to `@metamask/keyring-api`'s\n * `KeyringAccount`. `index` is stored so an account can be restored at a\n * previously used derivation index.\n */\nexport type KeyringAccountExtension = {\n  entropySource: EntropySourceId;\n  derivationPath: `m/${string}`;\n  index: number;\n};\n\n/**\n * A `KeyringAccount` plus the derivation fields used by Solana, Tron, and Stellar.\n *\n * A snap may narrow `derivationPath` (for example Stellar's BIP-44 coin type).\n */\nexport type ExtendedKeyringAccount = KeyringAccount & KeyringAccountExtension;\n\n/**\n * Converts an extended snap account to the Keyring API shape.\n *\n * Snaps persist `entropySource`, `derivationPath`, and `index` on the account\n * object. The Keyring API must not receive those fields, so this copies only\n * the six `KeyringAccount` properties.\n *\n * @param account - A snap keyring account with derivation fields.\n * @returns A `KeyringAccount` with no extra properties.\n */\nexport function asStrictKeyringAccount(\n  account: ExtendedKeyringAccount,\n): KeyringAccount {\n  const { id, address, type, options, methods, scopes } = account;\n  return {\n    id,\n    address,\n    type,\n    options,\n    methods,\n    scopes,\n  };\n}\n"]}

package/dist/utils/keyringAccount/keyringAccount.d.cts

@@ -0,0 +1,29 @@
+import type { EntropySourceId, KeyringAccount } from "@metamask/keyring-api";
+/**
+ * Keyring account fields snaps persist in addition to `@metamask/keyring-api`'s
+ * `KeyringAccount`. `index` is stored so an account can be restored at a
+ * previously used derivation index.
+ */
+export type KeyringAccountExtension = {
+    entropySource: EntropySourceId;
+    derivationPath: `m/${string}`;
+    index: number;
+};
+/**
+ * A `KeyringAccount` plus the derivation fields used by Solana, Tron, and Stellar.
+ *
+ * A snap may narrow `derivationPath` (for example Stellar's BIP-44 coin type).
+ */
+export type ExtendedKeyringAccount = KeyringAccount & KeyringAccountExtension;
+/**
+ * Converts an extended snap account to the Keyring API shape.
+ *
+ * Snaps persist `entropySource`, `derivationPath`, and `index` on the account
+ * object. The Keyring API must not receive those fields, so this copies only
+ * the six `KeyringAccount` properties.
+ *
+ * @param account - A snap keyring account with derivation fields.
+ * @returns A `KeyringAccount` with no extra properties.
+ */
+export declare function asStrictKeyringAccount(account: ExtendedKeyringAccount): KeyringAccount;
+//# sourceMappingURL=keyringAccount.d.cts.map

package/dist/utils/keyringAccount/keyringAccount.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyringAccount.d.cts","sourceRoot":"","sources":["../../../src/utils/keyringAccount/keyringAccount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,8BAA8B;AAE7E;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,aAAa,EAAE,eAAe,CAAC;IAC/B,cAAc,EAAE,KAAK,MAAM,EAAE,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAE9E;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAUhB"}

package/dist/utils/keyringAccount/keyringAccount.d.mts

@@ -0,0 +1,29 @@
+import type { EntropySourceId, KeyringAccount } from "@metamask/keyring-api";
+/**
+ * Keyring account fields snaps persist in addition to `@metamask/keyring-api`'s
+ * `KeyringAccount`. `index` is stored so an account can be restored at a
+ * previously used derivation index.
+ */
+export type KeyringAccountExtension = {
+    entropySource: EntropySourceId;
+    derivationPath: `m/${string}`;
+    index: number;
+};
+/**
+ * A `KeyringAccount` plus the derivation fields used by Solana, Tron, and Stellar.
+ *
+ * A snap may narrow `derivationPath` (for example Stellar's BIP-44 coin type).
+ */
+export type ExtendedKeyringAccount = KeyringAccount & KeyringAccountExtension;
+/**
+ * Converts an extended snap account to the Keyring API shape.
+ *
+ * Snaps persist `entropySource`, `derivationPath`, and `index` on the account
+ * object. The Keyring API must not receive those fields, so this copies only
+ * the six `KeyringAccount` properties.
+ *
+ * @param account - A snap keyring account with derivation fields.
+ * @returns A `KeyringAccount` with no extra properties.
+ */
+export declare function asStrictKeyringAccount(account: ExtendedKeyringAccount): KeyringAccount;
+//# sourceMappingURL=keyringAccount.d.mts.map

package/dist/utils/keyringAccount/keyringAccount.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyringAccount.d.mts","sourceRoot":"","sources":["../../../src/utils/keyringAccount/keyringAccount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,8BAA8B;AAE7E;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,aAAa,EAAE,eAAe,CAAC;IAC/B,cAAc,EAAE,KAAK,MAAM,EAAE,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAE9E;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAUhB"}

package/dist/utils/keyringAccount/keyringAccount.mjs

@@ -0,0 +1,22 @@
+/**
+ * Converts an extended snap account to the Keyring API shape.
+ *
+ * Snaps persist `entropySource`, `derivationPath`, and `index` on the account
+ * object. The Keyring API must not receive those fields, so this copies only
+ * the six `KeyringAccount` properties.
+ *
+ * @param account - A snap keyring account with derivation fields.
+ * @returns A `KeyringAccount` with no extra properties.
+ */
+export function asStrictKeyringAccount(account) {
+    const { id, address, type, options, methods, scopes } = account;
+    return {
+        id,
+        address,
+        type,
+        options,
+        methods,
+        scopes,
+    };
+}
+//# sourceMappingURL=keyringAccount.mjs.map

package/dist/utils/keyringAccount/keyringAccount.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyringAccount.mjs","sourceRoot":"","sources":["../../../src/utils/keyringAccount/keyringAccount.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA+B;IAE/B,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAChE,OAAO;QACL,EAAE;QACF,OAAO;QACP,IAAI;QACJ,OAAO;QACP,OAAO;QACP,MAAM;KACP,CAAC;AACJ,CAAC","sourcesContent":["import type { EntropySourceId, KeyringAccount } from '@metamask/keyring-api';\n\n/**\n * Keyring account fields snaps persist in addition to `@metamask/keyring-api`'s\n * `KeyringAccount`. `index` is stored so an account can be restored at a\n * previously used derivation index.\n */\nexport type KeyringAccountExtension = {\n  entropySource: EntropySourceId;\n  derivationPath: `m/${string}`;\n  index: number;\n};\n\n/**\n * A `KeyringAccount` plus the derivation fields used by Solana, Tron, and Stellar.\n *\n * A snap may narrow `derivationPath` (for example Stellar's BIP-44 coin type).\n */\nexport type ExtendedKeyringAccount = KeyringAccount & KeyringAccountExtension;\n\n/**\n * Converts an extended snap account to the Keyring API shape.\n *\n * Snaps persist `entropySource`, `derivationPath`, and `index` on the account\n * object. The Keyring API must not receive those fields, so this copies only\n * the six `KeyringAccount` properties.\n *\n * @param account - A snap keyring account with derivation fields.\n * @returns A `KeyringAccount` with no extra properties.\n */\nexport function asStrictKeyringAccount(\n  account: ExtendedKeyringAccount,\n): KeyringAccount {\n  const { id, address, type, options, methods, scopes } = account;\n  return {\n    id,\n    address,\n    type,\n    options,\n    methods,\n    scopes,\n  };\n}\n"]}

package/dist/utils/logger/Logger.cjs

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = exports.LogLevel = void 0;
+const superstruct_1 = require("@metamask/superstruct");
+/**
+ * The severity levels supported by {@link Logger}.
+ */
+exports.LogLevel = {
+    SILENT: 'silent',
+    ERROR: 'error',
+    WARN: 'warn',
+    INFO: 'info',
+    DEBUG: 'debug',
+    TRACE: 'trace',
+};
+/**
+ * Defines the severity ordering used to filter log messages.
+ *
+ * Lower values are less verbose. Changing these numeric priorities changes
+ * which messages are emitted for each configured {@link LogLevel}, including
+ * in production.
+ */
+const logLevelPriority = {
+    [exports.LogLevel.SILENT]: 0,
+    [exports.LogLevel.ERROR]: 1,
+    [exports.LogLevel.WARN]: 2,
+    [exports.LogLevel.INFO]: 3,
+    [exports.LogLevel.DEBUG]: 4,
+    [exports.LogLevel.TRACE]: 5,
+};
+const LogLevelStruct = (0, superstruct_1.enums)(Object.values(exports.LogLevel));
+/**
+ * Logs network Snap messages to the console at configurable severity levels.
+ *
+ * Disable output with {@link LogLevel.SILENT}.
+ *
+ * **Example: create an enabled logger.**
+ *
+ * ```ts
+ * import { Logger } from '@metamask/snap-networks-utils';
+ *
+ * const logger = new Logger({ level: LogLevel.TRACE });
+ * logger.info('Account synced');
+ * ```
+ *
+ * **Example: add a Snap or component prefix.**
+ *
+ * ```ts
+ * const rootLogger = new Logger({ level: LogLevel.TRACE });
+ * const snapLogger = rootLogger.withPrefix('[tron-wallet-snap]');
+ * const accountsLogger = snapLogger.withPrefix('[accounts]');
+ *
+ * accountsLogger.debug('Refreshing account balances');
+ * ```
+ *
+ * **Example: decorate a method with Snap-specific behavior.**
+ *
+ * ```ts
+ * const logger = new Logger({
+ *   level: LogLevel.TRACE,
+ *   decorators: {
+ *     error: (next, error) => {
+ *       const details = getSolanaErrorDetails(error);
+ *       next(details ?? error);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+class Logger {
+    #level;
+    #prefix;
+    #decorators;
+    constructor({ level, prefix, decorators }) {
+        (0, superstruct_1.assert)(level, LogLevelStruct);
+        this.#level = level;
+        this.#prefix = prefix;
+        this.#decorators = decorators;
+    }
+    /**
+     * Returns a logger with an additional prefix.
+     *
+     * The returned logger has the same log level and decorators as this one. Call
+     * this method as many times as needed; each derived logger appends its prefix
+     * to the existing prefix.
+     *
+     * @param prefix - The prefix to add to each message.
+     * @returns A derived logger.
+     */
+    withPrefix(prefix) {
+        return new Logger({
+            level: this.#level,
+            prefix: this.#prefix ? `${this.#prefix} ${prefix}` : prefix,
+            decorators: this.#decorators,
+        });
+    }
+    error(...args) {
+        this.#write(exports.LogLevel.ERROR, console.error, args);
+    }
+    warn(...args) {
+        this.#write(exports.LogLevel.WARN, console.warn, args);
+    }
+    /**
+     * Logs an informational message.
+     *
+     * @param args - The values to write to the console.
+     * @deprecated Use {@link Logger.info} instead.
+     */
+    log(...args) {
+        this.info(...args);
+    }
+    info(...args) {
+        this.#write(exports.LogLevel.INFO, console.info, args);
+    }
+    debug(...args) {
+        this.#write(exports.LogLevel.DEBUG, console.debug, args);
+    }
+    trace(...args) {
+        this.#write(exports.LogLevel.TRACE, console.trace, args);
+    }
+    #isLevelDisabled(level) {
+        return logLevelPriority[level] > logLevelPriority[this.#level];
+    }
+    #write(level, writeToConsole, args) {
+        if (this.#isLevelDisabled(level)) {
+            return;
+        }
+        const next = this.#prefix
+            ? (...nextArgs) => writeToConsole(this.#prefix, ...nextArgs)
+            : writeToConsole;
+        const decorator = this.#decorators?.[level];
+        if (decorator) {
+            decorator(next, ...args);
+            return;
+        }
+        next(...args);
+    }
+}
+exports.Logger = Logger;
+//# sourceMappingURL=Logger.cjs.map

package/dist/utils/logger/Logger.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.cjs","sourceRoot":"","sources":["../../../src/utils/logger/Logger.ts"],"names":[],"mappings":"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","sourcesContent":["import { assert, enums } from '@metamask/superstruct';\n\n/**\n * The severity levels supported by {@link Logger}.\n */\nexport const LogLevel = {\n  SILENT: 'silent',\n  ERROR: 'error',\n  WARN: 'warn',\n  INFO: 'info',\n  DEBUG: 'debug',\n  TRACE: 'trace',\n} as const;\n\nexport type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];\n\n/**\n * Defines the severity ordering used to filter log messages.\n *\n * Lower values are less verbose. Changing these numeric priorities changes\n * which messages are emitted for each configured {@link LogLevel}, including\n * in production.\n */\nconst logLevelPriority = {\n  [LogLevel.SILENT]: 0,\n  [LogLevel.ERROR]: 1,\n  [LogLevel.WARN]: 2,\n  [LogLevel.INFO]: 3,\n  [LogLevel.DEBUG]: 4,\n  [LogLevel.TRACE]: 5,\n};\n\nconst LogLevelStruct = enums(Object.values(LogLevel));\n\nexport type LoggerMethod = Exclude<LogLevel, typeof LogLevel.SILENT>;\n\nexport type LogMethod = (...args: unknown[]) => void;\n\n/**\n * A function that can add behavior around a logger method.\n *\n * Call `next` to forward a message through the logger's configured output.\n */\nexport type LogMethodDecorator = (next: LogMethod, ...args: unknown[]) => void;\n\nexport type LoggerDecorators = Partial<\n  Record<LoggerMethod, LogMethodDecorator>\n>;\n\n/**\n * Configuration for a {@link Logger}.\n *\n * **Example: configure logging with `LOG_LEVEL`.**\n *\n * ```ts\n * const logger = new Logger({\n *   level: process.env.LOG_LEVEL\n * });\n * ```\n */\nexport type LoggerOptions = {\n  /**\n   * The most verbose severity level that should be logged. Use\n   * {@link LogLevel.SILENT} to disable logging.\n   */\n  level: LogLevel;\n  /**\n   * An optional prefix prepended to every message.\n   *\n   * Use {@link Logger.withPrefix} to add prefixes after construction.\n   */\n  prefix?: string;\n  /**\n   * Optional behavior to apply to individual log methods.\n   *\n   * Decorators receive `next`, which preserves this logger's configured level,\n   * prefix, and console output.\n   */\n  decorators?: LoggerDecorators;\n};\n\n/**\n * Logs network Snap messages to the console at configurable severity levels.\n *\n * Disable output with {@link LogLevel.SILENT}.\n *\n * **Example: create an enabled logger.**\n *\n * ```ts\n * import { Logger } from '@metamask/snap-networks-utils';\n *\n * const logger = new Logger({ level: LogLevel.TRACE });\n * logger.info('Account synced');\n * ```\n *\n * **Example: add a Snap or component prefix.**\n *\n * ```ts\n * const rootLogger = new Logger({ level: LogLevel.TRACE });\n * const snapLogger = rootLogger.withPrefix('[tron-wallet-snap]');\n * const accountsLogger = snapLogger.withPrefix('[accounts]');\n *\n * accountsLogger.debug('Refreshing account balances');\n * ```\n *\n * **Example: decorate a method with Snap-specific behavior.**\n *\n * ```ts\n * const logger = new Logger({\n *   level: LogLevel.TRACE,\n *   decorators: {\n *     error: (next, error) => {\n *       const details = getSolanaErrorDetails(error);\n *       next(details ?? error);\n *     },\n *   },\n * });\n * ```\n */\nexport class Logger {\n  readonly #level: LogLevel;\n\n  readonly #prefix?: string;\n\n  readonly #decorators?: LoggerDecorators;\n\n  constructor({ level, prefix, decorators }: LoggerOptions) {\n    assert(level, LogLevelStruct);\n\n    this.#level = level;\n    this.#prefix = prefix;\n    this.#decorators = decorators;\n  }\n\n  /**\n   * Returns a logger with an additional prefix.\n   *\n   * The returned logger has the same log level and decorators as this one. Call\n   * this method as many times as needed; each derived logger appends its prefix\n   * to the existing prefix.\n   *\n   * @param prefix - The prefix to add to each message.\n   * @returns A derived logger.\n   */\n  withPrefix(prefix: string): Logger {\n    return new Logger({\n      level: this.#level,\n      prefix: this.#prefix ? `${this.#prefix} ${prefix}` : prefix,\n      decorators: this.#decorators,\n    });\n  }\n\n  error(...args: unknown[]): void {\n    this.#write(LogLevel.ERROR, console.error, args);\n  }\n\n  warn(...args: unknown[]): void {\n    this.#write(LogLevel.WARN, console.warn, args);\n  }\n\n  /**\n   * Logs an informational message.\n   *\n   * @param args - The values to write to the console.\n   * @deprecated Use {@link Logger.info} instead.\n   */\n  log(...args: unknown[]): void {\n    this.info(...args);\n  }\n\n  info(...args: unknown[]): void {\n    this.#write(LogLevel.INFO, console.info, args);\n  }\n\n  debug(...args: unknown[]): void {\n    this.#write(LogLevel.DEBUG, console.debug, args);\n  }\n\n  trace(...args: unknown[]): void {\n    this.#write(LogLevel.TRACE, console.trace, args);\n  }\n\n  #isLevelDisabled(level: LoggerMethod): boolean {\n    return logLevelPriority[level] > logLevelPriority[this.#level];\n  }\n\n  #write(\n    level: LoggerMethod,\n    writeToConsole: (...args: unknown[]) => void,\n    args: unknown[],\n  ): void {\n    if (this.#isLevelDisabled(level)) {\n      return;\n    }\n\n    const next: LogMethod = this.#prefix\n      ? (...nextArgs: unknown[]): void =>\n          writeToConsole(this.#prefix, ...nextArgs)\n      : writeToConsole;\n\n    const decorator = this.#decorators?.[level];\n\n    if (decorator) {\n      decorator(next, ...args);\n      return;\n    }\n\n    next(...args);\n  }\n}\n"]}

package/dist/utils/logger/Logger.d.cts

@@ -0,0 +1,118 @@
+/**
+ * The severity levels supported by {@link Logger}.
+ */
+export declare const LogLevel: {
+    readonly SILENT: "silent";
+    readonly ERROR: "error";
+    readonly WARN: "warn";
+    readonly INFO: "info";
+    readonly DEBUG: "debug";
+    readonly TRACE: "trace";
+};
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+export type LoggerMethod = Exclude<LogLevel, typeof LogLevel.SILENT>;
+export type LogMethod = (...args: unknown[]) => void;
+/**
+ * A function that can add behavior around a logger method.
+ *
+ * Call `next` to forward a message through the logger's configured output.
+ */
+export type LogMethodDecorator = (next: LogMethod, ...args: unknown[]) => void;
+export type LoggerDecorators = Partial<Record<LoggerMethod, LogMethodDecorator>>;
+/**
+ * Configuration for a {@link Logger}.
+ *
+ * **Example: configure logging with `LOG_LEVEL`.**
+ *
+ * ```ts
+ * const logger = new Logger({
+ *   level: process.env.LOG_LEVEL
+ * });
+ * ```
+ */
+export type LoggerOptions = {
+    /**
+     * The most verbose severity level that should be logged. Use
+     * {@link LogLevel.SILENT} to disable logging.
+     */
+    level: LogLevel;
+    /**
+     * An optional prefix prepended to every message.
+     *
+     * Use {@link Logger.withPrefix} to add prefixes after construction.
+     */
+    prefix?: string;
+    /**
+     * Optional behavior to apply to individual log methods.
+     *
+     * Decorators receive `next`, which preserves this logger's configured level,
+     * prefix, and console output.
+     */
+    decorators?: LoggerDecorators;
+};
+/**
+ * Logs network Snap messages to the console at configurable severity levels.
+ *
+ * Disable output with {@link LogLevel.SILENT}.
+ *
+ * **Example: create an enabled logger.**
+ *
+ * ```ts
+ * import { Logger } from '@metamask/snap-networks-utils';
+ *
+ * const logger = new Logger({ level: LogLevel.TRACE });
+ * logger.info('Account synced');
+ * ```
+ *
+ * **Example: add a Snap or component prefix.**
+ *
+ * ```ts
+ * const rootLogger = new Logger({ level: LogLevel.TRACE });
+ * const snapLogger = rootLogger.withPrefix('[tron-wallet-snap]');
+ * const accountsLogger = snapLogger.withPrefix('[accounts]');
+ *
+ * accountsLogger.debug('Refreshing account balances');
+ * ```
+ *
+ * **Example: decorate a method with Snap-specific behavior.**
+ *
+ * ```ts
+ * const logger = new Logger({
+ *   level: LogLevel.TRACE,
+ *   decorators: {
+ *     error: (next, error) => {
+ *       const details = getSolanaErrorDetails(error);
+ *       next(details ?? error);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare class Logger {
+    #private;
+    constructor({ level, prefix, decorators }: LoggerOptions);
+    /**
+     * Returns a logger with an additional prefix.
+     *
+     * The returned logger has the same log level and decorators as this one. Call
+     * this method as many times as needed; each derived logger appends its prefix
+     * to the existing prefix.
+     *
+     * @param prefix - The prefix to add to each message.
+     * @returns A derived logger.
+     */
+    withPrefix(prefix: string): Logger;
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    /**
+     * Logs an informational message.
+     *
+     * @param args - The values to write to the console.
+     * @deprecated Use {@link Logger.info} instead.
+     */
+    log(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    trace(...args: unknown[]): void;
+}
+//# sourceMappingURL=Logger.d.cts.map

package/dist/utils/logger/Logger.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.cts","sourceRoot":"","sources":["../../../src/utils/logger/Logger.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;;CAOX,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAoBhE,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;AAErE,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAE/E,MAAM,MAAM,gBAAgB,GAAG,OAAO,CACpC,MAAM,CAAC,YAAY,EAAE,kBAAkB,CAAC,CACzC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,KAAK,EAAE,QAAQ,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,MAAM;;gBAOL,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,aAAa;IAQxD;;;;;;;;;OASG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAQlC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI9B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI7B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;CA+BhC"}