@axiapps/gw2-data 0.1.0

package/data/overrides.json

@@ -0,0 +1,25 @@
+{
+  "trait:1719": {
+    "implicitFury": true,
+    "description": "Roiling Mists: has fury crit bonus but no Buff(Fury) fact in API"
+  },
+  "trait:1016": {
+    "petStatOnly": true,
+    "description": "Fang and Claw: AttributeAdjust facts apply to pets, not player"
+  },
+  "trait:1765": {
+    "mightOverride": { "power": 40, "condi": 20 },
+    "description": "Notoriety: modifies Might per-stack values (+40P/+20CD instead of +30P/+30CD)"
+  },
+  "trait:2220": {
+    "allyTargeted": ["elixir"],
+    "description": "Twisted Medicine: elixir skills become ally-targeted"
+  },
+  "trait:1831": {
+    "description": "Primal Rage: grants access to Primal Bursts (no burst recharge reduction)"
+  },
+  "trait:2046": {
+    "berserkConditional": true,
+    "description": "Fatal Frenzy: stat bonuses only apply while in berserk mode"
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@axiapps/gw2-data",
+  "version": "0.1.0",
+  "description": "GW2 data library — wiki-sourced facts, GW2 API structural data, and stat computation",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./wiki": "./src/wiki/client.js",
+    "./api": "./src/api/client.js",
+    "./facts": "./src/facts/merge.js",
+    "./engine": "./src/engine/index.js"
+  },
+  "scripts": {
+    "test": "jest"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": ["**/packages/gw2-data/tests/**/*.test.js"],
+    "clearMocks": true,
+    "testTimeout": 15000
+  },
+  "license": "MIT",
+  "keywords": ["gw2", "guild-wars-2", "wiki", "api", "build-editor"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/darkharasho/axiforge",
+    "directory": "packages/gw2-data"
+  },
+  "devDependencies": {
+    "jest": "^30.3.0"
+  }
+}

package/scripts/generate-fixtures.js

@@ -0,0 +1,242 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { computeAttributes } = require("../src/engine/attributes");
+const { hydrateCatalogs } = require("../tests/engine/test-utils");
+
+const FIXTURE_DIR = path.join(__dirname, "../tests/engine/fixtures");
+
+const fixtures = [
+  {
+    name: "Berserker Warrior",
+    description: "Heavy armor, 3-stat, full ascended, signets, Might+Fury assumed",
+    ctx: {
+      profession: "Warrior",
+      specializations: [
+        { id: 4, majorChoices: { 1: 1444, 2: 1449, 3: 1437 } },
+      ],
+      equipment: {
+        slots: {
+          head: "Berserker's", shoulders: "Berserker's", chest: "Berserker's",
+          gloves: "Berserker's", legs: "Berserker's", boots: "Berserker's",
+          mainhand1: "Berserker's", offhand1: "Berserker's",
+          back: "Berserker's", accessory1: "Berserker's", accessory2: "Berserker's",
+          amulet: "Berserker's", ring1: "Berserker's", ring2: "Berserker's",
+        },
+        weapons: { mainhand1: "greatsword" },
+        runes: {},
+        infusions: {},
+        enrichment: null,
+        food: null,
+        utility: null,
+      },
+      gameMode: "pve",
+      underwaterMode: false,
+      activeWeaponSet: 1,
+      skills: { healId: null, utilityIds: [9093], eliteId: null },
+      assumedBoons: { might: 25, fury: true },
+      sigilStacks: null,
+    },
+    catalogs: {
+      traits: [
+        { id: 1444, facts: [{ type: "AttributeAdjust", target: "Power", value: 120 }] },
+        { id: 1449, facts: [] },
+        { id: 1437, facts: [] },
+      ],
+      specializations: [{ id: 4, minorTraits: [] }],
+      skills: [],
+      runes: [],
+      foods: [],
+      utilities: [],
+      infusions: [],
+      enrichments: [],
+    },
+  },
+  {
+    name: "Viper Mirage",
+    description: "Medium armor, 4-stat, trait conversions, food + utility",
+    ctx: {
+      profession: "Mesmer",
+      specializations: [
+        { id: 24, majorChoices: { 1: 700 } },
+      ],
+      equipment: {
+        slots: {
+          head: "Viper's", shoulders: "Viper's", chest: "Viper's",
+          gloves: "Viper's", legs: "Viper's", boots: "Viper's",
+          mainhand1: "Viper's",
+          back: "Viper's", accessory1: "Viper's", accessory2: "Viper's",
+          amulet: "Viper's", ring1: "Viper's", ring2: "Viper's",
+        },
+        weapons: { mainhand1: "axe" },
+        runes: {},
+        infusions: {},
+        enrichment: null,
+        food: 91805,
+        utility: null,
+      },
+      gameMode: "pve",
+      underwaterMode: false,
+      activeWeaponSet: 1,
+      skills: { healId: null, utilityIds: [], eliteId: null },
+      assumedBoons: null,
+      sigilStacks: null,
+    },
+    catalogs: {
+      traits: [
+        { id: 700, facts: [{ type: "BuffConversion", source: "Vitality", target: "ConditionDamage", percent: 10 }] },
+      ],
+      specializations: [{ id: 24, minorTraits: [] }],
+      skills: [],
+      runes: [],
+      foods: [{ id: 91805, name: "Plate of Beef Rendang", buff: "+100 Expertise\n+70 Condition Damage" }],
+      utilities: [],
+      infusions: [],
+      enrichments: [],
+    },
+  },
+  {
+    name: "Celestial Firebrand WvW",
+    description: "Heavy armor, 9-stat, WvW Celestial exclusion, rune bonuses",
+    ctx: {
+      profession: "Guardian",
+      specializations: [],
+      equipment: {
+        slots: {
+          head: "Celestial", shoulders: "Celestial", chest: "Celestial",
+          gloves: "Celestial", legs: "Celestial", boots: "Celestial",
+          mainhand1: "Celestial",
+          back: "Celestial", accessory1: "Celestial", accessory2: "Celestial",
+          amulet: "Celestial", ring1: "Celestial", ring2: "Celestial",
+        },
+        weapons: { mainhand1: "axe" },
+        runes: {
+          head: 24836, shoulders: 24836, chest: 24836,
+          gloves: 24836, legs: 24836, boots: 24836,
+        },
+        infusions: {},
+        enrichment: null,
+        food: null,
+        utility: null,
+      },
+      gameMode: "wvw",
+      underwaterMode: false,
+      activeWeaponSet: 1,
+      skills: { healId: null, utilityIds: [], eliteId: null },
+      assumedBoons: null,
+      sigilStacks: null,
+    },
+    catalogs: {
+      traits: [],
+      specializations: [],
+      skills: [],
+      runes: [{ id: 24836, name: "Superior Rune of the Scholar", bonuses: ["+25 Power", "+35 Ferocity", "+50 Power", "+65 Ferocity", "+100 Power", "+125 Ferocity"] }],
+      foods: [],
+      utilities: [],
+      infusions: [],
+      enrichments: [],
+    },
+  },
+  {
+    name: "Harrier Druid",
+    description: "Medium armor, 3-stat healing, enrichment, infusions",
+    ctx: {
+      profession: "Ranger",
+      specializations: [],
+      equipment: {
+        slots: {
+          head: "Harrier's", shoulders: "Harrier's", chest: "Harrier's",
+          gloves: "Harrier's", legs: "Harrier's", boots: "Harrier's",
+          mainhand1: "Harrier's",
+          back: "Harrier's", accessory1: "Harrier's", accessory2: "Harrier's",
+          amulet: "Harrier's", ring1: "Harrier's", ring2: "Harrier's",
+        },
+        weapons: { mainhand1: "staff" },
+        runes: {},
+        infusions: {
+          head: [49432], shoulders: [49432], chest: [49432],
+          gloves: [49432], legs: [49432], boots: [49432],
+        },
+        enrichment: 78061,
+        food: null,
+        utility: null,
+      },
+      gameMode: "pve",
+      underwaterMode: false,
+      activeWeaponSet: 1,
+      skills: { healId: null, utilityIds: [], eliteId: null },
+      assumedBoons: null,
+      sigilStacks: null,
+    },
+    catalogs: {
+      traits: [],
+      specializations: [],
+      skills: [],
+      runes: [],
+      foods: [],
+      utilities: [],
+      infusions: [{ id: 49432, name: "+5 Healing Power Infusion", infixUpgrade: { attributes: [{ attribute: "Healing", modifier: 5 }] } }],
+      enrichments: [{ id: 78061, name: "+10 Concentration Enrichment", infixUpgrade: { attributes: [{ attribute: "BoonDuration", modifier: 10 }] } }],
+    },
+  },
+  {
+    name: "Berserker Thief",
+    description: "Medium armor, sparse gear (testing empty slots gracefully)",
+    ctx: {
+      profession: "Thief",
+      specializations: [],
+      equipment: {
+        slots: { chest: "Berserker's", legs: "Berserker's" },
+        weapons: {},
+        runes: {},
+        infusions: {},
+        enrichment: null,
+        food: null,
+        utility: null,
+      },
+      gameMode: "pve",
+      underwaterMode: false,
+      activeWeaponSet: 1,
+      skills: { healId: null, utilityIds: [], eliteId: null },
+      assumedBoons: null,
+      sigilStacks: null,
+    },
+    catalogs: {
+      traits: [],
+      specializations: [],
+      skills: [],
+      runes: [],
+      foods: [],
+      utilities: [],
+      infusions: [],
+      enrichments: [],
+    },
+  },
+];
+
+// Generate fixtures
+if (!fs.existsSync(FIXTURE_DIR)) {
+  fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+}
+
+for (const fixture of fixtures) {
+  const catalogs = hydrateCatalogs(fixture.catalogs);
+  const result = computeAttributes(fixture.ctx, catalogs);
+  const output = {
+    name: fixture.name,
+    description: fixture.description,
+    ctx: fixture.ctx,
+    catalogs: fixture.catalogs,
+    expected: {
+      total: result.total,
+      derived: result.derived,
+    },
+  };
+  const filename = fixture.name.toLowerCase().replace(/\s+/g, "-") + ".json";
+  const filepath = path.join(FIXTURE_DIR, filename);
+  fs.writeFileSync(filepath, JSON.stringify(output, null, 2) + "\n");
+  console.log(`Generated: ${filename}`);
+}
+
+console.log("Done!");

package/src/api/client.js

@@ -0,0 +1,117 @@
+"use strict";
+
+const { MemoryCache } = require("../wiki/cache");
+
+const GW2_API_ROOT = "https://api.guildwars2.com";
+const MAX_IDS_PER_REQUEST = 180;
+const MAX_RETRIES = 3;
+const MAX_CONCURRENT = 3;
+const RATE_LIMIT_DELAY_MS = 2000;
+const USER_AGENT = "@axiapps/gw2-data (https://github.com/darkharasho/axiforge)";
+
+class Gw2ApiClient {
+  /**
+   * @param {Object} options
+   * @param {import('../wiki/cache').CacheAdapter} options.cache - Cache adapter
+   * @param {Function} [options.fetch] - Fetch implementation (defaults to global fetch)
+   * @param {string} [options.apiRoot] - GW2 API root URL
+   * @param {string} [options.lang] - Language code (default: "en")
+   */
+  constructor(options = {}) {
+    this._cache = options.cache || new MemoryCache();
+    this._fetch = options.fetch || globalThis.fetch;
+    this._apiRoot = options.apiRoot || GW2_API_ROOT;
+    this._lang = options.lang || "en";
+    this._queue = [];
+    this._activeRequests = 0;
+  }
+
+  async fetchJson(url) {
+    let lastError;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      const res = await this._enqueue(() =>
+        this._fetch(url, {
+          headers: { "User-Agent": USER_AGENT },
+        })
+      );
+      if (res.ok) {
+        return res.json();
+      }
+      if (res.status === 429) {
+        await this._delay(RATE_LIMIT_DELAY_MS);
+        continue;
+      }
+      lastError = new Error(`HTTP ${res.status} ${res.statusText}: ${url}`);
+      if (res.status >= 500) {
+        await this._delay(500 * (attempt + 1));
+        continue;
+      }
+      throw lastError;
+    }
+    throw lastError;
+  }
+
+  async fetchByIds(endpoint, ids, lang) {
+    const dedupedIds = [...new Set(ids)];
+    const chunks = this._chunk(dedupedIds, MAX_IDS_PER_REQUEST);
+    const langParam = lang || this._lang;
+    const results = [];
+
+    for (const chunk of chunks) {
+      const url = `${this._apiRoot}${endpoint}?ids=${chunk.join(",")}&lang=${langParam}`;
+      const data = await this.fetchJson(url);
+      results.push(...data);
+    }
+
+    return results;
+  }
+
+  async fetchCached(key, url, ttlMs) {
+    const cached = await this._cache.get(key);
+    if (cached !== null) return cached;
+
+    const data = await this.fetchJson(url);
+    await this._cache.set(key, data, ttlMs);
+    return data;
+  }
+
+  _chunk(arr, size) {
+    const chunks = [];
+    for (let i = 0; i < arr.length; i += size) {
+      chunks.push(arr.slice(i, i + size));
+    }
+    return chunks;
+  }
+
+  _delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  _enqueue(fn) {
+    return new Promise((resolve, reject) => {
+      this._queue.push({ fn, resolve, reject });
+      this._drain();
+    });
+  }
+
+  _drain() {
+    while (this._queue.length > 0 && this._activeRequests < MAX_CONCURRENT) {
+      const { fn, resolve, reject } = this._queue.shift();
+      this._activeRequests++;
+      fn()
+        .then(resolve)
+        .catch(reject)
+        .finally(() => {
+          this._activeRequests--;
+          this._drain();
+        });
+    }
+  }
+}
+
+module.exports = {
+  Gw2ApiClient,
+  GW2_API_ROOT,
+  MAX_IDS_PER_REQUEST,
+  USER_AGENT,
+};

package/src/api/types.js

@@ -0,0 +1,80 @@
+"use strict";
+
+/**
+ * @typedef {'pve'|'wvw'|'pvp'} GameMode
+ */
+
+/**
+ * @typedef {Object} Fact
+ * @property {string} type - Fact type (Damage, Buff, AttributeAdjust, Recharge, etc.)
+ * @property {string} text - Display label
+ * @property {string} [icon] - Icon URL
+ * @property {number} [value] - Numeric value (AttributeAdjust, Number)
+ * @property {number} [duration] - Duration in seconds (Buff, Time)
+ * @property {number} [apply_count] - Stack count (Buff)
+ * @property {string} [status] - Buff/condition name (Buff)
+ * @property {number} [dmg_multiplier] - Damage coefficient (Damage)
+ * @property {number} [hit_count] - Number of hits (Damage)
+ * @property {number} [distance] - Distance/radius in units (Distance, Radius)
+ * @property {number} [percent] - Percentage value (Percent)
+ * @property {number} [coefficient] - Healing/barrier coefficient
+ * @property {string} [target] - Target attribute (AttributeAdjust, BuffConversion)
+ * @property {string} [source] - Source attribute (BuffConversion)
+ * @property {string} [finisher_type] - Combo finisher type (ComboFinisher)
+ * @property {string} [field_type] - Combo field type (ComboField)
+ * @property {boolean} [_splitFact] - Marked true when fact value comes from a balance split
+ * @property {boolean} [_traitedFact] - Marked true when fact is from traited_facts
+ * @property {boolean} [_newFact] - Marked true when fact was added by split (not in API)
+ */
+
+/**
+ * @typedef {Object} ResolvedSkill
+ * @property {number} id - Skill ID
+ * @property {string} name - Skill name
+ * @property {string} description - Skill description
+ * @property {string} icon - Icon URL
+ * @property {string} [slot] - Slot type (Weapon_1-5, Heal, Utility, Elite, Profession_1-5)
+ * @property {number} [specialization] - Required specialization ID
+ * @property {string[]} [professions] - Professions that can use this skill
+ * @property {Fact[]} facts - Resolved facts for the requested game mode
+ * @property {Fact[]} [traited_facts] - Facts that change when specific traits are active
+ * @property {boolean} [hasSplit] - True if facts differ from PvE in this game mode
+ */
+
+/**
+ * @typedef {Object} ResolvedTrait
+ * @property {number} id - Trait ID
+ * @property {string} name - Trait name
+ * @property {string} description - Trait description
+ * @property {string} icon - Icon URL
+ * @property {number} specialization - Specialization ID
+ * @property {number} tier - Trait tier (1=minor adept, 2=major adept, etc.)
+ * @property {number} order - Position in tier (0, 1, 2)
+ * @property {Fact[]} facts - Resolved facts for the requested game mode
+ * @property {Fact[]} [traited_facts] - Conditional facts
+ * @property {boolean} [hasSplit] - True if facts differ from PvE
+ */
+
+/**
+ * @typedef {Object} SplitEntry
+ * @property {Fact[]} facts - Facts for this game mode
+ * @property {boolean} [complete] - If true, this is the full fact set (not partial)
+ */
+
+/**
+ * @typedef {Object} WikiRelation
+ * @property {string} name - Related entity name
+ * @property {string} [icon] - Icon URL
+ * @property {string} [context] - Description of the relationship
+ */
+
+/**
+ * @typedef {Object} CacheAdapter
+ * @property {(key: string) => any|null} get
+ * @property {(key: string, value: any, ttlMs: number) => void} set
+ * @property {(key: string) => void} invalidate
+ * @property {() => void} clear
+ * @property {(key: string) => boolean} has
+ */
+
+module.exports = {};