hightjs 0.2.43 → 0.2.45

package/docs/autenticacao.md

@@ -0,0 +1,212 @@
+# 🔐 Autenticação (HightJS/auth)
+
+Autenticação JWT embutida, fácil de configurar.  
+O jeito recomendado é criar as rotas diretamente no `auth.ts` e importar onde quiser.
+
+## Configuração Básica & Rotas
+
+`src/auth.ts`:
+
+```ts
+import { CredentialsProvider, DiscordProvider, createAuthRoutes } from 'hightjs/auth';
+import type { AuthConfig } from 'hightjs/auth';
+
+export const authConfig: AuthConfig = {
+    providers: [
+        new CredentialsProvider({
+            id: 'credentials',
+            name: 'Credentials',
+            credentials: {
+                username: { label: 'Username', type: 'text', placeholder: 'Digite seu usuário' },
+                password: { label: 'Password', type: 'password', placeholder: 'Digite sua senha' }
+            },
+            async authorize(credentials) {
+                if (credentials.username === 'admin' && credentials.password === 'admin') {
+                    return {
+                        id: '1',
+                        username: 'admin',
+                        email: 'admin@test.com',
+                        name: 'Administrador',
+                        testeeee: 'sdondsfndsfndsfodsfo'
+                    };
+                }
+                return null;
+            }
+        }),
+        new DiscordProvider({
+            clientId: "ID",
+            clientSecret: "TOKEN",
+            callbackUrl: "http://localhost:3000/api/auth/callback/discord",
+            scope: ['identify', 'email', 'guilds'],
+            successUrl: "http://localhost:3000/"
+        })
+    ],
+    session: {
+        strategy: 'jwt',
+        maxAge: 24 * 60 * 60, // 24 horas
+    },
+    pages: {
+        signIn: '/login',
+        signOut: '/'
+    },
+    secret: 'hweb-test-secret-key-change-in-production'
+};
+
+// Cria as rotas de autenticação automaticamente
+export const authRoutes = createAuthRoutes(authConfig);
+```
+
+## Exportando as rotas
+
+`src/web/backend/routes/auth.ts`:
+
+```ts
+import { authRoutes } from "../../../auth";
+export default authRoutes;
+```
+
+## Configurando o Frontend
+
+Para usar autenticação no frontend, você precisa configurar o `SessionProvider` no layout:
+
+`src/web/layout.tsx`:
+
+```tsx
+import { SessionProvider } from 'hightjs/auth/react';
+
+export const metadata = { title: 'Meu App', descrição: 'Descrição global' };
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <SessionProvider>
+      {children}
+    </SessionProvider>
+  );
+}
+```
+
+## Fazendo Login no Frontend
+
+Exemplo de como implementar login com credenciais e Discord:
+
+```tsx
+import { useSession } from 'hightjs/auth/react';
+import React, { useState } from 'react';
+
+function LoginPage() {
+    const { signIn } = useSession();
+    const [username, setUsername] = useState('');
+    const [password, setPassword] = useState('');
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+
+    const handleDiscordLogin = async () => {
+        await signIn('discord', { redirect: true });
+    }
+
+    const handleLogin = async (e: React.FormEvent) => {
+        e.preventDefault();
+        setIsLoading(true);
+        setError(null);
+
+        try {
+            const result = await signIn('credentials', {
+                username: username,
+                password: password,
+                callbackUrl: '/'
+            });
+
+            if (!result || result.error) {
+                setError('Credenciais inválidas. Verifique seus dados e senha.');
+                setIsLoading(false);
+                return;
+            }
+            router.push("/")
+        } catch (err) {
+            setError('Ocorreu um erro inesperado. Tente novamente.');
+            setIsLoading(false);
+        }
+    };
+
+    return (
+        <div>
+            <form onSubmit={handleLogin}>
+                <input
+                    type="text"
+                    value={username}
+                    onChange={(e) => setUsername(e.target.value)}
+                    placeholder="Username"
+                />
+                <input
+                    type="password"
+                    value={password}
+                    onChange={(e) => setPassword(e.target.value)}
+                    placeholder="Password"
+                />
+                <button type="submit" disabled={isLoading}>Login</button>
+            </form>
+
+            <button onClick={handleDiscordLogin}>Login com Discord</button>
+
+            {error && <p style={{color: 'red'}}>{error}</p>}
+        </div>
+    );
+}
+```
+
+## Acessando Dados do Usuário
+
+Para acessar informações do usuário autenticado:
+
+```tsx
+import { useSession } from 'hightjs/auth/react';
+
+function UserProfile() {
+    const { data: session, status, signOut } = useSession();
+
+    if (status === 'loading') return <p>Carregando...</p>;
+
+    if (!session) return <p>Não autenticado</p>;
+
+    return (
+        <div>
+            <h1>Bem-vindo, {session.user?.name}</h1>
+            <p>Email: {session.user?.email}</p>
+            <button onClick={() => signOut()}>Logout</button>
+        </div>
+    );
+}
+```
+
+## Protegendo rotas backend
+
+```ts
+import { HightJSRequest } from "hightjs";
+import { BackendRouteConfig, HightJSResponse } from "hightjs";
+import { authRoutes } from "../../../../auth";
+
+const route: BackendRouteConfig = {
+    pattern: "/api/version",
+    GET: async (req: HightJSRequest, params: any) => {
+        const session = await authRoutes.auth.getSession(req)
+        if (!session) {
+            return HightJSResponse.json({ error: "Unauthorized" }, { status: 401 });
+        }
+        return HightJSResponse.json({
+            version: "1.0.0",
+            name: "HightJS",
+            description: "Um framework web full-stack moderno para Node.js",
+        });
+    }
+}
+export default route;
+```
+
+## Métodos principais
+
+- `signIn()` - Fazer login (credenciais ou provider)
+- `signOut()` - Fazer logout
+- `useSession()` - Hook para acessar sessão no frontend
+- `authRoutes.auth.getSession()` - Verificar sessão no backend
+- `authRoutes.auth.isAuthenticated()` - Verificar se está autenticado
+

package/docs/checklist.md

@@ -0,0 +1,9 @@
+# ✅ Checklist Mental
+
+1. Precisa de página? Crie em `src/web/routes/...`
+2. Precisa de endpoint? Crie em `src/web/backend/routes/...`
+3. Precisa proteger? Use autenticação nas rotas
+4. Precisa middleware? `middleware.ts` ou `middleware: []` na rota
+5. Metadata? `generateMetadata` ou `metadata` no layout
+6. Deploy? `npx hight start`
+

package/docs/cli.md

@@ -0,0 +1,21 @@
+# 🛠️ CLI
+
+Comandos principais:
+
+| Comando            | Descrição                                 |
+|--------------------|-------------------------------------------|
+| `npx hight dev`    | Modo desenvolvimento (hot reload)         |
+| `npx hight start`  | Modo produção (usa build gerado)          |
+
+## Opções
+
+- `--port`      Porta (default 3000)
+- `--hostname`  Host (default 0.0.0.0)
+- `--framework` `native` | `express` | `fastify` (default: native)
+
+## Produção
+
+```bash
+npx hight start -p 8080
+```
+

package/docs/estrutura.md

@@ -0,0 +1,20 @@
+# 📦 Estrutura Recomendada
+
+```
+src/
+  web/
+    layout.tsx              // Layout global (opcional)
+    notFound.tsx            // Página 404 customizada (opcional)
+    routes/
+      index.tsx             // Página inicial "/"
+      about.tsx             // Página "/about"
+      blog.tsx         // Rota dinâmica "/blog/123"
+    backend/
+      routes/
+        middleware.ts       // Middlewares globais da pasta
+        version.ts          // Endpoint "/version"
+        users/
+          middleware.ts     // Middlewares só desse grupo
+          list.ts           // Endpoint "/users/list"
+```
+

package/docs/faq.md

@@ -0,0 +1,10 @@
+# ❓ FAQ Rápido
+
+| Pergunta                       | Resposta                                            |
+|--------------------------------|-----------------------------------------------------|
+| Precisa Next/Vite?             | Não, bundler interno via esbuild.                   |
+| Dá para usar React 19?         | Sim (peer dependency).                              |
+| Tem SSR?                       | Atualmente só client-side hydration.                |
+| Posso usar CSS/SCSS?           | Import normal nos componentes.                      |
+| Rota de API conflita com página?| Não, rotas backend podem ser qualquer path.         |
+

package/docs/hot-reload.md

@@ -0,0 +1,5 @@
+# ♻️ Hot Reload
+
+Em modo dev, o cliente abre WebSocket `/hweb-hotreload/`.  
+Mudanças em rotas frontend ou backend recarregam automaticamente.
+

package/docs/middlewares.md

@@ -0,0 +1,73 @@
+# 🧩 Middlewares
+
+Adicione middlewares:
+
+- Direto na rota: `middleware: [...]`
+- Arquivo `middleware.ts` na pasta (auto-carregado)
+
+## Interface
+
+```ts
+export type HightMiddleware = (
+  request: HightJSRequest,
+  params: { [key: string]: string },
+  next: () => Promise<HightJSResponse>
+) => Promise<HightJSResponse> | HightJSResponse;
+```
+
+## Exemplo por Pasta
+
+`src/web/backend/routes/middleware.ts`:
+
+```ts
+import {HightJSRequest, HightJSResponse} from 'hightjs';
+
+export async function log(
+    request: HightJSRequest,
+    params: { [key: string]: string },
+    next: () => Promise<HightJSResponse>
+): Promise<HightJSResponse> {
+
+    console.log('[API]', request.method, request.url);
+    return next();
+}
+
+
+export async function blockLegacy(
+    request: HightJSRequest,
+    params: { [key: string]: string },
+    next: () => Promise<HightJSResponse>
+): Promise<HightJSResponse> {
+    if (request.header('user-agent')?.includes('IE 8')) {
+        return HightJSResponse.json({ error: 'Navegador não suportado' }, {status: 400});
+    }
+    return next();
+}
+
+export default [log, blockLegacy];
+```
+
+## Exemplo por Rota
+
+```ts
+import {BackendRouteConfig, HightJSRequest, HightJSResponse} from 'hightjs';
+
+async function authCheck(
+    request: HightJSRequest,
+    params: { [key: string]: string },
+    next: () => Promise<HightJSResponse>
+): Promise<HightJSResponse> {
+    if(!request.header("authorization")) {
+        return HightJSResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+    return next();
+}
+
+const route: BackendRouteConfig = {
+    pattern: '/secure/data',
+    middleware: [authCheck],
+    GET: async () => HightJSResponse.json({ secret: true })
+};
+export default route;
+```
+

package/docs/rotas-backend.md

@@ -0,0 +1,45 @@
+# 🌐 Rotas Backend
+
+Qualquer arquivo em `src/web/backend/routes` vira endpoint backend.  
+O _pattern_ pode ser qualquer caminho, não só `/api/...`!
+
+## Exemplo Simples
+
+`src/web/backend/routes/version.ts`:
+
+```ts
+import { HightJSRequest, HightJSResponse, BackendRouteConfig } from 'hightjs';
+
+const route: BackendRouteConfig = {
+  pattern: '/version',
+  GET: async (_req: HightJSRequest) => {
+    return HightJSResponse.json({
+      version: '1.0.0',
+      name: 'HightJS',
+      description: 'Framework web full-stack moderno para Node.js'
+    });
+  }
+};
+export default route;
+```
+
+## Suporte a Métodos
+
+Defina `GET`, `POST`, `PUT`, `DELETE` (ou só os necessários).
+
+## Rotas Dinâmicas Backend
+
+`src/web/backend/routes/users/[id].ts` → `/users/123`
+
+```ts
+import { BackendRouteConfig, HightJSResponse } from "hightjs";
+
+const route: BackendRouteConfig = {
+    pattern: '/users/[id]',
+    GET: async (req, params) => {
+        return HightJSResponse.json({ userId: params.id });
+    }
+};
+export default route;
+```
+

package/docs/rotas-frontend.md

@@ -0,0 +1,66 @@
+# 🖥️ Rotas Frontend
+
+Cada arquivo em `src/web/routes` é uma página.
+
+```tsx
+import { RouteConfig } from 'hightjs/client';
+import React from 'react';
+
+function Component() {
+  return <h1>HELLO WORLD</h1>;
+}
+
+const config: RouteConfig = {
+  pattern: '/thanks2',
+  component: Component,
+  generateMetadata: () => ({ title: 'HightJS | Thanks' })
+};
+export default config;
+```
+
+## Rotas Dinâmicas com Parâmetros
+
+```tsx
+import {RouteConfig} from "hightjs/client";
+import React from "react";
+
+function PostPage({ params }: { params: { id: string } }) {
+    const id = params.id
+    return (
+        <div>
+            <h1>Post ID: {id}</h1>
+            <p>This is the content of post {id}.</p>
+        </div>
+    );
+}
+
+const config: RouteConfig = {
+    pattern: '/post/[id]',
+    component: PostPage,
+    generateMetadata: async (params) => ({ title: `Post ${params.id}` })
+};
+export default config
+
+```
+
+## Layout Global
+
+`src/web/layout.tsx`:
+
+```tsx
+export const metadata = { title: 'Meu App', description: 'Descrição global' };
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return <div>{children}</div>;
+}
+```
+
+## Página 404
+
+`src/web/notFound.tsx`:
+
+```tsx
+export default function NotFound() {
+  return <h1>Página não encontrada</h1>;
+}
+```
+

package/docs/seguranca.md

@@ -0,0 +1,8 @@
+# 🔐 Segurança Interna
+
+- Sanitização de headers, cookies e body
+- Limites de tamanho configuráveis
+- Proteção contra JSON malformado
+- Timeout de requisição / body parser nativo
+- JWT com HS256, verificação constant-time
+

package/docs/websocket.md

@@ -0,0 +1,45 @@
+# 🛜 WebSocket
+
+O HightJS possui suporte nativo a WebSockets nas rotas do backend.
+
+## Exemplo Prático
+
+`src/web/backend/routes/chat.ts`:
+
+```ts
+import {BackendRouteConfig, HightJSResponse} from 'hightjs';
+
+const route: BackendRouteConfig = {
+    pattern: '/api/chat',
+    GET: async () => {
+        return HightJSResponse.json({ message: 'Chat HTTP endpoint' });
+    },
+    WS: (ctx) => {
+        console.log('Nova conexão WebSocket no chat');
+
+        ctx.send({
+            type: 'welcome',
+            message: 'Bem-vindo ao chat!'
+        });
+
+        ctx.ws.on('message', (data) => {
+            const message = JSON.parse(data.toString());
+            console.log(message)
+            // Broadcast para todos exceto o remetente
+            ctx.broadcast({
+                type: 'message',
+                user: message.user,
+                text: message.text,
+                timestamp: new Date().toISOString()
+            });
+        });
+
+        ctx.ws.on('close', () => {
+            console.log('Cliente desconectado');
+        });
+    }
+};
+
+export default route;
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hightjs",
-  "version": "0.2.43",
+  "version": "0.2.45",
   "description": "HightJS is a high-level framework for building web applications with ease and speed. It provides a robust set of tools and features to streamline development and enhance productivity.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",