steamutils 1.5.55 → 1.5.57

package/index.js

@@ -5967,7 +5967,11 @@ export default class SteamUser {
         partner = _.trim(partner, s);
       }
       const partnerSteamId = partner.split(`',`)[0].trim();
-      const partnerName = partner.split(`', "`)[1].trim();
+      let partnerName = partner.split(`', "`)[1].trim();
+      try {
+        partnerName = JSON.parse(partnerName);
+      } catch (e) {}
+
       const playerAvatar = $1.find(".playerAvatar");
       const avatar = playerAvatar.find("img")?.attr("src");
       const link = playerAvatar.find("a")?.attr("href");

package/package.json

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

package/parse_html.js

@@ -1,348 +1,409 @@
-import { StringUtils } from "alpha-common-utils/index.js";
-import { formatMarketHistoryDate, getAvatarHashFromUrl } from "./utils.js";
-import * as cheerio from "cheerio";
-import { getJSObjectFronXML } from "./xml2json.js";
-import moment from "moment";
-
-/**
- * @typedef {Object} HoverItem
- * @property {string|null} listingId         The listing ID extracted from the selector, if available (as string).
- * @property {number} appid                  The app (game) ID for this item.
- * @property {number} contextid              The context ID for this item.
- * @property {number} assetid                The unique asset ID.
- * @property {string} unknown                A string field captured from the arguments (usually "0").
- * @property {string} [name_selector]        The HTML selector for the item's name, if present.
- * @property {string} [image_selector]       The HTML selector for the item's image, if present.
- * @property {string} [other_selector]       The selector string if it does not match name/image pattern.
- */
-
-/**
- * Extracts item information from Steam inventory trade history or similar HTML fragments.
- * Scans the given HTML string for calls to `CreateItemHoverFromContainer` and extracts
- * key data for each referenced item. Returns each item's info in a structured array.
- *
- * @param {string} html - The HTML string to parse.
- * @returns {HoverItem[]} Array of hover item objects.
- */
-export function extractAssetItemsFromHovers(html) {
-  // Use your preferred HTML/space scrubber.
-  html = StringUtils.cleanSpace(html);
-
-  // RegExp for CreateItemHoverFromContainer arguments
-  const re = /CreateItemHoverFromContainer\s*\(\s*g_rgAssets\s*,\s*'([^']+)'\s*,\s*(\d+)\s*,\s*'(\d+)'\s*,\s*'(\d+)'\s*,\s*(\d+)\s*\)/g;
-
-  /** @type {Record<number, HoverItem>} */
-  const itemsMap = {};
-  let match;
-
-  while ((match = re.exec(html)) !== null) {
-    const [_, selector, appid, contextid, assetid, unknown] = match;
-
-    // Extract listingId as a string if present: "history_row_<listingId>_"
-    let listingId = null;
-    const lidMatch = selector.match(/history_row_(\d+)_/);
-    if (lidMatch) listingId = lidMatch[1]; // assign as string
-
-    const appidNum = Number(appid);
-    const contextidNum = Number(contextid);
-    const assetidNum = Number(assetid);
-
-    if (!itemsMap[assetidNum]) {
-      itemsMap[assetidNum] = {
-        listingId,
-        appid: appidNum,
-        contextid: contextidNum,
-        assetid: assetidNum,
-        unknown,
-      };
-    }
-
-    if (selector.endsWith("_name")) {
-      itemsMap[assetidNum].name_selector = selector;
-    } else if (selector.endsWith("_image")) {
-      itemsMap[assetidNum].image_selector = selector;
-    } else {
-      itemsMap[assetidNum].other_selector = selector;
-    }
-  }
-  return Object.values(itemsMap);
-}
-
-/**
- * @typedef {Object} MarketHistoryListing
- * @property {string} id - HTML row id attribute (e.g. "history_row_4316182845737233773_4316182845737233774").
- * @property {string} listingId - Listing id (e.g. "4316182845737233773").
- * @property {number} price - Price in integer form (e.g. 80270).
- * @property {string} itemName - The market item's name (e.g. "UMP-45 | Mudder").
- * @property {string} gameName - The game's name (e.g. "Counter-Strike 2").
- * @property {string} listedOn - Listing date as string (e.g. "27 May 2024").
- * @property {string} actedOn - Acted on date or empty string.
- * @property {string} image - Full image URL for the item.
- * @property {string} gainOrLoss - "+" for buys, "-" for sells.
- * @property {string} status - Status text, usually empty string.
- * @property {string} [assetId] - (optional) Associated asset id, if available.
- */
-
-/**
- * Parses Steam market history listing rows into structured data objects.
- *
- * @param {string} html - The raw HTML string to parse.
- * @param {Object} [assetByListingId={}] - Optional mapping of listingId to assetId.
- * @returns {MarketHistoryListing[]} Array of market listing objects.
- */
-export function parseMarketHistoryListings(html, assetByListingId = {}) {
-  const $ = cheerio.load(html);
-  return $(".market_listing_row")
-    .toArray()
-    .map((el) => {
-      const $el = $(el);
-      const id = $el.attr("id");
-      const listingId = id?.match(/history_row_(.*?)_/)?.[1];
-      if (!listingId) return null;
-      const [gainOrLoss, image, priceText, itemName, gameName, listedOnText, actedOnText, status] = [$el.find(".market_listing_gainorloss").text().trim(), $el.find(".market_listing_item_img").attr("src"), $el.find(".market_table_value .market_listing_price").text(), $el.find(".market_listing_item_name").text().trim(), $el.find(".market_listing_game_name").text().trim(), $el.find(".market_listing_listed_date + .market_listing_listed_date").text(), $el.find(".market_listing_whoactedwith + .market_listing_listed_date").text(), $el.find(".market_listing_whoactedwith").text().trim()];
-      const price = parseInt(priceText.replace(/[₫().,]/g, "").trim(), 10) || "";
-      const listedOn = typeof formatMarketHistoryDate === "function" ? formatMarketHistoryDate(listedOnText.replace(/Listed:/, "").trim()) : listedOnText.replace(/Listed:/, "").trim();
-      const actedOn = typeof formatMarketHistoryDate === "function" ? formatMarketHistoryDate(actedOnText.replace(/Listed:/, "").trim()) : actedOnText.replace(/Listed:/, "").trim();
-
-      const result = {
-        id,
-        listingId,
-        price,
-        itemName,
-        gameName,
-        listedOn,
-        actedOn,
-        image,
-        gainOrLoss,
-        status,
-      };
-      if (assetByListingId?.[listingId]) result.assetId = assetByListingId[listingId];
-      return result;
-    })
-    .filter(Boolean);
-}
-
-/**
- * Parses Steam Market HTML listings to an array of items.
- *
- * @param {string} html - HTML string containing listing rows.
- * @returns {Array<{
- *   listingId: string,
- *   appId: number,
- *   contextId: number,
- *   itemId: number,
- *   imageUrl: string|null,
- *   buyerPaysPrice: string,
- *   receivePrice: string,
- *   itemName: string,
- *   gameName: string,
- *   listedDate: string
- * }>}
- */
-export function parseMarketListings(html) {
-  const $ = cheerio.load(html);
-  const results = [];
-
-  $(".market_listing_row").each((index, element) => {
-    const $row = $(element);
-
-    const cancelLink = $row.find(".market_listing_cancel_button > a").attr("href");
-    if (!cancelLink) return;
-
-    const paramsMatch = cancelLink.match(/\(([^)]*)\)/);
-    if (!paramsMatch) return;
-
-    let [, listingId, appId, contextId, itemId] = paramsMatch[1].split(",").map((param) => param.trim().replace(/^['"]|['"]$/g, ""));
-
-    appId = Number(appId);
-    contextId = Number(contextId);
-    itemId = Number(itemId);
-
-    const imageUrl = $row.find(`#mylisting_${listingId}_image`).attr("src") || null;
-
-    const buyerPaysElem = $row.find('.market_listing_price span[title="This is the price the buyer pays."]');
-    const buyerPaysPrice = StringUtils.cleanSpace(buyerPaysElem.text().replace(/[()]/g, ""));
-
-    const receiveElem = $row.find('.market_listing_price span[title="This is how much you will receive."]');
-    const receivePrice = StringUtils.cleanSpace(receiveElem.text().replace(/[()]/g, ""));
-
-    const itemName = $row.find(".market_listing_item_name_link").text() || $row.find(".market_listing_item_name").text();
-
-    const gameName = $row.find(".market_listing_game_name").text();
-
-    const listedDateElem = $row.find(".market_listing_game_name + .market_listing_listed_date_combined");
-    const listedDate = formatMarketHistoryDate(StringUtils.cleanSpace(listedDateElem.text()));
-
-    results.push({
-      listingId,
-      appId,
-      contextId,
-      itemId,
-      imageUrl,
-      buyerPaysPrice,
-      receivePrice,
-      itemName,
-      gameName,
-      listedDate,
-    });
-  });
-
-  return results;
-}
-
-/**
- * Represents a Steam Community group for a profile.
- * @typedef {Object} SteamProfileGroupXml
- * @property {string} groupID64
- * @property {string} groupName
- * @property {string} groupURL
- * @property {string} headline
- * @property {string} summary
- * @property {string} avatarIcon
- * @property {string} avatarMedium
- * @property {string} avatarFull
- * @property {number} memberCount
- * @property {number} membersInChat
- * @property {number} membersInGame
- * @property {number} membersOnline
- */
-
-/**
- * Array of Steam Community groups.
- * @typedef {SteamProfileGroupXml[]} SteamProfileGroupsXml
- */
-
-/**
- * Represents a most played game on a Steam profile.
- * @typedef {Object} SteamProfileMostPlayedGameXml
- * @property {string} gameName
- * @property {string} gameLink
- * @property {string} gameIcon
- * @property {string} gameLogo
- * @property {string} gameLogoSmall
- * @property {number} hoursPlayed
- * @property {number} hoursOnRecord
- * @property {string} statsName
- */
-
-/**
- * Array of most played games.
- * @typedef {SteamProfileMostPlayedGameXml[]} SteamProfileMostPlayedGamesXml
- */
-
-/**
- * Steam Community profile (parsed from XML, normalized).
- * @typedef {Object} SteamProfileXml
- * @property {string} name
- * @property {string} steamId
- * @property {string} onlineState
- * @property {string} stateMessage
- * @property {string} privacyState
- * @property {number} visibilityState
- * @property {string} avatarIcon
- * @property {string} avatarMedium
- * @property {string} avatarFull
- * @property {string} avatarHash
- * @property {number} vacBanned
- * @property {string} tradeBanState
- * @property {number} isLimitedAccount
- * @property {string} customURL
- * @property {number | null} memberSince
- * @property {string} steamRating
- * @property {number} hoursPlayed2Wk
- * @property {string} headline
- * @property {string} location
- * @property {string} realname
- * @property {string} summary
- * @property {SteamProfileMostPlayedGamesXml} [mostPlayedGames]
- * @property {SteamProfileGroupsXml} [groups]
- */
-
-/**
- * Parses a Steam profile XML into a normalized JSON format.
- *
- * @param {string} xml - The XML string as returned by the Steam Community profile endpoint.
- * @returns {SteamProfileXml|undefined} The normalized profile object or undefined on error.
- *
- * @example
- * import { parseSteamProfileXmlToJson } from "./your-module";
- * const xml = await fetch('https://steamcommunity.com/profiles/76561198386265483/?xml=1').then(r => r.text());
- * const profile = parseSteamProfileXmlToJson(xml);
- * console.log(profile.name);
- */
-export function parseSteamProfileXmlToJson(xml) {
-  const parsed = getJSObjectFronXML(xml);
-  if (!parsed || !parsed.profile) return;
-
-  // Flatten out the xml2js _structure, for direct children
-  const profile = {};
-  Object.entries(parsed.profile).forEach(([key, value]) => {
-    // If only text, keep as string
-    if (typeof value === "object" && value !== null && "_" in value && Object.keys(value).length === 1) {
-      profile[key] = value._;
-    } else {
-      profile[key] = value;
-    }
-  });
-
-  // Rename fields
-  if ("steamID" in profile) {
-    profile.name = profile.steamID;
-    delete profile.steamID;
-  }
-  if ("steamID64" in profile) {
-    profile.steamId = profile.steamID64;
-    delete profile.steamID64;
-  }
-
-  // Convert numbers
-  const numberFields = ["vacBanned", "isLimitedAccount", "visibilityState", "memberCount", "membersInChat", "membersInGame", "membersOnline", "hoursOnRecord"];
-  const floatFields = ["hoursPlayed2Wk", "hoursPlayed"];
-  for (const field of numberFields) {
-    if (field in profile) profile[field] = parseInt(profile[field], 10) || 0;
-  }
-  for (const field of floatFields) {
-    if (field in profile) profile[field] = parseFloat(profile[field]) || 0;
-  }
-
-  // Add avatarHash
-  const avatarUrl = profile.avatarFull || profile.avatarMedium || profile.avatarIcon;
-  profile.avatarHash = getAvatarHashFromUrl(avatarUrl);
-
-  const memberSince = profile.memberSince;
-  profile.memberSince = null;
-  const formats = ["MMMM DD, YYYY", "MMMM D, YYYY", "MMMM DD", "MMMM D"];
-  for (const format of formats) {
-    const memberSinceMoment = moment(memberSince, format, true);
-    if (memberSinceMoment.isValid()) {
-      profile.memberSince = memberSinceMoment.valueOf();
-      break;
-    }
-  }
-
-  // Ensure all simple fields are strings if empty object
-  for (const key in profile) {
-    if (typeof profile[key] === "object" && profile[key] !== null && Object.keys(profile[key]).length === 0) {
-      profile[key] = "";
-    }
-  }
-
-  // Move groups.group to top-level 'groups' if present
-  if (profile.groups && profile.groups.group) {
-    profile.groups = profile.groups.group;
-  }
-
-  // Remove _attributes from groups (if present)
-  if (Array.isArray(profile.groups)) {
-    profile.groups = profile.groups.map((group) => {
-      if (group && typeof group === "object" && "_attributes" in group) {
-        // shallow clone and remove _attributes
-        const { _attributes, ...groupWithoutAttributes } = group;
-        return groupWithoutAttributes;
-      }
-      return group;
-    });
-  }
-
-  return profile;
-}
+import { StringUtils } from "alpha-common-utils/index.js";
+import { formatMarketHistoryDate, getAvatarHashFromUrl } from "./utils.js";
+import * as cheerio from "cheerio";
+import { getJSObjectFronXML } from "./xml2json.js";
+import moment from "moment";
+import { parseString } from "xml2js";
+
+/**
+ * @typedef {Object} HoverItem
+ * @property {string|null} listingId         The listing ID extracted from the selector, if available (as string).
+ * @property {number} appid                  The app (game) ID for this item.
+ * @property {number} contextid              The context ID for this item.
+ * @property {number} assetid                The unique asset ID.
+ * @property {string} unknown                A string field captured from the arguments (usually "0").
+ * @property {string} [name_selector]        The HTML selector for the item's name, if present.
+ * @property {string} [image_selector]       The HTML selector for the item's image, if present.
+ * @property {string} [other_selector]       The selector string if it does not match name/image pattern.
+ */
+
+/**
+ * Extracts item information from Steam inventory trade history or similar HTML fragments.
+ * Scans the given HTML string for calls to `CreateItemHoverFromContainer` and extracts
+ * key data for each referenced item. Returns each item's info in a structured array.
+ *
+ * @param {string} html - The HTML string to parse.
+ * @returns {HoverItem[]} Array of hover item objects.
+ */
+export function extractAssetItemsFromHovers(html) {
+  // Use your preferred HTML/space scrubber.
+  html = StringUtils.cleanSpace(html);
+
+  // RegExp for CreateItemHoverFromContainer arguments
+  const re = /CreateItemHoverFromContainer\s*\(\s*g_rgAssets\s*,\s*'([^']+)'\s*,\s*(\d+)\s*,\s*'(\d+)'\s*,\s*'(\d+)'\s*,\s*(\d+)\s*\)/g;
+
+  /** @type {Record<number, HoverItem>} */
+  const itemsMap = {};
+  let match;
+
+  while ((match = re.exec(html)) !== null) {
+    const [_, selector, appid, contextid, assetid, unknown] = match;
+
+    // Extract listingId as a string if present: "history_row_<listingId>_"
+    let listingId = null;
+    const lidMatch = selector.match(/history_row_(\d+)_/);
+    if (lidMatch) listingId = lidMatch[1]; // assign as string
+
+    const appidNum = Number(appid);
+    const contextidNum = Number(contextid);
+    const assetidNum = Number(assetid);
+
+    if (!itemsMap[assetidNum]) {
+      itemsMap[assetidNum] = {
+        listingId,
+        appid: appidNum,
+        contextid: contextidNum,
+        assetid: assetidNum,
+        unknown,
+      };
+    }
+
+    if (selector.endsWith("_name")) {
+      itemsMap[assetidNum].name_selector = selector;
+    } else if (selector.endsWith("_image")) {
+      itemsMap[assetidNum].image_selector = selector;
+    } else {
+      itemsMap[assetidNum].other_selector = selector;
+    }
+  }
+  return Object.values(itemsMap);
+}
+
+/**
+ * @typedef {Object} MarketHistoryListing
+ * @property {string} id - HTML row id attribute (e.g. "history_row_4316182845737233773_4316182845737233774").
+ * @property {string} listingId - Listing id (e.g. "4316182845737233773").
+ * @property {number} price - Price in integer form (e.g. 80270).
+ * @property {string} itemName - The market item's name (e.g. "UMP-45 | Mudder").
+ * @property {string} gameName - The game's name (e.g. "Counter-Strike 2").
+ * @property {string} listedOn - Listing date as string (e.g. "27 May 2024").
+ * @property {string} actedOn - Acted on date or empty string.
+ * @property {string} image - Full image URL for the item.
+ * @property {string} gainOrLoss - "+" for buys, "-" for sells.
+ * @property {string} status - Status text, usually empty string.
+ * @property {string} [assetId] - (optional) Associated asset id, if available.
+ */
+
+/**
+ * Parses Steam market history listing rows into structured data objects.
+ *
+ * @param {string} html - The raw HTML string to parse.
+ * @param {Object} [assetByListingId={}] - Optional mapping of listingId to assetId.
+ * @returns {MarketHistoryListing[]} Array of market listing objects.
+ */
+export function parseMarketHistoryListings(html, assetByListingId = {}) {
+  const $ = cheerio.load(html);
+  return $(".market_listing_row")
+    .toArray()
+    .map((el) => {
+      const $el = $(el);
+      const id = $el.attr("id");
+      const listingId = id?.match(/history_row_(.*?)_/)?.[1];
+      if (!listingId) return null;
+      const [gainOrLoss, image, priceText, itemName, gameName, listedOnText, actedOnText, status] = [$el.find(".market_listing_gainorloss").text().trim(), $el.find(".market_listing_item_img").attr("src"), $el.find(".market_table_value .market_listing_price").text(), $el.find(".market_listing_item_name").text().trim(), $el.find(".market_listing_game_name").text().trim(), $el.find(".market_listing_listed_date + .market_listing_listed_date").text(), $el.find(".market_listing_whoactedwith + .market_listing_listed_date").text(), $el.find(".market_listing_whoactedwith").text().trim()];
+      const price = parseInt(priceText.replace(/[₫().,]/g, "").trim(), 10) || "";
+      const listedOn = typeof formatMarketHistoryDate === "function" ? formatMarketHistoryDate(listedOnText.replace(/Listed:/, "").trim()) : listedOnText.replace(/Listed:/, "").trim();
+      const actedOn = typeof formatMarketHistoryDate === "function" ? formatMarketHistoryDate(actedOnText.replace(/Listed:/, "").trim()) : actedOnText.replace(/Listed:/, "").trim();
+
+      const result = {
+        id,
+        listingId,
+        price,
+        itemName,
+        gameName,
+        listedOn,
+        actedOn,
+        image,
+        gainOrLoss,
+        status,
+      };
+      if (assetByListingId?.[listingId]) result.assetId = assetByListingId[listingId];
+      return result;
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Parses Steam Market HTML listings to an array of items.
+ *
+ * @param {string} html - HTML string containing listing rows.
+ * @returns {Array<{
+ *   listingId: string,
+ *   appId: number,
+ *   contextId: number,
+ *   itemId: number,
+ *   imageUrl: string|null,
+ *   buyerPaysPrice: string,
+ *   receivePrice: string,
+ *   itemName: string,
+ *   gameName: string,
+ *   listedDate: string
+ * }>}
+ */
+export function parseMarketListings(html) {
+  const $ = cheerio.load(html);
+  const results = [];
+
+  $(".market_listing_row").each((index, element) => {
+    const $row = $(element);
+
+    const cancelLink = $row.find(".market_listing_cancel_button > a").attr("href");
+    if (!cancelLink) return;
+
+    const paramsMatch = cancelLink.match(/\(([^)]*)\)/);
+    if (!paramsMatch) return;
+
+    let [, listingId, appId, contextId, itemId] = paramsMatch[1].split(",").map((param) => param.trim().replace(/^['"]|['"]$/g, ""));
+
+    appId = Number(appId);
+    contextId = Number(contextId);
+    itemId = Number(itemId);
+
+    const imageUrl = $row.find(`#mylisting_${listingId}_image`).attr("src") || null;
+
+    const buyerPaysElem = $row.find('.market_listing_price span[title="This is the price the buyer pays."]');
+    const buyerPaysPrice = StringUtils.cleanSpace(buyerPaysElem.text().replace(/[()]/g, ""));
+
+    const receiveElem = $row.find('.market_listing_price span[title="This is how much you will receive."]');
+    const receivePrice = StringUtils.cleanSpace(receiveElem.text().replace(/[()]/g, ""));
+
+    const itemName = $row.find(".market_listing_item_name_link").text() || $row.find(".market_listing_item_name").text();
+
+    const gameName = $row.find(".market_listing_game_name").text();
+
+    const listedDateElem = $row.find(".market_listing_game_name + .market_listing_listed_date_combined");
+    const listedDate = formatMarketHistoryDate(StringUtils.cleanSpace(listedDateElem.text()));
+
+    results.push({
+      listingId,
+      appId,
+      contextId,
+      itemId,
+      imageUrl,
+      buyerPaysPrice,
+      receivePrice,
+      itemName,
+      gameName,
+      listedDate,
+    });
+  });
+
+  return results;
+}
+
+/**
+ * Represents a Steam Community group for a profile.
+ * @typedef {Object} SteamProfileGroupXml
+ * @property {string} groupID64
+ * @property {string} groupName
+ * @property {string} groupURL
+ * @property {string} headline
+ * @property {string} summary
+ * @property {string} avatarIcon
+ * @property {string} avatarMedium
+ * @property {string} avatarFull
+ * @property {number} memberCount
+ * @property {number} membersInChat
+ * @property {number} membersInGame
+ * @property {number} membersOnline
+ */
+
+/**
+ * Array of Steam Community groups.
+ * @typedef {SteamProfileGroupXml[]} SteamProfileGroupsXml
+ */
+
+/**
+ * Represents a most played game on a Steam profile.
+ * @typedef {Object} SteamProfileMostPlayedGameXml
+ * @property {string} gameName
+ * @property {string} gameLink
+ * @property {string} gameIcon
+ * @property {string} gameLogo
+ * @property {string} gameLogoSmall
+ * @property {number} hoursPlayed
+ * @property {number} hoursOnRecord
+ * @property {string} statsName
+ */
+
+/**
+ * Array of most played games.
+ * @typedef {SteamProfileMostPlayedGameXml[]} SteamProfileMostPlayedGamesXml
+ */
+
+/**
+ * Steam Community profile (parsed from XML, normalized).
+ * @typedef {Object} SteamProfileXml
+ * @property {string} name
+ * @property {string} steamId
+ * @property {string} onlineState
+ * @property {string} stateMessage
+ * @property {string} privacyState
+ * @property {number} visibilityState
+ * @property {string} avatarIcon
+ * @property {string} avatarMedium
+ * @property {string} avatarFull
+ * @property {string} avatarHash
+ * @property {number} vacBanned
+ * @property {string} tradeBanState
+ * @property {number} isLimitedAccount
+ * @property {string} customURL
+ * @property {number | null} memberSince
+ * @property {string} steamRating
+ * @property {number} hoursPlayed2Wk
+ * @property {string} headline
+ * @property {string} location
+ * @property {string} realname
+ * @property {string} summary
+ * @property {SteamProfileMostPlayedGamesXml} [mostPlayedGames]
+ * @property {SteamProfileGroupsXml} [groups]
+ */
+
+/**
+ * Parses a Steam profile XML into a normalized JSON format.
+ *
+ * @param {string} xml - The XML string as returned by the Steam Community profile endpoint.
+ * @returns {SteamProfileXml|undefined} The normalized profile object or undefined on error.
+ *
+ * @example
+ * import { parseSteamProfileXmlToJson } from "./your-module";
+ * const xml = await fetch('https://steamcommunity.com/profiles/76561198386265483/?xml=1').then(r => r.text());
+ * const profile = parseSteamProfileXmlToJson(xml);
+ * console.log(profile.name);
+ */
+export function parseSteamProfileXmlToJson(xml) {
+  if (guessDocumentType(xml) !== "xml") return;
+
+  const parsed = getJSObjectFronXML(xml);
+  if (!parsed || !parsed.profile) return;
+
+  // Flatten out the xml2js _structure, for direct children
+  const profile = {};
+  Object.entries(parsed.profile).forEach(([key, value]) => {
+    // If only text, keep as string
+    if (typeof value === "object" && value !== null && "_" in value && Object.keys(value).length === 1) {
+      profile[key] = value._;
+    } else {
+      profile[key] = value;
+    }
+  });
+
+  // Rename fields
+  if ("steamID" in profile) {
+    profile.name = profile.steamID;
+    delete profile.steamID;
+  }
+  if ("steamID64" in profile) {
+    profile.steamId = profile.steamID64;
+    delete profile.steamID64;
+  }
+
+  // Convert numbers
+  const numberFields = ["vacBanned", "isLimitedAccount", "visibilityState", "memberCount", "membersInChat", "membersInGame", "membersOnline", "hoursOnRecord"];
+  const floatFields = ["hoursPlayed2Wk", "hoursPlayed"];
+  for (const field of numberFields) {
+    if (field in profile) profile[field] = parseInt(profile[field], 10) || 0;
+  }
+  for (const field of floatFields) {
+    if (field in profile) profile[field] = parseFloat(profile[field]) || 0;
+  }
+
+  // Add avatarHash
+  const avatarUrl = profile.avatarFull || profile.avatarMedium || profile.avatarIcon;
+  profile.avatarHash = getAvatarHashFromUrl(avatarUrl);
+
+  const memberSince = profile.memberSince;
+  profile.memberSince = null;
+  const formats = ["MMMM DD, YYYY", "MMMM D, YYYY", "MMMM DD", "MMMM D"];
+  for (const format of formats) {
+    const memberSinceMoment = moment(memberSince, format, true);
+    if (memberSinceMoment.isValid()) {
+      profile.memberSince = memberSinceMoment.valueOf();
+      break;
+    }
+  }
+
+  // Ensure all simple fields are strings if empty object
+  for (const key in profile) {
+    if (typeof profile[key] === "object" && profile[key] !== null && Object.keys(profile[key]).length === 0) {
+      profile[key] = "";
+    }
+  }
+
+  // Move groups.group to top-level 'groups' if present
+  if (profile.groups && profile.groups.group) {
+    profile.groups = profile.groups.group;
+  }
+
+  // Remove _attributes from groups (if present)
+  if (Array.isArray(profile.groups)) {
+    profile.groups = profile.groups.map((group) => {
+      if (group && typeof group === "object" && "_attributes" in group) {
+        // shallow clone and remove _attributes
+        const { _attributes, ...groupWithoutAttributes } = group;
+        return groupWithoutAttributes;
+      }
+      return group;
+    });
+  }
+
+  return profile;
+}
+
+/**
+ * Attempts to heuristically determine if the input string is XML, HTML, or unknown.
+ *
+ * Checks for XML declarations, HTML DOCTYPE or root tags, XML namespaces, common error page patterns,
+ * and known XML root elements. Optionally uses strict XML parsing (if xml2js is installed) as a fallback.
+ *
+ * @param {string} input - The markup document as a string to be analyzed.
+ * @returns {"xml"|"html"|"unknown"} - Returns 'xml' if input appears to be XML, 'html' for HTML, or 'unknown' if indeterminate.
+ *
+ * @example
+ * guessDocumentType('<?xml version="1.0"?><profile></profile>'); // 'xml'
+ * guessDocumentType('<!DOCTYPE html><html><body></body></html>'); // 'html'
+ * guessDocumentType('<svg xmlns="http://www.w3.org/2000/svg"></svg>'); // 'xml'
+ * guessDocumentType('random text'); // 'unknown'
+ */
+export function guessDocumentType(input) {
+  if (typeof input !== "string" || !input.trim()) return "unknown";
+  const trimmed = input.trim();
+
+  // XML declaration
+  if (/^\s*<\?xml\b/i.test(trimmed)) return "xml";
+
+  // HTML DOCTYPE or <html> as first tag
+  if (/<!DOCTYPE\s+html\b[^>]*>/i.test(trimmed)) return "html";
+  if (/^\s*<html\b[^>]*>/i.test(trimmed)) return "html";
+
+  // Common HTML error patterns
+  if (/<meta\s[^>]*http-equiv=["']?refresh["']?/i.test(trimmed)) return "html";
+  if (/<title>.*(error|not\s*found|forbidden).*<\/title>/i.test(trimmed)) return "html";
+
+  // Root tag clues
+  const rootTagMatch = trimmed.match(/^\s*<([\w:-]+)/);
+  if (rootTagMatch) {
+    const tag = rootTagMatch[1].toLowerCase();
+    // Common XML API roots
+    const xmlLikeRoots = ["rss", "feed", "svg", "profile", "users", "user", "response", "data", "opml", "atom", "plist", "soap:envelope", "xsl:stylesheet"];
+    if (tag === "html") return "html";
+    if (xmlLikeRoots.includes(tag) || tag.includes(":")) return "xml";
+  }
+
+  // Namespace? (usually in XML, rarely HTML)
+  if (/xmlns\s*=\s*['"]/i.test(trimmed)) return "xml";
+
+  // Try strict XML parse (requires xml2js, non-fatal if missing)
+  let isXml = false;
+  try {
+    // xml2js parseString uses a callback, so we wrap in a try/catch for sync usage
+    parseString(trimmed, { strict: true }, (err) => {
+      isXml = !err;
+    });
+    if (isXml) return "xml";
+  } catch (e) {
+    // xml2js parse failed, ignore
+  }
+
+  return "unknown";
+}