@yaelouuu/fortnite-api 8.1.0 → 9.1.0

package/README.md

@@ -108,16 +108,58 @@ const duoLeaderboard = await client.tournaments.getLeaderboardV2(
 ```
 
 #### Tournament Tracker
-Track player participation history:
+Track player participation history. Returns human-readable event names plus the official window `beginTime` / `endTime`:
 
 ```typescript
 const tracker = await client.tournaments.getTracker(
   "accountId",
   "fortniteToken"
 );
-// Returns: All tournaments the player has participated in
+// Returns: tournaments the player took part in over the last 180 days.
+// The first call for an account queues a backfill of a few minutes: while
+// tracker.history.complete is false the count is a lower bound — re-poll.
 ```
 
+#### Player Result in One Tournament — **no user token**
+Final placement, points, team and every match played, without the OAuth flow:
+
+```typescript
+const result = await client.tournaments.getPlayerWindowMatches(
+  "epicgames_S41_CashCup_DuosZB_OCE",
+  "S41_CashCup_DuosZB_Event1Round1_OCE",
+  "b6d0db0cefd74ccda92c111e7230ac33",
+  { rankHint: 1 } // optional, but turns a page scan into a single fetch
+);
+
+console.log(result.rank);                  // 1
+console.log(result.pointsEarned);          // 704
+console.log(result.teamAccountIds.length); // 2 -> team size
+console.log(result.matches[0].trackedStats.PLACEMENT_STAT_INDEX);
+```
+
+#### Recent Tournament Sessions — **token required**
+A player's recent tournament sessions, grouped by event window. Epic keeps roughly the last **36 hours** of this data, so it is not a full history (use the tracker for 180 days), and private custom-key matches never appear. Epic only serves it to the player it belongs to, so a token-less call returns `403`:
+
+```typescript
+const matches = await client.tournaments.getPlayerMatches(
+  "accountId",
+  "fortniteToken",
+  { after: "2026-01-01" }
+);
+```
+
+#### Current Match of a Consenting Player — **token required, Custom plan**
+The match a player is in right now, any mode — Battle Royale, Reload, Ranked or a custom-key scrim hosted by anyone. The only route to non-tournament matches: Epic has no match-history listing. `sessionId` is the replay match ID; `playlist` lets you filter for scrims before parsing.
+
+```typescript
+const session = await client.tournaments.getPlayerSession("accountId", "fortniteToken");
+if (session.inMatch && session.playlist === "playlist_showdown_cts_solo") {
+  console.log(session.sessionId); // parse it with the replay endpoints once the match has ended
+}
+```
+
+Read before building on it: the token must be that player's **own** (verified — any other account's token is `403`); Fortnite kills every other session of an account when the game launches, so mint it from stored device auth (`/oauth/link`, then `/oauth/refresh-device` on `401`); the response is cached 10 s per account and Epic's party state lags the real match by about 1–2 minutes; the custom key is never returned (`hasCustomKey` only) and teammates appear as account ids only.
+
 #### Check Tournament Eligibility
 Verify if a player meets requirements for major tournaments (e.g., 14 tournaments in 180 days):
 
@@ -151,6 +193,57 @@ const events = await client.tournaments.download(
 
 ---
 
+### Power Rankings - **NEW**
+
+Epic's own competitive Power Rankings ladder — the same figure shown in the in-game Compete tab and on Fortnite's competitive site. Read live from Epic's events service; nothing here is computed by the API or taken from a third-party tracker.
+
+Top 10,000 players (100 pages x 100), chapter-scoped (e.g. `"C7 Power Rankings"`). Epic publishes the ladder as a periodic snapshot — every entry on every page carries the same `sessionHistory[0].endTime`, which is that snapshot's date. The API re-fetches Epic hourly and rebuilds the search index every 2 hours.
+
+#### Leaderboard
+
+```typescript
+const board = await client.powerRankings.getLeaderboard({ page: 0 });
+
+const top = board.entries[0];
+console.log(top.rank);                              // 1
+console.log(top.pointsEarned);                      // PR score
+console.log(top.sessionHistory[0].trackedStats);    // PR, countingEvents (max 20), peakPR, deltaPR, peakPerf
+console.log(top.teamAccountDisplayNames);           // display names, already resolved
+```
+
+Pass a token **and** the matching `accountId` to also get that player's own entry as `playerEntry`, even when they fall outside the requested page:
+
+```typescript
+const board = await client.powerRankings.getLeaderboard(
+  { page: 0, accountId: "your-account-id" },
+  "fortniteToken"
+);
+console.log(board.playerEntry); // null when unranked
+```
+
+#### Look up one player — **no token**
+
+```typescript
+const found = await client.powerRankings.search("scroll", 3);
+console.log(found.results[0]); // { accountId, displayName, rank, score, countingEvents, peakPr, deltaPr }
+
+const archived = await client.powerRankings.getFromArchive("accountId");
+console.log(archived.rank, archived.bestRank, archived.seasonLabel, archived.lastUpdated);
+```
+
+#### Look up one player — **token required**
+
+`getPlayer()` needs the `x-fortnite-token` of the player being looked up. Epic rejects the underlying `teamAccountIds` filter under service auth, so a token-less call returns **400** for every account, including accounts inside the top 10,000. With the token it resolves players ranked beyond the top 10,000 as well.
+
+```typescript
+const entry = await client.powerRankings.getPlayer("displayNameOrAccountId", "fortniteToken");
+console.log(entry.rank, entry.pointsEarned, entry.trackedStats);
+```
+
+> **Note:** PR is a rolling aggregate of a player's best 20 events (`countingEvents` caps at 20). Epic does not publish how much any individual tournament contributed, so there is no per-event PR figure in this data.
+
+---
+
 ### Quests - **NEW**
 
 Access player quest progress, XP, and account level information.

package/dist/client.d.ts

@@ -20,6 +20,7 @@ import { CrewResource } from "./resources/crew";
 import { MapResource } from "./resources/map";
 import { PlaylistsResource } from "./resources/playlists";
 import { SpritesResource } from "./resources/sprites";
+import { PowerRankingsResource } from "./resources/powerrankings";
 export interface ClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -49,6 +50,7 @@ export declare class FortniteAPI {
     map: MapResource;
     playlists: PlaylistsResource;
     sprites: SpritesResource;
+    powerRankings: PowerRankingsResource;
     constructor(options: ClientOptions);
     /**
      * Internal method to make HTTP requests

package/dist/client.js

@@ -24,6 +24,7 @@ const crew_1 = require("./resources/crew");
 const map_1 = require("./resources/map");
 const playlists_1 = require("./resources/playlists");
 const sprites_1 = require("./resources/sprites");
+const powerrankings_1 = require("./resources/powerrankings");
 class FortniteAPI {
     constructor(options) {
         this.apiKey = options.apiKey;
@@ -52,6 +53,7 @@ class FortniteAPI {
         this.map = new map_1.MapResource(this);
         this.playlists = new playlists_1.PlaylistsResource(this);
         this.sprites = new sprites_1.SpritesResource(this);
+        this.powerRankings = new powerrankings_1.PowerRankingsResource(this);
     }
     /**
      * Internal method to make HTTP requests

package/dist/resources/events.d.ts

@@ -41,10 +41,32 @@ export declare class EventsResource {
     getPlayerWindowStanding(eventId: string, eventWindowId: string, accountId: string): Promise<PlayerWindowStanding>;
     /**
      * Get a player's event participation history.
-     * Uses the V2 events endpoint with service token — no user token required.
+     *
+     * **`fortniteToken` is mandatory.** Epic serves this history only to the player
+     * it belongs to — service auth is rejected, so a token-less call returns **401**.
+     * Get a token through the OAuth flow: `client.oauth.getToken()` then
+     * `client.oauth.complete()`.
+     *
+     * Returns one score object per event window: `scoreKey` (gameId, eventId,
+     * eventWindowId), `teamId`, `teamAccountIds` (so team size is
+     * `teamAccountIds.length`), `pointsEarned`, `score`, `rank` (the placement),
+     * `percentile`, `pointBreakdown`, `sessionHistory` (one entry per match, with
+     * `endTime` and tracked stats) and `unscoredSessions`.
+     *
+     * Note that Epic returns raw event/window IDs here, not display names — pair it
+     * with `client.tournaments.getTracker()` for human-readable event names and the
+     * official window begin/end times.
+     *
+     * If you do not have the player's token, look a single tournament up instead with
+     * `client.tournaments.getPlayerWindowMatches()`, which needs no user token.
+     *
      * @param accountId - Epic account ID of the player
+     * @param fortniteToken - Required. Fortnite access token of that same player.
+     *
+     * @throws {FortniteAPIError} 401 when the token is missing, expired, or belongs to
+     *                            a different account
      */
-    getPlayerEventHistory(accountId: string): Promise<any>;
+    getPlayerEventHistory(accountId: string, fortniteToken: string): Promise<any>;
     /**
      * Get the raw token set for one or more players.
      * Tokens are eligibility flags earned by participating in tournaments

package/dist/resources/events.js

@@ -56,11 +56,33 @@ class EventsResource {
     }
     /**
      * Get a player's event participation history.
-     * Uses the V2 events endpoint with service token — no user token required.
+     *
+     * **`fortniteToken` is mandatory.** Epic serves this history only to the player
+     * it belongs to — service auth is rejected, so a token-less call returns **401**.
+     * Get a token through the OAuth flow: `client.oauth.getToken()` then
+     * `client.oauth.complete()`.
+     *
+     * Returns one score object per event window: `scoreKey` (gameId, eventId,
+     * eventWindowId), `teamId`, `teamAccountIds` (so team size is
+     * `teamAccountIds.length`), `pointsEarned`, `score`, `rank` (the placement),
+     * `percentile`, `pointBreakdown`, `sessionHistory` (one entry per match, with
+     * `endTime` and tracked stats) and `unscoredSessions`.
+     *
+     * Note that Epic returns raw event/window IDs here, not display names — pair it
+     * with `client.tournaments.getTracker()` for human-readable event names and the
+     * official window begin/end times.
+     *
+     * If you do not have the player's token, look a single tournament up instead with
+     * `client.tournaments.getPlayerWindowMatches()`, which needs no user token.
+     *
      * @param accountId - Epic account ID of the player
+     * @param fortniteToken - Required. Fortnite access token of that same player.
+     *
+     * @throws {FortniteAPIError} 401 when the token is missing, expired, or belongs to
+     *                            a different account
      */
-    async getPlayerEventHistory(accountId) {
-        return this.client.request(`/events/players/${encodeURIComponent(accountId)}/history`, {}, "v2");
+    async getPlayerEventHistory(accountId, fortniteToken) {
+        return this.client.request(`/events/players/${encodeURIComponent(accountId)}/history`, { headers: { "x-fortnite-token": fortniteToken } }, "v2");
     }
     /**
      * Get the raw token set for one or more players.

package/dist/resources/powerrankings.d.ts

@@ -0,0 +1,95 @@
+import { FortniteAPI } from "../client";
+import { PowerRankingsLeaderboard, PowerRankingsSearchResponse, PowerRankingsArchiveEntry, PowerRankingsPlayerEntry } from "../types";
+/**
+ * Power Rankings Resource
+ *
+ * Epic's own competitive Power Rankings ladder — the same figure shown in the
+ * in-game Compete tab and on Fortnite's competitive site. It is read live from
+ * Epic's events service (`epicgames_dreamyparadox`); nothing here is computed by
+ * the API or sourced from a third-party tracker.
+ *
+ * The ladder covers the top 10,000 players (100 pages x 100 entries) and is
+ * chapter-scoped (e.g. `"C7 Power Rankings"`).
+ *
+ * Epic publishes the ladder as a periodic snapshot: every entry on every page
+ * carries the same `sessionHistory[0].endTime`, which is the date of the snapshot
+ * currently being served. The API re-fetches Epic hourly and rebuilds the search
+ * index every 2 hours, so polling more often than that will not surface newer data.
+ *
+ * All methods require the `pro` or `custom` plan.
+ */
+export declare class PowerRankingsResource {
+    private client;
+    constructor(client: FortniteAPI);
+    /**
+     * Get a page of the Power Rankings leaderboard.
+     *
+     * 100 entries per page, 100 pages total (top 10,000). No `x-fortnite-token`
+     * needed for the global page.
+     *
+     * Per entry: `rank`, `pointsEarned` / `score` (the PR value),
+     * `teamAccountIds`, `teamAccountDisplayNames`, `playerFlagTokens` (region), and
+     * `sessionHistory[0].trackedStats` with `PR`, `countingEvents` (capped at 20),
+     * `peakPerf`, `deltaPR`, `peakPR` and `deltaPosition`.
+     *
+     * @param options.page - Zero-indexed page (default: 0, max: 99)
+     * @param options.accountId - Epic account ID of the token holder. Required when
+     *                            `fortniteToken` is supplied, ignored otherwise.
+     * @param fortniteToken - Optional. When supplied together with `accountId`, the
+     *                        response also carries that player's own entry as
+     *                        `playerEntry` (`null` when they are unranked), even if
+     *                        they sit outside the requested page.
+     */
+    getLeaderboard(options?: {
+        page?: number;
+        accountId?: string;
+    }, fortniteToken?: string): Promise<PowerRankingsLeaderboard>;
+    /**
+     * Search Power Rankings players by display name (partial, case-insensitive).
+     *
+     * Backed by an in-memory index built from the full 10,000-player leaderboard and
+     * rebuilt every 2 hours. **No `x-fortnite-token` required** — this is the simplest
+     * way to resolve a player's PR when you do not have their OAuth token.
+     *
+     * @param q - Display name search term (partial match; 2+ characters recommended)
+     * @param limit - Max results (default: 10, max: 50)
+     */
+    search(q: string, limit?: number): Promise<PowerRankingsSearchResponse>;
+    /**
+     * Look up a player's live Power Rankings entry by display name or account ID.
+     *
+     * **`fortniteToken` is mandatory, and it must belong to the player being looked
+     * up.** Epic rejects the `teamAccountIds` filter this endpoint relies on when the
+     * request carries service auth, so a token-less call returns **400** for every
+     * account — including accounts that sit inside the top 10,000. With the token the
+     * entry resolves even when the player is ranked beyond the top 10,000.
+     *
+     * Get a token through the OAuth flow: `client.oauth.getToken()` then
+     * `client.oauth.complete()`.
+     *
+     * If you do not have the player's token, use {@link search} or
+     * {@link getFromArchive} instead — same PR figures, no OAuth required.
+     *
+     * @param identifier - Epic display name or 32-char hex account ID (clan tags are
+     *                     stripped automatically)
+     * @param fortniteToken - Required. Fortnite access token of the player being looked up.
+     *
+     * @throws {FortniteAPIError} 400 when the token is missing, expired, or belongs to
+     *                            a different account
+     * @throws {FortniteAPIError} 404 when the player has no Power Rankings entry
+     */
+    getPlayer(identifier: string, fortniteToken: string): Promise<PowerRankingsPlayerEntry>;
+    /**
+     * Look up a player's most recent archived Power Rankings entry by account ID.
+     *
+     * **No `x-fortnite-token` required.** Works for any account that has appeared in
+     * the top-10,000 leaderboard. Returns `rank`, `score`, `bestRank`, `peakPr`,
+     * `deltaPr`, `countingEvents`, `seasonLabel` and `lastUpdated` — read the
+     * `lastUpdated` timestamp to see how fresh the archived row is.
+     *
+     * @param accountId - 32-char hex Epic account ID
+     *
+     * @throws {FortniteAPIError} 404 when the account is not in the archive
+     */
+    getFromArchive(accountId: string): Promise<PowerRankingsArchiveEntry>;
+}

package/dist/resources/powerrankings.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PowerRankingsResource = void 0;
+/**
+ * Power Rankings Resource
+ *
+ * Epic's own competitive Power Rankings ladder — the same figure shown in the
+ * in-game Compete tab and on Fortnite's competitive site. It is read live from
+ * Epic's events service (`epicgames_dreamyparadox`); nothing here is computed by
+ * the API or sourced from a third-party tracker.
+ *
+ * The ladder covers the top 10,000 players (100 pages x 100 entries) and is
+ * chapter-scoped (e.g. `"C7 Power Rankings"`).
+ *
+ * Epic publishes the ladder as a periodic snapshot: every entry on every page
+ * carries the same `sessionHistory[0].endTime`, which is the date of the snapshot
+ * currently being served. The API re-fetches Epic hourly and rebuilds the search
+ * index every 2 hours, so polling more often than that will not surface newer data.
+ *
+ * All methods require the `pro` or `custom` plan.
+ */
+class PowerRankingsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get a page of the Power Rankings leaderboard.
+     *
+     * 100 entries per page, 100 pages total (top 10,000). No `x-fortnite-token`
+     * needed for the global page.
+     *
+     * Per entry: `rank`, `pointsEarned` / `score` (the PR value),
+     * `teamAccountIds`, `teamAccountDisplayNames`, `playerFlagTokens` (region), and
+     * `sessionHistory[0].trackedStats` with `PR`, `countingEvents` (capped at 20),
+     * `peakPerf`, `deltaPR`, `peakPR` and `deltaPosition`.
+     *
+     * @param options.page - Zero-indexed page (default: 0, max: 99)
+     * @param options.accountId - Epic account ID of the token holder. Required when
+     *                            `fortniteToken` is supplied, ignored otherwise.
+     * @param fortniteToken - Optional. When supplied together with `accountId`, the
+     *                        response also carries that player's own entry as
+     *                        `playerEntry` (`null` when they are unranked), even if
+     *                        they sit outside the requested page.
+     */
+    async getLeaderboard(options, fortniteToken) {
+        const params = new URLSearchParams();
+        if (options?.page != null)
+            params.append("page", String(options.page));
+        if (options?.accountId)
+            params.append("accountId", options.accountId);
+        const qs = params.toString();
+        const requestOptions = fortniteToken
+            ? { headers: { "x-fortnite-token": fortniteToken } }
+            : undefined;
+        return this.client.request(`/events/powerrankings${qs ? `?${qs}` : ""}`, requestOptions);
+    }
+    /**
+     * Search Power Rankings players by display name (partial, case-insensitive).
+     *
+     * Backed by an in-memory index built from the full 10,000-player leaderboard and
+     * rebuilt every 2 hours. **No `x-fortnite-token` required** — this is the simplest
+     * way to resolve a player's PR when you do not have their OAuth token.
+     *
+     * @param q - Display name search term (partial match; 2+ characters recommended)
+     * @param limit - Max results (default: 10, max: 50)
+     */
+    async search(q, limit) {
+        const params = new URLSearchParams({ q });
+        if (limit != null)
+            params.append("limit", String(limit));
+        return this.client.request(`/events/powerrankings/search?${params.toString()}`);
+    }
+    /**
+     * Look up a player's live Power Rankings entry by display name or account ID.
+     *
+     * **`fortniteToken` is mandatory, and it must belong to the player being looked
+     * up.** Epic rejects the `teamAccountIds` filter this endpoint relies on when the
+     * request carries service auth, so a token-less call returns **400** for every
+     * account — including accounts that sit inside the top 10,000. With the token the
+     * entry resolves even when the player is ranked beyond the top 10,000.
+     *
+     * Get a token through the OAuth flow: `client.oauth.getToken()` then
+     * `client.oauth.complete()`.
+     *
+     * If you do not have the player's token, use {@link search} or
+     * {@link getFromArchive} instead — same PR figures, no OAuth required.
+     *
+     * @param identifier - Epic display name or 32-char hex account ID (clan tags are
+     *                     stripped automatically)
+     * @param fortniteToken - Required. Fortnite access token of the player being looked up.
+     *
+     * @throws {FortniteAPIError} 400 when the token is missing, expired, or belongs to
+     *                            a different account
+     * @throws {FortniteAPIError} 404 when the player has no Power Rankings entry
+     */
+    async getPlayer(identifier, fortniteToken) {
+        return this.client.request(`/events/powerrankings/player/${encodeURIComponent(identifier)}`, { headers: { "x-fortnite-token": fortniteToken } });
+    }
+    /**
+     * Look up a player's most recent archived Power Rankings entry by account ID.
+     *
+     * **No `x-fortnite-token` required.** Works for any account that has appeared in
+     * the top-10,000 leaderboard. Returns `rank`, `score`, `bestRank`, `peakPr`,
+     * `deltaPr`, `countingEvents`, `seasonLabel` and `lastUpdated` — read the
+     * `lastUpdated` timestamp to see how fresh the archived row is.
+     *
+     * @param accountId - 32-char hex Epic account ID
+     *
+     * @throws {FortniteAPIError} 404 when the account is not in the archive
+     */
+    async getFromArchive(accountId) {
+        return this.client.request(`/events/powerrankings/archive/${encodeURIComponent(accountId)}`);
+    }
+}
+exports.PowerRankingsResource = PowerRankingsResource;

package/dist/resources/tournaments.d.ts

@@ -1,5 +1,5 @@
 import { FortniteAPI } from "../client";
-import { Leaderboard, TournamentTrackerResponse, TournamentEligibilityResponse, EventTokenEligibilityResponse, CashPrizesResponse, PayoutTable } from "../types";
+import { Leaderboard, TournamentTrackerResponse, TournamentEligibilityResponse, EventTokenEligibilityResponse, CashPrizesResponse, PayoutTable, PlayerSession } from "../types";
 export declare class TournamentsResource {
     private client;
     constructor(client: FortniteAPI);
@@ -61,6 +61,59 @@ export declare class TournamentsResource {
         leaderboardDef?: string;
         accountId?: string;
     }, fortniteToken?: string): Promise<Leaderboard>;
+    /**
+     * Get a player's result in one tournament window — **no user token required.**
+     *
+     * Returns their final `rank` (placement), `pointsEarned`, `teamAccountIds` (team
+     * size is `teamAccountIds.length`) and every match they played in that window,
+     * each with `sessionId`, `endTime` and `trackedStats` (`PLACEMENT_STAT_INDEX`,
+     * `TEAM_ELIMS_STAT_INDEX`, `TIME_ALIVE_STAT`, `VICTORY_ROYALE_STAT`, ...).
+     *
+     * The lookup works by scanning leaderboard pages until the player's team is found.
+     * Pass `rankHint` (their approximate final rank) to turn it into a single page
+     * fetch — without it up to `maxPages` pages are scanned in order, which is slower
+     * and may miss players placed beyond that point.
+     *
+     * Use this when you do not have the player's OAuth token. For their full history
+     * across every tournament, use `client.events.getPlayerEventHistory()` (token
+     * required).
+     *
+     * @param eventId - Event identifier (e.g. `"epicgames_S41_CashCup_DuosZB_OCE"`)
+     * @param eventWindowId - Event window identifier (e.g. `"S41_CashCup_DuosZB_Event1Round1_OCE"`)
+     * @param accountId - Epic account ID of any player on the team
+     * @param options.rankHint - Approximate leaderboard rank, if known — makes this a single page fetch
+     * @param options.maxPages - Max leaderboard pages to scan (default: 15, max: 100)
+     *
+     * @throws {FortniteAPIError} 404 when the player was not found within the scanned pages
+     */
+    getPlayerWindowMatches(eventId: string, eventWindowId: string, accountId: string, options?: {
+        rankHint?: number;
+        maxPages?: number;
+    }): Promise<any>;
+    /**
+     * A player's RECENT tournament sessions, grouped by event window. Epic keeps roughly
+     * the last 36 hours of this data — it is not a full history. Tournament sessions
+     * only: private custom-key matches never appear here.
+     *
+     * Sourced from Epic's player-scoped download data, which Epic only serves to the
+     * player it belongs to — so `fortniteToken` is required (without it Epic returns
+     * **403**). For a 180-day participation history use {@link getTracker}; for a
+     * token-free lookup scoped to one tournament use {@link getPlayerWindowMatches};
+     * for the match a player is in right now use {@link getPlayerSession}.
+     *
+     * @param accountId - Epic Games Account ID
+     * @param fortniteToken - Fortnite access token of that same player (from OAuth flow)
+     * @param options.after - Only matches ending at or after this UTC timestamp
+     * @param options.before - Only matches ending before this UTC timestamp
+     * @param options.region - Region for the events catalogue (default: EU). The sessions themselves are global.
+     * @param options.platform - Platform (default: Windows)
+     */
+    getPlayerMatches(accountId: string, fortniteToken: string, options?: {
+        after?: string;
+        before?: string;
+        region?: string;
+        platform?: string;
+    }): Promise<any>;
     /**
      * Get tournament participation history for a player
      * Requires user's own Fortnite token
@@ -216,4 +269,26 @@ export declare class TournamentsResource {
         eventWindowId: string;
         leaderboardDef?: string;
     }, teams: string[][], fortniteToken?: string): Promise<Leaderboard>;
+    /**
+     * The match a consenting player is in right now — any mode: Battle Royale, Reload,
+     * Ranked, or a custom-key scrim hosted by anyone. This is the only route to a player's
+     * non-tournament matches: Epic exposes no match-history listing. **Custom plan.**
+     *
+     * Requires that player's OWN Fortnite token: it is verified against `accountId` before
+     * anything is forwarded (any other account's token returns **403**). Fortnite kills every
+     * other session of an account when the game launches, so a token obtained before the
+     * player started playing is dead by the time they play — obtain it from stored device
+     * auth (`/oauth/link` once, then `/oauth/refresh-device` on 401), not a one-off login.
+     *
+     * While the player is in a game, `sessionId` is the replay match ID: pass it to the
+     * replay endpoints once the match has ended. `playlist` lets you filter (e.g. scrims)
+     * before parsing. Cached 10 s per account (polling faster gains nothing); Epic's own
+     * party state lags the real match by about 1-2 minutes; a session ID does not change
+     * during a match. Never returns the custom match key (`hasCustomKey` only) nor
+     * teammates' state (account ids only). `inParty` is false when the client is offline.
+     *
+     * @param accountId - Epic Games Account ID
+     * @param fortniteToken - That same player's Fortnite access token
+     */
+    getPlayerSession(accountId: string, fortniteToken: string): Promise<PlayerSession>;
 }

package/dist/resources/tournaments.js

@@ -92,6 +92,71 @@ class TournamentsResource {
             : undefined;
         return this.client.request(`/events/global/leaderboard?${query.toString()}`, options);
     }
+    /**
+     * Get a player's result in one tournament window — **no user token required.**
+     *
+     * Returns their final `rank` (placement), `pointsEarned`, `teamAccountIds` (team
+     * size is `teamAccountIds.length`) and every match they played in that window,
+     * each with `sessionId`, `endTime` and `trackedStats` (`PLACEMENT_STAT_INDEX`,
+     * `TEAM_ELIMS_STAT_INDEX`, `TIME_ALIVE_STAT`, `VICTORY_ROYALE_STAT`, ...).
+     *
+     * The lookup works by scanning leaderboard pages until the player's team is found.
+     * Pass `rankHint` (their approximate final rank) to turn it into a single page
+     * fetch — without it up to `maxPages` pages are scanned in order, which is slower
+     * and may miss players placed beyond that point.
+     *
+     * Use this when you do not have the player's OAuth token. For their full history
+     * across every tournament, use `client.events.getPlayerEventHistory()` (token
+     * required).
+     *
+     * @param eventId - Event identifier (e.g. `"epicgames_S41_CashCup_DuosZB_OCE"`)
+     * @param eventWindowId - Event window identifier (e.g. `"S41_CashCup_DuosZB_Event1Round1_OCE"`)
+     * @param accountId - Epic account ID of any player on the team
+     * @param options.rankHint - Approximate leaderboard rank, if known — makes this a single page fetch
+     * @param options.maxPages - Max leaderboard pages to scan (default: 15, max: 100)
+     *
+     * @throws {FortniteAPIError} 404 when the player was not found within the scanned pages
+     */
+    async getPlayerWindowMatches(eventId, eventWindowId, accountId, options) {
+        const params = new URLSearchParams();
+        if (options?.rankHint != null)
+            params.append("rankHint", String(options.rankHint));
+        if (options?.maxPages != null)
+            params.append("maxPages", String(options.maxPages));
+        const qs = params.toString();
+        return this.client.request(`/events/${encodeURIComponent(eventId)}/${encodeURIComponent(eventWindowId)}/player/${encodeURIComponent(accountId)}/matches${qs ? `?${qs}` : ""}`);
+    }
+    /**
+     * A player's RECENT tournament sessions, grouped by event window. Epic keeps roughly
+     * the last 36 hours of this data — it is not a full history. Tournament sessions
+     * only: private custom-key matches never appear here.
+     *
+     * Sourced from Epic's player-scoped download data, which Epic only serves to the
+     * player it belongs to — so `fortniteToken` is required (without it Epic returns
+     * **403**). For a 180-day participation history use {@link getTracker}; for a
+     * token-free lookup scoped to one tournament use {@link getPlayerWindowMatches};
+     * for the match a player is in right now use {@link getPlayerSession}.
+     *
+     * @param accountId - Epic Games Account ID
+     * @param fortniteToken - Fortnite access token of that same player (from OAuth flow)
+     * @param options.after - Only matches ending at or after this UTC timestamp
+     * @param options.before - Only matches ending before this UTC timestamp
+     * @param options.region - Region for the events catalogue (default: EU). The sessions themselves are global.
+     * @param options.platform - Platform (default: Windows)
+     */
+    async getPlayerMatches(accountId, fortniteToken, options) {
+        const params = new URLSearchParams();
+        if (options?.after)
+            params.append("after", options.after);
+        if (options?.before)
+            params.append("before", options.before);
+        if (options?.region)
+            params.append("region", options.region);
+        if (options?.platform)
+            params.append("platform", options.platform);
+        const qs = params.toString();
+        return this.client.request(`/events/player/${encodeURIComponent(accountId)}/matches${qs ? `?${qs}` : ""}`, { headers: { "x-fortnite-token": fortniteToken } });
+    }
     /**
      * Get tournament participation history for a player
      * Requires user's own Fortnite token
@@ -297,5 +362,29 @@ class TournamentsResource {
         }
         return this.client.request(`/events/leaderboard?${query.toString()}`, options, "v2");
     }
+    /**
+     * The match a consenting player is in right now — any mode: Battle Royale, Reload,
+     * Ranked, or a custom-key scrim hosted by anyone. This is the only route to a player's
+     * non-tournament matches: Epic exposes no match-history listing. **Custom plan.**
+     *
+     * Requires that player's OWN Fortnite token: it is verified against `accountId` before
+     * anything is forwarded (any other account's token returns **403**). Fortnite kills every
+     * other session of an account when the game launches, so a token obtained before the
+     * player started playing is dead by the time they play — obtain it from stored device
+     * auth (`/oauth/link` once, then `/oauth/refresh-device` on 401), not a one-off login.
+     *
+     * While the player is in a game, `sessionId` is the replay match ID: pass it to the
+     * replay endpoints once the match has ended. `playlist` lets you filter (e.g. scrims)
+     * before parsing. Cached 10 s per account (polling faster gains nothing); Epic's own
+     * party state lags the real match by about 1-2 minutes; a session ID does not change
+     * during a match. Never returns the custom match key (`hasCustomKey` only) nor
+     * teammates' state (account ids only). `inParty` is false when the client is offline.
+     *
+     * @param accountId - Epic Games Account ID
+     * @param fortniteToken - That same player's Fortnite access token
+     */
+    async getPlayerSession(accountId, fortniteToken) {
+        return this.client.request(`/events/player/${encodeURIComponent(accountId)}/session`, { headers: { "x-fortnite-token": fortniteToken } });
+    }
 }
 exports.TournamentsResource = TournamentsResource;

package/dist/types/index.d.ts

@@ -733,6 +733,110 @@ export interface PlayerWindowStanding {
     percentile?: number;
     sessionHistory: PlayerWindowStandingSession[];
 }
+/**
+ * Tracked stats carried on a Power Rankings ladder entry.
+ * `PR` is the Power Rankings score itself; `countingEvents` is capped at 20
+ * (Epic only counts a player's best 20 events).
+ */
+export interface PowerRankingsTrackedStats {
+    PR: number;
+    countingEvents: number;
+    peakPerf: number;
+    deltaPR: number;
+    peakPR: number;
+    deltaPosition?: number;
+}
+export interface PowerRankingsSession {
+    sessionId: string;
+    /** Date of the Epic snapshot this ladder was published from — identical across every entry. */
+    endTime: string;
+    trackedStats: PowerRankingsTrackedStats;
+}
+export interface PowerRankingsLeaderboardEntry {
+    gameId: string;
+    eventId: string;
+    eventWindowId: string;
+    teamId: string;
+    teamAccountIds: string[];
+    teamAccountDisplayNames?: string[];
+    /** The player's PR value. `score` carries the same number. */
+    pointsEarned: number;
+    score: number;
+    rank: number;
+    percentile: number;
+    pointBreakdown: Record<string, {
+        timesAchieved: number;
+        pointsEarned: number;
+    }>;
+    sessionHistory: PowerRankingsSession[];
+    /** Region/geo identity flag, e.g. `GroupIdentity_GeoIdentity_denmark`. */
+    playerFlagTokens?: Record<string, string>;
+    unscoredSessions?: any[];
+}
+/**
+ * Returned by GET /api/v1/events/powerrankings
+ */
+export interface PowerRankingsLeaderboard {
+    gameId: string;
+    eventId: string;
+    eventWindowId: string;
+    page: number;
+    totalPages: number;
+    updatedTime: string;
+    entries: PowerRankingsLeaderboardEntry[];
+    /**
+     * The token holder's own entry — present only when both `x-fortnite-token` and
+     * `accountId` were supplied. `null` when that player is unranked.
+     */
+    playerEntry?: PowerRankingsLeaderboardEntry | null;
+}
+export interface PowerRankingsSearchResult {
+    accountId: string;
+    displayName: string;
+    rank: number;
+    score: number;
+    countingEvents: number;
+    peakPr: number;
+    deltaPr: number;
+}
+/**
+ * Returned by GET /api/v1/events/powerrankings/search
+ */
+export interface PowerRankingsSearchResponse {
+    query: string;
+    total: number;
+    results: PowerRankingsSearchResult[];
+}
+/**
+ * Returned by GET /api/v1/events/powerrankings/player/{identifier}
+ * (requires the x-fortnite-token of the player being looked up)
+ */
+export interface PowerRankingsPlayerEntry {
+    accountId: string;
+    displayName: string;
+    eventId: string;
+    eventWindowId: string;
+    rank?: number;
+    pointsEarned?: number;
+    trackedStats?: PowerRankingsTrackedStats;
+}
+/**
+ * Returned by GET /api/v1/events/powerrankings/archive/{accountId}
+ */
+export interface PowerRankingsArchiveEntry {
+    accountId: string;
+    displayName: string;
+    rank: number;
+    score: number;
+    bestRank: number;
+    peakPr: number;
+    deltaPr: number;
+    countingEvents: number;
+    /** When this archived row was last refreshed — not the date of Epic's snapshot. */
+    lastUpdated: string;
+    /** Chapter the ladder belongs to, e.g. `"C7 Power Rankings"`. */
+    seasonLabel: string;
+}
 export interface PayoutTableReward {
     itemType: string;
     itemId?: string;
@@ -1083,3 +1187,30 @@ export interface SpriteBoonsResponse {
     status: number;
     data: SpriteBoon[];
 }
+/** GET /events/player/{accountId}/session — the match a consenting player is in right now. */
+export interface PlayerSession {
+    accountId: string;
+    /** False when the player's client is offline; no other field is meaningful then. */
+    inParty: boolean;
+    inMatch: boolean;
+    /** The replay match ID while in a game; null in the lobby or offline. */
+    sessionId: string | null;
+    partySize?: number;
+    isLeader?: boolean;
+    /** e.g. "PreLobby" | "InGame" */
+    location?: string | null;
+    gameMode?: string | null;
+    /** e.g. "playlist_showdown_cts_solo" — what they play, or what they have selected in the lobby. */
+    playlist?: string | null;
+    region?: string | null;
+    /** The party runs on a custom match key. The key itself is never returned. */
+    hasCustomKey?: boolean;
+    matchStartedAt?: string | null;
+    playersLeft?: number | null;
+    /** Teammates by account id only. */
+    members?: Array<{
+        accountId: string | null;
+        isLeader: boolean;
+    }>;
+    note?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaelouuu/fortnite-api",
-  "version": "8.1.0",
+  "version": "9.1.0",
   "description": "SDK for Fortnite API - api-fortnite.com - Author : Yael Brinkert",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",