enerthya.dev-web-common 1.0.0 → 1.1.0

package/esm/constants/httpStatus.js

@@ -0,0 +1,23 @@
+/**
+ * HTTP_STATUS — Named HTTP status codes used across the Enerthya stack.
+ *
+ * Use these instead of magic numbers in route handlers and client error checks.
+ *
+ * @example
+ * res.status(HTTP_STATUS.UNAUTHORIZED).json(createError(401, "Not authenticated"));
+ */
+export const HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  UNPROCESSABLE: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503,
+};
+

package/esm/constants/index.js

@@ -0,0 +1,3 @@
+import { API_ROUTES } from "./routes.js";
+import { HTTP_STATUS } from "./httpStatus.js";
+export { API_ROUTES, HTTP_STATUS };

package/esm/constants/routes.js

@@ -0,0 +1,72 @@
+/**
+ * API_ROUTES — Central source of truth for all API route paths.
+ *
+ * Every route is defined once here and imported everywhere else.
+ * Prevents strings from diverging between server/routes/ and client/src/.
+ *
+ * Usage:
+ *   const { API_ROUTES } = require("enerthya.dev-web-common");
+ *   API_ROUTES.GUILD_CONFIG("123456")  // => "/guilds/123456/config"
+ *   API_ROUTES.AUTH.USER               // => "/auth/user"
+ *
+ * All paths are relative (no leading "/api/") — the client's axios baseURL
+ * already includes "/api", and the server mounts on "/api" as well.
+ */
+
+export const API_ROUTES = {
+  // ─── Auth ────────────────────────────────────────────────────────────────
+  AUTH: {
+    /** GET — OAuth2 login redirect */
+    LOGIN: "/auth/login",
+    /** GET — OAuth2 callback */
+    CALLBACK: "/auth/callback",
+    /** POST — Logout and destroy session */
+    LOGOUT: "/auth/logout",
+    /** GET — Current authenticated user */
+    USER: "/auth/user",
+  },
+
+  // ─── Guilds ──────────────────────────────────────────────────────────────
+  /** GET — All guilds the user manages */
+  GUILDS: "/guilds",
+  /**
+   * GET / POST — Guild config
+   * @param {string} id - Discord guild ID
+   */
+  GUILD_CONFIG: (id) => `/guilds/${id}/config`,
+  /**
+   * GET — Warns for a guild
+   * @param {string} id - Discord guild ID
+   */
+  GUILD_WARNS: (id) => `/guilds/${id}/warns`,
+  /**
+   * DELETE — Remove a specific warn
+   * @param {string} id - Discord guild ID
+   * @param {string} warnId - Warn document ID
+   */
+  GUILD_WARN: (id, warnId) => `/guilds/${id}/warns/${warnId}`,
+  /**
+   * GET — Command-level permission settings for a guild
+   * @param {string} id - Discord guild ID
+   */
+  GUILD_COMMAND_SETTINGS: (id) => `/guilds/${id}/command-settings`,
+
+  // ─── Daily ───────────────────────────────────────────────────────────────
+  DAILY: {
+    /** GET — Daily status (coins, streak, next claim) */
+    STATUS: "/daily",
+    /** GET — Captcha for daily claim */
+    CAPTCHA: "/daily/captcha",
+    /** POST — Claim daily reward */
+    CLAIM: "/daily/claim",
+  },
+
+  // ─── Meta ─────────────────────────────────────────────────────────────────
+  /** GET — Bot + shard status */
+  STATUS: "/status",
+  /** GET — All registered commands */
+  COMMANDS: "/commands",
+  /** GET — Dev-only diagnostics */
+  DEV: "/dev",
+};
+

package/esm/index.js

@@ -0,0 +1,15 @@
+/**
+ * enerthya.dev-web-common — ESM build
+ * Bundlers e Vite usam este arquivo via campo "exports"."import" no package.json.
+ * Node.js (bot/server) continua usando src/index.js via "require".
+ */
+
+export { API_ROUTES, HTTP_STATUS } from './constants/index.js';
+export { UrlUtils, ParamValidator } from './utils/index.js';
+export {
+  createSuccess,
+  createError,
+  isApiSuccess,
+  isApiError,
+  API_ERRORS,
+} from './structures/index.js';

package/esm/structures/ApiResponse.js

@@ -0,0 +1,86 @@
+/**
+ * Response factories — Standardised API response shapes.
+ *
+ * Inspired by Loritta's `loritta-website:web-common` typed response wrappers.
+ *
+ * All server routes should use these factories so the client always receives
+ * a predictable envelope. The client uses `isApiError` / `isApiSuccess` to
+ * branch on the result without checking HTTP status codes manually.
+ *
+ * @example
+ * // In an Express route handler:
+ * res.json(createSuccess({ guilds: [...] }));
+ * res.status(403).json(createError(403, "Forbidden", "MISSING_PERMISSION"));
+ *
+ * // In a React component:
+ * const data = await axios.get(...);
+ * if (isApiError(data.data)) { ... }
+ */
+
+/**
+ * Builds a successful API response envelope.
+ *
+ * @template T
+ * @param {T} data - Payload to embed in the response.
+ * @returns {{ ok: true, data: T }}
+ */
+export function createSuccess(data) {
+  return { ok: true, data };
+}
+
+/**
+ * Builds an error API response envelope.
+ *
+ * @param {number} status   - HTTP status code (for reference in the body).
+ * @param {string} message  - Human-readable error message.
+ * @param {string} [code]   - Optional machine-readable error code (UPPER_SNAKE).
+ * @returns {{ ok: false, status: number, message: string, code?: string }}
+ */
+export function createError(status, message, code) {
+  const response = { ok: false, status, message };
+  if (code !== undefined) response.code = code;
+  return response;
+}
+
+/**
+ * Returns true if the value looks like a successful API response.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isApiSuccess(value) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    value.ok === true &&
+    "data" in value
+  );
+}
+
+/**
+ * Returns true if the value looks like an error API response.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isApiError(value) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    value.ok === false &&
+    typeof value.message === "string"
+  );
+}
+
+/**
+ * Common pre-built error responses.
+ * Use these constants to avoid typos in repeated error messages.
+ */
+export const API_ERRORS = {
+  NOT_AUTHENTICATED: createError(401, "Not authenticated", "NOT_AUTHENTICATED"),
+  FORBIDDEN: createError(403, "Access forbidden", "FORBIDDEN"),
+  NOT_FOUND: createError(404, "Resource not found", "NOT_FOUND"),
+  INTERNAL: createError(500, "Internal server error", "INTERNAL_SERVER_ERROR"),
+  BOT_OFFLINE: createError(503, "Bot is offline or unreachable", "BOT_OFFLINE"),
+};
+

package/esm/structures/index.js

@@ -0,0 +1,8 @@
+import {
+  createSuccess,
+  createError,
+  isApiSuccess,
+  isApiError,
+  API_ERRORS,
+} from "./ApiResponse.js";
+export { createSuccess, createError, isApiSuccess, isApiError, API_ERRORS };

package/esm/utils/ParamValidator.js

@@ -0,0 +1,150 @@
+/**
+ * ParamValidator — Validates route parameters and request bodies.
+ *
+ * Used in Express route handlers to validate inputs before touching
+ * the database. Returns structured results instead of throwing, so
+ * routes can decide how to respond.
+ *
+ * @example
+ * const { ParamValidator } = require("enerthya.dev-web-common");
+ *
+ * const result = ParamValidator.guildId(req.params.id);
+ * if (!result.valid) return res.status(400).json(createError(400, result.error));
+ */
+
+export const ParamValidator = {
+  /**
+   * Validates a Discord guild ID (snowflake).
+   * @param {unknown} id
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  guildId(id) {
+    if (typeof id !== "string" || !/^\d{17,20}$/.test(id)) {
+      return { valid: false, error: "Invalid guild ID — must be a 17-20 digit Discord snowflake" };
+    }
+    return { valid: true };
+  },
+
+  /**
+   * Validates a MongoDB ObjectId string (24 hex chars).
+   * @param {unknown} id
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  objectId(id) {
+    if (typeof id !== "string" || !/^[a-f0-9]{24}$/i.test(id)) {
+      return { valid: false, error: "Invalid ID — must be a 24-character hex string" };
+    }
+    return { valid: true };
+  },
+
+  /**
+   * Validates a required string field in a request body.
+   * @param {unknown} value
+   * @param {string} fieldName - Used in the error message.
+   * @param {{ minLength?: number, maxLength?: number }} [options]
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  requiredString(value, fieldName, options = {}) {
+    if (typeof value !== "string" || value.trim() === "") {
+      return { valid: false, error: `"${fieldName}" is required and must be a non-empty string` };
+    }
+    const { minLength, maxLength } = options;
+    if (minLength !== undefined && value.length < minLength) {
+      return { valid: false, error: `"${fieldName}" must be at least ${minLength} characters` };
+    }
+    if (maxLength !== undefined && value.length > maxLength) {
+      return { valid: false, error: `"${fieldName}" must be at most ${maxLength} characters` };
+    }
+    return { valid: true };
+  },
+
+  /**
+   * Validates an optional string field — passes if undefined/null, fails if wrong type.
+   * @param {unknown} value
+   * @param {string} fieldName
+   * @param {{ maxLength?: number }} [options]
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  optionalString(value, fieldName, options = {}) {
+    if (value === undefined || value === null) return { valid: true };
+    if (typeof value !== "string") {
+      return { valid: false, error: `"${fieldName}" must be a string or null` };
+    }
+    const { maxLength } = options;
+    if (maxLength !== undefined && value.length > maxLength) {
+      return { valid: false, error: `"${fieldName}" must be at most ${maxLength} characters` };
+    }
+    return { valid: true };
+  },
+
+  /**
+   * Validates a boolean field.
+   * @param {unknown} value
+   * @param {string} fieldName
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  boolean(value, fieldName) {
+    if (typeof value !== "boolean") {
+      return { valid: false, error: `"${fieldName}" must be a boolean (true or false)` };
+    }
+    return { valid: true };
+  },
+
+  /**
+   * Validates a non-negative integer field.
+   * @param {unknown} value
+   * @param {string} fieldName
+   * @param {{ max?: number }} [options]
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  nonNegativeInt(value, fieldName, options = {}) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+      return { valid: false, error: `"${fieldName}" must be a non-negative integer` };
+    }
+    const { max } = options;
+    if (max !== undefined && value > max) {
+      return { valid: false, error: `"${fieldName}" must be at most ${max}` };
+    }
+    return { valid: true };
+  },
+
+  /**
+   * Validates a hex color string (e.g. "#5865F2" or "#FFF").
+   * @param {unknown} value
+   * @param {string} fieldName
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  hexColor(value, fieldName) {
+    if (typeof value !== "string" || !/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value)) {
+      return { valid: false, error: `"${fieldName}" must be a valid hex color (e.g. #5865F2)` };
+    }
+    return { valid: true };
+  },
+
+  /**
+   * Validates a Discord snowflake (channel ID, role ID, user ID, etc.).
+   * Alias for guildId — same format.
+   * @param {unknown} id
+   * @param {string} [fieldName]
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  snowflake(id, fieldName = "ID") {
+    if (typeof id !== "string" || !/^\d{17,20}$/.test(id)) {
+      return { valid: false, error: `"${fieldName}" must be a valid Discord snowflake ID` };
+    }
+    return { valid: true };
+  },
+
+  /**
+   * Runs multiple validators and returns the first failure, or { valid: true }.
+   * @param {...{ valid: boolean, error?: string }} results
+   * @returns {{ valid: boolean, error?: string }}
+   */
+  all(...results) {
+    for (const result of results) {
+      if (!result.valid) return result;
+    }
+    return { valid: true };
+  },
+};
+

package/esm/utils/UrlUtils.js

@@ -0,0 +1,75 @@
+/**
+ * UrlUtils — URL building and parsing helpers for the Enerthya dashboard.
+ *
+ * Centralises all path construction so route strings never drift between
+ * the server and the client.
+ *
+ * @example
+ * UrlUtils.guildBase("123456")        // "/dashboard/123456"
+ * UrlUtils.guildModule("123456", "xp-rates")  // "/dashboard/123456/xp-rates"
+ * UrlUtils.parseGuildId("/dashboard/123456/overview")  // "123456"
+ */
+
+const DASHBOARD_PREFIX = "/dashboard";
+
+export const UrlUtils = {
+  /**
+   * Root path for a guild in the dashboard.
+   * @param {string} guildId
+   * @returns {string}
+   */
+  guildBase(guildId) {
+    if (!guildId || typeof guildId !== "string") {
+      throw new TypeError("guildId must be a non-empty string");
+    }
+    return `${DASHBOARD_PREFIX}/${guildId}`;
+  },
+
+  /**
+   * Path to a specific module page inside a guild.
+   * @param {string} guildId
+   * @param {string} module - e.g. "welcome", "xp-rates", "suggestion"
+   * @returns {string}
+   */
+  guildModule(guildId, module) {
+    if (!module || typeof module !== "string") {
+      throw new TypeError("module must be a non-empty string");
+    }
+    return `${UrlUtils.guildBase(guildId)}/${module}`;
+  },
+
+  /**
+   * Extracts the guild ID from a dashboard URL path.
+   * Returns null if the path is not a valid guild path.
+   * @param {string} pathname
+   * @returns {string|null}
+   */
+  parseGuildId(pathname) {
+    if (typeof pathname !== "string") return null;
+    const match = pathname.match(/^\/dashboard\/(\d{17,20})/);
+    return match ? match[1] : null;
+  },
+
+  /**
+   * Returns true if the given string looks like a valid Discord snowflake ID.
+   * @param {string|unknown} id
+   * @returns {boolean}
+   */
+  isValidSnowflake(id) {
+    return typeof id === "string" && /^\d{17,20}$/.test(id);
+  },
+
+  /**
+   * Builds a full absolute URL given a base and a relative path.
+   * Safely handles trailing slashes on the base.
+   * @param {string} base - e.g. "https://enerthya.dev"
+   * @param {string} path - e.g. "/dashboard/123456/welcome"
+   * @returns {string}
+   */
+  absolute(base, path) {
+    const cleanBase = base.replace(/\/+$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    return `${cleanBase}${cleanPath}`;
+  },
+};
+

package/esm/utils/index.js

@@ -0,0 +1,3 @@
+import { UrlUtils } from "./UrlUtils.js";
+import { ParamValidator } from "./ParamValidator.js";
+export { UrlUtils, ParamValidator };

package/package.json

@@ -1,24 +1,20 @@
 {
   "name": "enerthya.dev-web-common",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared web layer for the Enerthya ecosystem: API routes, response envelopes, URL helpers and validators. Inspired by Loritta's web-common and dashboard-common modules.",
   "main": "src/index.js",
-  "keywords": [
-    "enerthya",
-    "discord",
-    "web",
-    "api",
-    "routes",
-    "common"
-  ],
+  "module": "esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js",
+      "require": "./src/index.js",
+      "default": "./esm/index.js"
+    }
+  },
+  "keywords": ["enerthya", "discord", "web", "api", "routes", "common"],
   "author": "Enerthya",
   "license": "MIT",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "files": [
-    "src/",
-    "README.md"
-  ],
+  "engines": { "node": ">=18.0.0" },
+  "files": ["src/", "esm/", "README.md"],
   "dependencies": {}
 }

package/src/utils/UrlUtils.js

@@ -28,7 +28,7 @@ const UrlUtils = {
   /**
    * Path to a specific module page inside a guild.
    * @param {string} guildId
-   * @param {string} module - e.g. "welcome", "xp-rates", "ticket"
+   * @param {string} module - e.g. "welcome", "xp-rates", "suggestion"
    * @returns {string}
    */
   guildModule(guildId, module) {