Options
All
  • Public
  • Public/Protected
  • All
Menu

Class NsApi

Provides access to the NationStates API.

Hierarchy

  • NsApi

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

  • Initializes a new instance of the NsApi class.

    Parameters

    • userAgent: string

      A string identifying you to the NationStates API. Using the name of your main nation is recommended.

    • options: NsApiOptions

      Other options.

    Returns NsApi

Properties

Private _apiDelayMillis

_apiDelayMillis: number = 600

Private _blockExistingRequests

_blockExistingRequests: boolean = false

Private _blockNewRequests

_blockNewRequests: boolean = false

Private _cache

_cache: {}

Type declaration

  • [url: string]: { data: any; time: number }
    • data: any
    • time: number

Private _cacheApiRequests

_cacheApiRequests: boolean = true

Private _cacheTime

_cacheTime: number = 900

Private _cleanup

_cleanup: boolean = false

Private _delay

_delay: boolean = true

Private _interval

_interval: any

Private _lastRequestTime

_lastRequestTime: number

Private _lastTgTime

_lastTgTime: number

Private _nonRecruitTgDelayMillis

_nonRecruitTgDelayMillis: number = 180000

Private _queue

_queue: { func: () => void; reject: (err: any) => void; tg: TelegramType | undefined }[] = []

Private _recruitTgDelayMillis

_recruitTgDelayMillis: number = 60000

Private _requestInProgress

_requestInProgress: boolean = false

Private _userAgent

_userAgent: string = ""

Accessors

apiDelayMillis

  • get apiDelayMillis(): number
  • set apiDelayMillis(apiDelayMillis: number): void

  • Gets the delay before API requests in milliseconds.

    Returns number

  • Sets the delay before API requests in milliseconds. Must be greater than or equal to 600.

    Parameters

    • apiDelayMillis: number

    Returns void

blockExistingRequests

  • get blockExistingRequests(): boolean
  • set blockExistingRequests(blockExistingRequests: boolean): void

  • Gets whether the API is blocked from performing any further requests.

    Returns boolean

  • Sets whether the API is blocked from performing any further requests.

    Parameters

    • blockExistingRequests: boolean

    Returns void

blockNewRequests

  • get blockNewRequests(): boolean
  • set blockNewRequests(blockNewRequests: boolean): void

  • Gets whether new API requests are blocked from being added to the queue.

    Returns boolean

  • Sets whether new API requests are blocked from being added to the queue.

    Parameters

    • blockNewRequests: boolean

    Returns void

cacheApiRequests

  • get cacheApiRequests(): boolean
  • set cacheApiRequests(cacheApiRequests: boolean): void

  • Gets whether API requests should be cached.

    Returns boolean

  • Sets whether API requests should be cached.

    Parameters

    • cacheApiRequests: boolean

    Returns void

cacheTime

  • get cacheTime(): number
  • set cacheTime(cacheTime: number): void

  • Gets the number of seconds that API requests should stay cached.

    Returns number

  • Sets the number of seconds that API requests should stay cached.

    Parameters

    • cacheTime: number

    Returns void

delay

  • get delay(): boolean
  • set delay(delay: boolean): void

  • Gets whether a delay is introduced before API and telegram requests.

    Setting this value re-initializes the API scheduler.

    Returns boolean

  • Sets a value indicating whether a delay is introduced before API and telegram requests.

    Setting this value re-initializes the API scheduler.

    Parameters

    • delay: boolean

    Returns void

nonRecruitTgDelayMillis

  • get nonRecruitTgDelayMillis(): number
  • set nonRecruitTgDelayMillis(nonRecruitTgDelayMillis: number): void

  • Gets the delay before non-recruitment telegram requests in milliseconds.

    Returns number

  • Sets the delay before non-recruitment telegram requests in milliseconds. Must be greater than or equal to 60000.

    Parameters

    • nonRecruitTgDelayMillis: number

    Returns void

recruitTgDelayMillis

  • get recruitTgDelayMillis(): number
  • set recruitTgDelayMillis(recruitTgDelayMillis: number): void

  • Gets the delay before recruitment telegram requests in milliseconds. Must be greater than or equal to 180000.

    Returns number

  • Sets the delay before recruitment telegram requests in milliseconds.

    Parameters

    • recruitTgDelayMillis: number

    Returns void

requestInProgress

  • get requestInProgress(): boolean

  • Gets whether an API request is in progress.

    Returns boolean

requestsQueued

  • get requestsQueued(): boolean

  • Gets whether there is at least one API request in the queue.

    Returns boolean

userAgent

  • get userAgent(): string
  • set userAgent(userAgent: string): void

  • Gets a string identifying you to the NationStates API.

    Returns string

  • Sets a string identifying you to the NationStates API. Using the name of your main nation is recommended.

    Parameters

    • userAgent: string

    Returns void

Methods

Private apiPath

  • apiPath(params: string): string

  • Creates a NationStates API path from a set of parameters.

    Parameters

    • params: string

    Returns string

Private apiRequest

  • apiRequest(path: string, tg: TelegramType | undefined, auth: Auth | undefined): Promise<HttpResponse>

  • Requests data from the NationStates API.

    Parameters

    • path: string

      The NationStates API path to request data from.

    • tg: TelegramType | undefined

      The telegram type, or undefined if this is not a telegram request.

    • auth: Auth | undefined

      Authentication information for private shards.

    Returns Promise<HttpResponse>

    A promise returning the data from the NationStates API.

authenticateRequest

  • authenticateRequest(nation: string, checksum: string, token?: undefined | string): Promise<boolean>

  • Sends an authentication request using the NationStates authentication API.

    Note that authentication requests are never cached.

    Parameters

    • nation: string

      The nation to authenticate.

    • checksum: string

      The checksum to perform authentication with.

    • Optional token: undefined | string

      Site-specific token. No token will be specified if this value is left undefined.

    Returns Promise<boolean>

    A promise returning true if authenticated or false if not authenticated.

cleanup

  • cleanup(): void

  • Cancels all requests in the API queue and turns off the API scheduler.

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

    Returns void

clearCache

  • clearCache(): void

  • Clears the API request cache.

    Returns void

clearQueue

  • clearQueue(): void

  • Cancels all API requests in the queue.

    Returns void

Private initInterval

  • initInterval(): void

  • Initializes the API scheduler.

    Returns void

nationCommandRequest

  • nationCommandRequest(auth: Auth, nation: string, command: string, commandParams?: {}, requiresPrepare?: boolean): Promise<any>

  • Executes a NationStates nation command. Even if request caching is enabled, these requests are never cached.

    Parameters

    • auth: Auth

      Authentication information for private shards.

    • nation: string

      The name of the nation to execute a command for.

    • command: string

      The command to execute.

    • Default value commandParams: {} = {}

      Additional command-specific parameters.

      • [name: string]: string
    • Default value requiresPrepare: boolean = true

      Whether this command requires a prepare.

    Returns Promise<any>

    A promise providing data from the API.

nationRequest

  • nationRequest(nation: string, shards?: string[], shardParams?: {}, auth?: Auth, disableCache?: boolean): Promise<any>

  • Requests data from the NationStates nation API.

    Parameters

    • nation: string

      The name of the nation to request data for.

    • Default value shards: string[] = []

      An array of nation API shards. No shards will be specified if left undefined.

    • Default value shardParams: {} = {}

      Additional shard-specific parameters.

      • [paramName: string]: string
    • Optional auth: Auth

      Authentication information for private shards.

    • Default value disableCache: boolean = false

      If the request cache is enabled, disable it for this request.

    Returns Promise<any>

    A promise providing data from the API.

Private parseXml

  • parseXml(text: string): Promise<any>

  • Parses XML into a JSON object.

    Parameters

    • text: string

      The XML to parse.

    Returns Promise<any>

    A promise returning a JSON object.

regionRequest

  • regionRequest(region: string, shards?: string[], shardParams?: {}, disableCache?: boolean): Promise<any>

  • Requests data from the NationStates region API.

    Parameters

    • region: string

      The name of the region to request data for.

    • Default value shards: string[] = []

      An array of region API shards. No shards will be specified if left undefined.

    • Default value shardParams: {} = {}

      Additional shard-specific parameters.

      • [paramName: string]: string
    • Default value disableCache: boolean = false

      If the request cache is enabled, disable it for this request.

    Returns Promise<any>

    A promise providing data from the API.

telegramRequest

  • telegramRequest(clientKey: string, tgId: string, tgSecretKey: string, recipient: string, type: TelegramType): Promise<void>

  • Sends a telegram using the NationStates telegram API. Even if request caching is enabled, these requests are never cached.

    Parameters

    • clientKey: string

      The client key.

    • tgId: string

      The ID of the telegram API template.

    • tgSecretKey: string

      The secret key of the telegram API template.

    • recipient: string

      The name of the recipient.

    • type: TelegramType

      The telegram type for rate limit purposes.

    Returns Promise<void>

    A promise providing confirmation from the telegram API.

worldAssemblyRequest

  • worldAssemblyRequest(council: WorldAssemblyCouncil, shards?: string[], shardParams?: {}, disableCache?: boolean): Promise<any>

  • Requests data from the NationStates World Assembly API.

    Parameters

    • council: WorldAssemblyCouncil

      The council of the World Assembly to request data for.

    • Default value shards: string[] = []

      An array of World Assembly API shards. No shards will be specified if left undefined.

    • Default value shardParams: {} = {}

      Additional shard-specific parameters.

      • [paramName: string]: string
    • Default value disableCache: boolean = false

      If the request cache is enabled, disable it for this request.

    Returns Promise<any>

    A promise providing data from the API.

worldRequest

  • worldRequest(shards?: string[], shardParams?: {}, disableCache?: boolean): Promise<any>

  • Requests data from the NationStates world API.

    This API can also be used to request information from the trading cards API if the "card" or "cards" shard is supplied.

    Parameters

    • Default value shards: string[] = []

      An array of world or trading card API shards. No shards will be specified if left undefined.

    • Default value shardParams: {} = {}

      Additional shard-specific parameters.

      • [paramName: string]: string
    • Default value disableCache: boolean = false

      If the request cache is enabled, disable it for this request.

    Returns Promise<any>

    A promise providing data from the API.

Private xmlRequest

  • xmlRequest(shards: string[], shardParams: {}, globalParams: {}, auth: Auth | undefined, disableCache: boolean): Promise<any>

  • Requests XML data from the NationStates API.

    Parameters

    • shards: string[]

      Shards to add to the NationStates API path.

    • shardParams: {}

      Additional shard-specific parameters.

      • [paramName: string]: string
    • globalParams: {}

      Additional URI-level parameters.

      • [paramName: string]: string
    • auth: Auth | undefined

      Authentication information for private shards.

    • disableCache: boolean

      If the request cache is enabled, disable it for this request.

    Returns Promise<any>

    A promise returning the data from the NationStates API.

Static Private toId

  • toId(name: string): string

  • Converts names to a fixed form: all lowercase, with spaces replaced with underscores.

    Parameters

    • name: string

      The name to convert.

    Returns string

    The converted name.

Generated using TypeDoc