nooklink.md

nxapi/nooklink

NookLink is more complex than other web services as it supports multiple users linked to the same network account:

• NooklinkApi is used at NSA-level, and is solely used to list available NookLink users and authenticate to NookLink at ACNH-level.
• NooklinkUserApi is used at ACNH-level, and is used to perform all other actions in the NookLink web app.

NooklinkApi

This is exported as default.

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

You should review HTTP captures of NookLink in the Nintendo Switch Online app and attempt to match the behaviour of Nintendo's official app.

NooklinkApi.createWithCoral

Authenticate to NookLink using a CoralApi instance.

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

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

const coral: CoralApi;
const coral_auth_data: CoralAuthData;

const {nooklink, data} = await NooklinkApi.createWithCoral(coral, coral_auth_data.user);
// nooklink instanceof NooklinkApi
// data is a plain object of type NooklinkAuthData
// data should be saved and reused

NooklinkApi.createWithSavedToken

Create a NooklinkApi instance using cached data from NooklinkApi.createWithCoral or NooklinkApi.loginWithCoral.

import NooklinkApi, { NooklinkAuthData } from 'nxapi/nooklink';

const auth_data: NooklinkAuthData;

const nooklink = NooklinkApi.createWithSavedToken(auth_data);
// nooklink instanceof NooklinkApi

NooklinkApi.getUsers

Retrieves a list of available NookLink-enabled users.

import NooklinkApi, { Users } from 'nxapi/nooklink';

const nooklink: Nooklink;

const users = await nooklink.getUsers();
// users is a plain object of type Users

NooklinkApi.createUserClient

Authenticate to NookLink and create a NooklinkUser instance.

import NooklinkApi, { NooklinkUserApi, NooklinkUserAuthData } from 'nxapi/nooklink';

const nooklink: Nooklink;
const user_id: string;

const {nooklinkuser, data} = await nooklink.createUserClient(user_id);
// nooklinkuser instanceof NooklinkUserApi
// data is a plain object of type NooklinkUserAuthData

NooklinkApi.onTokenExpired

Function called when a 401 Unauthorized response is received from the API.

This function should either call NooklinkApi.loginWithWebServiceToken or NooklinkApi.loginWithCoral to renew the token, then return the NooklinkAuthData object, or call NooklinkApi.renewTokenWithWebServiceToken or NooklinkApi.renewTokenWithCoral.

import NooklinkApi, { NooklinkAuthData, WebServiceError } from 'nxapi/nooklink';
import { Response } from 'node-fetch';

const nooklink = NooklinkApi.createWithSavedToken(...);
let auth_data: NooklinkAuthData;
const na_session_token: string;

nooklink.onTokenExpired = async (error: WebServiceError, response: Response) => {
    const data = await NooklinkApi.loginWithSessionToken(na_session_token);
    // data is a plain object of type NooklinkAuthData
    // data should be saved and reused

    auth_data = data;

    return data;
};

NooklinkUserApi

NookLink ACNH-level API client. An instance of this class should not be created directly; instead NooklinkApi.createUserClient or one of the createWith* static methods should be used.

Most of this API is intentionally undocumented. Read the source code at src/api/nooklink.ts, src/common/auth/nooklink.ts and src/cli/nooklink for examples of using this API. If you need any help using this API ask in #nooklink on Discord.

You should review HTTP captures of NookLink in the Nintendo Switch Online app and attempt to match the behaviour of Nintendo's official app.

NooklinkUserApi.createWithSavedToken

Create a NooklinkUserApi instance using cached data from NooklinkApi.createUserClient.

import { NooklinkUserApi, NooklinkUserAuthData } from 'nxapi/nooklink';

const auth_data: NooklinkAuthData;

const nooklinkuser = NooklinkUserApi.createWithSavedToken(auth_data);
// nooklinkuser instanceof NooklinkApi

NooklinkUserApi.createWithCliTokenData

Create a NooklinkUserApi instance using the output of the nxapi nooklink user-token --json command.

import { NooklinkUserApi, NooklinkUserCliTokenData } from 'nxapi/nooklink';

const data: NooklinkUserCliTokenData;

const nooklinkuser = NooklinkUserApi.createWithCliTokenData(data);
// nooklinkuser instanceof NooklinkUserApi

NooklinkUserApi.onTokenExpired

Function called when a 401 Unauthorized response is received from the API.

This function should either call NooklinkUserApi.getToken to renew the token, then return the PartialNooklinkUserAuthData object, or call NooklinkUserApi.renewToken.

import NooklinkApi, { NooklinkAuthData, NooklinkUserApi, PartialNooklinkUserAuthData, WebServiceError } from 'nxapi/nooklink';
import { Response } from 'node-fetch';

const nooklink: NooklinkApi;

const nooklinkuser = NooklinkUserApi.createWithSavedToken(...);
let auth_data: NooklinkUserAuthData;
const na_session_token: string;

nooklinkuser.onTokenExpired = async (error: WebServiceError, response: Response) => {
    const data = await nooklinkuser.getToken(nooklink);
    // data is a plain object of type PartialNooklinkUserAuthData
    // data should be saved and reused

    const new_auth_data = Object.assign({}, auth_data, data);
    // new_auth_data is a plain object of type NooklinkUserAuthData
    // new_auth_data should be saved and reused

    auth_data = new_auth_data;

    return data;
};

API types

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