@kava/kava-api-core 1.0.0

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./auth.util";
+export * from "./controller.util";
+export * from "./conversion.util";
+export * from "./context.util";
+export * from "./db.util";
+export * from "./middleware.util";
+export * from "./model.util";
+export * from "./permission.util";
+export * from "./route.util";
+export * from "./storage.util";
+export * from "./validation.util";
+export * from "./mail.util";
+export * from "./logger.util";

package/src/logger.util.ts

@@ -0,0 +1,170 @@
+import fs from 'fs';
+import path from 'path';
+
+
+
+type LogType = "start" | "info" | "error" | "warning" | "cron" | "queue" | "queueError" | "cronError" | "socket" | "socketError";
+
+export interface AccessLog {
+  method    :  string
+  path      :  string
+  status    :  number
+  latency   :  number
+  ip       ?:  string | null
+  agent    ?:  string | null
+  at       ?:  string
+}
+
+export interface ErrorLog {
+  service    ?:  string
+  key        ?:  string
+  feature    ?:  string
+  error       :  string | null
+  reference  ?:  string | null
+  at         ?:  string
+}
+
+
+
+
+const colors: Record<LogType | "default", string> = {
+  default      :  "\x1b[0m",      // default
+  start        :  "\x1b[32m",     // green
+  info         :  "\x1b[36m",     // cyan
+  error        :  "\x1b[31m",     // red
+  warning      :  "\x1b[33m",     // yellow
+  queue        :  "\x1b[34m",     // blue
+  queueError   :  "\x1b[31m",     // red
+  cron         :  "\x1b[35m",     // magenta
+  cronError    :  "\x1b[31m",     // red
+  socket       :  "\x1b[35m",     // blue
+  socketError  :  "\x1b[31m",     // red
+};
+
+const prefixes: Record<LogType, string> = {
+  start        :  "START",
+  info         :  "INFO",
+  error        :  "ERROR",
+  warning      :  "WARNING",
+  cron         :  "CRON",
+  queue        :  "QUEUE",
+  socket       :  "SOCKET",
+  queueError   :  "QUEUE ERROR",
+  cronError    :  "CRON ERROR",
+  socketError  :  "SOCKET ERROR",
+};
+
+function log(type: LogType, msg: string) {
+  const color = colors[type];
+  const prefix = prefixes[type];
+  // eslint-disable-next-line no-console
+  console.log(`${color}[${prefix}]${colors.default}`, msg);
+}
+
+export const logger = {
+  start    :  (msg: string) => log("start", msg),
+  info     :  (msg: string) => log("info", msg),
+  warning  :  (msg: string) => log("warning", msg),
+  queue    :  (msg: string) => log("queue", msg),
+  cron     :  (msg: string) => log("cron", msg),
+  socket   :  (msg: string) => log("socket", msg),
+
+  access   :  (msg: AccessLog) => logAccess(msg),
+
+  error: (msg: string, payload?: ErrorLog) => {
+    log("error", msg)
+    payload && logError({...payload, service: payload.service || 'app'})
+  },
+  queueError: (msg: string, payload?: ErrorLog) => {
+    log("queueError", msg)
+    payload && logError({...payload, service: payload.service || 'queue'})
+  },
+  cronError: (msg: string, payload?: ErrorLog) => {
+    log("cronError", msg)
+    payload && logError({...payload, service: payload.service || 'cron'})
+  },
+  socketError: (msg: string, payload?: ErrorLog) => {
+    log("socketError", msg)
+    payload && logError({...payload, service: payload.service || 'socket'})
+  },
+};
+
+
+
+
+
+type DriverName = "file" | "da"
+
+
+const ACCESS_LOG_DRIVER        =  process.env.ACCESS_LOG_DRIVER || "file"
+const ACCESS_LOG_LOG_DIR       =  process.env.ACCESS_LOG_DIR || "storage/logs/access"
+const ACCESS_LOG_QUEUE         =  process.env.ACCESS_LOG_QUEUE || "access-log"
+
+
+const ERROR_LOG_DRIVER        = process.env.ERROR_LOG_DRIVER || "file"
+const ERROR_LOG_LOG_DIR       = process.env.ERROR_LOG_DIR || "storage/logs/error"
+const ERROR_LOG_QUEUE         = process.env.ERROR_LOG_QUEUE_PREFIX || "error-log"
+
+
+
+// =====================
+// ## Access Log Drivers
+// =====================
+const filePath = () => {
+  const d = new Date().toISOString().slice(0, 10)
+  return path.resolve( ACCESS_LOG_LOG_DIR, `access-${d}.log`)
+}
+
+const handlers: Record<DriverName, (log: AccessLog) => Promise<void>> = {
+  file: async (log) => {
+    const dir = path.resolve(ACCESS_LOG_LOG_DIR);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    fs.appendFile(filePath(), JSON.stringify(log) + "\n", () => {})
+  },
+  da: async (log) => {
+    // try {
+    //   await queue.add(ACCESS_LOG_QUEUE, log)
+    // } catch {}
+  }
+}
+
+const activeDrivers: DriverName[] = (ACCESS_LOG_DRIVER).split(",").map(v => v.trim()).filter((v): v is DriverName => v in handlers)
+
+function logAccess(payload: AccessLog) {
+  for (const d of activeDrivers) {
+    handlers[d](payload)
+  }
+}
+
+
+
+// =====================
+// ## Error Log Drivers
+// =====================
+const errorFilePath = () => {
+  const d = new Date().toISOString().slice(0, 10)
+  return path.resolve(ERROR_LOG_LOG_DIR, `error-${d}.log`)
+}
+
+const errorHandlers: Record<DriverName, (log: ErrorLog) => Promise<void>> = {
+  file: async (log) => {
+    const dir = path.resolve(ERROR_LOG_LOG_DIR);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    fs.appendFile(errorFilePath(), JSON.stringify(log) + "\n", () => {});
+  },
+  da: async (log) => {
+    // try {
+    //   await queue.add(ERROR_LOG_QUEUE, log)
+    // } catch {}
+  }
+}
+
+const activeErrorDrivers: DriverName[] = ERROR_LOG_DRIVER.split(",").map(v => v.trim()).filter((v): v is DriverName => v in errorHandlers)
+
+function logError(payload: ErrorLog) {
+  for (const d of activeErrorDrivers) {
+    errorHandlers[d](payload)
+  }
+}

package/src/mail.util.ts

@@ -0,0 +1,86 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+import nodemailer, { SentMessageInfo } from "nodemailer";
+import { logger } from "@utils";
+
+
+
+export interface SendMailOptions {
+  to            :  string;
+  subject       :  string;
+  content      ?:  string;
+  text         ?:  string;
+  attachments  ?:  {
+    filename    :  string;
+    path        :  string;
+  }[];
+}
+
+
+
+// =============================>
+// ## Mail: Send mail 
+// =============================>
+export async function sendMail(options: {
+  to            :  string;
+  subject       :  string;
+  text         ?:  string;
+  content      ?:  string;
+  attachments  ?:  { filename: string; path: string }[];
+}) {
+  const transporter = nodemailer.createTransport({
+    host    :  process.env.MAIL_HOST,
+    port    :  Number(process.env.MAIL_PORT),
+    secure  :  Number(process.env.MAIL_PORT) === 465,
+    auth    :  {
+      user  :  process.env.MAIL_USERNAME,
+      pass  :  process.env.MAIL_PASSWORD,
+    },
+  });
+
+  const info = (await transporter.sendMail({
+    from         :  `${process.env.MAIL_FROM_NAME || process.env.APP_NAME} <${process.env.MAIL_FROM_ADDRESS || process.env.MAIL_USERNAME}>`,
+    to           :  options.to,
+    subject      :  options.subject,
+    text         :  options.text,
+    html         :  options.content,
+    attachments  :  options.attachments,
+  })) as SentMessageInfo;
+
+  logger.info(`Email sent successfully: ${info.messageId}`)
+  return info;
+}
+
+
+
+// =============================>
+// ## Mail: Render mail template 
+// =============================>
+export function renderMailTemplate(template: string, options: Record<string, string>) {
+  const templateDir = join(import.meta.dir, "./../outputs/mails/templates");
+
+  const contentPath = join(templateDir, `${template}.mail.stub`);
+  let content = readFileSync(contentPath, "utf-8");
+
+  for (const [key, value] of Object.entries(options)) {
+    const regex = new RegExp(`{{\\s*${key}\\s*}}`, "g");
+    content = content.replace(regex, value);
+  }
+
+  let layout = readFileSync(join(templateDir, "layout.mail.stub"), "utf-8");
+
+  const globalVars = {
+    ...options,
+    date      :  "20-10-2025",
+    app_name  :  process.env.APP_NAME || "",
+  };
+
+  for (const [key, value] of Object.entries(globalVars)) {
+    const regex = new RegExp(`{{\\s*${key}\\s*}}`, "g");
+    layout = layout.replace(regex, value);
+  }
+
+  layout = layout.replace("{{content}}", content);
+
+  return layout;
+}

package/src/middleware.util.ts

@@ -0,0 +1,289 @@
+import { Elysia, status } from 'elysia'
+import { auth, context, logger } from '@utils'
+
+declare module "elysia" {
+  interface Elysia {
+    api(
+      basePath: string,
+      controller: {
+        index    ?:  any
+        store    ?:  any
+        show     ?:  any
+        update   ?:  any
+        destroy  ?:  any
+      }
+    ): this
+  }
+}
+
+
+const errors = {
+  unauthorized: {
+    status: 401,
+    message: "Unauthorized!"
+  },
+  ratelimited: {
+    status: 429,
+    message: "Too many requests!"
+  },
+  notfound: {
+    status: 404,
+    message: "Endpoint not found!"
+  },
+  request: {
+    status: 400,
+    message: "Bad Request!"
+  },
+  error: {
+    status: 500,
+    message: "Endpoint not found!"
+  }
+} 
+
+
+export const middleware = {
+  // =============================>
+  // ## Middleware: Auth hand;er
+  // =============================>
+  Auth: (app: Elysia) => app.derive(async ({ request }) => {
+      const authHeader = request.headers.get('authorization')
+
+      if (!authHeader || !authHeader.startsWith('Bearer ')) return { user: null, permissions: [], token: null }
+
+      const bearer = authHeader.substring(7).trim()
+      const result = await auth.verifyAccessToken(bearer, request)
+
+      if (!result) return { user: null, permissions: [], token: null };
+
+      return {
+        user: result.user,
+        permissions: result.permissions,
+        token: result.token,
+      }
+  }),
+
+
+  // =============================>
+  // ## Middleware: Private handler
+  // =============================>
+  Private: (app: Elysia) => app.derive(async ({ user }: Record<string, any> | any) => {
+      if (!user) {
+        throw status(errors.unauthorized.status, { message: errors.unauthorized.message })
+      }
+  }),
+
+
+  // =============================>
+  // ## Middleware: Cors handler
+  // =============================>
+  Cors: (app: Elysia) => app.onRequest(({ request, set }) => {
+      const origin                       = request.headers.get('origin') ?? ''
+      let allowedOrigin: string          = '*'
+
+      const originsConf = process.env.APP_CORS_ORIGINS || '*'
+
+      if (originsConf !== '*') {
+        try {
+          const allowedOrigins = JSON.parse(originsConf)
+          if (Array.isArray(allowedOrigins) && allowedOrigins.includes(origin)) {
+              allowedOrigin = origin || ""
+          }
+        } catch (e) {
+          const em = 'Cors Error: Failed to parse APP_CORS_ORIGINS, fallback to "*"'
+          logger.error(em, { error: em })
+          allowedOrigin = ''
+        }
+      }
+      
+      set.headers['Access-Control-Allow-Origin']      = allowedOrigin
+      set.headers['Access-Control-Allow-Methods']     = process.env.APP_CORS_METHODS || 'GET, POST, PUT, DELETE, OPTIONS'
+      set.headers['Access-Control-Allow-Headers']     = 'Origin, X-Requested-With, Content-Type, Accept, Authorization, X-Option, x-App'
+      set.headers['Access-Control-Allow-Credentials'] = 'true'
+
+      if (request.method === 'OPTIONS') {
+          return new Response(null, { status: 204, })
+      }
+  }),
+
+
+  // =============================>
+  // ## Middleware: Rate limiter handler
+  // =============================>
+  RateLimiter: (app: Elysia, options?: { windowMs?: number, max?: number }) => app.onRequest(({ request, set, store }) => {
+    const max       =  options?.max      || ( process.env.APP_RATELIMIT_COUNTDOWN ? Number(process.env.APP_RATE_LIMIT)          :  60 )
+    const windowMs  =  options?.windowMs || ( process.env.APP_RATELIMIT_COUNTDOWN ? Number(process.env.APP_RATELIMIT_COUNTDOWN) :  60_000 )
+
+    const user    =  (store as any)?.user
+    const key     =  getClientKey(request, user?.id)
+
+    const now     =  Date.now()
+    let   record  =  rateLimitStore.get(key)
+
+    if (!record || record.expiresAt < now) {
+      record = { count: 1, expiresAt: now + windowMs }
+      rateLimitStore.set(key, record)
+    } else {
+      record.count++
+    }
+
+    set.headers['X-RateLimit-Limit']      =  String(max)
+    set.headers['X-RateLimit-Remaining']  =  String(Math.max(0, max - record.count))
+    set.headers['X-RateLimit-Reset']      =  String(record.expiresAt)
+
+    if (record.count > max) throw status(errors.ratelimited.status, { message: errors.ratelimited.message });
+  }),
+
+
+  // =============================>
+  // ## Middleware: Body parse handler
+  // =============================>
+  BodyParse: (app: Elysia) => app.state<{ rawBody?: any }>({}).onRequest(async ({ request, store }) => {
+    const text = await request.clone().text();
+
+    const contentType = request.headers.get("content-type") || "";
+    let rawBody: any = {};
+
+    try {
+      if (contentType.includes("application/json")) {
+        rawBody = text ? JSON.parse(text) : {};
+      } else if (contentType.includes("application/x-www-form-urlencoded")) {
+        const params = new URLSearchParams(text);
+        for (const [key, value] of params.entries()) bodyParseNestedSet(rawBody, key, value);
+      } else if (contentType.includes("multipart/form-data")) {
+        const formData = await request.clone().formData();
+        for (const [key, value] of formData.entries()) bodyParseNestedSet(rawBody, key, value);
+      } else {
+        rawBody = {};
+      }
+    } catch (e) {
+      const em = e instanceof Error ? e.message : String(e)
+      logger.error(`Body parse error: ${em}`, { error: em })
+      rawBody = {};
+      throw status(errors.request.status, { message: errors.request.message })
+    }
+
+    store.rawBody = rawBody;
+  }).derive(({ store }) => {
+    const payload = bodyParseKeyFormat(store.rawBody || {});
+    return { payload };
+  }),
+
+
+  AccessLog: (app: Elysia) => app.state<{ startedAt?: number }>({}).onRequest(({ store }) => { store.startedAt = Date.now() }).onAfterResponse(({ request, set, store }) => {
+      const method   =  request.method
+      const url      =  new URL(request.url)
+      const path     =  url.pathname
+      const status   =  Number(set.status) ?? 200
+      const latency  =  Date.now() - (store.startedAt ?? Date.now())
+      const agent    =  request.headers.get("user-agent") || 'unknown'
+      const ip       =  request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || request.headers.get('cf-connecting-ip') || 'unknown'
+
+      logger.info(`${method} : ${path} - ${status} - ${latency}ms - ${ip}]`)
+      logger.access({ method, path, status, latency, ip, agent })
+    }),
+
+
+  // =============================>
+  // ## Middleware: Error handler
+  // =============================>
+  ErrorHandler: (app: Elysia) => app.onError(({ code, set, error, request }) => {
+    if (code === 'NOT_FOUND') {
+      set.status = errors.notfound.status
+      return { message:  errors.notfound.message }
+    }
+
+    if (code === 'INTERNAL_SERVER_ERROR') {
+      set.status = errors.error.status
+      const em = error.message
+      const url = new URL(request.url)
+      const path = url.pathname
+
+      logger.error(`error: ${em}`, { error: em, reference: path })
+      return { message: em }
+    }
+  }),
+
+  Context: (app: Elysia) => app.derive(async ({ store }) => {
+    const userId = (store as any)?.user?.id
+
+    return context.run({
+        user_id: userId,
+      },() => ({})
+    )
+  }),
+}
+
+
+
+// =============================>
+// ## Middleware: Body parse helpers
+// =============================>
+function bodyParseKeyFormat(input: any): any {
+  if ( typeof input !== "object" || input === null || input instanceof File ) return input;
+
+  if (Array.isArray(input)) return input.map(bodyParseKeyFormat)
+
+  const result: any = {}
+  for (const [key, value] of Object.entries(input)) {
+    if (key.includes(".") || key.includes("[")) {
+      bodyParseNestedSet(result, key, bodyParseKeyFormat(value))
+    } else {
+      result[key] = bodyParseKeyFormat(value)
+    }
+  }
+  return result
+}
+
+
+function bodyParseNestedSet(obj: any, path: string, value: any) {
+  const parts = bodyParsePathFormat(path);
+  let current = obj;
+
+  for (let i = 0; i < parts.length; i++) {
+    const key = parts[i];
+    const isLast = i === parts.length - 1;
+
+    if (isLast) {
+      current[key] = bodyParseValueFormat(value);
+    } else {
+      if (!(key in current)) {
+        const nextKey = parts[i + 1];
+        current[key] = isNaN(Number(nextKey)) ? {} : [];
+      }
+      current = current[key];
+    }
+  }
+}
+
+function bodyParsePathFormat(path: string): string[] {
+  return path.replace(/\[(\w+)\]/g, ".$1").replace(/^\./, "").split(".");
+}
+
+function bodyParseValueFormat(value: any) {
+  if (value == "" || value == null || value == "null") return null;
+  if (typeof value !== "string") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (!isNaN(Number(value))) return Number(value);
+  return value;
+}
+
+
+
+// =============================>
+// ## Middleware: Rate Limiter Helpers
+// =============================>
+type RateLimitRecord = {
+  count: number
+  expiresAt: number
+}
+
+const rateLimitStore = new Map<string, RateLimitRecord>()
+
+function getClientKey(request: Request, userId?: string | number) {
+  if (userId) return `user:${userId}`
+
+  const ip = request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || request.headers.get('cf-connecting-ip') || 'unknown'
+
+  return `ip:${ip}`
+}