bro-framework 2.4.2 → 2.4.3

package/README.md

@@ -35,6 +35,7 @@
 - [Architecture & Request Lifecycle](#architecture--request-lifecycle)
 - [Tech Stack Breakdown](#tech-stack-breakdown)
 - [CLI Reference](#cli-reference)
+- [Next.js App Router Integration](#nextjs-app-router-integration)
 - [Author & License](#author--license)
 
 ---
@@ -309,9 +310,36 @@ For Redis-backed integration tests without an external Redis server, install `io
 | `bro init` | Automated workspace scaffolder. Generates configuration files and forcefully ensures your `package.json` respects `"type": "module"`. |
 | `bro sdk` | Route parser and browser client compiler. Generates your typed `bro-sdk.js` frontend SDK in one hit. |
 
+## Next.js App Router Integration
+
+You can natively use `bro.js` syntax, Zod validation, and Authentication inside your Next.js API routes (`app/api/.../route.ts`)!
+
+First, create your factory instance (e.g., `lib/bro.ts`):
+```typescript
+import { createBro } from 'bro-framework/next';
+
+export const { defineRoute, z } = createBro({
+  auth: { apiKey: process.env.API_KEY }
+});
+```
+
+Then use it seamlessly in your route files:
+```typescript
+import { defineRoute, z } from '@/lib/bro';
+
+export const POST = defineRoute({
+  body: z.object({ name: z.string() }),
+  handler: async ({ body }) => {
+    return { success: true, hello: body.name };
+  }
+});
+```
+
+> **Capabilities & Limitations**: Because Next.js API routes are "Serverless" (meaning they sleep when not actively processing a request), features that require a constantly running server such as **WebSockets**, **Background Tasks (Cron)**, **Rate Limiting**, and **Auto-generated Docs** are strictly limited to the standalone `bro.js` framework and are not available in the Next.js adapter.
+
 ---
 
 ## Author & License
 
-- **Author**: Yessin (@medyass1ne)
+- **Author**: Yass1n (@medyass1ne)
 - **License**: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bro-framework",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "The No-BS Backend Framework for Node.js",
   "repository": {
     "type": "git",
@@ -15,7 +15,15 @@
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.js",
       "default": "./src/index.js"
+    },
+    "./next": {
+      "types": "./src/next.d.ts",
+      "import": "./src/next.js",
+      "require": "./src/next.js",
+      "default": "./src/next.js"
     }
   },
   "bin": {

package/src/next.d.ts

@@ -0,0 +1,61 @@
+import { z, ZodTypeAny } from 'zod';
+
+export { z };
+
+export interface UploadedFile {
+  name: string;
+  type: string;
+  size: number;
+  arrayBuffer: () => Promise<ArrayBuffer>;
+  stream: () => ReadableStream;
+  text: () => Promise<string>;
+}
+
+export interface NextBroGlobalConfig<TDb = any> {
+  locale?: any;
+  redisUrl?: string;
+  auth?: {
+    jwtSecret?: string;
+    apiKey?: string | string[];
+  };
+  db?: TDb | Promise<TDb> | (() => TDb | Promise<TDb>) | { init: () => TDb | Promise<TDb> };
+}
+
+export interface NextRouteContext<TBody = any, TQuery = any, TParams = any, TDb = any> {
+  req: Request;
+  env: Record<string, string | undefined>;
+  db: TDb;
+  redis: any;
+  io: { emit: (event: string, data: any) => void };
+  body: TBody extends ZodTypeAny ? z.infer<TBody> : any;
+  query: TQuery extends ZodTypeAny ? z.infer<TQuery> : any;
+  params: TParams extends ZodTypeAny ? z.infer<TParams> : any;
+  file?: UploadedFile;
+  files?: Record<string, UploadedFile[]>;
+  locale: string;
+  t: (key: string, values?: any) => string;
+  user?: any;
+  jwt: { sign: (payload: any, opts?: any) => string };
+  error: (status: number, message: string) => never;
+}
+
+export interface NextRouteConfig<TBody = any, TQuery = any, TParams = any, TDb = any> {
+  auth?: boolean | string[] | 'api-key' | string;
+  body?: TBody;
+  query?: TQuery;
+  params?: TParams;
+  handler: (ctx: NextRouteContext<TBody, TQuery, TParams, TDb>) => Promise<any> | any;
+}
+
+export interface BroNextInstance<TDb = any> {
+  z: typeof z;
+  defineRoute: <
+    TBody extends ZodTypeAny = any,
+    TQuery extends ZodTypeAny = any,
+    TParams extends ZodTypeAny = any
+  >(
+    config: NextRouteConfig<TBody, TQuery, TParams, TDb>
+  ) => (req: Request | any, context: any) => Promise<any>;
+}
+
+export declare function createBro<TDb = any>(config?: NextBroGlobalConfig<TDb>): BroNextInstance<TDb>;

package/src/next.js

@@ -0,0 +1,211 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { verifyJwt, signJwt } from './auth.js';
+import { createClient } from 'redis';
+
+export function createBro(globalConfig = {}) {
+  let isInitialized = false;
+  let initPromise = null;
+
+  let globalDb = null;
+  let globalRedis = null;
+  let globalLocale = null;
+
+  async function ensureInitialized() {
+    if (isInitialized) return;
+    if (initPromise) return initPromise;
+
+    initPromise = (async () => {
+      try {
+        // Locale Dummy or Real
+        if (globalConfig.locale && typeof globalConfig.locale.resolveLocale === 'function') {
+          globalLocale = globalConfig.locale;
+        } else {
+          globalLocale = {
+            resolveLocale: () => 'en',
+            translate: (locale, key) => key
+          };
+        }
+
+        // DB
+        if (typeof globalConfig.db === 'function') {
+          globalDb = await globalConfig.db();
+        } else if (globalConfig.db && typeof globalConfig.db.init === 'function') {
+          globalDb = await globalConfig.db.init();
+        } else if (globalConfig.db) {
+          globalDb = globalConfig.db;
+          if (globalDb instanceof Promise) globalDb = await globalDb;
+        }
+
+        // Redis
+        if (globalConfig.redisUrl) {
+          globalRedis = createClient({ url: globalConfig.redisUrl });
+          globalRedis.on('error', (err) => console.error('[bro.js/next] Redis Error:', err));
+          if (globalRedis.status === 'wait' || !globalRedis.status) {
+             await globalRedis.connect().catch(err => {
+                if (!err.message.includes('already connecting') && !err.message.includes('already connected')) {
+                  throw err;
+                }
+             });
+          }
+        }
+
+        isInitialized = true;
+      } catch (err) {
+        console.error('[bro.js/next] Initialization Error:', err);
+        throw err;
+      }
+    })();
+
+    return initPromise;
+  }
+
+  const errorHelper = (status, message) => {
+    const err = new Error(message);
+    err.status = status;
+    throw err;
+  };
+
+  function defineRoute(config) {
+    return async function (req, context) {
+      try {
+        await ensureInitialized();
+
+        const rawParams = context?.params ? await context.params : {};
+        
+        const url = new URL(req.url);
+        const rawQuery = Object.fromEntries(url.searchParams.entries());
+        
+        let rawBody = {};
+        const parsedFiles = {};
+        let totalFiles = 0;
+        
+        if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
+          const contentType = req.headers.get('content-type') || '';
+          
+          if (contentType.includes('multipart/form-data')) {
+             try {
+                const formData = await req.formData();
+                for (const [key, value] of formData.entries()) {
+                   if (value instanceof File || value instanceof Blob) {
+                      if (!parsedFiles[key]) parsedFiles[key] = [];
+                      parsedFiles[key].push(value);
+                      totalFiles++;
+                   } else {
+                      rawBody[key] = value;
+                   }
+                }
+             } catch (err) {}
+          } else {
+            try {
+              rawBody = await req.json();
+            } catch (err) {}
+          }
+        }
+
+        let body, params, query;
+        try {
+          if (config.body) body = await config.body.parseAsync(rawBody);
+          if (config.params) params = await config.params.parseAsync(rawParams);
+          if (config.query) query = await config.query.parseAsync(rawQuery);
+        } catch (err) {
+          if (err instanceof z.ZodError) {
+            return NextResponse.json(
+              { error: 'Validation Error', issues: err.issues },
+              { status: 400 }
+            );
+          }
+          throw err;
+        }
+
+        let user = null;
+        if (config.auth) {
+          if (config.auth === 'api-key') {
+            const apiKey = req.headers.get('x-api-key') || req.headers.get('authorization')?.replace('Bearer ', '');
+            const configuredKey = globalConfig?.auth?.apiKey || process.env.API_KEY;
+            
+            let isValid = false;
+            if (configuredKey) {
+              const keys = (Array.isArray(configuredKey) ? configuredKey : configuredKey.split(',')).map(k => String(k).trim());
+              isValid = keys.includes(apiKey);
+            }
+            
+            if (!isValid) {
+              return NextResponse.json({ error: 'Unauthorized', details: 'Missing or invalid API key' }, { status: 401 });
+            }
+          } else {
+            const authHeader = req.headers.get('authorization');
+            if (!authHeader || !authHeader.startsWith('Bearer ')) {
+              return NextResponse.json({ error: 'Unauthorized', details: 'Missing Bearer token' }, { status: 401 });
+            }
+            
+            const token = authHeader.split(' ')[1];
+            const secret = globalConfig?.auth?.jwtSecret || process.env.JWT_SECRET;
+            
+            if (!secret) {
+               return NextResponse.json({ error: 'Internal Server Error', details: 'JWT_SECRET is not configured' }, { status: 500 });
+            }
+            
+            const decoded = verifyJwt(token, secret);
+            if (!decoded.valid) {
+              return NextResponse.json({ error: 'Unauthorized', details: decoded.error }, { status: 401 });
+            }
+            
+            user = decoded.payload;
+            
+            if (Array.isArray(config.auth) && config.auth.length > 0) {
+              if (!user.role || !config.auth.includes(user.role)) {
+                return NextResponse.json({ error: 'Forbidden', details: 'Insufficient permissions' }, { status: 403 });
+              }
+            }
+          }
+        }
+
+        const resolvedLocale = globalLocale.resolveLocale({ headers: Object.fromEntries(req.headers.entries()) });
+        
+        let ctxFile = undefined;
+        let ctxFiles = undefined;
+        if (totalFiles === 1) {
+          const keys = Object.keys(parsedFiles);
+          ctxFile = parsedFiles[keys[0]][0];
+          ctxFiles = parsedFiles;
+        } else if (totalFiles > 1) {
+          ctxFiles = parsedFiles;
+        }
+
+        const ctx = {
+          req,
+          env: process.env,
+          db: globalDb,
+          redis: globalRedis,
+          io: { emit: () => console.warn('[bro.js/next] WebSockets require standard bro.js server.') },
+          body,
+          params,
+          query,
+          file: ctxFile,
+          files: ctxFiles,
+          locale: resolvedLocale,
+          t: (key, values) => globalLocale.translate(resolvedLocale, key, values),
+          user,
+          jwt: { sign: (payload, opts) => signJwt(payload, globalConfig?.auth?.jwtSecret || process.env.JWT_SECRET, opts) },
+          error: errorHelper
+        };
+
+        const result = await config.handler(ctx);
+        return NextResponse.json(result, { status: 200 });
+
+      } catch (error) {
+        if (error.status) {
+           return NextResponse.json({ error: error.message }, { status: error.status });
+        }
+        console.error('[bro.js/next] Unhandled Error:', error);
+        return NextResponse.json(
+          { error: 'Internal Server Error', message: error.message },
+          { status: 500 }
+        );
+      }
+    };
+  }
+
+  return { defineRoute, z };
+}