cs2-inventory-resolver 0.1.0

package/dist/data-loader.d.ts

@@ -0,0 +1,2 @@
+import type { InventoryData } from './types.js';
+export declare function getData(): InventoryData;

package/dist/data-loader.js

@@ -0,0 +1,9 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+let data = null;
+export function getData() {
+    if (!data) {
+        data = require('../data/inventory.json');
+    }
+    return data;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { resolveItem, getAttributeUint32 } from './resolver.js';
+export type { ItemCategory, ResolvedItemData, GcItemInput } from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { resolveItem, getAttributeUint32 } from './resolver.js';

package/dist/resolver.d.ts

@@ -0,0 +1,45 @@
+import type { GcItemInput, ResolvedItemData } from './types.js';
+/**
+ * Resolve a raw GC item into a name, image, and category.
+ *
+ * Resolution priority:
+ * 1. Skins (by `def_index` + `paint_index`)
+ * 2. Music kits (by attribute 166)
+ * 3. Keychains (by attribute 299)
+ * 4. Graffiti (by `stickers[0].sticker_id` + attribute 233)
+ * 5. Crates / cases / keys (by `def_index`)
+ * 6. Collectibles (by `def_index`)
+ * 7. Stickers / patches (by `stickers[0].sticker_id`)
+ *
+ * @param gcItem - The raw GC item to resolve.
+ * @returns The resolved item data, or `null` if the item could not be identified.
+ *
+ * @example
+ * ```ts
+ * const result = resolveItem({ def_index: 7, paint_index: 282 });
+ * // => { name: "AK-47 | Redline", image: "https://...", category: "skin" }
+ * ```
+ */
+export declare function resolveItem(gcItem: GcItemInput): ResolvedItemData | null;
+/**
+ * Read a uint32 value from a raw GC item's attribute[] array.
+ *
+ * Each attribute has a `def_index` identifying which attribute it is, and
+ * `value_bytes` containing the raw little-endian bytes.
+ *
+ * @param item - An object with an optional `attribute` array (typically a {@link GcItemInput}).
+ * @param attrDefIndex - The attribute definition index to look up.
+ * @returns The decoded uint32 value, or `undefined` if the attribute is missing or too short.
+ *
+ * @example
+ * ```ts
+ * const musicIndex = getAttributeUint32(gcItem, 166);
+ * if (musicIndex) console.log("Music kit ID:", musicIndex);
+ * ```
+ */
+export declare function getAttributeUint32(item: {
+    attribute?: {
+        def_index: number;
+        value_bytes?: Buffer;
+    }[];
+}, attrDefIndex: number): number | undefined;

package/dist/resolver.js

@@ -0,0 +1,105 @@
+import { getData } from './data-loader.js';
+/**
+ * Resolve a raw GC item into a name, image, and category.
+ *
+ * Resolution priority:
+ * 1. Skins (by `def_index` + `paint_index`)
+ * 2. Music kits (by attribute 166)
+ * 3. Keychains (by attribute 299)
+ * 4. Graffiti (by `stickers[0].sticker_id` + attribute 233)
+ * 5. Crates / cases / keys (by `def_index`)
+ * 6. Collectibles (by `def_index`)
+ * 7. Stickers / patches (by `stickers[0].sticker_id`)
+ *
+ * @param gcItem - The raw GC item to resolve.
+ * @returns The resolved item data, or `null` if the item could not be identified.
+ *
+ * @example
+ * ```ts
+ * const result = resolveItem({ def_index: 7, paint_index: 282 });
+ * // => { name: "AK-47 | Redline", image: "https://...", category: "skin" }
+ * ```
+ */
+export function resolveItem(gcItem) {
+    const data = getData();
+    if (!data)
+        return null;
+    const defIdx = String(gcItem.def_index);
+    const musicIndex = getAttributeUint32(gcItem, 166);
+    const graffitiTint = getAttributeUint32(gcItem, 233);
+    const keychainIndex = getAttributeUint32(gcItem, 299);
+    // 1. Skins: def_index + paint_index
+    if (gcItem.paint_index && gcItem.paint_index > 0) {
+        const weapon = data.skins[defIdx];
+        if (weapon) {
+            const skin = weapon[String(gcItem.paint_index)];
+            if (skin)
+                return { name: skin.name, image: skin.image, category: 'skin' };
+        }
+    }
+    // 2. Music kits: music_index (attribute 166)
+    if (musicIndex && musicIndex > 0) {
+        const kit = data.music_kits[String(musicIndex)];
+        if (kit)
+            return { name: kit.name, image: kit.image, category: 'music_kit' };
+    }
+    // 3. Keychains (charms): keychain_index (attribute 299)
+    if (keychainIndex && keychainIndex > 0) {
+        const keychain = data.keychains[String(keychainIndex)];
+        if (keychain)
+            return { name: keychain.name, image: keychain.image, category: 'keychain' };
+    }
+    // 4. Graffiti: stickers[0].sticker_id + graffiti_tint (attribute 233)
+    if (graffitiTint !== undefined && gcItem.stickers?.length) {
+        const stickerId = gcItem.stickers[0].sticker_id;
+        if (stickerId) {
+            const tintedKey = `${stickerId}_${graffitiTint}`;
+            const tinted = data.graffiti[tintedKey];
+            if (tinted)
+                return { name: tinted.name, image: tinted.image, category: 'graffiti' };
+            const mono = data.graffiti[String(stickerId)];
+            if (mono)
+                return { name: mono.name, image: mono.image, category: 'graffiti' };
+        }
+    }
+    // 5. Crates / cases / keys
+    const crate = data.crates[defIdx];
+    if (crate)
+        return { name: crate.name, image: crate.image, category: 'crate' };
+    // 6. Collectibles (coins, pins, etc.)
+    const collectible = data.collectibles[defIdx];
+    if (collectible)
+        return { name: collectible.name, image: collectible.image, category: 'collectible' };
+    // 7. Stickers/patches as items: use stickers[0].sticker_id
+    if (gcItem.stickers?.length) {
+        const stickerId = gcItem.stickers[0].sticker_id;
+        if (stickerId) {
+            const sticker = data.stickers[String(stickerId)];
+            if (sticker)
+                return { name: sticker.name, image: sticker.image, category: 'sticker' };
+        }
+    }
+    return null;
+}
+/**
+ * Read a uint32 value from a raw GC item's attribute[] array.
+ *
+ * Each attribute has a `def_index` identifying which attribute it is, and
+ * `value_bytes` containing the raw little-endian bytes.
+ *
+ * @param item - An object with an optional `attribute` array (typically a {@link GcItemInput}).
+ * @param attrDefIndex - The attribute definition index to look up.
+ * @returns The decoded uint32 value, or `undefined` if the attribute is missing or too short.
+ *
+ * @example
+ * ```ts
+ * const musicIndex = getAttributeUint32(gcItem, 166);
+ * if (musicIndex) console.log("Music kit ID:", musicIndex);
+ * ```
+ */
+export function getAttributeUint32(item, attrDefIndex) {
+    const attrib = (item.attribute || []).find(a => a.def_index === attrDefIndex);
+    if (!attrib?.value_bytes || attrib.value_bytes.length < 4)
+        return undefined;
+    return attrib.value_bytes.readUInt32LE(0);
+}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+/** Possible CS2 item categories returned by {@link resolveItem}. */
+export type ItemCategory = 'skin' | 'music_kit' | 'keychain' | 'graffiti' | 'crate' | 'collectible' | 'sticker';
+/** The resolved information for a CS2 inventory item. */
+export interface ResolvedItemData {
+    /** The human-readable item name (e.g. `"AK-47 | Redline"`). */
+    name: string;
+    /** URL to the item's image. */
+    image: string;
+    /** The resolved item category. */
+    category: ItemCategory;
+}
+/**
+ * Raw GC (Game Coordinator) item input accepted by {@link resolveItem}.
+ *
+ * This mirrors the relevant fields from the CS2 GC protobuf `CSOEconItem` message.
+ */
+export interface GcItemInput {
+    /** The item definition index from the GC protobuf message. */
+    def_index: number;
+    /** The paint/skin index. Non-zero for weapon skins. */
+    paint_index?: number;
+    /** Sticker slots array. Also used for graffiti and sticker/patch items via `sticker_id`. */
+    stickers?: {
+        sticker_id?: number;
+    }[];
+    /**
+     * Raw attribute array from the GC message.
+     *
+     * Used to extract `music_index` (def_index 166), `graffiti_tint` (def_index 233),
+     * and `keychain_index` (def_index 299) via {@link getAttributeUint32}.
+     */
+    attribute?: {
+        def_index: number;
+        value_bytes?: Buffer;
+    }[];
+}
+/** A single entry in the inventory lookup tables. */
+export interface ItemEntry {
+    name: string;
+    image: string;
+}
+/** The full shape of inventory.json from the API. */
+export interface InventoryData {
+    skins: Record<string, Record<string, ItemEntry>>;
+    crates: Record<string, ItemEntry>;
+    collectibles: Record<string, ItemEntry>;
+    stickers: Record<string, ItemEntry>;
+    graffiti: Record<string, ItemEntry>;
+    music_kits: Record<string, ItemEntry>;
+    keychains: Record<string, ItemEntry>;
+    highlights: Record<string, ItemEntry>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "cs2-inventory-resolver",
+  "version": "0.1.0",
+  "description": "Resolve CS2 Game Coordinator protobuf items into human-readable names, images, and categories",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "data/"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  }
+}