steamutils 1.5.40 → 1.5.42

package/_steamproto.js

@@ -12,8 +12,13 @@ export class SteamProto {
   }
 
   toProto() {
-    const filePath = path.join(`${__dirname}/protos/`, this._proto.filename);
-    const root = new Protobuf.Root().loadSync([gpf.getProtoPath("google/protobuf/descriptor.proto"), filePath], {
+    const localProto = path.join(`${__dirname}/protos/`, this._proto.filename);
+    console.log(`localProto: ${localProto}`);
+
+    const descriptorPath = gpf.getProtoPath("protobuf/descriptor.proto");
+    console.log(`descriptorPath: ${descriptorPath}`);
+
+    const root = new Protobuf.Root().loadSync([descriptorPath, localProto], {
       keepCase: true,
     });
     return root.lookupType(this._proto.name);

package/full_steamproto.js

@@ -12,8 +12,13 @@ export class SteamProto {
   }
 
   toProto() {
-    const filePath = path.join(`${__dirname}/protos/`, this._proto.filename);
-    const root = new Protobuf.Root().loadSync([gpf.getProtoPath("google/protobuf/descriptor.proto"), filePath], {
+    const localProto = path.join(`${__dirname}/protos/`, this._proto.filename);
+    console.log(`localProto: ${localProto}`);
+
+    const descriptorPath = gpf.getProtoPath("protobuf/descriptor.proto");
+    console.log(`descriptorPath: ${descriptorPath}`);
+
+    const root = new Protobuf.Root().loadSync([descriptorPath, localProto], {
       keepCase: true,
     });
     return root.lookupType(this._proto.name);

package/index.js

@@ -5,7 +5,7 @@ import moment from "moment";
 import { hex2b64, Key as RSA } from "node-bignumber";
 import SteamID from "steamid";
 import qs from "qs";
-import { console_log, convertLongsToNumbers, downloadImage, formatMarketHistoryDate, getCleanObject, getImageSize, JSON_parse, JSON_stringify, removeSpaceKeys, secretAsBuffer, sleep } from "./utils.js";
+import { console_log, convertLongsToNumbers, downloadImage, formatMarketHistoryDate, getCleanObject, getImageSize, isJWT, JSON_parse, JSON_stringify, removeSpaceKeys, secretAsBuffer, sleep } from "./utils.js";
 import { Header, request } from "./axios.js";
 import { getTableHasHeaders, querySelectorAll, table2json } from "./cheerio.js";
 import { getJSObjectFronXML } from "./xml2json.js";
@@ -807,9 +807,25 @@ export default class SteamUser {
     };
   }
 
-  static async getAppVersion(appID) {
+  /**
+   * Fetches up-to-date status and version information for a Steam app by appID.
+   *
+   * @param {number|string} appID - The Steam app ID to query.
+   * @returns {Promise<{
+   *   response: {
+   *     success: boolean,
+   *     up_to_date: boolean,
+   *     version_is_listable: boolean,
+   *     required_version: number,
+   *     message: string
+   *   }
+   * }|undefined>} The API response object, or undefined if an error occurs.
+   *
+   */
+  static async getSteamAppVersionInfo(appID) {
     try {
-      return (await request(`https://api.steampowered.com/ISteamApps/UpToDateCheck/v1/?format=json&appid=${appID}&version=0`)).data.response.required_version;
+      const response = await fetch(`https://api.steampowered.com/ISteamApps/UpToDateCheck/v1/?format=json&appid=${appID}&version=0`);
+      return await response.json();
     } catch (e) {}
   }
 
@@ -4496,20 +4512,48 @@ export default class SteamUser {
     return await SteamUser.resolveUsers(steamIDs, this.getCookies());
   }
 
-  static async resolveUsers(steamIDs = [], cookie) {
+  /**
+   * @typedef {Object} SteamUserProfile
+   * @property {string} steamId - The user's 64-bit SteamID.
+   * @property {number} accountId - The user's numeric account ID.
+   * @property {string} name - The Steam persona name.
+   * @property {string} realName - The user's real name (may be empty).
+   * @property {string} avatarHash - The user's avatar hash or identifier.
+   * @property {string} customURL - The user's custom profile URL (may be empty).
+   * @property {number} personaState - The user's online status/state.
+   * @property {string} city - The user's city (may be empty).
+   * @property {string} state - The user's state/region (may be empty).
+   * @property {string} country - The user's country code (may be empty).
+   * @property {boolean} isFriend - Whether the user is a friend.
+   * @property {number} friendsInCommon - Number of mutual friends.
+   */
+
+  /**
+   * Resolves an array of Steam user IDs to their profile information using the Steam Community API.
+   *
+   * @param {(string|number)[]} steamIds - Array of Steam IDs (each a string or number).
+   * @param {string} [cookie] - Optional session cookie for Steam authentication.
+   * @returns {Promise<SteamUserProfile[]>} Promise resolving to an array of Steam user profile objects.
+   *
+   * @example
+   * const users = await SteamUser.resolveUsers(['76561199409201417']);
+   */
+  static async resolveUsers(steamIds, cookie) {
     //steamIDs max = 200
-    if (typeof steamIDs === "string") {
-      steamIDs = [steamIDs];
+
+    if (!Array.isArray(steamIds) || !steamIds.every((id) => typeof id === "string" || typeof id === "number")) {
+      console.error("steamIds must be an array of string or number.");
+      return [];
     }
 
-    steamIDs = _.uniq(steamIDs);
+    steamIds = _.uniq(steamIds);
 
-    if (steamIDs.length > 200) {
-      return _.flatten(await Promise.all(_.chunk(steamIDs, 200).map((_steamIDs) => SteamUser.resolveUsers(_steamIDs, cookie))));
+    if (steamIds.length > 200) {
+      return _.flatten(await Promise.all(_.chunk(steamIds, 200).map((_steamIds) => SteamUser.resolveUsers(_steamIds, cookie))));
     }
 
     const { data } = await request({
-      url: `https://steamcommunity.com/actions/ajaxresolveusers?steamids=${steamIDs.join(",")}`,
+      url: `https://steamcommunity.com/actions/ajaxresolveusers?steamids=${steamIds.join(",")}`,
       headers: { ...(cookie && { cookie }) },
     });
 
@@ -4520,21 +4564,43 @@ export default class SteamUser {
     return data.map(function (player) {
       return {
         steamId: player.steamid,
-        accountid: player.accountid,
+        accountId: player.accountid,
         name: player.persona_name,
-        realname: player.real_name,
+        realName: player.real_name,
         avatarHash: player.avatar_url,
         customURL: player.profile_url,
-        persona_state: player.persona_state,
+        personaState: player.persona_state,
         city: player.city,
         state: player.state,
         country: player.country,
-        is_friend: player.is_friend,
-        friends_in_common: player.friends_in_common,
+        isFriend: player.is_friend,
+        friendsInCommon: player.friends_in_common,
       };
     });
   }
 
+  /**
+   * Resolves a single Steam user ID to its profile information using the Steam Community API.
+   *
+   * @param {string|number} steamId - The Steam ID to resolve.
+   * @param {string} [cookie] - Optional session cookie for Steam authentication.
+   * @returns {Promise<SteamUserProfile|undefined>} Resolves to a user profile object, or undefined if not found or if input is invalid.
+   *
+   * @example
+   * const user = await SteamUser.resolveUser('76561199409201417');
+   * if (user) {
+   *   console.log(user.name);
+   * }
+   */
+  static async resolveUser(steamId, cookie) {
+    if (typeof steamId !== "string" && typeof steamId !== "number") {
+      console.error("resolveUser: steamId must be a string or number. Received:", steamId);
+      return;
+    }
+    const users = await this.resolveUsers([steamId], cookie);
+    return users[0];
+  }
+
   static GetAvatarURLFromHash(hash, size) {
     if (!hash) {
       return;
@@ -4658,10 +4724,25 @@ export default class SteamUser {
     return list;
   }
 
+  /**
+   * Retrieves the current Steam Guard status for the account.
+   *
+   * Makes an HTTP request to the Steam two-factor management page,
+   * parses the response, and determines the type of Steam Guard authentication enabled:
+   *   - "steam_authenticator" (mobile authenticator is enabled)
+   *   - "email_authenticator" (email confirmation is enabled)
+   *   - "none_authenticator" (no two-factor is enabled)
+   *
+   * If the request fails (ResponseError), returns null.
+   *
+   * @async
+   * @returns {Promise<"steam_authenticator"|"email_authenticator"|"none_authenticator"|null>}
+   *          A string representing the authenticator type, or null if the request fails.
+   */
   async getSteamGuardStatus() {
     const result = await this._httpRequest(`https://store.steampowered.com/twofactor/manage_action`);
     if (result instanceof ResponseError) {
-      return result;
+      return nuill;
     }
     const $ = cheerio.load(result?.data || "");
 
@@ -4678,7 +4759,20 @@ export default class SteamUser {
     }
   }
 
-  async turningSteamGuardOff() {
+  /**
+   * Attempts to initiate the process of turning Steam Guard off for the account.
+   *
+   * Sends a POST request to Steam's two-factor management endpoint to request the
+   * removal of Steam Guard. It then checks the response to verify whether the request
+   * to turn Steam Guard off was successfully triggered (an email confirmation is sent).
+   *
+   * @async
+   * @returns {Promise<boolean>}
+   *   Returns `true` if turning Steam Guard off requires email confirmation and the
+   *   corresponding message is found in the response;
+   *   returns `false` if an error occurs (e.g., a ResponseError is returned).
+   */
+  async requestSteamGuardDeactivation() {
     const result = await this._httpRequest({
       url: `https://store.steampowered.com/twofactor/manage_action`,
       headers: {
@@ -4692,13 +4786,25 @@ export default class SteamUser {
       method: "POST",
     });
     if (result instanceof ResponseError) {
-      return result;
+      return false;
     }
     const $ = cheerio.load(result?.data || "");
     return $("title").text() === `Steam Guard Mobile Authenticator` && !!result?.data?.includes?.(`Turning Steam Guard off requires confirmation. We've sent you an email with a link to confirm disabling Steam Guard.`);
   }
 
-  async turningEmailAuthenticatorCheckOn() {
+  /**
+   * Activates the email-based Steam Guard authenticator for the account.
+   *
+   * Sends a POST request to Steam's two-factor management endpoint to enable email-based authentication.
+   * Returns `true` if the response confirms that the email authenticator is enabled,
+   * or `false` if the request fails or the response does not indicate successful activation.
+   *
+   * @async
+   * @returns {Promise<boolean>}
+   *   Returns `true` if the email authenticator is activated successfully,
+   *   or `false` otherwise.
+   */
+  async activateEmailSteamGuard() {
     const result = await this._httpRequest({
       url: `https://store.steampowered.com/twofactor/manage_action`,
       headers: {
@@ -4713,19 +4819,31 @@ export default class SteamUser {
       method: "POST",
     });
     if (result instanceof ResponseError) {
-      return result;
+      return false;
     }
     const $ = cheerio.load(result?.data || "");
     return $("title").text() === `Steam Guard Mobile Authenticator` && $("#email_authenticator_check")?.attr("checked") == "checked";
   }
 
-  async getPhoneManage() {
-    //Ends in 17
+  /**
+   * Retrieves the current phone number status associated with the Steam account.
+   *
+   * Performs an HTTP request to the Steam phone management page and parses the response to
+   * determine if a phone number is bound to the account.
+   * - Returns `'none'` if no phone number is linked.
+   * - Returns a string describing the phone (e.g., 'Ends in 17') if one is bound.
+   * - Returns `null` on request failure or unexpected page content.
+   *
+   * @async
+   * @returns {Promise<string|null>}
+   *   The phone number status: `'none'`, a phone description string (like 'Ends in 17'), or `null` if the request fails.
+   */
+  async getPhoneNumberStatus() {
     const result = await this._httpRequest({
       url: `https://store.steampowered.com/phone/manage`,
     });
     if (result instanceof ResponseError) {
-      return result;
+      return null;
     }
     const $ = cheerio.load(result?.data || "");
     const pageheader = $("h2.pageheader").text();
@@ -4733,7 +4851,7 @@ export default class SteamUser {
       case "Add a phone number to your account":
         return "none";
       case "Manage phone number":
-        return $(".phone_header_description > span").text(); //Ends in 17}
+        return $(".phone_header_description > span").text(); //Example: Ends in 17
     }
   }
 
@@ -6769,34 +6887,102 @@ export default class SteamUser {
     return { error };
   }
 
-  async enableTwoFactor(accessToken) {
-    if (!accessToken || typeof accessToken !== "string") {
-      return { error: "Invalid accessToken: " + accessToken };
+  /**
+   * @typedef {Object} SteamAuthenticatorResponse
+   * @property {string} shared_secret
+   * @property {string} serial_number
+   * @property {string} revocation_code
+   * @property {string} uri
+   * @property {string} server_time
+   * @property {string} account_name
+   * @property {string} token_gid
+   * @property {string} identity_secret
+   * @property {string} secret_1
+   * @property {number} status
+   * @property {number} confirm_type
+   */
+
+  /**
+   * @typedef {Object} AddSteamAuthenticatorResult
+   * @property {boolean} success - Whether enabling 2FA was successful.
+   * @property {SteamAuthenticatorResponse} [response] - The response object if successful.
+   * @property {string} [error] - Error message if unsuccessful.
+   */
+
+  /**
+   * Adds a Steam mobile authenticator to the account.
+   *
+   * @async
+   * @param {string} accessToken - Steam access token (must be a valid JWT).
+   * @returns {Promise<AddSteamAuthenticatorResult>}
+   */
+  async addSteamAuthenticator(accessToken) {
+    if (!isJWT(accessToken)) {
+      return {
+        success: false,
+        error: `Invalid accessToken (must be JWT): ${accessToken}`,
+      };
     }
 
-    const SteamCommunity = (await import("steamcommunity")).default;
-    let error = null;
+    const steamId = this.getSteamIdUser();
+    const formData = new URLSearchParams({
+      steamid: steamId,
+      authenticator_type: 1,
+      device_identifier: SteamTotp.getDeviceID(steamId),
+      sms_phone_id: "1",
+      version: 2,
+    }).toString();
+
+    const url = `https://api.steampowered.com/ITwoFactorService/AddAuthenticator/v1/?access_token=${encodeURIComponent(accessToken)}`;
+    const headersBase = {
+      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36",
+      Origin: "https://api.steampowered.com",
+      "Content-Type": "application/x-www-form-urlencoded",
+    };
+
+    let lastError = null;
+
     for (const cookie of this._cookies) {
       try {
-        const community = new SteamCommunity();
-        community.setCookies(cookie.toString().split(";"));
-        community.oAuthToken = accessToken;
-        try {
-          community.setMobileAppAccessToken(accessToken);
-        } catch (e) {}
-        const response = await new Promise((resolve) => {
-          community.enableTwoFactor((error, response) => {
-            resolve({ error, response });
-          });
+        const response = await axios.request({
+          method: "POST",
+          url,
+          headers: {
+            ...headersBase,
+            Cookie: cookie,
+          },
+          data: formData,
         });
-        if (!response.error) {
-          return { ...response, success: true };
+        if (response.data && response.data.response) {
+          return {
+            success: true,
+            response: response.data.response,
+          };
         } else {
-          error = response.error;
+          return {
+            success: false,
+            error: `Unexpected API response: ${JSON.stringify(response.data)}`,
+          };
         }
-      } catch (e) {}
+      } catch (error) {
+        // Prepare a clear error message
+        let apiError = "Unknown error";
+        if (error.code === "ECONNABORTED") {
+          apiError = "Request timed out";
+        } else if (error.response && error.response.data) {
+          apiError = typeof error.response.data === "object" ? JSON.stringify(error.response.data) : String(error.response.data);
+        } else if (error.message) {
+          apiError = error.message;
+        }
+        lastError = apiError;
+      }
     }
-    return { error };
+
+    // All attempts failed.
+    return {
+      success: false,
+      error: lastError || "Failed to add Steam authenticator: No cookies provided or all attempts failed.",
+    };
   }
 
   async finalizeTwoFactor(accessToken, identitySecret, finalizeTwoFactorCode) {
@@ -7558,6 +7744,7 @@ export default class SteamUser {
     });
     return revokeRefreshTokenResult?.data;
   }
+
   async revokeAccessToken(accessToken, tokenId, sharedSecret) {
     if (!accessToken || typeof accessToken !== "string") {
       console.error("revokeAccessToken", "invalid accessToken", accessToken);
@@ -7989,7 +8176,7 @@ export default class SteamUser {
   /**
    * Fetches Steam batched loyalty reward items for given app ID(s).
    * @param {number|number[]} appIds - A Steam App ID or array of App IDs.
-   * @returns {Promise<Array<{eresult: number, response: BatchedLoyaltyRewardItemsResponse}>>}
+   * @returns {Promise<Array<{eresult: number, response: BatchedLoyaltyRewardItemsResponse}>|null|undefined>}
    */
   static async fetchBatchedLoyaltyRewardItems(appIds) {
     if (!appIds) {
@@ -8035,7 +8222,7 @@ export default class SteamUser {
       responseType: "arraybuffer",
     });
     if (result instanceof ResponseError) {
-      return result;
+      return;
     }
 
     try {
@@ -8181,71 +8368,132 @@ export default class SteamUser {
     return apps.filter((app) => app.event_app);
   }
 
-  static async decodeQRImage(imageURL) {
-    let response = null;
+  /**
+   * Downloads an image from the given URL, decodes its QR code and returns the result.
+   *
+   * @param {string} imageURL - The URL of the image containing the QR code.
+   * @returns {Promise<{ success: boolean, message: string, decodedQR: string | null }>}
+   */
+  static async extractQRCodeFromImageURL(imageURL) {
+    // Validate URL format first
     try {
-      response = await axios.get(imageURL, {
-        responseType: "arraybuffer",
-      });
-    } catch (e) {}
-    const imageBuffer = response?.data;
-    if (!imageBuffer) {
-      return;
+      new URL(imageURL);
+    } catch (e) {
+      return {
+        success: false,
+        message: "The provided imageURL is not a valid URL.",
+        decodedQR: null,
+      };
     }
-    try {
-      const { Jimp } = await import("jimp");
 
-      // Load the image with Jimp
-      const image = await Jimp.read(imageBuffer);
+    let jimp, jsQR, imageBuffer;
+    try {
+      // Parallelize imports and fetch
+      const [{ Jimp }, { default: jsQRmod }, response] = await Promise.all([import("jimp"), import("jsqr"), fetch(imageURL)]);
+      jimp = Jimp;
+      jsQR = jsQRmod;
 
-      // Get the image data
-      const imageData = {
-        data: new Uint8ClampedArray(image.bitmap.data),
-        width: image.bitmap.width,
-        height: image.bitmap.height,
+      if (!response.ok) {
+        return {
+          success: false,
+          message: `Failed to fetch image: HTTP ${response.status} ${response.statusText}`,
+          decodedQR: null,
+        };
+      }
+      imageBuffer = await response.arrayBuffer();
+      if (!imageBuffer) {
+        return {
+          success: false,
+          message: "Empty image data.",
+          decodedQR: null,
+        };
+      }
+    } catch (e) {
+      return {
+        success: false,
+        message: `Initialization or fetch failure: ${e.message || e}`,
+        decodedQR: null,
       };
+    }
 
-      // Use jsQR to decode the QR code
-      const jsQR = (await import("jsqr")).default;
-      const decodedQR = jsQR(imageData.data, imageData.width, imageData.height);
+    try {
+      // Jimp accepts Buffer in Node.js, use Buffer.from(arrayBuffer)
+      const image = await jimp.read(Buffer.from(imageBuffer));
+      const { data, width, height } = image.bitmap;
+      const clampedData = data instanceof Uint8ClampedArray ? data : new Uint8ClampedArray(data);
+      const decodedQR = jsQR(clampedData, width, height);
 
       if (!decodedQR) {
-        return "QR code not found in the image.";
+        return {
+          success: false,
+          message: "QR code not found in the image.",
+          decodedQR: null,
+        };
       }
-
-      return decodedQR.data;
+      return {
+        success: true,
+        message: "QR code successfully decoded.",
+        decodedQR: decodedQR.data,
+      };
     } catch (error) {
-      console.error("Error decoding QR code:", error);
+      return {
+        success: false,
+        message: `Error decoding QR code: ${error.message || error}`,
+        decodedQR: null,
+      };
     }
   }
 
-  static async approveLoginRequest(steamId, url, sharedSecret, accessToken) {
+  /**
+   * Approves a Steam login request.
+   * @param {string} steamId - Steam user ID.
+   * @param {string} qrChallengeUrl - QR challenge URL.
+   * @param {string} sharedSecret - Shared secret for TOTP.
+   * @param {string} accessToken - API access token.
+   * @returns {Promise<{steamId: string, error: string|null, success: boolean}>}
+   */
+  static async approveLoginRequest(steamId, qrChallengeUrl, sharedSecret, accessToken) {
     try {
       const { LoginApprover } = await import("steam-session");
-      const approver = new LoginApprover(accessToken, sharedSecret, {});
-      await approver.approveAuthSession({
-        qrChallengeUrl: url,
-        approve: true,
-      });
-
-      return {
-        steamId,
-        error: null,
-      };
+      const approver = new LoginApprover(accessToken, sharedSecret);
+      await approver.approveAuthSession({ qrChallengeUrl, approve: true });
+      return { steamId, error: null, success: true };
     } catch (error) {
-      console.error(`[${steamId}] approveLoginRequest Error`, error);
-      return {
-        steamId,
-        error: error || "Error",
-      };
+      return { steamId, error: error?.message || "Unknown error", success: false };
     }
   }
 
-  static async getAuthSessionInfo(steamId, url, sharedSecret, accessToken) {
+  /**
+   * @typedef {Object} SessionInfo
+   * @property {string} ip - The IP address of the session.
+   * @property {Object} location - Geolocation details.
+   * @property {string} location.geoloc - Latitude and longitude as a string.
+   * @property {string} location.city - City of the session.
+   * @property {string} location.state - State or region of the session.
+   * @property {number} platformType - Numeric platform type indicator.
+   * @property {string} deviceFriendlyName - Friendly name of the device.
+   * @property {number} version - Version of the protocol/session.
+   * @property {number} loginHistory - Login history flag or value.
+   * @property {boolean} locationMismatch - Whether the location mismatches profile.
+   * @property {boolean} highUsageLogin - Whether this is a high-usage login.
+   * @property {number} requestedPersistence - Type/level of session persistence requested.
+   * @property {string} steamId - Steam ID associated with the session.
+   */
+
+  /**
+   * Retrieves Steam authentication session information.
+   *
+   * @param {string} steamId - The Steam user ID.
+   * @param {string} qrChallengeUrl - The QR challenge URL.
+   * @param {string} sharedSecret - The shared secret for authentication.
+   * @param {string} accessToken - The access token.
+   * @returns {Promise<{steamId: string, sessionInfo?: SessionInfo, error?: string}>} Result containing the original Steam ID, session info if successful, or error message if failed.
+   */
+  static async getAuthSessionInfo(steamId, qrChallengeUrl, sharedSecret, accessToken) {
     try {
       const { LoginApprover } = await import("steam-session");
       const approver = new LoginApprover(accessToken, sharedSecret, {});
-      const sessionInfo = await approver.getAuthSessionInfo(url);
+      const sessionInfo = await approver.getAuthSessionInfo(qrChallengeUrl);
       sessionInfo.steamId = steamId;
 
       return {
@@ -8253,10 +8501,9 @@ export default class SteamUser {
         sessionInfo,
       };
     } catch (error) {
-      console.error(`[${steamId}] getAuthSessionInfo Error`, error);
       return {
         steamId,
-        error,
+        error: error?.message || "Unknown error",
       };
     }
   }

package/package.json

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

package/steamproto.js

@@ -12,8 +12,13 @@ export class SteamProto {
   }
 
   toProto() {
-    const filePath = path.join(`${__dirname}/protos/`, this._proto.filename);
-    const root = new Protobuf.Root().loadSync([gpf.getProtoPath("google/protobuf/descriptor.proto"), filePath], {
+    const localProto = path.join(`${__dirname}/protos/`, this._proto.filename);
+    console.log(`localProto: ${localProto}`);
+
+    const descriptorPath = gpf.getProtoPath("protobuf/descriptor.proto");
+    console.log(`descriptorPath: ${descriptorPath}`);
+
+    const root = new Protobuf.Root().loadSync([descriptorPath, localProto], {
       keepCase: true,
     });
     return root.lookupType(this._proto.name);