@berachain/berajs 0.1.1 → 0.2.0

package/src/errors/BeraError.ts

@@ -0,0 +1,241 @@
+import { type Abi, BaseError } from "viem";
+
+import { appConfig } from "@berachain/config/internal";
+
+import { GENERAL_ERROR } from "./errorMap";
+import { getErrorMessage } from "./getErrorMessage";
+import { parseViemError, rpcErrorToReason } from "./parseViemError";
+import type { SeverityLevel } from "./severity";
+
+export interface IBeraErrorArgs {
+  message?: string;
+  displayMessage?: string;
+  cause?: unknown;
+  reason?: string;
+  chainId?: number;
+  fingerprint?: string[];
+  /**
+   * The level of the error to be used for error reporting.
+   */
+  level?: SeverityLevel;
+  tags?: {
+    [key in TagsKey]?: Primitive;
+  };
+  extra?: Record<string, unknown>;
+  /**
+   * Optional ABI to be used to parse the error.
+   */
+  abi?: Abi;
+}
+
+type Primitive = number | string | boolean | bigint | symbol | null | undefined;
+
+/**
+ * An helper type to make sure we only use the allowed tags. Sync this with docs/errors.md
+ */
+type TagsKey =
+  | "wallet.chain"
+  | "wallet.connector"
+  | "wallet.address"
+  | "error.reason"
+  | "operation.type"
+  | "operation.key"
+  | "operation.txn.functionName"
+  | "operation.txn.to"
+  | "operation.txn.status"
+  | "operation.source.url"
+  | "operation.source.name"
+  | "operation.source.queryName"
+  | "operation.source.type";
+
+/**
+ * Base error class for the entire berajs SDK.
+ *
+ * All errors should be a BeraError or one of its subclasses. Unknown errors should be
+ * normalized via `initBeraError({ cause })`.
+ *
+ * Key design: the constructor runs an **automatic reason detection pipeline** when `reason`
+ * is not explicitly provided. It calls `parseViemError` on the `cause` to extract a
+ * machine-readable reason code (e.g. "NotEnoughBalance", "BAL#508", "UserRejectedRequestError").
+ * That reason is then matched against `errorMap.ts` to resolve a user-friendly `displayMessage`.
+ *
+ * This means: for most viem errors, you only need to pass `cause` and everything else
+ * (reason, displayMessage, level) is derived automatically.
+ *
+ * @see parseViemError — the reason extraction engine
+ * @see errorMap.ts — reason → displayMessage mapping
+ * @see initBeraError — normalizes any error into a BeraError (preferred entry point)
+ */
+export class BeraError extends Error {
+  /**
+   * A human-readable message that can be displayed to end user.
+   *
+   * In berachain dapps, this is shown in the error pop-up.
+   */
+  displayMessage: string;
+
+  /**
+   * The cause of the error.
+   *
+   * This is typically the error that was thrown.
+   */
+  cause: unknown;
+
+  /**
+   * The chain id of the error.
+   */
+  chainId?: number;
+
+  /**
+   * The code for the reason for the error.
+   *
+   * This is typically the error code can be found in the errorMap.ts file. I.e. NotEnoughBalance or BAL#508
+   */
+  reason: string | null = null;
+
+  /**
+   * The fingerprint for the error.
+   *
+   * This is typically used to group errors in Sentry.
+   */
+  fingerprint: string[] | undefined;
+
+  private _tags: {
+    [key: string | TagsKey]: Primitive;
+  } = {};
+
+  set tags(tags: {
+    [key: string | TagsKey]: Primitive;
+  }) {
+    this._tags = tags;
+  }
+
+  get tags(): {
+    [key: string | TagsKey]: Primitive;
+  } {
+    return {
+      ...this._tags,
+      "error.displayMessage": this.displayMessage,
+      "error.reason": this.reason,
+      "error.level": this.level,
+    };
+  }
+
+  level: SeverityLevel = "error";
+
+  extra: Record<string, unknown> = {};
+
+  constructor({
+    message: m,
+    displayMessage: dm,
+    cause,
+    reason,
+    level,
+    abi,
+    tags,
+    chainId,
+    fingerprint,
+  }: IBeraErrorArgs) {
+    let message = m;
+
+    if (!message) {
+      if (cause instanceof BaseError) {
+        // Using shortMesage as it doesn't include the payload.
+        message = cause.shortMessage;
+      } else if (cause instanceof Error) {
+        message = cause.message;
+      } else if (
+        typeof cause === "object" &&
+        cause !== null &&
+        "message" in cause &&
+        typeof cause.message === "string"
+      ) {
+        // this covers responses from HTTP requests
+        message = cause.message;
+      }
+    }
+    super(message, {
+      cause,
+    });
+
+    this.name = "BeraError";
+
+    this.fingerprint = fingerprint;
+
+    this.cause = cause;
+
+    this.chainId = chainId;
+
+    // ── Automatic reason detection ──────────────────────────────────────
+    // If `reason` was provided explicitly, use it directly.
+    // Otherwise, attempt to extract it from the `cause` by unwrapping the viem error chain.
+    // parseViemError walks nested errors (ContractFunctionExecutionError →
+    // ContractFunctionRevertedError → RpcRequestError) and decodes revert data using ABI.
+    // The extracted reason (e.g. "NotEnoughBalance", "BAL#508") is the key that drives
+    // displayMessage resolution and Sentry fingerprinting.
+    if (reason) {
+      this.reason = reason;
+    } else if (cause instanceof Error) {
+      try {
+        const parsed = parseViemError({
+          error: cause,
+          revertIfUnknown: true,
+          abi,
+        });
+
+        this.reason = parsed?.reason ?? null;
+      } catch {
+        // parseViemError throws when it can't identify the error type and revertIfUnknown=true.
+        // In that case, reason stays null and displayMessage falls back to GENERAL_ERROR.
+      }
+    }
+
+    // ── Level inference ─────────────────────────────────────────────────
+    // User rejections are "info" (not actionable by devs), everything else defaults to "error".
+    if (level) {
+      this.level = level;
+    } else if (this.reason === rpcErrorToReason("UserRejectedRequestError")) {
+      this.level = "info";
+    } else {
+      this.level = "error";
+    }
+
+    // ── displayMessage resolution ─────────────────────────────────────────
+    // Priority:
+    //   1. Explicit `displayMessage` passed by caller
+    //   2. Cascaded from a BeraError cause (if it has a non-generic message)
+    //   3. Looked up from errorMap.ts using the detected `reason` and `message`
+    //   4. GENERAL_ERROR fallback: "Something went wrong. Please try again later."
+    let displayMessage = dm;
+
+    if (
+      this.cause instanceof BeraError &&
+      this.cause.displayMessage !== GENERAL_ERROR
+    ) {
+      // Cascade: inner BeraError already resolved a good displayMessage, reuse it
+      displayMessage = this.cause.displayMessage;
+    }
+
+    if (!displayMessage) {
+      // Match reason (exact) or message (keyword) against errorMap.ts
+      displayMessage = getErrorMessage(this);
+    }
+
+    this.displayMessage = displayMessage ?? GENERAL_ERROR;
+
+    this.tags = {
+      ...this.tags,
+      ...tags,
+    };
+    // Useful for debugging in development or on vercel preview links
+    if (!appConfig.env.isProduction && process.env.NODE_ENV !== "test") {
+      console.group("BeraError thrown");
+      console.debug("Level", this.level);
+      console.debug("Reason", this.reason);
+      console.debug("Message", this.message);
+      console.debug("Display Message", this.displayMessage);
+      console.debug("Cause", this.cause);
+      console.groupEnd();
+    }
+  }
+}

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/InvalidArgumentError.ts

@@ -0,0 +1,81 @@
+import { BeraError, type IBeraErrorArgs } from "./BeraError";
+
+export interface IInvalidArgumentErrorArgs extends IBeraErrorArgs {
+  /**
+   * The name of the argument that is invalid.
+   */
+  property: string;
+  /**
+   * The value of the argument that is invalid.
+   */
+  value: unknown;
+
+  /**
+   * The expected type of the value as a string, eg. string, number, boolean, etc.
+   */
+  expected: string;
+}
+
+/**
+ * Error thrown when argument validation fails. (e.g. an argument is missing or invalid)
+ *
+ * Default level is "warning".
+ *
+ * @example ```ts
+ * if (!publicClient) {
+ *  throw new InvalidArgumentError({
+ *    property: "publicClient",
+ *    value: publicClient,
+ *    expected: "PublicClient",
+ *  });
+ * }
+ * if (!address || !isAddress(address)) {
+ *  throw new InvalidArgumentError({
+ *    property: "address",
+ *    value: address,
+ *    expected: "Address",
+ *  });
+ * }
+ * ```
+ *
+ */
+export class InvalidArgumentError extends BeraError {
+  /**
+   * The name of the argument that is invalid.
+   */
+  property: string;
+  /**
+   * The value of the argument that is invalid.
+   */
+  value: unknown;
+
+  /**
+   * The expected value of the argument.
+   */
+  expected: string;
+
+  constructor(args: IInvalidArgumentErrorArgs) {
+    super(args);
+    this.level = args.level ?? "warning";
+    this.name = "InvalidArgumentError";
+    this.property = args.property;
+    this.value = args.value;
+    this.expected = args.expected;
+    this.message = `Invalid argument: ${this.property} ${this.isMissing ? "is missing" : `is invalid, expected ${this.expected}`}`;
+
+    if (!args.reason) {
+      this.reason = `${this.name}.${this.property}.${this.isInvalid ? "invalid" : "missing"}`;
+    }
+  }
+
+  get isMissing(): boolean {
+    return this.value === undefined;
+  }
+
+  /**
+   * Whether the argument is defined but invalid.
+   */
+  get isInvalid(): boolean {
+    return this.value !== undefined;
+  }
+}

package/src/errors/NotFoundError.ts

@@ -0,0 +1,34 @@
+import { BeraError, type IBeraErrorArgs } from "./BeraError";
+
+export interface INotFoundErrorArgs extends IBeraErrorArgs {
+  resource: string;
+  id: string;
+  chainId: number;
+}
+
+/**
+ * Error thrown when a resource is not found.
+ */
+export class NotFoundError extends BeraError {
+  /**
+   * The name of the resource that was not found.
+   *
+   * @example "Reward vault"
+   */
+  resource: string;
+  /**
+   * The id of the resource that was not found.
+   *
+   * @example "0x1234567890123456789012345678901234567890"
+   */
+  id: string;
+
+  constructor(args: INotFoundErrorArgs) {
+    super(args);
+    this.name = "NotFoundError";
+    this.level = args.level ?? "info";
+    this.message = `Resource ${args.resource} with id ${args.id} not found`;
+    this.resource = args.resource;
+    this.id = args.id;
+  }
+}