@moonwell-fi/moonwell-sdk 0.12.0 → 0.12.1

package/actions/axiosWithRetry.ts

@@ -0,0 +1,42 @@
+/**
+ * Drop-in axios method wrappers with retry built in.
+ *
+ * Use these instead of `axios.get` / `axios.post` for outbound HTTP calls in
+ * action files. The retry policy lives in `./retry.ts`.
+ *
+ * Why a wrapper instead of `retry(() => axios.get(...))` at each callsite?
+ * TypeScript's control-flow narrowing (e.g. after `if (!env.url) return [];`)
+ * doesn't propagate into nested closures, so inline `retry(() => axios.get(env.url))`
+ * makes `env.url` `string | undefined` again. Passing the URL as a function
+ * argument keeps the narrowing intact.
+ */
+import axios, { type AxiosRequestConfig, type AxiosResponse } from "axios";
+
+import { retry } from "./retry.js";
+
+// Only forward args the caller actually passed — calling axios.get(url, undefined)
+// is observably different from axios.get(url) for tests that assert call arity.
+
+export function getWithRetry<T = unknown>(
+  url: string,
+  config?: AxiosRequestConfig,
+): Promise<AxiosResponse<T>> {
+  if (config !== undefined) {
+    return retry(() => axios.get<T>(url, config));
+  }
+  return retry(() => axios.get<T>(url));
+}
+
+export function postWithRetry<T = unknown, D = unknown>(
+  url: string,
+  data?: D,
+  config?: AxiosRequestConfig<D>,
+): Promise<AxiosResponse<T>> {
+  if (config !== undefined) {
+    return retry(() => axios.post<T, AxiosResponse<T>, D>(url, data, config));
+  }
+  if (data !== undefined) {
+    return retry(() => axios.post<T, AxiosResponse<T>, D>(url, data));
+  }
+  return retry(() => axios.post<T, AxiosResponse<T>, D>(url));
+}

package/actions/beam/getBeamTokenLimits.ts

@@ -1,7 +1,7 @@
-import axios from "axios";
 import type { HttpRequestError } from "../../common/index.js";
 import { Amount } from "../../common/index.js";
 import type { BeamTokenLimits, BeamTokenRoutes } from "../../types/beam.js";
+import { getWithRetry } from "../axiosWithRetry.js";
 
 export type GetBeamTokenLimitsErrorType = HttpRequestError;
 
@@ -36,7 +36,7 @@ export async function getBeamTokenLimits(
       direction === "withdraw" ? path.chainId : route.chainId;
 
     try {
-      const acrossLimitsResponse = await axios.get<{
+      const acrossLimitsResponse = await getWithRetry<{
         minDeposit: string;
         maxDeposit: string;
         maxDepositInstant: string;

package/actions/beam/getBeamTokenRoutes.ts

@@ -1,10 +1,10 @@
-import axios from "axios";
 import { zeroAddress } from "viem";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
 import type { HttpRequestError } from "../../common/index.js";
 import { getEnvironmentsFromArgs } from "../../common/index.js";
 import type { TokenConfig } from "../../environments/index.js";
 import type { BeamTokenInfo, BeamTokenRoutes } from "../../types/beam.js";
+import { getWithRetry } from "../axiosWithRetry.js";
 
 export type GetBeamTokenRoutesErrorType = HttpRequestError;
 
@@ -18,7 +18,7 @@ export async function getBeamTokenRoutes(
 ): GetBeamTokenRoutesReturnType {
   const environments = getEnvironmentsFromArgs(client, undefined, false);
 
-  const acrossRoutesResponse = await axios.get<
+  const acrossRoutesResponse = await getWithRetry<
     {
       originChainId: number;
       originToken: string;
@@ -30,7 +30,7 @@ export async function getBeamTokenRoutes(
     }[]
   >("https://across.to/api/available-routes");
 
-  const biconomyInfoResponse = await axios.get<{
+  const biconomyInfoResponse = await getWithRetry<{
     version: string;
     node: string;
     supportedChains: {

package/actions/core/markets/getMarketSnapshots.ts

@@ -1,4 +1,3 @@
-import axios from "axios";
 import type { MoonwellClient } from "../../../client/createMoonwellClient.js";
 import {
   type SnapshotPeriod,
@@ -12,6 +11,7 @@ import { buildMarketId } from "../../../common/lunar-indexer-helpers.js";
 import type { NetworkParameterType } from "../../../common/types.js";
 import type { Chain, Environment } from "../../../environments/index.js";
 import type { MarketSnapshot } from "../../../types/market.js";
+import { postWithRetry } from "../../axiosWithRetry.js";
 import {
   DEFAULT_LUNAR_TIMEOUT_MS,
   createLunarIndexerClient,
@@ -203,7 +203,7 @@ async function fetchCoreMarketSnapshotsFromPonder(
   let endCursor: string | undefined;
 
   while (hasNextPage) {
-    const result = await axios.post<{
+    const result = await postWithRetry<{
       data: {
         marketDailySnapshots: {
           items: MarketDailyData[];

package/actions/core/user-positions/getUserPositionSnapshots.ts

@@ -1,4 +1,3 @@
-import axios from "axios";
 import type { Address } from "viem";
 import type { MoonwellClient } from "../../../client/createMoonwellClient.js";
 import {
@@ -12,6 +11,7 @@ import {
 import type { NetworkParameterType } from "../../../common/types.js";
 import type { Chain, Environment } from "../../../environments/index.js";
 import type { UserPositionSnapshot } from "../../../types/userPosition.js";
+import { postWithRetry } from "../../axiosWithRetry.js";
 import {
   DEFAULT_LUNAR_TIMEOUT_MS,
   createLunarIndexerClient,
@@ -205,7 +205,7 @@ async function fetchUserPositionSnapshotsFromPonder(
   let endCursor: string | undefined;
 
   while (hasNextPage) {
-    const result = await axios.post<{
+    const result = await postWithRetry<{
       data: {
         accountDailySnapshots: {
           items: UserDailyData[];

package/actions/governance/getCirculatingSupplySnapshots.ts

@@ -1,9 +1,9 @@
-import axios from "axios";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
 import { getEnvironmentFromArgs } from "../../common/index.js";
 import type { OptionalNetworkParameterType } from "../../common/types.js";
 import type { Chain, Environment } from "../../environments/index.js";
 import type { CirculatingSupplySnapshot } from "../../types/circulatingSupply.js";
+import { getWithRetry, postWithRetry } from "../axiosWithRetry.js";
 
 export type GetCirculatingSupplySnapshotsParameters<
   environments,
@@ -46,7 +46,7 @@ async function fetchCirculatingSupplyFromLunar(
       params.cursor = cursor;
     }
 
-    const response = await axios.get<
+    const response = await getWithRetry<
       LunarPaginatedResponse<LunarCirculatingSupplySnapshot>
     >(`${lunarIndexerUrl}/api/v1/staking/circulating-supply/${chainId}`, {
       params,
@@ -118,7 +118,7 @@ async function fetchCirculatingSupplyFromPonder(
 ): Promise<CirculatingSupplySnapshot[]> {
   if (!environment.indexerUrl) return [];
   try {
-    const response = await axios.post<{
+    const response = await postWithRetry<{
       data: {
         circulatingSupplyDailySnapshots: {
           items: {

package/actions/governance/getDelegates.ts

@@ -1,4 +1,3 @@
-import axios from "axios";
 import { isAddress } from "viem";
 import { base, moonbeam, optimism } from "viem/chains";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
@@ -8,6 +7,7 @@ import {
 } from "../../environments/index.js";
 import * as logger from "../../logger/console.js";
 import type { Delegate } from "../../types/delegate.js";
+import { getWithRetry } from "../axiosWithRetry.js";
 import { fetchAllVoters } from "./governor-api-client.js";
 
 export type GetDelegatesReturnType = Promise<Delegate[]>;
@@ -119,7 +119,7 @@ const getForumProfiles = async () => {
 
   const getUsersPaginated = async (page = 0) => {
     try {
-      const response = await axios.get<{
+      const response = await getWithRetry<{
         directory_items: {
           user: {
             id: number;

package/actions/governance/getDiscussions.ts

@@ -1,9 +1,9 @@
-import axios from "axios";
 import lodash from "lodash";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
 import { HttpRequestError } from "../../common/index.js";
 import * as logger from "../../logger/console.js";
 import type { Discussion } from "../../types/discussion.js";
+import { getWithRetry } from "../axiosWithRetry.js";
 
 const { isEqual, uniqWith } = lodash;
 
@@ -43,7 +43,7 @@ export async function getDiscussions(
     "Starting to get discussions...",
   );
 
-  const moonwellProposalsResult = await axios.get<ForumTopicRequestResponse>(
+  const moonwellProposalsResult = await getWithRetry<ForumTopicRequestResponse>(
     "https://forum.moonwell.fi/c/proposals/moonwell-improvement-proposals/9/l/latest.json",
   );
 
@@ -51,9 +51,10 @@ export async function getDiscussions(
     throw new HttpRequestError(moonwellProposalsResult.statusText);
   }
 
-  const communityProposalsResult = await axios.get<ForumTopicRequestResponse>(
-    "https://forum.moonwell.fi/c/proposals/community-proposal/19/l/latest.json",
-  );
+  const communityProposalsResult =
+    await getWithRetry<ForumTopicRequestResponse>(
+      "https://forum.moonwell.fi/c/proposals/community-proposal/19/l/latest.json",
+    );
 
   if (
     communityProposalsResult.status !== 200 ||

package/actions/governance/getStakingSnapshots.ts

@@ -1,4 +1,3 @@
-import axios from "axios";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
 import {
   type SnapshotPeriod,
@@ -10,6 +9,7 @@ import {
 import type { NetworkParameterType } from "../../common/types.js";
 import type { Chain } from "../../environments/index.js";
 import type { StakingSnapshot } from "../../types/staking.js";
+import { postWithRetry } from "../axiosWithRetry.js";
 import {
   DEFAULT_LUNAR_TIMEOUT_MS,
   createLunarIndexerClient,
@@ -129,7 +129,7 @@ async function fetchStakingSnapshotsFromPonder(
   startTime?: number,
 ): Promise<StakingSnapshot[]> {
   try {
-    const response = await axios.post<{
+    const response = await postWithRetry<{
       data: {
         stakingDailySnapshots: {
           items: StakingSnapshot[];

package/actions/governance/getUserVotingPowers.ts

@@ -1,6 +1,10 @@
 import { type Address, zeroAddress } from "viem";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
-import { Amount, getEnvironmentsFromArgs } from "../../common/index.js";
+import {
+  Amount,
+  getBlockNumberAtTimestamp,
+  getEnvironmentsFromArgs,
+} from "../../common/index.js";
 import type { OptionalNetworkParameterType } from "../../common/types.js";
 import type { Chain, GovernanceToken } from "../../environments/index.js";
 import type { UserVotingPowers } from "../../types/userVotingPowers.js";
@@ -15,8 +19,21 @@ export type GetUserVotingPowersParameters<
   /** User address*/
   userAddress: Address;
 
-  /** Block number **/
+  /**
+   * Block number to read voting power at. Applied to every queried chain — only safe
+   * for single-chain governance tokens. For cross-chain tokens (e.g. WELL) prefer
+   * `snapshotTimestamp`, which resolves a correct per-chain block.
+   */
   blockNumber?: bigint;
+
+  /**
+   * Unix timestamp (seconds) at which to read voting power. When set, the SDK looks up
+   * the block on each queried chain whose timestamp is the latest one ≤ this value, and
+   * uses that per-chain block. Use this for cross-chain governance tokens; supplying a
+   * single block number across heterogeneous chains is unsafe because chain heights
+   * diverge. Takes priority over `blockNumber` when both are provided.
+   */
+  snapshotTimestamp?: number;
 };
 
 export type GetUserVotingPowersReturnType = Promise<UserVotingPowers[]>;
@@ -28,7 +45,7 @@ export async function getUserVotingPowers<
   client: MoonwellClient,
   args: GetUserVotingPowersParameters<environments, Network>,
 ): GetUserVotingPowersReturnType {
-  const { governanceToken, userAddress, blockNumber } = args;
+  const { governanceToken, userAddress, blockNumber, snapshotTimestamp } = args;
 
   const environments = getEnvironmentsFromArgs(client, args);
 
@@ -36,12 +53,30 @@ export async function getUserVotingPowers<
     (env) => env.custom?.governance?.token === governanceToken,
   );
 
+  const perChainBlockNumbers =
+    snapshotTimestamp !== undefined
+      ? await Promise.all(
+          tokenEnvironments.map((env) =>
+            getBlockNumberAtTimestamp(
+              env.publicClient,
+              BigInt(snapshotTimestamp),
+            ),
+          ),
+        )
+      : undefined;
+
   const environmentsUserVotingPowers = await Promise.all(
-    tokenEnvironments.map((environment) =>
-      environment.contracts.views?.read.getUserVotingPower([userAddress], {
-        blockNumber,
-      }),
-    ),
+    tokenEnvironments.map((environment, index) => {
+      const blockForChain = perChainBlockNumbers
+        ? perChainBlockNumbers[index]
+        : blockNumber;
+      return environment.contracts.views?.read.getUserVotingPower(
+        [userAddress],
+        {
+          blockNumber: blockForChain,
+        },
+      );
+    }),
   );
 
   return tokenEnvironments.map((environment, index) => {

package/actions/governance/governor-api-client.ts

@@ -1,5 +1,5 @@
-import axios from "axios";
 import type { Environment } from "../../environments/index.js";
+import { getWithRetry } from "../axiosWithRetry.js";
 
 /**
  * Base configuration for Governor API requests
@@ -108,7 +108,7 @@ export async function fetchProposals(
   if (options?.cursor) params.append("cursor", options.cursor);
   if (options?.chainId) params.append("chainId", options.chainId.toString());
 
-  const response = await axios.get<PaginatedResponse<ApiProposal>>(
+  const response = await getWithRetry<PaginatedResponse<ApiProposal>>(
     `${baseUrl}/api/v1/governor/proposals?${params.toString()}`,
   );
 
@@ -152,7 +152,7 @@ export async function fetchProposal(
 ): Promise<ApiProposal> {
   const baseUrl = getGovernorApiUrl(environment);
 
-  const response = await axios.get<ApiProposal>(
+  const response = await getWithRetry<ApiProposal>(
     `${baseUrl}/api/v1/governor/proposals/${proposalId}`,
   );
 
@@ -177,7 +177,7 @@ export async function fetchProposalVotes(
   if (options?.limit) params.append("limit", options.limit.toString());
   if (options?.cursor) params.append("cursor", options.cursor);
 
-  const response = await axios.get<PaginatedResponse<ApiVote>>(
+  const response = await getWithRetry<PaginatedResponse<ApiVote>>(
     `${baseUrl}/api/v1/governor/proposals/${proposalId}/votes?${params.toString()}`,
   );
 
@@ -225,7 +225,9 @@ export async function fetchProposalStateChanges(
   if (options?.limit) params.append("limit", options.limit.toString());
   if (options?.cursor) params.append("cursor", options.cursor);
 
-  const response = await axios.get<PaginatedResponse<ApiProposalStateChange>>(
+  const response = await getWithRetry<
+    PaginatedResponse<ApiProposalStateChange>
+  >(
     `${baseUrl}/api/v1/governor/proposals/${proposalId}/state-changes?${params.toString()}`,
   );
 
@@ -277,7 +279,7 @@ export async function fetchVoters(
   const endpoint = `${baseUrl}/api/v1/governor/voters?${params.toString()}`;
 
   try {
-    const response = await axios.get<PaginatedResponse<ApiVoter>>(endpoint);
+    const response = await getWithRetry<PaginatedResponse<ApiVoter>>(endpoint);
 
     if (response.status !== 200 || !response.data) {
       throw new Error(`Failed to fetch voters: ${response.statusText}`);
@@ -328,7 +330,7 @@ export async function fetchVoter(
 ): Promise<ApiVoter> {
   const baseUrl = getGovernorApiUrl(environment);
 
-  const response = await axios.get<ApiVoter>(
+  const response = await getWithRetry<ApiVoter>(
     `${baseUrl}/api/v1/governor/voters/${address}`,
   );
 
@@ -359,7 +361,7 @@ export async function fetchVoterProposals(
 
   const endpoint = `${baseUrl}/api/v1/governor/voters/${address}/proposals?${params.toString()}`;
 
-  const response = await axios.get<PaginatedResponse<ApiProposal>>(endpoint);
+  const response = await getWithRetry<PaginatedResponse<ApiProposal>>(endpoint);
 
   if (response.status !== 200 || !response.data) {
     throw new Error(`Failed to fetch voter proposals: ${response.statusText}`);
@@ -407,7 +409,7 @@ export async function fetchVoterVotes(
 
   const endpoint = `${baseUrl}/api/v1/governor/voters/${address}/votes?${params.toString()}`;
 
-  const response = await axios.get<PaginatedResponse<ApiVote>>(endpoint);
+  const response = await getWithRetry<PaginatedResponse<ApiVote>>(endpoint);
 
   if (response.status !== 200 || !response.data) {
     throw new Error(`Failed to fetch voter votes: ${response.statusText}`);
@@ -450,7 +452,7 @@ export async function fetchUserVoteReceipt(
 ): Promise<ApiVoteReceipt[]> {
   const baseUrl = getGovernorApiUrl(environment);
 
-  const response = await axios.get<ApiVoteReceipt[]>(
+  const response = await getWithRetry<ApiVoteReceipt[]>(
     `${baseUrl}/api/v1/governor/proposals/${proposalId}/vote/${voterAddress}`,
   );
 

package/actions/governance/proposals/common.ts

@@ -9,6 +9,7 @@ import {
   type Proposal,
   type ProposalState,
 } from "../../../types/proposal.js";
+import { postWithRetry } from "../../axiosWithRetry.js";
 import type { ApiProposal } from "../governor-api-client.js";
 
 export const WORMHOLE_CONTRACT = "0xc8e2b0cd52cf01b0ce87d389daa3d414d4ce29f3";
@@ -656,7 +657,7 @@ export const getExtendedProposalData = async (params: {
   try {
     while (shouldContinue && page < MAX_PAGES) {
       page++;
-      const response = await axios.post<{
+      const response = await postWithRetry<{
         data: {
           proposals: {
             items: {

package/actions/governance/snapshot/common.ts

@@ -1,4 +1,3 @@
-import axios from "axios";
 import {
   type Environment,
   base,
@@ -6,6 +5,7 @@ import {
   supportedChains,
 } from "../../../environments/index.js";
 import type { SnapshotProposal } from "../../../types/snapshotProposal.js";
+import { postWithRetry } from "../../axiosWithRetry.js";
 import type { GetSnapshotProposalsReturnType } from "./getSnapshotProposals.js";
 
 export const getSnapshotProposalData = async (params: {
@@ -32,7 +32,7 @@ export const getSnapshotProposalData = async (params: {
 
   const pageSize = params.pagination?.size ? params.pagination.size : 10;
 
-  const response = await axios.post<{
+  const response = await postWithRetry<{
     data: {
       spaces: {
         proposalsCount: number;

package/actions/lunar-indexer-client.ts

@@ -7,6 +7,8 @@
 
 import axios, { type AxiosInstance, type AxiosError } from "axios";
 
+import { attachRetryInterceptor } from "./retry.js";
+
 // ============================================================================
 // Type Definitions
 // ============================================================================
@@ -301,6 +303,12 @@ export class LunarIndexerClient {
         "Content-Type": "application/json",
       },
     });
+
+    // Retry transient failures (5xx, network errors, timeouts) silently before
+    // surfacing to callers. 4xx (incl. 404) bypasses retries — see ./retry.ts.
+    attachRetryInterceptor(this.client);
+    attachRetryInterceptor(this.stakingClient);
+    attachRetryInterceptor(this.vaultsClient);
   }
 
   /**

package/actions/morpho/markets/common.ts

@@ -1,4 +1,3 @@
-import axios from "axios";
 import type { Address } from "viem";
 import { Amount } from "../../../common/amount.js";
 import type { MultichainReturnType } from "../../../common/types.js";
@@ -8,6 +7,7 @@ import type {
   PublicAllocatorSharedLiquidityType,
 } from "../../../types/morphoMarket.js";
 import type { MorphoReward } from "../../../types/morphoReward.js";
+import { getWithRetry } from "../../axiosWithRetry.js";
 import { getGraphQL } from "../utils/graphql.js";
 import {
   type GetMorphoMarketsRewardsReturnType as LunarIndexerRewardsType,
@@ -49,7 +49,7 @@ async function fetchSharedLiquidityFromLunar(
   lunarIndexerUrl: string,
   chainId: number,
 ): Promise<LunarSharedLiquidityResponse> {
-  const response = await axios.get<LunarSharedLiquidityResponse>(
+  const response = await getWithRetry<LunarSharedLiquidityResponse>(
     `${lunarIndexerUrl}/api/v1/isolated/shared-liquidity/${chainId}`,
   );
   return response.data;

package/actions/morpho/markets/lunarIndexerTransform.ts

@@ -8,7 +8,6 @@
  * @module morpho/markets/lunarIndexerTransform
  */
 
-import axios from "axios";
 import type { Address } from "viem";
 import { parseUnits } from "viem";
 import { Amount } from "../../../common/amount.js";
@@ -20,6 +19,7 @@ import type {
   PublicAllocatorSharedLiquidityType,
 } from "../../../types/morphoMarket.js";
 import type { MorphoReward } from "../../../types/morphoReward.js";
+import { getWithRetry } from "../../axiosWithRetry.js";
 
 /**
  * Lunar Indexer API Response Types
@@ -185,7 +185,7 @@ export async function fetchMarketsFromIndexer(
   }
   const queryString = params.toString();
   const url = `${lunarIndexerUrl}/api/v1/isolated/markets/${chainId}${queryString ? `?${queryString}` : ""}`;
-  const response = await axios.get<LunarIndexerMarketsResponse>(url);
+  const response = await getWithRetry<LunarIndexerMarketsResponse>(url);
   return response.data;
 }
 
@@ -198,7 +198,7 @@ export async function fetchMarketFromIndexer(
   marketId: string,
 ): Promise<LunarIndexerMarket> {
   const url = `${lunarIndexerUrl}/api/v1/isolated/market/${chainId}/${marketId.toLowerCase()}`;
-  const response = await axios.get<LunarIndexerMarket>(url);
+  const response = await getWithRetry<LunarIndexerMarket>(url);
   return response.data;
 }
 
@@ -240,7 +240,7 @@ export async function fetchMarketSnapshotsFromIndexer(
     queryString ? `?${queryString}` : ""
   }`;
 
-  const response = await axios.get<LunarIndexerMarketSnapshotsResponse>(url);
+  const response = await getWithRetry<LunarIndexerMarketSnapshotsResponse>(url);
   return response.data;
 }
 
@@ -281,7 +281,8 @@ export async function fetchAccountMarketPortfolioFromIndexer(
     queryString ? `?${queryString}` : ""
   }`;
 
-  const response = await axios.get<LunarIndexerAccountPortfolioResponse>(url);
+  const response =
+    await getWithRetry<LunarIndexerAccountPortfolioResponse>(url);
   return response.data;
 }
 

package/actions/retry.ts

@@ -0,0 +1,121 @@
+/**
+ * Retry helpers for SDK API calls.
+ *
+ * Two consumers:
+ *  1. `attachRetryInterceptor` — axios response interceptor used inside
+ *     LunarIndexerClient. One install per axios instance covers every method.
+ *  2. `retry` — generic wrapper for ad-hoc `axios.post(...)` callsites in
+ *     actions that don't go through a shared axios instance.
+ *
+ * Policy:
+ *  - 3 attempts (initial + 2 retries) by default
+ *  - Exponential backoff: 250ms → 500ms (capped at 5s)
+ *  - Retry only network errors / timeouts / 5xx; never retry 4xx (incl. 404 —
+ *    retrying a deterministic "not found" wastes time and amplifies log noise)
+ *  - After retries exhaust, the last error propagates to the caller's try/catch
+ *    where the existing `environment.onError(...)` wiring picks it up
+ */
+import axios, {
+  type AxiosError,
+  type AxiosInstance,
+  type InternalAxiosRequestConfig,
+} from "axios";
+
+export interface RetryOptions {
+  maxAttempts?: number;
+  initialDelay?: number;
+  maxDelay?: number;
+}
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY_MS = 250;
+const DEFAULT_MAX_DELAY_MS = 5_000;
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function backoffDelay(
+  attemptIndex: number,
+  initialDelay: number,
+  maxDelay: number,
+): number {
+  return Math.min(initialDelay * 2 ** attemptIndex, maxDelay);
+}
+
+/**
+ * Decide whether an error represents a transient failure worth retrying.
+ * - Axios network errors (no `response`) → retry (server unreachable, timeout)
+ * - 5xx responses → retry (server hiccup)
+ * - 4xx responses (incl. 404) → do NOT retry (deterministic, won't change)
+ * - Non-axios errors (parse errors, code bugs) → do NOT retry
+ */
+export function isRetriableError(error: unknown): boolean {
+  if (!axios.isAxiosError(error)) return false;
+  if (!error.response) return true;
+  return error.response.status >= 500;
+}
+
+/**
+ * Attach a retry-on-failure interceptor to an axios instance. Every request
+ * made through this instance is retried up to `maxAttempts` times when the
+ * failure is retriable. Per-config state is tracked on a WeakMap so we don't
+ * pollute the public axios config shape.
+ */
+export function attachRetryInterceptor(
+  instance: AxiosInstance,
+  options: RetryOptions = {},
+): void {
+  const {
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    initialDelay = DEFAULT_INITIAL_DELAY_MS,
+    maxDelay = DEFAULT_MAX_DELAY_MS,
+  } = options;
+  const attemptsByConfig = new WeakMap<InternalAxiosRequestConfig, number>();
+
+  instance.interceptors.response.use(
+    (response) => response,
+    async (error: AxiosError) => {
+      const config = error.config;
+      if (!config) throw error;
+      if (!isRetriableError(error)) throw error;
+
+      const previousAttempts = attemptsByConfig.get(config) ?? 0;
+      if (previousAttempts >= maxAttempts - 1) throw error;
+
+      attemptsByConfig.set(config, previousAttempts + 1);
+      await sleep(backoffDelay(previousAttempts, initialDelay, maxDelay));
+      return instance.request(config);
+    },
+  );
+}
+
+/**
+ * Generic wrapper for individual axios calls (e.g. raw `axios.post(...)` in
+ * action files that don't share a configured instance). Mirrors the
+ * interceptor's policy: retry transient failures, fail fast on 4xx.
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const {
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    initialDelay = DEFAULT_INITIAL_DELAY_MS,
+    maxDelay = DEFAULT_MAX_DELAY_MS,
+  } = options;
+  let attempt = 0;
+  let lastError: unknown;
+  while (attempt < maxAttempts) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      attempt++;
+      if (!isRetriableError(error)) throw error;
+      if (attempt >= maxAttempts) break;
+      await sleep(backoffDelay(attempt - 1, initialDelay, maxDelay));
+    }
+  }
+  throw lastError;
+}