NsTgApi | nstg

Sends telegrams to a list of NationStates nations defined using a powerful query language called Telegram Recipient Language.

Hierarchy

NsTgApi

Index

Constructors

constructor

Properties

Accessors

Methods

Constructors

constructor

new NsTgApi(api: NsApi, clientKey: string, refreshRateSecs?: number): NsTgApi

- Defined in api.ts:203
Initializes a new instance of the TelegramApi class.

Parameters
- api: NsApi
  
  The NationStates API instance used by this API. Only this API should use this instance.
- clientKey: string
  
  The telegram client key used by this API.
- Default value refreshRateSecs: number = 60
  
  The number of seconds between refreshes for a telegram job with the refresh option enabled. Defaults to 60.
Returns NsTgApi

Properties

Private _api

_api: NsApi

Private _blockExistingTelegrams

_blockExistingTelegrams: boolean

Private _blockNewTelegrams

_blockNewTelegrams: boolean

Private _cleanup

_cleanup: boolean

Private _clientKey

_clientKey: string

Private _jobIdCounter

_jobIdCounter: number

Private _onJobComplete

_onJobComplete: function

Type declaration

- (jobId: string): void
- Parameters
  - jobId: string
  Returns void

Private _onJobStart

_onJobStart: function

Type declaration

- (jobId: string): void
- Parameters
  - jobId: string
  Returns void

Private _onNewRecipients

_onNewRecipients: function

Type declaration

- (jobId: string, recipients: Recipient[]): void
- Parameters
  - jobId: string
  - recipients: Recipient[]
  Returns void

Private _onTgFailure

_onTgFailure: function

Type declaration

- (recipient: Recipient): void
- Parameters
  - recipient: Recipient
  Returns void

Private _onTgSuccess

_onTgSuccess: function

Type declaration

- (recipient: Recipient): void
- Parameters
  - recipient: Recipient
  Returns void

Private _refreshRateSecs

_refreshRateSecs: number

Private _tgInProgress

_tgInProgress: boolean

Private _tgInterval

_tgInterval: any

Private _tgJobs

_tgJobs: object

Type declaration

[id: string]: TelegramJob

Private _tgQueue

_tgQueue: Recipient[]

Private _tgRefreshInterval

_tgRefreshInterval: any

Accessors

api

get api(): NsApi

- Defined in api.ts:302
Gets the NationStates API instance used by this API.

Returns NsApi

blockExistingTelegrams

get blockExistingTelegrams(): boolean
set blockExistingTelegrams(blockExistingTelegrams: boolean): void

- Defined in api.ts:416
Gets whether or not existing telegrams in the queue are blocked from being sent.

Returns boolean
- Defined in api.ts:427
If set to true, blocks the API from sending any further telegrams. If set to false, normal operation will resume.

Parameters
- blockExistingTelegrams: boolean
  
  Whether or not existing telegrams in the queue should be blocked from being sent.
Returns void

blockNewTelegrams

get blockNewTelegrams(): boolean
set blockNewTelegrams(blockNewTelegrams: boolean): void

- Defined in api.ts:435
Gets whether or not new telegrams are blocked from being added to the queue.

Returns boolean
- Defined in api.ts:446
If set to true, prevents any new telegrams from being added to the queue. If set to false, normal operation will resume.

Parameters
- blockNewTelegrams: boolean
  
  Whether or not new telegrams should be blocked from being added to the queue.
Returns void

clientKey

get clientKey(): string

- Defined in api.ts:309
Gets the telegram client key used by this API.

Returns string

onJobComplete

get onJobComplete(): function
set onJobComplete(onJobComplete: function): void

- Defined in api.ts:390
Gets the event handler called when the API finishes sending telegrams for a particular job.

Returns function
- - (jobId: string): void
  - The new event handler.
    
    Parameters
    - jobId: string
    Returns void
- Defined in api.ts:400
Sets the event handler called when the API finishes sending telegrams for a particular job.

Parameters
- onJobComplete: function
  
  The new event handler.
  - - (jobId: string): void
    - Parameters
      - jobId: string
      Returns void
Returns void

onJobStart

get onJobStart(): function
set onJobStart(onStart: function): void

- Defined in api.ts:317
Gets the event handler called when the API begins sending telegrams for a particular job.

Returns function
- - (jobId: string): void
  - Parameters
    - jobId: string
    Returns void
- Defined in api.ts:327
Sets the event handler called when the API begins sending telegrams for a particular job.

Parameters
- onStart: function
  
  The new event handler.
  - - (jobId: string): void
    - Parameters
      - jobId: string
      Returns void
Returns void

onNewRecipients

get onNewRecipients(): function
set onNewRecipients(onNewRecipients: function): void

- Defined in api.ts:334
Gets the event handler called when new recipients are added to a job.

Returns function
- - (jobId: string, recipients: Recipient[]): void
  - The new event handler.
    
    Parameters
    - jobId: string
    - recipients: Recipient[]
    Returns void
- Defined in api.ts:343
Sets the event handler called when new recipients are added to a job.

Parameters
- onNewRecipients: function
  
  The new event handler.
  - - (jobId: string, recipients: Recipient[]): void
    - Parameters
      - jobId: string
      - recipients: Recipient[]
      Returns void
Returns void

onTgFailure

get onTgFailure(): function
set onTgFailure(onTgFailure: function): void

- Defined in api.ts:371
Gets the event handler called when the API fails to send a telegram to a recipient.

Returns function
- - (recipient: Recipient): void
  - The new event handler.
    
    Parameters
    - recipient: Recipient
    Returns void
- Defined in api.ts:381
Sets the event handler called when the API fails to send a telegram to a recipient.

Parameters
- onTgFailure: function
  
  The new event handler.
  - - (recipient: Recipient): void
    - Parameters
      - recipient: Recipient
      Returns void
Returns void

onTgSuccess

get onTgSuccess(): function
set onTgSuccess(onTgSuccess: function): void

- Defined in api.ts:352
Gets the event handler called when the API successfully sends a telegram to a recipient.

Returns function
- - (recipient: Recipient): void
  - The new event handler.
    
    Parameters
    - recipient: Recipient
    Returns void
- Defined in api.ts:362
Sets the event handler called when the API successfully sends a telegram to a recipient.

Parameters
- onTgSuccess: function
  
  The new event handler.
  - - (recipient: Recipient): void
    - Parameters
      - recipient: Recipient
      Returns void
Returns void

refreshRateSecs

get refreshRateSecs(): number

- Defined in api.ts:408
Gets the number of seconds between refreshes for a telegram job with the refresh option enabled.

Returns number

tgInProgress

get tgInProgress(): boolean

- Defined in api.ts:453
Gets whether or not this API is currently sending telegrams.

Returns boolean

tgQueued

get tgQueued(): boolean

- Defined in api.ts:460
Gets whether or not telegrams are queued.

Returns boolean

Methods

cancelJob

cancelJob(id: string): void

- Defined in api.ts:506
Cancels the job with the specified ID.

Parameters
- id: string
  
  The ID of the job to cancel.
Returns void

cleanup

cleanup(): void

- Defined in api.ts:482
Cancels all requests in the telegram queue and turns off the API scheduler.

After this function is called, no further telegrams can be sent using this API instance, including telegrams currently in the queue.

Returns void

clearQueue

clearQueue(): void

- Defined in api.ts:467
Cancels all requests in the API queue.

Returns void

Private createJob

createJob(trl: string, tgInfo: TelegramInfo, refresh: boolean, refreshOverrideCache: RefreshOverrideCache, dryRun: boolean): Promise<TelegramJob>

- Defined in api.ts:610
Creates a job with the specified parameters.

Parameters
- trl: string
  
  The TRL string.
- tgInfo: TelegramInfo
  
  Information about the telegram to send.
- refresh: boolean
  
  Whether the list of recipients should be refreshed by re-evaluating the TRL string at periodic intervals.
- refreshOverrideCache: RefreshOverrideCache
  
  Rules for when to override API caching when re-evaluating a TRL string during a refresh.
- dryRun: boolean
  
  Whether to not actually send any telegrams to the specified recipients.
Returns Promise<TelegramJob>

A promise returning the created telegram job.

evaluateTrl

evaluateTrl(trl: string): Promise<string[]>

- Defined in api.ts:542
Parses and evaluates a TRL string.

Parameters
- trl: string
  
  A TRL string.
Returns Promise<string[]>

A promise returning the nations represented by the specified TRL string.

getJob

getJob(id: string): TelegramJob | undefined

- Defined in api.ts:497
Gets the telegram job with the specified ID.

Parameters
- id: string
  
  The telegram job ID.
Returns TelegramJob | undefined

The telegram job with the specified ID.

Private jobComplete

jobComplete(job: TelegramJob): void

- Defined in api.ts:736
Called when a recipient entry in the queue is processed in order to determine if a job is complete.

Parameters
- job: TelegramJob
  
  The job associated with the recipient.
Returns void

Private recipientFailure

recipientFailure(recipient: Recipient, err: any): void

- Defined in api.ts:717
Called when an attempt is made to send a telegram to the specified recipient that fails.

Parameters
- recipient: Recipient
  
  The specified recipient.
- err: any
  
  The error associated with the failure.
Returns void

Private recipientSuccess

recipientSuccess(recipient: Recipient): void

- Defined in api.ts:698
Called when a telegram is sent successfully to the specified recipient.

Parameters
- recipient: Recipient
  
  The specified recipient.
Returns void

Private sendTelegram

sendTelegram(recipient: Recipient): Promise<void>

- Defined in api.ts:657
Sends a telegram to the specified recipient.

Parameters
- recipient: Recipient
  
  The specified recipient.
Returns Promise<void>

Private sendTelegramWithCallbacks

sendTelegramWithCallbacks(recipient: Recipient): void

- Defined in api.ts:646
Sends a telegram to the specified recipient.

Parameters
- recipient: Recipient
  
  The specified recipient.
Returns void

sendTelegramsTrl

sendTelegramsTrl(trl: string, tgInfo: TelegramInfo, refresh?: boolean, refreshOverrideCache?: RefreshOverrideCache, dryRun?: boolean): Promise<string>

- Defined in api.ts:565
Sends telegrams to the recipients defined by the specified template recipient language string.

Parameters
- trl: string
  
  The TRL string.
- tgInfo: TelegramInfo
  
  Information about the telegram to send.
- Default value refresh: boolean = false
  
  Whether the list of recipients should be refreshed by re-evaluating the TRL string at periodic intervals. Defaults to false.
- Default value refreshOverrideCache: RefreshOverrideCache = {overrideRegions: true,overrideTags: true,overrideWa: true,overrideNew: true,overrideRefounded: true,overrideCategories: false,overrideCensus: false}
  
  Rules for when to override API caching when re-evaluating a TRL string during a refresh. By default, all primitives override caches except categories and census.
- Default value dryRun: boolean = false
  
  Whether to not actually send any telegrams to the specified recipients. Defaults to false.
Returns Promise<string>

A promise returning the ID of the telegram job associated with this request.

Static validateTrl

validateTrl(trl: string): void

- Defined in api.ts:530
Throws an error if the specified TRL string is not valid.

Parameters
- trl: string
  
  A TRL string.
Returns void

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

api: NsApi

clientKey: string

Default value refreshRateSecs: number = 60

Returns NsTgApi

Properties

Private _api

Private _blockExistingTelegrams

Private _blockNewTelegrams

Private _cleanup

Private _clientKey

Private _jobIdCounter

Private _onJobComplete

Type declaration

Parameters

jobId: string

Returns void

Private _onJobStart

Type declaration

Parameters

jobId: string

Returns void

Private _onNewRecipients

Type declaration

Parameters

jobId: string

recipients: Recipient[]

Returns void

Private _onTgFailure

Type declaration

Parameters

recipient: Recipient

Returns void

Private _onTgSuccess

Type declaration

Parameters

recipient: Recipient

Returns void

Private _refreshRateSecs

Private _tgInProgress

Private _tgInterval

Private _tgJobs

Type declaration

[id: string]: TelegramJob

Private _tgQueue

Private _tgRefreshInterval

Accessors

api

Returns NsApi

blockExistingTelegrams

Returns boolean

Parameters

blockExistingTelegrams: boolean

Returns void

blockNewTelegrams

Returns boolean

Parameters

blockNewTelegrams: boolean

Returns void

clientKey

Returns string

onJobComplete

Returns function

Parameters

jobId: string

Returns void

Parameters

onJobComplete: function

Parameters

jobId: string

Returns void

Returns void