@aruvili/api 0.1.0

package/dist/routes/crud.js

@@ -0,0 +1,845 @@
+import { Hono } from 'hono';
+import { registry } from '../registry.js';
+import { query, withTransaction } from '../db.js';
+import { getTableName } from '@aruvili/core';
+import { controllerRegistry } 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();
+/**
+ * Helper to compute diff between old and new JSON objects for audit trail.
+ */
+function computeDiff(oldVal, newVal) {
+    const diff = {};
+    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, doctype, body) {
+    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');
+    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 = { db: client, user };
+            const docName = body.name || await generateDocumentName(client, definition, body);
+            const record = {
+                ...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 = ['name', 'created_by', 'modified_by', 'docstatus'];
+            const parentVals = [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 = {};
+            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];
+                    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 = [];
+                    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 = {
+                            ...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) {
+        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);
+    }
+});
+/**
+ * GET /api/doctype/:doctype
+ * Dynamic list endpoint with enterprise-safe SQL construction.
+ */
+crudRouter.get('/', async (c) => {
+    const doctypeName = c.req.param('doctype');
+    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 = [];
+    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 = [];
+    const params = [];
+    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) {
+        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');
+    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) {
+        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');
+    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 = { 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 = ['modified_by = $2', 'updated_at = NOW()', 'version = version + 1'];
+            const updateVals = [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 = {};
+            for (const field of definition.fields) {
+                if (field.fieldtype === 'Table') {
+                    const childDocTypeName = field.options;
+                    const childTable = getTableName(childDocTypeName);
+                    const childRowsInput = body[field.fieldname] || [];
+                    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 = [];
+                    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 = {
+                            ...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) {
+        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);
+    }
+});
+/**
+ * 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');
+    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 = { 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) {
+        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');
+    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 = { 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) {
+        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');
+    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 = { 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) {
+        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');
+    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) {
+        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');
+    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 = { 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 = {
+                ...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 = {};
+            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 = [];
+                    let idx = 1;
+                    for (const row of childRes.rows) {
+                        const childRecord = {
+                            ...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 = ['name', 'created_by', 'modified_by', 'docstatus', 'version', 'amended_from'];
+            const parentVals = [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) {
+        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');
+    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 = { db: client, user };
+            const processed = [];
+            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 = {
+                        ...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) {
+        return c.json({ error: 'Bulk transaction rolled back', details: err.message }, 500);
+    }
+});
+//# sourceMappingURL=crud.js.map