nstg/lib/api.d.ts

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

/**
 * Copyright (C) 2016-2017 Auralia
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import { ParseError } from "./trl";
import { NsApi, TelegramType } from "nsapi";
export { ParseError };
/**
 * Represents a telegram job, which is a telegram combined with a set of
 * recipients for that telegram.
 */
export interface TelegramJob {
    /**
     * The ID of this job.
     */
    id: string;
    /**
     * The TRL string associated with this job.
     */
    trl: string;
    /**
     * The recipients associated with this job.
     */
    recipients: Recipient[];
    /**
     * Information about the telegram associated with this job.
     */
    tgInfo: TelegramInfo;
    /**
     * Whether the list of recipients should be refreshed by re-evaluating the
     * TRL string at periodic intervals.
     */
    refresh: boolean;
    /**
     * Rules for when to override API caching when re-evaluating a TRL string
     * during a refresh.
     */
    refreshOverrideCache: RefreshOverrideCache;
    /**
     * Whether to not actually send any telegrams to the specified recipients.
     */
    dryRun: boolean;
    /**
     * Information about the status of the job.
     */
    status: TelegramJobStatus;
}
/**
 * Represents the status of a telegram job.
 */
export interface TelegramJobStatus {
    /**
     * Whether at least one telegram associated with this job has been sent or
     * is in the process of being sent.
     */
    isStarted: boolean;
    /**
     * Whether there are no more telegrams that must be sent for this job.
     */
    isComplete: boolean;
}
/**
 * Represents a particular nation that will be the recipient of a telegram in
 * the context of a telegram job.
 */
export interface Recipient {
    /**
     * The name of the recipient.
     */
    nation: string;
    /**
     * The status of the recipient.
     */
    status: RecipientStatus;
    /**
     * The job ID associated with this recipient.
     */
    jobId: string;
}
/**
 * Represents a recipient's status in the context of a telegram job.
 */
export interface RecipientStatus {
    /**
     * Whether a telegram was successfully sent to the recipient. This value
     * will be undefined if no attempt to send a telegram was yet made.
     */
    success?: boolean;
    /**
     * Any error that occurred when trying to send a telegram to this recipient.
     */
    err?: any;
}
/**
 * Represents a particular telegram.
 */
export interface TelegramInfo {
    /**
     * The ID associated with this telegram.
     */
    telegramId: string;
    /**
     * The secret key associated with this telegram.
     */
    telegramKey: string;
    /**
     * The telegram type for rate limit purposes. Recruitment telegrams have a
     * stricter rate limit than non-recruitment telegrams.
     */
    telegramType: TelegramType;
    /**
     * Whether this telegram should not be sent to any nation with recruitment
     * telegrams blocked.
     */
    skipIfRecruitBlocked: boolean;
    /**
     * Whether this telegram should not be sent to any nation with campaign
     * telegrams blocked.
     */
    skipIfCampaignBlocked: boolean;
}
/**
 * Rules for when to override API caching when re-evaluating a TRL string
 * during a refresh.
 */
export declare class RefreshOverrideCache {
    /**
     * Whether to override API caching for regions primitives.
     */
    overrideRegions?: boolean;
    /**
     * Whether to override API caching for tags primitives.
     */
    overrideTags?: boolean;
    /**
     * Whether to override API caching for wa primitives.
     */
    overrideWa?: boolean;
    /**
     * Whether to override API caching for new primitives.
     */
    overrideNew?: boolean;
    /**
     * Whether to override API caching for refounded primitives.
     */
    overrideRefounded?: boolean;
    /**
     * Whether to override API caching for categories primitives.
     */
    overrideCategories?: boolean;
    /**
     * Whether to override API caching for census primitives.
     */
    overrideCensus?: boolean;
}
/**
 * Sends telegrams to a list of NationStates nations defined using a powerful
 * query language called Telegram Recipient Language.
 */
export declare class NsTgApi {
    private _api;
    private _clientKey;
    private _onJobStart;
    private _onTgSuccess;
    private _onTgFailure;
    private _onJobComplete;
    private _onNewRecipients;
    private readonly _tgJobs;
    private readonly _tgQueue;
    private readonly _tgInterval;
    private _tgInProgress;
    private readonly _tgRefreshInterval;
    private _refreshRateSecs;
    private _blockExistingTelegrams;
    private _blockNewTelegrams;
    private _cleanup;
    private _jobIdCounter;
    /**
     * Initializes a new instance of the TelegramApi class.
     *
     * @param api The NationStates API instance used by this API. Only this API
     *            should use this instance.
     * @param clientKey The telegram client key used by this API.
     * @param refreshRateSecs The number of seconds between refreshes for a
     *                        telegram job with the refresh option enabled.
     *                        Defaults to 60.
     */
    constructor(api: NsApi, clientKey: string, refreshRateSecs?: number);
    /**
     * Gets the NationStates API instance used by this API.
     */
    readonly api: NsApi;
    /**
     * Gets the telegram client key used by this API.
     */
    readonly clientKey: string;
    /**
     * Gets the event handler called when the API begins sending telegrams for
     * a particular job.
     */
    /**
     * Sets the event handler called when the API begins sending telegrams for
     * a particular job.
     *
     * @param onStart The new event handler.
     */
    onJobStart: (jobId: string) => void;
    /**
     * Gets the event handler called when new recipients are added to a job.
     */
    /**
     * Sets the event handler called when new recipients are added to a job.
     *
     * @param onNewRecipients The new event handler.
     */
    onNewRecipients: (jobId: string, recipients: Recipient[]) => void;
    /**
     * Gets the event handler called when the API successfully sends a telegram
     * to a recipient.
     */
    /**
     * Sets the event handler called when the API successfully sends a telegram
     * to a recipient.
     *
     * @param onTgSuccess The new event handler.
     */
    onTgSuccess: (recipient: Recipient) => void;
    /**
     * Gets the event handler called when the API fails to send a telegram
     * to a recipient.
     */
    /**
     * Sets the event handler called when the API fails to send a telegram
     * to a recipient.
     *
     * @param onTgFailure The new event handler.
     */
    onTgFailure: (recipient: Recipient) => void;
    /**
     * Gets the event handler called when the API finishes sending telegrams for
     * a particular job.
     */
    /**
     * Sets the event handler called when the API finishes sending telegrams for
     * a particular job.
     *
     * @param onJobComplete The new event handler.
     */
    onJobComplete: (jobId: string) => void;
    /**
     * Gets the number of seconds between refreshes for a telegram job with the
     * refresh option enabled.
     */
    readonly refreshRateSecs: number;
    /**
     * Gets whether or not existing telegrams in the queue are blocked from
     * being sent.
     */
    /**
     * If set to true, blocks the API from sending any further telegrams. If
     * set to false, normal operation will resume.
     *
     * @param blockExistingTelegrams Whether or not existing telegrams in the
     *                               queue should be blocked from being sent.
     */
    blockExistingTelegrams: boolean;
    /**
     * Gets whether or not new telegrams are blocked from being added to the
     * queue.
     */
    /**
     * If set to true, prevents any new telegrams from being added to the queue.
     * If set to false, normal operation will resume.
     *
     * @param blockNewTelegrams Whether or not new telegrams should be blocked
     *                          from being added to the queue.
     */
    blockNewTelegrams: boolean;
    /**
     * Gets whether or not this API is currently sending telegrams.
     */
    readonly tgInProgress: boolean;
    /**
     * Gets whether or not telegrams are queued.
     */
    readonly tgQueued: boolean;
    /**
     * Cancels all requests in the API queue.
     */
    clearQueue(): void;
    /**
     * 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.
     */
    cleanup(): void;
    /**
     * Gets the telegram job with the specified ID.
     *
     * @param id The telegram job ID.
     *
     * @return The telegram job with the specified ID.
     */
    getJob(id: string): TelegramJob | undefined;
    /**
     * Cancels the job with the specified ID.
     *
     * @param id The ID of the job to cancel.
     */
    cancelJob(id: string): void;
    /**
     * Throws an error if the specified TRL string is not valid.
     *
     * @param trl A TRL string.
     */
    static validateTrl(trl: string): void;
    /**
     * Parses and evaluates a TRL string.
     *
     * @param trl A TRL string.
     *
     * @return A promise returning the nations represented by the specified TRL
     *         string.
     */
    evaluateTrl(trl: string): Promise<string[]>;
    /**
     * Sends telegrams to the recipients defined by the specified template
     * recipient language string.
     *
     * @param trl The TRL string.
     * @param tgInfo Information about the telegram to send.
     * @param refresh Whether the list of recipients should be refreshed by
     *                re-evaluating the TRL string at periodic intervals.
     *                Defaults to false.
     * @param refreshOverrideCache 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.
     * @param dryRun Whether to not actually send any telegrams to the
     *               specified recipients. Defaults to false.
     *
     * @return A promise returning the ID of the telegram job associated with
     *         this request.
     */
    sendTelegramsTrl(trl: string, tgInfo: TelegramInfo, refresh?: boolean, refreshOverrideCache?: RefreshOverrideCache, dryRun?: boolean): Promise<string>;
    /**
     * Creates a job with the specified parameters.
     *
     * @param trl The TRL string.
     * @param tgInfo Information about the telegram to send.
     * @param refresh Whether the list of recipients should be refreshed by
     *                re-evaluating the TRL string at periodic intervals.
     * @param refreshOverrideCache Rules for when to override API caching when
     *                             re-evaluating a TRL string during a refresh.
     * @param dryRun Whether to not actually send any telegrams to the
     *               specified recipients.
     *
     * @return A promise returning the created telegram job.
     */
    private createJob(trl, tgInfo, refresh, refreshOverrideCache, dryRun);
    /**
     * Sends a telegram to the specified recipient.
     *
     * @param recipient The specified recipient.
     */
    private sendTelegramWithCallbacks(recipient);
    /**
     * Sends a telegram to the specified recipient.
     *
     * @param recipient The specified recipient.
     */
    private sendTelegram(recipient);
    /**
     * Called when a telegram is sent successfully to the specified recipient.
     *
     * @param recipient The specified recipient.
     */
    private recipientSuccess(recipient);
    /**
     * Called when an attempt is made to send a telegram to the specified
     * recipient that fails.
     *
     * @param recipient The specified recipient.
     * @param err The error associated with the failure.
     */
    private recipientFailure(recipient, err);
    /**
     * Called when a recipient entry in the queue is processed in order to
     * determine if a job is complete.
     *
     * @param job The job associated with the recipient.
     */
    private jobComplete(job);
}