Skip to content

Latest commit

 

History

History
196 lines (132 loc) · 7.43 KB

index.md

File metadata and controls

196 lines (132 loc) · 7.43 KB

Usage as a JavaScript library

nxapi exports it's API library and types. nxapi is split into several modules that can be imported separately.

You must set a user agent string using the addUserAgent function when using anything that contacts non-Nintendo APIs, such as the imink API.

Please 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.

By default nxapi will fetch certain settings, mostly version numbers to report to Nintendo, from my server. This can be disabled using environment variables.

nxapi uses native ECMAScript modules. nxapi also uses features like top-level await, so it cannot be converted to CommonJS using Rollup or similar. If you need to use nxapi from CommonJS modules or other module systems, use a dynamic import.

For TypeScript projects, this means you need to set moduleResolution to node16 (or nodenext) (https://www.typescriptlang.org/tsconfig#moduleResolution). I recommend setting the following options:

{
    "compilerOptions": {
        "strict": true,
        "target": "es2020",
        "module": "node16",
        "moduleResolution": "node16",
        "skipLibCheck": true
    }
}

If you need any help using nxapi as a library join the Discord server or create a discussion.

Example authenticating to the Nintendo Switch Online app:

This is a simplified example of authenticating to the Coral API and using cached tokens. More logic is required to ensure you are using these APIs properly, and to renew expired tokens - see src/common/auth/coral.ts for the authentication functions used in nxapi's CLI and Electron app.

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

addUserAgent('your-script/1.0.0 (+https://github.com/...)');

declare function getCachedCoralToken(): [CoralAuthData, Date];
declare function setCachedCoralToken(auth_data: CoralAuthData, expires_at: Date): void;
declare function getNintendoAccountSessionToken(): string;

let coral;

try {
    const [auth_data, expires_at] = getCachedCoralToken();
    if (expires_at.getTime() > Date.now()) throw new Error('Token expired');

    coral = CoralApi.createWithSavedToken(auth_data);
} catch (err) {
    const na_session_token = getNintendoAccountSessionToken();
    const {nso, data} = await CoralApi.createWithSessionToken(na_session_token);
    setCachedCoralToken(data, Date.now() + (data.credential.expiresIn * 1000));
    coral = nso;
}

const friends = await coral.getFriendList();

Example getting SplatNet 2 records:

This example does not include authenticating to SplatNet 2. To benefit from the caching in the nxapi command, the nxapi splatnet2 token --json command can be used in most scripts. For example:

SPLATNET_TOKEN=`nxapi splatnet2 token --json` node your-script.js

your-script.js can then read the iksm_session, unique player ID and region like this:

import SplatNet2Api from 'nxapi/splatnet2';

const data = JSON.parse(process.env.SPLATNET_TOKEN);
const splatnet2 = SplatNet2Api.createWithCliTokenData(data);
import SplatNet2Api from 'nxapi/splatnet2';

const iksm_session = '...';
const unique_id = '...';
const splatnet2 = SplatNet2Api.createWithIksmSession(iksm_session, unique_id);

const records = await splatnet2.getRecords();

Install

nxapi should be installed as a project dependency rather than a globally installed package. TypeScript definitions are included and do not need to be installed separately.

# From registry.npmjs.com
npm install nxapi

# From gitlab.fancy.org.uk
npm install --registry https://gitlab.fancy.org.uk/api/v4/packages/npm/ @samuel/nxapi

# From npm.pkg.github.com
npm install --registry https://npm.pkg.github.com @samuelthomas2774/nxapi

# From gitlab.com
npm install --registry https://gitlab.com/api/v4/packages/npm/ @samuelthomas2774/nxapi

nxapi

This module contains some generic utility functions and types.

getTitleIdFromEcUrl

This function takes a https://ec.nintendo.com/apps/... URL (provided by some Nintendo APIs) and returns the title ID in the URL. null is returned if the URL is not a valid Nintendo eShop URL containing a title ID.

import { getTitleIdFromEcUrl } from 'nxapi';

const title_id = getTitleIdFromEcUrl('https://ec.nintendo.com/apps/0100f8f0000a2000/GB?lang=en-GB');
// title_id === '0100f8f0000a2000'

If you are using Nintendo eShop links but do not know the user's Nintendo eShop region, you may use nxapi's Nintendo eShop region selection page.

https://fancy.org.uk/api/nxapi/title/0100f8f0000a2000/redirect

Please set an appropriate source query string parameter containing your project's name and version if you generate these links automatically.

https://fancy.org.uk/api/nxapi/title/0100f8f0000a2000/redirect?source=myproject-1.0.0

ErrorResponse

An instance of this class is thrown when an invalid or failure response is received. This class extends from Error.

Note that this is only used when the HTTP response is received correctly (including for non-2xx status codes). If a request fails due to a network error or another reason node-fetch will throw a different error.

import { ErrorResponse } from 'nxapi';

try {
    // ...
} catch (err) {
    if (err instanceof ErrorResponse) {
        // err.body is the response data as a string
        // err.data is the decoded JSON response data, or undefined if JSON decoding fails
        // err.response is the Response object from node-fetch
        // err.name, err.message and err.stack are inherited from Error
    }
}

addUserAgent

This function is used to set the user agent string to use for non-Nintendo API requests. Any project using nxapi (including as a dependency of another project) must call this function with an appropriate user agent string segment. See user agent strings.

addUserAgentFromPackageJson

This function is used to set the user agent string to use for non-Nintendo API requests using data from a package.json file. A string, URL object or the package.json data can be provided, as well as optional additional data. If a string/URL is provided this will return a Promise that will be resolved once the user agent is updated. See user agent strings.

version

nxapi's version number.

import { version } from 'nxapi';

// version === '1.3.0'

nxapi/coral

This module exports the Coral (Nintendo Switch Online app) API library and types.

See docs/lib/coral.md.

nxapi/moon

This module exports the Moon (Nintendo Switch Parental Controls app) API library and types.

See docs/lib/moon.md.

nxapi/splatnet2

This module exports the SplatNet 2 API library and types, as well as functions for calculating X Rank seasons, as this is done by the SplatNet 2 web app, not the API.

See docs/lib/splatnet2.md.

nxapi/nooklink

This module exports the NookLink API library and types.

See docs/lib/nooklink.md.

nxapi/splatnet3

This module exports the SplatNet 3 API library and types.

See docs/lib/splatnet3.md.