@nekosuneprojects/warframe-api 0.0.0-stage → 1.0.1

package/data/meta.json

@@ -0,0 +1,14 @@
+{
+  "name": "Warframe",
+  "title": "Cooperative science-fiction action game by Digital Extremes.",
+  "engine": "Evolution",
+  "Platform": "Windows, PlayStation, Xbox, Nintendo Switch, iOS, Android",
+  "Release date": "March 25, 2013",
+  "Genre": "Action RPG, Third-person shooter, Online co-op",
+  "developers": "Digital Extremes",
+  "publisher": "Digital Extremes",
+  "aliases": "WF, Warframe",
+  "image": "https://www.warframe.com/favicon.ico",
+  "description": "Online action game built around collectible Warframes, weapons, companions and the Origin System.",
+  "url": "https://www.warframe.com/"
+}

package/index.js

@@ -0,0 +1,11 @@
+'use strict';
+const {createTracker,TrackerError}=require('./src/tracker');
+const provider=require('./src/provider');
+
+module.exports=createTracker;
+module.exports.Warframe=createTracker;
+module.exports.createTracker=createTracker;
+module.exports.TrackerError=TrackerError;
+module.exports.platforms=provider.platforms;
+module.exports.worldstateFields=provider.worldstateFields;
+module.exports.staticKeys=provider.staticKeys;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@nekosuneprojects/warframe-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "WarframeStat.us live API, offline Warframe characters, and redeem-code/glyph JSON browsing with independent GitHub synchronization.",
+  "main": "index.js",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NekoSuneProjectsNPM/game-tracker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NekoSuneProjectsNPM/game-tracker/issues"
+  },
+  "funding": "https://github.com/NekoSuneProjectsNPM/game-tracker?sponsor",
+  "keywords": [
+    "warframe",
+    "warframe-api",
+    "warframestat",
+    "wfcd",
+    "worldstate",
+    "characters",
+    "json",
+    "offline",
+    "game-tracker",
+    "redeem-codes",
+    "glyphs",
+    "creator-glyphs"
+  ],
+  "author": "NekoSuneVR",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "data/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node scripts/validate-package.js",
+    "prepack": "npm run check && npm test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/catalog.js

@@ -0,0 +1,105 @@
+'use strict';
+
+// Common reusable JSON discovery across any game or category.
+const path = require('node:path');
+
+const normalise = value => String(value ?? '').trim().normalize('NFKC').toLowerCase().replace(/[\s_-]+/g, ' ');
+const slug = value => normalise(value).replace(/[^a-z0-9 ]/g, '').replace(/ +/g, '');
+
+function descriptor(file, record) {
+  const type = file.split('/')[0] || 'data';
+  const id = path.posix.basename(file, '.json');
+  const name = typeof record?.name === 'string' ? record.name :
+    typeof record?.title === 'string' ? record.title : id.replace(/[-_]/g, ' ');
+  return { id: String(record?.id || id), name, type, path: file };
+}
+function valuesFrom(record, limit = 10000) {
+  const values = [];
+  const stack = [record];
+  while (stack.length && values.length < limit) {
+    const value = stack.pop();
+    if (typeof value === 'string' || typeof value === 'number') values.push(String(value));
+    else if (Array.isArray(value)) stack.push(...value.slice(0,1000));
+    else if (value && typeof value === 'object') stack.push(...Object.values(value).slice(0,1000));
+  }
+  return values;
+}
+function createCatalog(data) {
+  if (!data || typeof data.list !== 'function' || typeof data.get !== 'function')
+    throw new TypeError('A JSON data store is required');
+
+  async function all(category) {
+    const files = await data.list();
+    const prefix = category ? category + '/' : '';
+    const matches = [];
+    for (const file of files) {
+      if (!file.endsWith('.json') || (category && !file.startsWith(prefix))) continue;
+      try {
+        const record = await data.get(file);
+        matches.push({ ...descriptor(file, record), record });
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        throw error;
+      }
+    }
+    return matches;
+  }
+
+  async function search(query, { category, limit = 50 } = {}) {
+    if (typeof query !== 'string' || !query.trim()) throw new TypeError('Search query is required');
+    if (category && !/^[a-z0-9_-]+$/.test(category)) throw new TypeError('Invalid category');
+    if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new RangeError('limit must be between 1 and 500');
+    const needle = normalise(query);
+    const results = [];
+    for (const item of await all(category)) {
+      const shortFields = [item.id, item.name, item.path, item.record?.title, ...(Array.isArray(item.record?.aliases) ? item.record.aliases : [])];
+      const direct = shortFields.some(v => v != null && normalise(v).includes(needle));
+      const content = !direct && valuesFrom(item.record).some(v => normalise(v).includes(needle));
+      if (!direct && !content) continue;
+      const score = normalise(item.name) === needle || normalise(item.id) === needle || slug(item.name) === slug(query) ? 0 :
+        direct ? 1 : 2;
+      results.push({ id:item.id, name:item.name, type:item.type, path:item.path, score });
+    }
+    results.sort((a,b) => a.score-b.score || a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+    const found = results.slice(0,limit).map(({score,...result})=>result);
+    return {
+      query,
+      total: results.length,
+      results: found,
+      message: results.length ? `Found ${results.length} result(s) for "${query}".` : `We don't have anything related to "${query}".`
+    };
+  }
+
+  async function get(category, idOrName) {
+    if (typeof category !== 'string' || !/^[a-z0-9_-]+$/.test(category))
+      throw new TypeError('Invalid category');
+    if (typeof idOrName !== 'string' || !idOrName.trim()) throw new TypeError('Record name or ID is required');
+    const needle = normalise(idOrName);
+    const matches = (await all(category)).filter(item =>
+      normalise(item.id) === needle || normalise(item.name) === needle ||
+      slug(item.id) === slug(idOrName) || slug(item.name) === slug(idOrName) ||
+      normalise(item.path) === needle);
+    if (!matches.length) {
+      const error = new Error(`We don't have anything related to "${idOrName}" in ${category}.`);
+      error.code = 'NOT_FOUND';
+      throw error;
+    }
+    if (matches.length > 1) {
+      const error = new Error(`Multiple ${category} records match "${idOrName}". Select an exact result path.`);
+      error.code = 'AMBIGUOUS';
+      error.results = matches.map(({record,...info})=>info);
+      throw error;
+    }
+    return matches[0].record;
+  }
+
+  return Object.freeze({
+    search,
+    get,
+    character: id => get('characters', id),
+    item: id => get('items', id),
+    code: id => get('codes', id),
+    map: id => get('maps', id)
+  });
+}
+module.exports = { createCatalog };

package/src/client-error.js

@@ -0,0 +1,9 @@
+'use strict';
+class TrackerError extends Error {
+  constructor(message,{status,cause}={}) {
+    super(message,{cause});
+    this.name='TrackerError';
+    if(status!==undefined)this.status=status;
+  }
+}
+module.exports={TrackerError};

package/src/data-source.js

@@ -0,0 +1,7 @@
+'use strict';
+const path=require('node:path');
+module.exports=Object.freeze({
+  gameId:'warframe',
+  bundledDir:path.join(__dirname,'..','data'),
+  github:{owner:'NekoSuneProjectsNPM',repo:'game-tracker',branch:'JsonData',directory:'games/warframe'}
+});

package/src/data-store.js

@@ -0,0 +1,138 @@
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+
+function safePath(value) {
+  if (typeof value !== 'string' || !value || value.includes('\\') || value.includes('\0') ||
+      value.startsWith('/') || value.split('/').some(v => !v || v === '.' || v === '..') ||
+      !/^[a-zA-Z0-9_./-]+$/.test(value)) throw new TypeError('Unsafe JSON data path');
+  if (!value.endsWith('.json')) throw new TypeError('Only .json files are supported');
+  return value;
+}
+function sourceConfig(source) {
+  if (!source) return null;
+  const { owner, repo, branch = 'main', directory } = source;
+  for (const part of [owner, repo, branch]) {
+    if (typeof part !== 'string' || !/^[a-zA-Z0-9._-]+$/.test(part)) throw new TypeError('Invalid GitHub repository source');
+  }
+  if (typeof directory !== 'string' || !directory || directory.split('/').some(x => !x || x === '.' || x === '..') ||
+      !/^[a-zA-Z0-9_/-]+$/.test(directory)) throw new TypeError('Invalid GitHub source directory');
+  return { owner, repo, branch, directory };
+}
+function createDataStore({ gameId, cacheDir, bundledDir, github, githubToken, syncFiles, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof gameId !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(gameId)) throw new TypeError('Valid gameId required');
+  if (typeof fetchImpl !== 'function') throw new TypeError('fetch is required');
+  const source = sourceConfig(github);
+  if (syncFiles !== undefined && (!Array.isArray(syncFiles) || syncFiles.length === 0)) throw new TypeError('syncFiles must be a nonempty array of JSON paths');
+  const whitelist = syncFiles === undefined ? null : new Set(syncFiles.map(safePath));
+  if (githubToken !== undefined && (typeof githubToken !== 'string' || !githubToken.trim())) throw new TypeError('githubToken must be a nonempty string');
+  const githubHeaders = { Accept: 'application/vnd.github+json', 'User-Agent': 'NekoSune-Game-Tracker', ...(githubToken ? { Authorization: 'Bearer ' + githubToken } : {}) };
+  const cache = path.resolve(cacheDir || path.join(os.homedir(), '.cache', 'nekosune-game-tracker', gameId));
+  const bundled = bundledDir ? path.resolve(bundledDir) : null;
+  const manifestFile = path.join(cache, '.manifest.json');
+  async function loadManifest() {
+    try {
+      const current = JSON.parse(await fs.readFile(manifestFile, 'utf8'));
+      if (current.source !== JSON.stringify({source, files: syncFiles || null}) || !current.files || typeof current.files !== 'object') return {};
+      return current.files;
+    } catch (err) { if (err.code === 'ENOENT' || err instanceof SyntaxError) return {}; throw err; }
+  }
+  async function atomicWrite(file, content) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = file + '.' + process.pid + '.' + require('node:crypto').randomBytes(6).toString('hex') + '.tmp';
+    try { await fs.writeFile(tmp, content); await fs.rename(tmp, file); }
+    catch (err) { await fs.rm(tmp, { force: true }); throw err; }
+  }
+  async function get(file) {
+    const relative = safePath(file);
+    for (const base of [cache, bundled].filter(Boolean)) {
+      try { return JSON.parse(await fs.readFile(path.join(base, relative), 'utf8')); }
+      catch (err) { if (err.code !== 'ENOENT') throw err; }
+    }
+    throw Object.assign(new Error('Local JSON not found: ' + relative), { code: 'ENOENT' });
+  }
+  async function list() {
+    const results = new Set();
+    async function walk(dir, relative = '') {
+      let entries;
+      try { entries = await fs.readdir(dir, { withFileTypes: true }); }
+      catch (err) { if (err.code === 'ENOENT') return; throw err; }
+      for (const entry of entries) {
+        if (entry.isSymbolicLink()) continue;
+        const rel = relative ? relative + '/' + entry.name : entry.name;
+        if (entry.isDirectory()) await walk(path.join(dir, entry.name), rel);
+        else if (entry.isFile() && rel.endsWith('.json') && rel !== '.manifest.json') {
+          try { safePath(rel); results.add(rel); } catch {}
+        }
+      }
+    }
+    if (bundled) await walk(bundled);
+    await walk(cache);
+    return [...results].sort();
+  }
+  async function sync({ signal } = {}) {
+    if (!source) throw new Error('No GitHub JSON source configured in this tracker branch');
+    const { owner, repo, branch, directory } = source;
+    const api = 'https://api.github.com/repos/' + owner + '/' + repo + '/git/trees/' + encodeURIComponent(branch) + '?recursive=1';
+    const request = await fetchImpl(api, { headers: githubHeaders, signal });
+    if (!request.ok) throw new Error('GitHub tree request failed: HTTP ' + request.status);
+    const tree = await request.json();
+    if (tree.truncated || !Array.isArray(tree.tree)) throw new Error('GitHub directory listing incomplete; refusing partial sync');
+    const prefix = directory + '/';
+    const files = tree.tree.filter(item => item.type === 'blob' && item.path.startsWith(prefix) && item.path.endsWith('.json') && (!whitelist || whitelist.has(item.path.slice(prefix.length))))
+      .map(item => ({ name: safePath(item.path.slice(prefix.length)), sha: item.sha, size: item.size }));
+    if (files.length > 5000) throw new Error('Too many JSON files');
+    const old = await loadManifest();
+    const next = { ...old };
+    let updated = 0, unchanged = 0;
+    for (const item of files) {
+      if (!/^[0-9a-f]{40}$/.test(item.sha) || item.size > 5 * 1024 * 1024) throw new Error('Invalid or oversized GitHub JSON blob');
+      const target = path.join(cache, item.name);
+      if (old[item.name] === item.sha) {
+        try {
+          const existing = await fs.readFile(target);
+          const existingHash = require('node:crypto').createHash('sha1')
+            .update('blob ' + existing.length + '\0').update(existing).digest('hex');
+          JSON.parse(existing.toString('utf8'));
+          if (existingHash === item.sha) { unchanged++; continue; }
+        } catch (err) {
+          if (err.code !== 'ENOENT' && !(err instanceof SyntaxError)) throw err;
+        }
+      }
+      // GitHub Git Blob API supports private repositories with a fine-grained read token.
+      // Fetch by content SHA so the downloaded file matches the exact tree snapshot.
+      const blobUrl = 'https://api.github.com/repos/' + owner + '/' + repo + '/git/blobs/' + item.sha;
+      const response = await fetchImpl(blobUrl, { headers: githubHeaders, signal });
+      if (!response.ok) throw new Error('GitHub JSON download failed (' + item.name + '): HTTP ' + response.status);
+      const blob = await response.json();
+      if (blob.encoding !== 'base64' || typeof blob.content !== 'string')
+        throw new Error('Unexpected GitHub blob encoding for ' + item.name);
+      const buffer = Buffer.from(blob.content.replace(/\s/g, ''), 'base64');
+      if (buffer.length > 5 * 1024 * 1024) throw new Error('JSON file too large');
+      const gitHash = require('node:crypto').createHash('sha1').update('blob ' + buffer.length + '\0').update(buffer).digest('hex');
+      if (gitHash !== item.sha) throw new Error('GitHub JSON checksum mismatch: ' + item.name);
+      JSON.parse(buffer.toString('utf8'));
+      await atomicWrite(target, buffer);
+      next[item.name] = item.sha;
+      updated++;
+    }
+    // Cache is additive: do not automatically delete removed upstream files or user files.
+    await atomicWrite(manifestFile, JSON.stringify({ source: JSON.stringify({source, files: syncFiles || null}), files: next }, null, 2) + '\n');
+    return { updated, unchanged, checked: files.length, cacheDir: cache };
+  }
+  // Ensures a newly published remote JSON record is available even when it
+  // was absent from the npm package and from this machine's cache.
+  async function ensure(file, { signal, refresh = false } = {}) {
+    const relative = safePath(file);
+    if (!refresh) {
+      try { return await get(relative); }
+      catch (err) { if (err.code !== 'ENOENT') throw err; }
+    }
+    if (!source) return get(relative);
+    await sync({ signal });
+    return get(relative);
+  }
+  return Object.freeze({ get, list, sync, ensure, cacheDir: cache });
+}
+module.exports = { createDataStore };

package/src/provider.js

@@ -0,0 +1,22 @@
+'use strict';
+const BASE = 'https://api.warframestat.us/';
+const PLATFORMS = Object.freeze(['pc','ps4','psn','xb1','swi','ns']);
+const WORLDSTATE_FIELDS = Object.freeze([
+  'alerts','arbitration','archonHunt','cambionCycle','cetusCycle','conclaveChallenges',
+  'constructionProgress','dailyDeals','darvo','earthCycle','events','fissures',
+  'flashSales','globalUpgrades','invasions','kuva','news','nightwave','persistentEnemies',
+  'sentientOutposts','simaris','sortie','steelPath','syndicateMissions','thermia',
+  'vallisCycle','voidTrader','weeklyChallenges'
+]);
+const STATIC_KEYS = Object.freeze([
+  'arcanes','synthTargets','solNodes','conclave','events','operationTypes',
+  'persistentEnemy','sortie','upgradeTypes','fissureModifiers','archonShards',
+  'factions','missionTypes','languages','locales','mods','weapons','warframes','items'
+]);
+module.exports = Object.freeze({
+  baseUrl: BASE,
+  auth: Object.freeze({type:'none'}),
+  platforms: PLATFORMS,
+  worldstateFields: WORLDSTATE_FIELDS,
+  staticKeys: STATIC_KEYS
+});

package/src/tracker.js

@@ -0,0 +1,115 @@
+'use strict';
+const provider=require('./provider');
+const {createWarframeClient,parameter,optionsQuery}=require('./warframe-client');
+const {createDataStore}=require('./data-store');
+const {createCatalog}=require('./catalog');
+const {createWarframeCodes}=require('./warframe-codes');
+const {createWFCD,createMarketQuery,createUpdateMonitor}=require('./wfcd');
+const {TrackerError}=require('./client-error');
+
+const itemTypes=new Set(['warframes','weapons','items','mods']);
+const id=v=>parameter(v,'identifier');
+function platformOf(value) {
+  const p=value||'pc';
+  if(!provider.platforms.includes(p))throw new RangeError('Unsupported platform '+p);
+  return p;
+}
+function createWarframeTracker({platform='pc',language='en',timeoutMs=15000,cacheDir,githubToken,fetchImpl}={}) {
+  const selected=platformOf(platform);
+  const {request}=createWarframeClient({language,timeoutMs,fetchImpl});
+  const data=createDataStore({
+    gameId:'warframe', github:{owner:'NekoSuneProjectsNPM',repo:'game-tracker',branch:'JsonData',directory:'games/warframe'},
+    bundledDir:require('node:path').join(__dirname,'..','data'),
+    cacheDir, githubToken, fetchImpl
+  });
+  const catalog=createCatalog(data);
+  // Local-first: only query GitHub if a requested character is absent.
+  // Existing bundled and cached characters work without any network call.
+  async function character(name, options = {}) {
+    try { return await catalog.character(name); }
+    catch (err) {
+      if (err.code !== 'NOT_FOUND') throw err;
+      if (options.refresh === false) throw err;
+      await data.sync({ signal: options.signal });
+      return catalog.character(name);
+    }
+  }
+  // Set refresh:true to discover new records that didn't exist in local JSON.
+  async function search(query, options = {}) {
+    if (options.refresh === true) await data.sync({ signal: options.signal });
+    return catalog.search(query, options);
+  }
+  const codes=createWarframeCodes({cacheDir,githubToken,fetchImpl});
+  const wfcd=createWFCD({cacheDir,githubToken,fetchImpl});
+  const worldstate=(field,options={})=>{
+    if(typeof field!=='string' || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(field)) throw new TypeError('Invalid worldstate field');
+    return request(selected+'/'+field,optionsQuery(options,['filter']));
+  };
+  const listing=(kind,options={})=>{
+    if(!itemTypes.has(kind))throw new RangeError('Unknown item type');
+    return request(kind,optionsQuery(options,['language','filter','only','remove']));
+  };
+  const single=(kind,name,options={})=>{
+    if(!itemTypes.has(kind))throw new RangeError('Unknown item type');
+    return request(kind+'/'+id(name),optionsQuery(options,['language','filter','only','remove','by']));
+  };
+  const find=(kind,query,options={})=>{
+    if(!itemTypes.has(kind))throw new RangeError('Unknown item type');
+    return request(kind+'/search/'+id(query),optionsQuery(options,['language','filter','only','remove','by']));
+  };
+  const api=Object.freeze({
+    health:()=>request('health'),
+    worldstate:()=>request(selected),
+    worldstateField:(field,options)=>worldstate(field,options),
+    profile:(playerId,options)=>request('profile/'+id(playerId),optionsQuery(options,['language','withItem'])),
+    profileStats:playerId=>request('profile/'+id(playerId)+'/stats'),
+    profileXP:(playerId,options)=>request('profile/'+id(playerId)+'/xpInfo',optionsQuery(options,['withItem'])),
+    list:listing,
+    get:single,
+    search:find,
+    warframes:options=>listing('warframes',options),
+    weapons:options=>listing('weapons',options),
+    items:options=>listing('items',options),
+    mods:options=>listing('mods',options),
+    warframe:(name,options)=>single('warframes',name,options),
+    weapon:(name,options)=>single('weapons',name,options),
+    item:(name,options)=>single('items',name,options),
+    mod:(name,options)=>single('mods',name,options),
+    searchWarframes:(q,options)=>find('warframes',q,options),
+    searchWeapons:(q,options)=>find('weapons',q,options),
+    searchItems:(q,options)=>find('items',q,options),
+    searchMods:(q,options)=>find('mods',q,options),
+    drops:()=>request('drops'),
+    searchDrops:(query,options)=>request('drops/search/'+id(query),optionsQuery(options,['grouped_by'])),
+    rivens:()=>request(selected+'/rivens'),
+    searchRivens:query=>request(selected+'/rivens/search/'+id(query)),
+    staticData:(key,options)=>request(id(key),optionsQuery(options,['language'])),
+    searchStatic:(key,query,options)=>request(id(key)+'/search/'+id(query),optionsQuery(options,['language'])),
+    synthTargets:options=>request('synthTargets',optionsQuery(options,['language'])),
+    arcanes:options=>request('arcanes',optionsQuery(options,['language'])),
+    rss:()=>request('rss'),
+    twitter:()=>request('twitter'),
+    wfinfoFilteredItems:()=>request('wfinfo/filtered_items'),
+    wfinfoPrices:()=>request('wfinfo/prices')
+  });
+  const fields=Object.fromEntries(provider.worldstateFields.filter(k=>!Object.hasOwn(api,k)).map(k=>[k,options=>worldstate(k,options)]));
+  const fullApi=Object.freeze({...api,...fields});
+  return Object.freeze({
+    api:fullApi,
+    data,
+    codes,
+    wfcd,
+    market:createMarketQuery,
+    createUpdateMonitor,
+    code:codes.get,
+    About:()=>data.get('meta.json'),
+    search,
+    character,
+    record:catalog.get,
+    item:catalog.item,
+    map:catalog.map,
+    // live player endpoints remain under api.* to distinguish local records
+    getPlayerStats:fullApi.profileStats
+  });
+}
+module.exports={createTracker:createWarframeTracker,TrackerError};

package/src/warframe-client.js

@@ -0,0 +1,57 @@
+'use strict';
+const { TrackerError } = require('./client-error');
+const provider = require('./provider');
+
+function parameter(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(name + ' must be nonempty text');
+  return encodeURIComponent(value.trim());
+}
+function optionsQuery(options, allowed) {
+  if (options === undefined || options === null) return undefined;
+  if (typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Options must be an object');
+  const params = {};
+  for (const [key,value] of Object.entries(options)) {
+    if (!allowed.includes(key)) throw new TypeError('Unsupported query option: ' + key);
+    if (value !== undefined && value !== null) {
+      if (!['string','number','boolean'].includes(typeof value)) throw new TypeError('Invalid query option: ' + key);
+      params[key]=String(value);
+    }
+  }
+  return params;
+}
+function createWarframeClient({ timeoutMs = 15000, fetchImpl = globalThis.fetch, language = 'en' } = {}) {
+  if (typeof fetchImpl !== 'function') throw new TypeError('Node.js 18+ fetch is required');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1) throw new TypeError('timeoutMs must be a positive integer');
+  if (typeof language !== 'string' || !/^[a-z]{2}$/.test(language)) throw new TypeError('language must be a 2-letter code');
+  async function request(route, query, { signal } = {}) {
+    if (typeof route !== 'string' || !/^[a-zA-Z0-9_/%.-]+$/.test(route) || route.startsWith('/'))
+      throw new TypeError('Invalid internal API route');
+    const url = new URL(route, provider.baseUrl);
+    if (url.origin !== new URL(provider.baseUrl).origin) throw new TypeError('API origin mismatch');
+    for (const [k,v] of Object.entries(query || {})) url.searchParams.set(k,String(v));
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(),timeoutMs);
+    const onAbort = () => controller.abort();
+    if (signal) {
+      if (signal.aborted) controller.abort();
+      else signal.addEventListener('abort',onAbort,{once:true});
+    }
+    try {
+      const response = await fetchImpl(url,{
+        headers:{Accept:'application/json','Accept-Language':language,'User-Agent':'nekosuneprojects-warframe-api'},
+        signal:controller.signal
+      });
+      if (!response.ok) throw new TrackerError('WarframeStat.us HTTP '+response.status,{status:response.status});
+      if (response.status===204) return null;
+      return await response.json();
+    } catch (cause) {
+      if (cause instanceof TrackerError) throw cause;
+      throw new TrackerError('WarframeStat.us request failed',{cause});
+    } finally {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort',onAbort);
+    }
+  }
+  return Object.freeze({request,parameter,optionsQuery});
+}
+module.exports={createWarframeClient,parameter,optionsQuery};

package/src/warframe-codes.js

@@ -0,0 +1,82 @@
+'use strict';
+const path = require('node:path');
+const { createDataStore } = require('./data-store');
+
+const FILE = 'warframe.json';
+const GROUPS = Object.freeze({ active:'Active', expired:'Expired', unknown:'Unknown' });
+const normalise = text => String(text ?? '').normalize('NFKC').trim().toLowerCase();
+function validate(source) {
+  if (!source || typeof source !== 'object' || Array.isArray(source) ||
+      !Object.values(GROUPS).every(group => Array.isArray(source[group]))) {
+    throw new TypeError('Invalid Warframe codes JSON: Active, Expired and Unknown arrays are required');
+  }
+  return source;
+}
+function createWarframeCodes({cacheDir,githubToken,fetchImpl}={}) {
+  const storage = createDataStore({
+    gameId:'warframe-codes',
+    cacheDir:cacheDir ? path.join(path.resolve(cacheDir),'codes') : undefined,
+    bundledDir:path.join(__dirname,'..','data','codes'),
+    github:{owner:'NekoSuneProjectsNPM',repo:'game-tracker',branch:'JsonData',directory:'codes/games'},
+    syncFiles:[FILE],
+    githubToken,fetchImpl
+  });
+  async function raw() { return validate(await storage.get(FILE)); }
+  async function list({status,category,claimType,hasCode,limit}={}) {
+    if (status !== undefined && !Object.hasOwn(GROUPS,status)) throw new RangeError('status must be active, expired, or unknown');
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) throw new RangeError('limit must be a positive integer');
+    const doc=await raw();
+    const keys=status ? [GROUPS[status]] : Object.values(GROUPS);
+    let entries=keys.flatMap(key=>doc[key]);
+    if (category !== undefined) entries=entries.filter(item=>normalise(item.category)===normalise(category));
+    if (claimType !== undefined) entries=entries.filter(item=>normalise(item.claimType)===normalise(claimType));
+    if (hasCode !== undefined) {
+      if (typeof hasCode !== 'boolean') throw new TypeError('hasCode must be boolean');
+      entries=entries.filter(item=>Boolean(typeof item.code==='string'&&item.code.trim())===hasCode);
+    }
+    return limit ? entries.slice(0,limit) : entries;
+  }
+  async function search(query,options={}) {
+    if(typeof query!=='string'||!query.trim()) throw new TypeError('Search query is required');
+    const needle=normalise(query);
+    const entries=await list(options);
+    const results=entries.filter(record=>{
+      const fields=[record.code,record.id,record.category,record.claimType,record.notes,record.redeemLocation,
+        ...(Array.isArray(record.items)?record.items.map(item=>item?.name):[])];
+      return fields.some(value=>normalise(value).includes(needle));
+    });
+    return {query,total:results.length,results,message:results.length?
+      'Found '+results.length+' Warframe code-related entries for "'+query+'".':
+      'We don\'t have anything related to "'+query+'" in Warframe codes.'};
+  }
+  async function get(key) {
+    if((typeof key!=='string' && typeof key!=='number') || !String(key).trim()) throw new TypeError('Code or ID is required');
+    const needle=normalise(key);
+    const results=(await list()).filter(item=>normalise(item.id)===needle || (item.code && normalise(item.code)===needle));
+    if(results.length===0) {
+      const err=new Error('No Warframe code entry found: '+key); err.code='NOT_FOUND';throw err;
+    }
+    if(results.length>1) {
+      const err=new Error('Multiple Warframe code entries match: '+key);err.code='AMBIGUOUS';err.results=results;throw err;
+    }
+    return results[0];
+  }
+  async function summary() {
+    const doc=await raw(); const groups={};let total=0;let redeemable=0;
+    for(const [status,key] of Object.entries(GROUPS)) {
+      const entries=doc[key];
+      const withCode=entries.filter(item=>typeof item.code==='string' && item.code.trim()).length;
+      groups[status]={total:entries.length,withCode,withoutCode:entries.length-withCode};
+      total+=entries.length;redeemable+=withCode;
+    }
+    return {total,withCode:redeemable,withoutCode:total-redeemable,groups};
+  }
+  return Object.freeze({
+    raw,list,active:options=>list({...options,status:'active'}),
+    expired:options=>list({...options,status:'expired'}),
+    unknown:options=>list({...options,status:'unknown'}),
+    search,get,summary,sync:options=>storage.sync(options),
+    cacheDir:storage.cacheDir
+  });
+}
+module.exports={createWarframeCodes};