@berachain/berajs 0.1.2 → 0.2.1

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,10 +31,12 @@ 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",
+    // bonder endpoints have date-based query params (e.g. ?start=2025-11-28)
+    mainnet.bonder,
   ];
 
   statusCode: number | undefined;
@@ -116,7 +118,10 @@ export class RequestError extends BeraError {
       message += `HTTP ${this.statusCode} – `;
     }
 
-    this.message = `${message}${this.endpoint.type}(${this.endpoint.url}): ${this.message}`;
+    const endpointLabel = this.endpoint.type
+      ? `${this.endpoint.type}(${this.endpoint.url})`
+      : this.endpoint.url;
+    this.message = `${message}${endpointLabel}: ${this.message}`;
   }
 
   setEndpoint(
@@ -202,6 +207,27 @@ export class RequestError extends BeraError {
       }
     }
 
+    if (
+      typeof this.cause === "object" &&
+      this.cause !== null &&
+      "message" in this.cause &&
+      typeof this.cause.message === "string"
+    ) {
+      const message = this.cause.message as string;
+      // this is a postgres error message. found in some bonder errors.
+      if (
+        message.startsWith(
+          "error: canceling statement due to lock timeout occurred in",
+        )
+      ) {
+        return {
+          reason: RequestError.REASON_MAP.NETWORK_ERROR,
+          message: message,
+          url: this.endpoint.url,
+        };
+      }
+    }
+
     return false;
   }
 }

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;
 }
 
@@ -76,13 +76,19 @@ export const errorMsgMap = {
     },
   },
   RPC: {
-    INSUFFICIENT_FUNDS: {
+    NOT_ENOUGH_GAS_TOKEN: {
       reasons: ["InsufficientFundsError"],
       keywords: [
+        "insufficient funds for gas * price + value:",
         "The total cost (gas * gas fee + value) of executing this transaction exceeds the balance of the account.",
       ],
       errorMSG: "Insufficient BERA balance to perform this action.",
     },
+    NONCE_TOO_LOW: {
+      keywords: ["nonce too low: next nonce"],
+      errorMSG:
+        "Nonce is too low. Your wallet might have unconfirmed transactions.",
+    },
     GAS_PRICE: {
       keywords: ["gasLimit"],
       errorMSG:
@@ -94,13 +100,8 @@ 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.",
-    // },
     HASH: {
       keywords: ["hash"],
-
       errorMSG:
         "It seems an RPC error has occurred. Please check if your transaction was finalized. If not, please try again.",
     },
@@ -120,6 +121,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 +147,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,40 +1,98 @@
 import { type ErrorCategory, errorMsgMap, GENERAL_ERROR } from "./errorMap";
 
-export function getErrorMessage({
+export interface MatchedError {
+  /** The error key in the errorMap (e.g. "NOT_ENOUGH_GAS_TOKEN") */
+  key: string;
+  /** The category in the errorMap (e.g. "RPC", "BEX") */
+  category: string;
+  /** The user-friendly display message */
+  errorMSG: string;
+  /** Whether the match was by exact reason (true) or keyword (false) */
+  matchedByReason: boolean;
+}
+
+/**
+ * Finds the matching error entry in errorMap by reason or message.
+ *
+ * ## Matching priority:
+ * 1. **Exact reason match** (preferred): checks `errorType.reasons` for an exact string match.
+ * 2. **Keyword fallback**: checks `errorType.keywords` for case-insensitive substring matches in `message`.
+ *
+ * @returns The matched error entry with key and category, or null if no match found.
+ */
+export function findMatchingError({
   reason,
   message,
 }: {
   reason?: string | null;
   message?: string;
-}): string {
-  // Check against defined categories
+}): MatchedError | null {
   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) => {
             return r === reason;
           })
         ) {
-          return errorType.errorMSG;
+          return {
+            key: type,
+            category,
+            errorMSG: errorType.errorMSG,
+            matchedByReason: true,
+          };
         }
       }
+
+      // Priority 2: Keyword substring match on message (case-insensitive fallback, use carefully)
       if (
         errorType?.keywords?.some((keyword) => {
-          return message?.includes(keyword.toLowerCase().trim());
+          return message?.toLowerCase().includes(keyword.toLowerCase().trim());
         })
       ) {
-        return errorType.errorMSG;
+        return {
+          key: type,
+          category,
+          errorMSG: errorType.errorMSG,
+          matchedByReason: false,
+        };
       }
     }
   }
 
-  return GENERAL_ERROR;
+  return null;
+}
+
+/**
+ * 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 case-insensitive 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,
+}: {
+  reason?: string | null;
+  message?: string;
+}): string {
+  return findMatchingError({ reason, message })?.errorMSG ?? GENERAL_ERROR;
 }