@nextsparkjs/core 0.1.0-beta.184 → 0.1.0-beta.186

package/dist/lib/api/entity/generic-handler.js

@@ -1,5 +1,5 @@
 import { NextResponse } from "next/server";
-import { authenticateRequest, hasRequiredScope, canBypassTeamContext } from "../auth/dual-auth.js";
+import { authenticateRequest, createAuthFailureResponse, canBypassTeamContext } from "../auth/dual-auth.js";
 import { resolveEntityFromUrl, validateEntityOperation } from "./resolver.js";
 import { generateEntitySchemas } from "../../entities/schema-generator.js";
 import { queryWithRLS, mutateWithRLS, queryOneWithRLS } from "../../db.js";
@@ -17,7 +17,8 @@ import {
   addCorsHeaders,
   handleCorsPreflightRequest
 } from "../helpers.js";
-import { afterEntityCreate, afterEntityUpdate, afterEntityDelete } from "../../entities/entity-hooks.js";
+import { beforeEntityCreate, afterEntityCreate, beforeEntityUpdate, afterEntityUpdate, beforeEntityDelete, afterEntityDelete, beforeEntityRead, afterEntityRead } from "../../entities/entity-hooks.js";
+import { logGenericHandlerUsage } from "./audit-log.js";
 import { checkPermission } from "../../permissions/check.js";
 import { extractPatternIds } from "../../blocks/pattern-resolver.js";
 import { isPatternReference } from "../../../types/pattern-reference.js";
@@ -169,6 +170,102 @@ function parseTaxonomyFilterParams(url, entityConfig) {
 function getTableName(entityConfig) {
   return entityConfig.tableName || entityConfig.slug;
 }
+function isEntityField(entityConfig, fieldName) {
+  return entityConfig.fields.some((field) => field.name === fieldName);
+}
+const LIST_RESERVED_PARAMS = /* @__PURE__ */ new Set([
+  "page",
+  "limit",
+  "fields",
+  "distinct",
+  "ids",
+  "parentId",
+  "search",
+  "sortBy",
+  "sortOrder",
+  "sort",
+  "order",
+  "child",
+  "meta",
+  "metas",
+  "includeMeta",
+  "userId",
+  "from",
+  "to",
+  "dateField",
+  "userFiltered"
+]);
+const TAXONOMY_FILTER_PARAMS = ["categoryId", "taxonomyId", "taxonomyType"];
+const SEARCHABLE_FIELDS = ["name", "title", "slug", "content"];
+const SORTABLE_BASE_FIELDS = ["id", "createdAt", "updatedAt", "teamId"];
+const BARE_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function omitHandlerManagedKeys(entityConfig, data) {
+  var _a;
+  const managed = /* @__PURE__ */ new Set(["userId", "teamId"]);
+  if ((_a = entityConfig.taxonomies) == null ? void 0 : _a.enabled) {
+    for (const taxonomyType of entityConfig.taxonomies.types ?? []) {
+      managed.add(taxonomyType.field);
+    }
+  }
+  return Object.fromEntries(Object.entries(data).filter(([key]) => !managed.has(key)));
+}
+function validationErrorMessage(issues) {
+  const unknownKeys = issues.filter((issue) => issue.code === "unrecognized_keys").flatMap((issue) => issue.keys ?? []);
+  return unknownKeys.length > 0 ? `Unknown field(s): ${unknownKeys.join(", ")}` : "Validation error";
+}
+function asPgError(error) {
+  if (error && typeof error === "object" && "code" in error && typeof error.code === "string") {
+    return error;
+  }
+  return null;
+}
+function mapConstraintViolation(error, operation) {
+  const pgError = asPgError(error);
+  if (!pgError) return null;
+  const { constraint, detail, table } = pgError;
+  switch (pgError.code) {
+    case "23505":
+      return createApiError(
+        "A record with this value already exists",
+        409,
+        { constraint, detail },
+        "UNIQUE_CONSTRAINT_VIOLATION"
+      );
+    case "23514":
+      return createApiError(
+        constraint ? `Value rejected by check constraint "${constraint}"` : "Value rejected by a database check constraint",
+        422,
+        { constraint, table },
+        "CHECK_CONSTRAINT_VIOLATION"
+      );
+    case "23503":
+      if (operation === "delete") {
+        return createApiError(
+          detail || "Cannot delete: this record is referenced by other records",
+          409,
+          { constraint },
+          "FOREIGN_KEY_VIOLATION"
+        );
+      }
+      return createApiError(
+        detail ? `Referenced record does not exist: ${detail}` : "Referenced record does not exist",
+        422,
+        { constraint, detail },
+        "FOREIGN_KEY_VIOLATION"
+      );
+    default:
+      return null;
+  }
+}
+function hookRejectionStatus(error) {
+  if (error && typeof error === "object") {
+    const candidate = error.status ?? error.statusCode;
+    if (typeof candidate === "number" && candidate >= 400 && candidate < 500) {
+      return candidate;
+    }
+  }
+  return 400;
+}
 async function filterOrphanedPatternReferences(blocks, userId) {
   if (!Array.isArray(blocks) || blocks.length === 0) return blocks;
   const patternIds = extractPatternIds(blocks);
@@ -193,11 +290,11 @@ function getTeamIdFromRequest(request) {
 function isBuilderRequest(request) {
   return request.headers.get("x-builder-source") === "true";
 }
-async function resolveOwnershipFilter(entityConfig, userId, teamId, isBypass, authType) {
+async function resolveOwnershipFilter(entityConfig, userId, teamId, isBypass) {
   var _a;
   const ownershipFilter = (_a = entityConfig.access) == null ? void 0 : _a.ownershipFilter;
   if (!ownershipFilter) return { applies: false };
-  if (isBypass || authType === "api-key") return { applies: false };
+  if (isBypass) return { applies: false };
   const memberRow = await queryOneWithRLS(
     'SELECT role FROM "team_members" WHERE "teamId" = $1 AND "userId" = $2',
     [teamId, userId],
@@ -221,9 +318,9 @@ async function resolveOwnershipFilter(entityConfig, userId, teamId, isBypass, au
   const filterValue = linkedRow ? linkedRow[valueField] ?? null : null;
   return { applies: true, field: ownershipFilter.field, value: filterValue };
 }
-async function checkSessionPermission(authResult, entitySlug, action, teamId, request) {
+async function checkAuthPermission(authResult, entitySlug, action, teamId, request) {
   var _a;
-  if (authResult.type !== "session" || !((_a = authResult.user) == null ? void 0 : _a.id)) return null;
+  if (!((_a = authResult.user) == null ? void 0 : _a.id)) return null;
   const permission = `${entitySlug}.${action}`;
   try {
     const allowed = await checkPermission(authResult.user.id, teamId, permission);
@@ -291,7 +388,24 @@ async function validateTeamContextWithBypass(request, authResult, userId) {
   }
   return { valid: true, teamId, isBypass: false };
 }
+async function runWithAuditLog(request, run) {
+  const startedAt = Date.now();
+  const audit = { auth: null };
+  let statusCode = 500;
+  try {
+    const response = await run(audit);
+    statusCode = response.status;
+    return response;
+  } finally {
+    logGenericHandlerUsage(audit.auth, request, statusCode, Date.now() - startedAt).catch((error) => {
+      console.error("[generic-handler:audit] unexpected audit failure:", error);
+    });
+  }
+}
 async function handleGenericList(request) {
+  return runWithAuditLog(request, (audit) => handleGenericListImpl(request, audit));
+}
+async function handleGenericListImpl(request, audit) {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
   try {
     const resolution = await resolveEntityFromUrl(request.nextUrl.pathname);
@@ -303,25 +417,22 @@ async function handleGenericList(request) {
       const response2 = createApiError("List operation not supported for this entity", 405);
       return addCorsHeaders(response2, request);
     }
-    const authResult = await authenticateRequest(request);
+    const authResult = await authenticateRequest(request, { requiredScope: `${resolution.entityConfig.slug}:read` });
+    audit.auth = authResult;
     let userId = null;
     let teamId = null;
     let isBypass = false;
+    if (!authResult.success && authResult.type === "api-key") {
+      return addCorsHeaders(createAuthFailureResponse(authResult), request);
+    }
     if (!authResult.success && ((_a = resolution.entityConfig.access) == null ? void 0 : _a.public)) {
       teamId = request.headers.get("x-team-id") ?? null;
     } else if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: "Authentication required", code: "AUTHENTICATION_FAILED" },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     } else {
       if (authResult.rateLimitResponse) {
         return authResult.rateLimitResponse;
       }
-      if (!hasRequiredScope(authResult, `${resolution.entityConfig.slug}:read`)) {
-        const response2 = createApiError("Insufficient permissions", 403);
-        return addCorsHeaders(response2, request);
-      }
       userId = authResult.user.id;
       const teamValidation = await validateTeamContextWithBypass(request, authResult, userId);
       if (!teamValidation.valid) {
@@ -330,7 +441,7 @@ async function handleGenericList(request) {
       teamId = teamValidation.teamId;
       isBypass = teamValidation.isBypass;
       if (!isBypass && teamId) {
-        const permDenied = await checkSessionPermission(authResult, resolution.entityConfig.slug, "list", teamId, request);
+        const permDenied = await checkAuthPermission(authResult, resolution.entityConfig.slug, "list", teamId, request);
         if (permDenied) return permDenied;
       }
     }
@@ -341,10 +452,9 @@ async function handleGenericList(request) {
     const distinctParam = url.searchParams.get("distinct") === "true";
     const idsFromParams = url.searchParams.getAll("ids");
     const specificIds = idsFromParams.length > 0 ? idsFromParams.flatMap((param) => param.split(",").map((id) => id.trim())).filter(Boolean) : null;
-    const knownParams = /* @__PURE__ */ new Set(["page", "limit", "fields", "distinct", "ids", "parentId", "search", "sortBy", "sortOrder", "child", "meta", "from", "to", "dateField"]);
     const customFilters = {};
     url.searchParams.forEach((value, key) => {
-      if (!knownParams.has(key) && value) {
+      if (!LIST_RESERVED_PARAMS.has(key) && value) {
         if (!customFilters[key]) {
           customFilters[key] = [];
         }
@@ -353,9 +463,59 @@ async function handleGenericList(request) {
       }
     });
     const entityConfig = resolution.entityConfig;
+    const shapedQuery = await beforeEntityRead(entityConfig.slug, { ...customFilters }, userId ?? void 0);
+    for (const [key, value] of Object.entries(shapedQuery)) {
+      customFilters[key] = Array.isArray(value) ? value.map(String) : [String(value)];
+    }
+    const taxonomyFilterParams = ((_b = entityConfig.taxonomies) == null ? void 0 : _b.enabled) ? TAXONOMY_FILTER_PARAMS : [];
+    const invalidFilterKeys = Object.keys(customFilters).filter(
+      (key) => !isEntityField(entityConfig, key) && !taxonomyFilterParams.includes(key)
+    );
+    if (invalidFilterKeys.length > 0) {
+      const response2 = createApiError(
+        `Unknown filter parameter(s) for ${entityConfig.slug}: ${invalidFilterKeys.join(", ")}`,
+        400,
+        {
+          invalidKeys: invalidFilterKeys,
+          allowedKeys: [...entityConfig.fields.map((f) => f.name), ...taxonomyFilterParams]
+        },
+        "INVALID_FILTER"
+      );
+      return addCorsHeaders(response2, request);
+    }
+    const searchParam = url.searchParams.get("search");
+    const searchableFields = SEARCHABLE_FIELDS.filter((name) => isEntityField(entityConfig, name));
+    if (searchParam && searchParam.trim() !== "" && searchableFields.length === 0) {
+      const response2 = createApiError(
+        `Entity ${entityConfig.slug} has no searchable field (${SEARCHABLE_FIELDS.join(", ")}); the search parameter is not supported`,
+        400,
+        { searchableFields: SEARCHABLE_FIELDS },
+        "SEARCH_NOT_SUPPORTED"
+      );
+      return addCorsHeaders(response2, request);
+    }
+    const sortByParam = url.searchParams.get("sortBy") || url.searchParams.get("sort");
+    if (sortByParam && !isEntityField(entityConfig, sortByParam) && !SORTABLE_BASE_FIELDS.includes(sortByParam)) {
+      const response2 = createApiError(
+        `Invalid sortBy field for ${entityConfig.slug}: ${sortByParam}`,
+        400,
+        { allowedFields: [...SORTABLE_BASE_FIELDS, ...entityConfig.fields.map((f) => f.name)] },
+        "INVALID_SORT_FIELD"
+      );
+      return addCorsHeaders(response2, request);
+    }
     let fields;
     if (fieldsParam && distinctParam) {
       const fieldName = fieldsParam;
+      if (!isEntityField(entityConfig, fieldName)) {
+        const response2 = createApiError(
+          `Invalid field for distinct query: ${fieldName}`,
+          400,
+          void 0,
+          "INVALID_FIELD"
+        );
+        return addCorsHeaders(response2, request);
+      }
       const isJsonbField = fieldName === "contentLanguages" || fieldName === "brandValues" || fieldName === "hashtags";
       if (isJsonbField) {
         return handleDistinctJsonbField(entityConfig, fieldName, url, userId);
@@ -364,19 +524,17 @@ async function handleGenericList(request) {
       }
     } else if (fieldsParam) {
       const requestedFields = fieldsParam.split(",").map((f) => f.trim());
-      const validFields = requestedFields.filter(
-        (fieldName) => entityConfig.fields.some((field) => field.name === fieldName)
-      );
+      const validFields = requestedFields.filter((fieldName) => isEntityField(entityConfig, fieldName));
       fields = ["id", ...validFields].map((fieldName) => {
         const columnName = /[A-Z]/.test(fieldName) ? `"${fieldName}"` : fieldName;
         return `t.${columnName}`;
       }).join(", ");
     } else {
       const systemFields = ["id", "userId", "teamId", "createdAt", "updatedAt"];
-      if ((_b = entityConfig.builder) == null ? void 0 : _b.enabled) {
+      if ((_c = entityConfig.builder) == null ? void 0 : _c.enabled) {
         systemFields.push("blocks");
       }
-      if ((_c = entityConfig.table) == null ? void 0 : _c.softDelete) {
+      if ((_d = entityConfig.table) == null ? void 0 : _d.softDelete) {
         systemFields.push("deletedAt", "deletedBy");
       }
       const configFields = entityConfig.fields.map((field) => {
@@ -395,12 +553,11 @@ async function handleGenericList(request) {
     let query;
     let queryParams;
     let paramIndex = 1;
-    const searchParam = url.searchParams.get("search");
     const fromDate = url.searchParams.get("from");
     const toDate = url.searchParams.get("to");
     const dateFieldName = url.searchParams.get("dateField");
-    const isPublicEntity = ((_d = entityConfig.access) == null ? void 0 : _d.public) === true;
-    const requestingPublishedOnly = (_e = customFilters["status"]) == null ? void 0 : _e.includes("published");
+    const isPublicEntity = ((_e = entityConfig.access) == null ? void 0 : _e.public) === true;
+    const requestingPublishedOnly = (_f = customFilters["status"]) == null ? void 0 : _f.includes("published");
     const skipUserFilter = isPublicEntity && requestingPublishedOnly;
     if (skipUserFilter && process.env.NODE_ENV === "development") {
       console.log(`[GenericHandler] Public access mode: skipping userId filter for ${entityConfig.slug} (status=published)`);
@@ -413,8 +570,7 @@ async function handleGenericList(request) {
         entityConfig,
         userId,
         teamId,
-        isBypass,
-        authResult.type
+        isBypass
       );
     }
     if (ownershipFilter.applies && ownershipFilter.value === null) {
@@ -430,7 +586,7 @@ async function handleGenericList(request) {
         query += ` AND t."teamId" = $${paramIndex++}`;
         queryParams.push(teamId);
       }
-      if (userId && !((_f = entityConfig.access) == null ? void 0 : _f.shared) && !skipUserFilter && !isBypass) {
+      if (userId && !((_g = entityConfig.access) == null ? void 0 : _g.shared) && !skipUserFilter && !isBypass) {
         query += ` AND t."userId" = $${paramIndex++}`;
         queryParams.push(userId);
       }
@@ -438,7 +594,7 @@ async function handleGenericList(request) {
         query += ` AND t."${ownershipFilter.field}" = $${paramIndex++}`;
         queryParams.push(ownershipFilter.value);
       }
-      if (((_g = entityConfig.table) == null ? void 0 : _g.softDelete) && !isBypass) {
+      if (((_h = entityConfig.table) == null ? void 0 : _h.softDelete) && !isBypass) {
         query += ` AND t."deletedAt" IS NULL`;
       }
     } else if (fieldsParam && distinctParam) {
@@ -454,7 +610,7 @@ async function handleGenericList(request) {
         query += ` AND t."parentId" = $${paramIndex++}`;
         queryParams.push(parentId);
       }
-      if (userId && !((_h = entityConfig.access) == null ? void 0 : _h.shared) && !skipUserFilter && !isBypass) {
+      if (userId && !((_i = entityConfig.access) == null ? void 0 : _i.shared) && !skipUserFilter && !isBypass) {
         query += ` AND t."userId" = $${paramIndex++}`;
         queryParams.push(userId);
       }
@@ -462,7 +618,7 @@ async function handleGenericList(request) {
         query += ` AND t."${ownershipFilter.field}" = $${paramIndex++}`;
         queryParams.push(ownershipFilter.value);
       }
-      if (((_i = entityConfig.table) == null ? void 0 : _i.softDelete) && !isBypass) {
+      if (((_j = entityConfig.table) == null ? void 0 : _j.softDelete) && !isBypass) {
         query += ` AND t."deletedAt" IS NULL`;
       }
       query += ` ORDER BY "${fieldName}" ASC LIMIT $${paramIndex++}`;
@@ -475,7 +631,7 @@ async function handleGenericList(request) {
         whereConditions.push(`t."teamId" = $${paramIndex++}`);
         queryParams.push(teamId);
       }
-      if (userId && !((_j = entityConfig.access) == null ? void 0 : _j.shared) && !skipUserFilter && !isBypass) {
+      if (userId && !((_k = entityConfig.access) == null ? void 0 : _k.shared) && !skipUserFilter && !isBypass) {
         whereConditions.push(`t."userId" = $${paramIndex++}`);
         queryParams.push(userId);
       }
@@ -483,33 +639,15 @@ async function handleGenericList(request) {
         whereConditions.push(`t."${ownershipFilter.field}" = $${paramIndex++}`);
         queryParams.push(ownershipFilter.value);
       }
-      if (((_k = entityConfig.table) == null ? void 0 : _k.softDelete) && !isBypass) {
+      if (((_l = entityConfig.table) == null ? void 0 : _l.softDelete) && !isBypass) {
         whereConditions.push(`t."deletedAt" IS NULL`);
       }
-      if (searchParam && searchParam.trim() !== "") {
+      if (searchParam && searchParam.trim() !== "" && searchableFields.length > 0) {
         const searchTerm = searchParam.trim();
-        const hasName = entityConfig.fields.some((f) => f.name === "name");
-        const hasTitle = entityConfig.fields.some((f) => f.name === "title");
-        const hasSlug = entityConfig.fields.some((f) => f.name === "slug");
-        const hasContent = entityConfig.fields.some((f) => f.name === "content");
-        if (hasName || hasTitle || hasSlug || hasContent) {
-          const searchConditions = [];
-          if (hasName) {
-            searchConditions.push(`t.name ILIKE $${paramIndex}`);
-          }
-          if (hasTitle) {
-            searchConditions.push(`t.title ILIKE $${paramIndex}`);
-          }
-          if (hasSlug) {
-            searchConditions.push(`t.slug ILIKE $${paramIndex}`);
-          }
-          if (hasContent) {
-            searchConditions.push(`t.content ILIKE $${paramIndex}`);
-          }
-          whereConditions.push(`(${searchConditions.join(" OR ")})`);
-          queryParams.push(`%${searchTerm}%`);
-          paramIndex++;
-        }
+        const searchConditions = searchableFields.map((name) => `t.${name} ILIKE $${paramIndex}`);
+        whereConditions.push(`(${searchConditions.join(" OR ")})`);
+        queryParams.push(`%${searchTerm}%`);
+        paramIndex++;
       }
       if (dateFieldName && (fromDate || toDate)) {
         const field = entityConfig.fields.find((f) => f.name === dateFieldName);
@@ -537,6 +675,18 @@ async function handleGenericList(request) {
               queryParams.push(JSON.stringify([value]));
             });
             whereConditions.push(`(${orConditions.join(" OR ")})`);
+          } else if (field.type === "date" || field.type === "datetime") {
+            const orConditions = values.map((value) => {
+              if (BARE_DATE_RE.test(value)) {
+                const lower = paramIndex++;
+                const upper = paramIndex++;
+                queryParams.push(value, value);
+                return `(t.${columnName} >= $${lower}::date AND t.${columnName} < $${upper}::date + 1)`;
+              }
+              queryParams.push(value);
+              return `t.${columnName} = $${paramIndex++}`;
+            });
+            whereConditions.push(`(${orConditions.join(" OR ")})`);
           } else {
             const orConditions = values.map(() => {
               const condition = `t.${columnName} = $${paramIndex++}`;
@@ -569,16 +719,9 @@ async function handleGenericList(request) {
           ) pu ON t.id = pu."patternId"
         `;
       }
-      const sortByParam = url.searchParams.get("sortBy");
-      const sortOrderParam = ((_l = url.searchParams.get("sortOrder")) == null ? void 0 : _l.toUpperCase()) === "ASC" ? "ASC" : "DESC";
-      let orderByClause = 't."createdAt" DESC';
-      if (sortByParam) {
-        const baseFields = ["id", "createdAt", "updatedAt", "teamId"];
-        const isValidField = entityConfig.fields.some((f) => f.name === sortByParam) || baseFields.includes(sortByParam);
-        if (isValidField) {
-          orderByClause = `t."${sortByParam}" ${sortOrderParam}`;
-        }
-      }
+      const sortOrderRaw = url.searchParams.get("sortOrder") || url.searchParams.get("order");
+      const sortOrderParam = (sortOrderRaw == null ? void 0 : sortOrderRaw.toUpperCase()) === "ASC" ? "ASC" : "DESC";
+      const orderByClause = sortByParam ? `t."${sortByParam}" ${sortOrderParam}` : 't."createdAt" DESC';
       query = `
         SELECT ${fields}, COUNT(*) OVER() as total_count
         FROM "${tableName}" t
@@ -625,7 +768,8 @@ async function handleGenericList(request) {
       );
     }
     const finalData = filterPublicFields(dataWithTaxonomies, entityConfig, userId);
-    const response = createApiResponse(finalData, paginationMeta);
+    const shapedData = await afterEntityRead(entityConfig.slug, finalData, { ...customFilters }, userId ?? void 0);
+    const response = createApiResponse(shapedData, paginationMeta);
     return addCorsHeaders(response, request);
   } catch (error) {
     console.error("Error in generic list handler:", error);
@@ -634,6 +778,9 @@ async function handleGenericList(request) {
   }
 }
 async function handleGenericCreate(request) {
+  return runWithAuditLog(request, (audit) => handleGenericCreateImpl(request, audit));
+}
+async function handleGenericCreateImpl(request, audit) {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
   try {
     const resolution = await resolveEntityFromUrl(request.nextUrl.pathname);
@@ -645,20 +792,14 @@ async function handleGenericCreate(request) {
       const response2 = createApiError("Create operation not supported for this entity", 405);
       return addCorsHeaders(response2, request);
     }
-    const authResult = await authenticateRequest(request);
+    const authResult = await authenticateRequest(request, { requiredScope: `${resolution.entityConfig.slug}:write` });
+    audit.auth = authResult;
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: "Authentication required", code: "AUTHENTICATION_FAILED" },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     }
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse;
     }
-    if (!hasRequiredScope(authResult, `${resolution.entityConfig.slug}:write`)) {
-      const response2 = createApiError("Insufficient permissions", 403);
-      return addCorsHeaders(response2, request);
-    }
     let body;
     try {
       body = await request.json();
@@ -671,16 +812,21 @@ async function handleGenericCreate(request) {
     const entityConfig = resolution.entityConfig;
     const tableName = getTableName(entityConfig);
     const schemas = generateEntitySchemas(entityConfig);
-    const validation = schemas.create.safeParse(entityData);
+    const validation = schemas.create.safeParse(omitHandlerManagedKeys(entityConfig, entityData));
     if (!validation.success) {
       console.error(`[${entityConfig.slug}] Validation failed:`, {
         entityData,
         errors: validation.error.issues
       });
-      const response2 = createApiError("Validation error", 400, validation.error.issues, "VALIDATION_ERROR");
+      const response2 = createApiError(
+        validationErrorMessage(validation.error.issues),
+        400,
+        validation.error.issues,
+        "VALIDATION_ERROR"
+      );
       return addCorsHeaders(response2, request);
     }
-    const validatedData = validation.data;
+    let validatedData = validation.data;
     const xssField = checkNameFieldXss(entityConfig, validatedData);
     if (xssField) {
       const xssResponse = createApiError(
@@ -714,8 +860,24 @@ async function handleGenericCreate(request) {
       const response2 = createApiError("Team context required for create operations. Include x-team-id header.", 400, void 0, "TEAM_CONTEXT_REQUIRED");
       return addCorsHeaders(response2, request);
     }
-    const permDenied = await checkSessionPermission(authResult, entityConfig.slug, "create", teamId, request);
+    const permDenied = await checkAuthPermission(authResult, entityConfig.slug, "create", teamId, request);
     if (permDenied) return permDenied;
+    try {
+      validatedData = await beforeEntityCreate(
+        entityConfig.slug,
+        { ...validatedData, userId: userIdToUse, teamId },
+        authResult.user.id
+      );
+    } catch (hookError) {
+      console.error(`[generic-handler] beforeEntityCreate rejected ${entityConfig.slug} create:`, hookError);
+      const response2 = createApiError(
+        hookError instanceof Error && hookError.message ? hookError.message : `Create rejected by ${entityConfig.slug} before_create hook`,
+        hookRejectionStatus(hookError),
+        void 0,
+        "BEFORE_CREATE_REJECTED"
+      );
+      return addCorsHeaders(response2, request);
+    }
     if (idStrategy === "serial") {
       insertFields = ['"userId"', '"teamId"'];
       placeholders = ["$1", "$2"];
@@ -801,6 +963,7 @@ async function handleGenericCreate(request) {
       if (!actionResult.allowed) {
         const statusCode = actionResult.reason === "quota_exceeded" ? 429 : 403;
         const response2 = createApiError(
+          // @ts-expect-error — pre-existing type error, tracked in https://github.com/NextSpark-js/nextspark/issues/131
           actionResult.message || `Quota exceeded for ${entityConfig.slug}`,
           statusCode,
           void 0,
@@ -883,22 +1046,18 @@ async function handleGenericCreate(request) {
     return addCorsHeaders(response, request);
   } catch (error) {
     console.error("Error in generic create handler:", error);
-    if (error && typeof error === "object" && "code" in error && error.code === "23505") {
-      const detail = "detail" in error ? error.detail : void 0;
-      const constraint = "constraint" in error ? error.constraint : void 0;
-      const response2 = createApiError(
-        "A record with this value already exists",
-        409,
-        { constraint, detail },
-        "UNIQUE_CONSTRAINT_VIOLATION"
-      );
-      return addCorsHeaders(response2, request);
+    const constraintResponse = mapConstraintViolation(error, "create");
+    if (constraintResponse) {
+      return addCorsHeaders(constraintResponse, request);
     }
     const response = createApiError("Internal server error", 500);
     return addCorsHeaders(response, request);
   }
 }
 async function handleGenericRead(request, { params }) {
+  return runWithAuditLog(request, (audit) => handleGenericReadImpl(request, audit, { params }));
+}
+async function handleGenericReadImpl(request, audit, { params }) {
   var _a, _b, _c, _d, _e, _f;
   try {
     const { id } = await params;
@@ -911,25 +1070,22 @@ async function handleGenericRead(request, { params }) {
       const response2 = createApiError("Read operation not supported for this entity", 405);
       return addCorsHeaders(response2, request);
     }
-    const authResult = await authenticateRequest(request);
+    const authResult = await authenticateRequest(request, { requiredScope: `${resolution.entityConfig.slug}:read` });
+    audit.auth = authResult;
     let userId = null;
     let teamId = null;
     let isBypass = false;
+    if (!authResult.success && authResult.type === "api-key") {
+      return addCorsHeaders(createAuthFailureResponse(authResult), request);
+    }
     if (!authResult.success && ((_a = resolution.entityConfig.access) == null ? void 0 : _a.public)) {
       console.log(`[GenericHandler] Public access allowed for ${resolution.entityConfig.slug} read`);
     } else if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: "Authentication required", code: "AUTHENTICATION_FAILED" },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     } else {
       if (authResult.rateLimitResponse) {
         return authResult.rateLimitResponse;
       }
-      if (!hasRequiredScope(authResult, `${resolution.entityConfig.slug}:read`)) {
-        const response2 = createApiError("Insufficient permissions", 403);
-        return addCorsHeaders(response2, request);
-      }
       userId = authResult.user.id;
       const teamValidation = await validateTeamContextWithBypass(request, authResult, userId);
       if (!teamValidation.valid) {
@@ -938,7 +1094,7 @@ async function handleGenericRead(request, { params }) {
       teamId = teamValidation.teamId;
       isBypass = teamValidation.isBypass;
       if (!isBypass && teamId) {
-        const permDenied = await checkSessionPermission(authResult, resolution.entityConfig.slug, "read", teamId, request);
+        const permDenied = await checkAuthPermission(authResult, resolution.entityConfig.slug, "read", teamId, request);
         if (permDenied) return permDenied;
       }
     }
@@ -982,8 +1138,7 @@ async function handleGenericRead(request, { params }) {
         entityConfig,
         userId,
         teamId,
-        isBypass,
-        authResult.type
+        isBypass
       );
       if (readOwnershipFilter.applies) {
         if (readOwnershipFilter.value === null) {
@@ -1036,7 +1191,8 @@ async function handleGenericRead(request, { params }) {
       itemWithTaxonomies = itemsWithTaxonomies[0] || itemWithChild;
     }
     const finalItem = filterPublicFields(itemWithTaxonomies, entityConfig, userId);
-    const response = createApiResponse(finalItem);
+    const [shapedItem] = await afterEntityRead(entityConfig.slug, [finalItem], { id }, userId ?? void 0);
+    const response = createApiResponse(shapedItem ?? finalItem);
     return addCorsHeaders(response, request);
   } catch (error) {
     console.error("Error in generic read handler:", error);
@@ -1045,7 +1201,10 @@ async function handleGenericRead(request, { params }) {
   }
 }
 async function handleGenericUpdate(request, { params }) {
-  var _a, _b, _c, _d, _e, _f;
+  return runWithAuditLog(request, (audit) => handleGenericUpdateImpl(request, audit, { params }));
+}
+async function handleGenericUpdateImpl(request, audit, { params }) {
+  var _a, _b, _c, _d, _e, _f, _g;
   try {
     const { id } = await params;
     const resolution = await resolveEntityFromUrl(request.nextUrl.pathname);
@@ -1057,20 +1216,14 @@ async function handleGenericUpdate(request, { params }) {
       const response2 = createApiError("Update operation not supported for this entity", 405);
       return addCorsHeaders(response2, request);
     }
-    const authResult = await authenticateRequest(request);
+    const authResult = await authenticateRequest(request, { requiredScope: `${resolution.entityConfig.slug}:write` });
+    audit.auth = authResult;
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: "Authentication required", code: "AUTHENTICATION_FAILED" },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     }
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse;
     }
-    if (!hasRequiredScope(authResult, `${resolution.entityConfig.slug}:write`)) {
-      const response2 = createApiError("Insufficient permissions", 403);
-      return addCorsHeaders(response2, request);
-    }
     const teamValidation = await validateTeamContextWithBypass(request, authResult, authResult.user.id);
     if (!teamValidation.valid) {
       return teamValidation.error;
@@ -1080,7 +1233,7 @@ async function handleGenericUpdate(request, { params }) {
       const response2 = createApiError("Team context required for update operations. Include x-team-id header.", 400, void 0, "TEAM_CONTEXT_REQUIRED");
       return addCorsHeaders(response2, request);
     }
-    const permDenied = await checkSessionPermission(authResult, resolution.entityConfig.slug, "update", teamId, request);
+    const permDenied = await checkAuthPermission(authResult, resolution.entityConfig.slug, "update", teamId, request);
     if (permDenied) return permDenied;
     let body;
     try {
@@ -1092,7 +1245,7 @@ async function handleGenericUpdate(request, { params }) {
     const { metas, ...entityData } = body;
     const entityConfig = resolution.entityConfig;
     const fieldGuards = (_b = (_a = entityConfig.access) == null ? void 0 : _a.ownershipFilter) == null ? void 0 : _b.fieldGuards;
-    if (fieldGuards && fieldGuards.length > 0 && authResult.type === "session") {
+    if (fieldGuards && fieldGuards.length > 0 && ((_c = authResult.user) == null ? void 0 : _c.id)) {
       const guardMemberRow = await queryOneWithRLS(
         'SELECT role FROM "team_members" WHERE "teamId" = $1 AND "userId" = $2',
         [teamId, authResult.user.id],
@@ -1117,16 +1270,21 @@ async function handleGenericUpdate(request, { params }) {
     }
     const tableName = getTableName(entityConfig);
     const schemas = generateEntitySchemas(entityConfig);
-    const validation = schemas.update.safeParse(entityData);
+    const validation = schemas.update.safeParse(omitHandlerManagedKeys(entityConfig, entityData));
     if (!validation.success) {
       console.log(`[${entityConfig.slug}] Validation failed:`, {
         entityData,
         errors: validation.error.issues
       });
-      const response2 = createApiError("Validation error", 400, validation.error.issues, "VALIDATION_ERROR");
+      const response2 = createApiError(
+        validationErrorMessage(validation.error.issues),
+        400,
+        validation.error.issues,
+        "VALIDATION_ERROR"
+      );
       return addCorsHeaders(response2, request);
     }
-    const validatedData = validation.data;
+    let validatedData = validation.data;
     const updateXssField = checkNameFieldXss(entityConfig, validatedData);
     if (updateXssField) {
       const updateXssResponse = createApiError(
@@ -1137,11 +1295,28 @@ async function handleGenericUpdate(request, { params }) {
       );
       return addCorsHeaders(updateXssResponse, request);
     }
+    try {
+      validatedData = await beforeEntityUpdate(
+        entityConfig.slug,
+        id,
+        validatedData,
+        authResult.user.id
+      );
+    } catch (hookError) {
+      console.error(`[generic-handler] beforeEntityUpdate rejected ${entityConfig.slug} update:`, hookError);
+      const response2 = createApiError(
+        hookError instanceof Error && hookError.message ? hookError.message : `Update rejected by ${entityConfig.slug} before_update hook`,
+        hookRejectionStatus(hookError),
+        void 0,
+        "BEFORE_UPDATE_REJECTED"
+      );
+      return addCorsHeaders(response2, request);
+    }
     const updates = [];
     const values = [];
     let paramCount = 1;
     const builderRequest = isBuilderRequest(request);
-    const entityHasBuilder = ((_c = entityConfig.builder) == null ? void 0 : _c.enabled) === true;
+    const entityHasBuilder = ((_d = entityConfig.builder) == null ? void 0 : _d.enabled) === true;
     if (builderRequest && entityHasBuilder && "blocks" in entityData) {
       let blocksData = entityData.blocks;
       blocksData = await filterOrphanedPatternReferences(blocksData, authResult.user.id);
@@ -1217,7 +1392,7 @@ async function handleGenericUpdate(request, { params }) {
         whereConditions.push(`"teamId" = $${paramCount++}`);
         values.push(teamId);
       }
-      if (!((_d = entityConfig.access) == null ? void 0 : _d.shared)) {
+      if (!((_e = entityConfig.access) == null ? void 0 : _e.shared)) {
         whereConditions.push(`"userId" = $${paramCount++}`);
         values.push(authResult.user.id);
       }
@@ -1225,8 +1400,7 @@ async function handleGenericUpdate(request, { params }) {
         entityConfig,
         authResult.user.id,
         teamId,
-        teamValidation.isBypass,
-        authResult.type
+        teamValidation.isBypass
       );
       if (updateOwnershipFilter.applies) {
         if (updateOwnershipFilter.value === null) {
@@ -1262,7 +1436,7 @@ async function handleGenericUpdate(request, { params }) {
       }
       updatedItem = result[0];
     }
-    if ((_e = entityConfig.taxonomies) == null ? void 0 : _e.enabled) {
+    if ((_f = entityConfig.taxonomies) == null ? void 0 : _f.enabled) {
       await processTaxonomyRelations(entityConfig, id, body, authResult.user.id, true);
     }
     if (metadataWasProvided) {
@@ -1274,7 +1448,7 @@ async function handleGenericUpdate(request, { params }) {
       );
     }
     let responseItem = updatedItem;
-    if ((_f = entityConfig.taxonomies) == null ? void 0 : _f.enabled) {
+    if ((_g = entityConfig.taxonomies) == null ? void 0 : _g.enabled) {
       const itemsWithTaxonomies = await includeTaxonomiesInData(
         entityConfig,
         [updatedItem],
@@ -1297,22 +1471,18 @@ async function handleGenericUpdate(request, { params }) {
     return addCorsHeaders(response, request);
   } catch (error) {
     console.error("Error in generic update handler:", error);
-    if (error && typeof error === "object" && "code" in error && error.code === "23505") {
-      const detail = "detail" in error ? error.detail : void 0;
-      const constraint = "constraint" in error ? error.constraint : void 0;
-      const response2 = createApiError(
-        "A record with this value already exists",
-        409,
-        { constraint, detail },
-        "UNIQUE_CONSTRAINT_VIOLATION"
-      );
-      return addCorsHeaders(response2, request);
+    const constraintResponse = mapConstraintViolation(error, "update");
+    if (constraintResponse) {
+      return addCorsHeaders(constraintResponse, request);
     }
     const response = createApiError("Internal server error", 500);
     return addCorsHeaders(response, request);
   }
 }
 async function handleGenericDelete(request, { params }) {
+  return runWithAuditLog(request, (audit) => handleGenericDeleteImpl(request, audit, { params }));
+}
+async function handleGenericDeleteImpl(request, audit, { params }) {
   var _a, _b, _c, _d, _e;
   try {
     const { id } = await params;
@@ -1325,20 +1495,14 @@ async function handleGenericDelete(request, { params }) {
       const response2 = createApiError("Delete operation not supported for this entity", 405);
       return addCorsHeaders(response2, request);
     }
-    const authResult = await authenticateRequest(request);
+    const authResult = await authenticateRequest(request, { requiredScope: `${resolution.entityConfig.slug}:delete` });
+    audit.auth = authResult;
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: "Authentication required", code: "AUTHENTICATION_FAILED" },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     }
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse;
     }
-    if (!hasRequiredScope(authResult, `${resolution.entityConfig.slug}:write`)) {
-      const response2 = createApiError("Insufficient permissions", 403);
-      return addCorsHeaders(response2, request);
-    }
     const teamValidation = await validateTeamContextWithBypass(request, authResult, authResult.user.id);
     if (!teamValidation.valid) {
       return teamValidation.error;
@@ -1348,10 +1512,31 @@ async function handleGenericDelete(request, { params }) {
       const response2 = createApiError("Team context required for delete operations. Include x-team-id header.", 400, void 0, "TEAM_CONTEXT_REQUIRED");
       return addCorsHeaders(response2, request);
     }
-    const permDenied = await checkSessionPermission(authResult, resolution.entityConfig.slug, "delete", teamId, request);
+    const permDenied = await checkAuthPermission(authResult, resolution.entityConfig.slug, "delete", teamId, request);
     if (permDenied) return permDenied;
     const entityConfig = resolution.entityConfig;
     const tableName = getTableName(entityConfig);
+    try {
+      const allowDelete = await beforeEntityDelete(entityConfig.slug, id, authResult.user.id);
+      if (!allowDelete) {
+        const response2 = createApiError(
+          `Delete rejected by ${entityConfig.slug} before_delete hook`,
+          403,
+          void 0,
+          "BEFORE_DELETE_REJECTED"
+        );
+        return addCorsHeaders(response2, request);
+      }
+    } catch (hookError) {
+      console.error(`[generic-handler] beforeEntityDelete rejected ${entityConfig.slug} delete:`, hookError);
+      const response2 = createApiError(
+        hookError instanceof Error && hookError.message ? hookError.message : `Delete rejected by ${entityConfig.slug} before_delete hook`,
+        hookRejectionStatus(hookError),
+        void 0,
+        "BEFORE_DELETE_REJECTED"
+      );
+      return addCorsHeaders(response2, request);
+    }
     const whereConditions = ["id = $1"];
     const deleteParams = [id];
     let paramIndex = 2;
@@ -1408,16 +1593,9 @@ async function handleGenericDelete(request, { params }) {
     return addCorsHeaders(response, request);
   } catch (error) {
     console.error("Error in generic delete handler:", error);
-    if (error && typeof error === "object" && "code" in error && error.code === "23503") {
-      const detail = "detail" in error ? error.detail : void 0;
-      const constraint = "constraint" in error ? error.constraint : void 0;
-      const response2 = createApiError(
-        detail || "Cannot delete: this record is referenced by other records",
-        409,
-        { constraint },
-        "FOREIGN_KEY_VIOLATION"
-      );
-      return addCorsHeaders(response2, request);
+    const constraintResponse = mapConstraintViolation(error, "delete");
+    if (constraintResponse) {
+      return addCorsHeaders(constraintResponse, request);
     }
     const response = createApiError("Internal server error", 500);
     return addCorsHeaders(response, request);