From bc8e2ae2ac710656d232ef076a8aa4219c60cf91 Mon Sep 17 00:00:00 2001 From: Samuel Elliott Date: Sat, 15 Oct 2022 20:23:17 +0100 Subject: [PATCH] Add note about using `node16` module resolution for TypeScript --- README.md | 68 ++----------------------------------------- docs/lib/README.md | 1 + docs/lib/index.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 75 insertions(+), 66 deletions(-) create mode 120000 docs/lib/README.md diff --git a/README.md b/README.md index 1b219f8..fd1daeb 100644 --- a/README.md +++ b/README.md @@ -260,73 +260,9 @@ addUserAgent(pkg.name + '/' + pkg.version + ' (+' + pkg.repository.url + ')'); ### Usage as a TypeScript/JavaScript library -nxapi exports it's API library and types. See [docs/lib](docs/lib/index.md) and [src/exports](src/exports). +nxapi exports it's API library and types. -> You must set a user agent string using the `addUserAgent` function when using anything that contacts non-Nintendo APIs, such as the splatnet2statink 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. - -> 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import). - -> If you need any help using nxapi as a library [join the Discord server](https://discord.com/invite/4D82rFkXRv) or [create a discussion](https://github.com/samuelthomas2774/nxapi/discussions/new). - -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](src/common/auth/coral.ts). - -```ts -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: -> -> ```sh -> 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: -> -> ```ts -> import SplatNet2Api from 'nxapi/splatnet2'; -> -> const data = JSON.parse(process.env.SPLATNET_TOKEN); -> const splatnet2 = SplatNet2Api.createWithCliTokenData(data); -> ``` - -```ts -import SplatNet2Api from 'nxapi/splatnet2'; - -const iksm_session = '...'; -const unique_id = '...'; -const splatnet2 = SplatNet2Api.createWithIksmSession(iksm_session, unique_id); - -const records = await splatnet2.getRecords(); -``` +See [docs/lib](docs/lib/index.md) and [src/exports](src/exports). diff --git a/docs/lib/README.md b/docs/lib/README.md new file mode 120000 index 0000000..dd0ea36 --- /dev/null +++ b/docs/lib/README.md @@ -0,0 +1 @@ +index.md \ No newline at end of file diff --git a/docs/lib/index.md b/docs/lib/index.md index 4912b39..9cc174a 100644 --- a/docs/lib/index.md +++ b/docs/lib/index.md @@ -10,9 +10,81 @@ nxapi exports it's API library and types. nxapi is split into several modules th > 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/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: +> +> ```jsonc +> { +> "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](https://discord.com/invite/4D82rFkXRv) or [create a discussion](https://github.com/samuelthomas2774/nxapi/discussions/new). +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](src/common/auth/coral.ts). + +```ts +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: +> +> ```sh +> 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: +> +> ```ts +> import SplatNet2Api from 'nxapi/splatnet2'; +> +> const data = JSON.parse(process.env.SPLATNET_TOKEN); +> const splatnet2 = SplatNet2Api.createWithCliTokenData(data); +> ``` + +```ts +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.