nstg
Version:
Sends telegrams to a list of NationStates nations defined using a powerful query language called Telegram Recipient Language
90 lines (67 loc) • 3 kB
Markdown
# nstg #
[](https://badge.fury.io/js/nstg)
nstg is a free and open source library that allows Node.js applications to
easily send telegrams to a list of NationStates nations defined using a
powerful query language called Telegram Recipient Language.
nstg features the following:
* ability to send telegrams to complex sets of nations defined using TRL or to
simple lists of nations
* a continuous mode that periodically updates the recipients list with new
nations that match the provided TRL string, which is useful for recruitment
purposes
* progress reporting using event handlers
* all the features of nsapi, including rate-limiting, XML decoding, request
caching, and support for version 9 of the NationStates API
## Usage ##
You can install nstg using npm: `npm install nstg`.
You can also build nstg from source using Gulp. There are two main targets:
`prod` and `dev`. The only difference between them is that `dev` includes
source maps. There is also a `docs` target to generate documentation.
Consult [the documentation](https://auralia.github.io/node-nstg/)
for more information on API structure and methods, or
[this page](https://github.com/auralia/node-nstg/blob/master/trl.md)
for more information on TRL.
nstg targets ES5 but requires support for ES6 promises, so if you're not
using a runtime that supports them natively, you'll have to use a polyfill.
## Examples ##
The following is a simple example that sends a telegram to the nation Auralia:
```js
var nsapi = require("nsapi");
var nstg = require("nstg");
// TODO: Replace client key, telegram ID and telegram secret key with your own
var clientKey = "<client key>";
var telegramId = "<telegram ID>";
var telegramKey = "<telegram secret key>";
// TODO: Replace the user agent with your own
var api = new nsapi.NsApi("<user agent>");
var tgapi = new nstg.NsTgApi(api, clientKey);
tgapi.onJobStart = function() {
console.log("Started sending telegrams.");
};
tgapi.onTgSuccess = function(recipient) {
console.log("Recipient succeeded: " + recipient.nation);
};
tgapi.onTgFailure = function(recipient) {
console.log("Recipient failed: " + recipient.nation);
console.log(recipient.status.err);
};
tgapi.onJobComplete = function() {
console.log("Finished sending telegrams.");
tgapi.cleanup();
api.cleanup();
};
tgapi.sendTelegramsTrl("nations [Auralia];", {
telegramId: telegramId,
telegramKey: telegramKey,
telegramType: nsapi.TelegramType.NonRecruitment,
doNotSendIfRecruitBlocked: false,
doNotSendIfCampaignBlocked: false
}).then(function(id) {
console.log("Job ID: " + id);
}).catch(function(err) {
console.log(err);
});
```
See examples/example.js for other examples on how to use nstg.
## License ##
nstg is licensed under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).