fastify-auto-sqlapi 0.1.9 → 0.1.11

package/AGENTS.md

@@ -12,7 +12,9 @@ The plugin generates REST endpoints (search, get, insert, update, delete, bulk u
 
 - **[AGENTS_BACKEND.md](./AGENTS_BACKEND.md)** — Setup workflow, CLI, schema/table generation, `defineTable()` complete reference, `buildRelation` (alias + unique), `extraFilters` + `extendedCondition`, **SqlApi** (programmatic high-level API for custom routes), ConditionBuilder API, QueryClient API, Swagger, multi-tenant configuration, **validation** (`validate` + `validateBulk`), hooks, key conventions, common backend patterns, FAQ/gotchas, dialect differences.
 
-- **[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)** — Generated endpoints overview, search (POST with body filters, conditions/advanced filters using ConditionBuilder methods, query params for ordering/pagination/aggregation), `joinMustExist` (EXISTS-based filtering by related tables), `joinMultiple` (fetch child rows), `joinGroup` (aggregations), `joinLeft` (embed N:1 parent inline), GET, INSERT (with secondaries), UPDATE (with secondaries + deletions), DELETE, bulk upsert, bulk delete, response shapes (PK-only), **validation errors** (structured field-level 400 responses), pagination, computed values.
+- **[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)** — Compact client-side request grammar (LLM-oriented, also the system-prompt reference for runtime agent clients): all endpoints, search with the four join families (`joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`), conditions methods, ordering (including dotted notations), pagination, writes with secondaries/deletions, structured 400 error shape. Pair with `GET {prefix}/agent/manifest.md` (when `agentManifest` is enabled) for this deployment's tables/fields/aliases.
+
+- **[docs/adr/](./docs/adr/README.md)** — Architecture Decision Records. **Read before proposing a "fix" to a deliberate behavior**: open-by-default, non-transactional bulk, always-updatable fields, raw DB errors, insert-pipeline ordering. These are recorded decisions with rationale, not gaps.
 
 ## Quick Reference
 

package/AGENTS_BACKEND.md

@@ -227,6 +227,8 @@ export const TableAgentTeamLink = defineTable({
 
 When `primary` is an array, RETURNING clauses include all PK columns, and response shapes contain all PK fields.
 
+**By-single-id operations are not available for composite PKs**: `get`, `delete` and `bulkDelete` address a record by one PK value, so their routes are skipped for composite-PK tables (matching on the first column alone could hit many rows — destructively for the deletes). Explicitly listing one of them in `operations` throws at startup, and the programmatic `sqlApi.get/delete/bulkDelete` reject with 400. Use `search` (all PK fields as filters), `update` (matches every PK column), or a custom route.
+
 ### All keys
 
 ```typescript
@@ -380,7 +382,7 @@ upsertMap: buildUpsertRules(
 // → PUT /rest/product { "main": {...}, "secondaries": { "translations": [{ "lang": "en", "name": "Bike" }] } }
 ```
 
-Expose a composite-PK table as a standalone CRUD table only when it stands on its own (M:N link tables, natural keys) — composite PKs are fully supported there too.
+Expose a composite-PK table as a standalone CRUD table only when it stands on its own (M:N link tables, natural keys) — search, insert, update and bulk upsert fully support composite PKs; the by-single-id routes (get, delete, bulkDelete) are skipped for them.
 
 **Aliasing the same table twice**: declare two `buildRelation` entries with different `alias`. Example: a `session` table referencing `user` for both `createdBy` and `updatedBy`:
 
@@ -527,7 +529,7 @@ For `joinLeft` specifically, the computed expr is automatically alias-prefixed b
 
 ## ConditionBuilder API
 
-Used in `extendedCondition` callbacks, hooks, and exposed via the `conditions` field in the search API (see [AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md#conditions-advanced-filters)).
+Used in `extendedCondition` callbacks, hooks, and exposed via the `conditions` field in the search API (methods and params arity in [AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)).
 
 ```typescript
 const cb = new ConditionBuilder('AND');  // or 'OR'
@@ -773,7 +775,8 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 
 - **camelCase in API, any case in DB**: all request/response fields are camelCase. The plugin converts via `col()` and `colMap`. For snake_case DB columns (default), conversion is automatic. For camelCase DB columns (e.g. betterauth), the CLI generates a `colMap` that preserves the original column names — no conversion needed. Manual schemas without `colMap` fall back to `toUnderscore()`.
 - **All fields Optional in response**: `RETURNING *` may return any subset. Response schemas use `Type.Partial`.
-- **`excludeFromCreation`**: **IMPORTANT** — auto-increment PKs (e.g. `id` serial/auto_increment) MUST be listed here, otherwise INSERT will try to send them and fail. The CLI auto-detects this and adds it by default. Also useful for `createdAt`/`updatedAt` columns managed by DB defaults or hooks.
+- **Nullable columns use `Nullable(T)` (type-array form)**: the generator emits `Type.Optional(Nullable(T))` for nullable columns — `Nullable` (exported by the package) produces `{ type: ['integer', 'null'] }`. Do NOT replace it with `Type.Union([T, Type.Null()])`: under Fastify's default Ajv `coerceTypes` a union corrupts values through its branches (`null` → `0` with the Null branch last, `0`/`""` → `null` with it first), while the type array validates and serializes NULL correctly. A bare `Type.Optional(T)` is also wrong: NULL serializes as `0`/`""`. In `filters`, an explicit `null` on a schema field builds `WHERE col IS NULL`.
+- **`excludeFromCreation`**: **IMPORTANT** — auto-increment PKs (e.g. `id` serial/auto_increment) MUST be listed here, otherwise INSERT will try to send them and fail. The CLI auto-detects this and adds it by default. Also useful for `createdAt`/`updatedAt` columns managed by DB defaults or hooks. It strips **client-supplied** values only: the payload is sanitized before `beforeInsert` runs, so a value the hook assigns to an excluded field (e.g. a server-generated TEXT id) DOES reach the INSERT. Same for the engine's FK auto-fill on secondaries — an excluded FK column does not suppress it. It is an **ergonomics tool for creation, NOT a field-level security mechanism**: it does not apply to updates — every Schema field is updatable by default, by design. Field-level update rules (`isAdmin`, roles, owner/tenant columns, state fields) are product logic: enforce them in `beforeUpdate` (silent strip) or `validate` (loud 400), or move the privileged transition to a dedicated endpoint and keep it off the auto routes via `operations`.
 - **`readExclude`**: fields hidden from every read — not projected by search/get, omitted from read response schemas and from this table's default (`*`) join selection when it is a join target. Referencing one from `filters`, `conditions`, `orderBy`, `joinGroup` aggregations or an explicit join `selection` returns 400: hiding a field from output while allowing it to be filtered would leak its value by bisection. **Writes are unaffected** — insert/update/bulk still accept the field, so a column can be writable but never readable (password hash, access token). Primary keys cannot be excluded. Complementary to trimming the Schema, which removes the column from reads *and* writes.
 - **`upsertMap`**: when present for a schema, INSERT becomes upsert. PostgreSQL: `ON CONFLICT (...) DO UPDATE`. MySQL/MariaDB: `ON DUPLICATE KEY UPDATE`. Applies to both main and secondary tables.
 - **`schemaOverrides`**: override auto-generated schema fields with stricter TypeBox types (e.g. `{ email: Type.String({ format: 'email' }) }`). Overrides are merged into the body schema for insert, update, and bulk-upsert. The original Schema file is never modified. In updates, overridden fields are still wrapped in Optional (validates only when present). Overrides appear in Swagger.
@@ -894,6 +897,78 @@ const TableCustomer = defineTable({
 });
 ```
 
+### PostgreSQL driver type parsers (numeric/int8 as strings, timestamp shifts)
+
+The `pg` driver — not the plugin — returns `numeric`/`int8` as **strings** (precision
+safety), parses `date` into a JS `Date` at local midnight, and interprets
+`timestamp without time zone` in the server's local timezone. The plugin deliberately does
+not touch `pg.types` (global process state — see the design principles). If your API should
+return numbers and stable date strings, configure the parsers once at startup, before
+creating the pool:
+
+```typescript
+import pg from 'pg';
+
+pg.types.setTypeParser(pg.types.builtins.INT8, (v) => parseInt(v, 10));
+pg.types.setTypeParser(pg.types.builtins.NUMERIC, (v) => parseFloat(v));
+// Keep dates/timestamps as verbatim strings (no local-timezone Date conversion).
+// Recommended when the DB stores UTC in `timestamp without time zone` (several ERPs do).
+pg.types.setTypeParser(pg.types.builtins.DATE, (v) => v);
+pg.types.setTypeParser(pg.types.builtins.TIMESTAMP, (v) => v);
+```
+
+Note: HTTP responses already coerce a numeric string like `"42"` to a number when the
+schema says integer — the parsers matter for programmatic `sqlApi.*` results, arithmetic in
+hooks, and timestamp correctness.
+
+### Translated jsonb fields (multi-language columns)
+
+Some applications (several ERPs among them) store translatable columns as jsonb:
+`{"en_US": "Bike", "it_IT": "Bici"}`. Expose the translation as a computed field — usable
+in `filters`, `conditions`, `orderBy` and (opt-in) projected via `selectComputed`:
+
+```typescript
+const LANG = process.env.APP_LANG || 'en_US';
+
+const TableProductTemplate = defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaProductTemplate),
+  computedFields: {
+    displayName: ({ qiCol }) => ({
+      expr: `${qiCol('name')}->>'${LANG}'`,
+      type: Type.String(),
+    }),
+  },
+});
+// → POST /search/product_template { "filters": { "displayName": "Bike" } }
+//   or body { "selectComputed": ["displayName"] } to project it in the response
+```
+
+### Protect sensitive fields on update (isAdmin, roles, ownership)
+
+Every Schema field is updatable by default — the plugin does not impose field-level rules
+(see `excludeFromCreation` in Key Conventions). Encode yours in the hooks:
+
+```typescript
+const TableUser = defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaUser),
+  // Silent strip: non-admins simply cannot touch the flag
+  beforeUpdate: async (db, req, fields) => {
+    if (!req.user.isAdmin) delete fields.isAdmin;
+  },
+  // Or loud 400 via validate:
+  // validate: async (db, req, main) => {
+  //   if (main.isAdmin !== undefined && !req.user.isAdmin)
+  //     return [['isAdmin', 'forbidden']];
+  //   return [];
+  // },
+});
+```
+
+For privileged transitions (promote to admin, move across tenants) prefer a dedicated
+endpoint with its own auth/audit, and keep the operation off the auto routes via `operations`.
+
 ### Full-text search filter
 
 ```typescript
@@ -978,6 +1053,30 @@ await app.register(async (instance) => {
 }, { prefix: '/admin' });
 ```
 
+### LLM / agent surface (read-only + manifest)
+
+Give a chat agent direct data access with the plugin as enforcement layer (tenant scoping,
+`readExclude`, caps still apply to whatever the model invents). Read-only surface + the
+manifest endpoint, agent-specific auth:
+
+```typescript
+import { searchRoutes, getRoutes, agentManifestRoutes } from 'fastify-auto-sqlapi';
+
+await app.register(async (instance) => {
+  const opts = { DbTables: dbTables, onRequests: [agentAuth] };
+  await instance.register(searchRoutes, opts);
+  await instance.register(getRoutes, opts);
+  await instance.register(agentManifestRoutes, opts);   // GET /agent/manifest(.md)
+}, { prefix: '/agent' });
+```
+
+System prompt = `AGENTS_FRONTEND.md` (request grammar, ships in the package) + the output of
+`GET /agent/manifest.md` (this deployment's tables/fields/aliases). On the main plugin the
+manifest is enabled with the `agentManifest: true` option. Validation strategy: either a
+loose generic tool (`table` enum from the manifest, free body) with the structured 400
+`fields[]` as the retry signal, or strict provider-side tools via
+`agentToolSchemas(dbTables, table)` — the exact JSON Schemas the routes validate with.
+
 ---
 
 ## FAQ / Gotchas