Use cached web service token to renew SplatNet 3 tokens and fix retrying getting web service tokens after renewing coral token

docs/lib/coral.md

@@ -54,8 +54,9 @@ import CoralApi, { CoralAuthData, PartialCoralAuthData } from 'nxapi/coral';
 
 const coral: CoralApi;
 const auth_data: CoralAuthData;
+const na_session_token: string;
 
-const data = await coral.renewToken(auth_data);
+const data = await coral.renewToken(na_session_token, auth_data.user);
 // data is a plain object of type PartialCoralAuthData
 
 const new_auth_data = Object.assign({}, auth_data, data);
@@ -63,6 +64,34 @@ const new_auth_data = Object.assign({}, auth_data, data);
 // new_auth_data should be saved and reused
 ```
 
+#### `CoralApi.onTokenExpired`
+
+Function called when a `9404 Token expired` response is received from the API.
+
+This function should either call `CoralApi.getToken` to renew the token, then return the `PartialCoralAuthData` object, or call `CoralApi.renewToken`.
+
+```ts
+import CoralApi, { CoralAuthData } from 'nxapi/coral';
+import { Response } from 'node-fetch';
+
+const coral = CoralApi.createWithSavedToken(...);
+let auth_data: CoralAuthData;
+const na_session_token: string;
+
+coral.onTokenExpired = async (response: Response) => {
+    const data = await coral.getToken(na_session_token, auth_data.user);
+    // data is a plain object of type PartialCoralAuthData
+
+    const new_auth_data = Object.assign({}, auth_data, data);
+    // new_auth_data is a plain object of type CoralAuthData
+    // new_auth_data should be saved and reused
+
+    auth_data = new_auth_data;
+
+    return data;
+};
+```
+
 ### `ZncProxyApi`
 
 nxapi API proxy server client. Instances of this class are generally compatible with `CoralApi`; nxapi's command line interface and Electron apps internally use either depending on whether the API proxy is enabled.

docs/lib/splatnet3.md

@@ -56,6 +56,68 @@ const splatnet = SplatNet3Api.createWithCliTokenData(data);
 // splatnet instanceof SplatNet3Api
 ```
 
+#### `SplatNet3Api.onTokenExpired`
+
+Function called when a `401 Unauthorized` response is received from the API, meaning the token has expired.
+
+This function should either call `SplatNet3Api.loginWithWebServiceToken` or `SplatNet3Api.loginWithCoral` to renew the token, then return the `SplatNet3AuthData` object, or call `SplatNet3Api.renewTokenWithWebServiceToken` or `SplatNet3Api.renewTokenWithCoral`. An existing web service token should be used to avoid calling the imink/flapg API, and then fall back to issuing a new token.
+
+```ts
+import { ErrorResponse } from 'nxapi';
+import CoralApi, { CoralAuthData } from 'nxapi/coral';
+import SplatNet3Api, { SplatNet3AuthData } from 'nxapi/splatnet3';
+import { Response } from 'node-fetch';
+
+let splatnet3_auth_data: SplatNet3AuthData;
+const splatnet = SplatNet3Api.createWithSavedToken(splatnet3_auth_data);
+
+splatnet.onTokenExpired = async (response: Response) => {
+    try {
+        // This should be cached - using stale data is fine, as only the user data is used
+        const coral_auth_data: CoralAuthData;
+
+        const data = await SplatNet3Api.loginWithWebServiceToken(splatnet3_auth_data.webserviceToken, coral_auth_data.user);
+        // data is a plain object of type SplatNet3AuthData
+        // data should be saved and reused
+
+        splatnet3_auth_data = data;
+
+        return data;
+    } catch (err) {
+        // `401 Unauthorized` from `/api/bullet_tokens` means the web service token has expired (or is invalid)
+        if (err instanceof ErrorResponse && err.response.status === 401) {
+            const coral: CoralApi;
+            const coral_auth_data: CoralAuthData;
+
+            const data = await SplatNet3Api.loginWithCoral(coral, coral_auth_data.user);
+            // data is a plain object of type SplatNet3AuthData
+            // data should be saved and reused
+
+            splatnet3_auth_data = data;
+
+            return data;
+        }
+
+        throw err;
+    }
+};
+```
+
+#### `SplatNet3Api.onTokenShouldRenew`
+
+Function called when the `x-bullettoken-remaining` header received from the API is less than 300, meaning the token will expire in 5 minutes and should be renewed in the background.
+
+```ts
+import SplatNet3Api, { SplatNet3AuthData } from 'nxapi/splatnet3';
+import { Response } from 'node-fetch';
+
+const splatnet = SplatNet3Api.createWithSavedToken(...);
+
+splatnet.onTokenShouldRenew = async (remaining: number, response: Response) => {
+    // See SplatNet3Api.onTokenExpired for an example
+};
+```
+
 ### API types
 
 `nxapi/splatnet3` exports all API types from [src/api/splatnet3-types.ts](../../src/api/splatnet3-types.ts).