enerthya.dev-web-common 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# enerthya.dev-web-common
+
+> Shared web layer for the Enerthya ecosystem.
+> Inspired by Loritta's `loritta-website:web-common` + `loritta-dashboard:dashboard-common` modules.
+
+---
+
+## What's inside
+
+| Export | What it does |
+|--------|-------------|
+| `API_ROUTES` | Central source of truth for all API route paths — never type route strings twice |
+| `HTTP_STATUS` | Named HTTP status code constants (no more magic numbers) |
+| `createSuccess(data)` | Wraps a payload in `{ ok: true, data }` |
+| `createError(status, message, code?)` | Wraps an error in `{ ok: false, status, message, code? }` |
+| `isApiSuccess(value)` | Returns true if value is a success envelope |
+| `isApiError(value)` | Returns true if value is an error envelope |
+| `API_ERRORS` | Pre-built common errors: `NOT_AUTHENTICATED`, `FORBIDDEN`, `NOT_FOUND`, `INTERNAL`, `BOT_OFFLINE` |
+| `UrlUtils` | Dashboard URL builders + snowflake helpers |
+| `ParamValidator` | Validates route params and request bodies — returns `{ valid, error? }` |
+
+---
+
+## Install
+
+```bash
+npm install enerthya.dev-web-common
+```
+
+---
+
+## Usage
+
+### API_ROUTES
+
+```js
+const { API_ROUTES } = require("enerthya.dev-web-common");
+
+// Static routes
+API_ROUTES.AUTH.USER          // "/auth/user"
+API_ROUTES.AUTH.LOGOUT        // "/auth/logout"
+API_ROUTES.GUILDS             // "/guilds"
+API_ROUTES.STATUS             // "/status"
+API_ROUTES.COMMANDS           // "/commands"
+API_ROUTES.DAILY.STATUS       // "/daily"
+API_ROUTES.DAILY.CAPTCHA      // "/daily/captcha"
+API_ROUTES.DAILY.CLAIM        // "/daily/claim"
+
+// Dynamic routes
+API_ROUTES.GUILD_CONFIG("123456")           // "/guilds/123456/config"
+API_ROUTES.GUILD_WARNS("123456")            // "/guilds/123456/warns"
+API_ROUTES.GUILD_WARN("123456", "warn_id")  // "/guilds/123456/warns/warn_id"
+API_ROUTES.GUILD_COMMAND_SETTINGS("123456") // "/guilds/123456/command-settings"
+```
+
+### Response envelopes
+
+```js
+const { createSuccess, createError, isApiError } = require("enerthya.dev-web-common");
+
+// 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(API_ROUTES.GUILD_CONFIG(guildId));
+if (isApiError(data)) throw new Error(data.message);
+const config = data.data; // strongly typed payload
+```
+
+### ParamValidator
+
+```js
+const { ParamValidator, createError, HTTP_STATUS } = require("enerthya.dev-web-common");
+
+router.get("/guilds/:id/config", CheckAuth, async (req, res) => {
+  const check = ParamValidator.guildId(req.params.id);
+  if (!check.valid) {
+    return res.status(HTTP_STATUS.BAD_REQUEST).json(createError(400, check.error));
+  }
+  // ... continue safely
+});
+```
+
+Available validators:
+- `ParamValidator.guildId(id)` — Discord snowflake
+- `ParamValidator.objectId(id)` — MongoDB ObjectId (24 hex chars)
+- `ParamValidator.requiredString(value, fieldName, { minLength?, maxLength? })`
+- `ParamValidator.optionalString(value, fieldName, { maxLength? })`
+- `ParamValidator.boolean(value, fieldName)`
+- `ParamValidator.nonNegativeInt(value, fieldName, { max? })`
+- `ParamValidator.hexColor(value, fieldName)`
+- `ParamValidator.snowflake(id, fieldName?)`
+- `ParamValidator.all(...results)` — runs multiple validators, returns first failure
+
+### UrlUtils
+
+```js
+const { UrlUtils } = require("enerthya.dev-web-common");
+
+UrlUtils.guildBase("123456")               // "/dashboard/123456"
+UrlUtils.guildModule("123456", "welcome")  // "/dashboard/123456/welcome"
+UrlUtils.parseGuildId("/dashboard/123456/overview") // "123456"
+UrlUtils.isValidSnowflake("123456789012345678")     // true
+UrlUtils.absolute("https://enerthya.dev", "/dashboard/123456") // full URL
+```
+
+---
+
+## Test
+
+```bash
+node test.js
+# 84/84 passing
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "enerthya.dev-web-common",
+  "version": "1.0.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"
+  ],
+  "author": "Enerthya",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {}
+}

package/src/constants/httpStatus.js

@@ -0,0 +1,24 @@
+/**
+ * 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"));
+ */
+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,
+};
+
+module.exports = { HTTP_STATUS };

package/src/constants/index.js

@@ -0,0 +1,4 @@
+const { API_ROUTES } = require("./routes");
+const { HTTP_STATUS } = require("./httpStatus");
+
+module.exports = { API_ROUTES, HTTP_STATUS };

package/src/constants/routes.js

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+
+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",
+};
+
+module.exports = { API_ROUTES };

package/src/index.js

@@ -0,0 +1,60 @@
+/**
+ * enerthya.dev-web-common — Shared web layer for the Enerthya ecosystem.
+ *
+ * Inspired by Loritta's `loritta-website:web-common` and
+ * `loritta-dashboard:dashboard-common` modules (LorittaBot/Loritta).
+ * Adapted for Node.js / JavaScript.
+ *
+ * What this package provides:
+ *   - API_ROUTES    : Central source of truth for all API route paths
+ *   - HTTP_STATUS   : Named HTTP status code constants
+ *   - createSuccess / createError : Standardised API response envelopes
+ *   - isApiSuccess / isApiError   : Type guards for API responses
+ *   - API_ERRORS    : Pre-built common error responses
+ *   - UrlUtils      : Dashboard URL builders and snowflake helpers
+ *   - ParamValidator: Validates route params and request bodies
+ *
+ * @example
+ * // Server (Express route handler)
+ * const { API_ROUTES, createSuccess, createError, ParamValidator, HTTP_STATUS } =
+ *   require("enerthya.dev-web-common");
+ *
+ * router.get(API_ROUTES.GUILD_CONFIG(":id"), CheckAuth, async (req, res) => {
+ *   const check = ParamValidator.guildId(req.params.id);
+ *   if (!check.valid) return res.status(HTTP_STATUS.BAD_REQUEST).json(createError(400, check.error));
+ *   const config = await Guild.findOne({ guildId: req.params.id });
+ *   res.json(createSuccess(config));
+ * });
+ *
+ * // Client (React / axios)
+ * const { API_ROUTES, isApiError } = require("enerthya.dev-web-common");
+ * const { data } = await axios.get(API_ROUTES.GUILD_CONFIG(guildId));
+ * if (isApiError(data)) throw new Error(data.message);
+ */
+
+const { API_ROUTES, HTTP_STATUS } = require("./constants/index");
+const { UrlUtils, ParamValidator } = require("./utils/index");
+const {
+  createSuccess,
+  createError,
+  isApiSuccess,
+  isApiError,
+  API_ERRORS,
+} = require("./structures/index");
+
+module.exports = {
+  // Constants
+  API_ROUTES,
+  HTTP_STATUS,
+
+  // Response helpers
+  createSuccess,
+  createError,
+  isApiSuccess,
+  isApiError,
+  API_ERRORS,
+
+  // URL + validation utilities
+  UrlUtils,
+  ParamValidator,
+};

package/src/structures/ApiResponse.js

@@ -0,0 +1,93 @@
+/**
+ * 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 }}
+ */
+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 }}
+ */
+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}
+ */
+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}
+ */
+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.
+ */
+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"),
+};
+
+module.exports = {
+  createSuccess,
+  createError,
+  isApiSuccess,
+  isApiError,
+  API_ERRORS,
+};

package/src/structures/index.js

@@ -0,0 +1,15 @@
+const {
+  createSuccess,
+  createError,
+  isApiSuccess,
+  isApiError,
+  API_ERRORS,
+} = require("./ApiResponse");
+
+module.exports = {
+  createSuccess,
+  createError,
+  isApiSuccess,
+  isApiError,
+  API_ERRORS,
+};

package/src/utils/ParamValidator.js

@@ -0,0 +1,151 @@
+/**
+ * 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));
+ */
+
+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 };
+  },
+};
+
+module.exports = { ParamValidator };

package/src/utils/UrlUtils.js

@@ -0,0 +1,76 @@
+/**
+ * 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";
+
+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", "ticket"
+   * @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}`;
+  },
+};
+
+module.exports = { UrlUtils };

package/src/utils/index.js

@@ -0,0 +1,4 @@
+const { UrlUtils } = require("./UrlUtils");
+const { ParamValidator } = require("./ParamValidator");
+
+module.exports = { UrlUtils, ParamValidator };