feat: add fetch middleware for api keys and request init

chore: remove file

wip

wip

docs: optimize ts docs

wip

Author: janniks

package-lock.json

@@ -67,14 +67,14 @@
     "rollup-plugin-node-globals": "^1.4.0",
     "rollup-plugin-terser": "^7.0.2",
     "stream-http": "^3.2.0",
-    "typedoc": "^0.22.13",
+    "typedoc": "^0.22.15",
     "typescript": "^4.2.4",
     "vite-compatible-readable-stream": "^3.6.0"
   },
   "scripts": {
     "bootstrap": "lerna bootstrap",
     "build": "lerna run build",
-    "build:docs": "rimraf docs && typedoc --tsconfig tsconfig.typedoc.json packages/**/src/index.ts --release-version $(node -p \"require('./lerna.json').version\")",
+    "build:docs": "rimraf docs && RELEASE_VERSION=$(node -p \"require('./lerna.json').version\") && typedoc --tsconfig tsconfig.typedoc.json packages/**/src/index.ts --release-version $RELEASE_VERSION",
     "clean": "lerna clean",
     "lerna": "lerna",
     "lint": "npm run lint:eslint && npm run lint:prettier",

package.json

@@ -1,5 +1,4 @@
 import { resolveZoneFileToProfile } from '@stacks/profile';
-import { fetchPrivate } from '@stacks/common';
 import { StacksMainnet, StacksNetwork, StacksNetworkName } from '@stacks/network';
 
 export interface ProfileLookupOptions {
@@ -31,13 +30,13 @@ export function lookupProfile(lookupOptions: ProfileLookupOptions): Promise<Reco
   let lookupPromise;
   if (options.zoneFileLookupURL) {
     const url = `${options.zoneFileLookupURL.replace(/\/$/, '')}/${options.username}`;
-    lookupPromise = fetchPrivate(url).then(response => response.json());
+    lookupPromise = network.fetchFn(url).then(response => response.json());
   } else {
     lookupPromise = network.getNameInfo(options.username);
   }
   return lookupPromise.then((responseJSON: any) => {
     if (responseJSON.hasOwnProperty('zonefile') && responseJSON.hasOwnProperty('address')) {
-      return resolveZoneFileToProfile(responseJSON.zonefile, responseJSON.address);
+      return resolveZoneFileToProfile(responseJSON.zonefile, responseJSON.address, network.fetchFn);
     } else {
       throw new Error(
         'Invalid zonefile lookup response: did not contain `address`' + ' or `zonefile` field'

packages/auth/src/profile.ts

@@ -1,6 +1,6 @@
 import * as queryString from 'query-string';
 import { decodeToken } from 'jsontokens';
-import { BLOCKSTACK_HANDLER, getGlobalObject, fetchPrivate } from '@stacks/common';
+import { BLOCKSTACK_HANDLER, getGlobalObject, createFetchFn, FetchFn } from '@stacks/common';
 
 /**
  * Retrieves the authentication request from the query string
@@ -36,7 +36,10 @@ export function getAuthRequestFromURL() {
  * @private
  * @ignore
  */
-export async function fetchAppManifest(authRequest: string): Promise<any> {
+export async function fetchAppManifest(
+  authRequest: string,
+  fetchFn: FetchFn = createFetchFn()
+): Promise<any> {
   if (!authRequest) {
     throw new Error('Invalid auth request');
   }
@@ -47,7 +50,7 @@ export async function fetchAppManifest(authRequest: string): Promise<any> {
   const manifestURI = payload.manifest_uri as string;
   try {
     // Logger.debug(`Fetching manifest from ${manifestURI}`)
-    const response = await fetchPrivate(manifestURI);
+    const response = await fetchFn(manifestURI);
     const responseText = await response.text();
     const responseJSON = JSON.parse(responseText);
     return { ...responseJSON, manifestURI };

packages/auth/src/provider.ts

@@ -1,5 +1,5 @@
 // @ts-ignore
-import { Buffer } from '@stacks/common';
+import { Buffer, FetchFn, createFetchFn } from '@stacks/common';
 import { AppConfig } from './appConfig';
 import { SessionOptions } from './sessionData';
 import { InstanceDataStore, LocalStorageStore, SessionDataStore } from './sessionStore';
@@ -15,7 +15,6 @@ import {
 import { getAddressFromDID } from './dids';
 import {
   BLOCKSTACK_DEFAULT_GAIA_HUB_URL,
-  fetchPrivate,
   getGlobalObject,
   InvalidStateError,
   isLaterVersion,
@@ -214,7 +213,8 @@ export class UserSession {
    * if handling the sign in request fails or there was no pending sign in request.
    */
   async handlePendingSignIn(
-    authResponseToken: string = this.getAuthResponseToken()
+    authResponseToken: string = this.getAuthResponseToken(),
+    fetchFn: FetchFn = createFetchFn()
   ): Promise<UserData> {
     const sessionData = this.store.getSessionData();
 
@@ -312,7 +312,7 @@ export class UserSession {
     };
     const profileURL = tokenPayload.profile_url as string;
     if (!userData.profile && profileURL) {
-      const response = await fetchPrivate(profileURL);
+      const response = await fetchFn(profileURL);
       if (!response.ok) {
         // return blank profile if we fail to fetch
         userData.profile = Object.assign({}, DEFAULT_PROFILE);

packages/auth/src/userSession.ts

@@ -1,11 +1,11 @@
 import blockstack from 'blockstack';
 import * as bitcoin from 'bitcoinjs-lib';
 import BN from 'bn.js';
-import fetch from 'node-fetch';
 
 import { CLI_CONFIG_TYPE } from './argparse';
 
 import { BlockstackNetwork } from 'blockstack/lib/network';
+import { FetchFn, createFetchFn } from '@stacks/common';
 
 export interface CLI_NETWORK_OPTS {
   consensusHash: string | null;
@@ -187,15 +187,16 @@ export class CLINetworkAdapter {
   getNamespaceBurnAddress(
     namespace: string,
     useCLI: boolean = true,
-    receiveFeesPeriod: number = -1
+    receiveFeesPeriod: number = -1,
+    fetchFn: FetchFn = createFetchFn()
   ): Promise<string> {
     // override with CLI option
     if (this.namespaceBurnAddress && useCLI) {
       return new Promise((resolve: any) => resolve(this.namespaceBurnAddress));
     }
 
     return Promise.all([
-      fetch(`${this.legacyNetwork.blockstackAPIUrl}/v1/namespaces/${namespace}`),
+      fetchFn(`${this.legacyNetwork.blockstackAPIUrl}/v1/namespaces/${namespace}`),
       this.legacyNetwork.getBlockHeight(),
     ])
       .then(([resp, blockHeight]: [any, number]) => {
@@ -245,10 +246,10 @@ export class CLINetworkAdapter {
     });
   }
 
-  getBlockchainNameRecord(name: string): Promise<any> {
+  getBlockchainNameRecord(name: string, fetchFn: FetchFn = createFetchFn()): Promise<any> {
     // TODO: send to blockstack.js
     const url = `${this.legacyNetwork.blockstackAPIUrl}/v1/blockchains/bitcoin/names/${name}`;
-    return fetch(url)
+    return fetchFn(url)
       .then(resp => {
         if (resp.status !== 200) {
           throw new Error(`Bad response status: ${resp.status}`);
@@ -268,10 +269,14 @@ export class CLINetworkAdapter {
       });
   }
 
-  getNameHistory(name: string, page: number): Promise<Record<string, any[]>> {
+  getNameHistory(
+    name: string,
+    page: number,
+    fetchFn: FetchFn = createFetchFn()
+  ): Promise<Record<string, any[]>> {
     // TODO: send to blockstack.js
     const url = `${this.legacyNetwork.blockstackAPIUrl}/v1/names/${name}/history?page=${page}`;
-    return fetch(url)
+    return fetchFn(url)
       .then(resp => {
         if (resp.status !== 200) {
           throw new Error(`Bad response status: ${resp.status}`);

packages/cli/src/network.ts

@@ -7,32 +7,168 @@ const defaultFetchOpts: RequestInit = {
   referrerPolicy: 'origin', // Use origin value for referrer policy
   // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
 };
-/*
+
+/**
  * Get fetch options
- * @return fetchOptions
+ * @category Network
  */
 export const getFetchOptions = () => {
   return defaultFetchOpts;
 };
-/*
- * Set fetch options
- * Users can change default referrer as well as other options when fetch is used internally by stacks.js libraries or from server side
+
+/**
+ * Sets global fetch options for stacks.js network calls.
+ *
  * @example
- *  Reference: https://developer.mozilla.org/en-US/docs/Web/API/Request/Request
- *  setFetchOptions({  referrer: 'no-referrer', referrerPolicy: 'no-referrer', ... other options as per above reference  });
- * Now all the subsequent fetchPrivate will use above options
- * @return fetchOptions
+ * Users can change the default referrer as well as other options when fetch is used internally by stacks.js:
+ * ```
+ * setFetchOptions({ referrer: 'no-referrer', referrerPolicy: 'no-referrer', ...otherRequestOptions });
+ * ```
+ * After calling {@link setFetchOptions} all subsequent network calls will use the specified options above.
+ *
+ * @see MDN Request: https://developer.mozilla.org/en-US/docs/Web/API/Request/Request
+ * @returns global fetch options after merging with previous options (or defaults)
+ * @category Network
+ * @related {@link getFetchOptions}
  */
-export const setFetchOptions = (ops: RequestInit) => {
+export const setFetchOptions = (ops: RequestInit): RequestInit => {
   return Object.assign(defaultFetchOpts, ops);
 };
 
-/** @ignore */
-export async function fetchPrivate(input: RequestInfo, init?: RequestInit): Promise<Response> {
+/** @internal */
+export async function fetchWrapper(input: RequestInfo, init?: RequestInit): Promise<Response> {
   const fetchOpts = {};
   // Use the provided options in request options along with default or user provided values
   Object.assign(fetchOpts, init, defaultFetchOpts);
 
   const fetchResult = await fetch(input, fetchOpts);
   return fetchResult;
 }
+
+export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+
+export interface RequestContext {
+  fetch: FetchFn;
+  url: string;
+  init: RequestInit;
+}
+
+export interface ResponseContext {
+  fetch: FetchFn;
+  url: string;
+  init: RequestInit;
+  response: Response;
+}
+
+export interface FetchParams {
+  url: string;
+  init: RequestInit;
+}
+
+export interface FetchMiddleware {
+  pre?: (context: RequestContext) => PromiseLike<FetchParams | void> | FetchParams | void;
+  post?: (context: ResponseContext) => Promise<Response | void> | Response | void;
+}
+export interface ApiKeyMiddlewareOpts {
+  /** The middleware / API key header will only be added to requests matching this host. */
+  host?: RegExp | string;
+  /** The http header name used for specifying the API key value. */
+  httpHeader?: string;
+  /** The API key string to specify as an http header value. */
+  apiKey: string;
+}
+
+/** @internal */
+export function hostMatches(host: string, pattern: string | RegExp) {
+  if (typeof pattern === 'string') return pattern === host;
+  return (pattern as RegExp).exec(host);
+}
+
+/**
+ * Creates a new middleware from an API key.
+ * @example
+ * ```
+ * const apiMiddleware = createApiKeyMiddleware("example_e8e044a3_41d8b0fe_3dd3988ef302");
+ * const fetchFn = createFetchFn(apiMiddleware);
+ * const network = new StacksMainnet({ fetchFn });
+ * ```
+ * @category Network
+ * @related {@link createFetchFn}, {@link StacksNetwork}
+ */
+export function createApiKeyMiddleware({
+  apiKey,
+  host = /(.*)api(.*)\.stacks\.co$/i,
+  httpHeader = 'x-api-key',
+}: ApiKeyMiddlewareOpts): FetchMiddleware {
+  return {
+    pre: context => {
+      const reqUrl = new URL(context.url);
+      if (!hostMatches(reqUrl.host, host)) return; // Skip middleware if host does not match pattern
+
+      const headers = new Headers(context.init.headers);
+      headers.set(httpHeader, apiKey);
+      context.init.headers = headers;
+    },
+  };
+}
+
+function argsForCreateFetchFn(args: any[]): { middlewares: FetchMiddleware[]; fetchLib: FetchFn } {
+  let fetchLib: FetchFn = fetchWrapper;
+  let middlewares: FetchMiddleware[] = [];
+  if (args.length > 0 && typeof args[0] === 'function') {
+    fetchLib = args.shift();
+  }
+  if (args.length > 0) {
+    middlewares = args;
+  }
+  return { middlewares, fetchLib };
+}
+
+/**
+ * Creates a new network fetching function, which combines an optional fetch-compatible library with optional middlware.
+ * @example
+ * ```
+ * const customFetch = createFetchFn(someMiddleware)
+ * const customFetch = createFetchFn(fetch, someMiddleware)
+ * const customFetch = createFetchFn(fetch, middlewareA, middlewareB)
+ * ```
+ * @category Network
+ */
+export function createFetchFn(fetchLib: FetchFn, ...middleware: FetchMiddleware[]): FetchFn;
+export function createFetchFn(...middleware: FetchMiddleware[]): FetchFn;
+export function createFetchFn(...args: any[]): FetchFn {
+  const { middlewares: middlewareArgs, fetchLib } = argsForCreateFetchFn(args);
+  const middlewares = [...middlewareArgs]; // shallow copy
+
+  const fetchFn = async (url: string, init?: RequestInit | undefined): Promise<Response> => {
+    let fetchParams = { url, init: init ?? {} };
+
+    for (const middleware of middlewares) {
+      if (typeof middleware.pre !== 'function') continue;
+      const result = await Promise.resolve(
+        middleware.pre({
+          fetch: fetchLib,
+          ...fetchParams,
+        })
+      );
+      fetchParams = result ?? fetchParams;
+    }
+
+    let response = await fetchLib(fetchParams.url, fetchParams.init);
+
+    for (const middleware of middlewares) {
+      if (typeof middleware.post !== 'function') continue;
+      const result = await Promise.resolve(
+        middleware.post({
+          fetch: fetchLib,
+          url: fetchParams.url,
+          init: fetchParams.init,
+          response: response.clone(),
+        })
+      );
+      response = result ?? response;
+    }
+    return response;
+  };
+  return fetchFn;
+}

packages/common/src/fetchUtil.ts

@@ -1,14 +1,17 @@
-import { fetchPrivate, getFetchOptions, setFetchOptions } from '../src'
-import fetchMock from "jest-fetch-mock";
+import { fetchWrapper, getFetchOptions, setFetchOptions } from '../src';
+import fetchMock from 'jest-fetch-mock';
 
 test('Verify fetch private options', async () => {
-  const defaultOptioins  = getFetchOptions();
+  const defaultOptioins = getFetchOptions();
 
   expect(defaultOptioins).toEqual({ referrerPolicy: 'origin' });
 
   // Override default options when fetchPrivate is called internally by other stacks.js libraries like transactions or from server side
   // This is for developers as they cannot directly pass options directly in fetchPrivate
-  const modifiedOptions: RequestInit= { referrer: 'http://test.com', referrerPolicy: 'same-origin' };
+  const modifiedOptions: RequestInit = {
+    referrer: 'http://test.com',
+    referrerPolicy: 'same-origin',
+  };
 
   // Developers can set fetch options globally one time specifically when fetchPrivate is used internally by stacks.js libraries
   setFetchOptions(modifiedOptions);
@@ -18,11 +21,10 @@ test('Verify fetch private options', async () => {
   // Browser will replace about:client with actual url but it will not be visible in test case
   fetchMock.mockOnce(`{ status: 'success'}`, { headers: modifiedOptions as any });
 
-  const result = await fetchPrivate('https://example.com');
+  const result = await fetchWrapper('https://example.com');
 
   // Verify the request options
   expect(result.status).toEqual(200);
   expect(result.headers.get('referrer')).toEqual(modifiedOptions.referrer);
   expect(result.headers.get('referrerPolicy')).toEqual(modifiedOptions.referrerPolicy);
-})
-
+});