@aruvili/api 0.1.0

package/src/routes/crud.ts

@@ -0,0 +1,1029 @@
+import { Hono } from 'hono';
+import { registry } from '../registry.js';
+import { query, withTransaction } from '../db.js';
+import { getTableName } from '@aruvili/core';
+import { controllerRegistry, ControllerContext } from '../controllers/index.js';
+import { resolveLinkFields } from '../utils/resolver.js';
+import { validateLinks } from '../utils/link-validator.js';
+import crypto from 'crypto';
+
+export const crudRouter = new Hono<{ Variables: { user: any } }>();
+
+/**
+ * Helper to compute diff between old and new JSON objects for audit trail.
+ */
+function computeDiff(oldVal: any, newVal: any) {
+  const diff: Record<string, any> = {};
+  const keys = new Set([...Object.keys(oldVal || {}), ...Object.keys(newVal || {})]);
+  for (const key of keys) {
+    if (key === 'updated_at' || key === 'modified_by' || key === 'version') continue;
+    if (Array.isArray(oldVal?.[key]) || Array.isArray(newVal?.[key])) continue;
+    if (oldVal?.[key] !== newVal?.[key]) {
+      diff[key] = [oldVal?.[key] ?? null, newVal?.[key] ?? null];
+    }
+  }
+  return diff;
+}
+
+/**
+ * Dynamic naming generator pipeline.
+ */
+async function generateDocumentName(client: any, doctype: any, body: any): Promise<string> {
+  const rule = doctype.naming_rule || 'UUID';
+  
+  if (rule === 'UUID') return crypto.randomUUID();
+
+  if (rule === 'Autoincrement') {
+    const table = getTableName(doctype.name);
+    const res = await client.query(`SELECT COALESCE(MAX(CAST(name AS INTEGER)), 0) + 1 AS next FROM ${table}`);
+    return String(res.rows[0].next);
+  }
+
+  if (rule === 'NamingSeries') {
+    const seriesFormat = doctype.naming_series || 'DOC-.#####';
+    const prefix = seriesFormat.split('.')[0] || 'DOC-';
+    const res = await client.query(
+      `INSERT INTO _naming_series (prefix, current_value) VALUES ($1, 1)
+       ON CONFLICT (prefix) DO UPDATE SET current_value = _naming_series.current_value + 1
+       RETURNING current_value`, [prefix]
+    );
+    const val = res.rows[0].current_value;
+    const padMatch = seriesFormat.match(/#+/);
+    const padSize = padMatch ? padMatch[0].length : 5;
+    const paddedNum = String(val).padStart(padSize, '0');
+    let name = seriesFormat.replace(/#+/, paddedNum).replace(/\./g, '');
+    const now = new Date();
+    name = name.replace(/YYYY/g, String(now.getFullYear()));
+    name = name.replace(/MM/g, String(now.getMonth() + 1).padStart(2, '0'));
+    return name;
+  }
+
+  if (rule === 'Expression') {
+    const expr = doctype.naming_series || 'DOC-{name}';
+    let name = expr;
+    const matches = expr.match(/\{([^}]+)\}/g);
+    if (matches) {
+      for (const m of matches) {
+        name = name.replace(m, body[m.replace(/[{}]/g, '')] || '');
+      }
+    }
+    return name.trim() !== '' ? name : crypto.randomUUID();
+  }
+
+  return crypto.randomUUID();
+}
+
+/**
+ * POST /api/doctype/:doctype — Create document
+ */
+crudRouter.post('/', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const body = await c.req.json();
+  const user = c.get('user');
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+
+  const validator = await registry.getValidator(doctypeName);
+  if (!validator) return c.json({ error: 'Failed to compile schema validator' }, 500);
+
+  const parsed = validator.safeParse(body);
+  if (!parsed.success) return c.json({ error: 'Validation failed', details: parsed.error.format() }, 400);
+
+  const table = getTableName(doctypeName);
+
+  try {
+    const document = await withTransaction(async (client) => {
+      const ctx: ControllerContext = { db: client, user };
+      const docName = body.name || await generateDocumentName(client, definition, body);
+
+      const record: Record<string, any> = {
+        ...parsed.data, name: docName, docstatus: 0,
+        created_by: user.email, modified_by: user.email
+      };
+
+      // Set workflow initial state default if missing
+      if (definition.workflow && record[definition.workflow.fieldname] === undefined) {
+        record[definition.workflow.fieldname] = definition.workflow.initial_state;
+      }
+
+      // Set field-level defaults if missing
+      for (const field of definition.fields) {
+        if (record[field.fieldname] === undefined && field.default !== undefined) {
+          record[field.fieldname] = field.default;
+        }
+      }
+
+      // Link validation
+      const linkErrors = await validateLinks(definition, record, client);
+      if (linkErrors.length > 0) throw new Error(`Link validation failed: ${linkErrors.join('; ')}`);
+
+      await controllerRegistry.triggerBeforeInsert(doctypeName, record, ctx);
+      await controllerRegistry.triggerBeforeSave(doctypeName, record, ctx);
+
+      const parentCols: string[] = ['name', 'created_by', 'modified_by', 'docstatus'];
+      const parentVals: any[] = [record.name, record.created_by, record.modified_by, record.docstatus];
+
+      for (const field of definition.fields) {
+        if (field.fieldtype === 'Table' || field.fieldtype === 'Table MultiSelect') {
+          continue; // Handled separately
+        }
+        parentCols.push(field.fieldname);
+        parentVals.push(record[field.fieldname] ?? null);
+      }
+
+      // Insert parent record
+      const colPlaceholders = parentVals.map((_, i) => `$${i + 1}`).join(', ');
+      const sql = `INSERT INTO ${table} (${parentCols.join(', ')}) VALUES (${colPlaceholders}) RETURNING *`;
+      const insertRes = await client.query(sql, parentVals);
+      const savedParent = insertRes.rows[0];
+
+      // Process and insert Child Tables nested collections
+      const childData: Record<string, any[]> = {};
+      
+      for (const field of definition.fields) {
+        if (field.fieldtype === 'Table' && Array.isArray(body[field.fieldname])) {
+          const childDocTypeName = field.options!;
+          const childTable = getTableName(childDocTypeName);
+          const childRowsInput = body[field.fieldname] as any[];
+
+          const childDefinition = await registry.get(childDocTypeName);
+          if (!childDefinition) {
+            throw new Error(`Child DocType '${childDocTypeName}' definition missing.`);
+          }
+
+          const childValidator = await registry.getValidator(childDocTypeName);
+          if (!childValidator) {
+            throw new Error(`Failed to compile validator for child '${childDocTypeName}'.`);
+          }
+
+          const savedChildren: any[] = [];
+          let idx = 1;
+
+          for (const row of childRowsInput) {
+            const childParsed = childValidator.safeParse(row);
+            if (!childParsed.success) {
+              throw new Error(`Child '${childDocTypeName}' validation failed: ${JSON.stringify(childParsed.error.format())}`);
+            }
+
+            const rowName = row.name || crypto.randomUUID();
+            const childRecord: Record<string, any> = {
+              ...childParsed.data,
+              name: rowName,
+              parent: record.name,
+              parenttype: doctypeName,
+              parentfield: field.fieldname,
+              idx: idx++,
+              created_by: user.email,
+              modified_by: user.email
+            };
+
+            const childCols = ['name', 'parent', 'parenttype', 'parentfield', 'idx', 'created_by', 'modified_by'];
+            const childVals = [
+              childRecord.name,
+              childRecord.parent,
+              childRecord.parenttype,
+              childRecord.parentfield,
+              childRecord.idx,
+              childRecord.created_by,
+              childRecord.modified_by
+            ];
+
+            for (const cf of childDefinition.fields) {
+              if (cf.fieldtype === 'Table' || cf.fieldtype === 'Table MultiSelect') continue;
+              childCols.push(cf.fieldname);
+              childVals.push(childRecord[cf.fieldname] ?? null);
+            }
+
+            const childPlaceholder = childVals.map((_, i) => `$${i + 1}`).join(', ');
+            const childSql = `INSERT INTO ${childTable} (${childCols.join(', ')}) VALUES (${childPlaceholder}) RETURNING *`;
+            const childRes = await client.query(childSql, childVals);
+            savedChildren.push(childRes.rows[0]);
+          }
+
+          childData[field.fieldname] = savedChildren;
+        }
+      }
+
+      const finalRecord = { ...savedParent, ...childData };
+
+      // Trigger after_insert hooks
+      await controllerRegistry.triggerAfterInsert(doctypeName, finalRecord, ctx);
+
+      // Audit Log
+      await client.query(
+        `INSERT INTO _audit_log (doctype_name, docname, action, changed_by, diff)
+         VALUES ($1, $2, 'CREATE', $3, $4)`,
+        [doctypeName, finalRecord.name, user.email, JSON.stringify(record)]
+      );
+
+      return finalRecord;
+    });
+
+    return c.json(document);
+  } catch (err: any) {
+    const status = err.message.includes('Link validation failed') ? 400 : 500;
+    if (status === 500) {
+      console.error('Create record failed:', err);
+    }
+    return c.json({ error: 'Failed to create record in database', details: err.message }, status as any);
+  }
+});
+
+/**
+ * GET /api/doctype/:doctype
+ * Dynamic list endpoint with enterprise-safe SQL construction.
+ */
+crudRouter.get('/', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) {
+    return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+  }
+
+  const table = getTableName(doctypeName);
+
+  // Parsing query settings with safe defaults
+  const limitRaw = parseInt(c.req.query('limit') || '20');
+  const limit = Math.min(Math.max(isNaN(limitRaw) ? 20 : limitRaw, 1), 100);
+  const offsetRaw = parseInt(c.req.query('offset') || '0');
+  const offset = Math.max(isNaN(offsetRaw) ? 0 : offsetRaw, 0);
+  const resolveLinks = c.req.query('resolve_links') === 'true';
+
+  // Whitelist-validated ORDER BY to prevent SQL injection
+  const allowedSortColumns = new Set([
+    'name', 'created_at', 'updated_at', 'docstatus',
+    ...definition.fields.filter(f => f.fieldtype !== 'Table' && f.fieldtype !== 'Table MultiSelect').map(f => f.fieldname)
+  ]);
+  const orderByInput = c.req.query('order_by') || 'created_at desc';
+  const orderParts = orderByInput.split(',').map(p => p.trim()).slice(0, 3); // Max 3 sort fields
+  const safeSortClauses: string[] = [];
+  for (const part of orderParts) {
+    const [col, dir] = part.split(/\s+/);
+    if (col && allowedSortColumns.has(col.toLowerCase())) {
+      const safeDir = dir?.toLowerCase() === 'asc' ? 'ASC' : 'DESC';
+      safeSortClauses.push(`${col.toLowerCase()} ${safeDir}`);
+    }
+  }
+  const orderByClause = safeSortClauses.length > 0 ? safeSortClauses.join(', ') : 'created_at DESC';
+
+  // Construct filters - only allow known schema columns via parameterized queries
+  const reservedParams = ['limit', 'offset', 'order_by', 'resolve_links', 'fields'];
+  const filterKeys = Object.keys(c.req.query()).filter(k => !reservedParams.includes(k));
+
+  const filters: string[] = [];
+  const params: any[] = [];
+  let paramIdx = 1;
+
+  for (const key of filterKeys) {
+    const fieldDef = definition.fields.find(f => f.fieldname === key);
+    const isSystemCol = ['name', 'docstatus', 'uuid', 'created_by', 'modified_by'].includes(key);
+    if (fieldDef || isSystemCol) {
+      // Use the validated column name, not user input
+      const safeCol = fieldDef ? fieldDef.fieldname : key;
+      filters.push(`${safeCol} = $${paramIdx++}`);
+      params.push(c.req.query(key));
+    }
+  }
+
+  const whereClause = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
+  
+  // Whitelist-validated SELECT columns to prevent over-fetching
+  const allowedFields = new Set([
+    'name', 'uuid', 'created_at', 'updated_at', 'created_by', 'modified_by', 'docstatus', 'version',
+    ...definition.fields.filter(f => f.fieldtype !== 'Table' && f.fieldtype !== 'Table MultiSelect').map(f => f.fieldname)
+  ]);
+  const fieldsInput = c.req.query('fields');
+  let selectFields = '*';
+  if (fieldsInput) {
+    const requested = fieldsInput.split(',').map(f => f.trim().toLowerCase());
+    const matched = requested.filter(f => allowedFields.has(f));
+    if (matched.length > 0) {
+      selectFields = matched.join(', ');
+    }
+  }
+
+  try {
+    const countSql = `SELECT COUNT(*) AS total FROM ${table} ${whereClause}`;
+    const countRes = await query(countSql, params);
+    const totalCount = parseInt(countRes.rows[0].total);
+
+    const sql = `SELECT ${selectFields} FROM ${table} ${whereClause} ORDER BY ${orderByClause} LIMIT ${limit} OFFSET ${offset}`;
+    const res = await query(sql, params);
+    let records = res.rows;
+
+    if (resolveLinks) {
+      records = await resolveLinkFields(doctypeName, records);
+    }
+
+    return c.json({ data: records, total_count: totalCount, limit, offset });
+  } catch (err: any) {
+    return c.json({ error: 'Failed to retrieve list', details: err.message }, 500);
+  }
+});
+
+/**
+ * GET /api/doctype/:doctype/:name
+ * Retrieve single record with nested child table lists.
+ */
+crudRouter.get('/:name', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const name = c.req.param('name');
+  const resolveLinks = c.req.query('resolve_links') === 'true';
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) {
+    return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+  }
+
+  const table = getTableName(doctypeName);
+
+  try {
+    const res = await query(`SELECT * FROM ${table} WHERE name = $1`, [name]);
+    if (res.rows.length === 0) {
+      return c.json({ error: 'Document not found' }, 404);
+    }
+
+    let record = res.rows[0];
+
+    // Fetch related child tables rows
+    for (const field of definition.fields) {
+      if (field.fieldtype === 'Table') {
+        const childDocTypeName = field.options!;
+        const childTable = getTableName(childDocTypeName);
+        const childRes = await query(
+          `SELECT * FROM ${childTable} WHERE parent = $1 AND parenttype = $2 AND parentfield = $3 ORDER BY idx ASC`,
+          [name, doctypeName, field.fieldname]
+        );
+        record[field.fieldname] = childRes.rows;
+      }
+    }
+
+    if (resolveLinks) {
+      const resolvedList = await resolveLinkFields(doctypeName, [record]);
+      record = resolvedList[0];
+    }
+
+    return c.json(record);
+  } catch (err: any) {
+    return c.json({ error: 'Failed to retrieve document', details: err.message }, 500);
+  }
+});
+
+/**
+ * PUT /api/doctype/:doctype/:name
+ * Update endpoint: supports transactional delta verification & child tables rewrite.
+ */
+crudRouter.put('/:name', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const name = c.req.param('name');
+  const body = await c.req.json();
+  const user = c.get('user');
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) {
+    return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+  }
+
+  const validator = await registry.getValidator(doctypeName);
+  if (!validator) {
+    return c.json({ error: 'Failed to compile validation shapes' }, 500);
+  }
+
+  const parsed = validator.safeParse(body);
+  if (!parsed.success) {
+    return c.json({ error: 'Payload validation failed', details: parsed.error.format() }, 400);
+  }
+
+  const table = getTableName(doctypeName);
+
+  try {
+    const updated = await withTransaction(async (client) => {
+      const ctx: ControllerContext = { db: client, user };
+
+      // Load with row lock for concurrency safety
+      const oldRes = await client.query(`SELECT * FROM ${table} WHERE name = $1 FOR UPDATE`, [name]);
+      if (oldRes.rows.length === 0) throw new Error('Document not found');
+      const oldRecord = oldRes.rows[0];
+
+      if (oldRecord.docstatus !== 0) throw new Error('Submitted or Cancelled documents cannot be modified.');
+
+      // Optimistic concurrency control
+      if (body.version !== undefined && body.version !== oldRecord.version) {
+        throw new Error(`Conflict: document was modified by another user (expected version ${body.version}, current ${oldRecord.version}).`);
+      }
+
+      const updatedRecord = { ...oldRecord, ...parsed.data, modified_by: user.email, updated_at: new Date() };
+
+      // Link validation
+      const linkErrors = await validateLinks(definition, updatedRecord, client);
+      if (linkErrors.length > 0) throw new Error(`Link validation failed: ${linkErrors.join('; ')}`);
+
+      await controllerRegistry.triggerBeforeSave(doctypeName, updatedRecord, ctx);
+
+      const updateSets: string[] = ['modified_by = $2', 'updated_at = NOW()', 'version = version + 1'];
+      const updateVals: any[] = [name, user.email];
+      let valIdx = 3;
+
+      for (const field of definition.fields) {
+        if (field.fieldtype === 'Table' || field.fieldtype === 'Table MultiSelect') continue;
+        updateSets.push(`${field.fieldname} = $${valIdx++}`);
+        updateVals.push(updatedRecord[field.fieldname] ?? null);
+      }
+
+      const parentSql = `UPDATE ${table} SET ${updateSets.join(', ')} WHERE name = $1 RETURNING *`;
+      const parentRes = await client.query(parentSql, updateVals);
+      const savedParent = parentRes.rows[0];
+
+      // Dynamic rewrite of child tables collections (clear & replace)
+      const childData: Record<string, any[]> = {};
+      
+      for (const field of definition.fields) {
+        if (field.fieldtype === 'Table') {
+          const childDocTypeName = field.options!;
+          const childTable = getTableName(childDocTypeName);
+          const childRowsInput = body[field.fieldname] as any[] || [];
+
+          const childDefinition = await registry.get(childDocTypeName);
+          if (!childDefinition) throw new Error(`Child definition missing: ${childDocTypeName}`);
+
+          const childValidator = await registry.getValidator(childDocTypeName);
+          if (!childValidator) throw new Error(`Child validator missing: ${childDocTypeName}`);
+
+          // Remove old items
+          await client.query(
+            `DELETE FROM ${childTable} WHERE parent = $1 AND parenttype = $2 AND parentfield = $3`,
+            [name, doctypeName, field.fieldname]
+          );
+
+          const savedChildren: any[] = [];
+          let idx = 1;
+
+          for (const row of childRowsInput) {
+            const childParsed = childValidator.safeParse(row);
+            if (!childParsed.success) {
+              throw new Error(`Child validation failed: ${JSON.stringify(childParsed.error.format())}`);
+            }
+
+            const rowName = row.name || crypto.randomUUID();
+            const childRecord: Record<string, any> = {
+              ...childParsed.data,
+              name: rowName,
+              parent: name,
+              parenttype: doctypeName,
+              parentfield: field.fieldname,
+              idx: idx++,
+              created_by: oldRecord.created_by,
+              modified_by: user.email
+            };
+
+            const childCols = ['name', 'parent', 'parenttype', 'parentfield', 'idx', 'created_by', 'modified_by'];
+            const childVals = [
+              childRecord.name,
+              childRecord.parent,
+              childRecord.parenttype,
+              childRecord.parentfield,
+              childRecord.idx,
+              childRecord.created_by,
+              childRecord.modified_by
+            ];
+
+            for (const cf of childDefinition.fields) {
+              if (cf.fieldtype === 'Table' || cf.fieldtype === 'Table MultiSelect') continue;
+              childCols.push(cf.fieldname);
+              childVals.push(childRecord[cf.fieldname] ?? null);
+            }
+
+            const childPlaceholder = childVals.map((_, i) => `$${i + 1}`).join(', ');
+            const childSql = `INSERT INTO ${childTable} (${childCols.join(', ')}) VALUES (${childPlaceholder}) RETURNING *`;
+            const childRes = await client.query(childSql, childVals);
+            savedChildren.push(childRes.rows[0]);
+          }
+
+          childData[field.fieldname] = savedChildren;
+        }
+      }
+
+      const finalRecord = { ...savedParent, ...childData };
+
+      // Trigger on_update hooks
+      await controllerRegistry.triggerOnUpdate(doctypeName, finalRecord, oldRecord, ctx);
+
+      // Compute scalar diffs & save version details
+      const diffLogs = computeDiff(oldRecord, finalRecord);
+
+      await client.query(
+        `INSERT INTO _audit_log (doctype_name, docname, action, changed_by, diff)
+         VALUES ($1, $2, 'UPDATE', $3, $4)`,
+        [doctypeName, name, user.email, JSON.stringify(diffLogs)]
+      );
+
+      return finalRecord;
+    });
+
+    return c.json(updated);
+  } catch (err: any) {
+    let status = 500;
+    if (err.message.includes('Link validation failed')) {
+      status = 400;
+    } else if (err.message.includes('Conflict:')) {
+      status = 409;
+    }
+    if (status === 500) {
+      console.error('Update record failed:', err);
+    }
+    return c.json({ error: 'Failed to update record in database', details: err.message }, status as any);
+  }
+});
+
+/**
+ * DELETE /api/doctype/:doctype/:name
+ * Delete record: validates docstatus and deletes parent + children records inside transaction.
+ */
+crudRouter.delete('/:name', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const name = c.req.param('name');
+  const user = c.get('user');
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) {
+    return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+  }
+
+  const table = getTableName(doctypeName);
+
+  try {
+    await withTransaction(async (client) => {
+      const ctx: ControllerContext = { db: client, user };
+
+      // Load record to assert existence and status
+      const res = await client.query(`SELECT * FROM ${table} WHERE name = $1`, [name]);
+      if (res.rows.length === 0) {
+        throw new Error('Document not found');
+      }
+      const record = res.rows[0];
+
+      if (record.docstatus === 1) {
+        throw new Error('Submitted documents cannot be deleted. Cancel it first.');
+      }
+
+      // Trigger before delete hooks
+      await controllerRegistry.triggerBeforeDelete(doctypeName, record, ctx);
+
+      // Delete children items in child tables
+      for (const field of definition.fields) {
+        if (field.fieldtype === 'Table') {
+          const childTable = getTableName(field.options!);
+          await client.query(
+            `DELETE FROM ${childTable} WHERE parent = $1 AND parenttype = $2 AND parentfield = $3`,
+            [name, doctypeName, field.fieldname]
+          );
+        }
+      }
+
+      // Delete parent record
+      await client.query(`DELETE FROM ${table} WHERE name = $1`, [name]);
+
+      // Trigger on trash hooks
+      await controllerRegistry.triggerOnTrash(doctypeName, record, ctx);
+
+      // Audit deletion
+      await client.query(
+        `INSERT INTO _audit_log (doctype_name, docname, action, changed_by, diff)
+         VALUES ($1, $2, 'DELETE', $3, $4)`,
+        [doctypeName, name, user.email, JSON.stringify(record)]
+      );
+    });
+
+    return c.json({ success: true, message: 'Document deleted successfully' });
+  } catch (err: any) {
+    return c.json({ error: 'Failed to delete document', details: err.message }, 500);
+  }
+});
+
+/**
+ * POST /api/doctype/:doctype/:name/submit
+ */
+crudRouter.post('/:name/submit', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const name = c.req.param('name');
+  const user = c.get('user');
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+  if (!definition.is_submittable) return c.json({ error: `DocType '${doctypeName}' is not submittable` }, 400);
+
+  const table = getTableName(doctypeName);
+
+  try {
+    const updated = await withTransaction(async (client) => {
+      const ctx: ControllerContext = { db: client, user };
+      const res = await client.query(`SELECT * FROM ${table} WHERE name = $1 FOR UPDATE`, [name]);
+      if (res.rows.length === 0) throw new Error('Document not found');
+      const doc = res.rows[0];
+      if (doc.docstatus !== 0) throw new Error('Only draft documents (status 0) can be submitted.');
+
+      await controllerRegistry.triggerBeforeSubmit(doctypeName, doc, ctx);
+
+      const updateRes = await client.query(
+        `UPDATE ${table} SET docstatus = 1, modified_by = $2, updated_at = NOW(), version = version + 1 WHERE name = $1 RETURNING *`,
+        [name, user.email]
+      );
+
+      await controllerRegistry.triggerOnSubmit(doctypeName, updateRes.rows[0], ctx);
+
+      await client.query(
+        `INSERT INTO _audit_log (doctype_name, docname, action, changed_by, diff) VALUES ($1, $2, 'SUBMIT', $3, '{}')`,
+        [doctypeName, name, user.email]
+      );
+
+      return updateRes.rows[0];
+    });
+    return c.json(updated);
+  } catch (err: any) {
+    return c.json({ error: 'Submission failed', details: err.message }, 500);
+  }
+});
+
+/**
+ * POST /api/doctype/:doctype/:name/cancel
+ */
+crudRouter.post('/:name/cancel', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const name = c.req.param('name');
+  const user = c.get('user');
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+  if (!definition.is_submittable) return c.json({ error: `DocType '${doctypeName}' is not submittable` }, 400);
+
+  const table = getTableName(doctypeName);
+
+  try {
+    const updated = await withTransaction(async (client) => {
+      const ctx: ControllerContext = { db: client, user };
+      const res = await client.query(`SELECT * FROM ${table} WHERE name = $1 FOR UPDATE`, [name]);
+      if (res.rows.length === 0) throw new Error('Document not found');
+      const doc = res.rows[0];
+      if (doc.docstatus !== 1) throw new Error('Only submitted documents (status 1) can be cancelled.');
+
+      await controllerRegistry.triggerBeforeCancel(doctypeName, doc, ctx);
+
+      const updateRes = await client.query(
+        `UPDATE ${table} SET docstatus = 2, modified_by = $2, updated_at = NOW(), version = version + 1 WHERE name = $1 RETURNING *`,
+        [name, user.email]
+      );
+
+      await controllerRegistry.triggerOnCancel(doctypeName, updateRes.rows[0], ctx);
+
+      await client.query(
+        `INSERT INTO _audit_log (doctype_name, docname, action, changed_by, diff) VALUES ($1, $2, 'CANCEL', $3, '{}')`,
+        [doctypeName, name, user.email]
+      );
+
+      return updateRes.rows[0];
+    });
+    return c.json(updated);
+  } catch (err: any) {
+    return c.json({ error: 'Cancellation failed', details: err.message }, 500);
+  }
+});
+
+/**
+ * POST /api/doctype/:doctype/:name/workflow
+ * Performs a workflow action/transition on a document.
+ */
+crudRouter.post('/:name/workflow', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const name = c.req.param('name');
+  const user = c.get('user');
+  const { action } = await c.req.json();
+
+  if (!action) {
+    return c.json({ error: 'Missing parameter "action" in request body.' }, 400);
+  }
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+  if (!definition.workflow) {
+    return c.json({ error: `DocType '${doctypeName}' does not have a workflow configured.` }, 400);
+  }
+
+  const wf = definition.workflow;
+  const wfCol = wf.fieldname;
+  const table = getTableName(doctypeName);
+
+  try {
+    const updated = await withTransaction(async (client) => {
+      const res = await client.query(`SELECT * FROM ${table} WHERE name = $1 FOR UPDATE`, [name]);
+      if (res.rows.length === 0) throw new Error('Document not found');
+      const doc = res.rows[0];
+
+      const currentState = doc[wfCol] || wf.initial_state;
+
+      // Find the matching transition
+      const transition = wf.transitions.find(
+        (t) => t.state === currentState && t.action === action
+      );
+
+      if (!transition) {
+        throw new Error(`No workflow transition found for state '${currentState}' with action '${action}'.`);
+      }
+
+      // Check permissions: user must possess one of the allowed_roles
+      const userRoles = user.roles || ['Guest'];
+      const isAuthorized = transition.allowed_roles.some((role) => userRoles.includes(role));
+      if (!isAuthorized) {
+        throw new Error(`Unauthorized: User roles [${userRoles.join(', ')}] are not permitted to trigger action '${action}'.`);
+      }
+
+      // Perform update
+      const updateRes = await client.query(
+        `UPDATE ${table} SET ${wfCol} = $2, modified_by = $3, updated_at = NOW(), version = version + 1 WHERE name = $1 RETURNING *`,
+        [name, transition.next_state, user.email]
+      );
+
+      // Audit log the transition
+      const diff = {
+        field: wfCol,
+        from: currentState,
+        to: transition.next_state,
+        action
+      };
+      await client.query(
+        `INSERT INTO _audit_log (doctype_name, docname, action, changed_by, diff) VALUES ($1, $2, $3, $4, $5)`,
+        [doctypeName, name, 'WORKFLOW', user.email, JSON.stringify(diff)]
+      );
+
+      return updateRes.rows[0];
+    });
+
+    return c.json(updated);
+  } catch (err: any) {
+    const status = err.message.includes('Unauthorized') ? 403 : 400;
+    return c.json({ error: 'Workflow transition failed', details: err.message }, status);
+  }
+});
+
+/**
+ * POST /api/doctype/:doctype/:name/amend
+ * Creates a new draft copy of a cancelled (docstatus: 2) document.
+ * The new document references the original via the `amended_from` column.
+ */
+crudRouter.post('/:name/amend', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const name = c.req.param('name');
+  const user = c.get('user');
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+  if (!definition.is_submittable) {
+    return c.json({ error: `DocType '${doctypeName}' is not submittable` }, 400);
+  }
+
+  const table = getTableName(doctypeName);
+
+  try {
+    const draft = await withTransaction(async (client) => {
+      const ctx: ControllerContext = { db: client, user };
+
+      // 1. Fetch cancelled document
+      const parentRes = await client.query(`SELECT * FROM ${table} WHERE name = $1`, [name]);
+      if (parentRes.rows.length === 0) throw new Error('Original document not found');
+      const originalDoc = parentRes.rows[0];
+
+      if (originalDoc.docstatus !== 2) {
+        throw new Error('Only cancelled documents (status 2) can be amended.');
+      }
+
+      // 2. Generate new document name
+      const newName = await generateDocumentName(client, definition, originalDoc);
+
+      // 3. Construct parent record copy
+      const record: Record<string, any> = {
+        ...originalDoc,
+        name: newName,
+        docstatus: 0,
+        version: 1,
+        amended_from: name,
+        created_by: user.email,
+        modified_by: user.email,
+        created_at: new Date(),
+        updated_at: new Date()
+      };
+      // Delete uuid to let DB generate a fresh one
+      delete record.uuid;
+
+      // 4. Load child table data of original doc
+      const childData: Record<string, any[]> = {};
+      for (const field of definition.fields) {
+        if (field.fieldtype === 'Table') {
+          const childDocTypeName = field.options!;
+          const childTable = getTableName(childDocTypeName);
+          const childRes = await client.query(
+            `SELECT * FROM ${childTable} WHERE parent = $1 AND parenttype = $2 AND parentfield = $3 ORDER BY idx ASC`,
+            [name, doctypeName, field.fieldname]
+          );
+          
+          const childDefinition = await registry.get(childDocTypeName);
+          if (!childDefinition) throw new Error(`Child DocType '${childDocTypeName}' not found`);
+
+          const savedChildren: any[] = [];
+          let idx = 1;
+          for (const row of childRes.rows) {
+            const childRecord: Record<string, any> = {
+              ...row,
+              name: crypto.randomUUID(),
+              parent: newName,
+              parenttype: doctypeName,
+              parentfield: field.fieldname,
+              idx: idx++,
+              created_by: user.email,
+              modified_by: user.email
+            };
+            delete childRecord.uuid;
+
+            const childCols = ['name', 'parent', 'parenttype', 'parentfield', 'idx', 'created_by', 'modified_by'];
+            const childVals = [
+              childRecord.name,
+              childRecord.parent,
+              childRecord.parenttype,
+              childRecord.parentfield,
+              childRecord.idx,
+              childRecord.created_by,
+              childRecord.modified_by
+            ];
+
+            for (const cf of childDefinition.fields) {
+              if (cf.fieldtype === 'Table' || cf.fieldtype === 'Table MultiSelect') continue;
+              childCols.push(cf.fieldname);
+              childVals.push(childRecord[cf.fieldname] ?? null);
+            }
+
+            const childPlaceholder = childVals.map((_, i) => `$${i + 1}`).join(', ');
+            const childSql = `INSERT INTO ${childTable} (${childCols.join(', ')}) VALUES (${childPlaceholder}) RETURNING *`;
+            const insertRes = await client.query(childSql, childVals);
+            savedChildren.push(insertRes.rows[0]);
+          }
+          childData[field.fieldname] = savedChildren;
+        }
+      }
+
+      // 5. Trigger lifecycle hooks
+      await controllerRegistry.triggerBeforeInsert(doctypeName, record, ctx);
+      await controllerRegistry.triggerBeforeSave(doctypeName, record, ctx);
+
+      // 6. Insert parent record
+      const parentCols: string[] = ['name', 'created_by', 'modified_by', 'docstatus', 'version', 'amended_from'];
+      const parentVals: any[] = [record.name, record.created_by, record.modified_by, record.docstatus, record.version, record.amended_from];
+
+      for (const field of definition.fields) {
+        if (field.fieldtype === 'Table' || field.fieldtype === 'Table MultiSelect') continue;
+        parentCols.push(field.fieldname);
+        parentVals.push(record[field.fieldname] ?? null);
+      }
+
+      const placeholders = parentVals.map((_, i) => `$${i + 1}`).join(', ');
+      const parentSql = `INSERT INTO ${table} (${parentCols.join(', ')}) VALUES (${placeholders}) RETURNING *`;
+      const parentInsert = await client.query(parentSql, parentVals);
+      
+      const finalRecord = { ...parentInsert.rows[0], ...childData };
+
+      // 7. Audit log
+      await client.query(
+        `INSERT INTO _audit_log (doctype_name, docname, action, changed_by, diff) VALUES ($1, $2, 'AMEND', $3, '{}')`,
+        [doctypeName, newName, user.email]
+      );
+
+      return finalRecord;
+    });
+
+    return c.json(draft, 201);
+  } catch (err: any) {
+    return c.json({ error: 'Amend operation failed', details: err.message }, 500);
+  }
+});
+
+/**
+ * POST /api/doctype/:doctype/bulk
+ * Perform mass inserts, updates, or deletions inside a single database transaction.
+ */
+crudRouter.post('/bulk', async (c) => {
+  const doctypeName = c.req.param('doctype') as string;
+  const body = await c.req.json();
+  const user = c.get('user');
+
+  const { action, items } = body;
+  if (!action || !Array.isArray(items)) {
+    return c.json({ error: "Invalid payload. Expected 'action' (delete/update/insert) and an 'items' array." }, 400);
+  }
+
+  const definition = await registry.get(doctypeName);
+  if (!definition) return c.json({ error: `DocType '${doctypeName}' not found` }, 404);
+
+  const table = getTableName(doctypeName);
+
+  try {
+    const result = await withTransaction(async (client) => {
+      const ctx: ControllerContext = { db: client, user };
+      const processed: any[] = [];
+
+      if (action === 'delete') {
+        for (const item of items) {
+          const name = typeof item === 'string' ? item : item.name;
+          if (!name) throw new Error("Missing 'name' field for delete action item.");
+
+          // Load original
+          const res = await client.query(`SELECT * FROM ${table} WHERE name = $1 FOR UPDATE`, [name]);
+          if (res.rows.length === 0) throw new Error(`Document '${name}' not found.`);
+          const record = res.rows[0];
+
+          if (record.docstatus === 1) {
+            throw new Error(`Submitted document '${name}' cannot be deleted. Cancel it first.`);
+          }
+
+          await controllerRegistry.triggerBeforeDelete(doctypeName, record, ctx);
+
+          // Delete children
+          for (const field of definition.fields) {
+            if (field.fieldtype === 'Table') {
+              const childTable = getTableName(field.options!);
+              await client.query(
+                `DELETE FROM ${childTable} WHERE parent = $1 AND parenttype = $2 AND parentfield = $3`,
+                [name, doctypeName, field.fieldname]
+              );
+            }
+          }
+
+          // Delete parent
+          await client.query(`DELETE FROM ${table} WHERE name = $1`, [name]);
+          await controllerRegistry.triggerOnTrash(doctypeName, record, ctx);
+
+          // Audit
+          await client.query(
+            `INSERT INTO _audit_log (doctype_name, docname, action, changed_by, diff) VALUES ($1, $2, 'DELETE', $3, $4)`,
+            [doctypeName, name, user.email, JSON.stringify(record)]
+          );
+          processed.push({ name, status: 'deleted' });
+        }
+      } else if (action === 'insert') {
+        const validator = await registry.getValidator(doctypeName);
+        if (!validator) throw new Error('Validator compilation failed');
+
+        for (const item of items) {
+          const parsed = validator.safeParse(item);
+          if (!parsed.success) throw new Error(`Validation failed for item: ${JSON.stringify(parsed.error.format())}`);
+
+          const docName = item.name || await generateDocumentName(client, definition, item);
+          const record: Record<string, any> = {
+            ...parsed.data, name: docName, docstatus: 0, version: 1,
+            created_by: user.email, modified_by: user.email
+          };
+
+          // Set workflow initial state default if missing
+          if (definition.workflow && record[definition.workflow.fieldname] === undefined) {
+            record[definition.workflow.fieldname] = definition.workflow.initial_state;
+          }
+
+          // Set field-level defaults if missing
+          for (const field of definition.fields) {
+            if (record[field.fieldname] === undefined && field.default !== undefined) {
+              record[field.fieldname] = field.default;
+            }
+          }
+
+          const linkErrors = await validateLinks(definition, record, client);
+          if (linkErrors.length > 0) throw new Error(`Link validation failed: ${linkErrors.join('; ')}`);
+
+          await controllerRegistry.triggerBeforeInsert(doctypeName, record, ctx);
+          await controllerRegistry.triggerBeforeSave(doctypeName, record, ctx);
+
+          const parentCols = ['name', 'created_by', 'modified_by', 'docstatus', 'version'];
+          const parentVals = [record.name, record.created_by, record.modified_by, record.docstatus, record.version];
+
+          for (const field of definition.fields) {
+            if (field.fieldtype === 'Table' || field.fieldtype === 'Table MultiSelect') continue;
+            parentCols.push(field.fieldname);
+            parentVals.push(record[field.fieldname] ?? null);
+          }
+
+          const placeholders = parentVals.map((_, i) => `$${i + 1}`).join(', ');
+          const sql = `INSERT INTO ${table} (${parentCols.join(', ')}) VALUES (${placeholders}) RETURNING *`;
+          const insertRes = await client.query(sql, parentVals);
+          processed.push(insertRes.rows[0]);
+        }
+      } else {
+        throw new Error(`Unsupported bulk action: ${action}`);
+      }
+
+      return processed;
+    });
+
+    return c.json({ success: true, count: result.length, data: result });
+  } catch (err: any) {
+    return c.json({ error: 'Bulk transaction rolled back', details: err.message }, 500);
+  }
+});
+
+