@seip/blue-bird 0.4.3

package/.env_example

@@ -0,0 +1,26 @@
+DEBUG=true
+DESCRIPTION_META="Example description meta"
+KEYWORDS_META="Example keywords meta"
+TITLE_META="Blue Bird"
+AUTHOR_META="Blue Bird"
+DESCRIPTION="Description project"
+TITLE="Blue Bird"
+VERSION="1.0.0"
+LANGMETA="en"
+HOST="http://localhost"
+PORT=3000
+STATIC_PATH="frontend/public"
+JWT_SECRET="JWT_SECRET"
+
+# Database Configuration 
+# SQLite (Default)
+#Remove this line if you are not going to use sqlite
+DATABASE_URL="file:./dev.db"
+
+# MySQL
+#Remove this line if you are not going to use Mysql
+#DATABASE_URL="mysql://root:@localhost:3306/blue_bird"
+
+# PostgreSQL
+#Remove this line if you are not going to use PostgreSQL
+# DATABASE_URL="postgresql://root:@localhost:5432/blue_bird?schema=public"

package/AGENTS.md

@@ -0,0 +1,199 @@
+# Blue Bird Framework - AI Agent Guide
+
+This document serves as the primary manual for any AI Agent interacting with the codebase. It details the architecture of Blue Bird, its internal modules, and how features should be written or modified.
+
+## 1. Core Architecture
+
+Blue Bird is a full-stack framework built on **Express (Backend)** and **React + Vite (Frontend)**. It is designed to save developers from repetitive configuration, packing validation, security, authentication (JWT), and multi-language support (i18n) out of the box.
+
+- **Backend (`backend/`)**: Initializes the server using `App` from `core/app.js` and invokes routing from `backend/routes/`.
+- **Frontend (`frontend/`)**: A React SPA handled by Vite. Default components and assets live in `frontend/resources/js/`.
+- **Core (`core/`)**: The framework core. Contains wrapper classes such as `Router`, `Validator`, `Template`, `Auth`, `Cache`, etc. **DO NOT MODIFY** the core unless explicitly requested, as it could break other apps.
+
+## 2. Routing (Router)
+
+Do not use Express' native router (`express.Router()`). Always use Blue Bird's `Router` wrapper.
+
+```javascript
+import Router from "@seip/blue-bird/core/router.js";
+
+const routerApi = new Router("/api");
+
+routerApi.get("/users", (req, res) => {
+  res.json({ users: [] });
+});
+
+export default routerApi;
+```
+
+**For the Frontend (React Rendering / SEO):**
+Blue Bird injects the SPA using its `Template` class.
+
+```javascript
+import Template from "@seip/blue-bird/core/template.js";
+
+// Render the entire App (SPA fallback)
+router.get("*", (req, res) => {
+  return Template.renderReact(res, "App", { title: "App Title" });
+});
+
+// SEO Routing (Meta tag SSR before React mounts)
+// Automatically registers /sitemap.xml, /robots.txt, and language-prefixed routes
+
+// Option A: Simple meta (no i18n)
+router.seo([
+  {
+    path: "/",
+    component: "Home",
+    meta: { titleMeta: "Home", descriptionMeta: "Welcome" },
+    props: { id: 1 }
+  }
+]);
+
+// Option B: Multilingual with external seoData file (recommended)
+import seoData from "./seo.js";
+router.seo([
+  { path: "/", component: "Home", seoKey: "home", props: { id: 1 } },
+  { path: "/about", component: "About", seoKey: "about" }
+], { languages: ["en", "es"], defaultLanguage: "en", seoData });
+// Generates: /, /en, /es, /about, /en/about, /es/about
+
+// Option C: Multilingual inline meta
+router.seo([
+  {
+    path: "/",
+    component: "Home",
+    meta: {
+      en: { titleMeta: "Home", descriptionMeta: "Welcome" },
+      es: { titleMeta: "Inicio", descriptionMeta: "Bienvenido" }
+    }
+  }
+], { languages: ["en", "es"], defaultLanguage: "en" });
+```
+
+**Advanced SEO Features:**
+- **SPA Navigation:** When `?source=frontend` is detected, `renderReact` returns JSON `{meta, props, component, lang}` instead of HTML.
+- **Automatic Sitemap:** Dynamic `sitemap.xml` with all language-prefixed routes.
+- **Robots.txt:** Auto-served pointing to the generated sitemap.
+- **Caching:** SEO templates are cached in memory for high performance.
+- **External SEO Data:** Use a `seo.js` file (like PHP's `seo.php`) for centralized multilingual meta management.
+
+**Static & Hybrid Rendering (renderHtml):**
+For ultra-fast pages (Landing, Privacy, Terms) that don't initially need React, use `Template.renderHtml`. It fallbacks to `.env` SEO values automatically.
+
+```javascript
+router.get("/", (req, res) => {
+  // Uses frontend/landing.html as base
+  return Template.renderHtml(res, "landing", { withAssets: false });
+});
+```
+
+**Strategy: Controlled Collision**
+You can use the same path for a static server page and a React route.
+1. **Initial Load:** Express serves a static, cached HTML (instant LCP).
+2. **Post-Mount:** React Router takes over. Navigation to `/` can then show a different component (like Login) without a full reload.
+
+
+
+## 3. Data Validation (Validator)
+
+Incoming request data must be validated using `core/validate.js`, which automatically returns HTTP 400 multilingual JSON responses on error.
+
+```javascript
+import Validator from "@seip/blue-bird/core/validate.js";
+
+const userSchema = {
+  email: { required: true, email: true },
+  password: { required: true, min: 8 },
+  bio: { required: false }, // *XSS mitigation is applied to all strings by default!
+};
+
+// If you need raw HTML without sanitization, disable XSS explicitly.
+const postSchema = {
+  contentHtml: { required: true, xss: false },
+};
+
+const validateUser = new Validator(userSchema, "en");
+
+routerApi.post("/users", validateUser.middleware(), (req, res) => {
+  // Reaching here means data is safe and valid
+  res.json({ success: true });
+});
+```
+
+## 4. Authentication (Auth)
+
+The system includes built-in JWT handling. The framework assumes tokens are passed via Cookies or the `Authorization` header.
+
+```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
+    res.json({ user: req.user });
+});
+
+// Protect a React route (redirects to login):
+router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => { ... });
+```
+
+## 5. Performance Coaching (Cache)
+
+If a route involves heavy processing or repetitive DB queries, utilize the in-memory `Cache` middleware.
+
+```javascript
+import Cache from "@seip/blue-bird/core/cache.js";
+
+// Cache this response for 60 seconds
+router.get("/stats", Cache.middleware(60), (req, res) => {
+  // Only executed once every 60s
+  res.json({ ok: true });
+});
+```
+
+## 6. Security (Helmet)
+
+Helmet is **not applied globally** by default. Apply it per-router where needed:
+
+```javascript
+import App from "@seip/blue-bird/core/app.js";
+
+// Apply helmet to a specific router
+const webRouter = new Router("/web");
+webRouter.use(App.helmet()); // Full helmet with defaults
+webRouter.use(App.helmet({ contentSecurityPolicy: false })); // Custom options
+
+// Or enable globally in App constructor (not recommended)
+new App({ helmet: true });
+```
+
+## 7. SPA Navigation (SPAProvider)
+
+The framework includes an `SPAProvider` that bridges React Router navigation with backend SEO data.
+On every client-side `<Link>` navigation, it fetches meta/props from the backend and updates `document.title` + meta tags.
+
+```javascript
+// In App.jsx — already configured by default
+import { SPAProvider } from './blue-bird/contexts/SPAContext.jsx';
+
+<SPAProvider languages={["en", "es"]} defaultLanguage="en">
+  <Routes>...</Routes>
+</SPAProvider>
+
+// In components — use navigateToLang for language switching
+import { useSPA } from './blue-bird/contexts/SPAContext.jsx';
+const { navigateToLang, pageProps, pageMeta } = useSPA();
+navigateToLang("es"); // Navigates to /es/current-path and updates meta
+```
+
+## 8. AI Development Guidelines
+
+1. **Frontend**: Components must be Functional React components, leveraging Tailwind CSS. Avoid inline styles. Reuse components from `blue-bird/components/` (e.g., Card, Button, Input) if available.
+2. **JSON Responses**: API endpoints should return standardized responses formatted as `{ message: "..." }` or `{ data: ... }`.
+3. **i18n**: Check the `useLanguage` hook provided in React for multi-language components; avoid hardcoding display strings when localization is active.
+4. **Magic Imports**: Stick to pure relative imports or well-configured aliases (imports natively resolve from `@seip/blue-bird/...` or relative directories like `../../`).
+5. **SPA Navigation**: Use `<Link>` from `react-router-dom` for internal navigation. The `SPAProvider` automatically fetches and updates meta tags.
+6. **Language Routes**: When using multilingual SEO, routes are generated for all language prefixes. Use `navigateToLang()` from `useSPA()` to switch languages.
+
+_This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._

package/README.md

@@ -0,0 +1,79 @@
+# Blue Bird Framework
+
+**The Future of Express & React Development**
+
+![Blue Bird Logo](https://seip25.github.io/Blue-bird/blue-bird.png)
+
+[![npm version](https://img.shields.io/npm/v/@seip/blue-bird.svg)](https://www.npmjs.com/package/@seip/blue-bird)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+## 🌟 Introduction / Introducción
+
+**Blue Bird** is a powerful, opinionated structure based on **Express** and **React**. It's designed to help developers build fast, scalable applications,apis and everything pre-configured.
+
+**Blue Bird** es una estructura potente basada en **Express** y **React**. Está diseñada para ayudar a los desarrolladores a construir aplicaciones rápidas ,apis escalables   y todo pre-configurado.
+
+ 
+
+## 🚀 Key Features / Características Clave
+
+- ⚡ **All-In-One**: Express, React, Vite, JWT Auth, and Validations ready to go.
+- 💎 **Flexible**: Extensible via standard Express `.use()` middleware. 
+- 🔐 **Secure**: Integrated JWT authentication and multi-language validation.
+- 📁 **Uploads**: Easy file handling with Multer-based helpers.
+
+ 
+
+## 🛠️ Quick Start / Inicio Rápido
+
+### 1. Installation / Instalación
+```bash
+npm install @seip/blue-bird
+```
+
+### 2. Initialize / Inicializar
+```bash
+npx blue-bird
+```
+*This copies the base structure: `backend`, `frontend`, and `.env`.*
+*Esto copia la estructura base: `backend`, `frontend` y `.env`.*
+
+### 3. Setup React
+```bash
+npm run react
+```
+*Configures React, React Router, and Vite automatically.*
+*Configura React, React Router y Vite automáticamente.*
+
+### 4. Development / Desarrollo
+```bash
+# Start Backend (Express)
+npm run dev
+
+# Start Frontend (Vite)
+npm run vite:dev
+```
+
+<hr />
+
+## 📖 Documentation / Documentación
+
+Check out our full documentation for detailed API reference and examples:
+
+- 🇺🇸 [English Documentation](https://seip25.github.io/Blue-bird/en.html)
+- 🇪🇸 [Documentación en Español](https://seip25.github.io/Blue-bird/index.html)
+
+<hr />
+
+## 📄 License / Licencia
+
+Distributed under the **MIT License**. See `LICENSE` for more information.
+
+Distribuido bajo la **Licencia MIT**. Mira `LICENSE` para más información.
+
+<hr />
+
+<div align="center">
+  <p>Made with ❤️ by <strong>Seip25</strong></p>
+</div>

package/backend/index.js

@@ -0,0 +1,13 @@
+import App from "../core/app.js";
+import routerApiExample from "./routes/api.js";
+import routerFrontendExample from "./routes/frontend.js";
+
+const app = new App({
+  routes: [routerApiExample, routerFrontendExample],
+  cors: [],
+  middlewares: [],
+  host: "http://localhost",
+  port: process.env.PORT,
+});
+
+app.run();

package/backend/routes/api.js

@@ -0,0 +1,31 @@
+import Router from "../../core/router.js";
+import Validator from "../../core/validate.js";
+
+const routerApiExample = new Router("/api");
+
+routerApiExample.get("/users", (req, res) => {
+  const users = [
+    {
+      name: "John Doe",
+      email: "john.doe@example.com",
+    },
+    {
+      name: "Jane Doe2",
+      email: "jane.doe2@example.com",
+    },
+  ];
+  res.json(users);
+});
+
+const loginSchema = {
+  email: { required: true, email: true },
+  password: { required: true, min: 6 },
+};
+
+const loginValidator = new Validator(loginSchema);
+
+routerApiExample.post("/login", loginValidator.middleware(), (req, res) => {
+  res.json({ message: "Login successful", body: req.body });
+});
+
+export default routerApiExample;

package/backend/routes/frontend.js

@@ -0,0 +1,41 @@
+import Router from "../../core/router.js";
+import Template from "../../core/template.js";
+import App from "../../core/app.js";
+import seoData from "./seo.js";
+
+const routerFrontendExample = new Router();
+routerFrontendExample.use(App.helmet()); // Helmet for frontend router
+
+routerFrontendExample.get("/landing", (req, res) => {
+  return Template.renderHtml(res, "landing", {
+    metaTags:{
+      titleMeta:"Landing Example",
+      descriptionMeta: "Description meta",
+      keywordsMeta: "keywordsMeta"
+    }
+  });
+});
+
+routerFrontendExample.seo(
+  [
+    {
+      path: "/",
+      component: "Home",
+      seoKey: "home",
+      props: { id: 1, name: "Name" },
+    },
+    {
+      path: "/about",
+      component: "About",
+      seoKey: "about",
+      props: { id: 2, name: "Name 2" },
+    },
+  ],
+  { languages: ["en", "es"], defaultLanguage: "en", seoData },
+);
+
+routerFrontendExample.get("*", (req, res) => {
+  return Template.renderReact(res, "App");
+});
+
+export default routerFrontendExample;

package/backend/routes/seo.js

@@ -0,0 +1,39 @@
+/**
+ * SEO Data File
+ * Define multilingual SEO metadata for each route.
+ * Used with router.seo() via the seoData option.
+ *
+ * Structure: { seoKey: { lang: { titleMeta, descriptionMeta, keywordsMeta } } }
+ *
+ * @example
+ * import seoData from "./seo.js";
+ * router.seo([
+ *   { path: "/", component: "Home", seoKey: "home" }
+ * ], { languages: ["en", "es"], defaultLanguage: "en", seoData });
+ */
+export default {
+  home: {
+    en: {
+      titleMeta: "Home - Blue Bird",
+      descriptionMeta: "Welcome to Blue Bird Framework",
+      keywordsMeta: "blue bird, framework, express, react",
+    },
+    es: {
+      titleMeta: "Inicio - Blue Bird",
+      descriptionMeta: "Bienvenido al Framework Blue Bird",
+      keywordsMeta: "blue bird, framework, express, react",
+    },
+  },
+  about: {
+    en: {
+      titleMeta: "About - Blue Bird",
+      descriptionMeta: "About Blue Bird Framework",
+      keywordsMeta: "about, blue bird, framework",
+    },
+    es: {
+      titleMeta: "Acerca - Blue Bird",
+      descriptionMeta: "Acerca del Framework Blue Bird",
+      keywordsMeta: "acerca, blue bird, framework",
+    },
+  },
+};