fastify-auto-sqlapi 0.1.9 → 0.1.11

package/dist/routes/auto/agent-manifest.routes.d.ts

@@ -0,0 +1,12 @@
+import type { FastifyInstance } from 'fastify';
+import type { SqlApiPluginOptions } from '../../types.js';
+/**
+ * GET /agent/manifest      → JSON description of every exposed table
+ * GET /agent/manifest.md   → compact markdown for an LLM system prompt
+ *
+ * Opt-in via the `agentManifest` plugin option (like `swagger`). Runs behind the same
+ * global `onRequests` hooks as the data routes. The manifest is built once at startup —
+ * `DbTables` is static configuration.
+ */
+export default function agentManifestRoutes(fastify: FastifyInstance, options: SqlApiPluginOptions): Promise<void>;
+//# sourceMappingURL=agent-manifest.routes.d.ts.map

package/dist/routes/auto/agent-manifest.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-manifest.routes.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/agent-manifest.routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAA8B,mBAAmB,CAC/C,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/routes/auto/agent-manifest.routes.js

@@ -0,0 +1,30 @@
+import { buildAgentManifest, renderAgentManifestMd } from '../../lib/agent/manifest.js';
+/**
+ * GET /agent/manifest      → JSON description of every exposed table
+ * GET /agent/manifest.md   → compact markdown for an LLM system prompt
+ *
+ * Opt-in via the `agentManifest` plugin option (like `swagger`). Runs behind the same
+ * global `onRequests` hooks as the data routes. The manifest is built once at startup —
+ * `DbTables` is static configuration.
+ */
+export default async function agentManifestRoutes(fastify, options) {
+    const manifest = buildAgentManifest(options.DbTables);
+    const markdown = renderAgentManifestMd(manifest);
+    const onRequest = options.onRequests?.length ? options.onRequests : undefined;
+    fastify.get('/agent/manifest', {
+        ...(onRequest ? { onRequest } : {}),
+        schema: {
+            tags: ['SqlAPI-agent'],
+            summary: 'Agent manifest (JSON)',
+            description: 'Machine-readable description of every exposed table: fields, operations, join aliases, computed fields. Pair with AGENTS_FRONTEND.md.',
+        },
+    }, async () => manifest);
+    fastify.get('/agent/manifest.md', {
+        ...(onRequest ? { onRequest } : {}),
+        schema: {
+            tags: ['SqlAPI-agent'],
+            summary: 'Agent manifest (markdown)',
+            description: 'Compact markdown rendering of the manifest, designed for an LLM system prompt.',
+        },
+    }, async (_req, reply) => reply.type('text/markdown; charset=utf-8').send(markdown));
+}

package/dist/routes/auto/bulk-delete.routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bulk-delete.routes.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/bulk-delete.routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,wBAA8B,gBAAgB,CAC5C,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAkBf"}
+{"version":3,"file":"bulk-delete.routes.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/bulk-delete.routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,wBAA8B,gBAAgB,CAC5C,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/routes/auto/bulk-delete.routes.js

@@ -5,6 +5,7 @@ import { DEFAULT_MAX_BULK_ITEMS } from '../../types.js';
 export default async function bulkDeleteRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'bulkDelete',
+        singlePkOnly: true,
         method: 'POST',
         url: (tc) => `/bulk/${tc.Schema.tableName}/delete`,
         successStatus: 200,

package/dist/routes/auto/delete.routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete.routes.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/delete.routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,wBAA8B,YAAY,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"delete.routes.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/delete.routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,wBAA8B,YAAY,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/routes/auto/delete.routes.js

@@ -4,6 +4,7 @@ import { registerForAllTables } from './route-helpers.js';
 export default async function deleteRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'delete',
+        singlePkOnly: true,
         method: 'DELETE',
         url: (tc) => `/rest/${tc.Schema.tableName}/:id`,
         successStatus: 200,

package/dist/routes/auto/get.routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get.routes.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/get.routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,wBAA8B,SAAS,CACrC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAiBf"}
+{"version":3,"file":"get.routes.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/get.routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,wBAA8B,SAAS,CACrC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/routes/auto/get.routes.js

@@ -3,6 +3,7 @@ import { registerForAllTables } from './route-helpers.js';
 export default async function getRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'get',
+        singlePkOnly: true,
         method: 'GET',
         url: (tc) => `/rest/${tc.Schema.tableName}/:id`,
         successStatus: 200,

package/dist/routes/auto/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,SAAS,CAAC;AAa7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;kCAuD/C,eAAe,WACf,mBAAmB,KAC3B,OAAO,CAAC,IAAI,CAAC;AAHhB,wBA0DoC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,SAAS,CAAC;AAc7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;kCAuD/C,eAAe,WACf,mBAAmB,KAC3B,OAAO,CAAC,IAAI,CAAC;AAHhB,wBA6DoC"}

package/dist/routes/auto/plugin.js

@@ -10,6 +10,7 @@ import updateRoutes from './update.routes.js';
 import deleteRoutes from './delete.routes.js';
 import bulkUpsertRoutes from './bulk-upsert.routes.js';
 import bulkDeleteRoutes from './bulk-delete.routes.js';
+import agentManifestRoutes from './agent-manifest.routes.js';
 // Schema combinators for which Ajv reports one error per failed branch plus a
 // single combinator-level summary error, all targeting the same path.
 const COMBINATOR_KEYWORDS = new Set(['anyOf', 'oneOf']);
@@ -97,5 +98,8 @@ export default fp(async function fastifyAutoSqlApi(fastify, options) {
         await instance.register(deleteRoutes, routeOptions);
         await instance.register(bulkUpsertRoutes, routeOptions);
         await instance.register(bulkDeleteRoutes, routeOptions);
+        if (options.agentManifest) {
+            await instance.register(agentManifestRoutes, routeOptions);
+        }
     }, { prefix });
 }, { name: 'fastify-auto-sqlapi' });

package/dist/routes/auto/route-helpers.d.ts

@@ -12,6 +12,13 @@ interface RouteSchema {
 export interface AutoRouteSpec {
     /** Operation key matched against `ITable.operations` to decide whether to register the route. */
     operation: TableOperation;
+    /**
+     * Set when the route addresses records by a single PK value (get, delete, bulkDelete).
+     * Tables with a composite primary key skip these routes: matching on the first PK column
+     * alone would touch every row sharing that value. Explicitly listing the operation in
+     * `ITable.operations` for such a table throws at registration.
+     */
+    singlePkOnly?: boolean;
     method: 'GET' | 'POST' | 'PUT' | 'DELETE';
     /** URL builder receiving the table configuration to read `Schema.tableName`. */
     url: (tableConf: ITable) => string;

package/dist/routes/auto/route-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE5F,KAAK,WAAW,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;AAElG,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CAE9F;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,gFAAgF;IAChF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAqCf"}
+{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE5F,KAAK,WAAW,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;AAElG,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CAE9F;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,gFAAgF;IAChF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAkDf"}

package/dist/routes/auto/route-helpers.js

@@ -1,4 +1,5 @@
 import { ensureSqlApiDecorator } from '../../lib/sql-api-decorator.js';
+import { isCompositePrimary } from '../../types.js';
 export function mergeOnRequests(options, tableConf) {
     return [...(options.onRequests || []), ...(tableConf.onRequests || [])];
 }
@@ -25,6 +26,16 @@ export async function registerForAllTables(fastify, options, spec) {
         // operations acts as a whitelist; when omitted every operation is exposed.
         if (tableConf.operations && !tableConf.operations.includes(spec.operation))
             continue;
+        // Single-PK routes cannot address composite-PK tables — skip them (default) or,
+        // when the consumer explicitly asked for the operation, fail loudly at startup.
+        if (spec.singlePkOnly && isCompositePrimary(tableConf.primary)) {
+            if (tableConf.operations?.includes(spec.operation)) {
+                throw new Error(`Table "${tableName}" has a composite primary key (${tableConf.primary.join(', ')}): ` +
+                    `operation "${spec.operation}" addresses records by a single PK value and cannot be exposed. ` +
+                    `Remove it from "operations", or handle the table via search/update or a custom route.`);
+            }
+            continue;
+        }
         const schemas = spec.schemas(DbTables, tableName, tableConf);
         // Only include schema keys that are actually defined: Fastify checks for key
         // *presence* (not undefined value) to decide whether to emit FSTWRN001.

package/dist/routes/auto/search.routes.js

@@ -1,4 +1,4 @@
-import { SearchTableBodyPost, SearchTableQueryString, SearchTableResponse } from '../../lib/schema/search.js';
+import { SearchTableBodyPost, SearchTableQuery, SearchTableResponse } from '../../lib/schema/search.js';
 import { registerForAllTables } from './route-helpers.js';
 import { httpError } from '../../lib/errors.js';
 import { DEFAULT_MAX_ITEMS_PER_PAGE } from '../../types.js';
@@ -10,7 +10,7 @@ export default async function searchRoutes(fastify, options) {
         successStatus: 200,
         schemas: (db, table) => ({
             body: SearchTableBodyPost(db, table),
-            querystring: SearchTableQueryString,
+            querystring: SearchTableQuery(options.maxItemsPerPage ?? DEFAULT_MAX_ITEMS_PER_PAGE),
             response: SearchTableResponse(db, table),
         }),
         summary: 'Search',
@@ -45,7 +45,7 @@ export default async function searchRoutes(fastify, options) {
                 selectComputed: body.selectComputed,
                 orderBy: query.orderBy,
                 paginator: (query.page || query.itemsPerPage)
-                    ? { page: query.page || 1, itemsPerPage: query.itemsPerPage || 500 }
+                    ? { page: query.page || 1, itemsPerPage: query.itemsPerPage || Math.min(500, maxRows) }
                     : undefined,
                 computeMin: query.computeMin,
                 computeMax: query.computeMax,

package/dist/types/plugin.d.ts

@@ -28,6 +28,13 @@ export interface SqlApiPluginOptions {
      * Defaults to {@link DEFAULT_MAX_BULK_ITEMS}.
      */
     maxBulkItems?: number;
+    /**
+     * Register `GET /agent/manifest` (JSON) and `GET /agent/manifest.md` (markdown): a
+     * machine-readable description of every exposed table (fields, operations, join
+     * aliases, computed fields), for LLM/agent clients. Opt-in, like `swagger`. The
+     * routes run behind the same global `onRequests` hooks as the data routes.
+     */
+    agentManifest?: boolean;
 }
 /** Default row cap for search (page size and no-paginator LIMIT). Override via `maxItemsPerPage`. */
 export declare const DEFAULT_MAX_ITEMS_PER_PAGE = 1000;

package/dist/types/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IACnC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,OAAO,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,OAAO,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IACnC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,OAAO,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,OAAO,CAAC"}

package/dist/types/table.d.ts

@@ -128,5 +128,11 @@ export interface ITable<F extends Record<string, TSchema> = Record<string, TSche
 }
 export type DbTables = Record<string, ITable<any>>;
 export declare function primaryAsString(pk: string | string[]): string;
+/**
+ * True when the primary key spans more than one column. Operations that address a
+ * record by a single PK value (get, delete, bulkDelete) cannot work on such tables:
+ * matching on the first column alone would hit every row sharing that value.
+ */
+export declare function isCompositePrimary(pk: string | string[]): boolean;
 export declare function primaryAsCols(pk: string | string[], colFn: (f: string) => string): string | string[];
 //# sourceMappingURL=table.d.ts.map

package/dist/types/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/types/table.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/types/table.ts"],"names":[],"mappings":"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"}

package/dist/types/table.js

@@ -2,6 +2,14 @@
 export function primaryAsString(pk) {
     return Array.isArray(pk) ? pk[0] : pk;
 }
+/**
+ * True when the primary key spans more than one column. Operations that address a
+ * record by a single PK value (get, delete, bulkDelete) cannot work on such tables:
+ * matching on the first column alone would hit every row sharing that value.
+ */
+export function isCompositePrimary(pk) {
+    return Array.isArray(pk) && pk.length > 1;
+}
 export function primaryAsCols(pk, colFn) {
     return Array.isArray(pk) ? pk.map(colFn) : colFn(pk);
 }

package/docs/adr/0001-no-orm-raw-sql.md

@@ -0,0 +1,38 @@
+# 0001. No ORM — raw SQL with minimal dependencies
+
+- **Status**: accepted
+- **Date**: 2026-07-23 (foundational decision, predates this record)
+
+## Context
+
+Auto-generating CRUD APIs from database tables is the territory of ORMs and heavy
+API-builder frameworks. Adopting one would have provided models, migrations and query
+building for free — at the price of a large dependency tree, an abstraction layer between
+the consumer and their SQL, and lock-in to the ORM's schema model.
+
+## Decision
+
+The plugin talks to the database with raw SQL through thin driver adapters (`pg`,
+`mysql2`), composing WHERE clauses with `node-condition-builder` and validating with
+TypeBox. No ORM, no query-builder DSL, no migration system. Runtime dependencies are kept
+to the minimum, and the plugin re-exports its building blocks (TypeBox, ConditionBuilder)
+so consumers build on the same tools instead of adding parallel ones.
+
+## Alternatives considered
+
+- **Build on an ORM (Prisma, Drizzle, Sequelize, …)** — rejected: large dependency
+  surface, a second schema definition to keep in sync with the DB, and the ORM's
+  abstractions leak into the public API. The CLI introspection (`information_schema`)
+  gives the same "schema from the DB" ergonomics without the layer.
+- **Hand-rolled query-builder DSL** — rejected: reinvents an ORM incrementally.
+  `node-condition-builder` covers the one genuinely composable part (conditions);
+  everything else is plain SQL the maintainer can read and debug.
+
+## Consequences
+
+- The engine owns dialect differences (placeholders, quoting, RETURNING vs insertId)
+  explicitly — see `src/lib/dialect.ts` and the adapters.
+- Consumers get a framework approach: tools are provided (SqlApi, QueryClient,
+  ConditionBuilder), product structure is not imposed.
+- Features an ORM would give for free (migrations, lazy relations, identity maps) are
+  intentionally out of scope.

package/docs/adr/0002-open-by-default.md

@@ -0,0 +1,37 @@
+# 0002. Open by default — no imposed auth model
+
+- **Status**: accepted
+- **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
+
+## Context
+
+Registering the plugin with no configuration exposes every operation (read and write,
+including bulk delete) on every table in `DbTables`. Security reviews repeatedly flag this
+as a vulnerability and propose secure-by-default behavior: routes disabled until
+explicitly enabled, or a mandatory auth hook.
+
+## Decision
+
+The plugin stays open by default. Authentication and authorization are the consumer's
+job, wired through the tools provided for it: `onRequests` (global or per-table request
+hooks), `operations` (per-table whitelist of registered routes), and `tenantScope`
+(tenant isolation). The README carries a prominent warning in its Security section.
+
+## Alternatives considered
+
+- **Deny-by-default routes** (`operations` required, empty = nothing exposed) — rejected:
+  it turns the five-minute quick start into configuration boilerplate, and the plugin's
+  primary use case is rapid internal API scaffolding where the consumer adds auth at the
+  Fastify level anyway.
+- **Mandatory auth callback** (refuse to register without an `onRequests`) — rejected:
+  imposes an auth model on consumers who legitimately handle auth outside the plugin
+  (gateway, network isolation, Fastify-level hooks on the parent scope).
+
+## Consequences
+
+- **You must lock it down before exposing it.** The responsibility is documented, not
+  enforced.
+- Security reviews will keep flagging this; the answer is this ADR plus the README
+  Security section, not a behavior change.
+- `operations` gates HTTP routes only — the programmatic `sqlApi.*` methods remain
+  available to consumer code, by design.

package/docs/adr/0003-bulk-not-transactional.md

@@ -0,0 +1,35 @@
+# 0003. Bulk operations are not transactional
+
+- **Status**: accepted
+- **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
+
+## Context
+
+Single insert and update run inside a transaction: main record, secondaries, deletions
+and after-hooks are atomic (`QueryClient.withTransaction`, degrading gracefully when the
+adapter has no `connect()`). Bulk upsert and bulk delete do not — a failure partway
+through leaves the earlier items committed. Reviews periodically report this as an
+inconsistency and propose wrapping bulk operations in a transaction.
+
+## Decision
+
+Bulk operations stay non-transactional. They are a shortcut for issuing many single
+operations efficiently, not an atomic batch primitive: "all or nothing" is explicitly not
+part of their contract.
+
+## Alternatives considered
+
+- **Wrap each bulk request in one transaction** — rejected: changes the semantics from
+  "N independent operations" to "one atomic batch", which is a different feature. Large
+  batches would also hold long transactions with the associated lock footprint.
+- **Opt-in `transactional: true` flag** — rejected for now: adds API surface for a need
+  no consumer has expressed; a consumer needing atomicity can call the programmatic
+  `sqlApi.*` methods inside their own `withTransaction`.
+
+## Consequences
+
+- A failed bulk request may have partially applied. Consumers that care must either
+  retry idempotently (upsert semantics make this natural) or manage their own
+  transaction via the programmatic API.
+- Bulk delete reports the ids actually deleted (`afterBulkDelete` receives the actual
+  subset), which is the honest contract for a non-atomic batch.

package/docs/adr/0004-updates-always-open.md

@@ -0,0 +1,46 @@
+# 0004. Updates are always open — no `excludeFromUpdate`
+
+- **Status**: accepted
+- **Date**: 2026-07-23
+
+## Context
+
+`excludeFromCreation` strips client-supplied fields from inserts. A symmetric
+`excludeFromUpdate` was proposed to statically block fields on the update path (e.g.
+`createdAt`, `isAdmin`), partly to close the asymmetry where a field excluded from
+creation can still be modified via `PUT`.
+
+## Decision
+
+No `excludeFromUpdate`. Every Schema field is updatable by default, and
+`excludeFromCreation` is defined as an **ergonomics tool for creation** (auto-generated
+PKs, DB-default columns — its original purpose was handling autoincrement validation),
+**not** a field-level security mechanism.
+
+Field-level update rules are product logic the plugin must not decide: a super admin may
+legitimately fix an `updatedAt`; in one product users may move themselves across tenants,
+in another an admin moves others, in a third nobody moves anyone. A static list cannot
+express any of this — real authorization is contextual (session, role, record state).
+Consumers encode their rules in `beforeUpdate` (silent strip) or `validate` (loud 400),
+or move privileged transitions to dedicated endpoints and keep them off the auto routes
+via `operations`.
+
+## Alternatives considered
+
+- **`excludeFromUpdate` list** — rejected: the main risk is the *false sense of
+  security*. It only covers "nobody, ever, via API", while the dangerous real-world cases
+  (`isAdmin`, roles, ownership) are session-dependent — someone would use the list for
+  them and believe the problem solved.
+- **`immutable: [...]` / per-field `writable` modes** — rejected: a bigger redesign of
+  the write model for the same limited static semantics.
+
+## Consequences
+
+- Sensitive flags in the Schema are updatable through the auto routes until the consumer
+  adds a hook. This is documented prominently (README Security → "Field-level update
+  rules are product logic", AGENTS_BACKEND.md pattern "Protect sensitive fields on
+  update").
+- The tenant column is the one deliberate exception, and only under opt-in `tenantScope`:
+  tenant-scoped callers cannot re-tenant records (isolation contract), while admin
+  callers (`getTenantId` → `null`) remain unrestricted — consistent with "the plugin does
+  not decide product rules".

package/docs/adr/0005-insert-pipeline-sanitize-before-hooks.md

@@ -0,0 +1,51 @@
+# 0005. Insert pipeline: client payload sanitized before `beforeInsert`
+
+- **Status**: accepted
+- **Date**: 2026-07-23
+
+## Context
+
+Until v0.1.9 the insert pipeline applied `excludeFromCreation` *after* the `beforeInsert`
+hook, so a value the hook assigned to an excluded field was silently stripped from the
+INSERT. This broke the documented server-generated-id pattern (TEXT PK in
+`excludeFromCreation`, id generated in `beforeInsert` → not-null violation) and
+contradicted the documented contract that hook mutations propagate to the SQL. The same
+ordering flaw let an excluded FK column erase the engine's own FK auto-fill on secondary
+records.
+
+## Decision
+
+Exclusion is a whitelist on **client input** and runs at the client boundary. The insert
+pipeline order is, for both single insert and bulk upsert:
+
+1. `validate` — receives the payload **as sent by the client** (documented contract);
+2. `excludeFromCreation` strip;
+3. `beforeInsert` — hook mutations, including on excluded fields, reach the SQL;
+4. conversion to DB column format.
+
+For secondary records, exclusion runs **before** the engine's FK auto-fill, so the
+injected parent key always survives.
+
+Server-side writers are ordered by trust: client input is sanitized first, then hooks
+mutate freely, then engine-enforced values (tenant injection/validation) run last and
+fail loudly on conflict rather than stripping silently.
+
+## Alternatives considered
+
+- **Strip after the hook** (previous behavior) — rejected: silently discards
+  server-generated values; the only thing it "protected" was the ability of a hook to
+  accidentally write an excluded field, which is server code and trusted.
+- **Strip before `validate` too** — rejected: `validate` is documented to receive the
+  record as sent by the client; changing its input would break that contract for no
+  gain.
+
+## Consequences
+
+- The pattern `excludeFromCreation: ['id']` + id-generating `beforeInsert` works as
+  documented; consumers no longer need the `schemaOverrides` workaround.
+- Behavior change (noted in the CHANGELOG): a hook that assigns an excluded field now
+  writes it, where it was previously discarded.
+- `afterInsert` no longer sees client-supplied values on excluded fields — it sees what
+  was actually written.
+- Locked by unit tests (single, bulk, upsert, secondaries, validate-ordering) and by a
+  dialect-parametric integration suite reproducing the original failure.

package/docs/adr/0006-raw-db-errors.md

@@ -0,0 +1,34 @@
+# 0006. Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping
+
+- **Status**: accepted
+- **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
+
+## Context
+
+Constraint violations (unique, foreign key, not-null) bubble up from the driver and reach
+the client as a `500` carrying the raw database message. A review proposed mapping
+SQLSTATE codes to HTTP semantics — unique violation → `409`, FK/not-null violation →
+`400` — with sanitized messages.
+
+## Decision
+
+No SQLSTATE mapping in the engine. Errors the plugin itself detects (validation, missing
+PK, not found, tenant violations) throw proper `4xx` via `httpError`; everything coming
+from the database is passed through unmapped.
+
+## Alternatives considered
+
+- **SQLSTATE→HTTP mapping layer** — rejected: the mapping is dialect-specific
+  (PostgreSQL SQLSTATE vs MySQL errno), inevitably partial, and encodes product decisions
+  (is a duplicate a conflict to surface or an internal bug?) the plugin should not make.
+- **Sanitizing DB messages** — rejected as a plugin default: hiding details is an
+  environment policy, and Fastify already gives consumers the hook for it.
+
+## Consequences
+
+- Constraint violations look like server errors (`500`) to API clients, and driver
+  messages may leak schema details (table/column/constraint names). Consumers who care
+  set a Fastify `setErrorHandler` — one place, their policy, their status codes.
+- A consumer-facing "friendly duplicate error" is expected to be handled in `validate`
+  (explicit pre-check) or in the consumer's error handler, not by the engine guessing
+  intent from SQLSTATE.

package/docs/adr/0007-explicit-table-generation.md

@@ -0,0 +1,39 @@
+# 0007. Table generation is explicit — `--all` is a migration helper, not the default
+
+- **Status**: accepted
+- **Date**: 2026-07-23
+
+## Context
+
+`sqlapi-generate-schema` with no arguments introspects every table, while
+`sqlapi-generate-tables` with no arguments prints usage and exits, requiring `--all` or
+explicit table names. A review flagged the opposite defaults as an inconsistency to
+harmonize.
+
+## Decision
+
+The asymmetry is deliberate and stays. The two generators have different roles:
+
+- **Schemas** are disposable mirrors of the database — regenerating all of them is always
+  correct, so "all" is the natural default.
+- **Table files are the consumer's working set**: which tables become API endpoints is a
+  deliberate choice, and it is legitimate to keep tables out of `DbTables`. The intended
+  flow is *"I added a table, I generate its Table file explicitly"*
+  (`sqlapi-generate-tables customer`). If the default were "all", every run would
+  resurrect Table files the consumer had deliberately deleted, forcing them to delete the
+  same files again and again. `--all` exists only as a bootstrap helper when introducing
+  the plugin into an existing codebase.
+
+## Alternatives considered
+
+- **Default to `--all` (mirror generate-schema)** — rejected: re-creates deleted Table
+  files on every run, fighting the consumer's curation of the exposed surface.
+- **Tracking deleted tables** (a skip-list) — rejected: state to maintain for a problem
+  explicit invocation solves for free.
+
+## Consequences
+
+- `sqlapi-generate-tables` keeps requiring `--all` or table names; running it bare prints
+  usage and exits non-zero.
+- The generator never overwrites existing Table files, so both the explicit and the
+  `--all` flow are safe to re-run.

package/docs/adr/README.md

@@ -0,0 +1,50 @@
+# Architecture Decision Records
+
+Deliberate design decisions of `fastify-auto-sqlapi`, with their rationale and the
+alternatives that were considered and rejected.
+
+**If you are an agent or a contributor about to "fix" one of the behaviors below: read the
+matching ADR first.** These are not gaps or oversights — proposals that re-litigate a
+decision recorded here should either reference new arguments the ADR does not address, or
+be dropped.
+
+ADRs are immutable: a decision is changed by adding a new ADR that supersedes the old one,
+not by editing history.
+
+## Index
+
+| # | Decision |
+|---|----------|
+| [0001](./0001-no-orm-raw-sql.md) | No ORM — raw SQL with minimal dependencies |
+| [0002](./0002-open-by-default.md) | Open by default — no imposed auth model |
+| [0003](./0003-bulk-not-transactional.md) | Bulk operations are not transactional |
+| [0004](./0004-updates-always-open.md) | Updates are always open — no `excludeFromUpdate` |
+| [0005](./0005-insert-pipeline-sanitize-before-hooks.md) | Insert pipeline: client payload sanitized before `beforeInsert` |
+| [0006](./0006-raw-db-errors.md) | Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping |
+| [0007](./0007-explicit-table-generation.md) | Table generation is explicit — `--all` is a migration helper, not the default |
+
+## When to write one
+
+Only when a decision was genuinely debated, or is counter-intuitive enough that a reasonable
+outsider would mistake it for a bug. Plain conventions belong in [AGENTS.md](../../AGENTS.md).
+
+## Format
+
+```markdown
+# NNNN. Title (imperative statement of the decision)
+
+- **Status**: accepted | superseded by NNNN
+- **Date**: YYYY-MM-DD
+
+## Context
+What problem or tension forced a choice.
+
+## Decision
+What was decided, stated plainly.
+
+## Alternatives considered
+Each rejected option and the reason it lost.
+
+## Consequences
+What follows — including the costs accepted knowingly.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "AGENTS.md",
     "AGENTS_BACKEND.md",
     "AGENTS_FRONTEND.md",