mirror of
https://github.com/samuelthomas2774/nxapi.git
synced 2026-03-21 18:04:10 -05:00
124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
`nxapi/splatnet3`
|
|
---
|
|
|
|
### `SplatNet3Api`
|
|
|
|
> This is exported as `default`.
|
|
|
|
SplatNet 3 API client. An instance of this class should not be created directly; instead one of the `createWith*` static methods should be used.
|
|
|
|
Most of this API is intentionally undocumented. Read the source code at [src/api/splatnet3.ts](../../src/api/splatnet3.ts), [src/common/auth/splatnet3.ts](../../src/common/auth/splatnet3.ts) and [src/cli/splatnet3](../../src/cli/splatnet3) for examples of using this API. If you need any help using this API ask in [#splatnet3](https://discordapp.com/channels/998657768594608138/998664939537440820) on Discord.
|
|
|
|
You should review HTTP captures of SplatNet 3 in the Nintendo Switch Online app and attempt to match the behaviour of Nintendo's official app.
|
|
|
|
#### `SplatNet3Api.createWithCoral`
|
|
|
|
Authenticate to SplatNet 3 using a `CoralApi` instance.
|
|
|
|
> This function should not be called often. If your project will create a new SplatNet3Api object again for the same user before the SplatNet 3 authentication token expires (usually after 2 hours), you must store the `data` object this returns and use `SplatNet3Api.createWithSavedToken`.
|
|
|
|
```ts
|
|
import CoralApi, { CoralAuthData } from 'nxapi/coral';
|
|
import SplatNet3Api, { SplatNet3AuthData } from 'nxapi/splatnet3';
|
|
|
|
const coral: CoralApi;
|
|
const coral_auth_data: CoralAuthData;
|
|
|
|
const {splatnet, data} = await SplatNet3Api.createWithCoral(coral, coral_auth_data.user);
|
|
// splatnet instanceof SplatNet3Api
|
|
// data is a plain object of type SplatNet3AuthData
|
|
// data should be saved and reused
|
|
```
|
|
|
|
#### `SplatNet3Api.createWithSavedToken`
|
|
|
|
Create a SplatNet3Api instance using cached data from `SplatNet3Api.createWithCoral` or `SplatNet3Api.loginWithCoral`.
|
|
|
|
```ts
|
|
import SplatNet3Api, { SplatNet3AuthData } from 'nxapi/splatnet3';
|
|
|
|
const auth_data: SplatNet3AuthData;
|
|
|
|
const splatnet = SplatNet3Api.createWithSavedToken(auth_data);
|
|
// splatnet instanceof SplatNet3Api
|
|
```
|
|
|
|
#### `SplatNet3Api.createWithCliTokenData`
|
|
|
|
Create a SplatNet3Api instance using the output of the `nxapi splatnet3 token --json` command.
|
|
|
|
```ts
|
|
import SplatNet3Api, { SplatNet3CliTokenData } from 'nxapi/splatnet3';
|
|
|
|
const data: SplatNet3CliTokenData;
|
|
|
|
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
|
|
|
|
SplatNet 3 types are available from [splatnet3-types](https://gitlab.fancy.org.uk/samuel/splatnet3-types) ([GitHub](https://github.com/nintendoapis/splatnet3-types)).
|