cs2-inventory-resolver 0.3.8 → 0.4.0

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { resolveItem, getAttributeUint32 } from './resolver.js';
-export type { ItemEntity, ResolvedItemData, GcItemInput, ItemEntry, InventoryData } from './types.js';
+export type { ItemEntity, TradeStatus, ResolvedItemData, GcItemInput, ItemEntry, InventoryData } from './types.js';

package/dist/resolver.js

@@ -1,4 +1,27 @@
 import { getData } from './data-loader.js';
+/** The `trade_protected_escrow_date` attribute def_index. */
+const TRADE_PROTECTED_ESCROW_DATE = 312;
+/**
+ * Derive the trade state of an item instance from attribute 312
+ * (`trade_protected_escrow_date`).
+ *
+ * - Attribute absent → `'tradable'`.
+ * - Attribute present and `0` → `'market_listed'` (listed on the Steam
+ *   Community Market, kept in inventory until it sells; no clear date).
+ * - Attribute present and a future timestamp → `'trade_hold'`, with the escrow
+ *   expiry returned as an ISO 8601 string.
+ */
+function resolveTradeStatus(gcItem) {
+    const escrow = getAttributeUint32(gcItem, TRADE_PROTECTED_ESCROW_DATE);
+    if (escrow === undefined)
+        return { status: 'tradable', trade_hold_expires: null };
+    if (escrow === 0)
+        return { status: 'market_listed', trade_hold_expires: null };
+    return {
+        status: 'trade_hold',
+        trade_hold_expires: new Date(escrow * 1000).toISOString(),
+    };
+}
 /**
  * Return the wear tier name for a given paint wear float.
  *
@@ -51,12 +74,15 @@ function buildSkinName(name, gcItem) {
 }
 /** Build a {@link ResolvedItemData} from a matched inventory entry. */
 function makeResult(entry, gcItem, entity) {
+    const { status, trade_hold_expires } = resolveTradeStatus(gcItem);
     return {
         name: entity === 'skin' ? buildSkinName(entry.name, gcItem) : entry.name,
         image: entry.image,
         entity,
         rarity: entry.rarity,
         marketable: entry.marketable,
+        status,
+        trade_hold_expires,
     };
 }
 /**

package/dist/resolver.test.js

@@ -345,6 +345,34 @@ describe('resolveItem — wear-name boundaries', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// Trade status (attribute 312 — trade_protected_escrow_date)
+// ---------------------------------------------------------------------------
+describe('resolveItem — trade status', () => {
+    const skin = { def_index: 7, paint_index: 282 };
+    it('is "tradable" when attribute 312 is absent', () => {
+        const result = resolveItem({ ...skin });
+        expect(result.status).toBe('tradable');
+        expect(result.trade_hold_expires).toBeNull();
+    });
+    it('is "market_listed" when attribute 312 is 0', () => {
+        const result = resolveItem({ ...skin, attribute: [makeAttr(312, 0)] });
+        expect(result.status).toBe('market_listed');
+        expect(result.trade_hold_expires).toBeNull();
+    });
+    it('is "trade_hold" with an ISO expiry when attribute 312 is a future date', () => {
+        // 1781161200 = 2026-06-11T07:00:00.000Z
+        const result = resolveItem({ ...skin, attribute: [makeAttr(312, 1781161200)] });
+        expect(result.status).toBe('trade_hold');
+        expect(result.trade_hold_expires).toBe('2026-06-11T07:00:00.000Z');
+    });
+    it('resolves trade status for non-skin entities too', () => {
+        const crateId = firstKey(data.crates);
+        const result = resolveItem({ def_index: crateId, attribute: [makeAttr(312, 0)] });
+        expect(result.entity).toBe('crate');
+        expect(result.status).toBe('market_listed');
+    });
+});
+// ---------------------------------------------------------------------------
 // Numeric edge cases
 // ---------------------------------------------------------------------------
 describe('resolveItem — numeric edge cases', () => {

package/dist/types.d.ts

@@ -1,5 +1,19 @@
 /** 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';
+/**
+ * Current trade state of a specific item instance, derived from attribute 312
+ * (`trade_protected_escrow_date`).
+ *
+ * - `'tradable'` — no hold; the item can be freely traded and moved to/from storage.
+ * - `'market_listed'` — listed on the Steam Community Market and kept in the
+ *   inventory until it sells (escrow date is `0`).
+ * - `'trade_hold'` — under a trade-protection / escrow hold (escrow date is a
+ *   future timestamp).
+ *
+ * Items that are `'market_listed'` or `'trade_hold'` cannot be moved into or out
+ * of a storage unit.
+ */
+export type TradeStatus = 'tradable' | 'market_listed' | 'trade_hold';
 /** The resolved information for a CS2 inventory item. */
 export interface ResolvedItemData {
     /** The human-readable item name (e.g. `"AK-47 | Redline"`). */
@@ -16,6 +30,13 @@ export interface ResolvedItemData {
     } | null;
     /** Whether the item is marketable on the Steam Community Market. */
     marketable: boolean;
+    /** Current trade state of this specific item instance. See {@link TradeStatus}. */
+    status: TradeStatus;
+    /**
+     * When a trade hold expires, as an ISO 8601 string, or `null`.
+     * Always `null` for `'tradable'` and `'market_listed'` (held until sold).
+     */
+    trade_hold_expires: string | null;
 }
 /**
  * Raw GC (Game Coordinator) item input accepted by {@link resolveItem}.
@@ -39,7 +60,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), and `highlight_index` (def_index 314) via {@link getAttributeUint32}.
+     * `keychain_index` (def_index 299), `highlight_index` (def_index 314), and the
+     * `trade_protected_escrow_date` (def_index 312) via {@link getAttributeUint32}.
      */
     attribute?: {
         def_index: number;

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "cs2-inventory-resolver",
-  "version": "0.3.8",
-  "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.0",
+  "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"
+  }
+}