@spinzaf/freefire-api 1.0.0

package/index.js

@@ -0,0 +1,3 @@
+const FreeFireAPI = require('./lib/api');
+
+module.exports = FreeFireAPI;

package/lib/api.js

@@ -0,0 +1,229 @@
+const axios = require('axios');
+const protoHandler = require('./protobuf');
+const { AE, HEADERS, URLS, GARENA_CLIENT, DEFAULT_CREDENTIALS } = require('./constants');
+const { processPlayerItems } = require('./utils');
+
+class FreeFireAPI {
+    constructor() {
+        this.session = {
+            token: null,
+            serverUrl: null,
+            openId: null,
+            accountId: null
+        };
+    }
+
+    /**
+     * Authenticate with Garena using UID and Password (Guest/Account)
+     * @param {string} [uid] - (Optional) User ID
+     * @param {string} [password] - (Optional) Password
+     */
+    async login(uid = null, password = null) {
+        // Use default credentials if not provided
+        if (!uid || !password) {
+            console.log("[i] No credentials provided, loading from config/credentials.yaml.");
+            uid = DEFAULT_CREDENTIALS.UID;
+            password = DEFAULT_CREDENTIALS.PASSWORD;
+        }
+
+        if (!uid || !password) {
+            throw new Error("Missing credentials. Set UID and PASSWORD in config/credentials.yaml or pass them to login(uid, password).");
+        }
+
+        // Step 1: Get Garena Token
+        const garenaData = await this._getGarenaToken(uid, password);
+        if (!garenaData || !garenaData.access_token) {
+            throw new Error("Garena authentication failed: Invalid credentials or response");
+        }
+
+        // Step 2: Major Login
+        const loginData = await this._majorLogin(garenaData.access_token, garenaData.open_id);
+        if (!loginData || !loginData.token) {
+            throw new Error("Major login failed: Empty token received");
+        }
+
+        this.session.token = loginData.token;
+        this.session.serverUrl = loginData.serverUrl;
+        this.session.openId = garenaData.open_id;
+        this.session.accountId = loginData.accountid;
+
+        return this.session;
+    }
+
+    async _getGarenaToken(uid, password) {
+        const params = new URLSearchParams();
+        params.append('uid', uid);
+        params.append('password', password);
+        params.append('response_type', 'token');
+        params.append('client_type', '2');
+        params.append('client_secret', GARENA_CLIENT.CLIENT_SECRET);
+        params.append('client_id', GARENA_CLIENT.CLIENT_ID);
+
+        try {
+            const response = await axios.post(URLS.GARENA_TOKEN, params, {
+                headers: HEADERS.GARENA_AUTH
+            });
+            return response.data;
+        } catch (error) {
+            throw new Error(`Garena Auth Request Failed: ${error.message}`);
+        }
+    }
+
+    async _majorLogin(accessToken, openId) {
+        const payload = {
+            openid: openId,
+            logintoken: accessToken,
+            platform: "4"
+        };
+
+        const encryptedBody = await protoHandler.encode('MajorLogin.proto', 'request', payload, true);
+
+        try {
+            const response = await axios.post(URLS.MAJOR_LOGIN, encryptedBody, {
+                headers: {
+                    ...HEADERS.COMMON,
+                    'Authorization': 'Bearer', // Specific to MajorLogin
+                    'Content-Type': 'application/octet-stream'
+                },
+                responseType: 'arraybuffer'
+            });
+
+            return await protoHandler.decode('MajorLogin.proto', 'response', response.data);
+        } catch (error) {
+            throw new Error(`Major Login Request Failed: ${error.message}`);
+        }
+    }
+
+    /**
+     * Search for accounts by name (fuzzy search)
+     * @param {string} keyword 
+     * @returns {Promise<Array>} List of matching accounts
+     */
+    async searchAccount(keyword) {
+        await this._checkSession();
+
+        if (keyword.length < 3) {
+            throw new Error("Search keyword must be at least 3 characters long.");
+        }
+
+        const payload = { keyword: String(keyword) };
+        const encryptedBody = await protoHandler.encode('SearchAccountByName.proto', 'SearchAccountByName.request', payload, true);
+
+        const url = URLS.SEARCH(this.session.serverUrl);
+
+        try {
+            const response = await axios.post(url, encryptedBody, {
+                headers: {
+                    ...HEADERS.COMMON,
+                    'Authorization': `Bearer ${this.session.token}`,
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                },
+                responseType: 'arraybuffer'
+            });
+
+            const data = await protoHandler.decode('SearchAccountByName.proto', 'SearchAccountByName.response', response.data);
+            return data.infos; // Field name is 'infos' in proto
+        } catch (error) {
+            throw new Error(`Search Failed: ${error.message}`);
+        }
+    }
+
+    /**
+     * Get detailed player profile (Personal Show)
+     * @param {number|string} uid 
+     * @returns {Promise<Object>} Player data including profile, guild, etc.
+     */
+    async getPlayerProfile(uid) {
+        await this._checkSession();
+
+        const payload = {
+            accountId: Number(uid),
+            callSignSrc: 7,
+            needGalleryInfo: true
+        };
+
+        const encryptedBody = await protoHandler.encode('PlayerPersonalShow.proto', 'request', payload, true);
+        const url = URLS.PERSONAL_SHOW(this.session.serverUrl);
+
+        try {
+            const response = await axios.post(url, encryptedBody, {
+                headers: {
+                    ...HEADERS.COMMON,
+                    'Authorization': `Bearer ${this.session.token}`
+                },
+                responseType: 'arraybuffer'
+            });
+
+            return await protoHandler.decode('PlayerPersonalShow.proto', 'response', response.data);
+        } catch (error) {
+            throw new Error(`Get Profile Failed: ${error.message}`);
+        }
+    }
+
+    /**
+     * Get player items (outfit, weapons, skills, pet)
+     * @param {number|string} uid 
+     */
+    async getPlayerItems(uid) {
+        const profile = await this.getPlayerProfile(uid);
+        if (!profile) return null;
+        return processPlayerItems(profile);
+    }
+
+    /**
+     * Get Player Stats
+     * @param {number|string} uid 
+     * @param {'br'|'cs'} mode - Battle Royale or Clash Squad
+     * @param {'career'|'ranked'|'normal'} matchType 
+     */
+    async getPlayerStats(uid, mode = 'br', matchType = 'career') {
+        await this._checkSession();
+
+        const modeLower = mode.toLowerCase();
+        const typeUpper = matchType.toUpperCase();
+
+        let matchMode = 0;
+        let url = '';
+        let protoFile = '';
+        let payload = { accountid: Number(uid) };
+
+        if (modeLower === 'br') {
+            const types = { 'CAREER': 0, 'NORMAL': 1, 'RANKED': 2 };
+            matchMode = types[typeUpper] !== undefined ? types[typeUpper] : 0;
+            url = URLS.PLAYER_STATS(this.session.serverUrl);
+            protoFile = 'PlayerStats.proto';
+            payload.matchmode = matchMode;
+        } else {
+            const types = { 'CAREER': 0, 'NORMAL': 1, 'RANKED': 6 };
+            matchMode = types[typeUpper] !== undefined ? types[typeUpper] : 0;
+            url = URLS.PLAYER_CS_STATS(this.session.serverUrl);
+            protoFile = 'PlayerCSStats.proto';
+            payload.gamemode = 15; // CS default
+            payload.matchmode = matchMode;
+        }
+
+        const encryptedBody = await protoHandler.encode(protoFile, 'request', payload, true);
+
+        try {
+            const response = await axios.post(url, encryptedBody, {
+                headers: {
+                    ...HEADERS.COMMON,
+                    'Authorization': `Bearer ${this.session.token}`
+                },
+                responseType: 'arraybuffer'
+            });
+
+            return await protoHandler.decode(protoFile, 'response', response.data);
+        } catch (error) {
+            throw new Error(`Get Stats Failed: ${error.message}`);
+        }
+    }
+    // ----- Auto login if no session with Default Data.
+    async _checkSession() {
+        if (!this.session.token || !this.session.serverUrl) {
+            await this.login();
+        }
+    }
+}
+
+module.exports = FreeFireAPI;

package/lib/constants.js

@@ -0,0 +1,115 @@
+const fs = require('fs');
+const path = require('path');
+
+function parseSimpleYaml(content) {
+    const result = {};
+    const lines = content.split(/\r?\n/);
+
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#')) continue;
+
+        const separatorIndex = line.indexOf(':');
+        if (separatorIndex === -1) continue;
+
+        const key = line.slice(0, separatorIndex).trim();
+        let value = line.slice(separatorIndex + 1).trim();
+
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+
+        result[key] = value;
+    }
+
+    return result;
+}
+
+function loadYamlFile(filePath) {
+    try {
+        const yamlRaw = fs.readFileSync(filePath, 'utf8');
+        return parseSimpleYaml(yamlRaw);
+    } catch (error) {
+        return {};
+    }
+}
+
+function readConfigValue(config, key, fallback) {
+    const value = config[key];
+    if (value === undefined || value === null || value === '') return fallback;
+    return String(value);
+}
+
+function requireConfigValue(config, key) {
+    const value = readConfigValue(config, key, '');
+    if (!value) {
+        throw new Error(`Missing required setting in config/settings.yaml: ${key}`);
+    }
+    return value;
+}
+
+function loadDefaultCredentials() {
+    const parsed = loadYamlFile(path.join(__dirname, '../config/credentials.yaml'));
+    return {
+        UID: readConfigValue(parsed, 'UID', ''),
+        PASSWORD: readConfigValue(parsed, 'PASSWORD', '')
+    };
+}
+
+function loadSettings() {
+    const parsed = loadYamlFile(path.join(__dirname, '../config/settings.yaml'));
+
+    return {
+        AE: {
+            MAIN_KEY: Buffer.from(requireConfigValue(parsed, 'AE_MAIN_KEY'), "binary"),
+            MAIN_IV: Buffer.from(requireConfigValue(parsed, 'AE_MAIN_IV'), "binary")
+        },
+        HEADERS: {
+            COMMON: {
+                'User-Agent': requireConfigValue(parsed, 'HEADERS_COMMON_USER_AGENT'),
+                'Connection': requireConfigValue(parsed, 'HEADERS_COMMON_CONNECTION'),
+                'Accept-Encoding': requireConfigValue(parsed, 'HEADERS_COMMON_ACCEPT_ENCODING'),
+                'Expect': requireConfigValue(parsed, 'HEADERS_COMMON_EXPECT'),
+                'X-Unity-Version': requireConfigValue(parsed, 'HEADERS_COMMON_X_UNITY_VERSION'),
+                'X-GA': requireConfigValue(parsed, 'HEADERS_COMMON_X_GA'),
+                'ReleaseVersion': requireConfigValue(parsed, 'HEADERS_COMMON_RELEASE_VERSION'),
+                'Content-Type': requireConfigValue(parsed, 'HEADERS_COMMON_CONTENT_TYPE')
+            },
+            GARENA_AUTH: {
+                'User-Agent': requireConfigValue(parsed, 'HEADERS_GARENA_AUTH_USER_AGENT'),
+                'Connection': requireConfigValue(parsed, 'HEADERS_GARENA_AUTH_CONNECTION'),
+                'Accept-Encoding': requireConfigValue(parsed, 'HEADERS_GARENA_AUTH_ACCEPT_ENCODING')
+            }
+        },
+        URLS: {
+            GARENA_TOKEN: requireConfigValue(parsed, 'URL_GARENA_TOKEN'),
+            MAJOR_LOGIN: requireConfigValue(parsed, 'URL_MAJOR_LOGIN'),
+            SEARCH_PATH: requireConfigValue(parsed, 'URL_PATH_SEARCH'),
+            PERSONAL_SHOW_PATH: requireConfigValue(parsed, 'URL_PATH_PERSONAL_SHOW'),
+            PLAYER_STATS_PATH: requireConfigValue(parsed, 'URL_PATH_PLAYER_STATS'),
+            PLAYER_CS_STATS_PATH: requireConfigValue(parsed, 'URL_PATH_PLAYER_CS_STATS')
+        },
+        GARENA_CLIENT: {
+            CLIENT_ID: requireConfigValue(parsed, 'GARENA_CLIENT_ID'),
+            CLIENT_SECRET: requireConfigValue(parsed, 'GARENA_CLIENT_SECRET')
+        }
+    };
+}
+
+const settings = loadSettings();
+const paths = settings.URLS;
+
+module.exports = {
+    AE: settings.AE,
+    HEADERS: settings.HEADERS,
+    URLS: {
+        GARENA_TOKEN: paths.GARENA_TOKEN,
+        MAJOR_LOGIN: paths.MAJOR_LOGIN,
+        SEARCH: (serverUrl) => `${serverUrl}${paths.SEARCH_PATH}`,
+        PERSONAL_SHOW: (serverUrl) => `${serverUrl}${paths.PERSONAL_SHOW_PATH}`,
+        PLAYER_STATS: (serverUrl) => `${serverUrl}${paths.PLAYER_STATS_PATH}`,
+        PLAYER_CS_STATS: (serverUrl) => `${serverUrl}${paths.PLAYER_CS_STATS_PATH}`
+    },
+    GARENA_CLIENT: settings.GARENA_CLIENT,
+    DEFAULT_CREDENTIALS: loadDefaultCredentials()
+};

package/lib/crypto.js

@@ -0,0 +1,15 @@
+const crypto = require('crypto');
+const { AE } = require('./constants');
+
+/**
+ * Encrypts data using AES-128-CBC with PKCS7 padding.
+ * @param {Buffer} buffer - The data to encrypt
+ * @returns {Buffer} Encrypted data
+ */
+function encrypt(buffer) {
+    const cipher = crypto.createCipheriv('aes-128-cbc', AE.MAIN_KEY, AE.MAIN_IV);
+    const encrypted = Buffer.concat([cipher.update(buffer), cipher.final()]);
+    return encrypted;
+}
+
+module.exports = { encrypt };

package/lib/protobuf.js

@@ -0,0 +1,51 @@
+const protobuf = require('protobufjs');
+const path = require('path');
+const { encrypt } = require('./crypto');
+
+const PROTO_DIR = path.join(__dirname, '../proto');
+
+class ProtoHandler {
+    constructor() {
+        this.roots = {};
+    }
+
+    async load(filename) {
+        if (!this.roots[filename]) {
+            this.roots[filename] = await protobuf.load(path.join(PROTO_DIR, filename));
+        }
+        return this.roots[filename];
+    }
+
+    async encode(filename, messageName, payload, shouldEncrypt = true) {
+        const root = await this.load(filename);
+        const Type = root.lookupType(messageName);
+
+        // Verify payload matches connection
+        const errMsg = Type.verify(payload);
+        if (errMsg) throw Error(errMsg);
+
+        const message = Type.create(payload);
+        const buffer = Type.encode(message).finish();
+
+        if (shouldEncrypt) {
+            return encrypt(buffer);
+        }
+        return buffer;
+    }
+
+    async decode(filename, messageName, buffer) {
+        const root = await this.load(filename);
+        const Type = root.lookupType(messageName);
+
+        const message = Type.decode(buffer);
+        return Type.toObject(message, {
+            longs: String,
+            enums: String,
+            bytes: String,
+            defaults: true,
+            arrays: true
+        });
+    }
+}
+
+module.exports = new ProtoHandler();

package/lib/utils.js

@@ -0,0 +1,112 @@
+const fs = require('fs');
+const path = require('path');
+
+let itemsDb = null;
+
+function loadItems() {
+    if (itemsDb) return itemsDb;
+    try {
+        const data = fs.readFileSync(path.join(__dirname, '../data/items.json'), 'utf8');
+        const itemsList = JSON.parse(data);
+        itemsDb = {};
+        itemsList.forEach(item => {
+            const id = item.id || item.itemID;
+            if (id) itemsDb[String(id)] = item;
+        });
+        console.log(`Loaded ${Object.keys(itemsDb).length} items into database.`);
+    } catch (e) {
+        console.error("Failed to load items database:", e);
+        itemsDb = {};
+    }
+    return itemsDb;
+}
+
+// Initialize immediately
+loadItems();
+
+function getItemDetails(itemId) {
+    const itemStrId = String(itemId);
+
+    const currentItem = {
+        id: itemId,
+        name: "Unknown Item",
+        type: "UNKNOWN",
+        rarity: "NONE",
+        description: "",
+        is_unique: false,
+        image: `https://raw.githubusercontent.com/ashqking/FF-Items/main/ICONS/${itemId}.png`,
+        image_fallback: `https://raw.githubusercontent.com/I-SHOW-AKIRU200/AKIRU-ICONS/main/ICONS/${itemId}.png`
+    };
+
+    if (itemsDb && itemsDb[itemStrId]) {
+        const itemData = itemsDb[itemStrId];
+        currentItem.name = itemData.name || itemData.description || "Unknown Name";
+        currentItem.type = itemData.type || "UNKNOWN";
+        currentItem.collection_type = itemData.collection_type || "NONE";
+        currentItem.rarity = itemData.rare || "NONE";
+        currentItem.description = itemData.description || "";
+        currentItem.is_unique = itemData.is_unique || false;
+        currentItem.icon_code = itemData.icon || "";
+    }
+
+    return currentItem;
+}
+
+function processPlayerItems(playerData) {
+    const profileInfo = playerData.profileinfo || {};
+    const basicInfo = playerData.basicinfo || {};
+    const petInfo = playerData.petinfo || {};
+
+    // Clothes
+    const outfitIds = profileInfo.clothes || [];
+    const outfitDetails = outfitIds.map(getItemDetails);
+
+    // Weapons (shown skins)
+    const weaponIds = basicInfo.weaponskinshows || [];
+    const weaponDetails = weaponIds.map(getItemDetails);
+
+    // Skills
+    const skillIds = profileInfo.equipedskills || [];
+    const skillDetails = skillIds.map(getItemDetails);
+
+    // Pet
+    let petDetails = null;
+    if (petInfo && (petInfo.id || petInfo.skinid)) {
+        petDetails = {
+            id: getItemDetails(petInfo.id),
+            name: petInfo.name,
+            level: petInfo.level,
+            skin: getItemDetails(petInfo.skinid),
+            selected_skill: getItemDetails(petInfo.selectedskillid)
+        };
+    }
+
+    const normalizedBasicInfo = {
+        accountid: basicInfo.accountid || "",
+        nickname: basicInfo.nickname || "",
+        level: basicInfo.level || 0,
+        region: basicInfo.region || "",
+        liked: basicInfo.liked || "",
+        signature: basicInfo.signature || ""
+    };
+
+    return {
+        basic_info: normalizedBasicInfo,
+        items: {
+            outfit: outfitDetails,
+            skills: {
+                equipped: skillDetails
+            },
+            weapons: {
+                shown_skins: weaponDetails
+            },
+            pet: petDetails
+        }
+    };
+}
+
+module.exports = {
+    loadItems,
+    getItemDetails,
+    processPlayerItems
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@spinzaf/freefire-api",
+  "version": "1.0.0",
+  "description": "A powerful Node.js library to interact with Garena Free Fire API using Protobuf. Login, Search Players, and get Profile Stats.",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test/search.js",
+    "test:login": "node test/login.js",
+    "test:search": "node test/search.js",
+    "test:profile": "node test/profile.js",
+    "test:stats": "node test/stats.js",
+    "test:items": "node test/items.js",
+    "test:all": "node test/all.js"
+  },
+  "keywords": [
+    "freefire",
+    "checker",
+    "game-api",
+    "player-stats",
+    "ff",
+    "freefire-api",
+    "garena-freefire",
+    "player-info",
+    "stats-checker",
+    "game-data",
+    "sdk",
+    "wrapper",
+    "nodejs",
+    "javascript"
+  ],
+  "author": "spinzaf",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spinzaf/freefire-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/spinzaf/freefire-api/issues"
+  },
+  "homepage": "https://github.com/spinzaf/freefire-api#readme",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "protobufjs": "^7.2.0"
+  }
+}