@berachain/berajs 0.2.9 → 0.2.11

package/src/actions/clients/fetchBeep.ts

@@ -0,0 +1,34 @@
+import type { paths } from "@berachain/graphql/beep";
+
+import { parseBaseArgs } from "../../utils/parseBaseArgs";
+import {
+  type DefinedParams,
+  fetchOpenApi,
+  type GetPath,
+  type GetResponse,
+} from "./fetchOpenApi";
+
+/**
+ * Typed GET against the next-gen "beep" backend.
+ *
+ * The `path`, its path/query params and the response are all type-checked
+ * against the beep schema (`@berachain/graphql/beep`), so route shapes (e.g.
+ * the `/v0/stake/*` namespace) can never drift out of sync with the backend.
+ * The base URL is resolved from `config.beep`.
+ *
+ * @throws if `config.beep` is not set for the active chain. Callers should only
+ * reach for beep when `config.beep` is non-null.
+ */
+export function fetchBeep<P extends GetPath<paths>>(
+  path: P,
+  params: DefinedParams<paths, P>,
+  args: BeraJS.BaseFunctionArgs = {},
+): Promise<GetResponse<paths, P>> {
+  const { config } = parseBaseArgs(args);
+
+  if (!config.beep) {
+    throw new Error("fetchBeep: `beep` backend is not configured.");
+  }
+
+  return fetchOpenApi<paths, P>(config.beep, path, params, "beep");
+}

package/src/actions/clients/fetchOpenApi.ts

@@ -0,0 +1,97 @@
+import type { HttpLink } from "@berachain/config";
+import { getUriFromLink } from "@berachain/config";
+
+import { beraFetchJson } from "../../utils/beraFetch";
+
+/**
+ * A minimal, fully-typed GET helper for our `openapi-typescript`-generated
+ * backends. Both backends serve only GETs, so rather than a full OpenAPI client
+ * we type a single `fetchOpenApi` against a schema's `paths` and wrap it per
+ * backend (`fetchBeep`, `fetchRailwayBackend`).
+ *
+ * The `path`, its path/query params and the response body are all type-checked
+ * against the schema, so route shapes can never drift out of sync with the
+ * backend. Requests go through {@link beraFetchJson} so they keep the same
+ * Sentry tracing, `RequestError` handling and URL sanitization as the rest of
+ * the codebase.
+ */
+
+/** Any `openapi-typescript` `paths` object. */
+// biome-ignore lint/suspicious/noExplicitAny: schema `paths` are structurally diverse; constrained at call sites by the concrete schema.
+type AnyPaths = Record<string, any>;
+
+/** Paths in a schema that expose a JSON GET response. */
+export type GetPath<Paths extends AnyPaths> = {
+  [P in keyof Paths]: Paths[P] extends {
+    get: { responses: { 200: { content: { "application/json": unknown } } } };
+  }
+    ? P
+    : never;
+}[keyof Paths];
+
+type GetParams<
+  Paths extends AnyPaths,
+  P extends GetPath<Paths>,
+> = Paths[P]["get"] extends { parameters: infer Params } ? Params : never;
+
+export type GetResponse<
+  Paths extends AnyPaths,
+  P extends GetPath<Paths>,
+> = Paths[P]["get"]["responses"][200]["content"]["application/json"];
+
+// Drop the params keys that are `never` (e.g. an endpoint with no query) so
+// callers only pass what an endpoint actually accepts.
+export type DefinedParams<Paths extends AnyPaths, P extends GetPath<Paths>> = {
+  [K in keyof GetParams<Paths, P> as GetParams<Paths, P>[K] extends never
+    ? never
+    : K]: GetParams<Paths, P>[K];
+};
+
+/**
+ * Perform a typed GET against an OpenAPI backend.
+ *
+ * @param link    The backend `HttpLink`. The base URL and monitoring name are
+ *                read from it.
+ * @param path    An OpenAPI path template, e.g. `/v0/stake/{vault}/stats-by-day`.
+ * @param params  Path and query params, typed from the schema for `path`.
+ * @param fallbackName  Monitoring name to use when `link` is a bare string.
+ */
+// biome-ignore lint/complexity/useMaxParams: internal helper; the wrappers (fetchBeep / fetchRailwayBackend) are the public surface.
+export function fetchOpenApi<Paths extends AnyPaths, P extends GetPath<Paths>>(
+  link: HttpLink,
+  path: P,
+  params: DefinedParams<Paths, P>,
+  fallbackName: string,
+): Promise<GetResponse<Paths, P>> {
+  const { path: pathParams, query } = params as {
+    path?: Record<string, string | number>;
+    query?: Record<string, string | number | undefined>;
+  };
+
+  // Substitute `{param}` placeholders from the typed path params.
+  const pathStr = path as string;
+  const resolvedPath = pathStr.replace(/\{([^}]+)\}/g, (_, key) => {
+    const value = pathParams?.[key];
+    if (value === undefined) {
+      throw new Error(
+        `fetchOpenApi: missing path param "${key}" for "${pathStr}"`,
+      );
+    }
+    return encodeURIComponent(String(value));
+  });
+
+  // Omit params whose value is `undefined` rather than serializing them as the
+  // literal string "undefined" (e.g. optional filters left unset by callers).
+  const search = query
+    ? new URLSearchParams(
+        Object.entries(query)
+          .filter(([, v]) => v !== undefined)
+          .map(([k, v]) => [k, String(v)]),
+      ).toString()
+    : "";
+
+  const url = `${getUriFromLink(link)}${resolvedPath}${search ? `?${search}` : ""}`;
+  const name = typeof link === "string" ? fallbackName : link.name;
+
+  return beraFetchJson<GetResponse<Paths, P>>({ url, name, type: "rest" });
+}

package/src/actions/clients/fetchOpenApi.unit.test.ts

@@ -0,0 +1,245 @@
+import {
+  assert,
+  beforeEach,
+  describe,
+  expect,
+  expectTypeOf,
+  it,
+  vi,
+} from "vitest";
+
+import type { HttpLink } from "@berachain/config";
+import { bepolia } from "@berachain/config/bepolia";
+import { mainnet } from "@berachain/config/mainnet";
+
+import type {
+  paths as beepPaths,
+  StakeEarningResponse,
+  StakeStatsByDayResponse,
+  ValidatorsResponse,
+} from "@berachain/graphql/beep";
+
+import { fetchBeep } from "./fetchBeep";
+import { fetchOpenApi } from "./fetchOpenApi";
+
+// Mock the network layer so we can assert exactly what the helpers build and
+// pass through, without hitting a backend.
+const beraFetchJson = vi.fn();
+vi.mock("../../utils/beraFetch", () => ({
+  beraFetchJson: (...args: unknown[]) => beraFetchJson(...args),
+}));
+
+const BASE = "https://beep.testnet.berachain.com";
+const NAMED_LINK: HttpLink = { name: "Berachain Beep", uri: BASE };
+
+const VAULT = "0x1111111111111111111111111111111111111111" as const;
+const OWNER = "0x2222222222222222222222222222222222222222" as const;
+
+describe("fetchOpenApi", () => {
+  beforeEach(() => {
+    beraFetchJson.mockReset();
+    beraFetchJson.mockResolvedValue(undefined);
+  });
+
+  it("substitutes path params and serializes the query", async () => {
+    await fetchOpenApi<beepPaths, "/v0/stake/{vault}/stats-by-day">(
+      NAMED_LINK,
+      "/v0/stake/{vault}/stats-by-day",
+      { path: { vault: VAULT }, query: { days: "30" } },
+      "beep",
+    );
+
+    expect(beraFetchJson).toHaveBeenCalledTimes(1);
+    expect(beraFetchJson).toHaveBeenCalledWith({
+      url: `${BASE}/v0/stake/${VAULT}/stats-by-day?days=30`,
+      name: "Berachain Beep",
+      type: "rest",
+    });
+  });
+
+  it("substitutes multiple path params and omits the query when absent", async () => {
+    await fetchOpenApi<beepPaths, "/v0/stake/{vault}/earnings/{owner}">(
+      NAMED_LINK,
+      "/v0/stake/{vault}/earnings/{owner}",
+      { path: { vault: VAULT, owner: OWNER } },
+      "beep",
+    );
+
+    expect(beraFetchJson).toHaveBeenCalledWith({
+      url: `${BASE}/v0/stake/${VAULT}/earnings/${OWNER}`,
+      name: "Berachain Beep",
+      type: "rest",
+    });
+  });
+
+  it("omits query params whose value is undefined", async () => {
+    await fetchOpenApi<beepPaths, "/v0/honey/transactions/latest">(
+      NAMED_LINK,
+      "/v0/honey/transactions/latest",
+      // `perPage` is set; `page` is left undefined and must not be serialized
+      // as the literal string "undefined".
+      { query: { page: undefined, perPage: "10" } },
+      "beep",
+    );
+
+    expect(beraFetchJson).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: `${BASE}/v0/honey/transactions/latest?perPage=10`,
+      }),
+    );
+  });
+
+  it("url-encodes path param values", async () => {
+    // `pubkey` is a free-form string segment; reserved chars must be encoded.
+    await fetchOpenApi<beepPaths, "/v0/validators/{pubkey}/incentives">(
+      NAMED_LINK,
+      "/v0/validators/{pubkey}/incentives",
+      { path: { pubkey: "a/b c" } },
+      "beep",
+    );
+
+    expect(beraFetchJson).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: `${BASE}/v0/validators/a%2Fb%20c/incentives`,
+      }),
+    );
+  });
+
+  it("falls back to the provided name for a string link", async () => {
+    await fetchOpenApi<beepPaths, "/v0/validators">(
+      BASE,
+      "/v0/validators",
+      {},
+      "beep",
+    );
+
+    expect(beraFetchJson).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "beep" }),
+    );
+  });
+
+  it("throws when a required path param is missing", () => {
+    expect(() =>
+      fetchOpenApi<beepPaths, "/v0/stake/{vault}/earnings/{owner}">(
+        NAMED_LINK,
+        "/v0/stake/{vault}/earnings/{owner}",
+        // @ts-expect-error — `vault` is required by the schema for this path.
+        { path: { owner: OWNER } },
+        "beep",
+      ),
+    ).toThrow(/missing path param "vault"/);
+  });
+
+  it("returns the response from beraFetchJson", async () => {
+    const response = [{ total_assets: "1", total_supply: "2", timestamp: 3 }];
+    beraFetchJson.mockResolvedValue(response);
+
+    const result = await fetchOpenApi<
+      beepPaths,
+      "/v0/stake/{vault}/stats-by-day"
+    >(
+      NAMED_LINK,
+      "/v0/stake/{vault}/stats-by-day",
+      { path: { vault: VAULT }, query: { days: "30" } },
+      "beep",
+    );
+
+    expect(result).toBe(response);
+  });
+});
+
+describe("fetchBeep", () => {
+  beforeEach(() => {
+    beraFetchJson.mockReset();
+    beraFetchJson.mockResolvedValue(undefined);
+  });
+
+  it("resolves the base URL from config.beep", async () => {
+    await fetchBeep(
+      "/v0/stake/{vault}/stats-by-day",
+      { path: { vault: VAULT }, query: { days: "30" } },
+      { config: bepolia },
+    );
+
+    expect(beraFetchJson).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: `${BASE}/v0/stake/${VAULT}/stats-by-day?days=30`,
+        name: "Berachain Beep",
+        type: "rest",
+      }),
+    );
+  });
+
+  it("throws when config.beep is not set (e.g. a chain not yet migrated)", () => {
+    // Construct the no-beep case explicitly rather than relying on a real
+    // chain config: `mainnet.beep` is env-gated, so it may be set in some
+    // environments.
+    const configWithoutBeep = { ...mainnet, beep: null };
+
+    expect(() =>
+      fetchBeep(
+        "/v0/stake/{vault}/earnings/{owner}",
+        { path: { vault: VAULT, owner: OWNER } },
+        { config: configWithoutBeep },
+      ),
+    ).toThrow(/`beep` backend is not configured/);
+  });
+});
+
+// Type-only assertions. The bodies are never executed at runtime (they would
+// hit the `beep` not-configured throw); they exist so `tsc` validates inference
+// and the `@ts-expect-error` lines. `expectTypeOf` is purely compile-time.
+describe("fetchBeep types", () => {
+  it("infers the response type per path", () => {
+    const _assert = () => {
+      expectTypeOf(
+        fetchBeep("/v0/stake/{vault}/stats-by-day", {
+          path: { vault: VAULT },
+          query: { days: "30" },
+        }),
+      ).resolves.toEqualTypeOf<StakeStatsByDayResponse>();
+
+      expectTypeOf(
+        fetchBeep("/v0/stake/{vault}/earnings/{owner}", {
+          path: { vault: VAULT, owner: OWNER },
+        }),
+      ).resolves.toEqualTypeOf<StakeEarningResponse>();
+
+      expectTypeOf(
+        fetchBeep("/v0/validators", {}),
+      ).resolves.toEqualTypeOf<ValidatorsResponse>();
+    };
+    assert.ok(_assert);
+  });
+
+  it("rejects unknown paths", () => {
+    const _assert = () => {
+      // @ts-expect-error — not a path in the beep schema.
+      fetchBeep("/v0/not/a/real/path", { path: {} });
+    };
+    assert.ok(_assert);
+  });
+
+  it("rejects unknown path params", () => {
+    const _assert = () => {
+      fetchBeep("/v0/stake/{vault}/stats-by-day", {
+        // @ts-expect-error — `owner` is not a param of stats-by-day.
+        path: { vault: VAULT, owner: OWNER },
+        query: { days: "30" },
+      });
+    };
+    assert.ok(_assert);
+  });
+
+  it("constrains query values to the schema enum", () => {
+    const _assert = () => {
+      fetchBeep("/v0/stake/{vault}/stats-by-day", {
+        path: { vault: VAULT },
+        // @ts-expect-error — `7` is not an allowed `days` value.
+        query: { days: "7" },
+      });
+    };
+
+    assert.ok(_assert);
+  });
+});

package/src/actions/clients/fetchRailwayBackend.ts

@@ -0,0 +1,34 @@
+import type { paths } from "@berachain/graphql/api";
+
+import { parseBaseArgs } from "../../utils/parseBaseArgs";
+import {
+  type DefinedParams,
+  fetchOpenApi,
+  type GetPath,
+  type GetResponse,
+} from "./fetchOpenApi";
+
+/**
+ * Typed GET against the legacy Railway backend.
+ *
+ * The `path`, its path/query params and the response are all type-checked
+ * against the Railway schema (`@berachain/graphql/api`). The base URL is
+ * resolved from `config.backend`.
+ *
+ * @deprecated The Railway backend is being replaced by beep; prefer
+ * {@link fetchBeep} where `config.beep` is available.
+ */
+export function fetchRailwayBackend<P extends GetPath<paths>>(
+  path: P,
+  params: DefinedParams<paths, P>,
+  args: BeraJS.BaseFunctionArgs = {},
+): Promise<GetResponse<paths, P>> {
+  const { config } = parseBaseArgs(args);
+
+  return fetchOpenApi<paths, P>(
+    config.backend,
+    path,
+    params,
+    "backend-railway",
+  );
+}

package/src/actions/enso/getEnsoUserTokensWithBalances.ts

@@ -31,6 +31,24 @@ export async function getEnsoUserTokensWithBalances({
     eoaAddress: account,
   });
 
+  // The Enso SDK can return a non-array (e.g. an error object) on a malformed
+  // or empty response. Guard before mapping to avoid the unactionable minified
+  // "(...).map is not a function" crash — but still report it as a typed,
+  // stably-grouped warning so we don't silently swallow an Enso API problem
+  // (an empty portfolio would otherwise look like "user has no tokens").
+  if (!Array.isArray(ensoBalances)) {
+    BeraMonitoring.captureException(
+      new InvalidArgumentError({
+        property: "ensoBalances",
+        value: ensoBalances,
+        expected: "BalanceToken[]",
+        chainId: typeof chainId === "number" ? chainId : undefined,
+        extra: { account, chainId },
+      }),
+    );
+    return [];
+  }
+
   const tokens: BalanceToken[] = ensoBalances.map(
     (balance) =>
       ({

package/src/actions/exports.ts

@@ -35,6 +35,7 @@ export * from "./honey/getHoneyPausedState";
 export * from "./honey/getHoneyPreview";
 export * from "./honey/getHoneyPythPriceOracle";
 export * from "./honey/getHoneyRootPriceOracle";
+export * from "./honey/getHoneyTxns";
 export * from "./honey/getHoneyVaultsBalance";
 export * from "./honey/getPythLatestPrices";
 export * from "./honey/getRelativeCapLimit";
@@ -43,6 +44,7 @@ export * from "./honey/isBadCollateralAsset";
 export * from "./honey/isBasketModeEnabled";
 export * from "./misc/getBlockTimestamp";
 export * from "./pol/getAutoclaimedIncentives";
+export * from "./pol/getAutoclaimedIncentivesTxHash";
 export * from "./pol/getBeraTokenTotalSupply";
 export * from "./pol/getBgtAprSimulation";
 export * from "./pol/getBgtIncentiveDistributorPaused";

package/src/actions/honey/getChartData.ts

@@ -1,18 +1,26 @@
+import type { HoneySnapshotResponse } from "@berachain/graphql/beep";
 import type { GetSnapshotsQuery } from "@berachain/graphql/honey";
 
 import { BeraError } from "../../errors/BeraError";
 import { beraFetchJson } from "../../utils/beraFetch";
+import { parseBaseArgs } from "../../utils/parseBaseArgs";
+import { fetchBeep } from "../clients/fetchBeep";
 
 /**
- * Browser-only. Hits the typed `/api/honey/snapshots` endpoint.
- * Server callers must compose the upstream query directly (this action is
- * not server-safe — `fetch` against a relative URL has no origin off-browser).
+ * Browser-only. Returns daily honey snapshots in the `beep` response shape
+ * (`HoneySnapshotResponse`) the chart consumes.
+ *
+ * Reads from the `beep` backend (`fetchBeep`) when configured, falling back to
+ * the legacy honey subgraph proxied through `/api/honey/snapshots` (whose
+ * GraphQL result is adapted into the beep shape) otherwise. Server callers must
+ * compose the upstream query directly (this action is not server-safe — `fetch`
+ * against a relative URL has no origin off-browser).
  */
 export async function getChartData({
   days,
 }: {
   days: number;
-}): Promise<GetSnapshotsQuery> {
+}): Promise<HoneySnapshotResponse> {
   if (typeof window === "undefined") {
     throw new BeraError({
       message:
@@ -21,13 +29,46 @@ export async function getChartData({
     });
   }
 
-  const params = new URLSearchParams({ interval: "day", first: String(days) });
-  const honeySnapshots = await beraFetchJson<
-    GetSnapshotsQuery["honeySnapshots"]
-  >({
-    url: `/api/honey/snapshots?${params}`,
-    name: "honey-snapshots",
-    type: "rest",
+  const { config } = parseBaseArgs({});
+
+  // TODO(beep): remove this entire block once `beep` is deployed on every
+  // chain. It is the only legacy honey-subgraph code left here; deleting it
+  // leaves the `beep` path below as the sole implementation.
+  if (!config.beep) {
+    const params = new URLSearchParams({
+      interval: "day",
+      first: String(days),
+    });
+    const snapshots = await beraFetchJson<GetSnapshotsQuery["honeySnapshots"]>({
+      url: `/api/honey/snapshots?${params}`,
+      name: "honey-snapshots",
+      type: "rest",
+    });
+    return snapshots.map(fromHoneySnapshot);
+  }
+
+  // beep backend (next-gen), typed against `@berachain/graphql/beep`. Queried
+  // directly from the browser — no Vercel proxy.
+  return fetchBeep("/v0/honey/snapshots/{interval}", {
+    path: { interval: "day" },
+    query: { perPage: String(days) },
   });
-  return { honeySnapshots };
+}
+
+/**
+ * Adapt a legacy subgraph snapshot into the beep `HoneySnapshotResponse` shape.
+ *
+ * The subgraph reports `timestamp` in microseconds; beep (and every consumer)
+ * expects seconds, so scale microseconds → seconds.
+ */
+function fromHoneySnapshot(
+  snapshot: GetSnapshotsQuery["honeySnapshots"][number],
+): HoneySnapshotResponse[number] {
+  return {
+    timestamp: Math.floor(Number(snapshot.timestamp) / 1_000_000),
+    mintVolume: snapshot.mintVolume,
+    redeemVolume: snapshot.redeemVolume,
+    totalVolume: snapshot.totalVolume,
+    totalSupply: snapshot.totalSupply,
+  };
 }

package/src/actions/honey/getHoney24hVolume.ts

@@ -3,8 +3,16 @@ import BigNumber from "@berachain/utils/pkg/bignumber.js";
 
 import { BeraError } from "../../errors/BeraError";
 import { beraFetchJson } from "../../utils/beraFetch";
+import { parseBaseArgs } from "../../utils/parseBaseArgs";
+import { fetchBeep } from "../clients/fetchBeep";
 
-/** Browser-only. Hits `/api/honey/snapshots?interval=hour&first=24` and reduces. */
+/**
+ * Browser-only. Sums the last 24 hourly honey snapshots into a 24h volume.
+ *
+ * Reads from the `beep` backend (`fetchBeep`) when configured, falling back to
+ * the legacy honey subgraph proxied through `/api/honey/snapshots` otherwise.
+ * Both backends expose `totalVolume` per snapshot, so the sum is shape-agnostic.
+ */
 export async function getHoney24hVolume(): Promise<BigNumber | undefined> {
   if (typeof window === "undefined") {
     throw new BeraError({
@@ -14,12 +22,32 @@ export async function getHoney24hVolume(): Promise<BigNumber | undefined> {
     });
   }
 
-  const params = new URLSearchParams({ interval: "hour", first: "24" });
-  const snapshots = await beraFetchJson<GetSnapshotsQuery["honeySnapshots"]>({
-    url: `/api/honey/snapshots?${params}`,
-    name: "honey-snapshots",
-    type: "rest",
+  const { config } = parseBaseArgs({});
+
+  // TODO(beep): remove this entire block once `beep` is deployed on every
+  // chain. It is the only legacy honey-subgraph code left here; deleting it
+  // leaves the `beep` path below as the sole implementation.
+  if (!config.beep) {
+    const params = new URLSearchParams({ interval: "hour", first: "24" });
+    const snapshots = await beraFetchJson<GetSnapshotsQuery["honeySnapshots"]>({
+      url: `/api/honey/snapshots?${params}`,
+      name: "honey-snapshots",
+      type: "rest",
+    });
+    return sumTotalVolume(snapshots);
+  }
+
+  // beep backend (next-gen), typed against `@berachain/graphql/beep`. Queried
+  // directly from the browser — no Vercel proxy.
+  const snapshots = await fetchBeep("/v0/honey/snapshots/{interval}", {
+    path: { interval: "hour" },
+    query: { perPage: "24" },
   });
+
+  return sumTotalVolume(snapshots);
+}
+
+function sumTotalVolume(snapshots: { totalVolume: string }[]): BigNumber {
   return snapshots.reduce(
     (acc, curr) => new BigNumber(curr.totalVolume).plus(acc),
     new BigNumber(0),