 |
 |
 |
|---|
Version: 1.0.0 | 📖 Documentation
NationsStates.js is a wrapper to ease accessing the NationStates client through method-chaining and other abstractions. Additional built-in methods for common tasks are also included.
This wrapper takes care of enforcing the rate limit, conversions to JS objects, and allowing usage of async/await.
| ㅤ | Feature | Note |
|---|---|---|
| ✅ | Rate limit | Built-in to 650ms. Can be raised, but not lowered. |
| ✅ | Dumps | Support for easily downloading, unzipping, and converting to JSON. See NSMethods and the documentation. |
| ✅ | Nations client | See Nation (recommended) or RequestBuilder |
| ✅ | Regions client | See Region (recommended) or RequestBuilder |
| ✅ | World client | See RequestBuilder. |
| ✅ | World Assembly client | See RequestBuilder. |
| ❌ | Telegrams | Future support planned. |
| 🟡 | Trading Cards client | See RequestBuilder. Requires use of addCustomParam. |
| ✅ | Verification client | Built-in functions to simplify process. No support for site-specific tokens. Use NSMethods (recommended) or RequestBuilder. |
| ✅ | Private shards | See PrivateRequestBuilder. |
| 🟡 | Private commands | See Dispatches. No support for issues or giftcards. |
| ✅ | Built-in methods for common tasks | See NSMethods. |
| 🟡 | Browser support | Yes, but not guaranteed. |
While in your projects' directory run the following command in the terminal to install the library:
npm i nationstates.js
// For TypeScript, you can use the following import statement (Recommended):
import * as ns from 'nationstates.js/client';
// For standard JavaScript:
const ns = require('nationstates.js');/**
* 1. Instantiate a Client object.
* TODO: Ensure to replace the user-agent. This is usually the name of your own nation.
* This allows NationStates servers to recognize you.
*/
const client = new ns.Client('user-Agent');All public shards for a nation are fetched and stored in a returned Promise<NationResult>
after awaiting init().
const nation = await new ns.Nation(client, 'nationName').init();
console.log(nation.happenings, nation.population); // Whatever shard you want!All public shards for a region are fetched and stored in a returned Promise<RegionResult>
after awaiting init().
const region = await new ns.Region(client, 'regionName').init();
console.log(region.messages, region.history); // Whatever shard you want!➡ Documentation
➡ For private shards use PrivateRequestBuilder.
In this example, we will get Testlandia's flag and population as a JS object.
const req = new ns.RequestBuilder(client);await req.addNation('testlandia') // nation=testlandia
.addShards(['flag', 'population']) // q=flag+population
.execute(); // Asynchronously execute the request.
// Convert the result to a JS object (optional).
const json = await req.toJS();You are responsible for traversing the result. This is approximately what the json response will look like:
{
"id": "testlandia",
"population": 39561,
"flag": "https://www.nationstates.net/images/flags/Iran.svg"
}console.log(json) // See above
console.log(json['flag']); // https://www.nationstates.net/images/flags/Iran.svg
console.log(json['population']); // 39561This class extends the RequestBuilder and functions the same.
But in order to send any request, you must first authenticate()
in order to get the x-pin and allow for quick repeated requests:
const privReq = new ns.PrivateRequestBuilder(client);
// You must authenticate. This retrieves the x-pin and allows for quick repeated requests.
await privReq.authenticate('nation', 'password')| Feature | Purpose |
|---|---|
verify(nation, checksum, siteSpecificToken?) |
Verify the checksum of a nation using. Returns a 0 or 1. You may optionally add a site-specific token. |
downloadDumpAsync(type, directory, options?) |
Download data dumps. For options, see IDumpOptions. |
isEndorsing(nation1, nation2) |
Verifies if nation1 is endorsing nation2. Returns a boolean. |
const nsFun = new ns.NSMethods(client);
let endoResult = await nsFun.isEndorsing('Testlandia', 'Olvaria'); // Is Testlandia endorsing Olvaria?
console.log(endoResult) // 0An easy way to interact with the NationStates Private Commands and add, remove, or edit dispatches in a high-level way.
Enumerators have also been provided for mode, category, subcategory for ease of use.
Here are some examples:
await new ns.Dispatch(client, 'nation', 'password', ns.Mode.add)
.title('Cool Title!')
.text('Hello World!')
.category(ns.Category.factbook)
.subcategory(ns.Factbook.legislation)
.execute();await new ns.Dispatch(client, 'nation', 'password', ns.Mode.remove)
.dispatchID(12345)
.execute();await new ns.Dispatch(client, 'nation', 'password', ns.Mode.edit)
.dispatchID(1630710)
.title('Edited Title')
.text('Hello World!')
.category(ns.Category.bulletin)
.subcategory(ns.Bulletin.news)
.execute();const result = await new ns.Dispatch(client, 'nation', 'password', ns.Mode.remove)
.dispatchID(12345)
.execute();
console.log(result.response.statusBool, result.response.statusCode, result.response.body);issue or giftcard private commands.
Browser support is not guarenteed but possible using Browserify. Here's how:
- Create a new Node.js project.
- Create a new
index.jsfile and runnpm install nationstates.js. - Require the library in your
index.js:
const ns = require('nationstates.js');- Now install Browserify:
npm install -g browserify. - Now we can convert our
.jsfile to a.jsfile that can be run in a browser. The following command recursively finds all require() statements and bundles them together in abrowser.jsfile. It outputsnsas a global variable which you use to access thelibrary:browserify index.js -o --standalone ns > browser.js - The following should now work in the browser:
<script src="browser.js">
const api = ns.Client('user-agent');
// Rest of your script here...
</script>If you've encountered any issue, have feature requests, or need support using this client please feel free to reach out to me at anytime! Preferably on Discord at Heaveria#6413. Otherwise, send me a telegram.
Cheers,
Heaveria 👋🏻