balda-js 0.0.1 → 0.0.3

package/docs/docs/plugins/cookie.md

@@ -1,424 +0,0 @@
----
-sidebar_position: 5
----
-
-# Cookie Plugin
-
-The Cookie plugin provides comprehensive cookie parsing and management for your Balda.js application. It automatically parses incoming cookies and provides convenient methods for setting and clearing cookies on responses.
-
-## Features
-
-- **Automatic Cookie Parsing**: Parses cookies from incoming requests
-- **Cookie Setting**: Easy methods to set cookies on responses
-- **Cookie Signing**: Optional cookie signing for security
-- **Flexible Configuration**: Customizable defaults and options
-- **Security Features**: HttpOnly, Secure, SameSite support
-
-## Basic Configuration
-
-### Simple Setup
-
-```typescript
-import { Server } from 'balda-js';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cookie: {
-      secret: 'your-secret-key'
-    }
-  }
-});
-```
-
-### Development Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cookie: {
-      secret: 'dev-secret-key',
-      defaults: {
-        httpOnly: true,
-        secure: false,
-        sameSite: 'Lax'
-      }
-    }
-  }
-});
-```
-
-## Configuration Options
-
-### Basic Options
-
-```typescript
-cookie: {
-  secret: 'your-secret-key',     // Required for signed cookies
-  parse: true,                   // Enable cookie parsing (default: true)
-  sign: false,                   // Enable cookie signing (default: false)
-  defaults: {
-    path: '/',                   // Cookie path (default: '/')
-    httpOnly: true,              // HttpOnly flag (default: true)
-    secure: false,               // Secure flag (default: false)
-    sameSite: 'Lax'             // SameSite attribute (default: 'Lax')
-  }
-}
-```
-
-### Production Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cookie: {
-      secret: process.env.COOKIE_SECRET,
-      sign: true,
-      defaults: {
-        httpOnly: true,
-        secure: true, // HTTPS only
-        sameSite: 'Strict',
-        domain: '.myapp.com'
-      }
-    }
-  }
-});
-```
-
-## Usage Examples
-
-### Basic Cookie Operations
-
-```typescript
-@controller('/auth')
-export class AuthController {
-  @post('/login')
-  async login(req: Request, res: Response) {
-    const { username, password } = req.body;
-
-    // Validate credentials
-    const user = await validateUser(username, password);
-
-    if (user) {
-      // Set session cookie
-      res.cookie('sessionId', user.sessionId, {
-        maxAge: 24 * 60 * 60 * 1000, // 24 hours
-        httpOnly: true,
-        secure: true
-      });
-
-      res.json({ message: 'Login successful' });
-    } else {
-      res.unauthorized({ error: 'Invalid credentials' });
-    }
-  }
-
-  @post('/logout')
-  async logout(req: Request, res: Response) {
-    // Clear session cookie
-    res.clearCookie('sessionId');
-    res.json({ message: 'Logout successful' });
-  }
-}
-```
-
-### Reading Cookies
-
-```typescript
-@controller('/api')
-export class ApiController {
-  @get('/profile')
-  async getProfile(req: Request, res: Response) {
-    // Access parsed cookies
-    const sessionId = req.cookies.sessionId;
-    const theme = req.cookies.theme || 'light';
-    const language = req.cookies.language || 'en';
-
-    if (!sessionId) {
-      return res.unauthorized({ error: 'No session found' });
-    }
-
-    const user = await getUserBySession(sessionId);
-    res.json({ user, theme, language });
-  }
-}
-```
-
-### Setting Multiple Cookies
-
-```typescript
-@post('/preferences')
-async updatePreferences(req: Request, res: Response) {
-  const { theme, language } = req.body;
-
-  // Set multiple cookies
-  res.cookie('theme', theme, {
-    maxAge: 365 * 24 * 60 * 60 * 1000, // 1 year
-    httpOnly: false // Allow JavaScript access
-  });
-
-  res.cookie('language', language, {
-    maxAge: 365 * 24 * 60 * 60 * 1000,
-    httpOnly: false
-  });
-
-  res.json({ message: 'Preferences updated' });
-}
-```
-
-### Signed Cookies
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cookie: {
-      secret: 'your-secret-key',
-      sign: true,
-      defaults: {
-        httpOnly: true,
-        secure: true
-      }
-    }
-  }
-});
-
-@controller('/secure')
-export class SecureController {
-  @post('/set-secure-cookie')
-  async setSecureCookie(req: Request, res: Response) {
-    // Set signed cookie
-    res.cookie('secureData', 'sensitive-information', {
-      signed: true,
-      maxAge: 60 * 60 * 1000 // 1 hour
-    });
-
-    res.json({ message: 'Secure cookie set' });
-  }
-
-  @get('/read-secure-cookie')
-  async readSecureCookie(req: Request, res: Response) {
-    // Read signed cookie
-    const secureData = req.cookies.secureData;
-
-    if (secureData) {
-      res.json({ data: secureData });
-    } else {
-      res.json({ error: 'No secure data found' });
-    }
-  }
-}
-```
-
-## Cookie Options
-
-### Domain Configuration
-
-```typescript
-// Set cookie for specific domain
-res.cookie('sessionId', 'value', {
-  domain: '.myapp.com' // Available on all subdomains
-});
-
-// Set cookie for current domain only
-res.cookie('sessionId', 'value', {
-  domain: 'api.myapp.com' // Only on this subdomain
-});
-```
-
-### Path Configuration
-
-```typescript
-// Set cookie for specific path
-res.cookie('adminToken', 'value', {
-  path: '/admin' // Only available on /admin routes
-});
-
-// Set cookie for entire site
-res.cookie('sessionId', 'value', {
-  path: '/' // Available everywhere
-});
-```
-
-### Expiration Options
-
-```typescript
-// Expire at specific date
-res.cookie('sessionId', 'value', {
-  expires: new Date('2024-12-31')
-});
-
-// Expire after specific time
-res.cookie('sessionId', 'value', {
-  maxAge: 24 * 60 * 60 * 1000 // 24 hours
-});
-
-// Session cookie (expires when browser closes)
-res.cookie('sessionId', 'value', {
-  // No expires or maxAge
-});
-```
-
-### Security Options
-
-```typescript
-// Secure cookie (HTTPS only)
-res.cookie('sessionId', 'value', {
-  secure: true,
-  httpOnly: true,
-  sameSite: 'Strict'
-});
-
-// Cross-site cookie
-res.cookie('trackingId', 'value', {
-  secure: true,
-  sameSite: 'None' // Requires secure: true
-});
-```
-
-## SameSite Configuration
-
-### SameSite Options
-
-```typescript
-// Strict - only same site
-res.cookie('sessionId', 'value', {
-  sameSite: 'Strict'
-});
-
-// Lax - same site + top-level navigation
-res.cookie('sessionId', 'value', {
-  sameSite: 'Lax'
-});
-
-// None - cross-site (requires secure: true)
-res.cookie('trackingId', 'value', {
-  sameSite: 'None',
-  secure: true
-});
-```
-
-## Environment-Based Configuration
-
-### Development vs Production
-
-```typescript
-const isProduction = process.env.NODE_ENV === 'production';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cookie: {
-      secret: process.env.COOKIE_SECRET,
-      sign: isProduction,
-      defaults: {
-        httpOnly: true,
-        secure: isProduction, // HTTPS only in production
-        sameSite: isProduction ? 'Strict' : 'Lax',
-        domain: isProduction ? '.myapp.com' : undefined
-      }
-    }
-  }
-});
-```
-
-## Error Handling
-
-### Invalid Signed Cookies
-
-```typescript
-@get('/verify-cookie')
-async verifyCookie(req: Request, res: Response) {
-  const signedCookie = req.cookies.secureData;
-
-  if (!signedCookie) {
-    return res.unauthorized({ error: 'No signed cookie found' });
-  }
-
-  // The cookie plugin automatically verifies signed cookies
-  // If verification fails, the cookie won't be available
-  res.json({ verified: true, data: signedCookie });
-}
-```
-
-## Integration Examples
-
-### With Authentication
-
-```typescript
-@controller('/auth')
-export class AuthController {
-  @post('/login')
-  async login(req: Request, res: Response) {
-    const { username, password } = req.body;
-
-    const user = await authenticateUser(username, password);
-
-    if (user) {
-      // Set authentication cookies
-      res.cookie('authToken', user.token, {
-        httpOnly: true,
-        secure: true,
-        sameSite: 'Strict',
-        maxAge: 24 * 60 * 60 * 1000
-      });
-
-      res.cookie('userId', user.id.toString(), {
-        httpOnly: true,
-        secure: true,
-        sameSite: 'Strict',
-        maxAge: 24 * 60 * 60 * 1000
-      });
-
-      res.json({ message: 'Login successful' });
-    } else {
-      res.unauthorized({ error: 'Invalid credentials' });
-    }
-  }
-
-  @post('/logout')
-  async logout(req: Request, res: Response) {
-    // Clear all authentication cookies
-    res.clearCookie('authToken');
-    res.clearCookie('userId');
-
-    res.json({ message: 'Logout successful' });
-  }
-}
-```
-
-### With Session Management
-
-```typescript
-@controller('/session')
-export class SessionController {
-  @post('/create')
-  async createSession(req: Request, res: Response) {
-    const sessionId = generateSessionId();
-
-    res.cookie('sessionId', sessionId, {
-      httpOnly: true,
-      secure: true,
-      sameSite: 'Strict',
-      maxAge: 30 * 24 * 60 * 60 * 1000 // 30 days
-    });
-
-    await createSession(sessionId, req.body);
-    res.json({ sessionId });
-  }
-
-  @get('/data')
-  async getSessionData(req: Request, res: Response) {
-    const sessionId = req.cookies.sessionId;
-
-    if (!sessionId) {
-      return res.unauthorized({ error: 'No session found' });
-    }
-
-    const sessionData = await getSession(sessionId);
-    res.json(sessionData);
-  }
-}
-```

package/docs/docs/plugins/cors.md

@@ -1,295 +0,0 @@
----
-sidebar_position: 2
----
-
-# CORS Plugin
-
-The CORS (Cross-Origin Resource Sharing) plugin enables cross-origin requests in your Balda.js application. It handles preflight requests and sets appropriate CORS headers for both simple and complex requests.
-
-## Features
-
-- **Automatic Preflight Handling**: Automatically handles OPTIONS requests
-- **Flexible Origin Configuration**: Support for strings, arrays, and regex patterns
-- **Customizable Headers**: Configurable allowed and exposed headers
-- **Credentials Support**: Enable/disable credentials for cross-origin requests
-- **Method Control**: Specify allowed HTTP methods
-
-## Basic Configuration
-
-### Simple Setup
-
-```typescript
-import { Server } from 'balda-js';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cors: {
-      origin: '*'
-    }
-  }
-});
-```
-
-### Development Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cors: {
-      origin: ['http://localhost:3000', 'http://localhost:3001'],
-      credentials: true,
-      methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
-      allowedHeaders: ['Content-Type', 'Authorization']
-    }
-  }
-});
-```
-
-## Configuration Options
-
-### Origin Configuration
-
-```typescript
-// Allow all origins (not recommended for production)
-cors: {
-  origin: '*'
-}
-
-// Allow specific origins
-cors: {
-  origin: ['https://myapp.com', 'https://admin.myapp.com']
-}
-
-// Allow origins with regex patterns
-cors: {
-  origin: [
-    'https://myapp.com',
-    /^https:\/\/.*\.myapp\.com$/
-  ]
-}
-
-// Function-based origin validation
-cors: {
-  origin: (origin) => {
-    const allowedOrigins = ['https://myapp.com', 'https://admin.myapp.com'];
-    return allowedOrigins.includes(origin);
-  }
-}
-```
-
-### Methods Configuration
-
-```typescript
-// Default methods (GET, HEAD, PUT, PATCH, POST, DELETE)
-cors: {
-  methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
-}
-
-// Custom methods
-cors: {
-  methods: ['GET', 'POST', 'PUT', 'DELETE']
-}
-
-// String format
-cors: {
-  methods: 'GET,POST,PUT,DELETE'
-}
-```
-
-### Headers Configuration
-
-```typescript
-// Allow specific headers
-cors: {
-  allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key']
-}
-
-// Allow all headers
-cors: {
-  allowedHeaders: '*'
-}
-
-// Expose headers to the client
-cors: {
-  exposedHeaders: ['X-Total-Count', 'X-Page-Count']
-}
-```
-
-### Advanced Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cors: {
-      origin: ['https://myapp.com', 'https://admin.myapp.com'],
-      methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
-      allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key'],
-      exposedHeaders: ['X-Total-Count', 'X-Page-Count'],
-      credentials: true,
-      maxAge: 86400, // 24 hours
-      preflightContinue: false,
-      optionsSuccessStatus: 204
-    }
-  }
-});
-```
-
-## Environment-Based Configuration
-
-```typescript
-const isProduction = process.env.NODE_ENV === 'production';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cors: {
-      origin: isProduction
-        ? ['https://myapp.com']
-        : ['http://localhost:3000', 'http://localhost:3001'],
-      credentials: isProduction,
-      maxAge: isProduction ? 86400 : undefined
-    }
-  }
-});
-```
-
-## Route-Level CORS
-
-You can also apply CORS middleware to specific routes:
-
-```typescript
-import { cors } from 'balda-js';
-
-@controller('/api')
-export class ApiController {
-  @get('/public', {
-    middleware: [cors({ origin: '*' })]
-  })
-  async publicEndpoint(req: Request, res: Response) {
-    res.json({ message: 'Public endpoint' });
-  }
-
-  @get('/private', {
-    middleware: [cors({
-      origin: ['https://myapp.com'],
-      credentials: true
-    })]
-  })
-  async privateEndpoint(req: Request, res: Response) {
-    res.json({ message: 'Private endpoint' });
-  }
-}
-```
-
-## CORS Headers Explained
-
-### Request Headers
-
-- **Origin**: The origin of the request (set by browser)
-- **Access-Control-Request-Method**: The HTTP method for the actual request
-- **Access-Control-Request-Headers**: The headers for the actual request
-
-### Response Headers
-
-- **Access-Control-Allow-Origin**: Which origins are allowed
-- **Access-Control-Allow-Methods**: Which HTTP methods are allowed
-- **Access-Control-Allow-Headers**: Which headers are allowed
-- **Access-Control-Expose-Headers**: Which headers are exposed to the client
-- **Access-Control-Allow-Credentials**: Whether credentials are allowed
-- **Access-Control-Max-Age**: How long preflight results can be cached
-
-## Preflight Requests
-
-CORS automatically handles preflight OPTIONS requests:
-
-```typescript
-// This OPTIONS request is handled automatically
-// OPTIONS /api/users
-// Origin: https://myapp.com
-// Access-Control-Request-Method: POST
-// Access-Control-Request-Headers: Content-Type, Authorization
-
-// Response:
-// Access-Control-Allow-Origin: https://myapp.com
-// Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH
-// Access-Control-Allow-Headers: Content-Type, Authorization
-// Access-Control-Max-Age: 86400
-```
-
-## Security Considerations
-
-### Production Configuration
-
-```typescript
-// Secure production configuration
-cors: {
-  origin: ['https://myapp.com'], // Specific origins only
-  credentials: true,
-  methods: ['GET', 'POST', 'PUT', 'DELETE'],
-  allowedHeaders: ['Content-Type', 'Authorization'],
-  maxAge: 86400
-}
-```
-
-### Development vs Production
-
-```typescript
-const corsConfig = process.env.NODE_ENV === 'production'
-  ? {
-      origin: ['https://myapp.com'],
-      credentials: true,
-      maxAge: 86400
-    }
-  : {
-      origin: ['http://localhost:3000'],
-      credentials: false
-    };
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cors: corsConfig
-  }
-});
-```
-
-## Common Issues and Solutions
-
-### Credentials with Wildcard Origin
-
-```typescript
-// ❌ This won't work - credentials require specific origins
-cors: {
-  origin: '*',
-  credentials: true
-}
-
-// ✅ This works - specific origins with credentials
-cors: {
-  origin: ['https://myapp.com'],
-  credentials: true
-}
-```
-
-### Multiple Origins with Credentials
-
-```typescript
-// ✅ Multiple specific origins with credentials
-cors: {
-  origin: ['https://myapp.com', 'https://admin.myapp.com'],
-  credentials: true
-}
-```
-
-### Custom Headers
-
-```typescript
-// ✅ Include custom headers
-cors: {
-  allowedHeaders: ['Content-Type', 'Authorization', 'X-Custom-Header'],
-  exposedHeaders: ['X-Total-Count', 'X-Page-Count']
-}
-```