@nextsparkjs/core 0.1.0-beta.185 → 0.1.0-beta.187

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);
@@ -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) {
@@ -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,16 +553,16 @@ 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)`);
     }
+    const forcePublishedOnly = isPublicEntity && userId === null && entityConfig.fields.some((f) => f.name === "status");
     const tableName = getTableName(entityConfig);
     const taxonomyFilter = parseTaxonomyFilterParams(url, entityConfig);
     let ownershipFilter = { applies: false };
@@ -429,7 +587,10 @@ 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 (forcePublishedOnly) {
+        query += ` AND t."status" = 'published'`;
+      }
+      if (userId && !((_g = entityConfig.access) == null ? void 0 : _g.shared) && !skipUserFilter && !isBypass) {
         query += ` AND t."userId" = $${paramIndex++}`;
         queryParams.push(userId);
       }
@@ -437,7 +598,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) {
@@ -453,7 +614,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);
       }
@@ -461,9 +622,12 @@ 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`;
       }
+      if (forcePublishedOnly) {
+        query += ` AND t."status" = 'published'`;
+      }
       query += ` ORDER BY "${fieldName}" ASC LIMIT $${paramIndex++}`;
       queryParams.push(pagination.limit);
     } else {
@@ -474,7 +638,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);
       }
@@ -482,33 +646,18 @@ 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 (forcePublishedOnly) {
+        whereConditions.push(`t."status" = 'published'`);
+      }
+      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);
@@ -536,6 +685,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++}`;
@@ -568,16 +729,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
@@ -624,7 +778,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);
@@ -633,6 +788,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);
@@ -644,20 +802,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();
@@ -670,16 +822,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(
@@ -715,6 +872,22 @@ async function handleGenericCreate(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"];
@@ -800,6 +973,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,
@@ -882,23 +1056,19 @@ 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 }) {
-  var _a, _b, _c, _d, _e, _f;
+  return runWithAuditLog(request, (audit) => handleGenericReadImpl(request, audit, { params }));
+}
+async function handleGenericReadImpl(request, audit, { params }) {
+  var _a, _b, _c, _d, _e, _f, _g;
   try {
     const { id } = await params;
     const resolution = await resolveEntityFromUrl(request.nextUrl.pathname);
@@ -910,25 +1080,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) {
@@ -959,6 +1126,7 @@ async function handleGenericRead(request, { params }) {
       return `t.${columnName}`;
     });
     const fields = [...systemFieldsFormatted, ...configFields].join(", ");
+    const forcePublishedOnly = ((_d = entityConfig.access) == null ? void 0 : _d.public) === true && userId === null && entityConfig.fields.some((f) => f.name === "status");
     let query;
     let queryParams;
     let paramIndex = 1;
@@ -972,7 +1140,7 @@ async function handleGenericRead(request, { params }) {
       query += ` AND t."teamId" = $${paramIndex++}`;
       queryParams.push(teamId);
     }
-    if (userId && !((_d = entityConfig.access) == null ? void 0 : _d.shared) && !isBypass) {
+    if (userId && !((_e = entityConfig.access) == null ? void 0 : _e.shared) && !isBypass) {
       query += ` AND t."userId" = $${paramIndex++}`;
       queryParams.push(userId);
     }
@@ -992,9 +1160,12 @@ async function handleGenericRead(request, { params }) {
         queryParams.push(readOwnershipFilter.value);
       }
     }
-    if (((_e = entityConfig.table) == null ? void 0 : _e.softDelete) && !isBypass) {
+    if (((_f = entityConfig.table) == null ? void 0 : _f.softDelete) && !isBypass) {
       query += ` AND t."deletedAt" IS NULL`;
     }
+    if (forcePublishedOnly) {
+      query += ` AND t."status" = 'published'`;
+    }
     const items = await queryWithRLS(query, queryParams, userId);
     if (!items[0]) {
       const response2 = createApiError("Item not found", 404);
@@ -1025,7 +1196,7 @@ async function handleGenericRead(request, { params }) {
       itemWithChild = itemsWithChild[0] || itemWithMeta;
     }
     let itemWithTaxonomies = itemWithChild;
-    if ((_f = entityConfig.taxonomies) == null ? void 0 : _f.enabled) {
+    if ((_g = entityConfig.taxonomies) == null ? void 0 : _g.enabled) {
       const itemsWithTaxonomies = await includeTaxonomiesInData(
         entityConfig,
         [itemWithChild],
@@ -1034,7 +1205,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);
@@ -1043,6 +1215,9 @@ async function handleGenericRead(request, { params }) {
   }
 }
 async function handleGenericUpdate(request, { params }) {
+  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;
@@ -1055,20 +1230,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;
@@ -1115,16 +1284,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(
@@ -1135,6 +1309,23 @@ 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;
@@ -1294,22 +1485,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;
@@ -1322,20 +1509,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}:delete`)) {
-      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;
@@ -1349,6 +1530,27 @@ async function handleGenericDelete(request, { params }) {
     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;
@@ -1405,16 +1607,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);