refactor(auth): Implement new initializer function API

[kitten]

Resolves #2815

Summary

This is a breaking change, which updates the authExchange API.

This PR eliminates the need for an authState (i.e. the authentication state) to be kept with the authExchange, and moves it into the responsibility of the user.
It also eliminates getAuth's "double duty" of being called, both, to initialize the authentication state, and to refresh the authentication state after an authentication error.

The authExchange now accepts an initializer function, which is an async function (or a function returning a promise). This function is user-defined and will receive a utilities object and must return an authentication configuration object.

This configuration object is unchanged but now contains refreshAuth rather than getAuth. Several arguments that its functions accept have been simplified.

authExchange(async utils => {
  let token = localStorage.getItem('token');
  let refreshToken = localStorage.getItem('refreshToken');

  return {
    addAuthToOperation(operation) {
      return utils.appendHeaders(operation, {
        Authorization: `Bearer ${token}`,
      });
    },
    willAuthError(_operation) {
      return false;
    },
    didAuthError(error, _operation) {
      return error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
    },
    async refreshAuth() {
      const result = await utils.mutate(REFRESH, { token });
      if (result.data?.refreshLogin) {
        token = result.data.refreshLogin.token;
        refreshToken = result.data.refreshLogin.refreshToken;
        localStorage.setItem('token', token);
        localStorage.setItem('refreshToken', refreshToken);
      }
    },
  };
});

As we can see, the initializer function itself now initializes the authentication state, and the state is just kept in local variables (which also now makes it easier to keep the state in some "third object" outside of the authExchange without any hacky code)

The function returns the configuration and can use utils.mutate to send GraphQL mutations for authentication purposes, and now also has utils.appendHeaders to add headers to operations!

Set of changes

• Simplify addAuthToOperation, willAuthError, and didAuthError arguments
• Remove authState and getAuth and replace with initializer
• Replace getAuth flow with refreshAuth call
• Update tests
• Add TSDocs to new exchange and APIs (generates a single d.ts output)
• Update documentation

NOTE: This isn't super final yet, but the goal here is to remove the API docs on the website and move those over to TSDocs. Hence, the website docs for the authExchange API are very lean now.

[kitten]

Here's a small guide on how to map things from the "old" API to this "new" API, as proposed.
Comments in ALL_CAPS are meant to mark common sections.

Legacy API

authExchange({
  addAuthToOperation({ authState, operation }) {
    if (!authState || !authState.token) {
      return operation; // DONT_ADD_AUTH
    }
    return operation; // ADD_AUTH
  },
  willAuthError({ authState, operation }) {
    return false; // WILL_AUTH_ERROR
  },
  didAuthError({ error }) {
    return false; // DID_AUTH_ERROR
  },
  async getAuth ({ authState, mutate }) {
    if (!authState) {
      // INITIALIZE_AUTH
      const token = localStorage.getItem('token');
      const refreshToken = localStorage.getItem('refreshToken');
      return token ? { token, refreshToken } : null;
    }

    // REFRESH_AUTH
    const result = await mutate(refreshMutation, { token: authState?.refreshToken });
    if (result.data?.refreshLogin) {
      localStorage.setItem('token', result.data.refreshLogin.token);
      localStorage.setItem('refreshToken', result.data.refreshLogin.refreshToken);
      return {
        token: result.data.refreshLogin.token,
        refreshToken: result.data.refreshLogin.refreshToken,
      };
    }

    // BAIL_REFRESH_AUTH
    localStorage.clear();
    logout();
    return null;
  },
});

Proposed API

authExchange(async (utils) => {
  // INITIALIZE_AUTH
  let token = localStorage.getItem('token');
  let refreshToken = localStorage.getItem('refreshToken');

  return {
    addAuthToOperation(operation) {
      if (!token) {
        return operation; // DONT_ADD_AUTH
      }
      // ADD_AUTH
      return utils.appendHeaders(operation, {
        Authorization: `Bearer ${token}`,
      });
    },
    willAuthError(_operation) {
      return false; // WILL_AUTH_ERROR
    },
    didAuthError(error, _operation) {
      return false; // DID_AUTH_ERROR
    },
    async refreshAuth() {
      // REFRESH_AUTH
      const result = await mutate(refreshMutation, { token: authState?.refreshToken });
      if (result.data?.refreshLogin) {
        token = result.data.refreshLogin.token;
        refreshToken = result.data.refreshLogin.refreshToken;
        localStorage.setItem('token', token);
        localStorage.setItem('refreshToken', refreshToken);
      } else {
        // BAIL_REFRESH_AUTH
        localStorage.clear();
        logout();
      }
    },
  };
});

[JoviDeCroock]

This is a huge improvement