lumisjs 1.0.0

package/src/errors/LumisError.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { ErrorCodes, ErrorMessages } = require('./ErrorCodes');
+
+class LumisError extends Error {
+  
+  constructor(code, ...args) {
+    const message = LumisError._getMessage(code, args);
+    super(message);
+
+    this.name = 'LumisError';
+    this.code = code;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  static _getMessage(code, args) {
+    const msg = ErrorMessages[code];
+    if (!msg) return `Unknown error: ${code}`;
+    if (typeof msg === 'function') return msg(...args);
+    return msg;
+  }
+}
+
+class APIError extends LumisError {
+  
+  constructor(path, error, method, status) {
+    super(ErrorCodes.API_ERROR, status, error.message || 'Unknown');
+
+    this.name = 'APIError';
+    this.method = method;
+    this.path = path;
+    this.httpStatus = status;
+    this.requestBody = null;
+
+    this.discordCode = error.code || 0;
+
+    this.discordMessage = error.message || 'Unknown';
+
+    this.errors = error.errors || {};
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      discordCode: this.discordCode,
+      message: this.discordMessage,
+      method: this.method,
+      path: this.path,
+      httpStatus: this.httpStatus,
+      errors: this.errors,
+    };
+  }
+}
+
+class WebSocketError extends LumisError {
+  
+  constructor(code, closeCode, ...args) {
+    super(code, ...args);
+    this.name = 'WebSocketError';
+    this.closeCode = closeCode || null;
+  }
+}
+
+class RateLimitError extends LumisError {
+  
+  constructor(path, retryAfter, global = false) {
+    super(ErrorCodes.RATE_LIMITED, retryAfter);
+
+    this.name = 'RateLimitError';
+    this.path = path;
+    this.retryAfter = retryAfter;
+    this.global = global;
+  }
+}
+
+module.exports = {
+  LumisError,
+  APIError,
+  WebSocketError,
+  RateLimitError,
+};

package/src/game/EconomyManager.js

@@ -0,0 +1,161 @@
+'use strict';
+
+class EconomyManager {
+  /**
+   * @param {import('../client/Client')} client
+   * @param {object} [options]
+   * @param {string} [options.currencyName='Coins']
+   * @param {string} [options.currencySymbol='💰']
+   * @param {number} [options.defaultBalance=0]
+   * @param {number} [options.maxBalance=Infinity]
+   */
+  constructor(client, options = {}) {
+    this.client = client;
+    this.currencyName = options.currencyName || 'Coins';
+    this.currencySymbol = options.currencySymbol || '💰';
+    this.defaultBalance = options.defaultBalance ?? 0;
+    this.maxBalance = options.maxBalance ?? Infinity;
+  }
+
+  _key(userId) {
+    return `eco_balance_${userId}`;
+  }
+
+  /**
+   * Get a user's balance.
+   * @param {string} userId
+   * @returns {Promise<number>}
+   */
+  async getBalance(userId) {
+    if (!userId) throw new TypeError('userId is required');
+    const val = await this.client.cache.get(this._key(userId));
+    if (val === null || val === undefined) return this.defaultBalance;
+    return Number(val);
+  }
+
+  /**
+   * Add to a user's balance.
+   * @param {string} userId
+   * @param {number} amount
+   * @returns {Promise<number>} New balance
+   */
+  async addBalance(userId, amount) {
+    if (!userId) throw new TypeError('userId is required');
+    if (typeof amount !== 'number' || isNaN(amount) || amount <= 0) {
+      throw new RangeError('amount must be a positive number');
+    }
+
+    const current = await this.getBalance(userId);
+    const newBalance = Math.min(current + amount, this.maxBalance);
+    await this.client.cache.set(this._key(userId), newBalance);
+    return newBalance;
+  }
+
+  /**
+   * Remove from a user's balance.
+   * @param {string} userId
+   * @param {number} amount
+   * @returns {Promise<number|false>} New balance, or false if insufficient funds
+   */
+  async removeBalance(userId, amount) {
+    if (!userId) throw new TypeError('userId is required');
+    if (typeof amount !== 'number' || isNaN(amount) || amount <= 0) {
+      throw new RangeError('amount must be a positive number');
+    }
+
+    const current = await this.getBalance(userId);
+    if (current < amount) return false;
+
+    const newBalance = current - amount;
+    await this.client.cache.set(this._key(userId), newBalance);
+    return newBalance;
+  }
+
+  /**
+   * Set a user's balance directly.
+   * @param {string} userId
+   * @param {number} amount
+   * @returns {Promise<number>}
+   */
+  async setBalance(userId, amount) {
+    if (!userId) throw new TypeError('userId is required');
+    if (typeof amount !== 'number' || isNaN(amount) || amount < 0) {
+      throw new RangeError('amount must be a non-negative number');
+    }
+
+    const clamped = Math.min(amount, this.maxBalance);
+    await this.client.cache.set(this._key(userId), clamped);
+    return clamped;
+  }
+
+  /**
+   * Transfer balance from one user to another.
+   * @param {string} fromUserId
+   * @param {string} toUserId
+   * @param {number} amount
+   * @returns {Promise<{ from: number, to: number }|false>}
+   */
+  async transfer(fromUserId, toUserId, amount) {
+    if (!fromUserId || !toUserId) throw new TypeError('Both user IDs are required');
+    if (fromUserId === toUserId) throw new Error('Cannot transfer to the same user');
+    if (typeof amount !== 'number' || isNaN(amount) || amount <= 0) {
+      throw new RangeError('amount must be a positive number');
+    }
+
+    const fromBalance = await this.getBalance(fromUserId);
+    if (fromBalance < amount) return false;
+
+    // Sequential to avoid race where both reads happen before writes
+    const newFrom = await this.removeBalance(fromUserId, amount);
+    const newTo = await this.addBalance(toUserId, amount);
+
+    return { from: newFrom, to: newTo };
+  }
+
+  /**
+   * Get a leaderboard sorted by balance.
+   * Works across all cache adapters via the keys() API.
+   * @param {number} [limit=10]
+   * @returns {Promise<Array<{ userId: string, balance: number }>>}
+   */
+  async getLeaderboard(limit = 10) {
+    if (typeof limit !== 'number' || limit < 1) {
+      throw new RangeError('limit must be a positive number');
+    }
+
+    const prefix = 'eco_balance_';
+    const users = [];
+
+    try {
+      const allKeys = await this.client.cache.keys();
+      const ecoKeys = allKeys.filter((k) => k.startsWith(prefix));
+
+      for (const key of ecoKeys) {
+        const val = await this.client.cache.get(key);
+        if (val !== undefined && val !== null) {
+          users.push({
+            userId: key.slice(prefix.length),
+            balance: Number(val),
+          });
+        }
+      }
+    } catch (err) {
+      this.client.logger?.warn(`EconomyManager.getLeaderboard failed: ${err.message}`);
+    }
+
+    return users.sort((a, b) => b.balance - a.balance).slice(0, limit);
+  }
+
+  /**
+   * Reset a user's balance to the default.
+   * @param {string} userId
+   * @returns {Promise<number>}
+   */
+  async resetBalance(userId) {
+    if (!userId) throw new TypeError('userId is required');
+    await this.client.cache.set(this._key(userId), this.defaultBalance);
+    return this.defaultBalance;
+  }
+}
+
+module.exports = EconomyManager;

package/src/game/GameSessionManager.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const Collection = require('../utils/Collection');
+const { EventEmitter } = require('node:events');
+
+class GameSessionManager extends EventEmitter {
+  constructor() {
+    super();
+
+    this.sessions = new Collection();
+  }
+
+  startSession(sessionId, initialData = {}, timeoutMs = 300000) {
+    if (this.sessions.has(sessionId)) {
+      this.endSession(sessionId, 'force_restart');
+    }
+
+    const session = {
+      id: sessionId,
+      data: initialData,
+      startTime: Date.now(),
+      lastActivityTime: Date.now(),
+      timeoutMs,
+      _timer: null
+    };
+
+    this.sessions.set(sessionId, session);
+    this._resetTimer(session);
+
+    this.emit('sessionStart', session);
+    return session;
+  }
+
+  getSession(sessionId) {
+    return this.sessions.get(sessionId) || null;
+  }
+
+  updateSession(sessionId, newData) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+
+    Object.assign(session.data, newData);
+    session.lastActivityTime = Date.now();
+    
+    this._resetTimer(session);
+    this.emit('sessionUpdate', session);
+    return session;
+  }
+
+  endSession(sessionId, reason = 'finished') {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    if (session._timer) {
+      clearTimeout(session._timer);
+    }
+
+    this.sessions.delete(sessionId);
+    this.emit('sessionEnd', session, reason);
+    return true;
+  }
+
+  _resetTimer(session) {
+    if (session._timer) {
+      clearTimeout(session._timer);
+    }
+
+    if (session.timeoutMs > 0) {
+      session._timer = setTimeout(() => {
+        this.endSession(session.id, 'timeout');
+      }, session.timeoutMs).unref();
+    }
+  }
+}
+
+module.exports = GameSessionManager;

package/src/game/GuildManager.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const { LumisError } = require('../errors/LumisError');
+const { ErrorCodes } = require('../errors/ErrorCodes');
+
+class GuildManager {
+  /**
+   * @param {import('../client/Client')} client
+   */
+  constructor(client) {
+    this.client = client;
+  }
+
+  _nameHistoryKey(userId, guildId) {
+    return `name_history_${guildId}_${userId}`;
+  }
+
+  /**
+   * Parse JSON from cache safely.
+   * @private
+   */
+  _parse(raw, fallback) {
+    if (!raw) return fallback;
+    if (typeof raw === 'object') return raw;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return fallback;
+    }
+  }
+
+  /**
+   * Register a user in a guild (set nickname + manage roles).
+   * @param {object} member
+   * @param {string} name
+   * @param {string|number} age
+   * @param {object} [options]
+   * @param {string} [options.nameFormat='{name} | {age}']
+   * @param {string[]} [options.rolesToAdd]
+   * @param {string[]} [options.rolesToRemove]
+   * @returns {Promise<boolean>}
+   */
+  async registerUser(member, name, age, options = {}) {
+    if (!member?.id || !member?.guildId) {
+      throw new LumisError(ErrorCodes.INVALID_STRUCTURE, 'member');
+    }
+    if (!name || typeof name !== 'string') {
+      throw new TypeError('name must be a non-empty string');
+    }
+
+    const nameFormat = options.nameFormat || '{name} | {age}';
+    const formattedName = nameFormat
+      .replace('{name}', name.trim())
+      .replace('{age}', String(age).trim());
+
+    // Truncate to Discord's 32-char nickname limit
+    const nick = formattedName.slice(0, 32);
+
+    try {
+      await this.client.rest.patch(`/guilds/${member.guildId}/members/${member.id}`, {
+        body: { nick },
+      });
+
+      if (Array.isArray(options.rolesToAdd)) {
+        await Promise.all(
+          options.rolesToAdd.map((roleId) =>
+            this.client.rest.put(
+              `/guilds/${member.guildId}/members/${member.id}/roles/${roleId}`
+            )
+          )
+        );
+      }
+
+      if (Array.isArray(options.rolesToRemove)) {
+        await Promise.all(
+          options.rolesToRemove.map((roleId) =>
+            this.client.rest.delete(
+              `/guilds/${member.guildId}/members/${member.id}/roles/${roleId}`
+            )
+          )
+        );
+      }
+
+      await this.addNameHistory(member.id, member.guildId, nick, 'Register');
+      return true;
+    } catch (error) {
+      this.client.logger?.error(`Registration failed (User: ${member.id}):`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Record a name change in history.
+   * @param {string} userId
+   * @param {string} guildId
+   * @param {string} name
+   * @param {string} [reason='Name Change']
+   */
+  async addNameHistory(userId, guildId, name, reason = 'Name Change') {
+    const key = this._nameHistoryKey(userId, guildId);
+    const raw = await this.client.cache.get(key);
+    const arr = this._parse(raw, []);
+
+    arr.push({ name, reason, date: Date.now() });
+
+    // Keep last 50 entries to prevent unbounded growth
+    if (arr.length > 50) arr.splice(0, arr.length - 50);
+
+    await this.client.cache.set(key, JSON.stringify(arr));
+  }
+
+  /**
+   * Get a user's name history (newest first).
+   * @param {string} userId
+   * @param {string} guildId
+   * @returns {Promise<Array<{ name: string, reason: string, date: number }>>}
+   */
+  async getNameHistory(userId, guildId) {
+    const key = this._nameHistoryKey(userId, guildId);
+    const raw = await this.client.cache.get(key);
+    const arr = this._parse(raw, []);
+    return arr.sort((a, b) => b.date - a.date);
+  }
+
+  /**
+   * Jail a user by replacing all their roles with a jail role.
+   * Saves their current roles for restoration.
+   * @param {object} member
+   * @param {string} jailRoleId
+   * @returns {Promise<boolean>}
+   */
+  async jailUser(member, jailRoleId) {
+    if (!member?.id || !member?.guildId) return false;
+    if (!jailRoleId) throw new TypeError('jailRoleId is required');
+
+    const currentRoles = Array.isArray(member.roles) ? member.roles : [];
+    const cacheKey = `jail_roles_${member.guildId}_${member.id}`;
+
+    await this.client.cache.set(cacheKey, JSON.stringify(currentRoles));
+
+    try {
+      await this.client.rest.patch(`/guilds/${member.guildId}/members/${member.id}`, {
+        body: { roles: [jailRoleId] },
+      });
+      return true;
+    } catch (error) {
+      this.client.logger?.error('Jail failed:', error);
+      // Rollback cache write if API call failed
+      await this.client.cache.delete(cacheKey);
+      return false;
+    }
+  }
+
+  /**
+   * Unjail a user by restoring their saved roles.
+   * @param {object} member
+   * @returns {Promise<boolean>}
+   */
+  async unjailUser(member) {
+    if (!member?.id || !member?.guildId) return false;
+
+    const cacheKey = `jail_roles_${member.guildId}_${member.id}`;
+    const raw = await this.client.cache.get(cacheKey);
+
+    if (!raw) {
+      this.client.logger?.warn(`Unjail: No saved roles found for user ${member.id}.`);
+      return false;
+    }
+
+    const rolesToRestore = this._parse(raw, []);
+
+    try {
+      await this.client.rest.patch(`/guilds/${member.guildId}/members/${member.id}`, {
+        body: { roles: rolesToRestore },
+      });
+      await this.client.cache.delete(cacheKey);
+      return true;
+    } catch (error) {
+      this.client.logger?.error('Unjail failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Check if a user is currently jailed.
+   * @param {string} userId
+   * @param {string} guildId
+   * @returns {Promise<boolean>}
+   */
+  async isJailed(userId, guildId) {
+    const cacheKey = `jail_roles_${guildId}_${userId}`;
+    const raw = await this.client.cache.get(cacheKey);
+    return raw !== undefined && raw !== null;
+  }
+}
+
+module.exports = GuildManager;

package/src/game/InventoryManager.js

@@ -0,0 +1,140 @@
+'use strict';
+
+class InventoryManager {
+  /**
+   * @param {import('../client/Client')} client
+   */
+  constructor(client) {
+    this.client = client;
+  }
+
+  _key(userId) {
+    return `inv_items_${userId}`;
+  }
+
+  /**
+   * Parse the stored inventory safely.
+   * @private
+   */
+  _parse(raw) {
+    if (!raw) return {};
+    if (typeof raw === 'object') return raw;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Get a user's full inventory.
+   * @param {string} userId
+   * @returns {Promise<Record<string, number>>}
+   */
+  async getInventory(userId) {
+    if (!userId) throw new TypeError('userId is required');
+    const val = await this.client.cache.get(this._key(userId));
+    return this._parse(val);
+  }
+
+  /**
+   * Add an item to a user's inventory.
+   * @param {string} userId
+   * @param {string} itemName
+   * @param {number} [amount=1]
+   * @returns {Promise<Record<string, number>>} Updated inventory
+   */
+  async addItem(userId, itemName, amount = 1) {
+    if (!userId) throw new TypeError('userId is required');
+    if (!itemName || typeof itemName !== 'string') throw new TypeError('itemName must be a non-empty string');
+    if (typeof amount !== 'number' || amount <= 0 || !Number.isInteger(amount)) {
+      throw new RangeError('amount must be a positive integer');
+    }
+
+    const inv = await this.getInventory(userId);
+    inv[itemName] = (inv[itemName] ?? 0) + amount;
+
+    await this.client.cache.set(this._key(userId), JSON.stringify(inv));
+    return inv;
+  }
+
+  /**
+   * Remove an item from a user's inventory.
+   * @param {string} userId
+   * @param {string} itemName
+   * @param {number} [amount=1]
+   * @returns {Promise<Record<string, number>|false>} Updated inventory or false if not enough
+   */
+  async removeItem(userId, itemName, amount = 1) {
+    if (!userId) throw new TypeError('userId is required');
+    if (!itemName || typeof itemName !== 'string') throw new TypeError('itemName must be a non-empty string');
+    if (typeof amount !== 'number' || amount <= 0 || !Number.isInteger(amount)) {
+      throw new RangeError('amount must be a positive integer');
+    }
+
+    const inv = await this.getInventory(userId);
+    const current = inv[itemName] ?? 0;
+
+    if (current < amount) return false;
+
+    inv[itemName] = current - amount;
+    if (inv[itemName] <= 0) {
+      delete inv[itemName];
+    }
+
+    await this.client.cache.set(this._key(userId), JSON.stringify(inv));
+    return inv;
+  }
+
+  /**
+   * Check how many of an item a user has.
+   * @param {string} userId
+   * @param {string} itemName
+   * @returns {Promise<number>}
+   */
+  async hasItem(userId, itemName) {
+    if (!userId) throw new TypeError('userId is required');
+    const inv = await this.getInventory(userId);
+    return inv[itemName] ?? 0;
+  }
+
+  /**
+   * Transfer an item from one user to another.
+   * @param {string} fromUserId
+   * @param {string} toUserId
+   * @param {string} itemName
+   * @param {number} [amount=1]
+   * @returns {Promise<boolean>}
+   */
+  async transferItem(fromUserId, toUserId, itemName, amount = 1) {
+    if (!fromUserId || !toUserId) throw new TypeError('Both user IDs are required');
+    if (fromUserId === toUserId) throw new Error('Cannot transfer item to the same user');
+
+    const removed = await this.removeItem(fromUserId, itemName, amount);
+    if (removed === false) return false;
+
+    await this.addItem(toUserId, itemName, amount);
+    return true;
+  }
+
+  /**
+   * Get all items in a user's inventory as an array.
+   * @param {string} userId
+   * @returns {Promise<Array<{ name: string, amount: number }>>}
+   */
+  async getItemList(userId) {
+    const inv = await this.getInventory(userId);
+    return Object.entries(inv).map(([name, amount]) => ({ name, amount }));
+  }
+
+  /**
+   * Clear a user's entire inventory.
+   * @param {string} userId
+   */
+  async clearInventory(userId) {
+    if (!userId) throw new TypeError('userId is required');
+    await this.client.cache.delete(this._key(userId));
+  }
+}
+
+module.exports = InventoryManager;