@seip/blue-bird 0.4.7 → 0.4.8

package/AGENTS.md

@@ -123,19 +123,57 @@ routerApi.post("/users", validateUser.middleware(), (req, res) => {
 
 ## 4. Authentication (Auth)
 
-The system includes built-in JWT handling. The framework assumes tokens are passed via Cookies or the `Authorization` header.
+The system includes built-in JWT handling with AES-256-GCM encryption. The framework handles tokens via Cookies or the `Authorization` header.
+
+### Protecting Routes
+Use `Auth.protect()` as a middleware to secure routes.
 
 ```javascript
 import Auth from "@seip/blue-bird/core/auth.js";
 
 // Protect an API route (returns 401 if failed):
 router.get("/profile", Auth.protect(), (req, res) => {
-    // The user payload is attached to req.user
+    // The decrypted user payload is attached to req.user
     res.json({ user: req.user });
 });
 
 // Protect a React route (redirects to login):
 router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => { ... });
+
+// Custom cookie key and storage key:
+router.get("/admin", Auth.protect({ 
+    cookieKey: "admin_session", 
+    key: "admin" 
+}), (req, res) => {
+    res.json({ admin: req.admin });
+});
+```
+
+### Login and Logout
+The `Auth` class provides helpers to handle session management via cookies.
+
+```javascript
+// Login a user
+router.post("/login", async (req, res) => {
+    const user = { id: 1, name: "John" };
+    
+    // Generates JWT and sets "auth" cookie (24h default)
+    await Auth.login(res, user);
+    
+    res.json({ message: "Logged in" });
+});
+
+// Logout a user
+router.post("/logout", async (req, res) => {
+    await Auth.logout(res);
+    res.json({ message: "Logged out" });
+});
+
+// Customizing Login (key, expiration, cookie options)
+await Auth.login(res, user, "my_session", {
+    expiresIn: "7d",
+    cookie: { httpOnly: true, secure: true }
+});
 ```
 
 ## 5. Performance Coaching (Cache)

package/backend/index.js

@@ -2,12 +2,31 @@ import App from "@seip/blue-bird/core/app.js";
 import routerApiExample from "./routes/api.js";
 import routerFrontendExample from "./routes/frontend.js";
 
+/**
+ * Main entry point for the Blue Bird application.
+ * Initializes the App instance with routes, configuration, and starts the server.
+ */
 const app = new App({
+  /**
+   * Array of router instances to be registered in the application.
+   * Each router can have its own base path.
+   */
   routes: [routerApiExample, routerFrontendExample],
+
+  /** CORS configuration. If empty, uses default settings. */
   cors: [],
+
+  /** Global middlewares to be applied before routes. */
   middlewares: [],
+
+  /** Base host URL for the application. */
   host: "http://localhost",
+
+  /** Server port, defaults to environment variable or fallback in config. */
   port: process.env.PORT,
 });
 
+/**
+ * Starts the application server.
+ */
 app.run();

package/backend/routes/api.js

@@ -1,8 +1,11 @@
 import Router from "@seip/blue-bird/core/router.js";
 import Validator from "@seip/blue-bird/core/validate.js";
+import Cache from "@seip/blue-bird/core/cache.js";
+import Auth from "@seip/blue-bird/core/auth.js"
 
 const routerApiExample = new Router("/api");
 
+/* simple test route */
 routerApiExample.get("/users", (req, res) => {
   const users = [
     {
@@ -16,7 +19,10 @@ routerApiExample.get("/users", (req, res) => {
   ];
   res.json(users);
 });
+/* End simple test route */
 
+
+/* Validation example */
 const loginSchema = {
   email: { required: true, email: true },
   password: { required: true, min: 6 },
@@ -27,5 +33,43 @@ const loginValidator = new Validator(loginSchema);
 routerApiExample.post("/login", loginValidator.middleware(), (req, res) => {
   res.json({ message: "Login successful", body: req.body });
 });
+/* End Validation example */
+
+/* Cache example */
+routerApiExample.get("/cache", Cache.middleware(), async (req, res) => {
+  //in debug =false , testing /api/cache should take 2 seconds , and after that should take 0 seconds 
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  res.json({ message: "Cache successful" });
+})
+/* End Cache example */
+
+/* Auth example */
+routerApiExample.get("/auth_generate", async (req, res) => {
+  const token = await Auth.login(res, { id: 1, name: "John Doe" })
+  /*Or use 
+  const token = Auth.generateToken({ id: user.id });//to generate token
+   res.cookie("auth", token,{
+    maxAge: 24 * 60 * 60 * 1000,
+    httpOnly: true,
+    secure: production,
+    sameSite: "strict",
+    path: "/",
+  });
+  */
+  res.json({ message: "Auth successful", token });
+
+})
+
+routerApiExample.get("/auth_logout", async (req, res) => {
+  await Auth.logout(res)
+  res.json({ message: "Auth successful" });
+})
+
+routerApiExample.get("/auth_verify", Auth.protect(), (req, res) => {
+  // req.user has inject with the jwt token payload and decoded by the Auth.protect() middleware
+  const userInfo = req.user
+  res.json({ message: "Auth successful", user: userInfo });
+})
+/* End Auth example */
 
 export default routerApiExample;

package/backend/routes/frontend.js

@@ -6,36 +6,42 @@ import seoData from "./seo.js";
 const routerFrontendExample = new Router();
 routerFrontendExample.use(App.helmet()); // Helmet for frontend router
 
+/* Render HTML frontend/landing.html */
 routerFrontendExample.get("/landing", (req, res) => {
   return Template.renderHtml(res, "landing", {
-    metaTags:{
-      titleMeta:"Landing Example",
+    metaTags: {
+      titleMeta: "Landing Example",
       descriptionMeta: "Description meta",
       keywordsMeta: "keywordsMeta"
     }
   });
 });
+/* End Render HTML frontend/landing.html */
 
+/* SEO example */
 routerFrontendExample.seo(
   [
     {
       path: "/",
       component: "Home",
-      seoKey: "home",
-      props: { id: 1, name: "Name" },
+      seoKey: "home",//key in seo.js data
+      props: { id: 1, name: "Name" },// Props pass to react component or 
     },
     {
       path: "/about",
       component: "About",
-      seoKey: "about",
+      seoKey: "about",//key in seo.js data 
       props: { id: 2, name: "Name 2" },
     },
   ],
   { languages: ["en", "es"], defaultLanguage: "en", seoData },
 );
+/* End SEO example */
 
+/* Render React example for '*' route (catch all routes) */
 routerFrontendExample.get("*", (req, res) => {
   return Template.renderReact(res, "App");
 });
+/* End Render React example */
 
 export default routerFrontendExample;

package/core/auth.js

@@ -1,6 +1,10 @@
 import jwt from "jsonwebtoken";
 import crypto from "node:crypto";
+import Config from "./config.js";
 
+const propsConfig = Config.props();
+const jwtSecret = propsConfig.jwtSecret;
+const production = propsConfig.debug;
 /**
  * Auth class to handle JWT generation, verification and protection with AES-256-GCM encryption.
  */
@@ -49,13 +53,13 @@ class Auth {
   /**
    * Generates an encrypted JWT token.
    * @param {Object} payload - The data to store in the token.
-   * @param {string} [secret=process.env.JWT_SECRET] - The secret key.
+   * @param {string} [secret=process.env.JWT_SECRET] - The secret key .
    * @param {string} [expiresIn="24h"] - Expiration time.
    * @returns {string} The generated token.
    */
   static generateToken(
     payload,
-    secret = process.env.JWT_SECRET,
+    secret = jwtSecret,
     expiresIn = "24h"
   ) {
     if (!secret)
@@ -70,7 +74,7 @@ class Auth {
    * @param {string} [secret=process.env.JWT_SECRET] - The secret key.
    * @returns {Object|null} The decoded and decrypted payload or null if invalid.
    */
-  static verifyToken(token, secret = process.env.JWT_SECRET) {
+  static verifyToken(token, secret = jwtSecret) {
     if (!secret)
       throw new Error("FATAL: JWT_SECRET environment variable is not defined.");
     try {
@@ -84,30 +88,42 @@ class Auth {
 
   /**
    * Middleware to protect routes. Checks for token in Cookies or Authorization header.
-   * @param {Object} options - Options for protection.
+   * @param {Object} [options={}] - Options for protection.
    * @param {string} [options.redirect=null] - URL to redirect if not authenticated.
    * @param {string} [options.key="user"] - Key to store the decoded token in the request.
+   * @param {string} [options.cookieKey="auth"] - The cookie key to look for the token.
    * @returns {Function} Express middleware.
+   * @example
+   * router.get("/profile", Auth.protect(), (req, res) => { ... });
+   * // Or with custom cookie key:
+   * router.get("/admin", Auth.protect({ cookieKey: "admin_session" }), (req, res) => { ... });
    */
-  static protect(options = { redirect: null, key: "user" }) {
+  static protect(options = {}) {
+    const { redirect = null, key = "user", cookieKey = "auth" } = options;
+
     return (req, res, next) => {
       const token =
-        req.cookies?.auth || req.headers.authorization?.split(" ")[1];
+        req.cookies?.[cookieKey] || req.headers.authorization?.split(" ")[1];
 
-      const isContentTypeJson = req.headers["content-type"] === "application/json";
+      const isContentTypeJson =
+        req.headers["content-type"] === "application/json";
 
       if (!token) {
-        if (options.redirect && !isContentTypeJson) return res.redirect(options.redirect);
-        return isContentTypeJson ? res.status(401).json({ message: "Unauthorized" }) : res.status(401).send();
+        if (redirect && !isContentTypeJson) return res.redirect(redirect);
+        return isContentTypeJson
+          ? res.status(401).json({ message: "Unauthorized" })
+          : res.status(401).send();
       }
 
       const decoded = this.verifyToken(token);
       if (!decoded) {
-        if (options.redirect && !isContentTypeJson) return res.redirect(options.redirect);
-        return isContentTypeJson ? res.status(401).json({ message: "Unauthorized" }) : res.status(401).send();
+        if (redirect && !isContentTypeJson) return res.redirect(redirect);
+        return isContentTypeJson
+          ? res.status(401).json({ message: "Unauthorized" })
+          : res.status(401).send();
       }
 
-      req[options.key || "user"] = decoded;
+      req[key || "user"] = decoded;
       next();
     };
   }
@@ -117,12 +133,29 @@ class Auth {
    * @param {import('express').Response} res - The response object.
    * @param {Object} data - The data to store in the token.
    * @param {string} [key="auth"] - The key for the cookie.
-   * @param {Object} [options={cookie: {maxAge: 60 * 60 * 1000, httpOnly: true, secure: true, sameSite: "strict"}}] - Options for the cookie.
-   * @returns {string} The generated token.
+   * @param {Object} [options={}] - Options for the cookie and token.
+   * @param {string} [options.expiresIn="24h"] - Token expiration (e.g., "1h", "7d").
+   * @param {import('express').CookieOptions} [options.cookie] - Express cookie options.
+   * @returns {Promise<string>} The generated token.
+   * @example
+   * await Auth.login(res, { id: 1, name: "Admin" });
    */
-  static login(res, data, key = "auth", options = { cookie: { maxAge: 60 * 60 * 1000, httpOnly: true, secure: true, sameSite: "strict" } }) {
-    const token = this.generateToken(data);
-    res.cookie(key, token, options.cookie);
+  static async login(res, data, key = "auth", options = {}) {
+    const { expiresIn = "24h", cookie = {} } = options;
+
+    const token = this.generateToken(data, jwtSecret, expiresIn);
+
+    const defaultCookieOptions = {
+      maxAge: 24 * 60 * 60 * 1000,
+      httpOnly: true,
+      secure: production,
+      sameSite: "strict",
+      path: "/",
+    };
+
+    const finalCookieOptions = { ...defaultCookieOptions, ...cookie };
+
+    res.cookie(key, token, finalCookieOptions);
     return token;
   }
 
@@ -130,11 +163,16 @@ class Auth {
    * Logs out a user by clearing the authentication cookie.
    * @param {import('express').Response} res - The response object.
    * @param {string} [key="auth"] - The key for the cookie.
-   * @param {Object} [options={cookie: {maxAge: 60 * 60 * 1000, httpOnly: true, secure: true, sameSite: "strict"}}] - Options for the cookie.
-   * @returns {boolean} True if the cookie was cleared successfully.
+   * @param {import('express').CookieOptions} [options={}] - Options for clearing the cookie.
+   * @returns {Promise<boolean>} True if the cookie was cleared successfully.
+   * @example
+   * await Auth.logout(res);
    */
-  static logout(res, key = "auth", options = { cookie: { maxAge: 60 * 60 * 1000, httpOnly: true, secure: true, sameSite: "strict" } }) {
-    res.clearCookie(key, options.cookie);
+  static async logout(res, key = "auth", options = {}) {
+    const defaultOptions = {
+      path: "/",
+    };
+    res.clearCookie(key, { ...defaultOptions, ...options });
     return true;
   }
 }

package/core/cache.js

@@ -9,37 +9,40 @@ setInterval(() => {
     }
 }, 300000).unref();
 /**
- * Cache Middleware
- * @example 
- * router.get("/stats",
-    Cache.middleware(120),
-    controller.stats
-);
- * */
+ * Simple in-memory Cache class to provide middleware for Express routes.
+ * Caches JSON responses based on the request URL.
+ */
 class Cache {
-
-    static middleware(seconds = 60) {
-        return (req, res, next) => {
-
-            const key = req.originalUrl;
-
-            if (CACHE[key] && CACHE[key].expiry > Date.now()) {
-                return res.json(CACHE[key].data);
-            }
-
-            const originalJson = res.json.bind(res);
-
-            res.json = (body) => {
-                CACHE[key] = {
-                    data: body,
-                    expiry: Date.now() + seconds * 1000
-                };
-                return originalJson(body);
-            };
-
-            next();
+  /**
+   * Middleware to cache responses.
+   * @param {number} [seconds=60] - Number of seconds to cache the response.
+   * @returns {Function} Express middleware function.
+   * @example
+   * router.get("/stats", Cache.middleware(120), (req, res) => {
+   *     res.json({ ok: true });
+   * });
+   */
+  static middleware(seconds = 60) {
+    return (req, res, next) => {
+      const key = req.originalUrl;
+
+      if (CACHE[key] && CACHE[key].expiry > Date.now()) {
+        return res.json(CACHE[key].data);
+      }
+
+      const originalJson = res.json.bind(res);
+
+      res.json = (body) => {
+        CACHE[key] = {
+          data: body,
+          expiry: Date.now() + seconds * 1000,
         };
-    }
+        return originalJson(body);
+      };
+
+      next();
+    };
+  }
 }
 
 export default Cache;

package/core/config.js

@@ -40,6 +40,7 @@ class Config {
       host: process.env.HOST || "http://localhost",
       appUrl: process.env.APP_URL || process.env.HOST || "http://localhost",
       port: Number.isNaN(portRaw) ? 3000 : portRaw,
+      jwtSecret: process.env.JWT_SECRET,
       static: {
         path: process.env.STATIC_PATH || "frontend/public",
         options: {},

package/frontend/resources/js/App.jsx

@@ -30,12 +30,10 @@ function generateRoutes(routes, languages = []) {
   const allRoutes = [];
 
   routes.forEach(({ path: routePath, element }) => {
-    // Base path
     allRoutes.push(
       <Route key={routePath} path={routePath} element={element} />
     );
 
-    // Language-prefixed paths (only if multiple languages are used)
     if (languages && languages.length > 0) {
       languages.forEach((lang) => {
         const langPath = `/${lang}${routePath === "/" ? "" : routePath}`;
@@ -56,7 +54,7 @@ export default function App(_props) {
     <ThemeProvider>
       <LanguageProvider initialLang={lang}>
         <Router>
-          <SPAProvider languages={LANGUAGES} defaultLanguage={DEFAULT_LANGUAGE}>
+          <SPAProvider languages={LANGUAGES} defaultLanguage={DEFAULT_LANGUAGE} {..._props} >
             <Suspense fallback={<Skeleton />}>
               <Routes>
                 {generateRoutes(ROUTES, LANGUAGES)}

package/frontend/resources/js/blue-bird/contexts/SPAContext.jsx

@@ -28,7 +28,7 @@ const SPAContext = createContext({
  * @param {Array<string>} [props.languages=[]] - Supported language codes.
  * @param {string} [props.defaultLanguage="en"] - Default language.
  */
-export function SPAProvider({
+export function SPAProvider({ props,
   children,
   languages = [],
   defaultLanguage = "en",
@@ -36,7 +36,7 @@ export function SPAProvider({
   const location = useLocation();
   const navigate = useNavigate();
   const { lang, setLang } = useLanguage();
-  const [pageProps, setPageProps] = useState({});
+  const [pageProps, setPageProps] = useState(props);
   const [pageMeta, setPageMeta] = useState({});
   const [loading, setLoading] = useState(false);
   const isFirstRender = useRef(true);
@@ -136,7 +136,6 @@ export function SPAProvider({
       }
     });
 
-    // Update OG tags
     const ogUpdates = {
       "og:title": meta.titleMeta,
       "og:description": meta.descriptionMeta,
@@ -153,21 +152,21 @@ export function SPAProvider({
   }, []);
 
   useEffect(() => {
-    // Sync language from URL prefix if present
     const urlLang = detectLangFromPath(location.pathname);
     if (urlLang) {
       setLang(urlLang);
     } else if (languages.length > 0 && !isFirstRender.current) {
-      // On subsequent navigations, if prefix is missing, revert to default
       setLang(defaultLanguage);
     }
 
-    // Skip fetch on initial render
     if (isFirstRender.current) {
       isFirstRender.current = false;
       return;
     }
 
+    setPageProps({});
+    setPageMeta({});
+
     if (abortRef.current) {
       abortRef.current.abort();
     }

package/frontend/resources/js/pages/About.jsx

@@ -4,9 +4,13 @@ import { useLanguage } from '../blue-bird/contexts/LanguageContext';
 
 import Card from '../blue-bird/components/Card';
 import Typography from '../blue-bird/components/Typography'
+import { useSPA } from '../blue-bird/contexts/SPAContext.jsx';
 
 export default function About() {
   const { t } = useLanguage();
+  const { navigateToLang, pageProps, pageMeta } = useSPA();
+  console.log("pageProps", pageProps);
+  console.log("pageMeta", pageMeta);
   return (
     <div
       className="bg-white dark:bg-slate-900 text-gray-900 dark:text-gray-100 min-h-screen"

package/frontend/resources/js/pages/Home.jsx

@@ -3,11 +3,16 @@ import Card from '../blue-bird/components/Card';
 import Header from '../components/Header';
 import { useLanguage } from '../blue-bird/contexts/LanguageContext';
 import Typography from '../blue-bird/components/Typography';
+import { useSPA } from '../blue-bird/contexts/SPAContext.jsx';
 
 export default function Home() {
   const { t } = useLanguage();
+  const { navigateToLang, pageProps, pageMeta } = useSPA();
+  console.log("pageProps", pageProps);
+  console.log("pageMeta", pageMeta);
+
   useEffect(() => {
-    // Example API call to the backend
+
     fetch("/api/login", {
       method: "POST",
       headers: {

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@seip/blue-bird",
-  "version": "0.4.7",
-  "description": "Express + React opinionated framework with SPA or API architecture and built-in JWT auth",
-  "type": "module",
-  "bin": {
-    "blue-bird": "core/cli/init.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/seip25/Blue-bird.git"
-  },
-  "keywords": [
-    "express",
-    "react",
-    "framework",
-    "vite"
-  ],
-  "author": "Seip25",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/seip25/Blue-bird/issues"
-  },
-  "homepage": "https://seip25.github.io/Blue-bird/",
-  "scripts": {
-    "dev": "node --watch --env-file=.env backend/index.js",
-    "start": "node --env-file=.env backend/index.js",
-    "create-react-app": "node core/cli/react.js",
-    "react": "node core/cli/react.js",
-    "init": "node core/cli/init.js",
-    "route": "node core/cli/route.js",
-    "component": "node core/cli/component.js",
-    "swagger-install": "node core/cli/swagger.js",
-    "vite:dev": "vite",
-    "vite:build": "vite build"
-  },
-  "dependencies": {
-    "@tailwindcss/vite": "^4.2.2",
-    "chalk": "^5.6.2",
-    "compression": "^1.8.1",
-    "cookie-parser": "^1.4.7",
-    "cors": "^2.8.6",
-    "express": "^5.2.1",
-    "express-rate-limit": "^8.2.1",
-    "helmet": "^8.1.0",
-    "jsonwebtoken": "^9.0.2",
-    "multer": "^2.0.2",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "react-router-dom": "^7.2.0",
-    "tailwindcss": "^4.2.2",
-    "xss": "^1.0.15"
-  },
-  "devDependencies": {
-    "@vitejs/plugin-react": "^4.3.4",
-    "vite": "^7.3.1"
-  }
+{
+  "name": "@seip/blue-bird",
+  "version": "0.4.8",
+  "description": "Express + React opinionated framework with SPA or API architecture and built-in JWT auth",
+  "type": "module",
+  "bin": {
+    "blue-bird": "core/cli/init.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seip25/Blue-bird.git"
+  },
+  "keywords": [
+    "express",
+    "react",
+    "framework",
+    "vite"
+  ],
+  "author": "Seip25",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/seip25/Blue-bird/issues"
+  },
+  "homepage": "https://seip25.github.io/Blue-bird/",
+  "scripts": {
+    "dev": "node --watch --env-file=.env backend/index.js",
+    "start": "node --env-file=.env backend/index.js",
+    "create-react-app": "node core/cli/react.js",
+    "react": "node core/cli/react.js",
+    "init": "node core/cli/init.js",
+    "route": "node core/cli/route.js",
+    "component": "node core/cli/component.js",
+    "swagger-install": "node core/cli/swagger.js",
+    "vite:dev": "vite",
+    "vite:build": "vite build"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.2.2",
+    "chalk": "^5.6.2",
+    "compression": "^1.8.1",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.2.1",
+    "helmet": "^8.1.0",
+    "jsonwebtoken": "^9.0.2",
+    "multer": "^2.0.2",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router-dom": "^7.2.0",
+    "tailwindcss": "^4.2.2",
+    "xss": "^1.0.15"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^7.3.1"
+  }
 }