steamworks-ffi-node 0.3.1 → 0.4.0

package/dist/internal/SteamStatsManager.js

@@ -82,13 +82,14 @@ class SteamStatsManager {
      * that track player progress and can be used for leaderboards and analytics.
      *
      * @param statName - Name of the stat to retrieve (as defined in Steamworks Partner site)
-     * @returns The stat value, or null if not found or on error
+     * @returns SteamStat object with name, value, and type, or null if not found or on error
      *
      * @example
      * ```typescript
-     * const totalKills = await statsManager.getStatInt('total_kills');
-     * if (totalKills !== null) {
-     *   console.log(`Total kills: ${totalKills}`);
+     * const killsStat = await statsManager.getStatInt('total_kills');
+     * if (killsStat) {
+     *   console.log(`[Steamworks] ${killsStat.name}: ${killsStat.value}`);
+     *   // Access value directly: killsStat.value
      * }
      * ```
      *
@@ -96,13 +97,14 @@ class SteamStatsManager {
      * - Returns null if Steam API is not initialized
      * - Stat names are case-sensitive and must match Steamworks configuration
      * - Use getStatFloat() for decimal values
+     * - Returns structured SteamStat object with full metadata
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetStatInt32()` - Get int32 stat value
      */
     async getStatInt(statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -111,16 +113,20 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetStatInt32(userStatsInterface, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'int32');
-                console.log(`📊 Got stat "${statName}": ${value}`);
-                return value;
+                console.log(`[Steamworks] Got stat "${statName}": ${value}`);
+                return {
+                    name: statName,
+                    value,
+                    type: 'int'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting stat "${statName}":`, error.message);
             return null;
         }
     }
@@ -131,26 +137,27 @@ class SteamStatsManager {
      * require decimal precision (e.g., average accuracy, distance traveled).
      *
      * @param statName - Name of the stat to retrieve (as defined in Steamworks Partner site)
-     * @returns The stat value, or null if not found or on error
+     * @returns SteamStat object with name, value, and type, or null if not found or on error
      *
      * @example
      * ```typescript
-     * const accuracy = await statsManager.getStatFloat('shooting_accuracy');
-     * if (accuracy !== null) {
-     *   console.log(`Accuracy: ${(accuracy * 100).toFixed(2)}%`);
+     * const accuracyStat = await statsManager.getStatFloat('shooting_accuracy');
+     * if (accuracyStat) {
+     *   console.log(`[Steamworks] ${accuracyStat.name}: ${(accuracyStat.value * 100).toFixed(2)}%`);
      * }
      * ```
      *
      * @remarks
      * - Returns null if Steam API is not initialized
      * - Use getStatInt() for whole number values
+     * - Returns structured SteamStat object with full metadata
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetStatFloat()` - Get float stat value
      */
     async getStatFloat(statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -159,16 +166,20 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetStatFloat(userStatsInterface, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'float');
-                console.log(`📊 Got stat "${statName}": ${value}`);
-                return value;
+                console.log(`[Steamworks] Got stat "${statName}": ${value}`);
+                return {
+                    name: statName,
+                    value,
+                    type: 'float'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting stat "${statName}":`, error.message);
             return null;
         }
     }
@@ -188,7 +199,7 @@ class SteamStatsManager {
      * const currentKills = await statsManager.getStatInt('total_kills') || 0;
      * const success = await statsManager.setStatInt('total_kills', currentKills + 1);
      * if (success) {
-     *   console.log('Kill count updated!');
+     *   console.log('[Steamworks] Kill count updated!');
      * }
      * ```
      *
@@ -205,7 +216,7 @@ class SteamStatsManager {
      */
     async setStatInt(statName, value) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -215,23 +226,23 @@ class SteamStatsManager {
                 // Store the stats to Steam servers
                 const stored = this.libraryLoader.SteamAPI_ISteamUserStats_StoreStats(userStatsInterface);
                 if (stored) {
-                    console.log(`✅ Set stat "${statName}" to ${value}`);
+                    console.log(`[Steamworks] Set stat "${statName}" to ${value}`);
                     // Process callbacks
                     this.libraryLoader.SteamAPI_RunCallbacks();
                     return true;
                 }
                 else {
-                    console.warn(`⚠️ Failed to store stat: ${statName}`);
+                    console.warn(`[Steamworks] Failed to store stat: ${statName}`);
                     return false;
                 }
             }
             else {
-                console.warn(`⚠️ Failed to set stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to set stat: ${statName}`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error setting stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error setting stat "${statName}":`, error.message);
             return false;
         }
     }
@@ -266,7 +277,7 @@ class SteamStatsManager {
      */
     async setStatFloat(statName, value) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -276,23 +287,23 @@ class SteamStatsManager {
                 // Store the stats to Steam servers
                 const stored = this.libraryLoader.SteamAPI_ISteamUserStats_StoreStats(userStatsInterface);
                 if (stored) {
-                    console.log(`✅ Set stat "${statName}" to ${value}`);
+                    console.log(`[Steamworks] Set stat "${statName}" to ${value}`);
                     // Process callbacks
                     this.libraryLoader.SteamAPI_RunCallbacks();
                     return true;
                 }
                 else {
-                    console.warn(`⚠️ Failed to store stat: ${statName}`);
+                    console.warn(`[Steamworks] Failed to store stat: ${statName}`);
                     return false;
                 }
             }
             else {
-                console.warn(`⚠️ Failed to set stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to set stat: ${statName}`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error setting stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error setting stat "${statName}":`, error.message);
             return false;
         }
     }
@@ -329,7 +340,7 @@ class SteamStatsManager {
      */
     async updateAvgRateStat(statName, countThisSession, sessionLength) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -339,23 +350,23 @@ class SteamStatsManager {
                 // Store the stats to Steam servers
                 const stored = this.libraryLoader.SteamAPI_ISteamUserStats_StoreStats(userStatsInterface);
                 if (stored) {
-                    console.log(`✅ Updated avg rate stat "${statName}": ${countThisSession} over ${sessionLength}s`);
+                    console.log(`[Steamworks] Updated avg rate stat "${statName}": ${countThisSession} over ${sessionLength}s`);
                     // Process callbacks
                     this.libraryLoader.SteamAPI_RunCallbacks();
                     return true;
                 }
                 else {
-                    console.warn(`⚠️ Failed to store stat: ${statName}`);
+                    console.warn(`[Steamworks] Failed to store stat: ${statName}`);
                     return false;
                 }
             }
             else {
-                console.warn(`⚠️ Failed to update avg rate stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to update avg rate stat: ${statName}`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error updating avg rate stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error updating avg rate stat "${statName}":`, error.message);
             return false;
         }
     }
@@ -384,7 +395,7 @@ class SteamStatsManager {
      *
      *   // Now get the friend's stats
      *   const friendKills = await statsManager.getUserStatInt(friendSteamId, 'total_kills');
-     *   console.log(`Friend has ${friendKills} kills`);
+     *   console.log(`[Steamworks] Friend has ${friendKills} kills`);
      * }
      * ```
      *
@@ -399,7 +410,7 @@ class SteamStatsManager {
      */
     async requestUserStats(steamId) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -407,16 +418,16 @@ class SteamStatsManager {
             const steamIdBigInt = typeof steamId === 'string' ? BigInt(steamId) : steamId;
             const callHandle = this.libraryLoader.SteamAPI_ISteamUserStats_RequestUserStats(userStatsInterface, steamIdBigInt);
             if (callHandle !== BigInt(0)) {
-                console.log(`📡 Requested stats for user: ${steamId}`);
+                console.log(`[Steamworks] Requested stats for user: ${steamId}`);
                 return true;
             }
             else {
-                console.warn(`⚠️ Failed to request user stats: ${steamId}`);
+                console.warn(`[Steamworks] Failed to request user stats: ${steamId}`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error requesting user stats:`, error.message);
+            console.error(`[Steamworks] Error requesting user stats:`, error.message);
             return false;
         }
     }
@@ -428,7 +439,7 @@ class SteamStatsManager {
      *
      * @param steamId - Steam ID of the user
      * @param statName - Name of the stat to retrieve
-     * @returns The stat value, or null if not found or on error
+     * @returns UserStat object with steamId, name, value, and type, or null if not found or on error
      *
      * @example
      * ```typescript
@@ -437,23 +448,26 @@ class SteamStatsManager {
      * await statsManager.requestUserStats(friendId);
      * await new Promise(resolve => setTimeout(resolve, 100));
      *
-     * const myKills = await statsManager.getStatInt('total_kills') || 0;
-     * const friendKills = await statsManager.getUserStatInt(friendId, 'total_kills') || 0;
+     * const myStat = await statsManager.getStatInt('total_kills');
+     * const friendStat = await statsManager.getUserStatInt(friendId, 'total_kills');
      *
-     * console.log(`You: ${myKills}, Friend: ${friendKills}`);
+     * if (myStat && friendStat) {
+     *   console.log(`[Steamworks] You: ${myStat.value}, Friend: ${friendStat.value}`);
+     * }
      * ```
      *
      * @remarks
      * - Must call requestUserStats() first
      * - Wait 50-100ms after requesting before calling this
      * - Returns null if stats haven't arrived yet or user's stats are private
+     * - Returns structured UserStat object with full metadata including steamId
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetUserStatInt32()` - Get user's int32 stat value
      */
     async getUserStatInt(steamId, statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -463,16 +477,21 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetUserStatInt32(userStatsInterface, steamIdBigInt, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'int32');
-                console.log(`📊 Got user stat "${statName}" for ${steamId}: ${value}`);
-                return value;
+                console.log(`[Steamworks] Got user stat "${statName}" for ${steamId}: ${value}`);
+                return {
+                    steamId: typeof steamId === 'string' ? steamId : steamId.toString(),
+                    name: statName,
+                    value,
+                    type: 'int'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get user stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get user stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting user stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting user stat "${statName}":`, error.message);
             return null;
         }
     }
@@ -484,7 +503,7 @@ class SteamStatsManager {
      *
      * @param steamId - Steam ID of the user
      * @param statName - Name of the stat to retrieve
-     * @returns The stat value, or null if not found or on error
+     * @returns UserStat object with steamId, name, value, and type, or null if not found or on error
      *
      * @example
      * ```typescript
@@ -493,9 +512,9 @@ class SteamStatsManager {
      * await statsManager.requestUserStats(friendId);
      * await new Promise(resolve => setTimeout(resolve, 100));
      *
-     * const friendAccuracy = await statsManager.getUserStatFloat(friendId, 'shooting_accuracy');
-     * if (friendAccuracy !== null) {
-     *   console.log(`Friend accuracy: ${(friendAccuracy * 100).toFixed(2)}%`);
+     * const friendStat = await statsManager.getUserStatFloat(friendId, 'shooting_accuracy');
+     * if (friendStat) {
+     *   console.log(`[Steamworks] Friend accuracy: ${(friendStat.value * 100).toFixed(2)}%`);
      * }
      * ```
      *
@@ -503,13 +522,14 @@ class SteamStatsManager {
      * - Must call requestUserStats() first
      * - Wait 50-100ms after requesting before calling this
      * - Returns null if stats haven't arrived yet or user's stats are private
+     * - Returns structured UserStat object with full metadata including steamId
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetUserStatFloat()` - Get user's float stat value
      */
     async getUserStatFloat(steamId, statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -519,16 +539,21 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetUserStatFloat(userStatsInterface, steamIdBigInt, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'float');
-                console.log(`📊 Got user stat "${statName}" for ${steamId}: ${value}`);
-                return value;
+                console.log(`[Steamworks] Got user stat "${statName}" for ${steamId}: ${value}`);
+                return {
+                    steamId: typeof steamId === 'string' ? steamId : steamId.toString(),
+                    name: statName,
+                    value,
+                    type: 'float'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get user stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get user stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting user stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting user stat "${statName}":`, error.message);
             return null;
         }
     }
@@ -555,7 +580,7 @@ class SteamStatsManager {
      * await new Promise(resolve => setTimeout(resolve, 100));
      *
      * const totalKills = await statsManager.getGlobalStatInt('total_kills');
-     * console.log(`All players combined: ${totalKills} kills`);
+     * console.log(`[Steamworks] All players combined: ${totalKills} kills`);
      * ```
      *
      * @remarks
@@ -570,7 +595,7 @@ class SteamStatsManager {
      */
     async requestGlobalStats(historyDays = 0) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -579,16 +604,16 @@ class SteamStatsManager {
             const userStatsInterface = this.libraryLoader.SteamAPI_SteamUserStats_v013();
             const callHandle = this.libraryLoader.SteamAPI_ISteamUserStats_RequestGlobalStats(userStatsInterface, days);
             if (callHandle !== BigInt(0)) {
-                console.log(`📡 Requested global stats with ${days} days of history`);
+                console.log(`[Steamworks] Requested global stats with ${days} days of history`);
                 return true;
             }
             else {
-                console.warn(`⚠️ Failed to request global stats`);
+                console.warn(`[Steamworks] Failed to request global stats`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error requesting global stats:`, error.message);
+            console.error(`[Steamworks] Error requesting global stats:`, error.message);
             return false;
         }
     }
@@ -599,7 +624,7 @@ class SteamStatsManager {
      * Must call requestGlobalStats() first and wait for the data to arrive.
      *
      * @param statName - Name of the global stat to retrieve
-     * @returns The stat value as BigInt, or null if not found or on error
+     * @returns GlobalStat object with name, value, and type, or null if not found or on error
      *
      * @example
      * ```typescript
@@ -607,24 +632,25 @@ class SteamStatsManager {
      * await statsManager.requestGlobalStats();
      * await new Promise(resolve => setTimeout(resolve, 100));
      *
-     * const globalKills = await statsManager.getGlobalStatInt('total_kills');
-     * if (globalKills !== null) {
-     *   console.log(`All players have ${globalKills} total kills`);
+     * const globalStat = await statsManager.getGlobalStatInt('total_kills');
+     * if (globalStat) {
+     *   console.log(`[Steamworks] ${globalStat.name}: ${globalStat.value}`);
      * }
      * ```
      *
      * @remarks
-     * - Returns BigInt for large numbers (can exceed JavaScript's safe integer range)
      * - Must call requestGlobalStats() first
      * - Wait 50-100ms after requesting before calling this
      * - Useful for tracking game-wide statistics
+     * - Returns structured GlobalStat object with full metadata
+     * - Value is number (BigInt converted to number for consistency)
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetGlobalStatInt64()` - Get global int64 stat value
      */
     async getGlobalStatInt(statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -633,16 +659,20 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetGlobalStatInt64(userStatsInterface, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'int64');
-                console.log(`🌍 Got global stat "${statName}": ${value}`);
-                return value;
+                console.log(`[Steamworks] Got global stat "${statName}": ${value}`);
+                return {
+                    name: statName,
+                    value: Number(value),
+                    type: 'int64'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get global stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get global stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting global stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting global stat "${statName}":`, error.message);
             return null;
         }
     }
@@ -654,7 +684,7 @@ class SteamStatsManager {
      * Use this for averages or stats requiring decimal precision.
      *
      * @param statName - Name of the global stat to retrieve
-     * @returns The stat value, or null if not found or on error
+     * @returns GlobalStat object with name, value, and type, or null if not found or on error
      *
      * @example
      * ```typescript
@@ -662,9 +692,9 @@ class SteamStatsManager {
      * await statsManager.requestGlobalStats();
      * await new Promise(resolve => setTimeout(resolve, 100));
      *
-     * const avgAccuracy = await statsManager.getGlobalStatDouble('average_accuracy');
-     * if (avgAccuracy !== null) {
-     *   console.log(`Global average accuracy: ${(avgAccuracy * 100).toFixed(2)}%`);
+     * const avgStat = await statsManager.getGlobalStatDouble('average_accuracy');
+     * if (avgStat) {
+     *   console.log(`[Steamworks] ${avgStat.name}: ${(avgStat.value * 100).toFixed(2)}%`);
      * }
      * ```
      *
@@ -673,13 +703,14 @@ class SteamStatsManager {
      * - Must call requestGlobalStats() first
      * - Wait 50-100ms after requesting before calling this
      * - Perfect for calculating game-wide averages
+     * - Returns structured GlobalStat object with full metadata
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetGlobalStatDouble()` - Get global double stat value
      */
     async getGlobalStatDouble(statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -688,16 +719,20 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetGlobalStatDouble(userStatsInterface, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'double');
-                console.log(`🌍 Got global stat "${statName}": ${value}`);
-                return value;
+                console.log(`[Steamworks] Got global stat "${statName}": ${value}`);
+                return {
+                    name: statName,
+                    value,
+                    type: 'double'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get global stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get global stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting global stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting global stat "${statName}":`, error.message);
             return null;
         }
     }
@@ -709,7 +744,7 @@ class SteamStatsManager {
      *
      * @param statName - Name of the global stat
      * @param days - Number of days of history to retrieve (1-60, default: 7)
-     * @returns Array of daily BigInt values, or null if error
+     * @returns GlobalStatHistory object with name, history array, and type, or null if error
      *
      * @example
      * ```typescript
@@ -719,10 +754,10 @@ class SteamStatsManager {
      *
      * const history = await statsManager.getGlobalStatHistoryInt('total_kills', 7);
      * if (history) {
-     *   console.log('Kill history (newest to oldest):');
-     *   history.forEach((kills, index) => {
+     *   console.log(`[Steamworks] ${history.name} history (${history.type}):`);
+     *   history.history.forEach((kills, index) => {
      *     const daysAgo = index === 0 ? 'today' : `${index} days ago`;
-     *     console.log(`  ${daysAgo}: ${kills} kills`);
+     *     console.log(`[Steamworks]   ${daysAgo}: ${kills} kills`);
      *   });
      * }
      * ```
@@ -730,7 +765,8 @@ class SteamStatsManager {
      * @remarks
      * - Array index [0] = today, [1] = yesterday, etc.
      * - Must call requestGlobalStats(days) first with same or greater number of days
-     * - Returns BigInt values for large numbers
+     * - Returns structured GlobalStatHistory object with full metadata
+     * - Values are numbers (BigInt converted to number for consistency)
      * - Maximum 60 days of history (automatically clamped)
      * - Perfect for trend analysis and visualizations
      *
@@ -739,7 +775,7 @@ class SteamStatsManager {
      */
     async getGlobalStatHistoryInt(statName, days = 7) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -751,18 +787,22 @@ class SteamStatsManager {
             if (elementsReturned > 0) {
                 const history = [];
                 for (let i = 0; i < elementsReturned; i++) {
-                    history.push(koffi.decode(historyOut, 'int64', i));
+                    history.push(Number(koffi.decode(historyOut, 'int64', i))); // Convert BigInt to number
                 }
-                console.log(`🌍 Got ${elementsReturned} days of history for "${statName}"`);
-                return history;
+                console.log(`[Steamworks] Got ${elementsReturned} days of history for "${statName}"`);
+                return {
+                    name: statName,
+                    history,
+                    type: 'int64'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get global stat history: ${statName}`);
+                console.warn(`[Steamworks] Failed to get global stat history: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting global stat history "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting global stat history "${statName}":`, error.message);
             return null;
         }
     }
@@ -775,7 +815,7 @@ class SteamStatsManager {
      *
      * @param statName - Name of the global stat
      * @param days - Number of days of history to retrieve (1-60, default: 7)
-     * @returns Array of daily float values, or null if error
+     * @returns GlobalStatHistory object with name, history array, and type, or null if error
      *
      * @example
      * ```typescript
@@ -785,10 +825,10 @@ class SteamStatsManager {
      *
      * const history = await statsManager.getGlobalStatHistoryDouble('average_accuracy', 30);
      * if (history) {
-     *   console.log('Accuracy trend:');
-     *   history.forEach((accuracy, index) => {
+     *   console.log(`[Steamworks] ${history.name} trend (${history.type}):`);
+     *   history.history.forEach((accuracy, index) => {
      *     if (index % 7 === 0) { // Weekly intervals
-     *       console.log(`  Week ${index/7}: ${(accuracy * 100).toFixed(2)}%`);
+     *       console.log(`[Steamworks]   Week ${index/7}: ${(accuracy * 100).toFixed(2)}%`);
      *     }
      *   });
      * }
@@ -797,6 +837,7 @@ class SteamStatsManager {
      * @remarks
      * - Array index [0] = today, [1] = yesterday, etc.
      * - Must call requestGlobalStats(days) first with same or greater number of days
+     * - Returns structured GlobalStatHistory object with full metadata
      * - Returns floating-point values for decimal precision
      * - Maximum 60 days of history (automatically clamped)
      * - Perfect for tracking averages, rates, and percentages over time
@@ -806,7 +847,7 @@ class SteamStatsManager {
      */
     async getGlobalStatHistoryDouble(statName, days = 7) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -820,16 +861,20 @@ class SteamStatsManager {
                 for (let i = 0; i < elementsReturned; i++) {
                     history.push(koffi.decode(historyOut, 'double', i));
                 }
-                console.log(`🌍 Got ${elementsReturned} days of history for "${statName}"`);
-                return history;
+                console.log(`[Steamworks] Got ${elementsReturned} days of history for "${statName}"`);
+                return {
+                    name: statName,
+                    history,
+                    type: 'double'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get global stat history: ${statName}`);
+                console.warn(`[Steamworks] Failed to get global stat history: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting global stat history "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting global stat history "${statName}":`, error.message);
             return null;
         }
     }