@berachain/berajs 0.1.2 → 0.2.0

package/src/errors/BeraMonitoring.ts

@@ -0,0 +1,66 @@
+import { createEmitter, type EmitterMixin } from "~/utils/createEmitter";
+import type { BeraError } from "./BeraError";
+import type { SeverityLevel } from "./severity";
+
+/**
+ * Context passed alongside captured exceptions.
+ * Mirrors the subset of Sentry's CaptureContext that berajs actually uses.
+ */
+export interface CaptureContext {
+  level: SeverityLevel;
+  extra?: Record<string, unknown>;
+  tags?: Record<string, string | number | boolean | null | undefined>;
+  fingerprint?: string[];
+  data?: Record<string, unknown>;
+}
+
+export interface ErrorEvent {
+  exception: BeraError;
+  timestamp: number;
+}
+
+const _emitter = createEmitter<{ exception: (event: ErrorEvent) => void }>();
+
+/**
+ * A generic error reporter for berajs.
+ *
+ * Instead of calling Sentry.captureException directly, berajs calls
+ * `BeraMonitoring.captureException()`. Consumer apps subscribe via `.on()` and
+ * forward events to their monitoring provider (Sentry, Datadog, etc.).
+ *
+ * @example
+ * ```ts
+ * // In berajs code:
+ * import { BeraMonitoring } from "~/errors/BeraMonitoring";
+ * BeraMonitoring.captureExceptionException(error);
+ *
+ * // In app instrumentation:
+ * import { BeraMonitoring } from "@berachain/berajs/errors";
+ * BeraMonitoring.on((event) => {
+ *   if (event.type === "exception") {
+ *     Sentry.captureException(event.exception);
+ *   }
+ * });
+ * ```
+ */
+export const BeraMonitoring: {
+  captureException: (exception: BeraError) => void;
+} & EmitterMixin<{ exception: (event: ErrorEvent) => void }> = {
+  /**
+   * Capture an exception. Notifies all subscribers.
+   */
+  captureException(exception: BeraError): void {
+    const event: ErrorEvent = {
+      exception,
+      timestamp: Date.now(),
+    };
+    _emitter.emit("exception", event);
+  },
+  /**
+   * Subscribe to error events.
+   * @returns An unsubscribe function.
+   */
+  on(...args) {
+    return _emitter.on(...args);
+  },
+};

package/src/errors/BeraTracing.ts

@@ -0,0 +1,79 @@
+import type { Unsubscribe } from "~/utils/createEmitter";
+
+/**
+ * Span context passed to tracing handlers.
+ * Compatible with Sentry's StartSpanOptions (name, op, attributes).
+ */
+export type SpanContext = {
+  name: string;
+  op: string;
+  attributes: Record<string, string | number | boolean | undefined>;
+};
+
+/**
+ * A function that wraps a callback in a tracing span.
+ * Compatible with Sentry.startSpan's signature.
+ */
+type StartSpanFn = <T>(
+  context: SpanContext,
+  callback: () => Promise<T>,
+) => Promise<T>;
+
+const _handlers: StartSpanFn[] = [];
+
+/**
+ * A generic span-tracing module for berajs.
+ *
+ * Instead of calling Sentry.startSpan directly, berajs calls
+ * `BeraTracing.startSpan()`. Consumer apps subscribe via `.on("span", handler)`
+ * and forward spans to their tracing provider (Sentry, Datadog, etc.).
+ *
+ * Multiple handlers are supported and chain in registration order:
+ * the first registered handler is the outermost wrapper.
+ *
+ * @example
+ * ```ts
+ * // In berajs code:
+ * import { BeraTracing } from "~/errors/BeraTracing";
+ * const result = await BeraTracing.startSpan(
+ *   { name: "GraphQL query", op: "graphql.query", attributes: {} },
+ *   () => executeQuery(),
+ * );
+ *
+ * // In app instrumentation:
+ * import { BeraTracing } from "@berachain/berajs/errors";
+ * BeraTracing.addSpanHandler(Sentry.startSpan);
+ * ```
+ */
+export const BeraTracing = {
+  /**
+   * Execute a callback, wrapping it in all registered span handlers.
+   *
+   * Handlers chain so each wraps the next. First registered = outermost wrapper.
+   * If no handlers are registered, the callback is executed directly.
+   */
+  startSpan<T>(context: SpanContext, callback: () => Promise<T>): Promise<T> {
+    if (_handlers.length === 0) return callback();
+
+    // Chain: h1(ctx, () => h2(ctx, () => h3(ctx, () => callback())))
+    return _handlers.reduceRight<() => Promise<T>>(
+      (next, handler) => () => handler(context, next),
+      callback,
+    )();
+  },
+
+  /**
+   * Register a span tracing handler.
+   *
+   * @param _event - Must be "span". Exists for API consistency with BeraMonitoring.
+   * @param handler - A StartSpanFn, e.g. Sentry.startSpan.
+   * @returns An unsubscribe function to remove the handler.
+   */
+  addSpanHandler(handler: StartSpanFn): Unsubscribe {
+    _handlers.push(handler);
+    return () => {
+      const idx = _handlers.indexOf(handler);
+      if (idx !== -1) _handlers.splice(idx, 1);
+    };
+  },
+};

package/src/errors/BeraTracing.unit.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { BeraTracing } from "./BeraTracing.js";
+
+describe("BeraTracing", () => {
+  describe("startSpan with no handlers", () => {
+    it("executes the callback directly", async () => {
+      const callback = vi.fn().mockResolvedValue("result");
+      const result = await BeraTracing.startSpan(
+        { name: "test", op: "test.op", attributes: {} },
+        callback,
+      );
+      expect(result).toBe("result");
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("startSpan with a single handler", () => {
+    it("wraps the callback in the handler", async () => {
+      const order: string[] = [];
+
+      const handler = vi.fn(async (context: any, callback: any) => {
+        order.push("handler-start");
+        const result = await callback();
+        order.push("handler-end");
+        return result;
+      });
+
+      const unsub = BeraTracing.addSpanHandler(handler);
+
+      const result = await BeraTracing.startSpan(
+        { name: "test", op: "test.op", attributes: { key: "value" } },
+        async () => {
+          order.push("callback");
+          return 42;
+        },
+      );
+
+      expect(result).toBe(42);
+      expect(order).toEqual(["handler-start", "callback", "handler-end"]);
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler.mock.calls[0][0]).toEqual({
+        name: "test",
+        op: "test.op",
+        attributes: { key: "value" },
+      });
+
+      unsub();
+    });
+  });
+
+  describe("startSpan with multiple handlers", () => {
+    it("chains handlers so first registered is outermost", async () => {
+      const order: string[] = [];
+
+      const handler1 = async (_ctx: any, cb: () => Promise<any>) => {
+        order.push("h1-start");
+        const r = await cb();
+        order.push("h1-end");
+        return r;
+      };
+      const handler2 = async (_ctx: any, cb: () => Promise<any>) => {
+        order.push("h2-start");
+        const r = await cb();
+        order.push("h2-end");
+        return r;
+      };
+      const handler3 = async (_ctx: any, cb: () => Promise<any>) => {
+        order.push("h3-start");
+        const r = await cb();
+        order.push("h3-end");
+        return r;
+      };
+
+      const unsub1 = BeraTracing.addSpanHandler(handler1);
+      const unsub2 = BeraTracing.addSpanHandler(handler2);
+      const unsub3 = BeraTracing.addSpanHandler(handler3);
+
+      await BeraTracing.startSpan(
+        { name: "test", op: "test.op", attributes: {} },
+        async () => {
+          order.push("callback");
+          return "done";
+        },
+      );
+
+      // h1 wraps h2 wraps h3 wraps callback
+      expect(order).toEqual([
+        "h1-start",
+        "h2-start",
+        "h3-start",
+        "callback",
+        "h3-end",
+        "h2-end",
+        "h1-end",
+      ]);
+
+      unsub1();
+      unsub2();
+      unsub3();
+    });
+  });
+
+  describe("on() returns unsubscribe", () => {
+    it("removes the handler when unsubscribe is called", async () => {
+      const handler = vi.fn(async (_ctx: any, cb: any) => cb());
+      const unsub = BeraTracing.addSpanHandler(handler);
+
+      await BeraTracing.startSpan(
+        { name: "test", op: "test.op", attributes: {} },
+        async () => "a",
+      );
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      unsub();
+
+      await BeraTracing.startSpan(
+        { name: "test", op: "test.op", attributes: {} },
+        async () => "b",
+      );
+      // Handler should not have been called again
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    it("is idempotent (double-unsubscribe does not throw)", () => {
+      const handler = vi.fn(async (_ctx: any, cb: any) => cb());
+      const unsub = BeraTracing.addSpanHandler(handler);
+
+      unsub();
+      expect(() => unsub()).not.toThrow();
+    });
+  });
+
+  describe("error propagation", () => {
+    it("propagates errors from the callback through handlers", async () => {
+      const handler = async (_ctx: any, cb: () => Promise<any>) => cb();
+      const unsub = BeraTracing.addSpanHandler(handler);
+
+      await expect(
+        BeraTracing.startSpan(
+          { name: "test", op: "test.op", attributes: {} },
+          async () => {
+            throw new Error("callback error");
+          },
+        ),
+      ).rejects.toThrow("callback error");
+
+      unsub();
+    });
+
+    it("propagates errors from a handler", async () => {
+      const handler = async () => {
+        throw new Error("handler error");
+      };
+      const unsub = BeraTracing.addSpanHandler(handler);
+
+      await expect(
+        BeraTracing.startSpan(
+          { name: "test", op: "test.op", attributes: {} },
+          async () => "ok",
+        ),
+      ).rejects.toThrow("handler error");
+
+      unsub();
+    });
+  });
+
+  describe("Sentry.startSpan compatibility", () => {
+    it("works with a handler that accepts (options, callback) like Sentry.startSpan", async () => {
+      // Sentry.startSpan signature: <T>(options, callback: (span) => T) => T
+      // When callback returns Promise<T>, the return is Promise<T>
+      const mockSentryStartSpan = <T>(
+        _options: { name: string },
+        callback: (span: unknown) => T,
+      ): T => {
+        // Sentry passes a span object to the callback; our callbacks ignore it
+        return callback({ spanId: "mock-span" });
+      };
+
+      const unsub = BeraTracing.addSpanHandler(
+        mockSentryStartSpan as typeof BeraTracing.startSpan,
+      );
+
+      const result = await BeraTracing.startSpan(
+        {
+          name: "GraphQL TestQuery",
+          op: "BeraApolloClient.query",
+          attributes: {},
+        },
+        async () => ({ data: { value: 1 } }),
+      );
+
+      expect(result).toEqual({ data: { value: 1 } });
+
+      unsub();
+    });
+  });
+});

package/src/errors/RequestError.ts

@@ -1,6 +1,6 @@
 import type { ErrorLike } from "@apollo/client";
 
-import mainnet from "@berachain/config/mainnet";
+import { mainnet } from "@berachain/config/mainnet";
 
 import { BeraError, type IBeraErrorArgs } from "./BeraError";
 import { errorMsgMap } from "./errorMap";
@@ -31,7 +31,7 @@ export class RequestError extends BeraError {
    */
   private queryRichfulDomains = [
     mainnet.bex.aggregatorsProxyUrl,
-    "https://api.magpiefi.xyz/aggregator/quote",
+    "https://api.fly.trade/aggregator/quote",
     "https://open-api.openocean.finance/v4/bera/swap",
     // vercel internal proxy
     "/api/aggregators?aggregator",

package/src/errors/assert.ts

@@ -1,3 +1,4 @@
+import type { GetPublicClientReturnType } from "@wagmi/core";
 import { type Address, isAddress, type PublicClient } from "viem";
 
 import { InvalidArgumentError } from "./InvalidArgumentError";
@@ -83,7 +84,8 @@ export function assertPublicClient(
   /**
    * The value to assert.
    */
-  value: PublicClient | undefined,
+  value: // it's important to have both types here because it helps with typescript build performance
+  PublicClient | GetPublicClientReturnType | undefined,
   /**
    * The property name.
    */
@@ -101,7 +103,7 @@ export function assertAddress(
   /**
    * The value to assert.
    */
-  value: string | undefined,
+  value: string | undefined | null,
   /**
    * The property name.
    */

package/src/errors/assert.unit.test.ts

@@ -61,8 +61,12 @@ describe("assertAddress", () => {
   });
 
   it("throws InvalidArgumentError for non-string", () => {
-    expect(() => assertAddress(123, "addr")).toThrow(InvalidArgumentError);
-    expect(() => assertAddress({}, "addr")).toThrow(InvalidArgumentError);
+    expect(() => assertAddress(123 as unknown as string, "addr")).toThrow(
+      InvalidArgumentError,
+    );
+    expect(() => assertAddress({} as unknown as string, "addr")).toThrow(
+      InvalidArgumentError,
+    );
   });
 
   it("throws InvalidArgumentError for invalid address string", () => {

package/src/errors/errorMap.ts

@@ -17,7 +17,7 @@ export interface ErrorCategory {
   [key: string]: ErrorType;
 }
 
-export interface ErrorMessages {
+interface ErrorMessages {
   [key: string]: ErrorCategory | string;
 }
 
@@ -94,10 +94,10 @@ export const errorMsgMap = {
       errorMSG:
         "It seems an RPC error has occurred. Please try your request one more later.",
     },
-    // ETH_GETBALANCE: {
-    //   keywords: "eth_getBalance",
-    //   err: "An RPC error has been detected. Please attempt your request after a short while.",
-    // },
+    NOT_ENOUGH_GAS: {
+      keywords: ["insufficient funds for gas * price + value:"],
+      errorMSG: "Gas balance is insufficient to cover the transaction cost.",
+    },
     HASH: {
       keywords: ["hash"],
 
@@ -120,6 +120,16 @@ export const errorMsgMap = {
         "Wallet seems to be on the wrong chain, please refresh the page and try again.",
     },
   },
+  EIP7702: {
+    SESSION_KEY_EXPIRED: {
+      reasons: ["SessionKeyExpired"],
+      errorMSG: "Session key has expired. Please create a new one.",
+    },
+    CALL_POLICY_VIOLATED: {
+      reasons: ["CallPolicyViolated"],
+      errorMSG: "Call policy violated. Please check your call policies.",
+    },
+  },
   HONEY: {
     BLACKLISTED_WALLET: {
       reasons: ["BlacklistedWallet", "0x265693b4"],
@@ -136,7 +146,7 @@ export const errorMsgMap = {
   // NOTE: descriptions are generated by GPT where not available.
   BEX: {
     SLIPPAGE_EXCEEDED: {
-      reasons: ["SlippageExceeded"],
+      reasons: ["SlippageExceeded", "TooMuchSlippage"],
       errorMSG:
         "Price changed while executing the transaction and exceeded the allowed slippage.",
     },

package/src/errors/{index.ts → exports.ts}

@@ -1,8 +1,15 @@
 export * from "./assert";
 export * from "./BeraError";
+export {
+  BeraMonitoring,
+  type CaptureContext,
+  type ErrorEvent,
+} from "./BeraMonitoring";
+export { BeraTracing, type SpanContext } from "./BeraTracing";
 export * from "./getErrorMessage";
 export * from "./InvalidArgumentError";
 export * from "./initBeraError";
 export * from "./NotFoundError";
 export * from "./RequestError";
+export type { SeverityLevel } from "./severity";
 export * from "./TransactionFailedError";

package/src/errors/getErrorMessage.ts

@@ -1,5 +1,23 @@
 import { type ErrorCategory, errorMsgMap, GENERAL_ERROR } from "./errorMap";
 
+/**
+ * Resolves a user-friendly displayMessage by matching `reason` and `message` against `errorMap.ts`.
+ *
+ * This is the bridge between the automatic reason detection pipeline (parseViemError) and
+ * the user-facing error messages. Called by the BeraError constructor.
+ *
+ * ## Matching priority:
+ * 1. **Exact reason match** (preferred): checks `errorType.reasons` for an exact string match.
+ *    This is the most reliable path — contract revert reasons like "NotEnoughBalance" or "BAL#508"
+ *    are matched deterministically.
+ * 2. **Keyword fallback**: checks `errorType.keywords` for substring matches in `message`.
+ *    Use sparingly — keyword matching can cause false positives (e.g. "InsufficientBalance"
+ *    keyword would also match "InsufficientBalanceToPayPythFee").
+ * 3. **GENERAL_ERROR fallback**: "Something went wrong. Please try again later."
+ *
+ * To ensure new contract errors get good displayMessages, add their reason to `errorMap.ts`.
+ * The reason is auto-detected by parseViemError — you only need to map it to a message here.
+ */
 export function getErrorMessage({
   reason,
   message,
@@ -7,16 +25,14 @@ export function getErrorMessage({
   reason?: string | null;
   message?: string;
 }): string {
-  // Check against defined categories
   for (const category in errorMsgMap) {
-    // Just for type safety
     const categoryKey = category as keyof typeof errorMsgMap;
-
     const errors = errorMsgMap[categoryKey] as ErrorCategory;
 
     for (const type in errors) {
       const errorType = errors[type];
 
+      // Priority 1: Exact reason match (deterministic, preferred for contract revert reasons)
       if (reason) {
         if (
           errorType?.reasons?.some((r) => {
@@ -26,6 +42,8 @@ export function getErrorMessage({
           return errorType.errorMSG;
         }
       }
+
+      // Priority 2: Keyword substring match on message (fallback, use carefully)
       if (
         errorType?.keywords?.some((keyword) => {
           return message?.includes(keyword.toLowerCase().trim());
@@ -36,5 +54,6 @@ export function getErrorMessage({
     }
   }
 
+  // Priority 3: No match found — return generic fallback
   return GENERAL_ERROR;
 }

package/src/errors/getRevertReason.integration.test.ts

@@ -17,18 +17,21 @@ import { mnemonicToAccount } from "viem/accounts";
 import { assert, describe, expect, it } from "vitest";
 
 import {
+  appConfig,
   ChainId,
   defaultChainId,
   getRpcUrls,
 } from "@berachain/config/internal";
 
-import { wagmiConfig } from "@berachain/wagmi/config";
+import { getConfig } from "@berachain/wagmi/config";
 
 import { metaMorphoAbi } from "~/abi/bend/metaMorpho";
 import { bgtAbi } from "~/abi/pol/bgt";
 import { rewardVaultAbi } from "~/abi/pol/rewardVault";
 import { beraWriteContract } from "~/actions/transactions/beraWriteContract";
+import { ContractName } from "~/enum/contracts";
 import { TransactionActionType } from "~/enum/txnEnum";
+import type { IContractWrite } from "~/types/global";
 import { getServerSidePublicClient } from "~/utils/getServerSideClient";
 import { parseBaseArgs } from "~/utils/parseBaseArgs";
 import { anvilMnemonic } from "~/utils/test-utils";
@@ -95,7 +98,6 @@ const expectedRevertReasons = [
 describe.skipIf(defaultChainId !== ChainId.MAINNET)("getRevertReason", () => {
   const publicClient = getServerSidePublicClient();
   const { config } = parseBaseArgs({});
-
   const errors = [
     {
       tx: "0x9c24d3fd3680411c0fada23ed5d1a11df86ea2f452eb9270bbe9cc701199511e",
@@ -407,6 +409,14 @@ describe("eip5972 transactions", () => {
     account: anvilMockAccount,
     chain: publicClient.chain!,
   });
+  const beraWagmiConfig = getConfig({
+    transports: {
+      [publicClient.chain!.id]: http(getRpcUrls().publicJsonRpcUrl),
+    },
+    defaultChain: publicClient.chain!,
+    thirdweb: { clientId: appConfig.apiKeys.public.thirdweb },
+  });
+  const wagmiConfig = beraWagmiConfig.wagmi;
 
   it.concurrent.each(expectedRevertReasons)(
     "should return the expected revert reason on sendCalls for $functionName to be $revertReason",
@@ -420,16 +430,18 @@ describe("eip5972 transactions", () => {
         calls: [
           {
             address: config.tokens.wbera,
+            contractName: ContractName.ERC20,
+            abi: erc20Abi,
             functionName: "approve",
             params: [zeroAddress, 0n],
-            abi: erc20Abi,
-          },
+          } as NonNullable<IContractWrite["calls"]>[number],
           {
+            contractName: ContractName.ERC20,
             address: "0x47a9E3A4b5a26eEDD0E53BC468bae31c24c9B158",
             abi: testErrorContractAbi,
             functionName,
             params: "args" in rest ? rest.args : undefined,
-          },
+          } as NonNullable<IContractWrite["calls"]>[number],
         ],
         message: "test",
         actionType: TransactionActionType.REDEEM_BGT,