steamworks-ffi-node 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +86 -10
  2. package/dist/index.d.ts +2 -2
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +6 -1
  5. package/dist/index.js.map +1 -1
  6. package/dist/internal/SteamAPICore.d.ts +221 -8
  7. package/dist/internal/SteamAPICore.d.ts.map +1 -1
  8. package/dist/internal/SteamAPICore.js +234 -14
  9. package/dist/internal/SteamAPICore.js.map +1 -1
  10. package/dist/internal/SteamAchievementManager.d.ts +602 -31
  11. package/dist/internal/SteamAchievementManager.d.ts.map +1 -1
  12. package/dist/internal/SteamAchievementManager.js +601 -32
  13. package/dist/internal/SteamAchievementManager.js.map +1 -1
  14. package/dist/internal/SteamCallbackPoller.d.ts +68 -0
  15. package/dist/internal/SteamCallbackPoller.d.ts.map +1 -0
  16. package/dist/internal/SteamCallbackPoller.js +134 -0
  17. package/dist/internal/SteamCallbackPoller.js.map +1 -0
  18. package/dist/internal/SteamLeaderboardManager.d.ts +338 -0
  19. package/dist/internal/SteamLeaderboardManager.d.ts.map +1 -0
  20. package/dist/internal/SteamLeaderboardManager.js +734 -0
  21. package/dist/internal/SteamLeaderboardManager.js.map +1 -0
  22. package/dist/internal/SteamLibraryLoader.d.ts +15 -0
  23. package/dist/internal/SteamLibraryLoader.d.ts.map +1 -1
  24. package/dist/internal/SteamLibraryLoader.js +42 -5
  25. package/dist/internal/SteamLibraryLoader.js.map +1 -1
  26. package/dist/internal/SteamStatsManager.d.ts +357 -50
  27. package/dist/internal/SteamStatsManager.d.ts.map +1 -1
  28. package/dist/internal/SteamStatsManager.js +444 -106
  29. package/dist/internal/SteamStatsManager.js.map +1 -1
  30. package/dist/steam.d.ts +169 -9
  31. package/dist/steam.d.ts.map +1 -1
  32. package/dist/steam.js +178 -0
  33. package/dist/steam.js.map +1 -1
  34. package/dist/types.d.ts +91 -0
  35. package/dist/types.d.ts.map +1 -1
  36. package/dist/types.js +34 -0
  37. package/dist/types.js.map +1 -1
  38. package/package.json +4 -3
@@ -1,40 +1,124 @@
1
1
  import { SteamLibraryLoader } from './SteamLibraryLoader';
2
2
  import { SteamAPICore } from './SteamAPICore';
3
+ import { SteamStat, GlobalStat, GlobalStatHistory, UserStat } from '../types';
3
4
  /**
4
- * Manages Steam user statistics operations
5
- * Handles getting/setting stats, global stats, and friend stats
5
+ * SteamStatsManager
6
+ *
7
+ * Manages all Steam user statistics operations including:
8
+ * - User stats (get/set integer and float values)
9
+ * - Average rate stats (for tracking rates over time)
10
+ * - Friend/user stats (view stats of other players)
11
+ * - Global stats (aggregate statistics across all players)
12
+ * - Global stat history (historical data over time)
13
+ *
14
+ * Stats are different from achievements - they are numeric values that can increase/decrease
15
+ * and are used for leaderboards, progress tracking, and game analytics.
16
+ *
17
+ * @example
18
+ * ```typescript
19
+ * const statsManager = new SteamStatsManager(libraryLoader, apiCore);
20
+ *
21
+ * // Set and get player stats
22
+ * await statsManager.setStatInt('total_kills', 100);
23
+ * const kills = await statsManager.getStatInt('total_kills');
24
+ *
25
+ * // Get global stats
26
+ * await statsManager.requestGlobalStats(7);
27
+ * const globalKills = await statsManager.getGlobalStatInt('total_kills');
28
+ * ```
6
29
  */
7
30
  export declare class SteamStatsManager {
31
+ /** Steam library loader for FFI function calls */
8
32
  private libraryLoader;
33
+ /** Steam API core for initialization and callback management */
9
34
  private apiCore;
35
+ /**
36
+ * Creates a new SteamStatsManager instance
37
+ *
38
+ * @param libraryLoader - The Steam library loader for FFI calls
39
+ * @param apiCore - The Steam API core for lifecycle management
40
+ */
10
41
  constructor(libraryLoader: SteamLibraryLoader, apiCore: SteamAPICore);
11
42
  /**
12
- * Get an integer stat value
43
+ * Get an integer stat value for the current user
13
44
  *
14
- * @param statName - Name of the stat to retrieve
15
- * @returns The stat value, or null if not found/error
45
+ * Retrieves a 32-bit integer stat value from Steam. Stats are numeric values
46
+ * that track player progress and can be used for leaderboards and analytics.
47
+ *
48
+ * @param statName - Name of the stat to retrieve (as defined in Steamworks Partner site)
49
+ * @returns SteamStat object with name, value, and type, or null if not found or on error
50
+ *
51
+ * @example
52
+ * ```typescript
53
+ * const killsStat = await statsManager.getStatInt('total_kills');
54
+ * if (killsStat) {
55
+ * console.log(`[Steamworks] ${killsStat.name}: ${killsStat.value}`);
56
+ * // Access value directly: killsStat.value
57
+ * }
58
+ * ```
59
+ *
60
+ * @remarks
61
+ * - Returns null if Steam API is not initialized
62
+ * - Stat names are case-sensitive and must match Steamworks configuration
63
+ * - Use getStatFloat() for decimal values
64
+ * - Returns structured SteamStat object with full metadata
16
65
  *
17
66
  * Steamworks SDK Functions:
18
67
  * - `SteamAPI_ISteamUserStats_GetStatInt32()` - Get int32 stat value
19
68
  */
20
- getStatInt(statName: string): Promise<number | null>;
69
+ getStatInt(statName: string): Promise<SteamStat | null>;
21
70
  /**
22
- * Get a float stat value
71
+ * Get a float stat value for the current user
23
72
  *
24
- * @param statName - Name of the stat to retrieve
25
- * @returns The stat value, or null if not found/error
73
+ * Retrieves a floating-point stat value from Steam. Use this for stats that
74
+ * require decimal precision (e.g., average accuracy, distance traveled).
75
+ *
76
+ * @param statName - Name of the stat to retrieve (as defined in Steamworks Partner site)
77
+ * @returns SteamStat object with name, value, and type, or null if not found or on error
78
+ *
79
+ * @example
80
+ * ```typescript
81
+ * const accuracyStat = await statsManager.getStatFloat('shooting_accuracy');
82
+ * if (accuracyStat) {
83
+ * console.log(`[Steamworks] ${accuracyStat.name}: ${(accuracyStat.value * 100).toFixed(2)}%`);
84
+ * }
85
+ * ```
86
+ *
87
+ * @remarks
88
+ * - Returns null if Steam API is not initialized
89
+ * - Use getStatInt() for whole number values
90
+ * - Returns structured SteamStat object with full metadata
26
91
  *
27
92
  * Steamworks SDK Functions:
28
93
  * - `SteamAPI_ISteamUserStats_GetStatFloat()` - Get float stat value
29
94
  */
30
- getStatFloat(statName: string): Promise<number | null>;
95
+ getStatFloat(statName: string): Promise<SteamStat | null>;
31
96
  /**
32
- * Set an integer stat value
97
+ * Set an integer stat value for the current user
33
98
  *
34
- * @param statName - Name of the stat to set
99
+ * Updates a 32-bit integer stat value and immediately stores it to Steam servers.
100
+ * The new value will be visible in your Steam profile and can trigger achievements.
101
+ *
102
+ * @param statName - Name of the stat to set (as defined in Steamworks Partner site)
35
103
  * @param value - Integer value to set
36
104
  * @returns true if successful, false otherwise
37
105
  *
106
+ * @example
107
+ * ```typescript
108
+ * // Increment kill count
109
+ * const currentKills = await statsManager.getStatInt('total_kills') || 0;
110
+ * const success = await statsManager.setStatInt('total_kills', currentKills + 1);
111
+ * if (success) {
112
+ * console.log('[Steamworks] Kill count updated!');
113
+ * }
114
+ * ```
115
+ *
116
+ * @remarks
117
+ * - Automatically calls StoreStats() to save to Steam servers
118
+ * - Runs callbacks to process the store operation
119
+ * - Can trigger stat-based achievements
120
+ * - Use setStatFloat() for decimal values
121
+ *
38
122
  * Steamworks SDK Functions:
39
123
  * - `SteamAPI_ISteamUserStats_SetStatInt32()` - Set int32 stat value
40
124
  * - `SteamAPI_ISteamUserStats_StoreStats()` - Store stats to Steam servers
@@ -42,12 +126,29 @@ export declare class SteamStatsManager {
42
126
  */
43
127
  setStatInt(statName: string, value: number): Promise<boolean>;
44
128
  /**
45
- * Set a float stat value
129
+ * Set a float stat value for the current user
46
130
  *
47
- * @param statName - Name of the stat to set
131
+ * Updates a floating-point stat value and immediately stores it to Steam servers.
132
+ * Use this for stats requiring decimal precision.
133
+ *
134
+ * @param statName - Name of the stat to set (as defined in Steamworks Partner site)
48
135
  * @param value - Float value to set
49
136
  * @returns true if successful, false otherwise
50
137
  *
138
+ * @example
139
+ * ```typescript
140
+ * // Update accuracy based on hits/shots
141
+ * const hits = 85;
142
+ * const shots = 100;
143
+ * const accuracy = hits / shots; // 0.85
144
+ * await statsManager.setStatFloat('shooting_accuracy', accuracy);
145
+ * ```
146
+ *
147
+ * @remarks
148
+ * - Automatically calls StoreStats() to save to Steam servers
149
+ * - Runs callbacks to process the store operation
150
+ * - Use setStatInt() for whole number values
151
+ *
51
152
  * Steamworks SDK Functions:
52
153
  * - `SteamAPI_ISteamUserStats_SetStatFloat()` - Set float stat value
53
154
  * - `SteamAPI_ISteamUserStats_StoreStats()` - Store stats to Steam servers
@@ -56,13 +157,30 @@ export declare class SteamStatsManager {
56
157
  setStatFloat(statName: string, value: number): Promise<boolean>;
57
158
  /**
58
159
  * Update an average rate stat
59
- * This is used for stats like "average speed" or "kills per hour"
60
160
  *
61
- * @param statName - Name of the stat to update
62
- * @param countThisSession - Count for this session
161
+ * Updates stats that represent rates or averages over time (e.g., "kills per hour",
162
+ * "average speed"). Steam automatically maintains the average calculation.
163
+ *
164
+ * @param statName - Name of the stat to update (as defined in Steamworks Partner site)
165
+ * @param countThisSession - Count/value for this session (e.g., kills this session)
63
166
  * @param sessionLength - Length of session in seconds
64
167
  * @returns true if successful, false otherwise
65
168
  *
169
+ * @example
170
+ * ```typescript
171
+ * // Update kills per hour stat
172
+ * const sessionKills = 25;
173
+ * const sessionSeconds = 1800; // 30 minutes
174
+ * await statsManager.updateAvgRateStat('kills_per_hour', sessionKills, sessionSeconds);
175
+ * // Steam calculates: (25 / 1800) * 3600 = 50 kills/hour
176
+ * ```
177
+ *
178
+ * @remarks
179
+ * - Automatically calls StoreStats() to save to Steam servers
180
+ * - Steam maintains the running average across all sessions
181
+ * - sessionLength should be in seconds
182
+ * - Used for "per hour" or "per game" statistics
183
+ *
66
184
  * Steamworks SDK Functions:
67
185
  * - `SteamAPI_ISteamUserStats_UpdateAvgRateStat()` - Update average rate stat
68
186
  * - `SteamAPI_ISteamUserStats_StoreStats()` - Store stats to Steam servers
@@ -71,95 +189,284 @@ export declare class SteamStatsManager {
71
189
  updateAvgRateStat(statName: string, countThisSession: number, sessionLength: number): Promise<boolean>;
72
190
  /**
73
191
  * Request stats for another user (friend)
74
- * Must be called before getting user stats
192
+ *
193
+ * Requests stat data from Steam servers for a specific user. Must be called
194
+ * before getting user stats with getUserStatInt() or getUserStatFloat().
195
+ * This is an asynchronous operation - wait a moment before reading the stats.
75
196
  *
76
197
  * @param steamId - Steam ID of the user (as string or BigInt)
77
- * @returns true if request was sent, false otherwise
198
+ * @returns true if request was sent successfully, false otherwise
199
+ *
200
+ * @example
201
+ * ```typescript
202
+ * const friendSteamId = '76561198012345678';
203
+ *
204
+ * // Request the friend's stats
205
+ * const success = await statsManager.requestUserStats(friendSteamId);
206
+ * if (success) {
207
+ * // Wait a moment for Steam to fetch the data
208
+ * await new Promise(resolve => setTimeout(resolve, 100));
209
+ *
210
+ * // Now get the friend's stats
211
+ * const friendKills = await statsManager.getUserStatInt(friendSteamId, 'total_kills');
212
+ * console.log(`[Steamworks] Friend has ${friendKills} kills`);
213
+ * }
214
+ * ```
215
+ *
216
+ * @remarks
217
+ * - Must be called before getting user stats
218
+ * - Returns true immediately if request was sent (not when data arrives)
219
+ * - Wait 50-100ms after requesting before reading stats
220
+ * - User's stats must be public for this to work
78
221
  *
79
222
  * Steamworks SDK Functions:
80
- * - `SteamAPI_ISteamUserStats_RequestUserStats()` - Request user stats from Steam
223
+ * - `SteamAPI_ISteamUserStats_RequestUserStats()` - Request user stats from Steam servers
81
224
  */
82
225
  requestUserStats(steamId: string | bigint): Promise<boolean>;
83
226
  /**
84
227
  * Get an integer stat value for another user (friend)
85
- * Must call requestUserStats() first and wait for callback
228
+ *
229
+ * Retrieves a 32-bit integer stat value for a specific user. Must call
230
+ * requestUserStats() first and wait for the data to arrive.
86
231
  *
87
232
  * @param steamId - Steam ID of the user
88
233
  * @param statName - Name of the stat to retrieve
89
- * @returns The stat value, or null if not found/error
234
+ * @returns UserStat object with steamId, name, value, and type, or null if not found or on error
235
+ *
236
+ * @example
237
+ * ```typescript
238
+ * // Compare your kills to a friend's
239
+ * const friendId = '76561198012345678';
240
+ * await statsManager.requestUserStats(friendId);
241
+ * await new Promise(resolve => setTimeout(resolve, 100));
242
+ *
243
+ * const myStat = await statsManager.getStatInt('total_kills');
244
+ * const friendStat = await statsManager.getUserStatInt(friendId, 'total_kills');
245
+ *
246
+ * if (myStat && friendStat) {
247
+ * console.log(`[Steamworks] You: ${myStat.value}, Friend: ${friendStat.value}`);
248
+ * }
249
+ * ```
250
+ *
251
+ * @remarks
252
+ * - Must call requestUserStats() first
253
+ * - Wait 50-100ms after requesting before calling this
254
+ * - Returns null if stats haven't arrived yet or user's stats are private
255
+ * - Returns structured UserStat object with full metadata including steamId
90
256
  *
91
257
  * Steamworks SDK Functions:
92
258
  * - `SteamAPI_ISteamUserStats_GetUserStatInt32()` - Get user's int32 stat value
93
259
  */
94
- getUserStatInt(steamId: string | bigint, statName: string): Promise<number | null>;
260
+ getUserStatInt(steamId: string | bigint, statName: string): Promise<UserStat | null>;
95
261
  /**
96
262
  * Get a float stat value for another user (friend)
97
- * Must call requestUserStats() first and wait for callback
263
+ *
264
+ * Retrieves a floating-point stat value for a specific user. Must call
265
+ * requestUserStats() first and wait for the data to arrive.
98
266
  *
99
267
  * @param steamId - Steam ID of the user
100
268
  * @param statName - Name of the stat to retrieve
101
- * @returns The stat value, or null if not found/error
269
+ * @returns UserStat object with steamId, name, value, and type, or null if not found or on error
270
+ *
271
+ * @example
272
+ * ```typescript
273
+ * // Compare accuracy with a friend
274
+ * const friendId = '76561198012345678';
275
+ * await statsManager.requestUserStats(friendId);
276
+ * await new Promise(resolve => setTimeout(resolve, 100));
277
+ *
278
+ * const friendStat = await statsManager.getUserStatFloat(friendId, 'shooting_accuracy');
279
+ * if (friendStat) {
280
+ * console.log(`[Steamworks] Friend accuracy: ${(friendStat.value * 100).toFixed(2)}%`);
281
+ * }
282
+ * ```
283
+ *
284
+ * @remarks
285
+ * - Must call requestUserStats() first
286
+ * - Wait 50-100ms after requesting before calling this
287
+ * - Returns null if stats haven't arrived yet or user's stats are private
288
+ * - Returns structured UserStat object with full metadata including steamId
102
289
  *
103
290
  * Steamworks SDK Functions:
104
291
  * - `SteamAPI_ISteamUserStats_GetUserStatFloat()` - Get user's float stat value
105
292
  */
106
- getUserStatFloat(steamId: string | bigint, statName: string): Promise<number | null>;
293
+ getUserStatFloat(steamId: string | bigint, statName: string): Promise<UserStat | null>;
107
294
  /**
108
295
  * Request global stats data from Steam
109
- * Must be called before getting global stats
110
296
  *
111
- * @param historyDays - Number of days of history to retrieve (0-60)
112
- * @returns true if request was sent, false otherwise
297
+ * Requests aggregated statistics across all players from Steam servers.
298
+ * Optionally includes historical data for trend analysis.
299
+ * Must be called before getting global stats.
300
+ *
301
+ * @param historyDays - Number of days of history to retrieve (0-60, default: 0)
302
+ * @returns true if request was sent successfully, false otherwise
303
+ *
304
+ * @example
305
+ * ```typescript
306
+ * // Request current global stats (no history)
307
+ * await statsManager.requestGlobalStats(0);
308
+ *
309
+ * // Request with 7 days of history for trends
310
+ * await statsManager.requestGlobalStats(7);
311
+ * await new Promise(resolve => setTimeout(resolve, 100));
312
+ *
313
+ * const totalKills = await statsManager.getGlobalStatInt('total_kills');
314
+ * console.log(`[Steamworks] All players combined: ${totalKills} kills`);
315
+ * ```
316
+ *
317
+ * @remarks
318
+ * - Must be called before getting global stats
319
+ * - Returns true immediately if request was sent (not when data arrives)
320
+ * - Wait 50-100ms after requesting before reading stats
321
+ * - historyDays is automatically clamped to 0-60 range
322
+ * - Historical data allows tracking trends over time
113
323
  *
114
324
  * Steamworks SDK Functions:
115
- * - `SteamAPI_ISteamUserStats_RequestGlobalStats()` - Request global stats from Steam
325
+ * - `SteamAPI_ISteamUserStats_RequestGlobalStats()` - Request global stats from Steam servers
116
326
  */
117
327
  requestGlobalStats(historyDays?: number): Promise<boolean>;
118
328
  /**
119
- * Get a global stat value (int64)
120
- * Must call requestGlobalStats() first and wait for callback
329
+ * Get a global stat value (64-bit integer)
330
+ *
331
+ * Retrieves an aggregated integer stat value across all players.
332
+ * Must call requestGlobalStats() first and wait for the data to arrive.
121
333
  *
122
334
  * @param statName - Name of the global stat to retrieve
123
- * @returns The stat value, or null if not found/error
335
+ * @returns GlobalStat object with name, value, and type, or null if not found or on error
336
+ *
337
+ * @example
338
+ * ```typescript
339
+ * // Get total kills across all players
340
+ * await statsManager.requestGlobalStats();
341
+ * await new Promise(resolve => setTimeout(resolve, 100));
342
+ *
343
+ * const globalStat = await statsManager.getGlobalStatInt('total_kills');
344
+ * if (globalStat) {
345
+ * console.log(`[Steamworks] ${globalStat.name}: ${globalStat.value}`);
346
+ * }
347
+ * ```
348
+ *
349
+ * @remarks
350
+ * - Must call requestGlobalStats() first
351
+ * - Wait 50-100ms after requesting before calling this
352
+ * - Useful for tracking game-wide statistics
353
+ * - Returns structured GlobalStat object with full metadata
354
+ * - Value is number (BigInt converted to number for consistency)
124
355
  *
125
356
  * Steamworks SDK Functions:
126
357
  * - `SteamAPI_ISteamUserStats_GetGlobalStatInt64()` - Get global int64 stat value
127
358
  */
128
- getGlobalStatInt(statName: string): Promise<bigint | null>;
359
+ getGlobalStatInt(statName: string): Promise<GlobalStat | null>;
129
360
  /**
130
- * Get a global stat value (double)
131
- * Must call requestGlobalStats() first and wait for callback
361
+ * Get a global stat value (double-precision float)
362
+ *
363
+ * Retrieves an aggregated floating-point stat value across all players.
364
+ * Must call requestGlobalStats() first and wait for the data to arrive.
365
+ * Use this for averages or stats requiring decimal precision.
132
366
  *
133
367
  * @param statName - Name of the global stat to retrieve
134
- * @returns The stat value, or null if not found/error
368
+ * @returns GlobalStat object with name, value, and type, or null if not found or on error
369
+ *
370
+ * @example
371
+ * ```typescript
372
+ * // Get average accuracy across all players
373
+ * await statsManager.requestGlobalStats();
374
+ * await new Promise(resolve => setTimeout(resolve, 100));
375
+ *
376
+ * const avgStat = await statsManager.getGlobalStatDouble('average_accuracy');
377
+ * if (avgStat) {
378
+ * console.log(`[Steamworks] ${avgStat.name}: ${(avgStat.value * 100).toFixed(2)}%`);
379
+ * }
380
+ * ```
381
+ *
382
+ * @remarks
383
+ * - Use for stats requiring decimal precision
384
+ * - Must call requestGlobalStats() first
385
+ * - Wait 50-100ms after requesting before calling this
386
+ * - Perfect for calculating game-wide averages
387
+ * - Returns structured GlobalStat object with full metadata
135
388
  *
136
389
  * Steamworks SDK Functions:
137
390
  * - `SteamAPI_ISteamUserStats_GetGlobalStatDouble()` - Get global double stat value
138
391
  */
139
- getGlobalStatDouble(statName: string): Promise<number | null>;
392
+ getGlobalStatDouble(statName: string): Promise<GlobalStat | null>;
140
393
  /**
141
- * Get global stat history (int64)
142
- * Returns daily values for the stat, with [0] being today, [1] yesterday, etc.
394
+ * Get global stat history for an integer stat
395
+ *
396
+ * Retrieves historical daily values for a global stat. Array index [0] is today,
397
+ * [1] is yesterday, etc. Useful for tracking trends and creating graphs.
143
398
  *
144
399
  * @param statName - Name of the global stat
145
- * @param days - Number of days of history to retrieve (max 60)
146
- * @returns Array of daily values, or null if error
400
+ * @param days - Number of days of history to retrieve (1-60, default: 7)
401
+ * @returns GlobalStatHistory object with name, history array, and type, or null if error
402
+ *
403
+ * @example
404
+ * ```typescript
405
+ * // Get 7 days of global kill history
406
+ * await statsManager.requestGlobalStats(7);
407
+ * await new Promise(resolve => setTimeout(resolve, 100));
408
+ *
409
+ * const history = await statsManager.getGlobalStatHistoryInt('total_kills', 7);
410
+ * if (history) {
411
+ * console.log(`[Steamworks] ${history.name} history (${history.type}):`);
412
+ * history.history.forEach((kills, index) => {
413
+ * const daysAgo = index === 0 ? 'today' : `${index} days ago`;
414
+ * console.log(`[Steamworks] ${daysAgo}: ${kills} kills`);
415
+ * });
416
+ * }
417
+ * ```
418
+ *
419
+ * @remarks
420
+ * - Array index [0] = today, [1] = yesterday, etc.
421
+ * - Must call requestGlobalStats(days) first with same or greater number of days
422
+ * - Returns structured GlobalStatHistory object with full metadata
423
+ * - Values are numbers (BigInt converted to number for consistency)
424
+ * - Maximum 60 days of history (automatically clamped)
425
+ * - Perfect for trend analysis and visualizations
147
426
  *
148
427
  * Steamworks SDK Functions:
149
- * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryInt64()` - Get global stat history
428
+ * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryInt64()` - Get historical int64 values
150
429
  */
151
- getGlobalStatHistoryInt(statName: string, days?: number): Promise<bigint[] | null>;
430
+ getGlobalStatHistoryInt(statName: string, days?: number): Promise<GlobalStatHistory | null>;
152
431
  /**
153
- * Get global stat history (double)
154
- * Returns daily values for the stat, with [0] being today, [1] yesterday, etc.
432
+ * Get global stat history for a floating-point stat
433
+ *
434
+ * Retrieves historical daily values for a global stat with decimal precision.
435
+ * Array index [0] is today, [1] is yesterday, etc. Ideal for tracking averages
436
+ * and rates over time.
155
437
  *
156
438
  * @param statName - Name of the global stat
157
- * @param days - Number of days of history to retrieve (max 60)
158
- * @returns Array of daily values, or null if error
439
+ * @param days - Number of days of history to retrieve (1-60, default: 7)
440
+ * @returns GlobalStatHistory object with name, history array, and type, or null if error
441
+ *
442
+ * @example
443
+ * ```typescript
444
+ * // Track average accuracy trend over 30 days
445
+ * await statsManager.requestGlobalStats(30);
446
+ * await new Promise(resolve => setTimeout(resolve, 100));
447
+ *
448
+ * const history = await statsManager.getGlobalStatHistoryDouble('average_accuracy', 30);
449
+ * if (history) {
450
+ * console.log(`[Steamworks] ${history.name} trend (${history.type}):`);
451
+ * history.history.forEach((accuracy, index) => {
452
+ * if (index % 7 === 0) { // Weekly intervals
453
+ * console.log(`[Steamworks] Week ${index/7}: ${(accuracy * 100).toFixed(2)}%`);
454
+ * }
455
+ * });
456
+ * }
457
+ * ```
458
+ *
459
+ * @remarks
460
+ * - Array index [0] = today, [1] = yesterday, etc.
461
+ * - Must call requestGlobalStats(days) first with same or greater number of days
462
+ * - Returns structured GlobalStatHistory object with full metadata
463
+ * - Returns floating-point values for decimal precision
464
+ * - Maximum 60 days of history (automatically clamped)
465
+ * - Perfect for tracking averages, rates, and percentages over time
159
466
  *
160
467
  * Steamworks SDK Functions:
161
- * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryDouble()` - Get global stat history
468
+ * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryDouble()` - Get historical double values
162
469
  */
163
- getGlobalStatHistoryDouble(statName: string, days?: number): Promise<number[] | null>;
470
+ getGlobalStatHistoryDouble(statName: string, days?: number): Promise<GlobalStatHistory | null>;
164
471
  }
165
472
  //# sourceMappingURL=SteamStatsManager.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"SteamStatsManager.d.ts","sourceRoot":"","sources":["../../src/internal/SteamStatsManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,OAAO,CAAe;gBAElB,aAAa,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY;IASpE;;;;;;;;OAQG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8B1D;;;;;;;;OAQG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8B5D;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqCnE;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqCrE;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0C5G;;;;;;;;;OASG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BlE;;;;;;;;;;OAUG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgCxF;;;;;;;;;;OAUG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAoC1F;;;;;;;;;OASG;IACG,kBAAkB,CAAC,WAAW,GAAE,MAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BnE;;;;;;;;;OASG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8BhE;;;;;;;;;OASG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8BnE;;;;;;;;;;OAUG;IACG,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;IAqC3F;;;;;;;;;;OAUG;IACG,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;CAoC/F"}
1
+ {"version":3,"file":"SteamStatsManager.d.ts","sourceRoot":"","sources":["../../src/internal/SteamStatsManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,iBAAiB;IAC5B,kDAAkD;IAClD,OAAO,CAAC,aAAa,CAAqB;IAE1C,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAe;IAE9B;;;;;OAKG;gBACS,aAAa,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY;IASpE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAkC7D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAkC/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0C5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAqC1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAyC5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,kBAAkB,CAAC,WAAW,GAAE,MAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkCpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkCvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAyCpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CAwCxG"}