odac 1.0.1 → 1.2.0

package/docs/backend/10-authentication/07-magic-links.md

@@ -0,0 +1,134 @@
+# Magic Links
+
+Magic links provide a passwordless authentication method where verification links are sent directly to the user's email address. Odac offers both a zero-configuration component and a programmatic API to implement this feature.
+
+## The `<odac:magic-login>` Component
+
+The simplest way to implement magic links is using the built-in view component. This works similarly to the standard `<odac:login>` component but requires no password field.
+
+### Basic Usage
+
+Use the `<odac:magic-login>` tag in your view. If you provide no inner content, Odac will automatically generate a default email input and submit button.
+
+```html
+<odac:magic-login redirect="/dashboard" />
+```
+
+### Attributes
+
+| Attribute | Description | Default |
+|-----------|-------------|---------|
+| `redirect` | URL to redirect to after successful login (Required) | `null` |
+| `email-label` | Label text for the default email field | `"Email Address"` |
+| `submit-text` | Text for the submit button | `"Send Magic Link"` |
+
+### Customized Usage
+
+You can fully customize the form by adding your own inputs and buttons inside the tag.
+
+```html
+<div class="auth-card">
+  <h2>Sign In</h2>
+  <p>We'll send a login link to your email.</p>
+  
+  <odac:magic-login redirect="/dashboard">
+    <div class="form-group">
+        <label for="email">Work Email</label>
+        <odac:input name="email" type="email" placeholder="name@company.com" class="form-control">
+            <odac:validate rule="required|email" message="Please enter a valid work email"/>
+        </odac:input>
+    </div>
+    
+    <odac:submit class="btn btn-primary w-full">Email me a login link</odac:submit>
+  </odac:magic-login>
+</div>
+```
+
+## Backend API
+
+For more complex requirements, such as building a custom API or integrating with other flows, you can use the `Odac.Auth` class directly.
+
+### Requesting a Magic Link
+
+Use `magic` to generate a token and send the email.
+
+```javascript
+// In your controller (e.g., AuthController.js)
+
+async sendLink(req, res) {
+    const email = req.input('email');
+    
+    // Returns { success: boolean, message: string, error?: string }
+    const result = await Odac.Auth.magic(email, {
+        redirect: '/dashboard',       // Redirect after verification
+        subject: 'Log in to MyApp',   // Email subject
+        template: 'auth/magic-link'   // View path for the email template
+    });
+    
+    if (result.success) {
+        return res.json({ message: result.message });
+    } else {
+        return res.status(400).json({ error: result.error });
+    }
+}
+```
+
+### Verification Logic
+
+Odac handles the verification route automatically at `/_odac/magic-verify`. However, if you are building a custom flow, you might interact with the underlying data model directly using `Odac.DB`.
+
+## Configuration
+
+Magic links usage is configured in your `odac.json` file under the `auth` object.
+
+```json
+{
+  "auth": {
+    "table": "users",                   // Table where users are stored
+    "magicTable": "magic_links",        // Table to store tokens (auto-created)
+    "magicLinkRateLimit": 3600000,      // Rate limit window in ms (Default: 1 hour)
+    "magicLinkMaxAttempts": 2,          // Max emails per address per window
+    "magicLinkMaxAttemptsPerIP": 5,     // Max requests per IP per window
+    "magicLinkSessionCooldown": 30000,  // Session cooldown in ms (Default: 30s)
+    "passwordless": true,               // Optimization: Skip generating passwords for new users (Default: false)
+    "passwordField": "password"         // Column name for password (Default: password)
+  }
+}
+```
+
+## Auto-Registration & Passwordless Mode
+ 
+ When a user verifies a magic link:
+ 
+ 1. **Existing User**: They are logged in immediately.
+ 2. **New User**: An account is automatically created for them (Auto-Registration).
+ 
+ By default, Odac attempts to generate a secure random password for new users to satisfy typical database constraints. However, if your application is purely passwordless (e.g. your storage schema doesn't have a `password` column at all), you should set `"passwordless": true` in your config. This optimizes performance by skipping the password generation step.
+ 
+ Even without this setting, Odac is smart enough to retry registration without a password if the database rejects the initial attempt due to a missing password column.
+ 
+ ## Security & Best Practices
+ 
+ 1.  **Rate Limiting**: Odac enforces a 3-layer defense system:
+     *   **Session Cooldown**: immediate cookie-based block for rapid clicks (Default: 30s).
+     *   **IP Limit**: prevents mass attacks from a single source.
+     *   **Email Limit**: prevents spamming a specific user.
+ 2.  **Token Security**: Tokens are hashed in the database (`token_hash`) using secure hashing algorithms. The raw token is only sent to the user's email and never stored.
+ 3.  **One-Time Use**: Tokens are immediately deleted upon successful verification or expiration.
+ 4.  **User Enumeration**: To prevent attackers from checking if an email exists in your system, the `magic` method (and the form) will return a "success" message even if the user does not exist.
+
+## Email Template
+
+If using the default mailer, you can create a custom email template at `views/auth/magic-link.html`. The template receives the following variables:
+
+- `link`: The full verification URL.
+- `network`: The hostname.
+- `ip`: The request IP address.
+
+```html
+<!-- views/auth/magic-link.html -->
+<h1>Login Request</h1>
+<p>Click the link below to log in to {{ network }}:</p>
+<a href="{{ link }}">Login Now</a>
+<p>This link was requested from IP: {{ ip }}</p>
+```

package/docs/backend/11-mail/01-the-mail-service.md

@@ -1,42 +1,132 @@
 ## ✉️ The `Mail` Service
 
-The `Odac.Mail` service is your friendly neighborhood postal worker. It provides a super simple way to send emails using the mail server settings you've already configured in the Odac core.
+The `Odac.Mail` service provides a fluent, chainable interface to send emails. **It is a zero-config service** designed to work exclusively with the **ODAC Core** server. If you are running Odac, the mail service works out of the box without any additional setup.
 
-#### How to Send an Email
+### How to Send an Email
 
-`Odac.Mail.send(to, subject, htmlBody)`
+The `Odac.Mail` class uses a builder pattern. You start by instantiating it with a template name, set various properties, and finally call `send()`.
 
-*   `to`: The email address of the person you're sending it to.
-*   `subject`: The subject line for your email.
-*   `htmlBody`: The main content of your email. You can even use HTML tags to make it look fancy!
+#### Syntax
 
-Just like the database service, `send` is an `async` method, so using it with `async/await` is the way to go.
+```javascript
+await Odac.Mail('template_name')
+  .from('sender@example.com', 'Sender Name')
+  .to('recipient@example.com')
+  .subject('Your Subject Here')
+  .send({
+    variable1: 'value1',
+    variable2: 'value2'
+  });
+```
+
+*   **Template**: The constructor takes the name of the HTML template file located in `view/mail/`.
+*   **Data**: The object passed to `send()` contains key-value pairs that replace `{key}` placeholders in your HTML template.
 
-#### Example: A Simple Contact Form
+#### Example: Contact Form Controller
 
-Let's imagine you have a controller that handles a contact form on your website.
+Here is a complete example of how to use the Mail service inside a controller:
 
 ```javascript
 module.exports = async function (Odac) {
-  const { recipient, subject, message } = Odac.Request.post;
-
-  // It's always a good idea to check your data first!
-  if (!recipient || !subject || !message) {
-    return { error: 'Oops! You missed a required field.' };
-  }
-
-  try {
-    // Let's try to send the email
-    await Odac.Mail.send(recipient, subject, `<p>${message}</p>`);
-
-    // If we get here, it worked!
-    return { success: true, message: 'Email sent successfully!' };
-  } catch (error) {
-    // If something went wrong...
-    console.error('Oh no, the email failed to send:', error);
-    return { error: 'Something went wrong while trying to send the email.' };
-  }
+    const { name, email, message } = Odac.Request.post;
+
+    // 1. Validate Input
+    if (!name || !email || !message) {
+        return { error: 'Please fill in all fields.' };
+    }
+
+    try {
+        // 2. Prepare and Send Email
+        const result = await Odac.Mail('contact_form_notification')
+            .from('system@myapp.com', 'My App System')
+            .to('admin@myapp.com')
+            .subject('New Contact Form Submission')
+            .send({
+                user_name: name,
+                user_email: email,
+                user_message: message,
+                timestamp: new Date().toISOString()
+            });
+
+        // 3. Check Result
+        if (result) {
+            return { success: true, message: 'Thank you! We received your message.' };
+        } else {
+            return { error: 'Failed to send email.' };
+        }
+
+    } catch (e) {
+        console.error(e);
+        return { error: 'An unexpected error occurred.' };
+    }
 }
 ```
 
-And that's all there is to it. You're now a master of email!
+### Template File
+
+Create your HTML template in `view/mail/contact_form_notification.html`:
+
+```html
+<h1>New Contact Message</h1>
+<p><strong>From:</strong> {user_name} ({user_email})</p>
+<p><strong>Time:</strong> {timestamp}</p>
+<hr>
+<p>{user_message}</p>
+```
+
+### Sending Plain Text or Raw HTML (No Template)
+
+You can send emails **without creating a template file** by using the `.text()` or `.html()` methods directly. This is useful for simple notifications or dynamic content.
+
+**Note:** If you provide both a template name AND manual content, the template will take precedence.
+
+#### 1. Plain Text Email
+
+Use the `.text()` method to send a simple, text-only email. The `Content-Type` will automatically be set to `text/plain`.
+
+```javascript
+await Odac.Mail() // No template name required
+  .to('recipient@example.com')
+  .subject('System Alert')
+  .text('Server load is critical. Please check immediately.')
+  .send();
+```
+
+> **Note:** Plain text does not support HTML tags like links (`<a href>`). If you write a URL (e.g., `https://odac.run`), most email clients will automatically make it clickable.
+
+#### 2. Raw HTML Email
+
+Use the `.html()` method to send an HTML email without a file.
+
+```javascript
+await Odac.Mail()
+  .to('user@example.com')
+  .subject('Welcome')
+  .html('<h1>Welcome!</h1><p>Please <a href="https://example.com">click here</a>.</p>')
+  .send();
+```
+
+If you use `.html()`, the system will automatically generate a plain-text version of your email by stripping the tags, just like it does for templates.
+
+### Advanced Usage
+
+#### Custom Headers
+
+You can inject custom headers into the email using the `header()` method:
+
+```javascript
+.header({
+    'X-Custom-Header': 'CustomValue',
+    'Reply-To': 'support@example.com'
+})
+```
+
+#### Chainable Methods
+
+*   `from(email, name)`: Sets the sender.
+*   `to(email)`: Sets the recipient.
+*   `subject(text)`: Sets the subject line.
+*   `text(content)`: Sets the plain text body (used if no template is provided).
+*   `html(content)`: Sets the HTML body (used if no template is provided).
+*   `header(object)`: Merges custom headers.
+*   `send(data)`: Compiles the template with `data`, connects to the Odac Core, and sends the email payload. Returns a `Promise`.

package/docs/backend/12-streaming/01-streaming-overview.md

@@ -91,7 +91,7 @@ module.exports = async (Odac) => {
 // controller/users/get/index.js
 module.exports = async (Odac) => {
   Odac.stream(async function* () {
-    const users = await Odac.Mysql.table('users').get()
+    const users = await Odac.DB.users.get()
     
     for (const user of users) {
       yield user
@@ -194,7 +194,7 @@ module.exports = async (Odac) => {
     let hasMore = true
     
     while (hasMore) {
-      const posts = await Odac.Mysql.table('posts')
+      const posts = await Odac.DB.posts
         .limit(10)
         .offset((page - 1) * 10)
         .get()

package/docs/backend/13-utilities/01-odac-var.md

@@ -313,7 +313,7 @@ module.exports = async function(Odac) {
   const profileSlug = Odac.Var(username).slug()
   
   // Save user
-  await Odac.Mysql.table('users').insert({
+  await Odac.DB.users.insert({
     email: email,
     username: username,
     password: hashedPassword,
@@ -332,7 +332,7 @@ module.exports = async function(Odac) {
   const password = Odac.Request.post('password')
   
   // Find user
-  const user = await Odac.Mysql.table('users')
+  const user = await Odac.DB.users
     .where('email', email)
     .first()
   
@@ -369,19 +369,19 @@ module.exports = async function(Odac) {
   const slug = Odac.Var(title).slug()
   
   // Check if slug exists
-  const exists = await Odac.Mysql.table('posts')
+  const exists = await Odac.DB.posts
     .where('slug', slug)
     .first()
   
   if (exists) {
     // Add timestamp to make unique
     const uniqueSlug = `${slug}-${Date.now()}`
-    await Odac.Mysql.table('posts').insert({
+    await Odac.DB.posts.insert({
       title: title,
       slug: uniqueSlug
     })
   } else {
-    await Odac.Mysql.table('posts').insert({
+    await Odac.DB.posts.insert({
       title: title,
       slug: slug
     })
@@ -464,7 +464,7 @@ module.exports = async function(Odac) {
   const encryptedCard = Odac.Var(creditCard).encrypt()
   
   // Save encrypted data
-  await Odac.Mysql.table('payments').insert({
+  await Odac.DB.payments.insert({
     user_id: Odac.Auth.id(),
     card: encryptedCard
   })
@@ -474,7 +474,7 @@ module.exports = async function(Odac) {
 
 // Later, to retrieve and decrypt
 module.exports = async function(Odac) {
-  const payment = await Odac.Mysql.table('payments')
+  const payment = await Odac.DB.payments
     .where('user_id', Odac.Auth.id())
     .first()
   

package/docs/backend/13-utilities/02-ipc.md

@@ -0,0 +1,73 @@
+# IPC (Inter-Process Communication)
+
+Odac provides a built-in IPC system that allows your application workers to communicate with each other, share data, and sync states. It abstracts the underlying driver, allowing you to switch between in-memory (cluster) and Redis-based communication with a simple configuration change.
+
+## Configuration
+
+To configure the IPC system, update your project configuration. The default driver is `memory`.
+
+```javascript
+// config.js
+module.exports = {
+  // ...
+  database: {
+    // ... other dbs
+    redis: {
+      default: {
+        // node-redis connection options
+        // e.g., url: 'redis://user:pass@host:port'
+      }
+    }
+  },
+  ipc: {
+    driver: 'memory', // Options: 'memory' or 'redis'
+    redis: 'default'  // The name of the redis connection to use (if driver is 'redis')
+  }
+}
+```
+
+### Drivers
+
+- **memory**: Uses Node.js `cluster` IPC. Ideal for single-server deployments. Data is stored in the Main/Primary process RAM and shared across workers via `process.send`.
+- **redis**: Uses a Redis server. Ideal for multi-server/horizontal scaling deployments. Requires a configured Redis connection.
+
+## Usage
+
+You can access the IPC module via `Odac.Ipc`.
+
+### Data Storage (Key-Value)
+
+You can set, get, and delete values. These values are shared across all workers.
+
+```javascript
+// Set a value (with optional TTL in seconds)
+await Odac.Ipc.set('maintenance_mode', true);
+await Odac.Ipc.set('temp_cache', { foo: 'bar' }, 60);
+
+// Get a value
+const isMaintenance = await Odac.Ipc.get('maintenance_mode');
+
+// Delete a value
+await Odac.Ipc.del('maintenance_mode');
+```
+
+> [!NOTE]
+> `get`, `set`, and `del` are asynchronous and return Promises.
+
+### Pub/Sub (Messaging)
+
+You can publish messages to channels and subscribe to them in other workers.
+
+```javascript
+// Subscribe to a channel
+// Best practice: Subscribe in your app initialization or a Service Provider
+await Odac.Ipc.subscribe('chat:global', (message) => {
+  console.log('New chat message:', message);
+});
+
+// Publish a message
+await Odac.Ipc.publish('chat:global', { user: 'Emre', text: 'Hello World' });
+```
+
+> [!TIP]
+> When using `memory` driver, the subscription listener is registered in the current worker. When a message is published, it goes to the Main process and is then broadcasted to all subscribed workers.

package/docs/frontend/01-overview/01-introduction.md

@@ -131,7 +131,11 @@ odac.get('/api/users', function(data) {
 ## Other Utility Functions
 
 -   **`Odac.client()`**: Returns a unique client identifier from a cookie.
--   **`Odac.data()`**: Returns data from the `candy_data` cookie, which is set by the backend. This data includes the current page and the initial CSRF token.
+-   **`Odac.data(key)`**: Returns shared data passed from the backend via `Odac.share`. You can get the full data object or a specific key:
+    ```javascript
+    let allData = odac.data();
+    let user = odac.data('user'); // Returns null if not exists
+    ```
 -   **`Odac.page()`**: Returns the identifier of the current page. This is the controller name (e.g., `'user'`) or view name (e.g., `'dashboard'`) set by the backend. Use this to conditionally run code for specific pages.
 -   **`Odac.storage()`**: A wrapper for `localStorage`.
     ```javascript

package/docs/frontend/02-ajax-navigation/01-quick-start.md

@@ -347,7 +347,7 @@ Odac.action({
 **Page Identifier Rules:**
 - **With controller**: Uses controller filename (e.g., `user.js` → `'user'`)
 - **With view object**: Uses `content` or `all` value (e.g., `{content: 'dashboard'}` → `'dashboard'`)
-- Accessible via `Odac.page()` or `document.documentElement.dataset.candyPage`
+- Accessible via `Odac.page()`
 
 ## Server Variables
 

package/docs/index.json

@@ -1,124 +1,4 @@
 {
-  "server": [
-    {
-      "file": "01-installation",
-      "title": "Installation",
-      "children": [
-        {
-          "file": "01-quick-install.md",
-          "title": "Quick Install"
-        },
-        {
-          "file": "02-manual-installation-via-npm.md",
-          "title": "Manual Installation (via NPM)"
-        }
-      ]
-    },
-    {
-      "file": "02-get-started",
-      "title": "Getting Started",
-      "children": [
-        {
-          "file": "01-core-concepts.md",
-          "title": "Core Concepts"
-        },
-        {
-          "file": "02-basic-commands.md",
-          "title": "Basic Commands"
-        },
-        {
-          "file": "03-cli-reference.md",
-          "title": "CLI Reference"
-        },
-        {
-          "file": "04-cli-quick-reference.md",
-          "title": "CLI Quick Reference"
-        }
-      ]
-    },
-    {
-      "file": "03-service",
-      "title": "Running a Service",
-      "children": [
-        {
-          "file": "01-start-a-new-service.md",
-          "title": "Start a New Service"
-        },
-        {
-          "file": "02-delete-a-service.md",
-          "title": "Delete a Service"
-        }
-      ]
-    },
-    {
-      "file": "04-web",
-      "title": "Managing Websites",
-      "children": [
-        {
-          "file": "01-create-a-website.md",
-          "title": "Create a Website"
-        },
-        {
-          "file": "02-list-websites.md",
-          "title": "List Websites"
-        },
-        {
-          "file": "03-delete-a-website.md",
-          "title": "Delete a Website"
-        }
-      ]
-    },
-    {
-      "file": "05-subdomain",
-      "title": "Managing Subdomains",
-      "children": [
-        {
-          "file": "01-create-a-subdomain.md",
-          "title": "Create a Subdomain"
-        },
-        {
-          "file": "02-list-subdomains.md",
-          "title": "List Subdomains"
-        },
-        {
-          "file": "03-delete-a-subdomain.md",
-          "title": "Delete a Subdomain"
-        }
-      ]
-    },
-    {
-      "file": "06-ssl",
-      "title": "Managing SSL",
-      "children": [
-        {
-          "file": "01-renew-an-ssl-certificate.md",
-          "title": "Renew an SSL Certificate"
-        }
-      ]
-    },
-    {
-      "file": "07-mail",
-      "title": "Managing Mail",
-      "children": [
-        {
-          "file": "01-create-a-mail-account.md",
-          "title": "Create a Mail Account"
-        },
-        {
-          "file": "02-delete-a-mail-account.md",
-          "title": "Delete a Mail Account"
-        },
-        {
-          "file": "03-list-mail-accounts.md",
-          "title": "List Mail Accounts"
-        },
-        {
-          "file": "04-change-account-password.md",
-          "title": "Change Account Password"
-        }
-      ]
-    }
-  ],
   "backend": [
     {
       "file": "01-overview",
@@ -134,7 +14,7 @@
         },
         {
           "file": "03-development-server.md",
-          "title": "Development Server"
+          "title": "CLI Commands & Deployment"
         }
       ]
     },
@@ -321,6 +201,10 @@
         {
           "file": "09-comments.md",
           "title": "Comments"
+        },
+        {
+          "file": "10-styling-and-tailwind.md",
+          "title": "Styling & Tailwind CSS"
         }
       ]
     },
@@ -329,12 +213,20 @@
       "title": "Database",
       "children": [
         {
-          "file": "01-database-connection.md",
-          "title": "Database Connection"
+          "file": "01-getting-started.md",
+          "title": "Getting Started"
+        },
+        {
+          "file": "02-basics.md",
+          "title": "Query Basics"
         },
         {
-          "file": "02-using-mysql.md",
-          "title": "Using MySQL"
+          "file": "03-advanced.md",
+          "title": "Advanced Queries"
+        },
+        {
+          "file": "04-migrations.md",
+          "title": "Code-First Migrations"
         }
       ]
     },
@@ -375,6 +267,10 @@
         {
           "file": "06-odac-login-forms.md",
           "title": "Odac Login Forms (Zero-Config)"
+        },
+        {
+          "file": "07-magic-links.md",
+          "title": "Magic Links"
         }
       ]
     },