hapta 1.0.0

package/README.md

@@ -0,0 +1,252 @@
+
+# 🛠️ **Hapta**
+
+**Hapta** is a modular, scalable, and feature-rich backend framework designed to extend [Pocketbase](https://pocketbase.io) with authentication, schema validation, caching, and tenant-based service orchestration.
+
+> Designed to integrate easily into any modern Node.js backend — and purpose-built to unlock Pocketbase for production-scale deployments.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install hapta
+# or
+bun add hapta
+# or
+yarn add hapta
+```
+
+---
+
+## 🚀 Key Features
+
+* ✅ **Authentication via Clover**
+  Multi-strategy login (OAuth, password, OTP, MFA) with tenant role/clearance support.
+
+* 🔐 **Context-Based Auth (`ctx.principal`)**
+  Automatically injects authenticated user state and metadata into each request.
+
+* 📦 **Zod-Based Schema Validation**
+  Auto-validates route inputs with fully typed schema files.
+
+* ⚡ **Smart Caching Layer**
+  Dynamic TTL, auto-invalidation, optimistic scaffolds, and memory-based caching.
+
+* 🧱 **Modular Context System**
+  Unified `Context` class handles services, request metadata, auth, and responses.
+
+* 🏗️ **Batch Write Mode**
+  Queue DB changes, defer execution, and optimize complex flows.
+
+---
+
+## 📁 Project Structure (Recommended)
+
+```
+/
+  └── routes/
+      └── auth/
+          └── index.ts        # Example auth endpoint
+  └── schemas/
+      └── auth/
+          └── index.ts        # Zod validation for auth route
+ 
+```
+
+---
+
+## 🧠 Quick Start
+
+### 🧩 Set up config
+> hapta-config.json
+```json 
+{
+    "port": 8080,
+    "logLevel": "info",
+    "origin":"http://localhost:8081",
+    "AI_ENABLED": false,
+    "Clover_Tenant_ID": "",
+    "Clover_Secret":"",
+    "Clover_Server_Url":"clover.postlyapp.com",
+    "JWT_SECRET":"*",
+    "DatabaseUrl":"http://localhost:8080",
+    "ADMIN_EMAIL":"malikwhitterb@gmail.com",
+    "ADMIN_PASSWORD":""
+}
+
+```
+
+### 🔐 Use the `principal`
+
+```ts
+if (ctx.principal.isAuthenticated) {
+  const username = ctx.principal.username;
+  const clearance = ctx.principal.highest_clearance;
+}
+```
+
+---
+
+## ⚙️ Usage Example
+
+### `/routes/auth/index.ts`
+
+```ts
+import Context from "hapta";
+import { Database } from "hapta";
+
+export default async function POST(ctx: Context, DB: Database) {
+  const { type } = ctx.metadata.query as any;
+
+  if (type === "oauth") {
+    const result = await ctx.services.Clover.Authenticate({ type: "oauth", ...ctx.metadata.query });
+
+    return result.isAuthenticated
+      ? ctx.json(result)
+      : ctx.json({ error: true, message: "OAuth failed" }, 401);
+
+  } else if (type === "password") {
+    const result = await ctx.services.Clover.Authenticate({
+      type: "passwordAuth",
+      ...ctx.metadata.json
+    });
+
+    return result.isAuthenticated
+      ? ctx.json(result)
+      : ctx.json({ error: true, message: "Invalid credentials" }, 400);
+  }
+
+  return ctx.json({ error: true, message: "Unsupported auth type" }, 400);
+}
+```
+
+## Then simply run
+
+```bash
+bun --hot run hapta
+```
+
+---
+
+## 🧬 Database API
+
+```ts
+import { DatabaseService } from "hapta";
+
+const DB = new DatabaseService(pocketbase, cacheHandler);
+```
+
+### 🔹 Get one (cached)
+
+```ts
+const record = await DB.get("users", "abc123");
+```
+
+### 🔹 List (cached + paginated)
+
+```ts
+await DB.list("posts", { page: 1, limit: 20 });
+```
+
+### 🔹 Create with scaffold
+
+```ts
+DB.setBatch(true);
+await DB.create("comments", { body: "Hello!" }, true);
+await DB.saveChanges();
+```
+
+---
+
+## 🧰 Built-in Response Helpers
+
+```ts
+ctx.json({ success: true }, 200);
+ctx.html("<h1>Welcome</h1>");
+ctx.text("Hello world");
+```
+
+All responses include CORS headers out of the box:
+
+```http
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Headers: Content-Type, Authorization
+```
+
+---
+
+## 🧪 Validation with Zod
+
+```ts
+// /schemas/auth/index.ts
+import { z } from "zod";
+
+export default z.object({
+  emailOrUsername: z.string().min(3),
+  password: z.string().min(6),
+});
+```
+
+Hapta automatically loads and validates this schema for `/auth` requests before your handler runs.
+
+---
+
+## 🔄 Batch Mode
+
+```ts
+DB.setBatch(true);
+await DB.create("logs", { message: "Init" });
+await DB.update("users", "abc", { active: false });
+await DB.delete("sessions", "xyz");
+await DB.saveChanges(); // executes all queued ops
+```
+
+---
+
+## 📦 Caching Details
+
+| Method     | Caches | TTL     | Invalidation                    |
+| ---------- | ------ | ------- | ------------------------------- |
+| `get()`    | ✅      | dynamic | on `update`, `delete`           |
+| `list()`   | ✅      | dynamic | on `create`, `update`, `delete` |
+| `create()` | ➖      | ➖       | invalidates all list caches     |
+| `update()` | ➖      | ➖       | invalidates list + get cache    |
+| `delete()` | ➖      | ➖       | invalidates list + get cache    |
+
+---
+
+## 🧱 Integrating with Express, Bun, or Custom Server
+
+You can wire Hapta into any server environment:
+
+```ts
+const ctx = new Context();
+// inject principal, services, metadata, etc.
+ctx.metadata = {
+  requestID: "xyz",
+  timestamp: new Date(),
+  json: await req.json(),
+  headers: req.headers,
+  ...
+};
+
+// call route handler
+const res = await handler(ctx, DB);
+return res;
+```
+
+---
+
+## 🧾 License
+
+MIT © Postr-Inc — Built for scale.
+
+---
+
+## 💬 Questions?
+
+* Open an issue
+* PRs welcome
+* Built with ❤️ by the Postr-Inc team
+ 

package/bun.lock

@@ -0,0 +1,13 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "dependencies": {
+        "pocketbase": "^0.26.1",
+      },
+    },
+  },
+  "packages": {
+    "pocketbase": ["pocketbase@0.26.1", "", {}, "sha512-fjcPDpxyqTZCwqGUTPUV7vssIsNMqHxk9GxbhxYHPEf18RqX2d9cpSqbbHk7aas30jqkgptuKfG7aY/Mytjj3g=="],
+  }
+}

package/helpers/HTTP/Methods/index.ts

@@ -0,0 +1,42 @@
+// A base type that all database records must have.
+export type BaseRecord = {
+    id: string;
+    cacheKey: string,
+    collectionName: string,
+    collectionId: string
+};
+
+// Data for creating a new record, which is the full object minus the 'id'.
+export type CreateData<T> = Omit<T, 'id'>;
+
+// A robust options object for querying lists of items.
+export type QueryOptions<T> = {
+    // Example: { name: 'Hapta', version: 2 }
+    filter?: Partial<T>;
+    sort?: {
+        field: keyof T;
+        direction: 'asc' | 'desc';
+    };
+    pagination?: {
+        limit: number;
+        offset: number;
+    };
+};
+
+// A fully-typed, generic, and async interface for database operations.
+export type Database = {
+    /** Gets a single item by its ID. */
+    get<T extends BaseRecord>(collection: string, id: string): Promise<T | null>;
+
+    /** Gets multiple items using a flexible query. */
+    list<T extends BaseRecord>(collection: string, options?: QueryOptions<T>): Promise<T[]>;
+    
+    /** Creates a new item in the database. */
+    create<T extends BaseRecord>(collection: string, data: CreateData<T>): Promise<T>;
+
+    /** Updates an existing item by its ID. */
+    update<T extends BaseRecord>(collection: string, id: string, data: Partial<CreateData<T>>): Promise<T>;
+
+    /** Deletes an item by its ID. */
+    delete(collection: string, id: string): Promise<void>;
+};

package/helpers/HTTP/Request/Context.ts

@@ -0,0 +1,209 @@
+import { config } from "../../../src/core/config";
+const corsHeaders = {
+  "Access-Control-Allow-Origin": config.origin,
+  "Access-Control-Allow-Methods": "OPTIONS, GET, POST, PUT, PATCH, DELETE",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization",
+};
+
+/**
+ * A discriminated union to safely represent the authenticated actor.
+ * The state is either fully authenticated or explicitly not.
+ */
+
+export type AuthenticatedPrincipal = {
+  isAuthenticated: true;
+  id: string; // The unique ID of the actor from Clover
+  token: string; // The auth token used for this context
+  Roles: string[];
+  username: string,
+  avatar: string,
+  
+  /**
+   * @description used to determine the highest rated security clearance a user has this helps identify users with low security levels.
+   */
+  highest_clearance: number,
+  createdAt: Date;
+  /**
+   * Assigned to allows devs to see which group the user is assigned to and which clover instance id they are authenticated in
+   */
+  clover_group_assigned_To: string
+  clover_assigned_id: string,
+
+};
+
+export type UnauthenticatedPrincipal = {
+  isAuthenticated: false;
+};
+
+export type Principal = AuthenticatedPrincipal | UnauthenticatedPrincipal;
+
+// ---
+
+type PasswordAuthOptions = {
+    type: 'passwordAuth';
+    emailOrUsername: string;
+    password: string;
+};
+
+type MfaAuthOptions = {
+    type: 'mfa';
+    userId: string; // MFA usually follows a login, so you'd have a user ID
+    mfaCode: string;
+};
+
+type OAuthAuthOptions = {
+  type: 'oauth';
+  code: string;
+  redirectUri: string | null;
+  authenticated_id: string;
+  accessToken?: string; // token received from Clover OAuth flow
+};
+
+
+type OtpAuthOptions = {
+    type: 'otp';
+    email: string;
+    otpCode: string;
+};
+
+// Create a union of all possible authentication methods
+type AuthOptions = PasswordAuthOptions | MfaAuthOptions | OtpAuthOptions | OAuthAuthOptions;
+
+// Define the final function type
+// (Assuming it returns a Promise with the Principal type from our previous discussions)
+type AuthenticateFn = (options: AuthOptions) => Promise<Principal>;
+type RegisterFn = (data: any ) => Promise<boolean>
+type TokenOptions = {
+  payload: {
+     id: string, 
+  },
+  iat: number
+} 
+type VerifyFn = (token: string) => Promise<Principal>;
+ 
+export type ServiceConfigs = {
+  Clover: {
+    Tenant_ID: string;
+    Roles?: { name: string; security_level: number }[];
+    Authorized_Users: string[];
+    Authenticate: AuthenticateFn; 
+    Register: RegisterFn;
+    Verify?: VerifyFn;            // just verify token
+  };
+};
+
+// ---
+
+/**
+ * Metadata for logging, tracing, and auditing.
+ * Key fields are now required for better traceability.
+ */
+export type RequestMetadata = {
+  requestID: string;
+  timestamp: Date;
+  ipAddress?: string;
+  userAgent?: string;
+  body: any,
+  json: {},
+  headers:  Headers | {};
+  query:{},
+  params: {}
+};
+
+// ---
+
+/**
+ * The main application context, redesigned for clarity.
+ */
+interface IContext {
+  /**
+   * The authenticated user or system actor for this request,
+   * populated by the Clover authentication backend.
+   */
+  principal: Principal;
+
+  /**
+   * Configurations for downstream services.
+   */
+  services: ServiceConfigs;
+
+  /**
+   * Optional tenant or organization context.
+   */
+  tenantId?: string | undefined | null;
+
+  /**
+   * Metadata about the incoming request.
+   * @prop headers
+   * @prop requestID
+   * @prop timestamp
+   * @prop ipAddress
+   * @prop userAgent
+   * @prop body
+   * @prop json 
+   */
+  metadata: RequestMetadata;
+  json: (value: any, status?: number, statusText?:string) => Response
+  html: (value: string, status?: number, statusText?:string) => Response
+  text: (value: string, status?: number, statusText?:string) => Response
+}
+ 
+export default class Context implements IContext {
+  public principal: Principal;
+  public services: ServiceConfigs;
+  public tenantId?: string;
+  public metadata: RequestMetadata;
+
+  constructor() {
+    // Initialize with default/empty values
+    this.principal = { isAuthenticated: false };
+    this.services = {} as ServiceConfigs; // Cast as empty, to be populated by the builder
+    this.metadata = {
+      requestID: '',
+      timestamp: new Date(),
+      json: {},
+      headers: {},
+      query: {},
+      params: {}
+    };
+  }
+
+  /**
+   * Helper method to create a JSON response.
+   */
+  json(value: any, status: number = 200): Response {
+    return Response.json(value, {
+      status,
+      headers: {
+        "Content-Type": "application/json", 
+        ...corsHeaders
+      }
+    });
+  }
+
+  /**
+   * Helper method to create an HTML response.
+   */
+  html(value: string, status: number = 200): Response {
+    return new Response(value, {
+      status,
+      headers: {
+        "Content-Type": "text/html", 
+        ...corsHeaders
+      }
+    });
+  }
+
+  /**
+   * Helper method to create a plain text response.
+   */
+  text(value: string, status: number = 200): Response {
+    return new Response(value, {
+      status,
+      headers: {
+        "Content-Type": "text/plain",
+        ...corsHeaders
+      }
+    });
+  }
+}

package/index.ts

@@ -0,0 +1,384 @@
+#!/usr/bin/env bun
+import Context from "./helpers/HTTP/Request/Context";
+import { serve, FileSystemRouter, type Serve, type Server } from "bun";
+import { config } from "./src/core/config";
+import Pocketbase from "pocketbase";
+import path from "path";
+import { DatabaseService } from "./src/core/CrudManager";
+import Cache from "./src/core/CacheManager";
+import process from "process";
+import jwt from "jsonwebtoken";
+import crypto from "crypto";
+import * as z from "zod";
+import { watch } from "fs";
+import fs from "fs"
+import { pathToFileURL } from "url";
+
+// --- Global server and router instances ---
+let server: Server;
+// MODIFIED: Make the router a single, persistent instance
+const router = new FileSystemRouter({
+    style: "nextjs",
+    dir: path.join(process.cwd(), "routes"),
+});
+
+
+// --- Validation: Ensure required config vars are present ---
+if (!config.Clover_Secret || !config.Clover_Tenant_ID) {
+    console.error("❌ Clover_Secret and Clover_Tenant_ID must be set in your config.");
+    process.exit(1);
+}
+
+if (!config.ADMIN_EMAIL || !config.ADMIN_PASSWORD) {
+    console.error("❌ Please set an admin email and admin password for database authentication");
+    process.exit(1);
+}
+
+if(!fs.existsSync(path.join(process.cwd(), "routes"))){
+    console.error("❌ Please create a routes folder and create your first route");
+    process.exit(1);
+}
+
+// --- Pocketbase Connection ---
+const pb = new Pocketbase(config.DatabaseUrl);
+try {
+    await pb.collection("_superusers").authWithPassword(config.ADMIN_EMAIL, config.ADMIN_PASSWORD);
+} catch (_) { }
+
+// --- Primary Tenant Data ---
+const primaryTenantData = await fetch(`${config.Clover_Server_Url}/tenants/${config.Clover_Tenant_ID}`, {
+    headers: { Authorization_Secret: config.Clover_Secret },
+}).then(async (res) => {
+    if (!res.ok) throw new Error(`Failed to fetch primary tenant data: ${res.status} ${res.statusText}`);
+    return res.json();
+});
+console.log("✅ Primary tenant data loaded.");
+
+const cache = new Cache();
+const db = new DatabaseService(pb, cache); 
+// --- Server Configuration Builder ---
+async function createServeConfig(): Promise<Serve> {
+    console.log("🛠️ Building server configuration...");
+
+    // MODIFIED: Reload the router to detect new/deleted files
+    router.reload();
+
+    const routeHandlers = new Map<string, (ctx: Context, db: DatabaseService) => Promise<Response>>();
+    const schemas = new Map();
+    const middlewares = new Map<string, (ctx: Context) => Promise<Response | boolean>>();
+
+    const reimportModule = async (modulePath: string) => { 
+        const resolvedPath = path.resolve(modulePath);
+        if (require.cache[resolvedPath]) {
+            delete require.cache[resolvedPath];
+        }
+        const module = require(modulePath)
+        return module
+    };
+
+    for (const [pathname, routePath] of Object.entries(router.routes)) {
+        try {
+            const routeModule = await reimportModule(routePath as string);
+            if (routeModule.default) {
+                routeHandlers.set(pathname, routeModule.default);
+            }
+
+            const schemaPath = path.join(process.cwd(), "schemas", pathname, "index.ts");
+            if (await Bun.file(schemaPath).exists()) {
+                const schema = await reimportModule(schemaPath);
+                if (schema.default) schemas.set(pathname, schema.default);
+            }
+
+            const middlewarePath = path.join(path.dirname(routePath as string), "middleware.ts");
+            if (await Bun.file(middlewarePath).exists()) {
+                const middleware = await reimportModule(middlewarePath);
+                if (middleware.default) middlewares.set(pathname, middleware.default);
+            }
+        } catch (e) { 
+            console.error(`❌ Error loading module for route ${pathname}:`, e);
+        }
+    }
+
+    console.log("✅ All modules loaded.");
+
+    return {
+        port: config.port,
+        async fetch(req: Request) {
+            if (req.method === "OPTIONS") {
+                return new Response(null, {
+                    status: 204,
+                    headers: {
+                        "Access-Control-Allow-Origin": config.origin,
+                        "Access-Control-Allow-Methods": "OPTIONS, GET, POST, PUT, PATCH, DELETE",
+                        "Access-Control-Allow-Headers": "Content-Type, Authorization",
+                        "Access-Control-Max-Age": "86400",
+                    },
+                });
+            }
+            const url = new URL(req.url);
+            const routeMatch = router.match(url.href);
+
+            if (!routeMatch) {
+                return new Response("404 Not Found", { status: 404 });
+            }
+
+            const routeHandler = routeHandlers.get(routeMatch.name);
+            const middleware = middlewares.get(routeMatch.name);
+            const schema = schemas.get(routeMatch.name);
+
+            if (!routeHandler) {
+                return new Response(`Route handler for ${routeMatch.name} not found.`, { status: 404 });
+            }
+
+            try {
+                const context = await buildRequestContext(req, req.headers);
+                context.metadata.params = routeMatch.params;
+                context.metadata.query = routeMatch.query;
+                context.metadata.headers = Object.fromEntries(req.headers.entries());
+
+                if (context.principal.isAuthenticated) {
+
+                }
+                if (middleware) {
+                    const result = await middleware(context);
+                    if (result instanceof Response) return result;
+                    if (result === false) return new Response("Forbidden", { status: 403 });
+                }
+
+                if (schema) {
+                    const validation = {
+                        body: schema.body?.safeParse(context.metadata.json),
+                        query: schema.query?.safeParse(context.metadata.query),
+                        headers: schema.headers?.safeParse(context.metadata.headers),
+                    };
+                    for (const key of ["body", "query", "headers"] as const) {
+                        if (validation[key] && !validation[key]?.success) {
+                            return new Response(JSON.stringify({ success: false, error: validation[key]?.error.flatten() }), { status: 400, headers: { "Content-Type": "application/json" } });
+                        }
+                    }
+                }
+
+                return await routeHandler(context, db);
+            } catch (err) {
+                console.error(`❌ Error handling ${url.pathname}:`, err);
+                return new Response("Internal Server Error", { status: 500 });
+            }
+        },
+        error(error) {
+            console.error("☠️ Uncaught Error:", error);
+            return new Response("Something went wrong!", { status: 500 });
+        },
+    };
+}
+
+// --- Debounced File Watcher ---
+let reloadTimeout: Timer | null = null;
+function watchFiles() {
+    const watchDirs = [
+        path.join(process.cwd(), "routes"),
+        path.join(process.cwd(), "schemas")
+    ];
+
+    const triggerReload = (changeType: string, filename: string | null) => {
+        if (!filename) return;
+        if (reloadTimeout) clearTimeout(reloadTimeout);
+
+        reloadTimeout = setTimeout(async () => {
+            console.log(`\n🔁 Change detected in ${changeType}: ${filename}.`);
+            try {
+                const newConfig = await createServeConfig();
+                server.reload(newConfig);
+                console.log("✅ Server reloaded successfully.");
+            } catch (e) {
+                console.error("❌ Server reload failed:", e)
+            }
+        }, 100); // Debounce for 100ms
+    };
+
+    for (const dir of watchDirs) {
+        watch(dir, { recursive: true }, (changeType, filename) => triggerReload(changeType, filename));
+    }
+
+    console.log("👀 Watching for file changes in routes/ and schemas/...");
+}
+
+// --- Helper Functions ---
+function validateToken(token: string) {
+    try {
+        return jwt.verify(token, config.JWT_SECRET) as jwt.JwtPayload;
+    } catch {
+        return null;
+    }
+}
+
+async function buildRequestContext(req: Request, headers: Headers) {
+    const reqJSON = await req.json().catch(() => ({}));
+
+    const hasToken = headers.has("Authorization")
+    var isAuthenticated = false;
+    if (hasToken) {
+        try {
+            jwt.verify(token as string, config.JWT_SECRET)
+            isAuthenticated = true
+        } catch (error) {
+            isAuthenticated = false
+        }
+    }
+    const context = {
+        principal: { isAuthenticated },
+        services: {
+            Clover: {
+                Tenant_ID: primaryTenantData.id,
+                Authorized_Users: primaryTenantData.expand?.Tenant_Groups?.Users || [],
+                Register: async (data: any) => {
+                    const fetchBody = {
+                        Tenant_Id: primaryTenantData.id,
+                        Secret: config.Clover_Secret,
+                        ...data
+                    }
+
+                    if (!data.record.email || !data.record.password || !data.record.username) {
+                        return { success: false, error: "Missing email username or password" }
+                    }
+                    const res = await fetch(`${config.Clover_Server_Url}/auth/signup`, {
+                        method: "POST",
+                        headers: {
+                            "Authorization_Secret": config.Clover_Secret
+                        },
+                        body: JSON.stringify(fetchBody)
+                    })
+
+                    return await res.json()
+
+                },
+                Authenticate: async (options) => {
+                    const fetchBody = {
+                        Tenant_Id: primaryTenantData.id,
+                        Secret: config.Clover_Secret,
+                        type: options.type,
+                    };
+
+                    if (options.type === "passwordAuth") {
+                        fetchBody.emailOrUsername = options.emailOrUsername;
+                        fetchBody.password = options.password;
+                    }
+
+                    if (options.type === "oauth") {
+                        fetchBody.code = options.code;
+                        fetchBody.redirectUri = options.redirectUri;
+                        fetchBody.client_secret = config.Clover_Secret
+                        fetchBody.authenticated_id = options.authenticated_id
+                    }
+
+
+                    const authRes = await fetch(`${config.Clover_Server_Url}/oauth/token`, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                            Authorization_Secret: config.Clover_Secret,
+                            tenantid: config.Clover_Tenant_ID,
+                            "User-Agent": headers.get("User-Agent") || "",
+                        },
+                        body: JSON.stringify(fetchBody),
+                    });
+
+                    if (!authRes.ok) { 
+                        return {
+                            isAuthenticated: false,
+                            error: true,
+                            message: "Authentication failed",
+                        };
+                    }
+
+                    const responseJson = await authRes.json();
+                    const record = responseJson.AuthenticatedModal;
+                    record.clover_assigned_id = primaryTenantData.id;
+
+                    record.token = jwt.sign(
+                        {
+                            id: record.id,
+                            clover_assigned_id: record.clover_assigned_id,
+                            Roles: record.Roles,
+                            Group: record.clover_group_assigned_To,
+                        },
+                        config.JWT_SECRET,
+                    );
+
+                    record.isAuthenticated = true;
+
+                    return record;
+                },
+                Verify: async (token) => {
+                    try {
+                        const payload = jwt.verify(token, config.JWT_SECRET);
+                        return {
+                            isAuthenticated: true,
+                            id: payload.id,
+                            clover_group_assigned_To: payload.Group,
+                            clover_assigned_id: payload.clover_assigned_id,
+                            Roles: payload.Roles,
+                            token,
+                        };
+                    } catch {
+                        return { isAuthenticated: false };
+                    }
+                },
+                Roles: Array.isArray(primaryTenantData.Tenant_Roles)
+                    ? primaryTenantData.Tenant_Roles
+                    : [primaryTenantData.Tenant_Roles],
+            },
+        },
+        metadata: {
+            requestID: crypto.randomUUID(),
+            timestamp: new Date(),
+            params: {},
+            query: {},
+            json: reqJSON,
+            headers : {}
+        },
+        tenantId: headers.get("tenantid") ?? undefined,
+        json: (value: any, status?: number, statusText?:string) => {
+            return Response.json(value, {
+                ...(status && {status}),
+                headers: {
+                    "Access-Control-Origin": config.origin,
+                    "Access-Control-Allow-Methods": "GET,PATCH,PUT,DELETE",
+                    "Access-Control-Allow-Headers": "Content-Type, Authorization"
+                }
+            })
+        },
+
+        html: (value: string, status: number, statusText?: string) => {
+            return new Response(value, {
+                ...(status && {status}),
+                ...(statusText && {statusText}),
+                headers:{
+                    "Content-Type": "text/html",
+                    "Access-Control-Origin": config.origin,
+                    "Access-Control-Allow-Methods": "GET,PATCH,PUT,DELETE",
+                    "Access-Control-Allow-Headers": "Content-Type, Authorization"
+                }
+            })
+        }
+    };
+
+    const authHeader = headers.get("authorization");
+    const token = authHeader?.startsWith("Bearer ") ? authHeader.split(" ")[1] : authHeader;
+
+    if (token) {
+        context.principal = await context.services.Clover.Verify(token);
+    }
+
+    return context;
+}
+
+ 
+// --- Initial Server Start --- 
+server = Bun.serve(await createServeConfig());
+console.log(`🚀 Hapta listening at http://localhost:${server.port}`);
+watchFiles();
+ 
+export {
+    DatabaseService,
+    Context
+};

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "hapta",
+  "bin": {
+    "hapta":"./index.ts"
+  },
+  "version": "1.0.0",
+  "description": "modular, scalable, and feature-rich backend framework designed to extend Pocketbase with authentication, schema validation, caching, and tenant-based service orchestration.",
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2",
+    "pocketbase": "^0.26.1",
+    "zod": "^4.0.5"
+  }
+}

package/src/core/CacheManager.ts

@@ -0,0 +1,117 @@
+//@ts-nocheck
+const COMPRESSION_THRESHOLD = 1024;
+
+interface CacheSyncMessage {
+  action: "set" | "delete" | "invalidate";
+  key: string;
+  data?: any; // For 'set'
+  expiresAt?: number;
+  source: number;
+}
+
+export default class CacheHandler {
+  private cache = new Map<string, { data: any; ttl: number; compressed?: boolean }>();
+  private broadcastCallback?: (msg: CacheSyncMessage) => void;
+
+  constructor() {
+    this.startExpirationCheck();
+  }
+
+  public setBroadcastCallback(callback: (msg: CacheSyncMessage) => void) {
+    this.broadcastCallback = callback;
+  }
+  public timesVisited = new Map<string, { incremental: number }>();
+  /** Store data in cache, compress if large */
+  public set(key: string, data: any, ttlSeconds = 0, isInternal = false): any {
+    if (!key.includes("undefined") && !key.includes("null")) {
+      const expiresAt = ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : 0;
+      try {
+        const jsonStr = JSON.stringify(data);
+        if (jsonStr.length > COMPRESSION_THRESHOLD) {
+          const compressed = Bun.gzipSync(new TextEncoder().encode(jsonStr));
+          this.cache.set(key, { data: compressed, ttl: expiresAt, compressed: true });
+        } else {
+          this.cache.set(key, { data, ttl: expiresAt });
+        }
+      } catch {
+        this.cache.set(key, { data, ttl: expiresAt });
+      }
+
+      if (this.broadcastCallback && !isInternal) {
+        this.broadcastCallback({ action: "set", key, data, expiresAt, source: parseInt(config.Server.NodeId as any) });
+      }
+    } else {
+      console.warn(`[CacheHandler] Invalid cache key: ${key}`);
+    }
+    return data;
+  }
+  public getDynamicTTL(key: string, mode: "immediate" | "short" | "medium" | "long" | "dynamic" = "dynamic"): number {
+    if (mode !== "dynamic") {
+      switch (mode) {
+        case "immediate": return 5 * 60 * 1000;
+        case "short": return 30 * 60 * 1000;
+        case "medium": return 2 * 60 * 60 * 1000;
+        case "long": return 6 * 60 * 60 * 1000;
+      }
+    }
+    let status = this.timesVisited.get(key) ?? { incremental: 0 };
+    status.incremental++;
+    this.timesVisited.set(key, status);
+
+    if (status.incremental > 5) {
+      return 30 * 60 * 1000; // 30 mins
+    } else if (status.incremental > 0) {
+      return 2 * 60 * 60 * 1000; // 2 hrs
+    } else {
+      return 6 * 60 * 60 * 1000; // 6 hrs default
+    }
+  }
+  public get<T>(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    if (entry.ttl > 0 && entry.ttl < Date.now()) {
+      this.cache.delete(key);
+      return null;
+    }
+    if (entry.compressed) {
+      try {
+        const decompressed = Bun.gunzipSync(entry.data);
+        return JSON.parse(new TextDecoder().decode(decompressed));
+      } catch {
+        this.cache.delete(key);
+        return null;
+      }
+    }
+    return entry.data;
+  }
+
+  public delete(key: string): boolean {
+    if (this.broadcastCallback) {
+      this.broadcastCallback({ action: "delete", key, source: parseInt(config.Server.NodeId as any) });
+    }
+    return this.cache.delete(key);
+  }
+
+  /** Invalidate all keys starting with prefix */
+  public invalidateByPrefix(prefix: string): void {
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+        if (this.broadcastCallback) {
+          this.broadcastCallback({ action: "invalidate", key, source: parseInt(config.Server.NodeId as any) });
+        }
+      }
+    }
+  }
+
+  private startExpirationCheck() {
+    setInterval(() => {
+      const now = Date.now();
+      for (const [key, { ttl }] of this.cache.entries()) {
+        if (ttl > 0 && ttl < now) {
+          this.cache.delete(key);
+        }
+      }
+    }, 60000);
+  }
+}

package/src/core/CrudManager.ts

@@ -0,0 +1,197 @@
+import Pocketbase from "pocketbase";
+import CacheHandler from "./CacheManager";
+
+export type BaseRecord = {
+  id: string;
+  created: string;
+  updated: string;
+};
+
+export type ListOptions<T> = {
+  page?: number;
+  limit?: number;
+  filter?: string;
+  sort?: string;
+  expand?: string[];
+};
+
+export type PaginatedResponse<T> = {
+  items: T[];
+  totalItems: number;
+  totalPages: number;
+  page: number;
+  limit: number;
+  cacheKey: string; // ✅ clients can store this key!
+};
+
+export class DatabaseService {
+  private pb: Pocketbase;
+  private cache: CacheHandler;
+  private isBatchMode = false;
+  private batchQueue: Array<{ action: "create" | "update" | "delete"; payload: any }> = [];
+
+  constructor(pocketbaseInstance: Pocketbase, cacheController: CacheHandler) {
+    this.pb = pocketbaseInstance;
+    this.cache = cacheController;
+  }
+
+  public setBatch(enable: boolean) {
+    this.isBatchMode = enable;
+  }
+
+  /** Combines parts into a normalized cache key. */
+  private generateCacheKey(parts: (string | number | undefined)[]): string {
+    return parts.filter(Boolean).join(":");
+  }
+
+  /** Dynamic TTL based on usage or type. */
+  private getDynamicTTL(key: string, mode: "short" | "medium" | "long" = "medium"): number {
+    switch (mode) {
+      case "short": return 10 * 60; // 10 min
+      case "medium": return 60 * 60; // 1 hour
+      case "long": return 6 * 60 * 60; // 6 hours
+    }
+  }
+
+  public async saveChanges() {
+    for (const op of this.batchQueue) {
+      switch (op.action) {
+        case "create":
+          await this.create(op.payload.collection, op.payload.data, false);
+          break;
+        case "update":
+          await this.update(op.payload.collection, op.payload.id, op.payload.data);
+          break;
+        case "delete":
+          await this.delete(op.payload.collection, op.payload.id);
+          break;
+      }
+    }
+    this.batchQueue = [];
+    this.isBatchMode = false;
+  }
+
+  /** Get one record, with caching. */
+  public async get<T extends BaseRecord>(
+    collection: string,
+    id: string,
+    expand?: string[]
+  ): Promise<(T & { cacheKey: string }) | null> {
+    const cacheKey = this.generateCacheKey([collection, "get", id, expand?.join(",")]);
+    const cached = this.cache.get<T>(cacheKey);
+    if (cached) return { ...cached, cacheKey };
+
+    try {
+      const record = await this.pb.collection(collection).getOne<T>(id, {
+        ...(expand && { expand: expand.join(",") }),
+      });
+      this.cache.set(cacheKey, record, this.getDynamicTTL(cacheKey));
+      return { ...record, cacheKey };
+    } catch (error: any) {
+      if (error.status === 404) return null;
+      console.error(`[DatabaseService] get failed: ${collection}/${id}`, error);
+      throw error;
+    }
+  }
+
+  /** List records with pagination + caching. */
+  public async list<T extends BaseRecord>(
+    collection: string,
+    options: ListOptions<T>
+  ): Promise<PaginatedResponse<T>> {
+    const { page = 1, limit = 10, filter, sort, expand } = options;
+    const cacheKey = this.generateCacheKey([collection, "list", page, limit, filter, sort, expand?.join(",")]);
+
+    const cached = this.cache.get<PaginatedResponse<T>>(cacheKey);
+    if (cached) return cached;
+
+    const result = await this.pb.collection(collection).getList<T>(page, limit, {
+      filter,
+      sort,
+      ...(expand && { expand: expand.join(",") }),
+    });
+
+    const response: PaginatedResponse<T> = {
+      items: result.items,
+      totalItems: result.totalItems,
+      totalPages: result.totalPages,
+      page: result.page,
+      limit: result.perPage,
+      cacheKey,
+    };
+
+    this.cache.set(cacheKey, response, this.getDynamicTTL(cacheKey));
+    return response;
+  }
+
+  /** Create a record. Supports batching + scaffold. */
+  public async create<T extends BaseRecord>(
+    collection: string,
+    data: Partial<T>,
+    useScaffold: boolean = false
+  ): Promise<T> {
+    if (this.isBatchMode && useScaffold) {
+      const scaffoldId = Math.random().toString(36).substring(2, 10);
+      const scaffoldRecord: any = {
+        ...data,
+        id: scaffoldId,
+        created: new Date().toISOString(),
+        updated: new Date().toISOString(),
+        scaffold: true,
+      };
+
+      // Prepend to any feed cache:
+      this.cache.keys().forEach((key) => {
+        if (key.startsWith(`${collection}:list`)) {
+          const existing = this.cache.get<any>(key);
+          if (existing && Array.isArray(existing.items)) {
+            existing.items = [scaffoldRecord, ...existing.items];
+            this.cache.set(key, existing, this.getDynamicTTL(key));
+          }
+        }
+      });
+
+      this.batchQueue.push({ action: "create", payload: { collection, data } });
+      return scaffoldRecord;
+    }
+
+    const record = await this.pb.collection(collection).create<T>(data);
+    this.cache.invalidateByPrefix(this.generateCacheKey([collection, "list"]));
+    return record;
+  }
+ 
+  public async update<T extends BaseRecord>(
+    collection: string,
+    id: string,
+    data: Partial<T>,
+    expand?: string[]
+  ): Promise<T> {
+    if (this.isBatchMode) {
+      this.batchQueue.push({ action: "update", payload: { collection, id, data } });
+      return { id, created: "", updated: "", ...(data as any) };
+    }
+
+    const record = await this.pb.collection(collection).update<T>(id, data, {
+      ...(expand && { expand: expand.join(",") }),
+    });
+
+    this.cache.delete(this.generateCacheKey([collection, "get", id]));
+    this.cache.invalidateByPrefix(this.generateCacheKey([collection, "list"]));
+    return record;
+  }
+
+  /** Delete a record. */
+  public async delete(collection: string, id: string): Promise<boolean> {
+    if (this.isBatchMode) {
+      this.batchQueue.push({ action: "delete", payload: { collection, id } });
+      return true;
+    }
+
+    const success = await this.pb.collection(collection).delete(id);
+    if (success) {
+      this.cache.delete(this.generateCacheKey([collection, "get", id]));
+      this.cache.invalidateByPrefix(this.generateCacheKey([collection, "list"]));
+    }
+    return success;
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,56 @@
+// src/core/config.ts
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Define the shape of your configuration
+export interface AppConfig {
+    port: number;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    // Add other configuration properties here
+    origin: string,
+    AI_ENABLED: boolean,
+    Clover_Tenant_ID: string, 
+    Clover_Secret: string,
+    Clover_Server_Url: string,
+    NodeId: string,
+    JWT_SECRET: String,
+    ADMIN_EMAIL: string,
+    ADMIN_PASSWORD: string,
+    DatabaseUrl:string,
+}
+
+// Define your default configuration as a fallback
+const defaultConfig: AppConfig = {
+    port: 8080,
+    logLevel: 'info',
+};
+
+function findAndLoadConfig(): AppConfig {
+    // 1. Look for 'hapta.config.json' in the current directory
+    const localConfigPath = path.join(process.cwd(), 'hapta.config.json');
+
+    // Add other locations to check here if you want (e.g., home directory)
+
+    try {
+        if (fs.existsSync(localConfigPath)) {
+            console.log(`Loading configuration from: ${localConfigPath}`);
+            const fileContent = fs.readFileSync(localConfigPath, 'utf-8');
+            const userConfig = JSON.parse(fileContent); 
+            
+            // Merge user config with defaults, so user only has to specify what they want to change
+            return { ...defaultConfig, ...userConfig };
+        }
+    } catch (error) {
+        console.error('Error reading or parsing config file:', error);
+        // Fallback to defaults if the file is malformed
+        return defaultConfig;
+    }
+
+    // 2. If no file is found, return the default configuration
+    console.log('No hapta.config.json found. Using default settings.');
+    return defaultConfig;
+}
+
+// Load the config once and export it for the rest of the app to use
+export const config = findAndLoadConfig();

package/test_html/index.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+    <input type="text" placeholder="Username" id ="username" />
+    <input type="text" placeholder="Password" id="password" />
+    <button onclick="login()"></button>
+    <script> 
+        function login(){
+            
+        const username = document.getElementById("username").value
+        const password = document.getElementById("password").value
+                console.log(username,password)
+        }
+
+
+    </script>
+</body>
+</html>