cs2-inventory-resolver 0.4.19 → 0.4.21

package/dist/resolver.d.ts

@@ -6,16 +6,17 @@ import type { GcItemInput, ResolvedItemData } from './types.js';
  * 1. Skins (by `def_index` + `paint_index`)
  * 2. Music kits (by attribute 166)
  * 3. Highlights / souvenir charms (by attribute 314)
- * 4. Keychains (by attribute 299)
- * 5. Graffiti (by `stickers[0].sticker_id` + attribute 233)
- * 6. Keys (by `def_index`)
- * 7. Crates / cases (by `def_index`)
- * 8. Collectibles (by `def_index`)
- * 9. Agents (by `def_index`)
- * 10. Tools (by `def_index`)
- * 11. Patches (by `stickers[0].sticker_id`)
- * 12. Stickers (by `stickers[0].sticker_id`)
- * 13. Sticker slabs — TODO: add sticker_slabs resolution
+ * 4. Sticker slabs (by attribute 321)
+ * 5. Keychains (by attribute 299)
+ * 6. Graffiti (by `stickers[0].sticker_id` + attribute 233)
+ * 7. Keys (by `def_index`)
+ * 8. Crates / cases (by `def_index`)
+ * 9. Collectibles (by `def_index`)
+ * 10. Agents (by `def_index`)
+ * 11. Tools (by `def_index`)
+ * 12. Sticker slabs (by `stickers[0].sticker_id`, only for `def_index` 1355)
+ * 13. Patches (by `stickers[0].sticker_id`)
+ * 14. Stickers (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.

package/dist/resolver.js

@@ -1,6 +1,8 @@
 import { getData } from './data-loader.js';
 /** The `trade_protected_escrow_date` attribute def_index. */
 const TRADE_PROTECTED_ESCROW_DATE = 312;
+/** The item def_index shared by every sticker slab. */
+const STICKER_SLAB_DEF_INDEX = 1355;
 /**
  * Derive the trade state of an item instance from attribute 312
  * (`trade_protected_escrow_date`).
@@ -92,16 +94,17 @@ function makeResult(entry, gcItem, entity) {
  * 1. Skins (by `def_index` + `paint_index`)
  * 2. Music kits (by attribute 166)
  * 3. Highlights / souvenir charms (by attribute 314)
- * 4. Keychains (by attribute 299)
- * 5. Graffiti (by `stickers[0].sticker_id` + attribute 233)
- * 6. Keys (by `def_index`)
- * 7. Crates / cases (by `def_index`)
- * 8. Collectibles (by `def_index`)
- * 9. Agents (by `def_index`)
- * 10. Tools (by `def_index`)
- * 11. Patches (by `stickers[0].sticker_id`)
- * 12. Stickers (by `stickers[0].sticker_id`)
- * 13. Sticker slabs — TODO: add sticker_slabs resolution
+ * 4. Sticker slabs (by attribute 321)
+ * 5. Keychains (by attribute 299)
+ * 6. Graffiti (by `stickers[0].sticker_id` + attribute 233)
+ * 7. Keys (by `def_index`)
+ * 8. Crates / cases (by `def_index`)
+ * 9. Collectibles (by `def_index`)
+ * 10. Agents (by `def_index`)
+ * 11. Tools (by `def_index`)
+ * 12. Sticker slabs (by `stickers[0].sticker_id`, only for `def_index` 1355)
+ * 13. Patches (by `stickers[0].sticker_id`)
+ * 14. Stickers (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.
@@ -119,6 +122,7 @@ export function resolveItem(gcItem) {
     const graffitiTint = getAttributeUint32(gcItem, 233);
     const highlightIndex = getAttributeUint32(gcItem, 314);
     const keychainIndex = getAttributeUint32(gcItem, 299);
+    const stickerSlabIndex = getAttributeUint32(gcItem, 321);
     // 1. Skins: def_index + paint_index
     if (gcItem.paint_index && gcItem.paint_index > 0) {
         const weapon = data.skins[defIdx];
@@ -140,13 +144,23 @@ export function resolveItem(gcItem) {
         if (highlight)
             return makeResult(highlight, gcItem, 'highlight');
     }
-    // 4. Keychains (charms): keychain_index (attribute 299)
+    // 4. Sticker slabs: sticker_slab_index (attribute 321)
+    //
+    // Checked before keychains: slabs also carry attribute 299 (a constant slab
+    // marker, not a keychain id), so leaving keychains first would let a slab
+    // resolve as the wrong charm.
+    if (stickerSlabIndex && stickerSlabIndex > 0) {
+        const slab = data.sticker_slabs[String(stickerSlabIndex)];
+        if (slab)
+            return makeResult(slab, gcItem, 'sticker_slab');
+    }
+    // 5. Keychains (charms): keychain_index (attribute 299)
     if (keychainIndex && keychainIndex > 0) {
         const keychain = data.keychains[String(keychainIndex)];
         if (keychain)
             return makeResult(keychain, gcItem, 'keychain');
     }
-    // 5. Graffiti: stickers[0].sticker_id + graffiti_tint (attribute 233)
+    // 6. Graffiti: stickers[0].sticker_id + graffiti_tint (attribute 233)
     if (graffitiTint !== undefined && gcItem.stickers?.length) {
         const stickerId = gcItem.stickers[0].sticker_id;
         if (stickerId) {
@@ -159,38 +173,44 @@ export function resolveItem(gcItem) {
                 return makeResult(mono, gcItem, 'graffiti');
         }
     }
-    // 6. Keys
+    // 7. Keys
     const key = data.keys[defIdx];
     if (key)
         return makeResult(key, gcItem, 'key');
-    // 7. Crates / cases
+    // 8. Crates / cases
     const crate = data.crates[defIdx];
     if (crate)
         return makeResult(crate, gcItem, 'crate');
-    // 8. Collectibles (coins, pins, etc.)
+    // 9. Collectibles (coins, pins, etc.)
     const collectible = data.collectibles[defIdx];
     if (collectible)
         return makeResult(collectible, gcItem, 'collectible');
-    // 9. Agents (characters)
+    // 10. Agents (characters)
     const agent = data.agents[defIdx];
     if (agent)
         return makeResult(agent, gcItem, 'agent');
-    // 10. Tools (Name Tag, Storage Unit, etc.)
+    // 11. Tools (Name Tag, Storage Unit, etc.)
     const tool = data.tools[defIdx];
     if (tool)
         return makeResult(tool, gcItem, 'tool');
-    // 11. Patches: use stickers[0].sticker_id (checked before stickers)
     if (gcItem.stickers?.length) {
         const stickerId = gcItem.stickers[0].sticker_id;
         if (stickerId) {
+            // 12. Sticker slabs: slabs share their id with the applied sticker of the
+            // same design, so only def_index 1355 may resolve to a slab.
+            if (gcItem.def_index === STICKER_SLAB_DEF_INDEX) {
+                const slab = data.sticker_slabs[String(stickerId)];
+                if (slab)
+                    return makeResult(slab, gcItem, 'sticker_slab');
+            }
+            // 13. Patches (checked before stickers)
             const patch = data.patches[String(stickerId)];
             if (patch)
                 return makeResult(patch, gcItem, 'patch');
-            // 12. Stickers
+            // 14. Stickers
             const sticker = data.stickers[String(stickerId)];
             if (sticker)
                 return makeResult(sticker, gcItem, 'sticker');
-            // TODO: add sticker_slabs resolution (separate entity from stickers)
         }
     }
     return null;

package/dist/resolver.test.js

@@ -230,14 +230,39 @@ describe('resolveItem', () => {
         expect(result.name).toBe(data.stickers[String(stickerId)].name);
         expect(typeof result.marketable).toBe('boolean');
     });
-    // 14. Non-skin name is unchanged
+    // 14. Sticker slab
+    it('resolves a sticker slab by attribute 321', () => {
+        const slabId = firstKey(data.sticker_slabs);
+        const result = resolveItem({ def_index: 1355, attribute: [makeAttr(321, slabId)] });
+        expect(result).not.toBeNull();
+        expect(result.entity).toBe('sticker_slab');
+        expect(result.name).toBe(data.sticker_slabs[String(slabId)].name);
+        expect(typeof result.marketable).toBe('boolean');
+    });
+    // 14b. Sticker slab — real GC item (Sticker Slab | rain | Rio 2022)
+    it('resolves a real sticker slab GC item', () => {
+        const result = resolveItem({
+            def_index: 1355,
+            quality: 8,
+            attribute: [
+                makeAttr(299, 37),
+                makeAttr(321, 6110),
+                makeAttr(75, 1786777200),
+            ],
+        });
+        expect(result).not.toBeNull();
+        expect(result.entity).toBe('sticker_slab');
+        expect(result.name).toBe('Sticker Slab | rain | Rio 2022');
+        expect(result.image).toBe(data.sticker_slabs['6110'].image);
+    });
+    // 15. Non-skin name is unchanged
     it('non-skin entities return name unchanged', () => {
         const crateId = firstKey(data.crates);
         const result = resolveItem({ def_index: crateId });
         expect(result).not.toBeNull();
         expect(result.name).toBe(data.crates[String(crateId)].name);
     });
-    // 15. Unknown item → null
+    // 16. Unknown item → null
     it('returns null for an unknown def_index', () => {
         expect(resolveItem({ def_index: 999999 })).toBeNull();
     });
@@ -261,6 +286,21 @@ describe('resolveItem — priority', () => {
         const result = resolveItem({ def_index: keyId });
         expect(result.entity).toBe('key');
     });
+    it('sticker_id 6110 is a slab at def_index 1355 and a sticker at 1209', () => {
+        const slab = resolveItem({ def_index: 1355, stickers: [{ sticker_id: 6110 }] });
+        expect(slab.entity).toBe('sticker_slab');
+        expect(slab.name).toBe('Sticker Slab | rain | Rio 2022');
+        const sticker = resolveItem({ def_index: 1209, stickers: [{ sticker_id: 6110 }] });
+        expect(sticker.entity).toBe('sticker');
+        expect(sticker.name).toBe('Sticker | rain | Rio 2022');
+    });
+    it('sticker slab attribute 321 takes priority over keychain attribute 299', () => {
+        const result = resolveItem({
+            def_index: 1355,
+            attribute: [makeAttr(299, firstKey(data.keychains)), makeAttr(321, 6110)],
+        });
+        expect(result.entity).toBe('sticker_slab');
+    });
     it('patch takes priority over sticker when sticker_id matches both', () => {
         const patchKeys = Object.keys(data.patches);
         const overlapping = patchKeys.find(k => data.stickers[k]);
@@ -280,6 +320,40 @@ describe('resolveItem — edge cases', () => {
         expect(result).not.toBeNull();
         expect(result.entity).toBe('crate');
     });
+    it('unknown sticker slab id falls through to null', () => {
+        const result = resolveItem({ def_index: 1355, attribute: [makeAttr(321, 999999)] });
+        expect(result).toBeNull();
+    });
+    it('sticker slab id of 0 is treated as absent', () => {
+        const result = resolveItem({ def_index: 1355, attribute: [makeAttr(321, 0)] });
+        expect(result).toBeNull();
+    });
+    it('def_index 1355 with an unknown sticker_id resolves to null', () => {
+        const result = resolveItem({ def_index: 1355, stickers: [{ sticker_id: 999999 }] });
+        expect(result).toBeNull();
+    });
+    it('sticker_id of 0 is treated as absent', () => {
+        const result = resolveItem({ def_index: 1355, stickers: [{ sticker_id: 0 }] });
+        expect(result).toBeNull();
+    });
+    it('resolves trade status for a sticker slab', () => {
+        const result = resolveItem({
+            def_index: 1355,
+            attribute: [makeAttr(321, 6110), makeAttr(312, 0)],
+        });
+        expect(result.entity).toBe('sticker_slab');
+        expect(result.status).toBe('market_listed');
+    });
+    it('StatTrak takes priority over Souvenir when both attributes are present', () => {
+        const result = resolveItem({
+            def_index: 7,
+            paint_index: 282,
+            paint_wear: 0.3,
+            attribute: [makeAttr(80, 1), makeAttr(140, 1)],
+        });
+        expect(result.name).toMatch(/^StatTrak™ /);
+        expect(result.name).not.toContain('Souvenir');
+    });
     it('empty stickers array does not crash', () => {
         const crateId = firstKey(data.crates);
         const result = resolveItem({ def_index: crateId, stickers: [] });

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /** Possible CS2 item entity types returned by {@link resolveItem}. */
-export type ItemEntity = 'skin' | 'music_kit' | 'highlight' | 'keychain' | 'graffiti' | 'crate' | 'key' | 'collectible' | 'agent' | 'tool' | 'patch' | 'sticker';
+export type ItemEntity = 'skin' | 'music_kit' | 'highlight' | 'keychain' | 'graffiti' | 'crate' | 'key' | 'collectible' | 'agent' | 'tool' | 'patch' | 'sticker' | 'sticker_slab';
 /**
  * Current trade state of a specific item instance, derived from attribute 312
  * (`trade_protected_escrow_date`).
@@ -48,7 +48,10 @@ export interface GcItemInput {
     def_index: number;
     /** The paint/skin index. Non-zero for weapon skins. */
     paint_index?: number;
-    /** The item quality (3 = ★ knife/glove, 9 = StatTrak, 12 = Souvenir). */
+    /**
+     * The item quality. Only `3` (★ knife/glove) affects resolution; StatTrak™ and
+     * Souvenir are detected from attributes 80 and 140, not from this field.
+     */
     quality?: number;
     /** The paint wear float (0.0–1.0). Present only for skins. */
     paint_wear?: number;
@@ -60,7 +63,8 @@ export interface GcItemInput {
      * Raw attribute array from the GC message.
      *
      * Used to extract `music_index` (def_index 166), `graffiti_tint` (def_index 233),
-     * `keychain_index` (def_index 299), `highlight_index` (def_index 314), and the
+     * `keychain_index` (def_index 299), `highlight_index` (def_index 314),
+     * `sticker_slab_index` (def_index 321), and the
      * `trade_protected_escrow_date` (def_index 312) via {@link getAttributeUint32}.
      */
     attribute?: {

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "cs2-inventory-resolver",
-  "version": "0.4.19",
-  "description": "Resolve CS2 Game Coordinator protobuf items into human-readable names, images, and categories",
-  "keywords": [
-    "cs2",
-    "csgo",
-    "counter-strike",
-    "steam",
-    "inventory",
-    "skins",
-    "game-coordinator",
-    "protobuf",
-    "resolver",
-    "valve"
-  ],
-  "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",
-    "test": "vitest run"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.0.0"
-  }
-}
+{
+  "name": "cs2-inventory-resolver",
+  "version": "0.4.21",
+  "description": "Resolve CS2 Game Coordinator protobuf items into human-readable names, images, and categories",
+  "keywords": [
+    "cs2",
+    "csgo",
+    "counter-strike",
+    "steam",
+    "inventory",
+    "skins",
+    "game-coordinator",
+    "protobuf",
+    "resolver",
+    "valve"
+  ],
+  "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",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  }
+}