Expose weekly reward offers and personal-store updates

DETAILED_DOCUMENTATION.md

@@ -406,15 +406,36 @@ Acknowledges XP shop tracks.
 
 ---
 
+##### `personalStore` and `personalStoreUpdate`
+
+`personalStore` is `null` until the GC supplies weekly reward data. Otherwise it contains:
+
+- `generation_time` (`number | null`) - Server-provided offer generation timestamp.
+- `redeemable_balance` (`number | null`) - Server-provided remaining balance.
+- `items` (`string[]`) - Available reward item IDs, preserved as decimal strings.
+
+Initial data is loaded before `connectedToGC`. The `personalStoreUpdate(store)` event
+fires when data arrives through welcome, create, or update messages, including batched
+updates. Removal, disconnect, or a new welcome clears stale data and emits `null` if a
+store was previously present. Missing scalar fields are `null`; an explicit zero balance
+remains `0`. Malformed store payloads emit a debug message and are ignored.
+
+A missing store does not prove that an account is ineligible. This API exposes server
+state; it does not calculate a weekly reset or generate rewards. Select IDs from the
+current offer and pass its generation time and balance to `redeemFreeReward`. Keep
+claims sequential and wait for refreshed store data before another claim.
+
+---
+
 ##### `redeemFreeReward(generationTime, redeemableBalance, items, callback)`
 
 Redeems a free reward.
 
 **Parameters:**
 
-- `generationTime` (number) - Generation time of the reward
-- `redeemableBalance` (number) - Redeemable balance
-- `items` (Array<number>) - Array of item IDs
+- `generationTime` (number) - Generation time from the current `personalStore`
+- `redeemableBalance` (number) - Balance from the current `personalStore`
+- `items` (Array<string | number>) - Selected reward IDs; use strings to preserve 64-bit precision
 - `callback` (function, optional) - Callback function `(err, itemIds) => {}`
 
 **Returns:**

EXAMPLES.md

@@ -337,26 +337,44 @@ cs2.acknowledgeRentalExpiration(crateItemId);
 cs2.acknowledgeXPShopTracks();
 ```
 
-### Redeem Free Reward
+### View and Redeem Weekly Rewards
+
+The GC supplies the current offer in `personalStore`. Listen for updates to display
+available choices, and explicitly choose which rewards to claim. A `null` store
+means no current data is available; it does not establish weekly eligibility.
 
 ```javascript
-// Redeem free reward
-const generationTime = Date.now() / 1000;
-const redeemableBalance = 100;
-const items = [1234567890, 9876543210];
+cs2.on('personalStoreUpdate', (store) => {
+	console.log('Weekly reward offer:', store);
+});
 
-await cs2.redeemFreeReward(generationTime, redeemableBalance, items);
+cs2.on('connectedToGC', () => {
+	console.log('Initial weekly reward offer:', cs2.personalStore);
+});
 
-// With callback
-cs2.redeemFreeReward(generationTime, redeemableBalance, items, (err, itemIds) => {
-	if (err) {
-		console.error('Error redeeming reward:', err);
-		return;
+// Call after the user selects item IDs from the current offer.
+async function claimWeeklyRewards(selectedItemIds) {
+	const store = cs2.personalStore;
+	if (!cs2.haveGCSession || !store || store.generation_time === null || !store.redeemable_balance) {
+		throw new Error('No weekly rewards available to claim');
 	}
-	console.log('Reward redeemed, items:', itemIds);
-});
+	if (
+		selectedItemIds.length === 0 ||
+		selectedItemIds.length > store.redeemable_balance ||
+		new Set(selectedItemIds).size !== selectedItemIds.length ||
+		!selectedItemIds.every((id) => store.items.includes(id))
+	) {
+		throw new Error('Select distinct item IDs from the current weekly reward offer');
+	}
+	return cs2.redeemFreeReward(store.generation_time, store.redeemable_balance, selectedItemIds);
+}
 ```
 
+Keep item IDs as strings. Use the server-provided generation time and balance;
+do not substitute the current time or an invented balance. Make one claim at a
+time and wait for updated store data before another. The existing callback form
+`redeemFreeReward(generationTime, redeemableBalance, items, callback)` is also supported.
+
 ### Redeem Mission Reward
 
 ```javascript

constants.js

@@ -27,6 +27,7 @@ const PLAYERS_PROFILE_REQUEST_LEVEL = 32;
 
 // ─── Shared Object Types ────────────────────────────────────────────────────────
 const SO_TYPE_ECON_ITEM = 1;
+const SO_TYPE_PERSONAL_STORE = 4;
 
 // ─── Item Definition Indices ────────────────────────────────────────────────────
 const DEFINDEX_STORAGE_UNIT = 1201;
@@ -70,6 +71,7 @@ module.exports = {
 	CRATE_TIMEOUT_MS,
 	PLAYERS_PROFILE_REQUEST_LEVEL,
 	SO_TYPE_ECON_ITEM,
+	SO_TYPE_PERSONAL_STORE,
 	DEFINDEX_STORAGE_UNIT,
 	ATTRIB_PAINT_INDEX,
 	ATTRIB_PAINT_SEED,

handlers.js

@@ -59,9 +59,20 @@ handlers[Language.ClientWelcome] = function (body) {
 		return;
 	}
 
+	this._setPersonalStore(null);
+	for (const subscribed of proto.outofdate_subscribed_caches || []) {
+		for (const cache of subscribed.objects || []) {
+			if (cache.type_id === Constants.SO_TYPE_PERSONAL_STORE) {
+				cache.object_data.forEach((object) => this._decodePersonalStore(object));
+			}
+		}
+	}
 	if (proto.outofdate_subscribed_caches && proto.outofdate_subscribed_caches.length) {
 		proto.outofdate_subscribed_caches[0].objects.forEach((cache) => {
 			switch (cache.type_id) {
+				case Constants.SO_TYPE_PERSONAL_STORE:
+					// Loaded from all subscribed caches above.
+					break;
 				case Constants.SO_TYPE_ECON_ITEM:
 					// Inventory
 					const items = cache.object_data
@@ -145,6 +156,7 @@ handlers[Language.ClientConnectionStatus] = function (body) {
 	);
 
 	if (proto.status != NodeCS2.GCConnectionStatus.HAVE_SESSION && this.haveGCSession) {
+		this._setPersonalStore(null);
 		this.emit('disconnectedFromGC', proto.status);
 		this.haveGCSession = false;
 		this._connect(); // Try to reconnect
@@ -446,6 +458,26 @@ NodeCS2.prototype._processSOEconItem = function (item) {
 	}
 };
 
+// Personal-store IDs are uint64 values and remain decimal strings, like inventory IDs.
+NodeCS2.prototype._setPersonalStore = function (store) {
+	if (store === null && this.personalStore === null) {
+		return;
+	}
+	this.personalStore = store;
+	this.emit('personalStoreUpdate', store);
+};
+
+NodeCS2.prototype._decodePersonalStore = function (body) {
+	let store;
+	try {
+		store = decodeProto(Protos.CSOAccountItemPersonalStore, body);
+	} catch (err) {
+		this.emit('debug', `Failed to decode personal store: ${err.message}`);
+		return;
+	}
+	this._setPersonalStore(store);
+};
+
 handlers[Language.SO_Create] = function (body) {
 	let proto;
 	try {
@@ -458,6 +490,11 @@ handlers[Language.SO_Create] = function (body) {
 };
 
 NodeCS2.prototype._handleSOCreate = function (proto) {
+	if (proto && proto.type_id === Constants.SO_TYPE_PERSONAL_STORE) {
+		this._decodePersonalStore(proto.object_data);
+		return;
+	}
+
 	if (!proto || proto.type_id != Constants.SO_TYPE_ECON_ITEM) {
 		return; // Not an item
 	}
@@ -492,6 +529,11 @@ handlers[Language.SO_Update] = function (body) {
 };
 
 NodeCS2.prototype._handleSOUpdate = function (so) {
+	if (so && so.type_id === Constants.SO_TYPE_PERSONAL_STORE) {
+		this._decodePersonalStore(so.object_data);
+		return;
+	}
+
 	if (!so || so.type_id != Constants.SO_TYPE_ECON_ITEM) {
 		return; // Not an item, we don't care
 	}
@@ -538,6 +580,11 @@ handlers[Language.SO_Destroy] = function (body) {
 };
 
 NodeCS2.prototype._handleSODestroy = function (proto) {
+	if (proto && proto.type_id === Constants.SO_TYPE_PERSONAL_STORE) {
+		this._setPersonalStore(null);
+		return;
+	}
+
 	if (!proto || proto.type_id != Constants.SO_TYPE_ECON_ITEM) {
 		return; // Not an item
 	}

index.js

@@ -28,6 +28,7 @@ function NodeCS2(steam) {
 	}
 
 	this._steam = steam;
+	this.personalStore = null;
 	this.haveGCSession = false;
 	this._isInCSGO = false;
 
@@ -79,6 +80,8 @@ function NodeCS2(steam) {
 			this._helloInterval = null;
 		}
 
+		this._setPersonalStore(null);
+
 		if (this.haveGCSession && emitDisconnectEvent) {
 			this.emit('disconnectedFromGC', NodeCS2.GCConnectionStatus.NO_SESSION);
 		}
@@ -771,7 +774,7 @@ NodeCS2.prototype.acknowledgeXPShopTracks = function () {
  * Redeem a free reward.
  * @param {int} generationTime - Generation time of the reward
  * @param {int} redeemableBalance - Redeemable balance
- * @param {int[]} items - Array of item IDs
+ * @param {Array<string|number>} items - Reward item IDs; use strings for 64-bit precision
  * @param {function} callback - Optional callback. If not provided, returns a Promise.
  * @returns {Promise|undefined} Returns a Promise if no callback is provided
  */