@yaelouuu/fortnite-api 4.1.0 → 4.3.0

package/dist/resources/quests.d.ts

@@ -1,14 +1,53 @@
 import { FortniteAPI } from "../client";
 import { QuestsResponse } from "../types";
+/**
+ * QuestsResource provides access to Fortnite quests and account progression data
+ *
+ * This resource allows you to fetch player quest progress, XP, playtime, and account level.
+ * All methods require the user's personal Fortnite OAuth token obtained through the OAuth flow.
+ *
+ * @example
+ * ```typescript
+ * // Get quests for an account
+ * const quests = await client.quests.getQuests(
+ *   "account-id-here",
+ *   "user-fortnite-token-here"
+ * );
+ * ```
+ */
 export declare class QuestsResource {
     private client;
     constructor(client: FortniteAPI);
     /**
      * Get account quests and level information
-     * Requires user's own Fortnite token
-     * @param accountId - Epic Games Account ID
-     * @param fortniteToken - User's Fortnite access token (from OAuth flow)
-     * @returns Quest progress, XP, playtime, and account level data
+     *
+     * Retrieves comprehensive quest data including:
+     * - Active quest progress and completion status
+     * - Account XP and level information
+     * - Total playtime statistics
+     * - Quest rewards and milestones
+     *
+     * **Authentication**: Requires user's personal Fortnite OAuth token
+     *
+     * **API Version**: v3
+     *
+     * **Rate Limit**: Standard API rate limits apply
+     *
+     * @param accountId - Epic Games Account ID (32 character hexadecimal string)
+     * @param fortniteToken - User's Fortnite access token obtained from OAuth flow
+     *
+     * @returns Promise resolving to quest progress, XP, playtime, and account level data
+     *
+     * @throws {FortniteAPIError} When the request fails (invalid token, account not found, etc.)
+     *
+     * @example
+     * ```typescript
+     * const accountId = "a1b2c3d4e5f6..."; // 32 character account ID
+     * const token = "eg1~..."; // User's Fortnite OAuth token
+     *
+     * const questData = await client.quests.getQuests(accountId, token);
+     * console.log(questData);
+     * ```
      */
     getQuests(accountId: string, fortniteToken: string): Promise<QuestsResponse>;
 }

package/dist/resources/quests.js

@@ -1,16 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QuestsResource = void 0;
+/**
+ * QuestsResource provides access to Fortnite quests and account progression data
+ *
+ * This resource allows you to fetch player quest progress, XP, playtime, and account level.
+ * All methods require the user's personal Fortnite OAuth token obtained through the OAuth flow.
+ *
+ * @example
+ * ```typescript
+ * // Get quests for an account
+ * const quests = await client.quests.getQuests(
+ *   "account-id-here",
+ *   "user-fortnite-token-here"
+ * );
+ * ```
+ */
 class QuestsResource {
     constructor(client) {
         this.client = client;
     }
     /**
      * Get account quests and level information
-     * Requires user's own Fortnite token
-     * @param accountId - Epic Games Account ID
-     * @param fortniteToken - User's Fortnite access token (from OAuth flow)
-     * @returns Quest progress, XP, playtime, and account level data
+     *
+     * Retrieves comprehensive quest data including:
+     * - Active quest progress and completion status
+     * - Account XP and level information
+     * - Total playtime statistics
+     * - Quest rewards and milestones
+     *
+     * **Authentication**: Requires user's personal Fortnite OAuth token
+     *
+     * **API Version**: v3
+     *
+     * **Rate Limit**: Standard API rate limits apply
+     *
+     * @param accountId - Epic Games Account ID (32 character hexadecimal string)
+     * @param fortniteToken - User's Fortnite access token obtained from OAuth flow
+     *
+     * @returns Promise resolving to quest progress, XP, playtime, and account level data
+     *
+     * @throws {FortniteAPIError} When the request fails (invalid token, account not found, etc.)
+     *
+     * @example
+     * ```typescript
+     * const accountId = "a1b2c3d4e5f6..."; // 32 character account ID
+     * const token = "eg1~..."; // User's Fortnite OAuth token
+     *
+     * const questData = await client.quests.getQuests(accountId, token);
+     * console.log(questData);
+     * ```
      */
     async getQuests(accountId, fortniteToken) {
         return this.client.request(`/quests/${accountId}`, {

package/dist/resources/stats.d.ts

@@ -0,0 +1,40 @@
+import { FortniteAPI } from "../client";
+import { PlayerStats, BulkStatsResponse, LeaderboardResponse, LeaderboardOptions } from "../types";
+/**
+ * Stats Resource
+ * Handles player statistics queries
+ */
+export declare class StatsResource {
+    private client;
+    constructor(client: FortniteAPI);
+    /**
+     * Get player stats with optional filters
+     * @param accountId - Account ID
+     * @param options - Query options
+     * @param fortniteToken - Optional user Fortnite token
+     * @returns Player statistics
+     */
+    getPlayerStats(accountId: string, options?: {
+        startDate?: string;
+        endDate?: string;
+        stats?: string[];
+    }, fortniteToken?: string): Promise<PlayerStats>;
+    /**
+     * Get bulk stats for multiple players
+     * @param accountIds - Array of account IDs (max 100)
+     * @param options - Query options
+     * @param fortniteToken - Optional user Fortnite token
+     * @returns Array of player statistics
+     */
+    getBulkStats(accountIds: string[], options?: {
+        stats?: string[];
+    }, fortniteToken?: string): Promise<BulkStatsResponse[]>;
+    /**
+     * Get leaderboard for specific stat
+     * @param stat - Stat name to query
+     * @param options - Query options
+     * @param fortniteToken - Optional user Fortnite token
+     * @returns Leaderboard data
+     */
+    getLeaderboard(stat: string, options?: LeaderboardOptions, fortniteToken?: string): Promise<LeaderboardResponse>;
+}

package/dist/resources/stats.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatsResource = void 0;
+/**
+ * Stats Resource
+ * Handles player statistics queries
+ */
+class StatsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get player stats with optional filters
+     * @param accountId - Account ID
+     * @param options - Query options
+     * @param fortniteToken - Optional user Fortnite token
+     * @returns Player statistics
+     */
+    async getPlayerStats(accountId, options, fortniteToken) {
+        const headers = {};
+        if (fortniteToken) {
+            headers["x-fortnite-token"] = fortniteToken;
+        }
+        const queryParams = new URLSearchParams();
+        if (options?.startDate)
+            queryParams.append("startDate", options.startDate);
+        if (options?.endDate)
+            queryParams.append("endDate", options.endDate);
+        if (options?.stats)
+            queryParams.append("stats", options.stats.join(","));
+        const query = queryParams.toString();
+        const url = `/stats/${accountId}${query ? `?${query}` : ""}`;
+        return this.client.request(url, { headers }, "v2");
+    }
+    /**
+     * Get bulk stats for multiple players
+     * @param accountIds - Array of account IDs (max 100)
+     * @param options - Query options
+     * @param fortniteToken - Optional user Fortnite token
+     * @returns Array of player statistics
+     */
+    async getBulkStats(accountIds, options, fortniteToken) {
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (fortniteToken) {
+            headers["x-fortnite-token"] = fortniteToken;
+        }
+        const body = {
+            accountIds,
+        };
+        if (options?.stats) {
+            body.stats = options.stats;
+        }
+        return this.client.request("/stats/bulk", {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        }, "v2");
+    }
+    /**
+     * Get leaderboard for specific stat
+     * @param stat - Stat name to query
+     * @param options - Query options
+     * @param fortniteToken - Optional user Fortnite token
+     * @returns Leaderboard data
+     */
+    async getLeaderboard(stat, options, fortniteToken) {
+        const headers = {};
+        if (fortniteToken) {
+            headers["x-fortnite-token"] = fortniteToken;
+        }
+        const queryParams = new URLSearchParams();
+        if (options?.limit)
+            queryParams.append("limit", options.limit.toString());
+        if (options?.offset)
+            queryParams.append("offset", options.offset.toString());
+        if (options?.window)
+            queryParams.append("window", options.window);
+        const query = queryParams.toString();
+        const url = `/stats/leaderboard/${stat}${query ? `?${query}` : ""}`;
+        return this.client.request(url, { headers }, "v2");
+    }
+}
+exports.StatsResource = StatsResource;

package/dist/resources/tournaments.d.ts

@@ -68,11 +68,73 @@ export declare class TournamentsResource {
     }): Promise<TournamentEligibilityResponse>;
     /**
      * Get tournament leaderboard using V2 endpoint (POST with teams body)
-     * @param params.eventId - Event ID
-     * @param params.eventWindowId - Event window ID
-     * @param params.leaderboardDef - Optional leaderboard definition (required for Ranked Cups)
-     * @param teams - Array of team member account ID arrays (e.g., [["accountId1"], ["accountId2"]])
-     * @param fortniteToken - Optional user's Fortnite token for personalized view
+     *
+     * This is an enhanced version of the leaderboard endpoint that accepts a POST request
+     * with a teams array in the body. Use this endpoint when you need to query leaderboard
+     * data for multiple teams at once or for Ranked Cups that require specific team lookups.
+     *
+     * **Differences from V1**:
+     * - Uses POST method instead of GET
+     * - Accepts teams array in request body
+     * - Better suited for bulk team queries
+     * - Required for certain Ranked Cup leaderboards
+     *
+     * **Authentication**: Optional. Include fortniteToken for personalized leaderboard views
+     *
+     * **API Version**: v2
+     *
+     * **Rate Limit**: Standard API rate limits apply
+     *
+     * @param params - Leaderboard query parameters
+     * @param params.eventId - Event ID (e.g., "epicgames_S37_BlitzCupsAllPlatforms_BR")
+     * @param params.eventWindowId - Event window ID (e.g., "S37_BlitzCupsAllPlatforms_Event1_BR")
+     * @param params.leaderboardDef - Optional leaderboard definition ID (required for Ranked Cups with multiple leaderboards)
+     * @param teams - Array of team member account ID arrays. Each team is an array of account IDs.
+     *                For solo events: [["accountId1"], ["accountId2"]]
+     *                For duo events: [["player1Id", "player2Id"], ["player3Id", "player4Id"]]
+     * @param fortniteToken - Optional user's Fortnite access token for personalized leaderboard view
+     *
+     * @returns Promise resolving to leaderboard data with entries, ranks, and stats
+     *
+     * @throws {FortniteAPIError} When the request fails (invalid event, missing leaderboardDef, etc.)
+     *
+     * @example
+     * ```typescript
+     * // Get leaderboard for multiple solo players
+     * const leaderboard = await client.tournaments.getLeaderboardV2(
+     *   {
+     *     eventId: "epicgames_S37_BlitzCupsAllPlatforms_BR",
+     *     eventWindowId: "S37_BlitzCupsAllPlatforms_Event1_BR"
+     *   },
+     *   [
+     *     ["accountId1"],
+     *     ["accountId2"],
+     *     ["accountId3"]
+     *   ]
+     * );
+     *
+     * // For duo tournament
+     * const duoLeaderboard = await client.tournaments.getLeaderboardV2(
+     *   {
+     *     eventId: "epicgames_S37_DuoCup_BR",
+     *     eventWindowId: "S37_DuoCup_Event1_BR"
+     *   },
+     *   [
+     *     ["player1Id", "player2Id"],
+     *     ["player3Id", "player4Id"]
+     *   ]
+     * );
+     *
+     * // For Ranked Cup with leaderboardDef
+     * const rankedLeaderboard = await client.tournaments.getLeaderboardV2(
+     *   {
+     *     eventId: "epicgames_S37_RankedCup_BR",
+     *     eventWindowId: "S37_RankedCup_Event1_BR",
+     *     leaderboardDef: "ranked_br_division_7"
+     *   },
+     *   [["accountId1"], ["accountId2"]]
+     * );
+     * ```
      */
     getLeaderboardV2(params: {
         eventId: string;

package/dist/resources/tournaments.js

@@ -114,11 +114,73 @@ class TournamentsResource {
     }
     /**
      * Get tournament leaderboard using V2 endpoint (POST with teams body)
-     * @param params.eventId - Event ID
-     * @param params.eventWindowId - Event window ID
-     * @param params.leaderboardDef - Optional leaderboard definition (required for Ranked Cups)
-     * @param teams - Array of team member account ID arrays (e.g., [["accountId1"], ["accountId2"]])
-     * @param fortniteToken - Optional user's Fortnite token for personalized view
+     *
+     * This is an enhanced version of the leaderboard endpoint that accepts a POST request
+     * with a teams array in the body. Use this endpoint when you need to query leaderboard
+     * data for multiple teams at once or for Ranked Cups that require specific team lookups.
+     *
+     * **Differences from V1**:
+     * - Uses POST method instead of GET
+     * - Accepts teams array in request body
+     * - Better suited for bulk team queries
+     * - Required for certain Ranked Cup leaderboards
+     *
+     * **Authentication**: Optional. Include fortniteToken for personalized leaderboard views
+     *
+     * **API Version**: v2
+     *
+     * **Rate Limit**: Standard API rate limits apply
+     *
+     * @param params - Leaderboard query parameters
+     * @param params.eventId - Event ID (e.g., "epicgames_S37_BlitzCupsAllPlatforms_BR")
+     * @param params.eventWindowId - Event window ID (e.g., "S37_BlitzCupsAllPlatforms_Event1_BR")
+     * @param params.leaderboardDef - Optional leaderboard definition ID (required for Ranked Cups with multiple leaderboards)
+     * @param teams - Array of team member account ID arrays. Each team is an array of account IDs.
+     *                For solo events: [["accountId1"], ["accountId2"]]
+     *                For duo events: [["player1Id", "player2Id"], ["player3Id", "player4Id"]]
+     * @param fortniteToken - Optional user's Fortnite access token for personalized leaderboard view
+     *
+     * @returns Promise resolving to leaderboard data with entries, ranks, and stats
+     *
+     * @throws {FortniteAPIError} When the request fails (invalid event, missing leaderboardDef, etc.)
+     *
+     * @example
+     * ```typescript
+     * // Get leaderboard for multiple solo players
+     * const leaderboard = await client.tournaments.getLeaderboardV2(
+     *   {
+     *     eventId: "epicgames_S37_BlitzCupsAllPlatforms_BR",
+     *     eventWindowId: "S37_BlitzCupsAllPlatforms_Event1_BR"
+     *   },
+     *   [
+     *     ["accountId1"],
+     *     ["accountId2"],
+     *     ["accountId3"]
+     *   ]
+     * );
+     *
+     * // For duo tournament
+     * const duoLeaderboard = await client.tournaments.getLeaderboardV2(
+     *   {
+     *     eventId: "epicgames_S37_DuoCup_BR",
+     *     eventWindowId: "S37_DuoCup_Event1_BR"
+     *   },
+     *   [
+     *     ["player1Id", "player2Id"],
+     *     ["player3Id", "player4Id"]
+     *   ]
+     * );
+     *
+     * // For Ranked Cup with leaderboardDef
+     * const rankedLeaderboard = await client.tournaments.getLeaderboardV2(
+     *   {
+     *     eventId: "epicgames_S37_RankedCup_BR",
+     *     eventWindowId: "S37_RankedCup_Event1_BR",
+     *     leaderboardDef: "ranked_br_division_7"
+     *   },
+     *   [["accountId1"], ["accountId2"]]
+     * );
+     * ```
      */
     async getLeaderboardV2(params, teams, fortniteToken) {
         const query = new URLSearchParams({

package/dist/types/index.d.ts

@@ -292,3 +292,208 @@ export interface BattlePassOffers {
 export interface QuestsResponse {
     [key: string]: any;
 }
+export interface Account {
+    id: string;
+    displayName: string;
+    externalAuths?: Record<string, ExternalAuth>;
+}
+export interface ExternalAuth {
+    accountId: string;
+    type: string;
+    externalAuthId?: string;
+    externalDisplayName?: string;
+    authIds?: Array<{
+        id: string;
+        type: string;
+    }>;
+}
+export interface BulkExternalDisplayNameRequest {
+    lookups: Array<{
+        externalAuthType: string;
+        displayName: string;
+    }>;
+}
+export interface BulkExternalIdRequest {
+    lookups: Array<{
+        externalAuthType: string;
+        externalId: string;
+    }>;
+}
+export interface BRInventory {
+    stash?: {
+        globalcash?: number;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
+export interface Keychain {
+    keychain?: Array<{
+        key: string;
+        [key: string]: any;
+    }>;
+    [key: string]: any;
+}
+export interface Receipt {
+    receiptId: string;
+    purchaseDate: string;
+    offerId: string;
+    [key: string]: any;
+}
+export interface EnabledFeatures {
+    [key: string]: any;
+}
+export interface VersionCheck {
+    type: string;
+    [key: string]: any;
+}
+export interface PrivacySettings {
+    accountId?: string;
+    optOutOfPublicLeaderboards?: boolean;
+    [key: string]: any;
+}
+export interface EntitlementCheck {
+    entitlement?: boolean;
+    [key: string]: any;
+}
+export interface FriendsSummary {
+    friends?: Friend[];
+    incoming?: FriendRequest[];
+    outgoing?: FriendRequest[];
+    blocklist?: BlockedUser[];
+    settings?: {
+        [key: string]: any;
+    };
+}
+export interface Friend {
+    accountId: string;
+    displayName?: string;
+    status: "ACCEPTED" | "PENDING";
+    direction: "INBOUND" | "OUTBOUND";
+    created: string;
+    favorite?: boolean;
+    mutual?: number;
+}
+export interface FriendRequest {
+    accountId: string;
+    displayName?: string;
+    status: string;
+    direction: string;
+    created: string;
+}
+export interface BlockedUser {
+    accountId: string;
+    displayName?: string;
+}
+export interface FriendshipInfo extends Friend {
+    mutual: number;
+}
+export interface SuggestedFriend {
+    accountId: string;
+    displayName?: string;
+    mutualFriends?: number;
+}
+export interface PlayerStats {
+    accountId: string;
+    stats: {
+        [key: string]: any;
+    };
+}
+export interface BulkStatsRequest {
+    accountIds: string[];
+    stats?: string[];
+}
+export interface BulkStatsResponse {
+    accountId: string;
+    stats: {
+        [key: string]: any;
+    };
+}
+export interface LeaderboardOptions {
+    limit?: number;
+    offset?: number;
+    window?: "alltime" | "season" | "weekly" | "daily";
+}
+export interface LeaderboardResponse {
+    stat: string;
+    window: string;
+    entries: Array<{
+        rank: number;
+        accountId: string;
+        displayName?: string;
+        value: number;
+    }>;
+    pagination?: {
+        limit: number;
+        offset: number;
+        total?: number;
+    };
+}
+export interface EventWindows {
+    eventId: string;
+    displayName?: string;
+    windows: Array<{
+        eventWindowId: string;
+        beginTime: string;
+        endTime: string;
+        round?: number;
+    }>;
+}
+export interface PlayerEventHistory {
+    eventId: string;
+    eventWindowId: string;
+    eventName?: string;
+    beginTime: string;
+    endTime: string;
+    region?: string;
+}
+export interface TournamentDetails {
+    eventId: string;
+    eventWindowId: string;
+    beginTime: string;
+    endTime: string;
+    round?: number;
+    payoutDelay?: number;
+    [key: string]: any;
+}
+export interface ScoringRules {
+    scoring: Array<{
+        eventName: string;
+        points: number;
+    }>;
+}
+export interface EventLeaderboard {
+    entries: Array<{
+        rank: number;
+        accountId: string;
+        teamId?: string;
+        pointsEarned: number;
+        score: number;
+        [key: string]: any;
+    }>;
+}
+export interface PlayerEventData {
+    accountId: string;
+    teamId?: string;
+    pointsEarned: number;
+    rank?: number;
+    percentile?: number;
+    sessions?: Array<any>;
+}
+export interface EligibilityStatus {
+    eligible: boolean;
+    reasons?: string[];
+}
+export interface ArenaHype {
+    accountId: string;
+    currentHype?: number;
+    division?: string;
+    divisionNumber?: number;
+    progress?: number;
+}
+export interface EventRewards {
+    prizes: Array<{
+        placement: string;
+        amount: number;
+        currency?: string;
+    }>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaelouuu/fortnite-api",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "SDK for Fortnite Tournaments API by Royal Arena - Author : Yael Brinkert",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",