Add setting a user agent using an environment variable

README.md

@@ -719,6 +719,31 @@ Some options can be set using environment variables. These can be stored in a `.
 
 This can be used with the Electron app (including when using the packaged version).
 
+#### User agent strings
+
+As nxapi can be used in scripts or as a library, it exposes a few different methods for setting a user agent string for requests to the splatnet2statink, flapg, imink and other non-Nintendo APIs. You must include the name and version number of your script/program in the user agent. If your program is not open source or not easily discoverable (e.g. by searching GitHub) it must also include contact information.
+
+When using the nxapi command in a script or other program, the `NXAPI_USER_AGENT` environment variable should be used. The `NXAPI_USER_AGENT` environment variable is only used by the nxapi command, and will be ignored by the Electron app or when using nxapi as a library.
+
+```sh
+NXAPI_USER_AGENT="your-script/1.0.0 (+https://github.com/...)" nxapi nso ...
+```
+
+When using nxapi as a TypeScript/JavaScript library, the `addUserAgent` function should be used.
+
+```ts
+import { addUserAgent } from 'nxapi';
+
+addUserAgent('your-script/1.0.0 (+https://github.com/...)');
+
+// This could also be read from a package.json file
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { readFile } from 'node:fs/promises':
+const pkg = JSON.parse(await readFile(resolve(fileURLToPath(import.meta.url), '..', 'package.json'), 'utf-8'));
+addUserAgent(pkg.name + '/' + pkg.version + ' (+' + pkg.repository.url + ')');
+```
+
 ### Links
 
 - Nintendo Switch Online app API docs

src/cli.ts

@@ -10,6 +10,7 @@ import { dev } from './util/product.js';
 import { paths } from './util/storage.js';
 import { YargsArguments } from './util/yargs.js';
 import { addUserAgent } from './util/useragent.js';
+import { USER_AGENT_INFO_URL } from './common/constants.js';
 
 const debug = createDebug('cli');
 
@@ -51,6 +52,13 @@ export type Arguments = YargsArguments<ReturnType<typeof createYargs>>;
 export async function main(argv = process.argv.slice(2)) {
     addUserAgent('nxapi-cli');
 
+    if (process.env.NXAPI_USER_AGENT) {
+        addUserAgent(process.env.NXAPI_USER_AGENT);
+    } else if (!process.stdout.isTTY) {
+        console.warn('[warn] The nxapi command is not running in a terminal. If using the nxapi command in a script or other program, the NXAPI_USER_AGENT environment variable should be set. See ' + USER_AGENT_INFO_URL + '.');
+        addUserAgent('unidentified-script');
+    }
+
     const yargs = createYargs(argv);
 
     if (!process.env.NXAPI_SKIP_UPDATE_CHECK) await checkUpdates();

src/common/constants.ts

@@ -2,3 +2,4 @@ export const GITLAB_URL = 'https://gitlab.fancy.org.uk/samuel/nxapi';
 export const GITHUB_MIRROR_URL = 'https://github.com/samuelthomas2774/nxapi';
 export const ISSUES_URL = 'https://github.com/samuelthomas2774/nxapi/issues';
 export const ZNCA_API_USE_URL = 'https://gitlab.fancy.org.uk/samuel/nxapi#splatnet2statink-and-flapg';
+export const USER_AGENT_INFO_URL = 'https://gitlab.fancy.org.uk/samuel/nxapi#user-agent-strings';