allow fetch functions to pass headers

Author: kadirchan

src/lib/mina/fetch.ts

@@ -56,6 +56,8 @@ export {
   getCachedGenesisConstants,
   addCachedAccount,
   networkConfig,
+  setMinaDefaultHeaders,
+  setArchiveDefaultHeaders,
   setGraphqlEndpoint,
   setGraphqlEndpoints,
   setMinaGraphqlFallbackEndpoints,
@@ -85,6 +87,10 @@ type ActionsQueryInputs = {
   tokenId?: string;
 };
 
+let minaDefaultHeaders: HeadersInit = {};
+
+let archiveDefaultHeaders: HeadersInit = {};
+
 let networkConfig = {
   minaEndpoint: '',
   minaFallbackEndpoints: [] as string[],
@@ -102,6 +108,52 @@ function checkForValidUrl(url: string) {
   }
 }
 
+/**
+ * Internal function to classify the URL as an archive node or not.
+ * @param url graphql endpoint
+ * @returns boolean indicating if the URL is an archive node or not
+ */
+function isArchiveUrl(url: string): boolean {
+  return (
+    url === networkConfig.archiveEndpoint ||
+    networkConfig.archiveFallbackEndpoints.includes(url)
+  );
+}
+
+/**
+ * Sets up the default headers to be used for all Mina node GraphQL requests, example usage:
+ * ```typescript
+ * setMinaDefaultHeaders({ Authorization: 'Bearer example-token' });
+ * ```
+ *
+ * It can be overridden by passing headers to the individual fetch functions, example usage:
+ * ```typescript
+ * setMinaDefaultHeaders({ Authorization: 'Bearer default-token' });
+ * await fetchAccount({publicKey}, minaEndpoint, { headers: { Authorization: 'Bearer override-token' } });
+ * ```
+ * @param headers Arbitrary sized headers to be used for all Mina node GraphQL requests.
+ */
+function setMinaDefaultHeaders(headers: HeadersInit) {
+  minaDefaultHeaders = headers;
+}
+
+/**
+ * Sets up the default headers to be used for all Archive node GraphQL requests, example usage:
+ * ```typescript
+ * setArchiveDefaultHeaders({ Authorization: 'Bearer example-token' });
+ * ```
+ *
+ * It can be overridden by passing headers to the individual fetch functions, example usage:
+ * ```typescript
+ * setArchiveDefaultHeaders({ Authorization: 'Bearer default-token' });
+ * await fetchEvents({publicKey}, archiveEndpoint, { headers: { Authorization: 'Bearer override-token' } });
+ * ```
+ * @param headers Arbitrary sized headers to be used for all Mina Archive node GraphQL requests.
+ */
+function setArchiveDefaultHeaders(headers: HeadersInit) {
+  archiveDefaultHeaders = headers;
+}
+
 function setGraphqlEndpoints([
   graphqlEndpoint,
   ...fallbackEndpoints
@@ -173,13 +225,13 @@ function setLightnetAccountManagerEndpoint(endpoint: string) {
  * @param accountInfo.publicKey The specified publicKey to get account information on
  * @param accountInfo.tokenId The specified tokenId to get account information on
  * @param graphqlEndpoint The graphql endpoint to fetch from
- * @param config An object that exposes an additional timeout option
+ * @param config An object that exposes an additional timeout and header options
  * @returns zkapp information on the specified account or an error is thrown
  */
 async function fetchAccount(
   accountInfo: { publicKey: string | PublicKey; tokenId?: string | Field },
   graphqlEndpoint = networkConfig.minaEndpoint,
-  { timeout = defaultTimeout } = {}
+  { timeout = defaultTimeout, headers }: FetchConfig = {}
 ): Promise<
   | { account: Types.Account; error: undefined }
   | { account: undefined; error: FetchError }
@@ -198,6 +250,7 @@ async function fetchAccount(
     graphqlEndpoint,
     {
       timeout,
+      headers,
     }
   );
 }
@@ -236,7 +289,7 @@ async function fetchAccountInternal(
   };
 }
 
-type FetchConfig = { timeout?: number };
+type FetchConfig = { timeout?: number; headers?: HeadersInit };
 type FetchResponse<TDataResponse = any> = { data: TDataResponse; errors?: any };
 type FetchError = {
   statusCode: number;
@@ -458,11 +511,15 @@ function accountCacheKey(
 /**
  * Fetches the last block on the Mina network.
  */
-async function fetchLastBlock(graphqlEndpoint = networkConfig.minaEndpoint) {
+async function fetchLastBlock(
+  graphqlEndpoint = networkConfig.minaEndpoint,
+  headers?: HeadersInit
+) {
   let [resp, error] = await makeGraphqlRequest<LastBlockQueryResponse>(
     lastBlockQuery,
     graphqlEndpoint,
-    networkConfig.minaFallbackEndpoints
+    networkConfig.minaFallbackEndpoints,
+    { headers }
   );
   if (error) throw Error(error.statusText);
   let lastBlock = resp?.data?.bestChain?.[0];
@@ -478,11 +535,21 @@ async function fetchLastBlock(graphqlEndpoint = networkConfig.minaEndpoint) {
   return network;
 }
 
-async function fetchCurrentSlot(graphqlEndpoint = networkConfig.minaEndpoint) {
+/**
+ * Fetches the current slot number of the Mina network.
+ * @param graphqlEndpoint GraphQL endpoint to fetch from
+ * @param headers optional headers to pass to the fetch request
+ * @returns The current slot number
+ */
+async function fetchCurrentSlot(
+  graphqlEndpoint = networkConfig.minaEndpoint,
+  headers?: HeadersInit
+) {
   let [resp, error] = await makeGraphqlRequest<CurrentSlotResponse>(
     currentSlotQuery,
     graphqlEndpoint,
-    networkConfig.minaFallbackEndpoints
+    networkConfig.minaFallbackEndpoints,
+    { headers }
   );
   if (error) throw Error(`Error making GraphQL request: ${error.statusText}`);
   let bestChain = resp?.data?.bestChain;
@@ -597,12 +664,14 @@ function parseEpochData({
  */
 async function fetchTransactionStatus(
   txId: string,
-  graphqlEndpoint = networkConfig.minaEndpoint
+  graphqlEndpoint = networkConfig.minaEndpoint,
+  headers?: HeadersInit
 ): Promise<TransactionStatus> {
   let [resp, error] = await makeGraphqlRequest<TransactionStatusQueryResponse>(
     transactionStatusQuery(txId),
     graphqlEndpoint,
-    networkConfig.minaFallbackEndpoints
+    networkConfig.minaFallbackEndpoints,
+    { headers }
   );
   if (error) throw Error(error.statusText);
   let txStatus = resp?.data?.transactionStatus;
@@ -618,14 +687,15 @@ async function fetchTransactionStatus(
 function sendZkapp(
   json: string,
   graphqlEndpoint = networkConfig.minaEndpoint,
-  { timeout = defaultTimeout } = {}
+  { timeout = defaultTimeout, headers }: FetchConfig = {}
 ) {
   return makeGraphqlRequest<SendZkAppResponse>(
     sendZkappQuery(json),
     graphqlEndpoint,
     networkConfig.minaFallbackEndpoints,
     {
       timeout,
+      headers,
     }
   );
 }
@@ -637,6 +707,7 @@ function sendZkapp(
  * @param [accountInfo.tokenId] - The optional token ID for the account.
  * @param [graphqlEndpoint=networkConfig.archiveEndpoint] - The GraphQL endpoint to query. Defaults to the Archive Node GraphQL API.
  * @param [filterOptions={}] - The optional filter options object.
+ * @param headers - Optional headers to pass to the fetch request
  * @returns A promise that resolves to an array of objects containing event data, block information and transaction information for the account.
  * @throws If the GraphQL request fails or the response is invalid.
  * @example
@@ -649,7 +720,8 @@ function sendZkapp(
 async function fetchEvents(
   accountInfo: { publicKey: string; tokenId?: string },
   graphqlEndpoint = networkConfig.archiveEndpoint,
-  filterOptions: EventActionFilterOptions = {}
+  filterOptions: EventActionFilterOptions = {},
+  headers?: HeadersInit
 ) {
   if (!graphqlEndpoint)
     throw Error(
@@ -663,7 +735,8 @@ async function fetchEvents(
       filterOptions
     ),
     graphqlEndpoint,
-    networkConfig.archiveFallbackEndpoints
+    networkConfig.archiveFallbackEndpoints,
+    { headers }
   );
   if (error) throw Error(error.statusText);
   let fetchedEvents = response?.data.events;
@@ -697,6 +770,7 @@ async function fetchEvents(
  *
  * @param accountInfo - An {@link ActionsQueryInputs} containing the public key, and optional query parameters for the actions query
  * @param graphqlEndpoint - The GraphQL endpoint to fetch from. Defaults to the configured Mina endpoint.
+ * @param headers - Optional headers to pass to the fetch request
  *
  * @returns A promise that resolves to an object containing the final actions hash for the account, and a list of actions
  * @throws Will throw an error if the GraphQL endpoint is invalid or if the fetch request fails.
@@ -710,7 +784,8 @@ async function fetchEvents(
  */
 async function fetchActions(
   accountInfo: ActionsQueryInputs,
-  graphqlEndpoint = networkConfig.archiveEndpoint
+  graphqlEndpoint = networkConfig.archiveEndpoint,
+  headers?: HeadersInit
 ): Promise<
   | {
       actions: string[][];
@@ -731,7 +806,8 @@ async function fetchActions(
   let [response, error] = await makeGraphqlRequest<ActionQueryResponse>(
     getActionsQuery(publicKey, actionStates, tokenId),
     graphqlEndpoint,
-    networkConfig.archiveFallbackEndpoints
+    networkConfig.archiveFallbackEndpoints,
+    { headers }
   );
   // As of 2025-01-07, minascan is running a version of the node which supports `sequenceNumber` and `zkappAccountUpdateIds` fields
   // We could consider removing this fallback since no other nodes are widely used
@@ -746,7 +822,8 @@ async function fetchActions(
         /* _excludeTransactionInfo= */ true
       ),
       graphqlEndpoint,
-      networkConfig.archiveFallbackEndpoints
+      networkConfig.archiveFallbackEndpoints,
+      { headers } // Should we pass headers to other nodes?
     );
     if (error)
       throw Error(
@@ -867,12 +944,14 @@ export function createActionsList(
  * Fetches genesis constants.
  */
 async function fetchGenesisConstants(
-  graphqlEndpoint = networkConfig.minaEndpoint
+  graphqlEndpoint = networkConfig.minaEndpoint,
+  headers?: HeadersInit
 ): Promise<GenesisConstants> {
   let [resp, error] = await makeGraphqlRequest<GenesisConstantsResponse>(
     genesisConstantsQuery,
     graphqlEndpoint,
-    networkConfig.minaFallbackEndpoints
+    networkConfig.minaFallbackEndpoints,
+    { headers }
   );
   if (error) throw Error(error.statusText);
   const genesisConstants = resp?.data?.genesisConstants;
@@ -1029,7 +1108,7 @@ async function makeGraphqlRequest<TDataResponse = any>(
   query: string,
   graphqlEndpoint = networkConfig.minaEndpoint,
   fallbackEndpoints: string[],
-  { timeout = defaultTimeout } = {} as FetchConfig
+  { timeout = defaultTimeout, headers } = {} as FetchConfig
 ) {
   if (graphqlEndpoint === 'none')
     throw Error(
@@ -1049,7 +1128,11 @@ async function makeGraphqlRequest<TDataResponse = any>(
     try {
       let response = await fetch(url, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: {
+          'Content-Type': 'application/json',
+          ...(isArchiveUrl(url) ? archiveDefaultHeaders : minaDefaultHeaders),
+          ...headers,
+        },
         body,
         signal: controller.signal,
       });