@yaelouuu/fortnite-api 4.1.0 → 4.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Fortnite API SDK
 
-JavaScript/TypeScript SDK for the Fortnite API by Royal Arena.
+Official JavaScript/TypeScript SDK for the Fortnite API by Royal Arena.
 
 ## Installation
 
@@ -10,7 +10,7 @@ npm install @yaelouuu/fortnite-api
 
 ## API Key
 
-Acquire your API Key by creating a Free Account here : https://api-fortnite.com
+Acquire your API Key by creating a Free Account here: https://api-fortnite.com
 
 ## Quick Start
 
@@ -26,27 +26,502 @@ const shop = await client.shop.getCurrent();
 
 // Get tournament leaderboard
 const leaderboard = await client.tournaments.getLeaderboard({
-  eventId: "epicgames_...",
-  eventWindowId: "S37_...",
+  eventId: "epicgames_S37_BlitzCupsAllPlatforms_BR",
+  eventWindowId: "S37_BlitzCupsAllPlatforms_Event1_BR",
   page: 0,
 });
+```
+
+## Features
+
+- ✅ Full TypeScript support with comprehensive type definitions
+- ✅ Promise-based async/await API
+- ✅ Automatic error handling with detailed error messages
+- ✅ Support for all Fortnite API endpoints
+- ✅ Built-in OAuth flow helpers
+- ✅ Tree-shakeable for optimal bundle size
+
+---
+
+## 📚 API Resources
+
+### Shop
+
+Access the Fortnite Item Shop and Battle Pass data.
+
+```typescript
+// Get current item shop
+const shop = await client.shop.getCurrent();
+
+// Get current Battle Pass
+const battlePass = await client.battlepass.getBattlePass();
+```
+
+---
+
+### Tournaments
+
+Comprehensive tournament data including leaderboards, events, and eligibility tracking.
+
+#### Get Current Events
+```typescript
+const events = await client.tournaments.getCurrent();
+```
+
+#### Get Tournament Leaderboard (V1)
+```typescript
+const leaderboard = await client.tournaments.getLeaderboard({
+  eventId: "epicgames_S37_BlitzCupsAllPlatforms_BR",
+  eventWindowId: "S37_BlitzCupsAllPlatforms_Event1_BR",
+  page: 0,
+});
+```
+
+#### Get Tournament Leaderboard (V2) - **NEW**
+Enhanced leaderboard endpoint with POST body for bulk team queries:
+
+```typescript
+// Solo tournament - query multiple players
+const leaderboard = await client.tournaments.getLeaderboardV2(
+  {
+    eventId: "epicgames_S37_BlitzCupsAllPlatforms_BR",
+    eventWindowId: "S37_BlitzCupsAllPlatforms_Event1_BR",
+  },
+  [
+    ["accountId1"],
+    ["accountId2"],
+    ["accountId3"],
+  ]
+);
+
+// Duo tournament
+const duoLeaderboard = await client.tournaments.getLeaderboardV2(
+  {
+    eventId: "epicgames_S37_DuoCup_BR",
+    eventWindowId: "S37_DuoCup_Event1_BR",
+  },
+  [
+    ["player1Id", "player2Id"],
+    ["player3Id", "player4Id"],
+  ]
+);
+```
+
+#### Tournament Tracker
+Track player participation history:
+
+```typescript
+const tracker = await client.tournaments.getTracker(
+  "accountId",
+  "fortniteToken"
+);
+// Returns: All tournaments the player has participated in
+```
+
+#### Check Tournament Eligibility
+Verify if a player meets requirements for major tournaments (e.g., 14 tournaments in 180 days):
+
+```typescript
+const eligibility = await client.tournaments.checkEligibility(
+  "accountId",
+  "fortniteToken",
+  {
+    days: 180,
+    requiredTournaments: 14,
+  }
+);
+
+console.log(eligibility.eligible); // true/false
+console.log(eligibility.tournaments_remaining); // How many more needed
+```
+
+#### Download Events
+Get personalized event data:
+
+```typescript
+const events = await client.tournaments.download(
+  {
+    accountId: "your-account-id",
+    region: "EU",
+    platform: "Windows",
+  },
+  "fortniteToken"
+);
+```
+
+---
+
+### Quests - **NEW**
 
-// Get profile stats
-const stats = await client.profiles.getStats("PlayerName");
+Access player quest progress, XP, and account level information.
 
-// Get season info
+```typescript
+// Get quest data for an account
+const quests = await client.quests.getQuests(
+  "accountId",
+  "fortniteToken"
+);
+
+// Returns comprehensive data:
+// - Active quest progress
+// - Account XP and level
+// - Playtime statistics
+// - Quest rewards
+```
+
+**Authentication Required**: User's personal Fortnite OAuth token
+
+---
+
+### Profiles
+
+Player profile information and statistics.
+
+```typescript
+// Get profile by display name
+const profile = await client.profiles.getByName("PlayerName");
+
+// Get profile statistics
+const stats = await client.profiles.getStats("accountId");
+```
+
+---
+
+### Calendar
+
+Fortnite in-game calendar and season information.
+
+```typescript
+// Get current season info
 const season = await client.calendar.getCurrentSeason();
+
+// Returns: Season number, start/end dates, and more
 ```
 
-## Features
+---
 
-- ✅ Full TypeScript support
-- ✅ Promise-based async/await API
-- ✅ Automatic error handling
-- ✅ Built-in retry logic (optional)
-- ✅ Tree-shakeable
+### Bundles
+
+Fortnite game asset bundles and cosmetics.
+
+```typescript
+// Get all available bundles
+const bundles = await client.bundles.getAll();
+```
+
+---
+
+### Weapons
+
+Comprehensive weapon data including stats and metadata.
+
+```typescript
+// Get all weapons
+const weapons = await client.weapons.getAll();
+
+// Includes: Damage, fire rate, reload time, rarity, and more
+```
+
+---
+
+### OAuth
+
+OAuth authentication flow helpers for obtaining user tokens.
+
+```typescript
+// Start OAuth flow
+const flow = await client.oauth.startFlow();
+console.log(flow.verificationUri); // Show this URL to the user
+
+// Complete OAuth flow
+const authData = await client.oauth.completeFlow(flow.flowId);
+console.log(authData.accessToken); // User's Fortnite token
+console.log(authData.deviceAuth); // Device auth credentials
+
+// Refresh token
+const refreshed = await client.oauth.refreshToken(authData.refreshToken);
+```
+
+---
+
+### Parsing
+
+Parse Fortnite replay files to extract match data.
+
+```typescript
+// Parse a single replay file
+const replayData = await client.parsing.parseReplay(fileBuffer);
+
+// Parse multiple replays
+const batchResults = await client.parsing.parseBatch([file1, file2, file3]);
+```
+
+---
+
+### Account - **NEW**
+
+Comprehensive account lookup and management with cross-platform support.
+
+#### Lookup by Account ID
+```typescript
+const account = await client.account.getById('accountId123');
+// Returns: { id, displayName, externalAuths }
+```
+
+#### Lookup by Display Name
+```typescript
+const account = await client.account.getByDisplayName('Ninja');
+// Returns: Epic account information
+```
+
+#### Cross-Platform Lookup
+Search for accounts by platform usernames (PSN, Xbox, Steam, Nintendo, Twitch, GitHub):
+
+```typescript
+// Find by PSN username
+const account = await client.account.getByExternalDisplayName(
+  'psn',
+  'PSN_Username',
+  true  // case insensitive
+);
+
+// Find by Xbox gamertag
+const xboxAccount = await client.account.getByExternalDisplayName(
+  'xbl',
+  'Xbox_Gamertag',
+  false  // case sensitive
+);
+```
+
+**Supported Platforms:**
+- `psn` - PlayStation Network
+- `xbl` - Xbox Live
+- `steam` - Steam
+- `nintendo` - Nintendo Switch
+- `twitch` - Twitch
+- `github` - GitHub
+
+#### Bulk Operations
+Process multiple accounts efficiently:
+
+```typescript
+// Bulk account lookup (max 100)
+const accounts = await client.account.getBulk([
+  'accountId1',
+  'accountId2',
+  'accountId3'
+]);
+
+// Bulk external display name lookup
+const accounts = await client.account.getBulkExternalDisplayNames({
+  lookups: [
+    { externalAuthType: 'psn', displayName: 'PSNUser1' },
+    { externalAuthType: 'xbl', displayName: 'XboxUser1' },
+    { externalAuthType: 'steam', displayName: 'SteamUser1' }
+  ]
+});
+
+// Bulk external ID lookup
+const accounts = await client.account.getBulkExternalIds({
+  lookups: [
+    { externalAuthType: 'psn', externalId: 'psn-id-123' },
+    { externalAuthType: 'xbl', externalId: 'xbl-id-456' }
+  ]
+});
+```
+
+#### External Authentications
+Get platform connection information:
+
+```typescript
+// List all linked platforms
+const auths = await client.account.getExternalAuths('accountId123');
+// Returns: Array of all connected platforms
+
+// Get specific platform connection
+const psnAuth = await client.account.getExternalAuth('accountId123', 'psn');
+// Returns: PSN-specific connection details
+```
+
+---
+
+### FN (Fortnite Game) - **NEW**
+
+Fortnite-specific game data including inventory, features, and settings.
+
+#### Battle Royale Inventory
+Get player V-Bucks and in-game currency:
+
+```typescript
+const inventory = await client.fn.getBRInventory('accountId123');
+// Returns: { stash: { globalcash: 1250 } }
+console.log(`Player has ${inventory.stash.globalcash} V-Bucks`);
+```
+
+#### Storefront Keychain
+Get encryption keys for storefront data:
+
+```typescript
+const keychain = await client.fn.getKeychain();
+// Returns: Storefront encryption keychain
+```
+
+#### Purchase Receipts
+Get player purchase history:
+
+```typescript
+const receipts = await client.fn.getReceipts('accountId123');
+// Returns: Array of purchase receipts
+```
+
+#### Enabled Features
+Get currently active game features:
+
+```typescript
+const features = await client.fn.getEnabledFeatures();
+// Returns: Currently enabled game features
+```
+
+#### Version Check
+Validate game client version:
+
+```typescript
+const versionCheck = await client.fn.checkVersion(
+  'Windows',
+  '++Fortnite+Release-30.40-CL-35235494-Windows'
+);
+// Returns: { type: 'NO_UPDATE' } or update information
+```
+
+#### Privacy Settings (Requires User Token)
+Manage player privacy settings:
+
+```typescript
+// Get privacy settings
+const privacy = await client.fn.getPrivacySettings(
+  'accountId123',
+  'fortniteToken'
+);
+
+// Update privacy settings
+await client.fn.updatePrivacySettings(
+  'accountId123',
+  {
+    optOutOfPublicLeaderboards: true
+  },
+  'fortniteToken'
+);
+```
+
+#### Entitlement (Requires User Token)
+Check and request Fortnite access:
+
+```typescript
+// Check if user has Fortnite access
+const check = await client.fn.checkEntitlement('fortniteToken');
+
+// Request Fortnite access
+await client.fn.requestEntitlement('accountId123', 'fortniteToken');
+```
+
+---
+
+## 🔐 Authentication
+
+Some endpoints require user-specific authentication:
+
+### Endpoints Requiring User Token:
+- `client.quests.getQuests()`
+- `client.tournaments.getTracker()`
+- `client.tournaments.checkEligibility()`
+- `client.tournaments.download()`
+- `client.fn.getPrivacySettings()`
+- `client.fn.updatePrivacySettings()`
+- `client.fn.checkEntitlement()`
+- `client.fn.requestEntitlement()`
+
+**How to obtain user tokens:**
+
+1. Use the OAuth flow:
+```typescript
+const flow = await client.oauth.startFlow();
+// Direct user to flow.verificationUri
+const auth = await client.oauth.completeFlow(flow.flowId);
+// Use auth.accessToken as the fortniteToken parameter
+```
+
+---
+
+## 🚀 Advanced Usage
+
+### Custom Base URL
+
+```typescript
+const client = new FortniteAPI({
+  apiKey: "your-api-key",
+  baseUrl: "https://custom-api-url.com/api",
+});
+```
+
+### Error Handling
+
+```typescript
+import { FortniteAPIError } from "@yaelouuu/fortnite-api";
+
+try {
+  const shop = await client.shop.getCurrent();
+} catch (error) {
+  if (error instanceof FortniteAPIError) {
+    console.error(`API Error: ${error.message}`);
+    console.error(`Status Code: ${error.statusCode}`);
+    console.error(`Details:`, error.data);
+  }
+}
+```
+
+---
+
+## 📖 Documentation
+
+- **Full API Documentation (Swagger)**: https://documentation.api-fortnite.com/documentation
+- **SDK Documentation**: https://sdk.api-fortnite.com/
+- **Support**: https://api-fortnite.com
+
+---
+
+## 📝 License
+
+MIT
+
+---
+
+## 🆕 Changelog
+
+### v4.2.0 (2026-01-06)
+- ✨ **NEW** `AccountResource` with 8 methods:
+  - Account lookups by ID, display name, and external platforms
+  - Cross-platform search (PSN, Xbox, Steam, Nintendo, Twitch, GitHub)
+  - Bulk operations (up to 100 accounts)
+  - External authentication management
+- ✨ **NEW** `FNResource` with 9 methods:
+  - BR inventory (V-Bucks)
+  - Storefront keychain
+  - Purchase receipts
+  - Enabled features
+  - Version checking
+  - Privacy settings management
+  - Entitlement checking
+- 📝 Comprehensive TypeScript types for all new endpoints
+- 🎯 Full JSDoc documentation
+- ✅ 100% backward compatible
 
-## Documentation
+### v4.1.0
+- ✨ Added `WeaponsResource` with weapon stats and metadata
+- 🐛 Various bug fixes and improvements
 
-Full API documentation (swagger): https://documentation.api-fortnite.com/documentation
-SDK documentation: https://sdk.api-fortnite.com/
+### v4.0.0
+- ✨ Added `QuestsResource` with `getQuests()` method
+- ✨ Added `getLeaderboardV2()` method to `TournamentsResource`
+- 🐛 Fixed typo in `battlepass` property name
+- 📝 Comprehensive JSDoc documentation for all resources
+- 🎯 Full TypeScript type coverage

package/dist/client.d.ts

@@ -8,6 +8,11 @@ import { ParsingResource } from "./resources/parsing";
 import { WeaponsResource } from "./resources/weapons";
 import { BattlePassResource } from "./resources/battlepass";
 import { QuestsResource } from "./resources/quests";
+import { AccountResource } from "./resources/account";
+import { FNResource } from "./resources/fn";
+import { FriendsResource } from "./resources/friends";
+import { StatsResource } from "./resources/stats";
+import { EventsResource } from "./resources/events";
 export interface ClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -25,6 +30,11 @@ export declare class FortniteAPI {
     weapons: WeaponsResource;
     battlepass: BattlePassResource;
     quests: QuestsResource;
+    account: AccountResource;
+    fn: FNResource;
+    friends: FriendsResource;
+    stats: StatsResource;
+    events: EventsResource;
     constructor(options: ClientOptions);
     /**
      * Internal method to make HTTP requests

package/dist/client.js

@@ -12,6 +12,11 @@ const parsing_1 = require("./resources/parsing");
 const weapons_1 = require("./resources/weapons");
 const battlepass_1 = require("./resources/battlepass");
 const quests_1 = require("./resources/quests");
+const account_1 = require("./resources/account");
+const fn_1 = require("./resources/fn");
+const friends_1 = require("./resources/friends");
+const stats_1 = require("./resources/stats");
+const events_1 = require("./resources/events");
 class FortniteAPI {
     constructor(options) {
         this.apiKey = options.apiKey;
@@ -28,6 +33,11 @@ class FortniteAPI {
         this.weapons = new weapons_1.WeaponsResource(this);
         this.battlepass = new battlepass_1.BattlePassResource(this);
         this.quests = new quests_1.QuestsResource(this);
+        this.account = new account_1.AccountResource(this);
+        this.fn = new fn_1.FNResource(this);
+        this.friends = new friends_1.FriendsResource(this);
+        this.stats = new stats_1.StatsResource(this);
+        this.events = new events_1.EventsResource(this);
     }
     /**
      * Internal method to make HTTP requests

package/dist/resources/account.d.ts

@@ -0,0 +1,54 @@
+import { FortniteAPI } from "../client";
+import { Account, ExternalAuth, BulkExternalDisplayNameRequest, BulkExternalIdRequest } from "../types";
+export declare class AccountResource {
+    private client;
+    constructor(client: FortniteAPI);
+    /**
+     * Lookup account by Account ID
+     * @param accountId - Epic Games account ID
+     * @param fortniteToken - Optional user Fortnite token
+     */
+    getById(accountId: string, fortniteToken?: string): Promise<Account>;
+    /**
+     * Bulk account lookup by Account IDs
+     * @param accountIds - Array of Epic Games account IDs (max 100)
+     */
+    getBulk(accountIds: string[]): Promise<Account[]>;
+    /**
+     * Lookup account by Epic display name
+     * @param displayName - Epic Games display name
+     * @param fortniteToken - Optional user Fortnite token
+     */
+    getByDisplayName(displayName: string, fortniteToken?: string): Promise<Account>;
+    /**
+     * Cross-platform account lookup by external display name
+     * @param platform - Platform type (psn, xbl, steam, nintendo, twitch, github)
+     * @param displayName - Platform display name
+     * @param caseInsensitive - Case-insensitive search (default: false)
+     * @param fortniteToken - Optional user Fortnite token
+     */
+    getByExternalDisplayName(platform: string, displayName: string, caseInsensitive?: boolean, fortniteToken?: string): Promise<Account>;
+    /**
+     * Bulk external display name lookup
+     * @param payload - Array of platform/displayName pairs (max 100)
+     */
+    getBulkExternalDisplayNames(payload: BulkExternalDisplayNameRequest): Promise<Account[]>;
+    /**
+     * Bulk external ID lookup
+     * @param payload - Array of platform/externalId pairs (max 100)
+     */
+    getBulkExternalIds(payload: BulkExternalIdRequest): Promise<Account[]>;
+    /**
+     * Get all external authentications for an account
+     * @param accountId - Epic Games account ID
+     * @param fortniteToken - Optional user Fortnite token
+     */
+    getExternalAuths(accountId: string, fortniteToken?: string): Promise<ExternalAuth[]>;
+    /**
+     * Get specific external authentication for an account
+     * @param accountId - Epic Games account ID
+     * @param platform - Platform type (psn, xbl, steam, nintendo, twitch, github)
+     * @param fortniteToken - Optional user Fortnite token
+     */
+    getExternalAuth(accountId: string, platform: string, fortniteToken?: string): Promise<ExternalAuth>;
+}