@aruvili/api 0.1.0

package/dist/scheduler.d.ts

@@ -0,0 +1,33 @@
+export interface BackgroundTask {
+    name: string;
+    intervalSeconds: number;
+    execute: (client: any) => Promise<void>;
+}
+declare class AruviliScheduler {
+    private tasks;
+    private timer;
+    private isRunning;
+    /**
+     * Registers a task with the scheduler.
+     */
+    register(task: BackgroundTask): void;
+    /**
+     * Starts the scheduler loop.
+     */
+    start(tickIntervalMs?: number): Promise<void>;
+    /**
+     * Stops the scheduler.
+     */
+    stop(): void;
+    /**
+     * Performs a single scheduler loop check.
+     */
+    private tick;
+    /**
+     * Tries to lock and run a background task.
+     */
+    private runTaskDistributed;
+}
+export declare const scheduler: AruviliScheduler;
+export {};
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,cAAM,gBAAgB;IACpB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACI,QAAQ,CAAC,IAAI,EAAE,cAAc;IAIpC;;OAEG;IACU,KAAK,CAAC,cAAc,GAAE,MAAc;IAuBjD;;OAEG;IACI,IAAI;IASX;;OAEG;YACW,IAAI;IAMlB;;OAEG;YACW,kBAAkB;CA6CjC;AAED,eAAO,MAAM,SAAS,kBAAyB,CAAC"}

package/dist/scheduler.js

@@ -0,0 +1,97 @@
+import { query, withTransaction } from './db.js';
+class AruviliScheduler {
+    tasks = [];
+    timer = null;
+    isRunning = false;
+    /**
+     * Registers a task with the scheduler.
+     */
+    register(task) {
+        this.tasks.push(task);
+    }
+    /**
+     * Starts the scheduler loop.
+     */
+    async start(tickIntervalMs = 10000) {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        // 1. Ensure the jobs tracking table exists
+        await query(`
+      CREATE TABLE IF NOT EXISTS _scheduled_jobs (
+        name VARCHAR(255) PRIMARY KEY,
+        last_started TIMESTAMP WITH TIME ZONE,
+        last_completed TIMESTAMP WITH TIME ZONE,
+        status VARCHAR(50),
+        error_message TEXT
+      );
+    `);
+        console.log(`[SCHEDULER] Started scheduler with tick interval: ${tickIntervalMs}ms. Registered tasks: ${this.tasks.length}`);
+        // Run the scheduler tick loop
+        this.timer = setInterval(async () => {
+            await this.tick();
+        }, tickIntervalMs);
+    }
+    /**
+     * Stops the scheduler.
+     */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.isRunning = false;
+        console.log('[SCHEDULER] Scheduler stopped.');
+    }
+    /**
+     * Performs a single scheduler loop check.
+     */
+    async tick() {
+        for (const task of this.tasks) {
+            await this.runTaskDistributed(task);
+        }
+    }
+    /**
+     * Tries to lock and run a background task.
+     */
+    async runTaskDistributed(task) {
+        try {
+            // Try to acquire distributed lock atomically
+            const acquired = await withTransaction(async (client) => {
+                const sql = `
+          INSERT INTO _scheduled_jobs (name, last_started, status)
+          VALUES ($1, NOW(), 'RUNNING')
+          ON CONFLICT (name) DO UPDATE
+          SET last_started = NOW(), status = 'RUNNING'
+          WHERE (_scheduled_jobs.status != 'RUNNING' AND _scheduled_jobs.last_started < NOW() - (INTERVAL '1 second' * $2))
+             OR (_scheduled_jobs.status = 'RUNNING' AND _scheduled_jobs.last_started < NOW() - (INTERVAL '1 second' * $2 * 2))
+          RETURNING 1;
+        `;
+                const res = await client.query(sql, [task.name, task.intervalSeconds]);
+                return res.rows.length > 0;
+            });
+            if (!acquired) {
+                return; // Lock not acquired (already running or completed too recently)
+            }
+            console.log(`[SCHEDULER] Running task: ${task.name}`);
+            const start = Date.now();
+            try {
+                await withTransaction(async (client) => {
+                    await task.execute(client);
+                });
+                // Update task state on success
+                await query(`UPDATE _scheduled_jobs SET last_completed = NOW(), status = 'SUCCESS', error_message = NULL WHERE name = $1`, [task.name]);
+                console.log(`[SCHEDULER] Task ${task.name} finished successfully in ${Date.now() - start}ms`);
+            }
+            catch (err) {
+                console.error(`[SCHEDULER ERROR] Task ${task.name} failed:`, err.message);
+                await query(`UPDATE _scheduled_jobs SET last_completed = NOW(), status = 'FAILED', error_message = $2 WHERE name = $1`, [task.name, err.message]);
+            }
+        }
+        catch (err) {
+            // Catch db concurrency locking serialization or connection errors
+        }
+    }
+}
+export const scheduler = new AruviliScheduler();
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/utils/link-validator.d.ts

@@ -0,0 +1,7 @@
+import { DocTypeDefinition } from '@aruvili/core';
+/**
+ * Validates all Link field values exist in their target DocType tables.
+ * Prevents dangling references (foreign key integrity without DB-level FK constraints).
+ */
+export declare function validateLinks(definition: DocTypeDefinition, record: Record<string, any>, client: any): Promise<string[]>;
+//# sourceMappingURL=link-validator.d.ts.map

package/dist/utils/link-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-validator.d.ts","sourceRoot":"","sources":["../../src/utils/link-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAgB,MAAM,eAAe,CAAC;AAGhE;;;GAGG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,iBAAiB,EAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,GAAG,GACV,OAAO,CAAC,MAAM,EAAE,CAAC,CAiCnB"}

package/dist/utils/link-validator.js

@@ -0,0 +1,33 @@
+import { getTableName } from '@aruvili/core';
+/**
+ * Validates all Link field values exist in their target DocType tables.
+ * Prevents dangling references (foreign key integrity without DB-level FK constraints).
+ */
+export async function validateLinks(definition, record, client) {
+    const errors = [];
+    const linkFields = definition.fields.filter(f => f.fieldtype === 'Link' && f.options && record[f.fieldname]);
+    for (const field of linkFields) {
+        const targetDocType = field.options;
+        const targetTable = getTableName(targetDocType);
+        const value = record[field.fieldname];
+        if (typeof value !== 'string' || value.trim() === '')
+            continue;
+        try {
+            const res = await client.query(`SELECT 1 FROM ${targetTable} WHERE name = $1 LIMIT 1`, [value]);
+            if (res.rows.length === 0) {
+                errors.push(`Link field '${field.fieldname}': value '${value}' does not exist in ${targetDocType}.`);
+            }
+        }
+        catch (err) {
+            // Table might not exist yet if DocType not registered
+            if (err.code === '42P01') { // undefined_table
+                errors.push(`Link field '${field.fieldname}': target DocType '${targetDocType}' table does not exist.`);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=link-validator.js.map

package/dist/utils/link-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-validator.js","sourceRoot":"","sources":["../../src/utils/link-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,YAAY,EAAE,MAAM,eAAe,CAAC;AAGhE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAA6B,EAC7B,MAA2B,EAC3B,MAAW;IAEX,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,CACzC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,MAAM,IAAI,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAChE,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,aAAa,GAAG,KAAK,CAAC,OAAQ,CAAC;QACrC,MAAM,WAAW,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAEtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QAE/D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAC5B,iBAAiB,WAAW,0BAA0B,EACtD,CAAC,KAAK,CAAC,CACR,CAAC;YACF,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,SAAS,aAAa,KAAK,uBAAuB,aAAa,GAAG,CAAC,CAAC;YACvG,CAAC;QACH,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,sDAAsD;YACtD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,kBAAkB;gBAC5C,MAAM,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,SAAS,sBAAsB,aAAa,yBAAyB,CAAC,CAAC;YAC1G,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/resolver.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolves all Link fields for a list of document records in a single batch, preventing N+1 queries.
+ */
+export declare function resolveLinkFields(doctypeName: string, records: any[]): Promise<any[]>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/utils/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/utils/resolver.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAyD3F"}

package/dist/utils/resolver.js

@@ -0,0 +1,58 @@
+import { registry } from '../registry.js';
+import { getTableName } from '@aruvili/core';
+import { query } from '../db.js';
+/**
+ * Resolves all Link fields for a list of document records in a single batch, preventing N+1 queries.
+ */
+export async function resolveLinkFields(doctypeName, records) {
+    if (records.length === 0)
+        return records;
+    const definition = await registry.get(doctypeName);
+    if (!definition)
+        return records;
+    // Identify fields of type Link
+    const linkFields = definition.fields.filter(f => f.fieldtype === 'Link' && f.options);
+    if (linkFields.length === 0)
+        return records;
+    // Deep clone to prevent mutating original parameters
+    const resolved = JSON.parse(JSON.stringify(records));
+    for (const field of linkFields) {
+        const targetDocType = field.options;
+        const fieldname = field.fieldname;
+        // Collect all unique referenced names
+        const ids = Array.from(new Set(resolved.map((r) => r[fieldname]).filter((v) => typeof v === 'string' && v.trim() !== '')));
+        if (ids.length === 0)
+            continue;
+        // Retrieve target configuration to locate its title field
+        const targetDef = await registry.get(targetDocType);
+        const titleField = targetDef?.title_field || 'name';
+        const targetTable = getTableName(targetDocType);
+        try {
+            // Fetch key and title mappings in a single batch query
+            const sql = `SELECT name, ${titleField} AS title FROM ${targetTable} WHERE name = ANY($1)`;
+            const res = await query(sql, [ids]);
+            const map = new Map();
+            for (const row of res.rows) {
+                map.set(row.name, {
+                    name: row.name,
+                    title_field_value: String(row.title)
+                });
+            }
+            // Merge results
+            for (const record of resolved) {
+                const val = record[fieldname];
+                if (val && map.has(val)) {
+                    record[fieldname] = map.get(val);
+                }
+                else if (val) {
+                    record[fieldname] = { name: val, title_field_value: val };
+                }
+            }
+        }
+        catch (err) {
+            console.error(`Failed to resolve link field '${fieldname}' pointing to '${targetDocType}':`, err);
+        }
+    }
+    return resolved;
+}
+//# sourceMappingURL=resolver.js.map

package/dist/utils/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/utils/resolver.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@aruvili/api",
+  "version": "0.1.0",
+  "description": "Bun + Hono generic CRUD engine for Meta Framework",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@aruvili/core": "^0.1.0",
+    "hono": "^4.4.7",
+    "pg": "^8.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "@types/pg": "^8.11.6",
+    "typescript": "~6.0.2"
+  }
+}

package/src/api.test.ts

@@ -0,0 +1,362 @@
+import { describe, expect, it } from 'bun:test';
+
+// Establish dbMock globally for unit tests BEFORE importing modules that query db
+(globalThis as any).dbMock = {
+  query: async (text: string, params?: any[]) => {
+    if (text.includes('SELECT definition FROM _doctype_meta')) {
+      if (params && params[0] === 'Ticket') {
+        return { rows: [{ definition: {
+          name: 'Ticket',
+          fields: [
+            { fieldname: 'title', label: 'Title', fieldtype: 'Text', required: true },
+            { fieldname: 'workflow_state', label: 'State', fieldtype: 'Text' }
+          ],
+          permissions: [{ role: 'Employee', create: true, read: true, update: true, delete: true }],
+          workflow: {
+            fieldname: 'workflow_state',
+            initial_state: 'Draft',
+            transitions: [
+              { state: 'Draft', action: 'Approve', next_state: 'Approved', allowed_roles: ['System Manager'] }
+            ]
+          }
+        }}]};
+      }
+      return { rows: [{ definition: {
+        name: 'Project', title_field: 'project_name',
+        fields: [{ fieldname: 'project_name', label: 'Project Name', fieldtype: 'Text', required: true }],
+        permissions: [{ role: 'System Manager', create: true, read: true, update: true, delete: true }]
+      }}]};
+    }
+    return { rows: [] };
+  },
+  withTransaction: async (cb: any) => {
+    const clientMock = {
+      query: async (text: string, params?: any[]) => {
+        if (text.includes('SELECT * FROM dt_ticket')) {
+          return { rows: [{ name: 'TKT-100', title: 'Need access', workflow_state: 'Draft', docstatus: 0 }] };
+        }
+        if (text.includes('UPDATE dt_ticket')) {
+          return { rows: [{ name: 'TKT-100', title: 'Need access', workflow_state: 'Approved', docstatus: 0 }] };
+        }
+        return { rows: [] };
+      }
+    };
+    return cb(clientMock);
+  }
+};
+
+import { registry } from './registry.js';
+import { authMiddleware } from './middleware/auth.js';
+import { controllerRegistry, DocTypeController } from './controllers/index.js';
+
+describe('Registry Metadata Cache', () => {
+  it('should resolve and cache doctype schemas', async () => {
+    const doc = await registry.get('Project');
+    expect(doc).not.toBeNull();
+    expect(doc!.name).toBe('Project');
+    expect(doc!.title_field).toBe('project_name');
+  });
+
+  it('should compile Zod validators dynamically', async () => {
+    const val = await registry.getValidator('Project');
+    expect(val).not.toBeNull();
+    expect(val!.safeParse({ project_name: 'Test' }).success).toBe(true);
+  });
+
+  it('should invalidate cache on demand', async () => {
+    registry.invalidate('Project');
+    const doc = await registry.get('Project');
+    expect(doc).not.toBeNull(); // Re-fetched from mock DB
+  });
+});
+
+describe('Authentication Middleware', () => {
+  it('should resolve mock admin token in non-production', async () => {
+    let contextUser: any = null;
+    const mockCtx: any = {
+      req: { header: (n: string) => n === 'Authorization' ? 'Bearer admin-token' : null },
+      set: (k: string, v: any) => { if (k === 'user') contextUser = v; },
+      json: () => {}
+    };
+    let called = false;
+    await authMiddleware(mockCtx, async () => { called = true; });
+    expect(called).toBe(true);
+    expect(contextUser.roles).toContain('System Manager');
+    expect(contextUser.session_id).toBeDefined();
+  });
+
+  it('should assign Guest role when no auth header', async () => {
+    let contextUser: any = null;
+    const mockCtx: any = {
+      req: { header: () => null },
+      set: (k: string, v: any) => { if (k === 'user') contextUser = v; }
+    };
+    let called = false;
+    await authMiddleware(mockCtx, async () => { called = true; });
+    expect(called).toBe(true);
+    expect(contextUser.roles).toContain('Guest');
+    expect(contextUser.session_id).toBeDefined();
+  });
+
+  it('should reject empty bearer tokens', async () => {
+    let statusCode = 0;
+    const mockCtx: any = {
+      req: { header: (n: string) => n === 'Authorization' ? 'Bearer ' : null },
+      set: () => {},
+      json: (_body: any, status: number) => { statusCode = status; }
+    };
+    await authMiddleware(mockCtx, async () => {});
+    expect(statusCode).toBe(401);
+  });
+});
+
+describe('Controller Lifecycle Hooks', () => {
+  it('should execute registered hook', async () => {
+    let hookCalled = false;
+    class TestCtrl extends DocTypeController {
+      override async before_insert() { hookCalled = true; }
+    }
+    controllerRegistry.register('Project', new TestCtrl());
+    await controllerRegistry.triggerBeforeInsert('Project', {}, { db: {} as any, user: { email: 'a', roles: [] } });
+    expect(hookCalled).toBe(true);
+  });
+
+  it('should not throw for unregistered doctypes', async () => {
+    await controllerRegistry.triggerBeforeInsert('NonExistent', {}, { db: {} as any, user: { email: 'a', roles: [] } });
+  });
+});
+
+describe('Link Validation', () => {
+  it('should pass if no link fields or values are present', async () => {
+    const { validateLinks } = await import('./utils/link-validator.js');
+    const docDef: any = {
+      name: 'Task',
+      fields: [{ fieldname: 'title', fieldtype: 'Text' }]
+    };
+    const errors = await validateLinks(docDef, { title: 'Hello' }, { query: async () => ({ rows: [] }) });
+    expect(errors.length).toBe(0);
+  });
+
+  it('should fail if link target does not exist in db', async () => {
+    const { validateLinks } = await import('./utils/link-validator.js');
+    const docDef: any = {
+      name: 'Task',
+      fields: [{ fieldname: 'project', fieldtype: 'Link', options: 'Project' }]
+    };
+    const mockClient = {
+      query: async () => ({ rows: [] }) // Empty means not found
+    };
+    const errors = await validateLinks(docDef, { project: 'Proj-1' }, mockClient);
+    expect(errors.length).toBe(1);
+    expect(errors[0]).toContain('does not exist');
+  });
+
+  it('should pass if link target exists in db', async () => {
+    const { validateLinks } = await import('./utils/link-validator.js');
+    const docDef: any = {
+      name: 'Task',
+      fields: [{ fieldname: 'project', fieldtype: 'Link', options: 'Project' }]
+    };
+    const mockClient = {
+      query: async () => ({ rows: [{ name: 'Proj-1' }] }) // Found
+    };
+    const errors = await validateLinks(docDef, { project: 'Proj-1' }, mockClient);
+    expect(errors.length).toBe(0);
+  });
+});
+
+describe('Rate Limiter Middleware', () => {
+  it('should allow requests within limit and block when exceeded', async () => {
+    const { rateLimitMiddleware } = await import('./middleware/rate-limit.js');
+    const { config } = await import('./config.js');
+    
+    // Temporarily reduce rate limit to 2 for testing
+    const originalMax = config.rateLimitMax;
+    config.rateLimitMax = 2;
+
+    const mockCtx: any = {
+      get: (k: string) => k === 'user' ? { email: 'test@user.com' } : null,
+      header: () => {},
+      req: { header: () => null },
+      json: (body: any, status: number) => ({ body, status })
+    };
+
+    let called = 0;
+    const next = async () => { called++; };
+
+    // Request 1: Allow
+    let res = await rateLimitMiddleware(mockCtx, next);
+    expect(res).toBeUndefined();
+    expect(called).toBe(1);
+
+    // Request 2: Allow
+    res = await rateLimitMiddleware(mockCtx, next);
+    expect(res).toBeUndefined();
+    expect(called).toBe(2);
+
+    // Request 3: Block (returns Hono response representation)
+    res = await rateLimitMiddleware(mockCtx, next);
+    expect(res).toBeDefined();
+    expect(res!.status).toBe(429);
+    expect(called).toBe(2); // next not called
+
+    // Restore rate limit config
+    config.rateLimitMax = originalMax;
+  });
+});
+
+describe('Body Limit Middleware', () => {
+  it('should block requests exceeding bodyLimitBytes', async () => {
+    const { bodyLimitMiddleware } = await import('./middleware/body-limit.js');
+    const { config } = await import('./config.js');
+    
+    const originalLimit = config.bodyLimitBytes;
+    config.bodyLimitBytes = 100; // 100 bytes
+
+    const mockCtx: any = {
+      req: { header: (k: string) => k === 'content-length' ? '150' : null },
+      json: (body: any, status: number) => ({ body, status })
+    };
+
+    const next = async () => {};
+    const res = await bodyLimitMiddleware(mockCtx, next);
+    expect(res).toBeDefined();
+    expect(res!.status).toBe(413);
+
+    config.bodyLimitBytes = originalLimit;
+  });
+
+  it('should allow requests within limit', async () => {
+    const { bodyLimitMiddleware } = await import('./middleware/body-limit.js');
+    const mockCtx: any = {
+      req: { header: (k: string) => k === 'content-length' ? '50' : null },
+      json: () => {}
+    };
+
+    let called = false;
+    const next = async () => { called = true; };
+    await bodyLimitMiddleware(mockCtx, next);
+    expect(called).toBe(true);
+  });
+});
+
+describe('Amend & Bulk Route Handlers', () => {
+  it('should process bulk insert successfully', async () => {
+    const { Hono } = await import('hono');
+    const { crudRouter } = await import('./routes/crud.js');
+    const app = new Hono<any>();
+    
+    app.use('*', async (c, next) => {
+      c.set('user', { email: 'test@user.com', roles: ['System Manager'] });
+      await next();
+    });
+    app.route('/api/doctype/:doctype', crudRouter);
+
+    const res = await app.request('/api/doctype/Project/bulk', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        action: 'insert',
+        items: [{ project_name: 'Bulk Proj 1' }]
+      })
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.success).toBe(true);
+    expect(body.count).toBe(1);
+  });
+
+  it('should fail bulk insert with invalid data', async () => {
+    const { Hono } = await import('hono');
+    const { crudRouter } = await import('./routes/crud.js');
+    const app = new Hono<any>();
+    
+    app.use('*', async (c, next) => {
+      c.set('user', { email: 'test@user.com', roles: ['System Manager'] });
+      await next();
+    });
+    app.route('/api/doctype/:doctype', crudRouter);
+
+    // Schema validator fails when required fields are missing
+    // Project name is not present in items
+    const res = await app.request('/api/doctype/Project/bulk', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        action: 'insert',
+        items: [{ wrong_field: 'Wrong' }]
+      })
+    });
+    expect(res.status).toBe(500);
+    const body = await res.json();
+    expect(body.error).toContain('Bulk transaction rolled back');
+  });
+});
+
+describe('File Attachments Router', () => {
+  it('should block file uploads for Guest users', async () => {
+    const { Hono } = await import('hono');
+    const { filesRouter } = await import('./routes/files.js');
+    const app = new Hono<any>();
+    app.use('*', async (c, next) => {
+      c.set('user', { email: 'guest@user.com', roles: ['Guest'] });
+      await next();
+    });
+    app.route('/api/files', filesRouter);
+
+    const formData = new FormData();
+    formData.append('file', new File(['hello'], 'hello.txt', { type: 'text/plain' }));
+
+    const res = await app.request('/api/files/upload', {
+      method: 'POST',
+      body: formData
+    });
+    expect(res.status).toBe(401);
+  });
+});
+
+describe('Workflow Engine Router', () => {
+  it('should successfully execute transition if user has allowed role', async () => {
+    const { Hono } = await import('hono');
+    const { crudRouter } = await import('./routes/crud.js');
+    const app = new Hono<any>();
+    app.use('*', async (c, next) => {
+      c.set('user', { email: 'manager@user.com', roles: ['System Manager'] });
+      await next();
+    });
+    app.route('/api/doctype/:doctype', crudRouter);
+
+    const res = await app.request('/api/doctype/Ticket/TKT-100/workflow', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'Approve' })
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.workflow_state).toBe('Approved');
+  });
+
+  it('should reject transition if user does not have allowed role', async () => {
+    const { Hono } = await import('hono');
+    const { crudRouter } = await import('./routes/crud.js');
+    const app = new Hono<any>();
+    app.use('*', async (c, next) => {
+      c.set('user', { email: 'worker@user.com', roles: ['Employee'] });
+      await next();
+    });
+    app.route('/api/doctype/:doctype', crudRouter);
+
+    const res = await app.request('/api/doctype/Ticket/TKT-100/workflow', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'Approve' })
+    });
+    expect(res.status).toBe(403);
+    const body = await res.json();
+    expect(body.error).toContain('Workflow transition failed');
+  });
+});
+
+
+
+