nationstates.js/src/request_builder/request_builder.d.ts

A wrapper to interact with the NationStates API.

import { API, Client } from "../client";
import { NationPublic } from "../enums/nation_public";
import { NationPrivate } from "../enums/nation_private";
import { RegionPublic } from "../enums/region_public";
import { World } from "../enums/world";
import { WorldAssembly } from "../enums/world_assembly";
import { Cards } from "../enums/cards";
import { IResponse } from "./interfaces/response";
import { CouncilID } from "../enums/council_id";
/**
 * Build a request to your specifications! Usage:
 * - (1) Define the architecture of a https request before it sent to the client.
 * - (2) Access and modify the response of a request.
 * @example const request = await new RequestBuilder(api).addNation('testlandia').execute();
 * console.log(request.body);
 * @param {client} api - The client instance to use. Used to enforce the rate limit and user agent.
 */
export declare class RequestBuilder {
    protected client: Client;
    protected _urlObj: URL;
    protected _shards: string[];
    response: IResponse;
    constructor(client: API | Client);
    /**
     * Returns full node-fetch request and other meta-data created by the client wrapper.
     * Typical usage would to analyze the request for any errors.
     * @example console.log(request.fetchResponse);
     */
    get responseData(): IResponse;
    /**
     * Returns the response status code and status boolean from the node-fetch response as an object.
     * @example console.log(request.responseStatus.statusCode);
     */
    get responseStatus(): IResponseStatus;
    /**
     * Returns the current body of the last node-fetch request associated with this instance.
     * @example console.log(request.body);
     */
    get body(): string | number;
    /**
     * Returns the current JS object of the last node-fetch request associated with this instance.
     * You must convert the body to a JS object before using this method via convertBodyToJSON().
     * @example request.convertToJSON();
     * console.log(request.js);
     */
    get js(): object;
    /**
     * Returns the current shards of a RequestBuilder object as a single string or as an array of strings.
     * @example console.log(request.shards);
     */
    get shards(): string | string[];
    /**
     * Builds and then returns the URL for which the request will be sent.
     * Serves the purpose of ensuring proper URL encoding.
     */
    get href(): string;
    /**
     * Adds the nation to the url parameters.
     * @example .addNation('Testlandia') adds 'nation=Testlandia' to the url.
     * @param name - The name of the nation from which data is retrieved.
     */
    addNation(name: string): RequestBuilder;
    /**
     * Adds the region to the url parameters.
     * @example .addRegion('The South Pacific') adds 'region=The%20South%20Pacific' to the url.
     * @param name
     */
    addRegion(name: string): RequestBuilder;
    /**
     * Adds a council ID to the url parameters.
     * @example .addCouncil(1) adds 'wa=1' to the url.
     * @param id
     */
    addCouncilID(id: CouncilID | number): RequestBuilder;
    /**
     * Adds a resolution ID to the url parameters.
     * @example .addResolutionID(22) adds 'id=22' to the url parameters.
     * @param id
     */
    addResolutionID(id: number): RequestBuilder;
    /**
     * Add shards to the url parameters after the 'q=' parameter.
     * @example .addShards('flag') adds 'q=Testlandia' to the url.
     * @example .addShards([ 'flag', 'population' ]) adds 'q=flag+population' to the url.
     * @param shards
     */
    addShards(shards: NationPublic | NationPrivate | RegionPublic | World | WorldAssembly | Cards | string | string[]): RequestBuilder;
    /**
     * Appends the given parameters to the url with the defined key and value.
     * @example .addCustomParam('key', 'value') adds 'key=value' to the url.
     * @param key
     * @param value
     */
    addCustomParam(key: string, value: string | number): this;
    /**
     * Removes all shards from the RequestBuilder object and its associated URL.
     * @example new RequestBuilder(api).addShards('numnations').removeShards()
     */
    deleteAllShards(): void;
    /**
     * Enforces the rate-limit by calculating time-to-wait and then waiting for the specified amount of time.
     */
    protected execRateLimit(): Promise<void>;
    /**
     * Executes the request and saves the response to the RequestBuilder object.
     * Retrieve after awaiting it via .response, .body, or convert it to a JS object with convertToJSON();
     * @example const req = await new RequestBuilder(api).addNation('Testlandia').execute()
     */
    execute(): Promise<RequestBuilder>;
    /**
     * ⚠️ Deprecated! Use execute() instead.
     */
    sendRequestAsync(): Promise<void>;
    /**
     * Saves the node-fetch response to the response object within the instance.
     * @param res
     * @protected
     */
    protected logRequest(res: any): Promise<void>;
    toJS(): Promise<RequestBuilder>;
    /**
     * ⚠️ Deprecated! Use execute() instead.
     */
    convertToJSAsync(): Promise<void>;
    /**
     * Resets the url and shards to the default. Protected to allow extending into the NSMethods class.
     * End-users wishing to reset their URL should simply create a new RequestBuilder object instead.
     * @protected
     */
    protected resetURL(): RequestBuilder;
}