clashofclans.js 2.0.0-dev.ba3ae68 → 2.0.0

package/CHANGELOG.md

@@ -2,15 +2,16 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-## 2.0.0
+## 2.0.0 (2021-11-26)
 
 This new version is a complete TypeScript rewrite to convert everything from plain (literal JSON) objects to class (constructor) objects and support a lot more features.
 
 ### Features
 
--   EventManager and Custom Events ([#37](https://github.com/clashperk/clashofclans.js/issues/37)) ([5027ae6](https://github.com/clashperk/clashofclans.js/commit/5027ae663a8e07175e17384c7e5706f4a1a7afb4)) ([984451d](https://github.com/clashperk/clashofclans.js/commit/30ea3240c11866008d0dae514468c0fdbb34ffd0))
--   Internal Caching Options ([#53](https://github.com/clashperk/clashofclans.js/issues/53))
--   Email Password Login ([#31](https://github.com/clashperk/clashofclans.js/issues/31)) ([4153cd3](https://github.com/clashperk/clashofclans.js/commit/4153cd37ea0e1c71550b9e892105b84d5a407e23))
 -   API Date Parser and Request Retries ([#26](https://github.com/clashperk/clashofclans.js/issues/26)) ([94585f3](https://github.com/clashperk/clashofclans.js/commit/94585f3a84a7175b2d07872f9eb9e42372b95e12))
--   Override Request Options ([#36](https://github.com/clashperk/clashofclans.js/issues/36)) ([42d7fdd](https://github.com/clashperk/clashofclans.js/commit/42d7fdd36262cc46f23b731f8cffb9daea19d3b0))
+-   EventManager and Custom Events ([#37](https://github.com/clashperk/clashofclans.js/issues/37)) ([5027ae6](https://github.com/clashperk/clashofclans.js/commit/5027ae663a8e07175e17384c7e5706f4a1a7afb4))
+-   Email Password Login ([#31](https://github.com/clashperk/clashofclans.js/issues/31)) ([4153cd3](https://github.com/clashperk/clashofclans.js/commit/4153cd37ea0e1c71550b9e892105b84d5a407e23))
 -   QueueThrottler and BatchThrottler ([#34](https://github.com/clashperk/clashofclans.js/issues/34)) ([3a8f051](https://github.com/clashperk/clashofclans.js/commit/3a8f051552e93b98f89bc7d524acdecddf242718))
+-   Override Request Options ([#36](https://github.com/clashperk/clashofclans.js/issues/36)) ([42d7fdd](https://github.com/clashperk/clashofclans.js/commit/42d7fdd36262cc46f23b731f8cffb9daea19d3b0))
+-   Internal Caching Options ([#53](https://github.com/clashperk/clashofclans.js/issues/53)) ([984451d](https://github.com/clashperk/clashofclans.js/commit/30ea3240c11866008d0dae514468c0fdbb34ffd0))
+-   Raw Data for Player Units ([#65](https://github.com/clashperk/clashofclans.js/pull/65)) ([aa1696](https://github.com/clashperk/clashofclans.js/commit/aa1696243d96d4fed0250b4282c60522a6482343))

package/README.md

@@ -39,14 +39,14 @@ const client = new Client();
 ```js
 const { Client, BatchThrottler } = require('clashofclans.js');
 const client = new Client({
+    cache: true,
     retryLimit: 1,
-    restRequestTimeout: 3000,
-    throttler: new BatchThrottler(30)
+    restRequestTimeout: 5000,
+    throttler: new BatchThrottler(20)
 });
 
-client.events.addClans(['#8P2QG08P']);
-client.events.setEvent({
-    type: 'CLAN',
+client.events.addClans(['#8QU8J9LP', '#8P2QG08P']);
+client.events.setClanEvent({
     name: 'clanDescriptionChange',
     filter: (oldClan, newClan) => {
         return oldClan.description !== newClan.description;

package/dist/client/Client.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import { ClanSearchOptions, SearchOptions, ClientOptions, InitOptions, OverrideOptions } from '../rest/RequestHandler';
-import { EVENTS } from '../util/Constants';
+import { EVENTS, CWL_ROUNDS } from '../util/Constants';
 import { RESTManager } from '../rest/RESTManager';
 import { EventManager } from './EventManager';
 import { EventEmitter } from 'events';
@@ -21,6 +21,8 @@ export declare class Client extends EventEmitter {
     constructor(options?: ClientOptions);
     /** Contains various general-purpose utility methods. */
     get util(): typeof Util;
+    /** Whether the API is in maintenance break. */
+    get inMaintenance(): boolean;
     /**
      * Initialize the client to create keys.
      * @example
@@ -40,21 +42,47 @@ export declare class Client extends EventEmitter {
     getClanMembers(clanTag: string, options?: SearchOptions): Promise<ClanMember[]>;
     /** Get clan war log. */
     getClanWarLog(clanTag: string, options?: SearchOptions): Promise<ClanWarLog[]>;
-    /** Get info about currently running war (regular or friendly) in the clan. */
-    getClanWar(clanTag: string, options?: OverrideOptions): Promise<ClanWar | null>;
-    /** Get info about currently running war in the clan. */
-    getCurrentWar(clanTag: string, options?: OverrideOptions): Promise<ClanWar | null>;
-    /** Get info about currently running CWL round. */
-    getLeagueWar(clanTag: string, warState?: keyof typeof CWLRound): Promise<ClanWar | null>;
+    /** Get info about currently running war (normal or friendly) in the clan. */
+    getClanWar(clanTag: string, options?: OverrideOptions): Promise<ClanWar>;
+    /**
+     * Get info about currently running war in the clan.
+     * @example
+     * ```ts
+     * await client.getCurrentWar('#8QU8J9LP');
+     * ```
+     * @example
+     * ```ts
+     * await client.getCurrentWar({ clanTag: '#8QU8J9LP', round: 'PREVIOUS_ROUND' });
+     * ```
+     */
+    getCurrentWar(clanTag: string | {
+        clanTag: string;
+        round?: keyof typeof CWL_ROUNDS;
+    }, options?: OverrideOptions): Promise<ClanWar | null>;
+    /**
+     * Get info about currently running CWL round.
+     * @example
+     * ```ts
+     * await client.getLeagueWar('#8QU8J9LP');
+     * ```
+     * @example
+     * ```ts
+     * await client.getLeagueWar({ clanTag: '#8QU8J9LP', round: 'PREVIOUS_ROUND' });
+     * ```
+     */
+    getLeagueWar(clanTag: string | {
+        clanTag: string;
+        round?: keyof typeof CWL_ROUNDS;
+    }, options?: OverrideOptions): Promise<ClanWar | null>;
     private _getCurrentLeagueWars;
     private _getClanWars;
     /** Get information about clan war league. */
     getClanWarLeagueGroup(clanTag: string, options?: OverrideOptions): Promise<ClanWarLeagueGroup>;
-    /** Get information about CWL round by WarTag. */
+    /** Get info about a CWL round by WarTag. */
     getClanWarLeagueRound(warTag: string | {
         warTag: string;
         clanTag?: string;
-    }, options?: OverrideOptions): Promise<ClanWar | null>;
+    }, options?: OverrideOptions): Promise<ClanWar>;
     /** Get information about a player by tag. */
     getPlayer(playerTag: string, options?: OverrideOptions): Promise<Player>;
     /** Verify Player API token that can be found from the Game settings. */
@@ -73,9 +101,9 @@ export declare class Client extends EventEmitter {
     getClanRanks(locationId: number | 'global', options?: SearchOptions): Promise<RankedClan[]>;
     /** Get player rankings for a specific location. */
     getPlayerRanks(locationId: number | 'global', options?: SearchOptions): Promise<RankedPlayer[]>;
-    /** Get clan versus rankings for a specific location */
+    /** Get clan versus rankings for a specific location. */
     getVersusClanRanks(locationId: number | 'global', options?: SearchOptions): Promise<RankedClan[]>;
-    /** Get player versus rankings for a specific location */
+    /** Get player versus rankings for a specific location. */
     getVersusPlayerRanks(locationId: number | 'global', options?: SearchOptions): Promise<RankedPlayer[]>;
     /** Get list of clan labels. */
     getClanLabels(options?: SearchOptions): Promise<Label[]>;
@@ -88,8 +116,8 @@ export declare class Client extends EventEmitter {
      *
      * **Parameters**
      *
-     * | Name | Type | Description |
-     * | :--: | :--: | :---------: |
+     * | Name |   Type   | Description           |
+     * | :--: | :------: | :-------------------: |
      * | `id` | `string` | Id of the new season. |
      * @public
      * @event
@@ -106,8 +134,8 @@ export declare class Client extends EventEmitter {
      *
      * **Parameters**
      *
-     * | Name | Type | Description |
-     * | :--: | :--: | :---------: |
+     * |    Name    |   Type   |                    Description                     |
+     * | :--------: | :------: | :------------------------------------------------: |
      * | `duration` | `number` | Duration of the maintenance break in milliseconds. |
      * @public
      * @event
@@ -115,15 +143,21 @@ export declare class Client extends EventEmitter {
     private static maintenanceEnd;
     /** @internal */
     on<K extends keyof ClientEvents>(event: K, listeners: (...args: ClientEvents[K]) => void): this;
+    /** @internal */
+    on<S extends keyof CustomEvents>(event: Exclude<S, keyof ClientEvents>, listeners: (...args: CustomEvents[S]) => void): this;
     /** @internal */ on<S extends string | symbol>(event: Exclude<S, keyof ClientEvents>, listeners: (...args: any[]) => void): this;
     /** @internal */
     once<K extends keyof ClientEvents>(event: K, listeners: (...args: ClientEvents[K]) => void): this;
+    /** @internal */
+    once<S extends keyof CustomEvents>(event: Exclude<S, keyof ClientEvents>, listeners: (...args: CustomEvents[S]) => void): this;
     /** @internal */ once<S extends string | symbol>(event: Exclude<S, keyof ClientEvents>, listeners: (...args: any[]) => void): this;
     /** @internal */
     emit<K extends keyof ClientEvents>(event: K, ...args: ClientEvents[K]): boolean;
+    /** @internal */
+    emit<S extends keyof CustomEvents>(event: Exclude<S, keyof ClientEvents>, ...args: CustomEvents[S]): this;
     /** @internal */ emit<S extends string | symbol>(event: Exclude<S, keyof ClientEvents>, ...args: any[]): boolean;
 }
-export interface ClientEvents {
+interface ClientEvents {
     [EVENTS.NEW_SEASON_START]: [id: string];
     [EVENTS.MAINTENANCE_START]: [];
     [EVENTS.MAINTENANCE_END]: [duration: number];
@@ -135,13 +169,9 @@ export interface ClientEvents {
     [EVENTS.WAR_LOOP_END]: [];
     [EVENTS.ERROR]: [error: unknown];
 }
-export interface EventTypes {
-    CLAN: [oldClan: Clan, newClan: Clan];
-    PLAYER: [oldPlayer: Player, newPlayer: Player];
-    CLAN_WAR: [oldWar: ClanWar, newWar: ClanWar];
+interface CustomEvents {
+    [key: `clan${string}`]: [oldClan: Clan, newClan: Clan];
+    [key: `war${string}`]: [oldWar: ClanWar, newWar: ClanWar];
+    [key: `player${string}`]: [oldPlayer: Player, newPlayer: Player];
 }
-export declare const CWLRound: {
-    readonly PREVIOUS_WAR: "warEnded";
-    readonly CURRENT_WAR: "inWar";
-    readonly NEXT_WAR: "preparation";
-};
+export {};

package/dist/client/Client.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CWLRound = exports.Client = void 0;
+exports.Client = void 0;
 const Constants_1 = require("../util/Constants");
+const HTTPError_1 = require("../rest/HTTPError");
 const RESTManager_1 = require("../rest/RESTManager");
 const EventManager_1 = require("./EventManager");
-const HTTPError_1 = require("../rest/HTTPError");
 const events_1 = require("events");
 const Util_1 = require("../util/Util");
 const struct_1 = require("../struct");
@@ -25,6 +25,11 @@ class Client extends events_1.EventEmitter {
     get util() {
         return Util_1.Util;
     }
+    /** Whether the API is in maintenance break. */
+    get inMaintenance() {
+        // @ts-expect-error
+        return this.events._inMaintenance;
+    }
     /**
      * Initialize the client to create keys.
      * @example
@@ -62,30 +67,52 @@ class Client extends events_1.EventEmitter {
         const { data } = await this.rest.getClanWarLog(clanTag, options);
         return data.items.map((entry) => new struct_1.ClanWarLog(this, entry));
     }
-    /** Get info about currently running war (regular or friendly) in the clan. */
+    /** Get info about currently running war (normal or friendly) in the clan. */
     async getClanWar(clanTag, options) {
-        const { data, maxAge } = await this.rest.getCurrentWar(clanTag, options);
-        if (data.state === 'notInWar')
-            return null;
+        const { data, maxAge, path, status } = await this.rest.getCurrentWar(clanTag, options);
+        if (data.state === 'notInWar') {
+            throw new HTTPError_1.HTTPError(HTTPError_1.NotInWarError, status, path, maxAge);
+        }
         return new struct_1.ClanWar(this, data, { clanTag, maxAge });
     }
-    /** Get info about currently running war in the clan. */
+    /**
+     * Get info about currently running war in the clan.
+     * @example
+     * ```ts
+     * await client.getCurrentWar('#8QU8J9LP');
+     * ```
+     * @example
+     * ```ts
+     * await client.getCurrentWar({ clanTag: '#8QU8J9LP', round: 'PREVIOUS_ROUND' });
+     * ```
+     */
     async getCurrentWar(clanTag, options) {
+        const args = typeof clanTag === 'string' ? { clanTag } : { clanTag: clanTag.clanTag, round: clanTag.round };
         try {
-            const data = await this.getClanWar(clanTag, options);
-            return data ?? (await this.getLeagueWar(clanTag));
+            return await this.getClanWar(args.clanTag, options);
         }
         catch (e) {
-            if (e instanceof HTTPError_1.HTTPError && e.status === 403) {
-                return this.getLeagueWar(clanTag);
+            if (e instanceof HTTPError_1.HTTPError && [200, 403].includes(e.status)) {
+                return this.getLeagueWar({ clanTag: args.clanTag, round: args.round }, options);
             }
+            throw e;
         }
-        return null;
     }
-    /** Get info about currently running CWL round. */
-    async getLeagueWar(clanTag, warState) {
-        const state = (warState && exports.CWLRound[warState]) ?? 'inWar'; // eslint-disable-line
-        const data = await this.getClanWarLeagueGroup(clanTag);
+    /**
+     * Get info about currently running CWL round.
+     * @example
+     * ```ts
+     * await client.getLeagueWar('#8QU8J9LP');
+     * ```
+     * @example
+     * ```ts
+     * await client.getLeagueWar({ clanTag: '#8QU8J9LP', round: 'PREVIOUS_ROUND' });
+     * ```
+     */
+    async getLeagueWar(clanTag, options) {
+        const args = typeof clanTag === 'string' ? { clanTag } : { clanTag: clanTag.clanTag, round: clanTag.round };
+        const state = (args.round && Constants_1.CWL_ROUNDS[args.round]) ?? 'inWar'; // eslint-disable-line
+        const data = await this.getClanWarLeagueGroup(args.clanTag, options);
         const rounds = data.rounds.filter((round) => !round.warTags.includes('#0'));
         if (!rounds.length)
             return null;
@@ -95,29 +122,30 @@ class Client extends events_1.EventEmitter {
             .map((round) => round.warTags)
             .flat()
             .reverse();
-        const wars = await this.util.allSettled(warTags.map((warTag) => this.getClanWarLeagueRound({ warTag, clanTag }, { ignoreRateLimit: true })));
-        return wars.find((war) => war?.state === state) ?? wars.at(0) ?? null;
+        const wars = await this.util.allSettled(warTags.map((warTag) => this.getClanWarLeagueRound({ warTag, clanTag: args.clanTag }, { ...options, ignoreRateLimit: true })));
+        if (args.round && args.round in Constants_1.CWL_ROUNDS) {
+            return wars.find((war) => war.state === state) ?? null;
+        }
+        return wars.find((war) => war.state === state) ?? wars.at(0) ?? null;
     }
     async _getCurrentLeagueWars(clanTag, options) {
         const data = await this.getClanWarLeagueGroup(clanTag, options);
         // @ts-expect-error
-        return data._getCurrentWars(clanTag);
+        return data._getCurrentWars(clanTag, options);
     }
     async _getClanWars(clanTag, options) {
-        const date = new Date().getDate();
+        const date = new Date().getUTCDate();
+        if (!(date >= 1 && date <= 10)) {
+            return [await this.getClanWar(clanTag, options)];
+        }
         try {
-            const data = await this.getClanWar(clanTag, options);
-            if (!(date >= 1 && date <= 10))
-                return data ? [data] : [];
-            return data ? [data] : await this._getCurrentLeagueWars(clanTag);
+            return this._getCurrentLeagueWars(clanTag, options);
         }
         catch (e) {
-            if (!(date >= 1 && date <= 10))
-                return [];
-            if (e instanceof HTTPError_1.HTTPError && e.status === 403) {
-                return this._getCurrentLeagueWars(clanTag);
+            if (e instanceof HTTPError_1.HTTPError && [404].includes(e.status)) {
+                return [await this.getClanWar(clanTag, options)];
             }
-            return [];
+            throw e;
         }
     }
     /** Get information about clan war league. */
@@ -125,12 +153,13 @@ class Client extends events_1.EventEmitter {
         const { data } = await this.rest.getClanWarLeagueGroup(clanTag, options);
         return new struct_1.ClanWarLeagueGroup(this, data);
     }
-    /** Get information about CWL round by WarTag. */
+    /** Get info about a CWL round by WarTag. */
     async getClanWarLeagueRound(warTag, options) {
         const args = typeof warTag === 'string' ? { warTag } : { warTag: warTag.warTag, clanTag: warTag.clanTag };
-        const { data, maxAge } = await this.rest.getClanWarLeagueRound(args.warTag, options);
-        if (data.state === 'notInWar')
-            return null;
+        const { data, maxAge, status, path } = await this.rest.getClanWarLeagueRound(args.warTag, options);
+        if (data.state === 'notInWar') {
+            throw new HTTPError_1.HTTPError(HTTPError_1.NotInWarError, status, path, maxAge);
+        }
         return new struct_1.ClanWar(this, data, { warTag: args.warTag, clanTag: args.clanTag, maxAge });
     }
     /** Get information about a player by tag. */
@@ -140,7 +169,7 @@ class Client extends events_1.EventEmitter {
     }
     /** Verify Player API token that can be found from the Game settings. */
     async verifyPlayerToken(playerTag, token, options) {
-        const { data } = await this.rest.postPlayerToken(playerTag, token, options);
+        const { data } = await this.rest.verifyPlayerToken(playerTag, token, options);
         return data.status === 'ok';
     }
     /** Get list of Leagues. */
@@ -179,12 +208,12 @@ class Client extends events_1.EventEmitter {
         const { data } = await this.rest.getPlayerRanks(locationId, options);
         return data.items.map((entry) => new struct_1.RankedPlayer(this, entry));
     }
-    /** Get clan versus rankings for a specific location */
+    /** Get clan versus rankings for a specific location. */
     async getVersusClanRanks(locationId, options) {
         const { data } = await this.rest.getVersusClanRanks(locationId, options);
         return data.items.map((entry) => new struct_1.RankedClan(entry));
     }
-    /** Get player versus rankings for a specific location */
+    /** Get player versus rankings for a specific location. */
     async getVersusPlayerRanks(locationId, options) {
         const { data } = await this.rest.getVersusPlayerRanks(locationId, options);
         return data.items.map((entry) => new struct_1.RankedPlayer(this, entry));
@@ -206,8 +235,3 @@ class Client extends events_1.EventEmitter {
     }
 }
 exports.Client = Client;
-exports.CWLRound = {
-    PREVIOUS_WAR: 'warEnded',
-    CURRENT_WAR: 'inWar',
-    NEXT_WAR: 'preparation'
-};

package/dist/client/EventManager.d.ts

@@ -1,5 +1,6 @@
-import { EventTypes, Client } from './Client';
-/** Represents Event Manager of the {@link Client} class. */
+import { Clan, ClanWar, Player } from '../struct';
+import { Client } from './Client';
+/** Represents Event Manager of the {@link Client}. */
 export declare class EventManager {
     private readonly client;
     private readonly _clanTags;
@@ -13,25 +14,29 @@ export declare class EventManager {
     private _maintenanceStartTime;
     constructor(client: Client);
     /** Initialize the Event Manager to start pulling. */
-    init(): Promise<(string | symbol)[]>;
-    addClans(...tags: string[]): this;
-    deleteClans(...tags: string[]): this;
-    addPlayers(...tags: string[]): this;
-    deletePlayers(...tags: string[]): this;
-    addWars(...tags: string[]): this;
-    deleteWars(...tags: string[]): this;
+    init(): Promise<string[]>;
+    /** Add clan tags to clan events. */
+    addClans(tags: string[] | string): this;
+    /** Delete clan tags from clan events. */
+    deleteClans(tags: string[] | string): this;
+    /** Add player tags for player events. */
+    addPlayers(tags: string[] | string): this;
+    /** Delete player tags from player events. */
+    deletePlayers(tags: string[] | string): this;
+    /** Add clan tags for war events. */
+    addWars(tags: string[] | string): this;
+    /** Delete clan tags from war events. */
+    deleteWars(tags: string[] | string): this;
     /**
-     * Set your own custom event.
-     * @param event.type - `CLAN` | `PLAYER` | `CLAN_WAR`
-     * @param event.name - Name of the event.
-     * @param event.filter - Filter of this event. Must return a boolean value.
+     * Set your own custom clan event.
+     *
+     * In order to emit the custom event, you must have this filter function that returns a boolean.
      *
      * @example
      * ```js
-     * client.events.addClans(['#2PP', '']);
+     * client.events.addClans(['#2PP', '#8QU8J9LP']);
      *
-     * client.events.setEvent({
-     *   type: 'CLAN',
+     * client.events.setClanEvent({
      *   name: 'clanMemberUpdate',
      *   filter: (oldClan, newClan) => {
      *     return oldClan.memberCount !== newClan.memberCount;
@@ -40,14 +45,35 @@ export declare class EventManager {
      *
      * client.on('clanMemberUpdate', (oldClan, newClan) => {
      *   console.log(oldClan.memberCount, newClan.memberCount);
-     * })
+     * });
+     *
+     * (async function () {
+     *   await client.events.init();
+     * })();
      * ```
      * @returns
      */
-    setEvent<K extends keyof EventTypes>(event: {
-        type: K;
+    setClanEvent(event: {
+        name: string;
+        filter: (oldClan: Clan, newClan: Clan) => boolean;
+    }): this;
+    /**
+     * Set your own custom war event.
+     *
+     * In order to emit the custom event, you must have this filter function that returns a boolean.
+     */
+    setWarEvent(event: {
+        name: string;
+        filter: (oldWar: ClanWar, newWar: ClanWar) => boolean;
+    }): this;
+    /**
+     * Set your own custom player event.
+     *
+     * In order to emit the custom event, you must have this filter function that returns a boolean.
+     */
+    setPlayerEvent(event: {
         name: string;
-        filter: (...args: EventTypes[K]) => boolean;
+        filter: (oldPlayer: Player, newPlayer: Player) => boolean;
     }): this;
     private maintenanceHandler;
     private seasonEndHandler;