@yaelouuu/fortnite-api 9.0.0 → 9.1.0

package/README.md

@@ -115,7 +115,9 @@ 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**
@@ -135,8 +137,8 @@ console.log(result.teamAccountIds.length); // 2 -> team size
 console.log(result.matches[0].trackedStats.PLACEMENT_STAT_INDEX);
 ```
 
-#### Full Match History — **token required**
-Every tournament match a player has played, grouped by event window. Epic only serves this to the player it belongs to, so a token-less call returns `403`:
+#### 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(
@@ -146,6 +148,18 @@ const matches = await client.tournaments.getPlayerMatches(
 );
 ```
 
+#### 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):
 

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);
@@ -91,18 +91,21 @@ export declare class TournamentsResource {
         maxPages?: number;
     }): Promise<any>;
     /**
-     * Get every tournament match a player has played, grouped by event window.
+     * 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 effectively required (without it
-     * Epic returns **403**). For a token-free lookup scoped to one tournament, use
-     * {@link getPlayerWindowMatches}.
+     * 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). Match history itself is global.
+     * @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?: {
@@ -266,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

@@ -127,18 +127,21 @@ class TournamentsResource {
         return this.client.request(`/events/${encodeURIComponent(eventId)}/${encodeURIComponent(eventWindowId)}/player/${encodeURIComponent(accountId)}/matches${qs ? `?${qs}` : ""}`);
     }
     /**
-     * Get every tournament match a player has played, grouped by event window.
+     * 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 effectively required (without it
-     * Epic returns **403**). For a token-free lookup scoped to one tournament, use
-     * {@link getPlayerWindowMatches}.
+     * 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). Match history itself is global.
+     * @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) {
@@ -359,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

@@ -1187,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": "9.0.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",