pw-js-api/cm/api/PWApiClient.d.ts

A PixelWalker Library, aims to be minimal with support for browsers.

import PWGameClient from "../game/PWGameClient.js";
import type { APIFailure, AuthResultSuccess, CollectionResult, ColUser, ColQuery, ColWorld, JoinKeyResult, ListBlockResult, LobbyResult, ApiClientOptions } from "../types/api.js";
import type { GameClientSettings, WorldJoinData } from "../types/game.js";
/**
 * Note if you want to join a world, use new PWGameClient() then run .init()
 */
export default class PWApiClient {
    /**
     * The account token, this is private to prevent tampering.
     */
    private token?;
    /**
     * Account details with email and password, if applicable.
     */
    private account;
    options: ApiClientOptions;
    loggedIn: boolean;
    /**
     * This will be undefined if getListBlocks() hasn't been run once.
     *
     * (This is sorted by ID)
     */
    static listBlocks: ListBlockResult[] | undefined;
    /**
     * This will be undefined if getListBlocks() hasn't been run once.
     *
     * NOTE: The keys are in UPPER_CASE form.
     */
    static listBlocksObj: Record<string, ListBlockResult> | undefined;
    /**
     * This will create an instance of the class, as you're using the token, it will automatically be marked as loggedIn.
     * @param token Must be a valid account token.
     */
    constructor(token: string, options?: ApiClientOptions);
    /**
     * This will create an instance of the class, as you're putting the account details, you must manually authenticate before invoking restricted calls including joinRoom.
     * If populating email and password, you must manually authenticate yourself.
     */
    constructor(email: string, password: string, options?: ApiClientOptions);
    /**
     * Connects the API instance to the server.
     * This will enable the client to join the room, or access to restricted collections.
     */
    authenticate(): Promise<AuthResultSuccess | APIFailure>;
    /**
     * Overrides local account details, the parameters are not needed if PW Api was already created with email/password in the first place.
     * This is for those that used a token in the first place, the accounts won't be saved in the instance.
     */
    authenticate(email: string, password: string): Promise<AuthResultSuccess | APIFailure>;
    /**
     * Internal.
     */
    getJoinKey(roomType: string, roomId: string): Promise<JoinKeyResult>;
    /**
     * This route is available to take if you chose to create an API client to then join a world, in which case this returns the Game Client instance.
     *
     * Make sure the API client is already authenticated before calling this.
     *
     * The 3rd parameter is for if you wish to customise the reconnectability of the game client.
     */
    joinWorld(roomId: string, obj?: {
        joinData?: WorldJoinData;
        gameSettings?: Partial<GameClientSettings>;
    }): Promise<PWGameClient<{}>>;
    /**
     * This will be an empty array if getRoomTypes has never been used successfully at least once.
     */
    static roomTypes: string[];
    /**
     * This will be an empty array if getRoomTypes has never been used successfully at least once.
     */
    get roomTypes(): string[];
    /**
     * Non-authenticated. This will refresh the room types each time, so make sure to check if roomTypes is available.
     */
    getRoomTypes(): Promise<string[]>;
    /**
     * Non-authenticated. This will refresh the room types each time, so make sure to check if roomTypes is available.
     */
    static getRoomTypes(EndpointURL?: string): Promise<string[]>;
    /**
     * Non-authenticated. Returns the mappings from the game API.
     *
     * Note: This library also exports "BlockNames" which is an enum containing the block names along with their respective id.
     *
     * @deprecated Use getListBlocks()
     */
    getMappings(): Promise<Record<string, number>>;
    /**
     * Non-authenticated. Returns the mappings from the game API.
     *
     * Note: This library also exports "BlockNames" which is an enum containing the block names along with their respective id.
     *
     * @deprecated Use getListBlocks()
     */
    static getMappings(): Promise<Record<string, number>>;
    /**
     * Non-authenticated. Returns the mappings from the game API.
     *
     * This will fetch for the first time if it hasn't been used, hence asynchronous. You can use listBlocks property if it exists and if you wish to avoid potentially using async.
     * After that, it will return a list or object if specified.
     *
     * This is automatically invoked when getRoomTypes() is invoked to clear cache.
     *
     * Note: This library also exports "BlockNames" which is an enum containing the block names along with their respective id.     *
     */
    getListBlocks(skipCache: boolean | undefined, toObject: true): Promise<Record<string, ListBlockResult>>;
    getListBlocks(skipCache?: boolean, toObject?: false): Promise<ListBlockResult[]>;
    /**
     * Non-authenticated. Returns the list blocks from the game API.
     *
     * This will fetch for the first time if it hasn't been used, hence asynchronous. You can use listBlocks property if it exists and if you wish to avoid potentially using async.
     * After that, it will return a list or object if specified.
     *
     * This is automatically invoked when getRoomTypes() is invoked to clear cache.
     *
     * Note: This library also exports "BlockNames" which is an enum containing the block names along with their respective id.
     */
    static getListBlocks(skipCache: boolean | undefined, toObject: true, EndpointURL?: string): Promise<Record<string, ListBlockResult>>;
    static getListBlocks(skipCache?: boolean, toObject?: false, EndpointURL?: string): Promise<ListBlockResult[]>;
    /**
     * Returns the collection result of the query - your own worlds.
     * Default: page - 1, perPage - 10
     */
    getOwnedWorlds(page: number, perPage: number, query?: ColQuery<ColWorld>): Promise<CollectionResult<ColWorld>>;
    getOwnedWorlds(query: ColQuery<ColWorld>): Promise<CollectionResult<ColWorld>>;
    /**
     * Returns the collection result of the query - players.
     * Default: page - 1, perPage - 10
     */
    getPlayers(page: number, perPage: number, query?: ColQuery<ColUser>): Promise<CollectionResult<ColUser>>;
    getPlayers(query: ColQuery<ColUser>): Promise<CollectionResult<ColUser>>;
    /**
     * Returns the collection result of the query - players.
     * Default: page - 1, perPage - 10
     */
    static getPlayers(page?: number, perPage?: number, query?: ColQuery<ColUser>, EndpointURL?: string): Promise<CollectionResult<ColUser>>;
    static getPlayers(query: ColQuery<ColUser>, EndpointURL?: string): Promise<CollectionResult<ColUser>>;
    /**
     * Returns the collection result of the query - public worlds.
     * Default: page - 1, perPage - 10
     */
    getPublicWorlds(page: number, perPage: number, query?: ColQuery<ColWorld>): Promise<CollectionResult<ColWorld>>;
    getPublicWorlds(query: ColQuery<ColWorld>): Promise<CollectionResult<ColWorld>>;
    /**
     * Returns the collection result of the query - public worlds.
     * Default: page - 1, perPage - 10
     */
    static getPublicWorlds(page?: number, perPage?: number, query?: ColQuery<ColWorld>, EndpointURL?: string): Promise<CollectionResult<ColWorld>>;
    static getPublicWorlds(query: ColQuery<ColWorld>, EndpointURL?: string): Promise<CollectionResult<ColWorld>>;
    /**
     * Returns the collection result of the query - public worlds.
     * Default: page - 1, perPage - 10
     */
    getWootedWorlds(page: number, perPage: number, query?: ColQuery<ColWorld>): Promise<CollectionResult<ColWorld>>;
    getWootedWorlds(query: ColQuery<ColWorld>): Promise<CollectionResult<ColWorld>>;
    /**
     * NOTE: It will always return empty result if not authenticated.
     *
     * Returns the collection result of the query - wooted worlds.
     * Default: page - 1, perPage - 10
     */
    static getWootedWorlds(page?: number, perPage?: number, query?: ColQuery<ColWorld>, EndpointURL?: string): Promise<CollectionResult<ColWorld>>;
    static getWootedWorlds(query: ColQuery<ColWorld>, EndpointURL?: string): Promise<CollectionResult<ColWorld>>;
    /**
     * Returns the lobby result.
     */
    getVisibleWorlds(): Promise<LobbyResult>;
    /**
     * Returns the lobby result.
     */
    static getVisibleWorlds(EndpointURL?: string): Promise<LobbyResult>;
    /**
     * Returns the world, if it exists and is public.
     */
    getPublicWorld(id: string): Promise<ColWorld | undefined>;
    /**
     * Returns the world, if it exists and is public.
     */
    static getPublicWorld(id: string): Promise<ColWorld | undefined>;
    /**
     * Gets the raw minimap bytes, the format may differ depending on the environment (Bun, NodeJS, Browser etc).
     */
    getMinimap(world: ColWorld | {
        id: string;
        minimap: string;
    }, toURL?: false): Promise<ArrayBuffer>;
    /**
     * Gives the URL pointing to the minimap image.
     */
    getMinimap(world: ColWorld | {
        id: string;
        minimap: string;
    }, toURL: true): string;
    /**
     * Gets the raw minimap bytes, the format may differ depending on the environment (Bun, NodeJS, Browser etc).
     */
    static getMinimap(world: ColWorld | {
        id: string;
        minimap: string;
    }, toURL?: false, EndpointURL?: string): Promise<ArrayBuffer>;
    /**
     * Gives the URL pointing to the minimap image.
     */
    static getMinimap(world: ColWorld | {
        id: string;
        minimap: string;
    }, toURL: true, EndpointURL?: string): string;
    /**
     * Note that username is cap sensitive, and may require you to use toUppercase
     */
    getPlayerByName(username: string): Promise<ColUser | undefined>;
    /**
     * Note that username is cap sensitive, and may require you to use toUppercase
     */
    static getPlayerByName(username: string): Promise<ColUser | undefined>;
    /**
     * IMPORTANT: This will return JSON for any responses that have the content-type of json, anything else will be sent back as ArrayBuffer.
     * If you're expecting raw bytes, make sure the endpoint is guaranteed to give you that otherwise there isn't a reason.
     *
     * This requires the manager to be authenticated, it will error if otherwise.
     * @param url Requires to be a full URL with endpoint unfortunately. It will throw error if it doesn't match any of the 2 HTTP endpoint URLs.
     * @param body If this is passed, the request will become a POST. (If you need to send a POST but has no data, just send an empty object).
     * @param token The API token (not join key), this is if you wish to use authenticated API calls without having to instantise an api client yourself.
     * @param overrideURL If true, this will skip checking if the URL truly belongs to PW (production wise).
     */
    static request<T>(url: string, body?: Record<string, any> | string, token?: string, overrideURL?: boolean): Promise<T>;
    /**
     * IMPORTANT: This will return JSON for any responses that have the content-type of json, anything else will be sent back as Uint8array.
     * If you're expecting raw bytes, make sure the endpoint is guaranteed to give you that otherwise there isn't a reason.
     *
     * This requires the manager to be authenticated, it will error if otherwise.
     * @param url Requires to be a full URL with endpoint unfortunately. It will throw error if it doesn't match any of the 2 HTTP endpoint URLs.
     * @param body If this is passed, the request will become a POST. (If you need to send a POST but has no data, just send an empty object).
     * @param isAuthenticated If true, this will send the token as the header.
     * @param overrideURL If true, this will skip checking if the URL truly belongs to PW (production wise).
     */
    protected request<T>(url: string, body?: Record<string, any> | string, isAuthenticated?: boolean, overrideURL?: boolean): Promise<T>;
}