@berachain/berajs 0.1.2 → 0.2.1

package/dist/errors/exports.d.cts

@@ -0,0 +1,408 @@
+import { GetPublicClientReturnType } from '@wagmi/core';
+import { PublicClient, Address, TransactionReceipt } from 'viem';
+import { B as BeraError, S as SeverityLevel, I as IBeraErrorArgs } from '../BeraError-_mQdkanr.cjs';
+export { R as RequestError } from '../RequestError-A8XJ6QR9.cjs';
+import { Hex } from '@berachain-foundation/berancer-sdk';
+import '@apollo/client';
+
+/**
+ * Asserts that a value is defined.
+ * @throws An InvalidArgumentError if the value is undefined or null.
+ */
+declare function assertDefined<T>(
+/**
+ * The value to assert.
+ */
+value: T, 
+/**
+ * The property name.
+ */
+property: string): asserts value is NonNullable<T>;
+/**
+ * Asserts that a value is a PublicClient.
+ * @throws An InvalidArgumentError if the value is undefined or not a PublicClient.
+ */
+declare function assertPublicClient(
+/**
+ * The value to assert.
+ */
+value: // it's important to have both types here because it helps with typescript build performance
+PublicClient | GetPublicClientReturnType | undefined, 
+/**
+ * The property name.
+ */
+property?: string): asserts value is PublicClient;
+/**
+ * Asserts that a value is an address (20 bytes).
+ * @throws An InvalidArgumentError if the value is undefined, null, not a string, or not an address.
+ */
+declare function assertAddress(
+/**
+ * The value to assert.
+ */
+value: string | undefined | null, 
+/**
+ * The property name.
+ */
+property: string): asserts value is Address;
+/**
+ * Asserts that a value is a number greater than 0.
+ * @throws An InvalidArgumentError if the value is undefined, null, not a string or number, or not a number greater than 0.
+ */
+declare function assertAmount(
+/**
+ * The value to assert.
+ */
+value: unknown, 
+/**
+ * The property name.
+ */
+property: string): asserts value is string | number;
+
+interface EventsMap {
+    [event: string]: any;
+}
+interface DefaultEvents extends EventsMap {
+    [event: string]: (...args: any) => void;
+}
+type Unsubscribe = () => void;
+/**
+ * An interface for mixins that expose the `on` function (without the emitter
+ * bound to `this`)
+ *
+ * ```js
+ * import { createEmitter } from '~utils/createEmitter'
+ *
+ * class Ticker implements EmitterMixin<Events> {
+ *   constructor() {
+ *     this.emitter = createEmitter()
+ *   }
+ *   on(...args) {
+ *     return this.emitter.on(...args)
+ *   }
+ *   tick() {
+ *     this.emitter.emit('tick')
+ *   }
+ * }
+ * ```
+ */
+interface EmitterMixin<Events extends EventsMap = DefaultEvents> {
+    on<K extends keyof Events>(event: K, cb: Events[K]): Unsubscribe;
+}
+
+/**
+ * Context passed alongside captured exceptions.
+ * Mirrors the subset of Sentry's CaptureContext that berajs actually uses.
+ */
+interface CaptureContext {
+    level: SeverityLevel;
+    extra?: Record<string, unknown>;
+    tags?: Record<string, string | number | boolean | null | undefined>;
+    fingerprint?: string[];
+    data?: Record<string, unknown>;
+}
+interface ErrorEvent {
+    exception: BeraError;
+    timestamp: number;
+}
+/**
+ * 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);
+ *   }
+ * });
+ * ```
+ */
+declare const BeraMonitoring: {
+    captureException: (exception: BeraError) => void;
+} & EmitterMixin<{
+    exception: (event: ErrorEvent) => void;
+}>;
+
+/**
+ * Span context passed to tracing handlers.
+ * Compatible with Sentry's StartSpanOptions (name, op, attributes).
+ */
+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>;
+/**
+ * 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);
+ * ```
+ */
+declare 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>;
+    /**
+     * 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;
+};
+
+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.
+ */
+declare function findMatchingError({ reason, message, }: {
+    reason?: string | null;
+    message?: string;
+}): MatchedError | 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.
+ */
+declare function getErrorMessage({ reason, message, }: {
+    reason?: string | null;
+    message?: string;
+}): string;
+
+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",
+ *  });
+ * }
+ * ```
+ *
+ */
+declare 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);
+    get isMissing(): boolean;
+    /**
+     * Whether the argument is defined but invalid.
+     */
+    get isInvalid(): boolean;
+}
+
+/**
+ * The preferred way to normalize any unknown error into a BeraError.
+ *
+ * This function acts as a smart factory that picks the correct BeraError subclass:
+ *
+ * 1. If `cause` is already a `BeraError`, returns it as-is (no double-wrapping).
+ * 2. If `cause` is a viem `BaseError`, runs `parseViemError` to classify it:
+ *    - If the root cause is an `HttpRequestError` (RPC transport failure), wraps it
+ *      in a `RequestError` with the endpoint URL extracted from the error.
+ * 3. Otherwise, wraps in a new `BeraError` — which triggers the automatic reason
+ *    detection pipeline in the BeraError constructor (parseViemError → errorMap → displayMessage).
+ *
+ * **Use this instead of `new BeraError({ cause })` when you don't know the error type.**
+ * It ensures RequestErrors are correctly classified (important for Sentry filtering
+ * and fingerprinting — RequestErrors are skipped from transaction error grouping).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   // Normalizes to the right subclass, reason auto-detected
+ *   throw initBeraError({ cause: error });
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Reporting to Sentry without rethrowing
+ * catch (error) {
+ *   captureException(initBeraError({ cause: error }));
+ * }
+ * ```
+ */
+declare function initBeraError({ cause: error, level, }: {
+    cause: unknown;
+    /**
+     * The severity level of the error, only used if the error is not a BeraError.
+     */
+    level?: SeverityLevel;
+}): BeraError;
+
+interface INotFoundErrorArgs extends IBeraErrorArgs {
+    resource: string;
+    id: string;
+    chainId: number;
+}
+/**
+ * Error thrown when a resource is not found.
+ */
+declare 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);
+}
+
+/**
+ * This error is generally thrown by beraWriteContract when a transaction or simulation fails.
+ */
+declare class TransactionFailedError extends BeraError {
+    /**
+     * The hash of the transaction that failed.
+     *
+     * Null if the error is due to a simulation failure.
+     */
+    txHash: string | null;
+    /**
+     * The receipt of the transaction that failed.
+     *
+     * Null if the error is due to a simulation failure.
+     */
+    receipt: TransactionReceipt | null;
+    /**
+     * The address of the contract that was called.
+     */
+    to: Address | undefined;
+    /**
+     * The data of the transaction that failed.
+     */
+    callData: Hex | undefined;
+    /**
+     * The block number of the transaction that failed.
+     */
+    blockNumber: bigint | null;
+    /**
+     * The input of the transaction that failed.
+     */
+    input: object;
+    /**
+     * The function name of the transaction that failed.
+     */
+    functionName: string | undefined;
+    constructor(args: IBeraErrorArgs & {
+        txHash?: string;
+        receipt?: TransactionReceipt;
+        to?: Address;
+        blockNumber?: bigint;
+        functionName?: string;
+        input: object;
+    });
+}
+
+export { BeraError, BeraMonitoring, BeraTracing, type CaptureContext, type ErrorEvent, IBeraErrorArgs, type IInvalidArgumentErrorArgs, type INotFoundErrorArgs, InvalidArgumentError, type MatchedError, NotFoundError, SeverityLevel, type SpanContext, TransactionFailedError, assertAddress, assertAmount, assertDefined, assertPublicClient, findMatchingError, getErrorMessage, initBeraError };