@berachain/berajs 0.2.8-beta.9 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@berachain/berajs",
-  "version": "0.2.8-beta.9",
+  "version": "0.2.10",
   "sideEffects": false,
   "files": [
     "dist",
@@ -11,37 +11,73 @@
   "type": "module",
   "dependencies": {
     "@apollo/client": "4.1.6",
-    "@berachain-foundation/berancer-sdk": "1.1.4",
-    "@berachain/abis": "0.1.0",
-    "@berachain/config": "0.1.8",
-    "@berachain/graphql": "0.4.10-beta.2",
-    "@ensofinance/sdk": "2.0.12",
+    "@berachain-foundation/berancer-sdk": "1.1.7",
+    "@berachain/abis": "0.1.3-beta.0",
+    "@berachain/config": "0.1.17",
+    "@berachain/graphql": "0.5.0",
+    "@ensofinance/sdk": "2.3.1",
     "@pythnetwork/hermes-client": "2.0.0",
     "@wagmi/core": "2.22.1",
     "gray-matter": "4.0.3",
     "swr": "2.4.1"
   },
   "devDependencies": {
-    "@types/react-dom": "19.1.6",
-    "@types/react": "19.1.8",
+    "@types/react-dom": "19.2.3",
+    "@types/react": "19.2.14",
     "@typescript/analyze-trace": "0.10.1",
     "tsup": "8.5.1",
     "typescript": "5.5.4",
     "viem": "2.45.0",
     "vitest": "3.2.4",
     "@berachain/utils": "0.1.0",
-    "@berachain/wagmi": "0.4.2"
+    "@berachain/wagmi": "0.4.2-beta.6"
   },
   "exports": {
+    "./actions/*": {
+      "types": "./dist/actions/*/exports.d.ts",
+      "import": "./dist/actions/*/exports.mjs",
+      "require": "./dist/actions/*/exports.cjs",
+      "default": "./dist/actions/*/exports.cjs"
+    },
+    "./hooks/*": {
+      "types": "./dist/hooks/*/exports.d.ts",
+      "import": "./dist/hooks/*/exports.mjs",
+      "require": "./dist/hooks/*/exports.cjs",
+      "default": "./dist/hooks/*/exports.cjs"
+    },
+    "./enum/*": {
+      "types": "./dist/enum/*/exports.d.ts",
+      "import": "./dist/enum/*/exports.mjs",
+      "require": "./dist/enum/*/exports.cjs",
+      "default": "./dist/enum/*/exports.cjs"
+    },
+    "./types/*": {
+      "types": "./dist/types/*/exports.d.ts",
+      "import": "./dist/types/*/exports.mjs",
+      "require": "./dist/types/*/exports.cjs",
+      "default": "./dist/types/*/exports.cjs"
+    },
     "./*": {
       "types": "./dist/*/exports.d.ts",
       "import": "./dist/*/exports.mjs",
-      "module": "./dist/*/exports.mjs",
+      "require": "./dist/*/exports.cjs",
       "default": "./dist/*/exports.cjs"
     }
   },
   "typesVersions": {
     "*": {
+      "actions/*": [
+        "dist/actions/*/exports.d.ts"
+      ],
+      "hooks/*": [
+        "dist/hooks/*/exports.d.ts"
+      ],
+      "enum/*": [
+        "dist/enum/*/exports.d.ts"
+      ],
+      "types/*": [
+        "dist/types/*/exports.d.ts"
+      ],
       "*": [
         "dist/*/exports.d.ts"
       ]
@@ -51,7 +87,7 @@
     "react": "^19.1",
     "react-dom": "^19.1",
     "viem": "^2.41.2",
-    "@berachain/wagmi": "0.4.2"
+    "@berachain/wagmi": "0.4.2-beta.6"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -65,11 +101,11 @@
     }
   },
   "scripts": {
-    "build": "tsup",
+    "build": "NODE_OPTIONS='--max-old-space-size=8192' tsup",
     "prebuild": "pnpm contracts:update",
     "test": "vitest",
     "clean": "git clean -xdf dist .turbo node_modules",
-    "check-types": "tsup --dtsOnly",
+    "check-types": "NODE_OPTIONS='--max-old-space-size=8192' tsup --dtsOnly",
     "precheck-types": "pnpm prebuild",
     "dev": "tsup --watch",
     "lint": "biome lint",

package/src/actions/__test/transports.ts

@@ -0,0 +1,61 @@
+import { fallback, http } from "viem";
+import {
+  arbitrum,
+  avalanche,
+  base,
+  bsc,
+  mainnet,
+  optimism,
+  polygon,
+} from "viem/chains";
+
+import { publicJsonRpcUrl } from "@berachain/config/internal";
+import { defaultChain } from "@berachain/config/internal/wagmi";
+
+const transportOptions = {
+  batch: { wait: 35 },
+};
+
+const externalTransportOptions = {
+  batch: { wait: 15 },
+};
+
+export const urls = [publicJsonRpcUrl].filter(Boolean) as string[];
+
+/**
+ * Thirdweb RPC URLs have a rate limit of 3 RPS.
+ * http() uses default viem transport which varies based on the chain definition.
+ *
+ * Quicknode RPC URLs are CORS restricted to *.berachain.com, *.berachain-staging.com. They have a 100rpm rate limit.
+ */
+export const testTransports = {
+  [defaultChain.id]: fallback(urls.map((url) => http(url, transportOptions))),
+  [mainnet.id]: fallback([
+    http("https://1.rpc.thirdweb.com/", externalTransportOptions),
+    http(),
+  ]),
+  [polygon.id]: fallback([
+    http("https://137.rpc.thirdweb.com/", externalTransportOptions),
+    http(),
+  ]),
+  [optimism.id]: fallback([
+    http("https://10.rpc.thirdweb.com/", externalTransportOptions),
+    http(),
+  ]),
+  [base.id]: fallback([
+    http("https://8453.rpc.thirdweb.com/", externalTransportOptions),
+    http(),
+  ]),
+  [bsc.id]: fallback([
+    http("https://56.rpc.thirdweb.com/", externalTransportOptions),
+    http(),
+  ]),
+  [avalanche.id]: fallback([
+    http("https://43114.rpc.thirdweb.com/", externalTransportOptions),
+    http(),
+  ]),
+  [arbitrum.id]: fallback([
+    http("https://42161.rpc.thirdweb.com/", externalTransportOptions),
+    http(),
+  ]),
+};

package/src/actions/clients/exports.ts

@@ -0,0 +1,7 @@
+export { fetchBeep } from "./fetchBeep";
+export { fetchOpenApi } from "./fetchOpenApi";
+export { fetchRailwayBackend } from "./fetchRailwayBackend";
+export {
+  getApolloClient,
+  gql,
+} from "./getApolloClient";

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,93 @@
+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>;
+  };
+
+  // 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));
+  });
+
+  const search = query
+    ? new URLSearchParams(
+        Object.entries(query).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,223 @@
+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("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. mainnet)", () => {
+    expect(() =>
+      fetchBeep(
+        "/v0/stake/{vault}/earnings/{owner}",
+        { path: { vault: VAULT, owner: OWNER } },
+        { config: mainnet },
+      ),
+    ).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/clients/getApolloClient.ts

@@ -80,28 +80,68 @@ function getClient(
   });
 }
 
-type GraphqlClient =
-  | "honey.subgraph"
-  | "pol.subgraph"
-  | "pol.fees"
-  | "governance.subgraph"
-  | "bex.subgraph"
-  | "api"
-  | "bend.whisk";
+/**
+ * Browser-reachable Apollo client factory for `api` and Bend's `whisk`
+ * endpoints. Subgraph clients (honey/pol) are server-only; browser data
+ * access goes through the typed `/api/honey/*` and `/api/pol/*` REST
+ * endpoints. Same auth shape as bend.whiskApi — non-public env values only
+ * resolve server-side.
+ */
+type GraphqlClient = "api" | "bend.whisk" | "honey.subgraph" | "pol.subgraph";
+
+const SUBGRAPH_CLIENTS = [
+  "honey.subgraph",
+  "pol.subgraph",
+] as const satisfies readonly GraphqlClient[];
+
+type SubgraphClient = (typeof SUBGRAPH_CLIENTS)[number];
+
+function isSubgraphClient(name: GraphqlClient): name is SubgraphClient {
+  return SUBGRAPH_CLIENTS.includes(name as SubgraphClient);
+}
+
+const clientCache = new Map<string, BeraApolloClient>();
+
+function store(
+  cacheKey: string | null,
+  client: BeraApolloClient,
+): BeraApolloClient {
+  if (cacheKey) clientCache.set(cacheKey, client);
+  return client;
+}
 
 export function getApolloClient(
   clientName: GraphqlClient,
   { ...args }: BeraJS.BaseFunctionArgs,
 ): BeraApolloClient {
-  const { config } = parseBaseArgs(args);
+  if (typeof window !== "undefined" && isSubgraphClient(clientName)) {
+    throw new BeraError({
+      message: "Subgraph Apollo client is server-only",
+      level: "error",
+    });
+  }
+
+  const { config, chainId } = parseBaseArgs(args);
+
+  // Caller-supplied configs are treated as unique (may override URLs/headers),
+  // so they bypass the cache. The common path (chainId-only) is memoized.
+  const cacheKey = args.config ? null : `${chainId}:${clientName}`;
+
+  if (cacheKey) {
+    const cached = clientCache.get(cacheKey);
+    if (cached) return cached;
+  }
 
   switch (clientName) {
     case "api":
-      return getClient(applyStellateClientName(config.api), {
-        inMemoryCacheOptions: {
-          possibleTypes: apiResults.possibleTypes,
-        },
-      });
+      return store(
+        cacheKey,
+        getClient(applyStellateClientName(config.api), {
+          inMemoryCacheOptions: {
+            possibleTypes: apiResults.possibleTypes,
+          },
+        }),
+      );
 
     case "bend.whisk":
       if (!config.bend.whiskApi) {
@@ -110,17 +150,12 @@ export function getApolloClient(
           level: "error",
         });
       }
-      return getClient(config.bend.whiskApi);
+      return store(cacheKey, getClient(config.bend.whiskApi));
 
     case "honey.subgraph":
-      return getClient(config.honey.subgraph);
+      return store(cacheKey, getClient(config.honey.subgraph));
+
     case "pol.subgraph":
-      return getClient(config.pol.subgraph);
-    case "pol.fees":
-      return getClient(config.pol.feesSubgraph);
-    case "governance.subgraph":
-      return getClient(config.governance.subgraph);
-    case "bex.subgraph":
-      return getClient(config.bex.subgraph);
+      return store(cacheKey, getClient(config.pol.subgraph));
   }
 }