@nexa-stack/framework 1.0.0

package/docs/services.md

@@ -0,0 +1,146 @@
+# Mail · Notifications · Cache · Log · Schedule
+
+Built-in services with concise Nexa syntax.
+
+## Mail
+
+```ts
+import { mail, Mail, on, getDb } from "./packages/core/src/index.js";
+
+// Simple
+await mail("ali@corp.com", "New invoice", "Invoice #12 created");
+
+// HTML
+await Mail().to("ali@corp.com").subject("Hello").html("<b>Hi</b>").send();
+
+// Via queue
+await Mail().to("ali@corp.com").subject("Hello").text("Hi").queue(getDb()!);
+// then: bun run nexa queue:work
+```
+
+### .env
+
+```env
+MAIL_DRIVER=log          # default — writes storage/logs/mail.log
+# MAIL_DRIVER=smtp
+# MAIL_HOST=smtp.mailtrap.io
+# MAIL_PORT=587
+# MAIL_USER=...
+# MAIL_PASS=...
+# MAIL_FROM=noreply@yourapp.com
+```
+
+With events:
+
+```ts
+on("orders.created", async ({ data }) => {
+  await mail("admin@corp.com", "New order", `Order #${data.id}`);
+});
+```
+
+---
+
+## Notifications
+
+```ts
+import { notify, on } from "./packages/core/src/index.js";
+
+await notify(
+  { id: 1, email: "ali@corp.com" },
+  {
+    title: "New order",
+    body: "Your order was created",
+    via: ["database", "mail"],  // default: ["database"]
+  }
+);
+```
+
+API (login required):
+
+| Method | URL | Description |
+|--------|-----|-------------|
+| GET | `/api/notifications` | Unread list |
+| POST | `/api/notifications/:id/read` | Mark one read |
+| POST | `/api/notifications/read-all` | Mark all read |
+
+---
+
+## Cache
+
+```ts
+import { cache } from "./packages/core/src/index.js";
+
+await cache.set("stats", { total: 10 }, 60); // 60 seconds
+await cache.get("stats");
+await cache.forget("stats");
+
+const value = await cache.remember("dashboard", 120, async () => {
+  return { revenue: 5000 };
+});
+```
+
+```env
+CACHE_DRIVER=memory   # or file → storage/cache/
+# CACHE_DRIVER=redis
+# REDIS_URL=redis://127.0.0.1:6379
+```
+
+Redis is optional (`ioredis` or Bun redis).
+---
+
+## Logging
+
+```ts
+import { log } from "./packages/core/src/index.js";
+
+log.debug("...");
+log.info("Server started");
+log.warn("Slow query");
+log.error("Failed", { err });
+```
+
+Writes to console + `storage/logs/nexa.log`.
+
+```env
+LOG_LEVEL=info   # debug | info | warn | error
+```
+
+---
+
+## Schedule
+
+`schedule.ts` in project root:
+
+```ts
+import { schedule, log, processJobs, getDb } from "./packages/core/src/index.js";
+
+schedule.everyMinute(async () => {
+  await processJobs(getDb()!, 20);
+});
+
+schedule.daily(() => log.info("Daily cleanup"));
+```
+
+```bash
+bun run nexa schedule:work
+```
+
+| Method | Interval |
+|--------|----------|
+| `everyMinute` | 1 min |
+| `everyFiveMinutes` | 5 min |
+| `everyHour` | 1 hour |
+| `daily` | 24 hours |
+| `every(seconds, fn)` | custom |
+
+---
+
+## vs Laravel
+
+| Laravel | Nexa |
+|---------|------|
+| `Mail::to()->send()` | `Mail().to().send()` / `mail()` |
+| `Notification::send()` | `notify(user, {...})` |
+| `Cache::remember()` | `cache.remember()` |
+| `Log::info()` | `log.info()` |
+| `Schedule::` + `schedule:run` | `schedule.` + `schedule:work` |

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@nexa-stack/framework",
+  "version": "1.0.0",
+  "description": "Nexa Stack — Node.js framework. One resource → REST API, ORM, auth, queue, and admin panel. Zero native build (Hostinger / Windows friendly).",
+  "type": "module",
+  "main": "./packages/core/src/index.ts",
+  "module": "./packages/core/src/index.ts",
+  "types": "./packages/core/src/index.ts",
+  "exports": {
+    ".": "./packages/core/src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "nexa": "./bin/nexa.mjs"
+  },
+  "files": [
+    "packages",
+    "bin",
+    "public",
+    "docs",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "homepage": "https://www.npmjs.com/package/@nexa-stack/framework",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "nexa serve",
+    "nexa": "node --import tsx bin/nexa.ts",
+    "serve": "node --import tsx bin/nexa.ts serve",
+    "test": "vitest run",
+    "prepublishOnly": "vitest run"
+  },
+  "keywords": [
+    "nexa",
+    "nexa-stack",
+    "@nexa-stack/framework",
+    "framework",
+    "node",
+    "nodejs",
+    "fullstack",
+    "api",
+    "typescript",
+    "admin",
+    "crud",
+    "orm",
+    "rest",
+    "hostinger"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.2",
+    "mysql2": "^3.24.2",
+    "nodemailer": "^9.0.6",
+    "postgres": "^3.4.9",
+    "sql.js": "^1.14.2",
+    "tsx": "^4.20.3"
+  },
+  "optionalDependencies": {
+    "ioredis": "^5.6.1"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/node": "^22.15.30",
+    "@types/nodemailer": "^8.0.1",
+    "@types/sql.js": "^1.4.11",
+    "vitest": "^3.2.3"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true
+  }
+}

package/packages/auth/src/auth.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test, beforeAll } from "vitest";
+import { signToken, verifyToken, hasRole, setupAuth } from "./auth.js";
+import { createDatabase } from "../../database/src/database.js";
+
+describe("auth", () => {
+  beforeAll(async () => {
+    const db = createDatabase(":memory:");
+    await db.connect();
+    await setupAuth({ secret: "auth-test-secret-key" }, db);
+  });
+
+  test("sign and verify token", () => {
+    const user = { id: 1, email: "a@test.com", role: "user" };
+    const token = signToken(user);
+    const decoded = verifyToken(token);
+    expect(decoded?.email).toBe("a@test.com");
+  });
+
+  test("hasRole admin bypass", () => {
+    expect(hasRole({ id: 1, email: "a", role: "admin" }, "user")).toBe(true);
+    expect(hasRole({ id: 1, email: "a", role: "user" }, "admin")).toBe(false);
+  });
+});

package/packages/auth/src/auth.ts

@@ -0,0 +1,287 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { Database } from "../../database/src/database.js";
+import { passwordResetsTableSql, usersTableSql } from "../../database/src/dialect.js";
+import { mail } from "../../mail/src/index.js";
+import { config as appConfig } from "../../core/src/config.js";
+
+export interface AuthUser {
+  id: number;
+  email: string;
+  role: string;
+  email_verified_at?: string | null;
+}
+
+export interface AuthConfig {
+  secret: string;
+}
+
+let authConfig: AuthConfig = { secret: "change-me" };
+let dbRef: Database | null = null;
+
+export async function setupAuth(cfg: AuthConfig, db: Database): Promise<void> {
+  if (!cfg.secret || cfg.secret.length < 8) {
+    throw new Error("APP_SECRET must be at least 8 characters");
+  }
+  authConfig = cfg;
+  dbRef = db;
+  await db.run(usersTableSql(db.dialect));
+  await db.run(passwordResetsTableSql(db.dialect));
+  await ensureUserColumns(db);
+}
+
+async function ensureUserColumns(db: Database): Promise<void> {
+  const alters = ["ALTER TABLE users ADD COLUMN email_verified_at TEXT"];
+  for (const sql of alters) {
+    try {
+      await db.run(sql);
+    } catch {
+      /* column already exists */
+    }
+  }
+}
+
+import bcrypt from "bcryptjs";
+
+export async function hashPassword(password: string): Promise<string> {
+  return bcrypt.hash(password, 10);
+}
+
+export async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(password, hash);
+}
+
+function b64urlJson(data: unknown): string {
+  return Buffer.from(JSON.stringify(data), "utf8")
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function b64urlBytes(buf: Buffer): string {
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function b64urlDecode(s: string): string {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64").toString("utf8");
+}
+
+function hmacSign(header: string, payload: string): string {
+  return b64urlBytes(
+    createHmac("sha256", authConfig.secret).update(`${header}.${payload}`).digest()
+  );
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const ba = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ba.length !== bb.length) return false;
+  return timingSafeEqual(ba, bb);
+}
+
+function randomToken(): string {
+  return crypto.randomUUID().replace(/-/g, "") + crypto.randomUUID().replace(/-/g, "");
+}
+
+export function signToken(user: AuthUser): string {
+  const header = b64urlJson({ alg: "HS256", typ: "JWT" });
+  const payload = b64urlJson({
+    sub: user.id,
+    email: user.email,
+    role: user.role,
+    exp: Date.now() + 86400000,
+  });
+  const sig = hmacSign(header, payload);
+  return `${header}.${payload}.${sig}`;
+}
+
+export function verifyToken(token: string): AuthUser | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const [headerB64, payloadB64, sig] = parts;
+
+    const header = JSON.parse(b64urlDecode(headerB64));
+    if (header.alg !== "HS256") return null;
+
+    const expected = hmacSign(headerB64, payloadB64);
+    if (!safeEqual(sig, expected)) return null;
+
+    const payload = JSON.parse(b64urlDecode(payloadB64));
+    if (typeof payload.exp !== "number" || payload.exp < Date.now()) return null;
+    if (payload.sub == null || !payload.email || !payload.role) return null;
+
+    return {
+      id: Number(payload.sub),
+      email: String(payload.email),
+      role: String(payload.role),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function userFromRequest(req: Request): AuthUser | null {
+  const header = req.headers.get("authorization");
+  if (!header?.startsWith("Bearer ")) return null;
+  return verifyToken(header.slice(7));
+}
+
+function toUser(row: Record<string, unknown>): AuthUser {
+  return {
+    id: row.id as number,
+    email: row.email as string,
+    role: row.role as string,
+    email_verified_at: (row.email_verified_at as string) ?? null,
+  };
+}
+
+export async function register(
+  email: string,
+  password: string,
+  role = "user"
+): Promise<AuthUser> {
+  if (!dbRef) throw new Error("Call auth() first");
+  const hash = await hashPassword(password);
+  const row = await dbRef.insert("users", {
+    email,
+    password: hash,
+    role,
+    email_verified_at: null,
+  });
+  const user = toUser(row);
+  await sendVerificationEmail(user).catch(() => undefined);
+  return user;
+}
+
+export async function login(
+  email: string,
+  password: string
+): Promise<{ user: AuthUser; token: string } | null> {
+  if (!dbRef) throw new Error("Call start() first");
+  const row = await dbRef.getOne("SELECT * FROM users WHERE email = ?", [email]);
+  if (!row) return null;
+  const ok = await verifyPassword(password, row.password as string);
+  if (!ok) return null;
+  const user = toUser(row);
+  return { user, token: signToken(user) };
+}
+
+export async function seedAdmin(db: Database): Promise<void> {
+  const exists = await db.getOne("SELECT id FROM users WHERE role = ?", ["admin"]);
+  if (exists) return;
+  const email = appConfig("ADMIN_EMAIL") || "admin@nexa.dev";
+  const password = appConfig("ADMIN_PASSWORD") || "123456";
+  const hash = await hashPassword(password);
+  await db.insert("users", {
+    email,
+    password: hash,
+    role: "admin",
+    email_verified_at: new Date().toISOString(),
+  });
+}
+
+export function hasRole(user: AuthUser | null, role: string): boolean {
+  if (!user) return false;
+  if (user.role === "admin") return true;
+  return user.role === role;
+}
+
+/** Request password reset — emails a token (always returns ok to avoid email enumeration) */
+export async function forgotPassword(email: string): Promise<{ sent: boolean }> {
+  if (!dbRef) throw new Error("Call start() first");
+  const row = await dbRef.getOne("SELECT * FROM users WHERE email = ?", [email]);
+  if (!row) return { sent: true };
+
+  const token = randomToken();
+  const expires = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+  await dbRef.run(`DELETE FROM password_resets WHERE email = ?`, [email]);
+  await dbRef.insert("password_resets", { email, token, expires_at: expires });
+
+  const appUrl = appConfig("APP_URL") || "http://localhost:3333";
+  const link = `${appUrl}/reset-password?token=${token}&email=${encodeURIComponent(email)}`;
+  await mail(
+    email,
+    "Reset password",
+    `Reset your password:\n\n${link}\n\nToken: ${token}\nExpires in 1 hour.`
+  );
+  return { sent: true };
+}
+
+export async function resetPassword(
+  email: string,
+  token: string,
+  password: string
+): Promise<boolean> {
+  if (!dbRef) throw new Error("Call start() first");
+  const row = await dbRef.getOne(
+    `SELECT * FROM password_resets WHERE email = ? AND token = ?`,
+    [email, token]
+  );
+  if (!row) return false;
+  if (new Date(String(row.expires_at)).getTime() < Date.now()) {
+    await dbRef.run(`DELETE FROM password_resets WHERE email = ?`, [email]);
+    return false;
+  }
+
+  const hash = await hashPassword(password);
+  await dbRef.run(`UPDATE users SET password = ? WHERE email = ?`, [hash, email]);
+  await dbRef.run(`DELETE FROM password_resets WHERE email = ?`, [email]);
+  return true;
+}
+
+export async function sendVerificationEmail(user: AuthUser): Promise<void> {
+  if (!dbRef) return;
+  const token = randomToken();
+  const expires = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+  await dbRef.run(`DELETE FROM password_resets WHERE email = ? AND token LIKE 'verify:%'`, [
+    user.email,
+  ]);
+  await dbRef.insert("password_resets", {
+    email: user.email,
+    token: `verify:${token}`,
+    expires_at: expires,
+  });
+
+  const appUrl = appConfig("APP_URL") || "http://localhost:3333";
+  const link = `${appUrl}/api/auth/verify-email?token=${token}&email=${encodeURIComponent(user.email)}`;
+  await mail(
+    user.email,
+    "Verify your email",
+    `Verify your email:\n\n${link}\n\nOr POST /api/auth/verify-email with { email, token }`
+  );
+}
+
+export async function verifyEmail(email: string, token: string): Promise<boolean> {
+  if (!dbRef) throw new Error("Call start() first");
+  const row = await dbRef.getOne(
+    `SELECT * FROM password_resets WHERE email = ? AND token = ?`,
+    [email, `verify:${token}`]
+  );
+  if (!row) return false;
+  if (new Date(String(row.expires_at)).getTime() < Date.now()) return false;
+
+  await dbRef.run(`UPDATE users SET email_verified_at = ? WHERE email = ?`, [
+    new Date().toISOString(),
+    email,
+  ]);
+  await dbRef.run(`DELETE FROM password_resets WHERE email = ? AND token = ?`, [
+    email,
+    `verify:${token}`,
+  ]);
+  return true;
+}
+
+export async function resendVerification(email: string): Promise<boolean> {
+  if (!dbRef) return false;
+  const row = await dbRef.getOne("SELECT * FROM users WHERE email = ?", [email]);
+  if (!row) return false;
+  if (row.email_verified_at) return true;
+  await sendVerificationEmail(toUser(row));
+  return true;
+}

package/packages/auth/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  setupAuth,
+  register,
+  login,
+  signToken,
+  verifyToken,
+  userFromRequest,
+  hasRole,
+  seedAdmin,
+  forgotPassword,
+  resetPassword,
+  sendVerificationEmail,
+  verifyEmail,
+  resendVerification,
+  type AuthUser,
+  type AuthConfig,
+} from "./auth.js";