nationstates.js v1.0.0
NationStates.js | client Wrapper
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. |
Installation / Setup
1. Installation
While in your projects' directory run the following command in the terminal to install the library:
npm i nationstates.js
2. Import/Require the library
// 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');
3. Initialize
/**
* 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');
Nation
ā” Documentation
All public shards for a nation are fetched and stored in a returned Promise<NationResult>
after awaiting init()
.
Example:
const nation = await new ns.Nation(client, 'nationName').init();
console.log(nation.happenings, nation.population); // Whatever shard you want!
Region
ā” Documentation
All public shards for a region are fetched and stored in a returned Promise<RegionResult>
after awaiting init()
.
Example:
const region = await new ns.Region(client, 'regionName').init();
console.log(region.messages, region.history); // Whatever shard you want!
RequestBuilder
ā” Documentation
ā” For private shards use PrivateRequestBuilder.
Example:
In this example, we will get Testlandia's flag and population as a JS object.
1. Instantiate Object
const req = new ns.RequestBuilder(client);
2. Build and send the request.
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();
3. See the result!
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']); // 39561
PrivateRequestBuilder
ā” Documentation
Instructions
This 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')
Notice
ā ļøāļø Will not work if you did not authenticate().
NSMethods
ā” Documentation
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. |
Example:
const nsFun = new ns.NSMethods(client);
let endoResult = await nsFun.isEndorsing('Testlandia', 'Olvaria'); // Is Testlandia endorsing Olvaria?
console.log(endoResult) // 0
Private Commands
Dispatches
An 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:
1. Adding a dispatch
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();
2. Removing a dispatch
await new ns.Dispatch(client, 'nation', 'password', ns.Mode.remove)
.dispatchID(12345)
.execute();
3. Editing a dispatch
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();
4. Check for success/failure
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);
ā ļø There is no support for issue
or giftcard
private commands.
Browser Support
Browser support is not guarenteed but possible using Browserify.
Here's how:
1. Create a new Node.js project.
2. Create a new index.js
file and run npm install nationstates.js
.
3. Require the library in your index.js
:
const ns = require('nationstates.js');
- Now install Browserify:
npm install -g browserify
. - Now we can convert our
.js
file to a.js
file that can be run in a browser. The following command recursively finds all require() statements and bundles them together in abrowser.js
file. It outputsns
as 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>
Contact / Questions
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 šš»