Skip to content

Latest commit

 

History

History
122 lines (76 loc) · 5.47 KB

coral.md

File metadata and controls

122 lines (76 loc) · 5.47 KB

nxapi/coral

Using this module requires sending an authentication token (as a JSON Web Token, containing account identifiers itself) to third-party APIs. If you use this module in your own project, you must read https://github.com/frozenpandaman/splatnet2statink/wiki/api-docs and https://github.com/JoneWang/imink/wiki/imink-API-Documentation if you intend to share anything you create, and explain this to your users and provide a link to the Coral client authentication section of nxapi's README. Do not contact any service without the user's informed consent.

CoralApi

This is exported as default.

Coral 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/coral.ts, src/common/auth/coral.ts and src/cli/nso for examples of using this API. If you need any help using this API ask in #coral on Discord.

You should review HTTP captures of the Nintendo Switch Online app and attempt to match the behaviour of Nintendo's official app. For example, when opening the app it will fetch announcements, friends, web services and the active event; your project should match this.

CoralApi.createWithSessionToken

Authenticate to the Coral API using a Nintendo Account session token.

This function should not be called often. If your project will create a new CoralApi object again for the same user before the Coral authentication token expires (usually after two hours), you must store the data object this returns and use CoralApi.createWithSavedToken.

import CoralApi, { CoralAuthData } from 'nxapi/coral';

const na_session_token: string;

const {nso, data} = await CoralApi.createWithSessionToken(na_session_token);
// nso instanceof CoralApi
// data is a plain object of type CoralAuthData
// data should be saved and reused

CoralApi.createWithSavedToken

Create a CoralApi instance using cached data from CoralApi.createWithSessionToken or CoralApi.loginWithSessionToken.

import CoralApi, { CoralAuthData } from 'nxapi/coral';

const auth_data: CoralAuthData;

const coral = CoralApi.createWithSavedToken(auth_data);
// coral instanceof CoralApi

CoralApi.renewToken

Renew the Coral authentication token. This should be called if any API requests throw a token expired error. This updates the token of the CoralApi object and returns a partial CoralAuthData object, that should replace properties of the object passed to CoralApi.createWithSavedToken.

This function should not be called often. You must store the object this returns (replacing properties of the previous CoralAuthData object).

import CoralApi, { CoralAuthData, PartialCoralAuthData } from 'nxapi/coral';

const coral: CoralApi;
const auth_data: CoralAuthData;
const na_session_token: string;

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);
// new_auth_data is a plain object of type CoralAuthData
// 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.

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.

The API proxy will cache data and will request certain data together to match Nintendo's app, however you should still try to only make requests that would match the behaviour of Nintendo's app as with CoralApi.

new ZncProxyApi

Create a ZncProxyApi instance with a Nintendo Account session token.

Because the API proxy server handles Nintendo Account authentication, you do not need to store any data to reuse later, and should call the constructor directly instead of using a helper function.

import { ZncProxyApi } from 'nxapi/coral';

const znc_proxy_url: string;
const na_session_token: string;

const coral = new ZncProxyApi(znc_proxy_url, na_session_token);

API types

nxapi/coral exports all API types from src/api/coral-types.ts.

Coral client authentication

nxapi/coral exports it's API library and types for various APIs used for generating f tokens used to authenticate to the Coral API. These functions should generally not be required as they are used by nxapi internally.