nuxt-auto-crud 1.24.0 → 1.25.0

package/README.md

@@ -1,373 +1,43 @@
 # Nuxt Auto CRUD
 
-> **Note:** This module is production-ready and actively maintained. The core CRUD API is stable. Minor breaking changes may occasionally occur in advanced features or configuration. We recommend version pinning for production deployments.
+**Nuxt Auto CRUD is a headless, zero-codegen CRUD engine that transforms Drizzle ORM schemas into fully functional RESTful APIs for Nuxt 4.** 
 
-Auto-expose RESTful CRUD APIs for your **Nuxt** application based solely on your database schema. Minimal configuration required.
+| Specification | Details |
+| :--- | :--- |
+| **Runtime** | Nuxt 4 (`app/` directory), Nitro |
+| **Persistence** | SQLite / libSQL (Optimized for Cloudflare D1) |
+| **ORM & SSOT** | Drizzle ORM (Schema-driven) |
+| **Validation** | `drizzle-zod` (Dynamic derivation) |
 
-**Core Philosophy:**
-The main objective of this module is to **expose CRUD APIs without the need for writing code**. You define your database schema, and `nuxt-auto-crud` handles the rest.
+## 🛠 Architectural Logic: Zero-Codegen
+NAC treats your Drizzle schema as the **Single Source of Truth (SSOT)**. Unlike traditional scaffolds, it does not generate physical files; it mounts dynamic Nitro handlers at runtime.
 
-You don't need to setup an extra server or database to create an MVP of an application. The Nuxt (Nitro) server and SQLite can save you time and money.
-And you don't need a separate Strapi or Supabase setup to automate your CRUD process. `nuxt-auto-crud` will help you with that and accelerate your development exponentially.
+* **Dynamic Routing**: Automatically maps `GET|POST|PATCH|DELETE` to your Drizzle tables.
+* **Agentic Compatibility**: Built with an MCP-friendly structure to allow AI Agents to interact directly with the schema-driven API.
 
-While this module exposes CRUD APIs, you are expected to build your own frontend application to consume them.
+## 🔐 RBAC & Permissions
+Integrates with `nuxt-authorization` for database-driven Role-Based Access Control.
+* **Ownership Logic**: Supports `update_own` and `delete_own` via `createdBy` column reflection.
+* **Granular Scopes**: Fine-grained control over `list` vs `list_all` (drafts/soft-deleted).
 
-- [✨ Release Notes](/CHANGELOG.md)
-- [🗺️ Roadmap](/ROADMAP.md)
-- [🎮 Try the Playground](/playground)
+## 🌐 Endpoints
+| Method | Endpoint | Description |
+| :--- | :--- | :--- |
+| `GET` | `/api/:model` | List with filtering/paging |
+| `POST` | `/api/:model` | Validated creation |
+| `GET` | `/api/:model/:id` | Single record retrieval |
+| `PATCH` | `/api/:model/:id` | Partial validated update |
+| `DELETE` | `/api/:model/:id` | Soft/Hard deletion |
 
-## 🚀 CRUD APIs are ready to use without code
+---
 
-Once installed, your database tables' CRUD APIs are exposed in a controlled manner:
+## Installation
+It is highly recommended to use the [Template](https://auto-crud.clifland.in/docs/auto-crud) for new installations.
 
-- `GET /api/:model` - List all records
-- `POST /api/:model` - Create a new record
-- `GET /api/:model/:id` - Get record by ID
-- `PATCH /api/:model/:id` - Update record
-- `DELETE /api/:model/:id` - Delete record
+If you are adding it to an existing application, refer to the [Manual Installation](https://auto-crud.clifland.in/docs/manual-installation) guide.
 
-## 📦 How to install
+[YouTube Walkthrough](https://www.youtube.com/watch?v=_o0cddJUU50&list=PLnbvxcojhIixqM1J08Tnm7vmMdx2wsy4B)
 
-### 1. Fullstack Template (Recommended)
+[NPM Package](https://www.npmjs.com/package/nuxt-auto-crud)
 
-Start a new project with everything pre-configured using our template:
-
-```bash
-npx nuxi init -t gh:clifordpereira/nuxt-auto-crud_template <project-name>
-cd <project-name>
-bun install
-bun db:generate
-bun run dev
-```
-
-**Template Usage Modes:**
-
-1.  **Fullstack App**: The template includes the `nuxt-auto-crud` module, providing both the backend APIs and the frontend UI. [Watch Demo](https://youtu.be/M9-koXmhB9k)
-2.  **Frontend Only**: You can use the template just for the frontend. In this case, you don't need to install the module in the frontend app. Instead, you would install `nuxt-auto-crud` in a separate backend setup (e.g., another Nuxt project acting as the API).
-
-Detailed instructions can be found in [https://auto-crud.clifland.in/docs/auto-crud](https://auto-crud.clifland.in/docs/auto-crud)
-
-### 2. Manual Setup (Existing Project)
-
-If you want to add `nuxt-auto-crud` to an existing project, follow these steps:
-
-> **Note:** These instructions have been simplified for NuxtHub.
-
-#### Install dependencies
-
-```bash
-npm install nuxt-auto-crud @nuxthub/core@^0.10.0 drizzle-orm
-npm install nuxt-auth-utils nuxt-authorization  # Optional: for authentication
-npm install --save-dev wrangler drizzle-kit
-```
-
-> You can also use `bun` or `pnpm` instead of `npm`.
-
-#### Configure Nuxt
-
-Add the modules to your `nuxt.config.ts`:
-
-```typescript
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@nuxthub/core', 'nuxt-auto-crud'],
-
-  hub: {
-    db: 'sqlite',
-  },
-
-  autoCrud: {
-    schemaPath: 'server/db/schema',
-    // auth: false,
-    auth: {
-      type: 'session', // for Normal Authentication with nuxt-auth-utils
-      authentication: true,
-      authorization: true,
-    },
-  },
-})
-```
-
-#### Configure Drizzle
-
-Add the generation script to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "db:generate": "nuxt db generate"
-  }
-  // ...
-}
-```
-
-Create `drizzle.config.ts` in your project root:
-
-```typescript
-// drizzle.config.ts
-import { defineConfig } from 'drizzle-kit'
-
-export default defineConfig({
-  dialect: 'sqlite',
-  schema: './server/db/schema/index.ts', // Point to your schema index file
-  out: './server/db/migrations'
-})
-```
-
-
-
-#### Define your database schema
-
-Create your schema files in `server/db/schema/`. For example, `server/db/schema/users.ts`:
-
-```typescript
-// server/db/schema/users.ts
-import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
-
-export const users = sqliteTable('users', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  name: text('name').notNull(),
-  email: text('email').notNull().unique(),
-  password: text('password').notNull(),
-  avatar: text('avatar').notNull(),
-  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
-})
-```
-#### Run the project
-
-```bash
-cd <project-name>
-bun db:generate
-bun run dev
-```
-
-That's it! 🎉 Your CRUD APIs are now available at `/api/users`. 
-
-
-#### Adding New Schemas
-
-To add a new table (e.g., `posts`), simply create a new file in your schema directory:
-
-```typescript
-// server/db/schema/posts.ts
-import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
-import { users } from './users'
-
-export const posts = sqliteTable('posts', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  title: text('title').notNull(),
-  content: text('content').notNull(),
-  authorId: integer('author_id').references(() => users.id),
-  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
-})
-```
-
-Then, ensure it is exported in your `server/db/schema/index.ts` (if you are using an index file) or that your `drizzle.config.ts` is pointing to the correct location.
-
-```typescript
-// server/db/schema/index.ts
-export * from './users'
-export * from './posts'
-```
-
-After adding the file, run the generation script:
-
-```bash
-bun db:generate
-```
-
-The new API endpoints (e.g., `/api/posts`) will be automatically available. [Watch Demo](https://youtu.be/7gW0KW1KtN0)
-
-
-> **Note:** The `organization.ts` and `cms.ts` files you might see in the playground are just examples and are commented out by default. You should implement a robust schema tailored to your production needs.
-
-### 3. Backend-only App (API Mode)
-
-If you are using Nuxt as a backend for a separate client application (e.g., mobile app, SPA), you can use this module to quickly expose REST APIs.
-
-In this case, you might handle authentication differently (e.g., validating tokens in middleware) or disable the built-in auth checks if you have a global auth middleware.
-
-```typescript
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['nuxt-auto-crud'],
-  autoCrud: {
-    schemaPath: 'server/db/schema',
-    // auth: false, // Uncomment this line for testing APIs without auth   
-    auth: {
-      type: 'jwt', // for app providing backend apis only
-      authentication: true,
-      authorization: true,
-      jwtSecret: process.env.NUXT_JWT_SECRET || 'test-secret-key-123',
-    },
-  },
-})
-```
-
-**Note:** Remember to add your `NUXT_JWT_SECRET` in `.env`.
-
-You should also configure `drizzle.config.ts` correctly:
-
-```typescript
-// drizzle.config.ts
-import { defineConfig } from 'drizzle-kit'
-
-export default defineConfig({
-  dialect: 'sqlite',
-  schema: './server/db/schema/index.ts',
-  out: './server/db/migrations',
-  tablesFilter: ['!_hub_migrations'],
-})
-```
-
-## 🔐 Authentication
-
-Authentication is enabled by default using **Session Auth** (requires `nuxt-auth-utils` and `nuxt-authorization`).
-
-To disable auth for testing:
-```typescript
-autoCrud: { auth: false }
-```
-
-For **JWT Auth** (backend-only apps) or advanced configuration, see the [Authentication docs](https://auto-crud.clifland.in/docs/configuration/authentication).
-
-
-
-## 🛡️ Public View Configuration (Field Visibility)
-
-You can define which fields are visible to unauthenticated (guest) users in your `nuxt.config.ts`.
-> **Note:** Access control (RBAC) - determining *who* can access *what* - is expected to be handled by your database/permissions system (using `nuxt-authorization`). This configuration only controls the *serialization* of the response for guests.
-
-```typescript
-// nuxt.config.ts
-export default defineNuxtConfig({
-  autoCrud: {
-    resources: {
-      // Guest View: Only these columns are visible to unauthenticated users.
-      // Access control (who can list/read) is managed by your DB permissions.
-      users: ['id', 'name', 'avatar'], 
-    },
-  },
-})
-```
-
-
-## 👤 Owner-based Permissions (RBAC)
-
-In addition to standard `create`, `read`, `update`, and `delete` permissions, you can assign **Ownership Permissions**:
-
-- `list`: Allows a user to view a list of active records (status='active').
-- `list_all`: Allows a user to view **all** records, including inactive ones (e.g., status='inactive', 'draft').
-- `update_own`: Allows a user to update a record **only if they created it**.
-- `delete_own`: Allows a user to delete a record **only if they created it**.
-
-**How it works:**
-The module checks for ownership using the following logic:
-1.  **Standard Tables:** Checks if the record has a `createdBy` (or `userId`) column that matches the logged-in user's ID.
-2.  **Users Table:** Checks if the record being accessed is the user's own profile (`id` matches).
-
-**Prerequisites:**
-Ensure your schema includes a `createdBy` field for resources where you want this behavior:
-
-```typescript
-export const posts = sqliteTable('posts', {
-  // ...
-  createdBy: integer('created_by'), // Recommended
-})
-```
-
-## 🎮 Try the Playground
-
-Want to see it in action? Clone this repo and try the playground:
-
-```bash
-# Clone the repository
-git clone https://github.com/clifordpereira/nuxt-auto-crud.git
-cd nuxt-auto-crud
-
-# Install dependencies (parent folder)
-bun install
-
-# Run the playground (Fullstack)
-cd playground
-bun install
-bun db:generate
-bun run dev
-```
-
-## 📖 Usage Examples
-
-### Create a Record
-
-```typescript
-const user = await $fetch("/api/users", {
-  method: "POST",
-  body: {
-    name: "Cliford Pereira",
-    email: "clifordpereira@gmail.com",
-    bio: "Full-Stack Developer",
-  },
-});
-```
-
-### Get All Records
-
-```typescript
-const users = await $fetch("/api/users");
-```
-
-### Get Record by ID
-
-```typescript
-const user = await $fetch("/api/users/1");
-```
-
-### Update a Record
-
-```typescript
-const updated = await $fetch("/api/users/1", {
-  method: "PATCH",
-  body: {
-    bio: "Updated bio",
-  },
-});
-```
-
-### Delete a Record
-
-```typescript
-await $fetch("/api/users/1", {
-  method: "DELETE",
-});
-```
-
-> **Note:** If authentication is enabled (default):
-> - **Fullstack App:** The module integrates with `nuxt-auth-utils`, so session cookies are handled automatically.
-> - **Backend-only App:** You must include the `Authorization: Bearer <token>` header in your requests.
-
-
-
-## 🔧 Requirements
-
-- Nuxt 3 or 4
-- Drizzle ORM (SQLite)
-- NuxtHub >= 0.10.0
-
-## 🔗 Links
-
-- **📚 Documentation:** [auto-crud.clifland.in](https://auto-crud.clifland.in/docs/auto-crud)
-- **🎬 Video Tutorials:** [YouTube Channel](https://www.youtube.com/@ClifordPereira)
-- **💬 Community:** [Discord](https://discord.gg/FBkQQfRFJM) • [GitHub Discussions](https://github.com/clifordpereira/nuxt-auto-crud/discussions/1)
-- **📦 npm:** [nuxt-auto-crud](https://www.npmjs.com/package/nuxt-auto-crud)
-
-## 🤝 Contributing
-
-Contributions are welcome! Please check out the [contribution guide](/CONTRIBUTING.md).
-
-## 📝 License
-
-[MIT License](./LICENSE)
-
-## 👨‍💻 Author
-
-Made with ❤️ by [Cliford Pereira](https://github.com/clifordpereira)
+[Creator: Clifland](https://www.clifland.in/)

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-auto-crud",
   "configKey": "autoCrud",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -67,6 +67,11 @@ const module$1 = defineNuxtModule({
       method: "get",
       handler: resolver.resolve(apiDir, "_relations.get")
     });
+    addServerHandler({
+      route: "/api/_meta",
+      method: "get",
+      handler: resolver.resolve(apiDir, "_meta.get")
+    });
     addServerHandler({
       route: "/api/:model",
       method: "get",

package/dist/runtime/server/api/[model]/[id].patch.js

@@ -1,7 +1,7 @@
 import { eventHandler, getRouterParams, readBody } from "h3";
 import { getUserSession } from "#imports";
 import { eq } from "drizzle-orm";
-import { getTableForModel, filterUpdatableFields } from "../../utils/modelMapper.js";
+import { getTableForModel, getZodSchema } from "../../utils/modelMapper.js";
 import { db } from "hub:db";
 import { ensureResourceAccess, formatResourceResult, hashPayloadFields } from "../../utils/handler.js";
 import { RecordNotFoundError } from "../../exceptions.js";
@@ -10,7 +10,8 @@ export default eventHandler(async (event) => {
   const isAdmin = await ensureResourceAccess(event, model, "update", { id });
   const table = getTableForModel(model);
   const body = await readBody(event);
-  const payload = filterUpdatableFields(model, body);
+  const schema = getZodSchema(model, "patch");
+  const payload = await schema.parseAsync(body);
   if ("status" in payload) {
     const { checkAdminAccess } = await import("../../utils/auth.js");
     const hasStatusPermission = await checkAdminAccess(event, model, "update_status", { id });

package/dist/runtime/server/api/[model]/index.post.js

@@ -1,6 +1,6 @@
 import { eventHandler, getRouterParams, readBody } from "h3";
 import { getUserSession } from "#imports";
-import { getTableForModel, filterUpdatableFields } from "../../utils/modelMapper.js";
+import { getTableForModel, getZodSchema } from "../../utils/modelMapper.js";
 import { db } from "hub:db";
 import { ensureResourceAccess, formatResourceResult, hashPayloadFields } from "../../utils/handler.js";
 export default eventHandler(async (event) => {
@@ -8,7 +8,8 @@ export default eventHandler(async (event) => {
   const isAdmin = await ensureResourceAccess(event, model, "create");
   const table = getTableForModel(model);
   const body = await readBody(event);
-  const payload = filterUpdatableFields(model, body);
+  const schema = getZodSchema(model, "insert");
+  const payload = await schema.parseAsync(body);
   if ("status" in payload) {
     const { checkAdminAccess } = await import("../../utils/auth.js");
     const hasStatusPermission = await checkAdminAccess(event, model, "update_status");

package/dist/runtime/server/api/_meta.get.d.ts

@@ -0,0 +1,19 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+    architecture: string;
+    version: string;
+    resources: ({
+        resource: string;
+        endpoint: string;
+        labelField: string;
+        fields: {
+            name: string;
+            type: any;
+            required: boolean;
+            isEnum: boolean;
+            options: any;
+            references: any;
+            isRelation: boolean;
+        }[];
+    } | null)[];
+}>>;
+export default _default;

package/dist/runtime/server/api/_meta.get.js

@@ -0,0 +1,55 @@
+import { eventHandler } from "h3";
+import { getTableForModel, getAvailableModels } from "../utils/modelMapper.js";
+import { getTableColumns as getDrizzleTableColumns } from "drizzle-orm";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import { PROTECTED_FIELDS, HIDDEN_FIELDS } from "../utils/constants.js";
+import { db } from "hub:db";
+import { ensureAuthenticated } from "../utils/auth.js";
+export default eventHandler(async (event) => {
+  await ensureAuthenticated(event);
+  const models = getAvailableModels().length > 0 ? getAvailableModels() : Object.keys(db?.query || {});
+  const resources = models.map((model) => {
+    try {
+      const table = getTableForModel(model);
+      const columns = getDrizzleTableColumns(table);
+      const config = getTableConfig(table);
+      const fields = Object.entries(columns).filter(([name]) => !PROTECTED_FIELDS.includes(name) && !HIDDEN_FIELDS.includes(name)).map(([name, col]) => {
+        let references = null;
+        const fk = config?.foreignKeys.find(
+          (f) => f.reference().columns[0].name === col.name
+        );
+        if (fk) {
+          references = fk.reference().foreignTable[Symbol.for("drizzle:Name")];
+        } else if (col.referenceConfig?.foreignTable) {
+          const foreignTable = col.referenceConfig.foreignTable;
+          references = foreignTable[Symbol.for("drizzle:Name")] || foreignTable.name;
+        }
+        const semanticType = col.columnType.toLowerCase().replace("sqlite", "");
+        return {
+          name,
+          type: semanticType,
+          required: col.notNull || false,
+          isEnum: !!col.enumValues,
+          options: col.enumValues || null,
+          references,
+          isRelation: !!references
+        };
+      });
+      const fieldNames = fields.map((f) => f.name);
+      const labelField = fieldNames.find((n) => n === "name") || fieldNames.find((n) => n === "title") || fieldNames.find((n) => n === "email") || "id";
+      return {
+        resource: model,
+        endpoint: `/api/${model}`,
+        labelField,
+        fields
+      };
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+  return {
+    architecture: "Clifland-NAC",
+    version: "1.0.0-agentic",
+    resources
+  };
+});

package/dist/runtime/server/api/_schema/[table].get.d.ts

@@ -1,5 +1,6 @@
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
     resource: string;
+    labelField: string;
     fields: import("../../utils/schema.js").Field[];
 }>>;
 export default _default;

package/dist/runtime/server/utils/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const PROTECTED_FIELDS: string[];
+export declare const HIDDEN_FIELDS: string[];

package/dist/runtime/server/utils/constants.js

@@ -0,0 +1,36 @@
+export const PROTECTED_FIELDS = [
+  "id",
+  "createdAt",
+  "updatedAt",
+  "deletedAt",
+  "createdBy",
+  "updatedBy",
+  "deletedBy",
+  "created_at",
+  "updated_at",
+  "deleted_at",
+  "created_by",
+  "updated_by",
+  "deleted_by"
+];
+export const HIDDEN_FIELDS = [
+  // Sensitive Auth
+  "password",
+  "resetToken",
+  "reset_token",
+  "resetExpires",
+  "reset_expires",
+  "githubId",
+  "github_id",
+  "googleId",
+  "google_id",
+  "secret",
+  "token",
+  // System Fields (Leakage prevention)
+  "deletedAt",
+  "createdBy",
+  "updatedBy",
+  "deleted_at",
+  "created_by",
+  "updated_by"
+];

package/dist/runtime/server/utils/modelMapper.d.ts

@@ -1,86 +1,28 @@
 import type { SQLiteTable } from 'drizzle-orm/sqlite-core';
-/**
- * Custom updatable fields configuration (optional)
- * Only define here if you want to override the auto-detection
- *
- * Example:
- * export const customUpdatableFields: Record<string, string[]> = {
- *   users: ['name', 'avatar'], // Only these fields can be updated
- * }
- */
+import type { z } from 'zod';
 export declare const customUpdatableFields: Record<string, string[]>;
-/**
- * Custom hidden fields configuration (optional)
- * Only define here if you want to override the default hidden fields
- */
 export declare const customHiddenFields: Record<string, string[]>;
-/**
- * Auto-generated model table map
- * Automatically includes all tables from schema
- */
 export declare const modelTableMap: Record<string, unknown>;
 /**
- * Gets the table for a given model name
- * @param modelName - The name of the model (e.g., 'users', 'products')
- * @returns The corresponding database table
- * @throws Error if model is not found
+ * @throws 404 if modelName is not found in tableMap.
  */
 export declare function getTableForModel(modelName: string): SQLiteTable;
-/**
- * Gets the updatable fields for a model
- * @param modelName - The name of the model
- * @returns Array of field names that can be updated
- */
 export declare function getUpdatableFields(modelName: string): string[];
 /**
- * Filters an object to only include updatable fields for a model
- * @param modelName - The name of the model
- * @param data - The data object to filter
- * @returns Filtered object with only updatable fields
+ * Filters and coerces data for updates, handling timestamp conversion.
  */
 export declare function filterUpdatableFields(modelName: string, data: Record<string, unknown>): Record<string, unknown>;
-/**
- * Gets the singular name for a model (for error messages)
- * Uses pluralize library for accurate singular/plural conversion
- * @param modelName - The plural model name
- * @returns The singular name in PascalCase
- */
 export declare function getModelSingularName(modelName: string): string;
-/**
- * Gets the plural name for a model
- * @param modelName - The model name (singular or plural)
- * @returns The plural name
- * @return The plural name
- */
 export declare function getModelPluralName(modelName: string): string;
-/**
- * Lists all available models
- * @returns Array of model names
- */
 export declare function getAvailableModels(): string[];
-/**
- * Gets the hidden fields for a model
- * @param modelName - The name of the model
- * @returns Array of field names that should be hidden
- */
 export declare function getHiddenFields(modelName: string): string[];
-/**
- * Gets the public columns for a model
- * @param modelName - The name of the model
- * @returns Array of field names that are public (or undefined if all are public)
- */
 export declare function getPublicColumns(modelName: string): string[] | undefined;
 /**
- * Filters an object to only include public columns (if configured)
- * @param modelName - The name of the model
- * @param data - The data object to filter
- * @returns Filtered object
+ * Restricts payload to runtimeConfig resource whitelist and filters hidden fields.
  */
 export declare function filterPublicColumns(modelName: string, data: Record<string, unknown>): Record<string, unknown>;
+export declare function filterHiddenFields(modelName: string, data: Record<string, unknown>): Record<string, unknown>;
 /**
- * Filters an object to exclude hidden fields
- * @param modelName - The name of the model
- * @param data - The data object to filter
- * @returns Filtered object without hidden fields
+ * Generates Zod schema via drizzle-zod, omitting server-managed and protected fields.
  */
-export declare function filterHiddenFields(modelName: string, data: Record<string, unknown>): Record<string, unknown>;
+export declare function getZodSchema(modelName: string, type?: 'insert' | 'patch'): z.ZodObject<any, any>;

package/dist/runtime/server/utils/modelMapper.js

@@ -4,15 +4,10 @@ import { pascalCase } from "scule";
 import { getTableColumns as getDrizzleTableColumns, getTableName } from "drizzle-orm";
 import { createError } from "h3";
 import { useRuntimeConfig } from "#imports";
-const PROTECTED_FIELDS = ["id", "created_at", "updated_at", "createdAt", "updatedAt"];
-const HIDDEN_FIELDS = ["password", "secret", "token"];
-export const customUpdatableFields = {
-  // Add custom field restrictions here if needed
-  // By default, all fields except PROTECTED_FIELDS are updatable
-};
-export const customHiddenFields = {
-  // Add custom hidden fields here if needed
-};
+import { createInsertSchema } from "drizzle-zod";
+import { PROTECTED_FIELDS, HIDDEN_FIELDS } from "./constants.js";
+export const customUpdatableFields = {};
+export const customHiddenFields = {};
 function buildModelTableMap() {
   const tableMap = {};
   for (const [key, value] of Object.entries(schema)) {
@@ -56,7 +51,7 @@ export function getUpdatableFields(modelName) {
   const table = modelTableMap[modelName];
   if (!table) return [];
   const allColumns = getTableColumns(table);
-  return allColumns.filter((col) => !PROTECTED_FIELDS.includes(col));
+  return allColumns.filter((col) => !PROTECTED_FIELDS.includes(col) && !HIDDEN_FIELDS.includes(col));
 }
 export function filterUpdatableFields(modelName, data) {
   const allowedFields = getUpdatableFields(modelName);
@@ -86,10 +81,7 @@ export function getAvailableModels() {
   return Object.keys(modelTableMap);
 }
 export function getHiddenFields(modelName) {
-  if (customHiddenFields[modelName]) {
-    return customHiddenFields[modelName];
-  }
-  return HIDDEN_FIELDS;
+  return customHiddenFields[modelName] ?? HIDDEN_FIELDS;
 }
 export function getPublicColumns(modelName) {
   const { resources } = useRuntimeConfig().autoCrud;
@@ -101,8 +93,9 @@ export function filterPublicColumns(modelName, data) {
     return filterHiddenFields(modelName, data);
   }
   const filtered = {};
+  const hidden = getHiddenFields(modelName);
   for (const [key, value] of Object.entries(data)) {
-    if (publicColumns.includes(key) && !getHiddenFields(modelName).includes(key)) {
+    if (publicColumns.includes(key) && !hidden.includes(key)) {
       filtered[key] = value;
     }
   }
@@ -118,3 +111,22 @@ export function filterHiddenFields(modelName, data) {
   }
   return filtered;
 }
+export function getZodSchema(modelName, type = "insert") {
+  const table = getTableForModel(modelName);
+  const schema2 = createInsertSchema(table);
+  if (type === "patch") {
+    return schema2.partial();
+  }
+  const OMIT_ON_CREATE = [
+    ...PROTECTED_FIELDS,
+    ...HIDDEN_FIELDS
+  ];
+  const columns = getDrizzleTableColumns(table);
+  const fieldsToOmit = {};
+  OMIT_ON_CREATE.forEach((field) => {
+    if (columns[field]) {
+      fieldsToOmit[field] = true;
+    }
+  });
+  return schema2.omit(fieldsToOmit);
+}

package/dist/runtime/server/utils/schema.d.ts

@@ -7,11 +7,13 @@ export interface Field {
 }
 export declare function drizzleTableToFields(table: any, resourceName: string): {
     resource: string;
+    labelField: string;
     fields: Field[];
 };
 export declare function getRelations(): Promise<Record<string, Record<string, string>>>;
 export declare function getAllSchemas(): Promise<Record<string, any>>;
 export declare function getSchema(tableName: string): Promise<{
     resource: string;
+    labelField: string;
     fields: Field[];
 } | undefined>;

package/dist/runtime/server/utils/schema.js

@@ -15,6 +15,8 @@ export function drizzleTableToFields(table, resourceName) {
       selectOptions
     });
   }
+  const fieldNames = fields.map((f) => f.name);
+  const labelField = fieldNames.find((n) => n === "name") || fieldNames.find((n) => n === "title") || fieldNames.find((n) => n === "email") || "id";
   try {
     const config = getTableConfig(table);
     config.foreignKeys.forEach((fk) => {
@@ -32,6 +34,8 @@ export function drizzleTableToFields(table, resourceName) {
   }
   return {
     resource: resourceName,
+    labelField,
+    // metadata point
     fields
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-auto-crud",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Exposes RESTful CRUD APIs for your Nuxt app based solely on your database migrations.",
   "author": "Cliford Pereira",
   "license": "MIT",
@@ -51,6 +51,7 @@
     "@nuxt/scripts": "^0.13.0",
     "@types/pluralize": "^0.0.33",
     "c12": "^2.0.1",
+    "drizzle-zod": "^0.8.3",
     "jose": "^5.9.6",
     "pluralize": "^8.0.0",
     "scule": "^1.0.0"
@@ -78,7 +79,7 @@
     "drizzle-orm": "^0.38.3",
     "eslint": "^9.39.1",
     "nuxt": "^4.2.1",
-    "nuxt-auth-utils": "^0.5.26",
+    "nuxt-auth-utils": "^0.5.27",
     "nuxt-authorization": "^0.3.5",
     "typescript": "~5.9.3",
     "vitest": "^4.0.13",

package/src/runtime/server/api/[model]/[id].patch.ts

@@ -4,7 +4,7 @@ import type { H3Event } from 'h3'
 // @ts-expect-error - #imports is a virtual alias
 import { getUserSession } from '#imports'
 import { eq } from 'drizzle-orm'
-import { getTableForModel, filterUpdatableFields } from '../../utils/modelMapper'
+import { getTableForModel, getZodSchema } from '../../utils/modelMapper'
 import type { TableWithId } from '../../types'
 
 // @ts-expect-error - hub:db is a virtual alias
@@ -20,7 +20,8 @@ export default eventHandler(async (event) => {
   const table = getTableForModel(model) as TableWithId
 
   const body = await readBody(event)
-  const payload = filterUpdatableFields(model, body)
+  const schema = getZodSchema(model, 'patch')
+  const payload = await schema.parseAsync(body)
 
   // Custom check for status update permission
   if ('status' in payload) {

package/src/runtime/server/api/[model]/index.post.ts

@@ -1,10 +1,10 @@
 // server/api/[model]/index.post.ts
 import { eventHandler, getRouterParams, readBody } from 'h3'
 import type { H3Event } from 'h3'
-// @ts-expect-error - #imports is a virtual alias
+// @ts-expect-error - '#imports' is a virtual alias
 import { getUserSession } from '#imports'
-import { getTableForModel, filterUpdatableFields } from '../../utils/modelMapper'
-// @ts-expect-error - hub:db is a virtual alias
+import { getTableForModel, getZodSchema } from '../../utils/modelMapper'
+// @ts-expect-error - 'hub:db' is a virtual alias
 import { db } from 'hub:db'
 import { ensureResourceAccess, formatResourceResult, hashPayloadFields } from '../../utils/handler'
 
@@ -15,7 +15,8 @@ export default eventHandler(async (event) => {
   const table = getTableForModel(model)
 
   const body = await readBody(event)
-  const payload = filterUpdatableFields(model, body)
+  const schema = getZodSchema(model, 'insert')
+  const payload = await schema.parseAsync(body)
 
   // Custom check for status update permission (or just remove it during creation as per requirement)
   if ('status' in payload) {

package/src/runtime/server/api/_meta.get.ts

@@ -0,0 +1,86 @@
+// server/api/_meta.get.ts
+import { eventHandler } from 'h3'
+import { getTableForModel, getAvailableModels } from '../utils/modelMapper'
+import { getTableColumns as getDrizzleTableColumns } from 'drizzle-orm'
+import { getTableConfig } from 'drizzle-orm/sqlite-core'
+import { PROTECTED_FIELDS, HIDDEN_FIELDS } from '../utils/constants'
+// @ts-expect-error - 'hub:db' is a virtual alias
+import { db } from 'hub:db'
+import { ensureAuthenticated } from '../utils/auth'
+
+export default eventHandler(async (event) => {
+  await ensureAuthenticated(event)
+
+  const models = getAvailableModels().length > 0
+    ? getAvailableModels()
+    : Object.keys(db?.query || {})
+
+  const resources = models.map((model) => {
+    try {
+      const table = getTableForModel(model)
+      const columns = getDrizzleTableColumns(table)
+      const config = getTableConfig(table)
+
+      // Map columns to fields
+      const fields = Object.entries(columns)
+        .filter(([name]) => !PROTECTED_FIELDS.includes(name) && !HIDDEN_FIELDS.includes(name))
+        .map(([name, col]) => {
+          let references = null
+
+          // 1. Check for Foreign Keys via getTableConfig (Robust Drizzle Reflection)
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const fk = config?.foreignKeys.find((f: any) =>
+            f.reference().columns[0].name === col.name,
+          )
+
+          if (fk) {
+            // @ts-expect-error - Drizzle internals
+            references = fk.reference().foreignTable[Symbol.for('drizzle:Name')]
+          }
+          // 2. Fallback to inline reference config if symbol lookup fails
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          else if ((col as any).referenceConfig?.foreignTable) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const foreignTable = (col as any).referenceConfig.foreignTable
+            references = foreignTable[Symbol.for('drizzle:Name')] || foreignTable.name
+          }
+
+          // Semantic Normalization
+          const semanticType = col.columnType.toLowerCase().replace('sqlite', '')
+
+          return {
+            name,
+            type: semanticType,
+            required: col.notNull || false,
+            isEnum: !!col.enumValues,
+            options: col.enumValues || null,
+            references,
+            isRelation: !!references,
+          }
+        })
+
+      // 3. Implement Clifland Label Heuristic (name > title > email > id)
+      const fieldNames = fields.map(f => f.name)
+      const labelField = fieldNames.find(n => n === 'name')
+        || fieldNames.find(n => n === 'title')
+        || fieldNames.find(n => n === 'email')
+        || 'id'
+
+      return {
+        resource: model,
+        endpoint: `/api/${model}`,
+        labelField,
+        fields,
+      }
+    }
+    catch {
+      return null
+    }
+  }).filter(Boolean)
+
+  return {
+    architecture: 'Clifland-NAC',
+    version: '1.0.0-agentic',
+    resources,
+  }
+})

package/src/runtime/server/utils/constants.ts

@@ -0,0 +1,25 @@
+export const PROTECTED_FIELDS = [
+  'id',
+  'createdAt', 'updatedAt', 'deletedAt',
+  'createdBy', 'updatedBy', 'deletedBy',
+  'created_at', 'updated_at', 'deleted_at',
+  'created_by', 'updated_by', 'deleted_by',
+]
+
+export const HIDDEN_FIELDS = [
+  // Sensitive Auth
+  'password',
+  'resetToken', 'reset_token',
+  'resetExpires', 'reset_expires',
+  'githubId', 'github_id',
+  'googleId', 'google_id',
+  'secret',
+  'token',
+  // System Fields (Leakage prevention)
+  'deletedAt',
+  'createdBy',
+  'updatedBy',
+  'deleted_at',
+  'created_by',
+  'updated_by',
+]

package/src/runtime/server/utils/modelMapper.ts

@@ -7,53 +7,23 @@ import { getTableColumns as getDrizzleTableColumns, getTableName } from 'drizzle
 import type { SQLiteTable } from 'drizzle-orm/sqlite-core'
 import { createError } from 'h3'
 import { useRuntimeConfig } from '#imports'
+import { createInsertSchema } from 'drizzle-zod'
+import type { z } from 'zod'
 
-/**
- * Fields that should never be updatable via PATCH requests
- */
-const PROTECTED_FIELDS = ['id', 'created_at', 'updated_at', 'createdAt', 'updatedAt']
-
-/**
- * Fields that should never be returned in API responses
- */
-const HIDDEN_FIELDS = ['password', 'secret', 'token']
-
-/**
- * Custom updatable fields configuration (optional)
- * Only define here if you want to override the auto-detection
- *
- * Example:
- * export const customUpdatableFields: Record<string, string[]> = {
- *   users: ['name', 'avatar'], // Only these fields can be updated
- * }
- */
-export const customUpdatableFields: Record<string, string[]> = {
-  // Add custom field restrictions here if needed
-  // By default, all fields except PROTECTED_FIELDS are updatable
-}
+import { PROTECTED_FIELDS, HIDDEN_FIELDS } from './constants'
 
-/**
- * Custom hidden fields configuration (optional)
- * Only define here if you want to override the default hidden fields
- */
-export const customHiddenFields: Record<string, string[]> = {
-  // Add custom hidden fields here if needed
-}
+export const customUpdatableFields: Record<string, string[]> = {}
+export const customHiddenFields: Record<string, string[]> = {}
 
 /**
- * Automatically builds a map of all exported tables from the schema
- * No manual configuration needed!
+ * Builds a map of all exported Drizzle tables from the schema.
  */
 function buildModelTableMap(): Record<string, unknown> {
   const tableMap: Record<string, unknown> = {}
 
-  // Iterate through all exports from schema
   for (const [key, value] of Object.entries(schema)) {
-    // Check if it's a Drizzle table
     if (value && typeof value === 'object') {
       try {
-        // getTableName returns the table name for valid tables, and undefined/null for others (like relations)
-        // This is a more robust check than checking for properties
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const tableName = getTableName(value as any)
         if (tableName) {
@@ -61,7 +31,7 @@ function buildModelTableMap(): Record<string, unknown> {
         }
       }
       catch {
-        // Ignore if it throws (not a table)
+        // Not a table
       }
     }
   }
@@ -69,17 +39,10 @@ function buildModelTableMap(): Record<string, unknown> {
   return tableMap
 }
 
-/**
- * Auto-generated model table map
- * Automatically includes all tables from schema
- */
 export const modelTableMap = buildModelTableMap()
 
 /**
- * Gets the table for a given model name
- * @param modelName - The name of the model (e.g., 'users', 'products')
- * @returns The corresponding database table
- * @throws Error if model is not found
+ * @throws 404 if modelName is not found in tableMap.
  */
 export function getTableForModel(modelName: string): SQLiteTable {
   const table = modelTableMap[modelName]
@@ -95,10 +58,6 @@ export function getTableForModel(modelName: string): SQLiteTable {
   return table as SQLiteTable
 }
 
-/**
- * Auto-detects updatable fields for a table
- * Returns all fields except protected ones (id, createdAt, etc.)
- */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function getTableColumns(table: any): string[] {
   try {
@@ -111,33 +70,20 @@ function getTableColumns(table: any): string[] {
   }
 }
 
-/**
- * Gets the updatable fields for a model
- * @param modelName - The name of the model
- * @returns Array of field names that can be updated
- */
 export function getUpdatableFields(modelName: string): string[] {
-  // Check if custom fields are defined for this model
   if (customUpdatableFields[modelName]) {
     return customUpdatableFields[modelName]
   }
 
-  // Auto-detect from table schema
   const table = modelTableMap[modelName]
-
   if (!table) return []
 
   const allColumns = getTableColumns(table)
-
-  // Filter out protected fields
-  return allColumns.filter(col => !PROTECTED_FIELDS.includes(col))
+  return allColumns.filter(col => !PROTECTED_FIELDS.includes(col) && !HIDDEN_FIELDS.includes(col))
 }
 
 /**
- * Filters an object to only include updatable fields for a model
- * @param modelName - The name of the model
- * @param data - The data object to filter
- * @returns Filtered object with only updatable fields
+ * Filters and coerces data for updates, handling timestamp conversion.
  */
 export function filterUpdatableFields(modelName: string, data: Record<string, unknown>): Record<string, unknown> {
   const allowedFields = getUpdatableFields(modelName)
@@ -151,7 +97,6 @@ export function filterUpdatableFields(modelName: string, data: Record<string, un
       let value = data[field]
       const column = columns[field]
 
-      // Coerce timestamp fields to Date objects if they are strings
       if (column && column.mode === 'timestamp' && typeof value === 'string') {
         value = new Date(value)
       }
@@ -163,79 +108,43 @@ export function filterUpdatableFields(modelName: string, data: Record<string, un
   return filtered
 }
 
-/**
- * Gets the singular name for a model (for error messages)
- * Uses pluralize library for accurate singular/plural conversion
- * @param modelName - The plural model name
- * @returns The singular name in PascalCase
- */
 export function getModelSingularName(modelName: string): string {
   const singular = pluralize.singular(modelName)
   return pascalCase(singular)
 }
 
-/**
- * Gets the plural name for a model
- * @param modelName - The model name (singular or plural)
- * @returns The plural name
- * @return The plural name
- */
 export function getModelPluralName(modelName: string): string {
   return pluralize.plural(modelName)
 }
 
-/**
- * Lists all available models
- * @returns Array of model names
- */
 export function getAvailableModels(): string[] {
   return Object.keys(modelTableMap)
 }
 
-/**
- * Gets the hidden fields for a model
- * @param modelName - The name of the model
- * @returns Array of field names that should be hidden
- */
 export function getHiddenFields(modelName: string): string[] {
-  // Check if custom hidden fields are defined for this model
-  if (customHiddenFields[modelName]) {
-    return customHiddenFields[modelName]
-  }
-
-  return HIDDEN_FIELDS
+  return customHiddenFields[modelName] ?? HIDDEN_FIELDS
 }
 
-/**
- * Gets the public columns for a model
- * @param modelName - The name of the model
- * @returns Array of field names that are public (or undefined if all are public)
- */
 export function getPublicColumns(modelName: string): string[] | undefined {
   const { resources } = useRuntimeConfig().autoCrud
-  // Runtime config structure now matches simple key-value
   return resources?.[modelName]
 }
 
 /**
- * Filters an object to only include public columns (if configured)
- * @param modelName - The name of the model
- * @param data - The data object to filter
- * @returns Filtered object
+ * Restricts payload to runtimeConfig resource whitelist and filters hidden fields.
  */
 export function filterPublicColumns(modelName: string, data: Record<string, unknown>): Record<string, unknown> {
   const publicColumns = getPublicColumns(modelName)
 
-  // If no public columns configured, return all (except hidden)
   if (!publicColumns) {
     return filterHiddenFields(modelName, data)
   }
 
   const filtered: Record<string, unknown> = {}
+  const hidden = getHiddenFields(modelName)
 
   for (const [key, value] of Object.entries(data)) {
-    // Must be in publicColumns AND not in hidden fields (double safety)
-    if (publicColumns.includes(key) && !getHiddenFields(modelName).includes(key)) {
+    if (publicColumns.includes(key) && !hidden.includes(key)) {
       filtered[key] = value
     }
   }
@@ -243,12 +152,6 @@ export function filterPublicColumns(modelName: string, data: Record<string, unkn
   return filtered
 }
 
-/**
- * Filters an object to exclude hidden fields
- * @param modelName - The name of the model
- * @param data - The data object to filter
- * @returns Filtered object without hidden fields
- */
 export function filterHiddenFields(modelName: string, data: Record<string, unknown>): Record<string, unknown> {
   const hiddenFields = getHiddenFields(modelName)
   const filtered: Record<string, unknown> = {}
@@ -261,3 +164,34 @@ export function filterHiddenFields(modelName: string, data: Record<string, unkno
 
   return filtered
 }
+
+/**
+ * Generates Zod schema via drizzle-zod, omitting server-managed and protected fields.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getZodSchema(modelName: string, type: 'insert' | 'patch' = 'insert'): z.ZodObject<any, any> {
+  const table = getTableForModel(modelName)
+  const schema = createInsertSchema(table)
+
+  if (type === 'patch') {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return schema.partial() as z.ZodObject<any, any>
+  }
+
+  const OMIT_ON_CREATE = [
+    ...PROTECTED_FIELDS,
+    ...HIDDEN_FIELDS,
+  ]
+
+  const columns = getDrizzleTableColumns(table)
+  const fieldsToOmit: Record<string, true> = {}
+
+  OMIT_ON_CREATE.forEach((field) => {
+    if (columns[field]) {
+      fieldsToOmit[field] = true
+    }
+  })
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (schema as any).omit(fieldsToOmit)
+}

package/src/runtime/server/utils/schema.ts

@@ -30,6 +30,13 @@ export function drizzleTableToFields(table: any, resourceName: string) {
     })
   }
 
+  // Clifland Heuristic: Auto-detect the primary label for the resource
+  const fieldNames = fields.map(f => f.name)
+  const labelField = fieldNames.find(n => n === 'name')
+    || fieldNames.find(n => n === 'title')
+    || fieldNames.find(n => n === 'email')
+    || 'id'
+
   try {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const config = getTableConfig(table as any)
@@ -57,6 +64,7 @@ export function drizzleTableToFields(table: any, resourceName: string) {
 
   return {
     resource: resourceName,
+    labelField, // metadata point
     fields,
   }
 }