clashofclans.js 2.0.0-dev.30ea324 → 2.0.0-dev.3a1efb5

package/dist/rest/HTTPError.d.ts

@@ -1,8 +1,24 @@
 /** Represents an HTTP Error. */
 export declare class HTTPError extends Error {
+    /** The message of this error. */
+    message: string;
+    /** The HTTP method of this request. */
     method: string;
+    /** The reason of this error. */
     reason: string;
+    /** The HTTP status code of this request. */
     status: number;
+    /** The path of this request. */
     path: string;
-    constructor(error: any, status: number, path: string, method?: string);
+    /** Maximum number of milliseconds the results can be cached. */
+    maxAge: number;
+    constructor(error: any, status: number, path: string, maxAge: number, method?: string);
 }
+export declare const NotInWarError: {
+    message: string;
+    reason: string;
+};
+export declare const PrivateWarLogError: {
+    message: string;
+    reason: string;
+};

package/dist/rest/HTTPError.js

@@ -1,23 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HTTPError = void 0;
+exports.PrivateWarLogError = exports.NotInWarError = exports.HTTPError = void 0;
 const messages = {
-    504: 'The user aborted a request.',
-    404: 'Resource was not found.'
+    500: 'Unknown error happened when handling the request.',
+    504: 'The user aborted this request.',
+    404: 'Requested resource was not found.',
+    400: 'Client provided incorrect parameters for the request.',
+    503: 'Service is temporarily unavailable because of maintenance.',
+    429: 'Request was throttled, because amount of requests was above the threshold defined for the used API token.',
+    403: 'Access denied, either because of missing/incorrect credentials or used API token does not grant access to the requested resource.'
 };
 const reasons = {
-    504: 'networkTimeout',
-    404: 'notFound'
+    503: 'serviceUnavailable',
+    429: 'tooManyRequests',
+    400: 'badRequest',
+    403: 'forbidden',
+    500: 'unknownError',
+    404: 'notFound',
+    504: 'requestAborted'
 };
 /** Represents an HTTP Error. */
 class HTTPError extends Error {
-    constructor(error, status, path, method = 'GET') {
+    constructor(error, status, path, maxAge, method) {
         super();
         this.message = error?.message ?? messages[status];
         this.reason = error?.reason ?? reasons[status];
         this.path = path;
-        this.method = method;
+        this.method = method ?? 'GET';
         this.status = status;
+        this.maxAge = maxAge;
     }
 }
 exports.HTTPError = HTTPError;
+exports.NotInWarError = {
+    message: 'Clan is not in war at this moment.',
+    reason: 'notInWar'
+};
+exports.PrivateWarLogError = {
+    message: 'Access denied, clan war log is private.',
+    reason: 'privateWarLog'
+};

package/dist/rest/RESTManager.d.ts

@@ -8,120 +8,144 @@ export declare class RESTManager {
         data: APIClanList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getClan(clanTag: string, options?: OverrideOptions): Promise<{
         data: APIClan;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getClanMembers(clanTag: string, options?: SearchOptions): Promise<{
         data: APIClanMemberList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getClanWarLog(clanTag: string, options?: SearchOptions): Promise<{
         data: APIClanWarLog;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getCurrentWar(clanTag: string, options?: OverrideOptions): Promise<{
         data: APIClanWar;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getClanWarLeagueGroup(clanTag: string, options?: OverrideOptions): Promise<{
         data: APIClanWarLeagueGroup;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getClanWarLeagueRound(warTag: string, options?: OverrideOptions): Promise<{
         data: APIClanWar;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getPlayer(playerTag: string, options?: OverrideOptions): Promise<{
         data: APIPlayer;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     postPlayerToken(playerTag: string, token: string, options?: OverrideOptions): Promise<{
         data: APIVerifyToken;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getLeagues(options?: SearchOptions): Promise<{
         data: APILeagueList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getLeague(leagueId: string | number, options?: OverrideOptions): Promise<{
         data: APILeague;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getLeagueSeasons(leagueId: number, options?: SearchOptions): Promise<{
         data: APILeagueSeasonList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getSeasonRankings(leagueId: number, seasonId: string, options?: SearchOptions): Promise<{
         data: APIPlayerSeasonRankingList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getWarLeagues(options?: SearchOptions): Promise<{
         data: APIWarLeagueList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getWarLeague(leagueId: number, options?: OverrideOptions): Promise<{
         data: APIWarLeague;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getLocations(options?: SearchOptions): Promise<{
         data: APILocationList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getLocation(locationId: number, options?: OverrideOptions): Promise<{
         data: APILocation;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getClanRanks(locationId: number | string, options?: SearchOptions): Promise<{
         data: APIClanRankingList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getPlayerRanks(locationId: number | string, options?: SearchOptions): Promise<{
         data: APIPlayerRankingList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getVersusClanRanks(locationId: number | string, options?: SearchOptions): Promise<{
         data: APIClanVersusRankingList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getVersusPlayerRanks(locationId: number | string, options?: SearchOptions): Promise<{
         data: APIPlayerVersusRankingList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getClanLabels(options?: SearchOptions): Promise<{
         data: APILabelList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getPlayerLabels(options?: SearchOptions): Promise<{
         data: APILabelList;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     getGoldPassSeason(options?: OverrideOptions): Promise<{
         data: APIGoldPassSeason;
         maxAge: number;
         status: number;
+        path: string;
     }>;
 }

package/dist/rest/RequestHandler.d.ts

@@ -1,4 +1,5 @@
 import { QueueThrottler, BatchThrottler } from './Throttler';
+import Keyv from 'keyv';
 /** Represents a Request Handler. */
 export declare class RequestHandler {
     #private;
@@ -6,13 +7,13 @@ export declare class RequestHandler {
     private password;
     private keyCount;
     private keyName;
-    private keyDescription;
+    private keyDescription?;
     private keys;
     private readonly baseURL;
     private readonly retryLimit;
-    private readonly cached;
     private readonly restRequestTimeout;
     private readonly throttler?;
+    private readonly cached;
     constructor(options?: ClientOptions);
     private get _keys();
     private get _key();
@@ -21,54 +22,134 @@ export declare class RequestHandler {
         data: T;
         maxAge: number;
         status: number;
+        path: string;
     }>;
     private exec;
     init(options: InitOptions): Promise<string[]>;
+    private reValidateKeys;
     private login;
     private getKeys;
     private revokeKey;
     private createKey;
     private getIp;
 }
+/** Options for a client. */
 export interface ClientOptions {
+    /** Keys from Clash of Clans API developer site. */
     keys?: string[];
-    cache?: boolean;
+    /** Base URL of the Clash of Clans API. */
     baseURL?: string;
+    /**
+     * How many times to retry on 5XX errors.
+     */
     retryLimit?: number;
+    /**
+     * Whether enable or disable internal caching.
+     * @example
+     * ```ts
+     * const client = new Client({ cache: true });
+     * ```
+     */
+    cache?: boolean | Keyv;
+    /** Time to wait before cancelling a REST request, in milliseconds. */
     restRequestTimeout?: number;
+    /**
+     * Throttler class which handles rate-limit
+     * @example
+     * ```ts
+     * const client = new Client({ throttler: new QueueThrottler(1000 / 10) });
+     * ```
+     * @example
+     * ```ts
+     * const client = new Client({ throttler: new BatchThrottler(30) });
+     * ```
+     */
     throttler?: QueueThrottler | BatchThrottler;
 }
+/** Search options for request. */
 export interface SearchOptions extends OverrideOptions {
+    /** Limit the number of items returned in the response. */
     limit?: number;
+    /**
+     * Return only items that occur after this marker.
+     * Before marker can be found from the response, inside the 'paging' property.
+     * Note that only after or before can be specified for a request, not both.
+     */
     after?: string;
+    /**
+     * Return only items that occur before this marker.
+     * Before marker can be found from the response, inside the 'paging' property.
+     * Note that only after or before can be specified for a request, not both.
+     */
     before?: string;
 }
+/** Override options for a request. */
 export interface OverrideOptions {
+    /** Whether to cache this response. */
+    cache?: boolean;
+    /** Whether to skip the cache check and request the API. */
+    force?: boolean;
+    /** How many times to retry on 5XX errors. */
     retryLimit?: string;
+    /** Whether to ignore throttlers. */
     ignoreRateLimit?: boolean;
+    /** Time to wait before cancelling a REST request, in milliseconds. */
     restRequestTimeout?: number;
 }
 export interface RequestOptions extends OverrideOptions {
     body?: string;
     method?: string;
 }
+/**
+ * Clan search options for a request.
+ *
+ * ::info
+ * If name is used as part of search query, it needs to be at least three characters long.
+ * Name search parameter is interpreted as wild card search, so it may appear anywhere in the clan name.
+ * :::
+ */
 export interface ClanSearchOptions {
+    /** Search clans by name. */
     name?: string;
+    /** Filter by minimum number of clan members. */
     minMembers?: number;
+    /** Filter by maximum number of clan members. */
     maxMembers?: number;
+    /** Filter by minimum amount of clan points. */
     minClanPoints?: number;
+    /** Filter by minimum clan level. */
     minClanLevel?: number;
+    /** Filter by clan war frequency. */
     warFrequency?: string;
+    /** Filter by clan location identifier. For list of available locations, refer to getLocations operation. */
     locationId?: string;
+    /** Comma separated list of label IDs to use for filtering results. */
     labelIds?: string;
+    /** Limit the number of items returned in the response. */
     limit?: number;
+    /**
+     * Return only items that occur after this marker.
+     * Before marker can be found from the response, inside the 'paging' property.
+     * Note that only after or before can be specified for a request, not both.
+     */
     after?: string;
+    /**
+     * Return only items that occur before this marker.
+     * Before marker can be found from the response, inside the 'paging' property.
+     * Note that only after or before can be specified for a request, not both.
+     */
     before?: string;
 }
+/** Login options for a client. */
 export interface InitOptions {
+    /** Developer site email address. */
     email: string;
+    /** Developer site password. */
     password: string;
+    /** Name of API key(s). */
     keyName?: string;
+    /** Number of allowed API keys. */
     keyCount?: number;
+    /** Description of API key(s). */
     keyDescription?: string;
 }

package/dist/rest/RequestHandler.js

@@ -30,8 +30,11 @@ class RequestHandler {
         this.retryLimit = options?.retryLimit ?? 0;
         this.throttler = options?.throttler ?? null;
         this.baseURL = options?.baseURL ?? Constants_1.API_BASE_URL;
-        this.cached = options?.cache ? new keyv_1.default() : null;
         this.restRequestTimeout = options?.restRequestTimeout ?? 0;
+        if (options?.cache instanceof keyv_1.default)
+            this.cached = options.cache;
+        else
+            this.cached = options?.cache ? new keyv_1.default() : null;
     }
     get _keys() {
         return Array.isArray(this.keys) ? this.keys : [this.keys];
@@ -47,8 +50,8 @@ class RequestHandler {
     }
     async request(path, options = {}) {
         const cached = (await this.cached?.get(path)) ?? null;
-        if (cached)
-            return { data: cached, maxAge: 0, status: 200 };
+        if (cached && options.force !== true)
+            return { data: cached.data, maxAge: cached.ttl - Date.now(), status: 200, path };
         if (!this.throttler || options.ignoreRateLimit)
             return this.exec(path, options);
         await this.throttler.wait();
@@ -74,23 +77,41 @@ class RequestHandler {
             await this.login();
             return this.exec(path, options, ++retries);
         }
+        const maxAge = Number(res?.headers.get('cache-control')?.split('=')?.[1] ?? 0) * 1000;
+        if (res?.status === 403 && !data?.message)
+            throw new HTTPError_1.HTTPError(HTTPError_1.PrivateWarLogError, res.status, path, maxAge);
         if (!res?.ok)
-            throw new HTTPError_1.HTTPError(data, res?.status ?? 504, path, options.method);
-        const maxAge = Number(res.headers.get('cache-control')?.split('=')?.[1] ?? 0) * 1000;
-        if (this.cached && maxAge > 0)
-            await this.cached.set(path, data, maxAge);
-        return { data, maxAge, status: res.status };
+            throw new HTTPError_1.HTTPError(data, res?.status ?? 504, path, maxAge, options.method);
+        if (this.cached && maxAge > 0 && options.cache !== false) {
+            await this.cached.set(path, { data, ttl: Date.now() + maxAge }, maxAge);
+        }
+        return { data, maxAge, status: res.status, path };
     }
-    init(options) {
+    async init(options) {
         if (!(options.email && options.password))
             throw ReferenceError('Missing email and password.');
-        this.keyDescription = options.keyDescription ?? new Date().toUTCString();
+        this.keyDescription = options.keyDescription;
         this.keyName = options.keyName ?? 'clashofclans.js.keys';
         this.keyCount = Math.min(options.keyCount ?? 1, 10);
         this.password = options.password;
         this.email = options.email;
+        await this.reValidateKeys();
         return this.login();
     }
+    async reValidateKeys() {
+        for (const key of this.keys) {
+            const res = await (0, node_fetch_1.default)(`${this.baseURL}/locations?limit=1`, {
+                method: 'GET',
+                timeout: 10000,
+                headers: { 'Authorization': `Bearer ${key}`, 'Content-Type': 'application/json' }
+            }).catch(() => null);
+            if (res?.status === 403) {
+                const index = this.keys.indexOf(key);
+                this.keys.splice(index, 1);
+                console.warn(`[WARN] Pre-defined key #${index + 1} is no longer valid. Removed from the key list.`);
+            }
+        }
+    }
     async login() {
         const res = await (0, node_fetch_1.default)(`${Constants_1.DEV_SITE_API_BASE_URL}/login`, {
             method: 'POST',
@@ -112,17 +133,19 @@ class RequestHandler {
         // Get all available keys from the developer site.
         const keys = (data.keys ?? []);
         // Revoke keys for specified key name but not matching current IP address.
-        const expiredKeys = keys.filter((key) => key.name === this.keyName && !key.cidrRanges.includes(ip));
-        for (const key of expiredKeys) {
+        for (const key of keys.filter((key) => key.name === this.keyName && !key.cidrRanges.includes(ip))) {
             if (!(await this.revokeKey(key.id, cookie)))
                 continue;
             const index = keys.findIndex(({ id }) => id === key.id);
             keys.splice(index, 1);
         }
         // Filter keys for current IP address and specified key name.
-        const matching = keys.filter((key) => key.name === this.keyName && key.cidrRanges.includes(ip));
-        if (matching.length)
-            this.keys.push(...matching.map((key) => key.key).slice(0, this.keyCount));
+        for (const key of keys.filter((key) => key.name === this.keyName && key.cidrRanges.includes(ip))) {
+            if (this.keys.length >= this.keyCount)
+                break;
+            if (!this.keys.includes(key.key))
+                this.keys.push(key.key);
+        }
         // Create keys within limits (maximum of 10 keys per account)
         while (this.keys.length < this.keyCount && keys.length < 10) {
             const key = await this.createKey(cookie, ip);
@@ -152,7 +175,11 @@ class RequestHandler {
         const res = await (0, node_fetch_1.default)(`${Constants_1.DEV_SITE_API_BASE_URL}/apikey/create`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', cookie },
-            body: JSON.stringify({ cidrRanges: [ip], name: this.keyName, description: this.keyDescription })
+            body: JSON.stringify({
+                cidrRanges: [ip],
+                name: this.keyName,
+                description: this.keyDescription ?? new Date().toUTCString()
+            })
         });
         const data = await res.json();
         return data.key;

package/dist/rest/Throttler.d.ts

@@ -29,7 +29,3 @@ export declare class BatchThrottler {
     wait(): Promise<void>;
     throttle(): Promise<void>;
 }
-export interface DeferredPromise {
-    resolve(): void;
-    promise: Promise<void>;
-}

package/dist/struct/Clan.d.ts

@@ -1,3 +1,4 @@
+import { OverrideOptions } from '../rest/RequestHandler';
 import { ChatLanguage } from './ChatLanguage';
 import { ClanMember } from './ClanMember';
 import { Client } from '../client/Client';
@@ -59,5 +60,5 @@ export declare class Clan {
     members: ClanMember[];
     constructor(client: Client, data: APIClan);
     /** Get {@link Player} information for every Player in the clan. */
-    fetchMembers(): Promise<Player[]>;
+    fetchMembers(options?: OverrideOptions): Promise<Player[]>;
 }

package/dist/struct/Clan.js

@@ -35,8 +35,8 @@ class Clan {
         this.members = data.memberList?.map((mem) => new ClanMember_1.ClanMember(this.client, mem)) ?? []; // eslint-disable-line
     }
     /** Get {@link Player} information for every Player in the clan. */
-    async fetchMembers() {
-        return (await Promise.allSettled(this.members.map((m) => this.client.getPlayer(m.tag, { ignoreRateLimit: true }))))
+    async fetchMembers(options) {
+        return (await Promise.allSettled(this.members.map((m) => this.client.getPlayer(m.tag, { ...options, ignoreRateLimit: true }))))
             .filter((res) => res.status === 'fulfilled')
             .map((res) => res.value);
     }

package/dist/struct/ClanMember.d.ts

@@ -1,3 +1,4 @@
+import { OverrideOptions } from '../rest/RequestHandler';
 import { Client } from '../client/Client';
 import { APIClanMember } from '../types';
 import { League } from './League';
@@ -27,5 +28,5 @@ export declare class ClanMember {
     received: number;
     constructor(client: Client, data: APIClanMember);
     /** Fetch detailed clan info for the member's clan. */
-    fetch(): Promise<import("./Player").Player>;
+    fetch(options?: OverrideOptions): Promise<import("./Player").Player>;
 }

package/dist/struct/ClanMember.js

@@ -21,8 +21,8 @@ class ClanMember {
         this.received = data.donationsReceived;
     }
     /** Fetch detailed clan info for the member's clan. */
-    async fetch() {
-        return this.client.getPlayer(this.tag);
+    async fetch(options) {
+        return this.client.getPlayer(this.tag, options);
     }
 }
 exports.ClanMember = ClanMember;

package/dist/struct/ClanWar.d.ts

@@ -116,12 +116,12 @@ export declare class ClanWar {
     opponent: WarClan;
     /** The war's unique tag. This is `null` unless this is a CWL.  */
     warTag: string | null;
-    /** The timestamp when a fresh version of this data will be available again. */
+    /** Maximum number of milliseconds the results can be cached. */
     maxAge: number;
     constructor(client: Client, data: APIClanWar, extra: {
         clanTag?: string;
         warTag?: string;
-        maxAge?: number;
+        maxAge: number;
     });
     /** Return a {@link ClanWarMember} with the tag provided. */
     getMember(tag: string): ClanWarMember | null;
@@ -129,7 +129,9 @@ export declare class ClanWar {
     getAttack(attackerTag: string, defenderTag: string): ClanWarAttack | null;
     /** Return a list of {@link ClanWarAttack} for the defenderTag provided. */
     getDefenses(defenderTag: string): ClanWarAttack[];
-    /** Returns either `friendly`, `cwl` or `regular`. */
-    get type(): 'friendly' | 'cwl' | 'regular';
+    /** Returns either `friendly`, `cwl` or `normal`. */
+    get type(): "friendly" | "cwl" | "normal";
     private get _isFriendly();
+    /** Returns the war status, based off the home clan. */
+    get status(): "win" | "lose" | "tie" | "pending";
 }

package/dist/struct/ClanWar.js

@@ -147,7 +147,7 @@ class ClanWar {
         }
         this.clan = new WarClan(this, clan);
         this.opponent = new WarClan(this, opponent);
-        this.maxAge = Date.now() + (extra.maxAge ?? 0);
+        this.maxAge = extra.maxAge;
     }
     /** Return a {@link ClanWarMember} with the tag provided. */
     getMember(tag) {
@@ -168,17 +168,31 @@ class ClanWar {
         }
         return this.opponent.attacks.filter((atk) => atk.defenderTag === defenderTag);
     }
-    /** Returns either `friendly`, `cwl` or `regular`. */
+    /** Returns either `friendly`, `cwl` or `normal`. */
     get type() {
         if (this._isFriendly)
             return 'friendly';
         if (this.warTag)
             return 'cwl';
-        return 'regular';
+        return 'normal';
     }
     get _isFriendly() {
         const preparationTime = this.startTime.getTime() - this.preparationStartTime.getTime();
         return Constants_1.FRIENDLY_WAR_PREPARATION_TIMES.includes(preparationTime);
     }
+    /** Returns the war status, based off the home clan. */
+    get status() {
+        if (this.state === 'preparation')
+            return 'pending';
+        if (this.clan.stars > this.opponent.stars)
+            return 'win';
+        if (this.clan.stars === this.opponent.stars) {
+            if (this.clan.destruction > this.opponent.destruction)
+                return 'win';
+            if (this.clan.destruction === this.opponent.destruction)
+                return 'tie';
+        }
+        return 'lose';
+    }
 }
 exports.ClanWar = ClanWar;

package/dist/struct/ClanWarLeagueGroup.d.ts

@@ -1,4 +1,5 @@
 import { APIClanWarLeagueClan, APIClanWarLeagueClanMember, APIClanWarLeagueGroup, APIClanWarLeagueRound } from '../types';
+import { OverrideOptions } from '../rest/RequestHandler';
 import { Client } from '../client/Client';
 import { ClanWar } from './ClanWar';
 import { Player } from './Player';
@@ -28,7 +29,7 @@ export declare class ClanWarLeagueClan {
     members: ClanWarLeagueClanMember[];
     constructor(client: Client, data: APIClanWarLeagueClan);
     /** Get {@link Player} information for every members that are in the CWL group. */
-    fetchMembers(): Promise<Player[]>;
+    fetchMembers(options?: OverrideOptions): Promise<Player[]>;
 }
 /** Represents a Round of CWL Group. */
 export declare class ClanWarLeagueRound {
@@ -54,7 +55,7 @@ export declare class ClanWarLeagueGroup {
      * This returns an array of {@link ClanWar} which fetches all wars in parallel.
      * @param clanTag Optional clan tag. If present, this will only return wars which belong to this clan.
      */
-    getWars(clanTag?: string): Promise<ClanWar[]>;
+    getWars(clanTag?: string, options?: OverrideOptions): Promise<ClanWar[]>;
     private _getCurrentWars;
     /** Returns # (1-7) of the round for the specified warTag. */
     getRoundIndex(warTag: string): number | null;