steamutils 1.5.36 → 1.5.38

package/index.js

@@ -7215,6 +7215,27 @@ export default class SteamUser {
     ];
   }
 
+  /**
+   * @typedef {Object} RedeemPointsResponse
+   * @property {number[]} bundle_community_item_ids - Array of community item IDs in the bundle. May be empty.
+   * @property {number} communityitemid - The redeemed community item ID.
+   */
+
+  /**
+   * Redeems Steam Points for a specified reward definition.
+   *
+   * @async
+   * @param {string} accessToken - The user's Steam OAuth access token.
+   * @param {number|string} definitionId - The definition ID for the reward to redeem.
+   * @returns {Promise<?RedeemPointsResponse>} A promise that resolves to the redemption response object,
+   * or null/undefined if unsuccessful.
+   *
+   * @example
+   * {
+   *   bundle_community_item_ids: [],
+   *   communityitemid: 34336330688
+   * }
+   */
   async redeemPoints(accessToken, definitionId) {
     if (!definitionId) {
       return;
@@ -8020,6 +8041,56 @@ export default class SteamUser {
     } catch (e) {}
   }
 
+  /**
+   * Fetches information about one or more Steam apps by their app IDs using the Steam Community GetApps API.
+   *
+   * Each app object in the response may include fields such as:
+   * - appid: {number} The Steam application ID
+   * - name: {string} Name of the app
+   * - icon: {string} App icon hash
+   * - logo, logo_small: {string} App logo (if any)
+   * - tool, demo, media: {boolean} App type flags
+   * - community_visible_stats: {boolean} If the app has community stats visible
+   * - friendly_name: {string} Optional, usually empty for event apps
+   * - propagation: {string} Propagation mode
+   * - has_adult_content: {boolean} If app contains adult content
+   * - is_visible_in_steam_china: {boolean} Visibility on Steam China
+   * - app_type: {number} App type code
+   * - has_adult_content_sex: {boolean}
+   * - has_adult_content_violence: {boolean}
+   * - content_descriptorids: {Array<number>}
+   *
+   * @async
+   * @static
+   * @param {number|number[]} appIds - A single app ID or array of app IDs to request.
+   * @returns {Promise<{
+   *   apps: Array<{
+   *     content_descriptorids: number[],
+   *     appid: number,
+   *     name: string,
+   *     icon: string,
+   *     logo: string,
+   *     logo_small: string,
+   *     tool: boolean,
+   *     demo: boolean,
+   *     media: boolean,
+   *     community_visible_stats: boolean,
+   *     friendly_name: string,
+   *     propagation: string,
+   *     has_adult_content: boolean,
+   *     is_visible_in_steam_china: boolean,
+   *     app_type: number,
+   *     has_adult_content_sex: boolean,
+   *     has_adult_content_violence: boolean
+   *   }>
+   * }|ResponseError|undefined>} Returns an object containing an 'apps' array with the app data on success,
+   * a ResponseError if the request fails, or undefined if no appIds are supplied.
+   *
+   * @example
+   * const result = await SteamUser.cCommunityGetAppsRequest(3558910);
+   * console.log(result);
+   * // { apps: [ { appid: 3558910, name: '...', ... } ] }
+   */
   static async cCommunityGetAppsRequest(appIds) {
     if (!appIds) {
       return;
@@ -8054,6 +8125,59 @@ export default class SteamUser {
     return response;
   }
 
+  /**
+   * @typedef {Object} EligibleEventApp
+   * @property {number} appid The unique Steam app ID.
+   * @property {number} has_items_anyone_can_purchase 1 if anyone can purchase items, 0 otherwise.
+   * @property {number} event_app 1 if the app is considered an event app, 0 otherwise.
+   * @property {string|null} hero_carousel_image The filename for the hero carousel image, or null if not present.
+   * @property {null} owned Reserved, always null in current data.
+   */
+
+  /**
+   * Fetches the list of eligible event apps from the Steam Points Shop events store.
+   * This function retrieves the event page's HTML, parses out the loyalty store data,
+   * and returns all eligible apps that are marked as event apps.
+   *
+   * @returns {Promise<EligibleEventApp[]>} Array of eligible event app objects (empty array if an error occurs).
+   */
+  static async getEligibleEventApps() {
+    let html;
+    try {
+      ({ data: html } = await axios.get("https://store.steampowered.com/points/shop/c/events"));
+    } catch (e) {
+      console.error("Failed to fetch Steam Points Shop events page:", e);
+      return [];
+    }
+    if (!html) {
+      console.error("No HTML received from the events page.");
+      return [];
+    }
+
+    const $ = cheerio.load(html);
+    const loyaltyStr = $("#application_config").attr("data-loyaltystore");
+    if (!loyaltyStr) {
+      console.error("Loyalty store data not found in HTML.");
+      return [];
+    }
+
+    let loyaltyObj;
+    try {
+      loyaltyObj = JSON.parse(loyaltyStr);
+    } catch (e) {
+      console.error("Failed to parse loyalty store JSON:", e);
+      return [];
+    }
+
+    const apps = loyaltyObj?.eligible_apps?.apps;
+    if (!Array.isArray(apps)) {
+      console.error("No valid eligible_apps array found in loyalty store object.");
+      return [];
+    }
+
+    return apps.filter((app) => app.event_app);
+  }
+
   static async decodeQRImage(imageURL) {
     let response = null;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "steamutils",
-  "version": "1.5.36",
+  "version": "1.5.38",
   "main": "index.js",
   "dependencies": {
     "alpha-common-utils": "^1.0.6",