Merge branch 'main' of github.com:devforth/adminforth into update-express-version

AdminForth/1781/image

Author: yaroslav8765

adminforth/documentation/docs/tutorial/03-Customization/03-virtualColumns.md

@@ -53,6 +53,10 @@ columns: [
 ```
 
  This field will be displayed in show and list views with custom component `CountryFlag.vue`.
+
+:::tip Enriching a virtual column from a hook
+If you fill a virtual column from a hook (e.g. [`afterDatasourceResponse`](./04-hooks.md#modify-record-after-it-is-returned-from-database)) instead of a custom component, write the enriched value into a field with **the same name as the virtual column**. This keeps the value addressable by column name everywhere — most importantly, the [Agent plugin](/docs/tutorial/Plugins/agent/) selects records by column name, so a mismatched field name makes it select the (empty) virtual column and miss your enriched data.
+:::
  Create file `CountryFlag.vue` in `custom` folder of your project:
 
  ```html title="./custom/CountryFlag.vue"

adminforth/documentation/docs/tutorial/03-Customization/04-hooks.md

@@ -199,6 +199,12 @@ Also you can use this hook to enrich the returned records list with some additio
 }
 ```
 
+:::tip Name enriched fields after the virtual column
+When you enrich records with extra fields for display, declare a matching [virtual column](./03-virtualColumns.md) and use **the same name** for the field you add in the hook (e.g. add a `priceWithTax` virtual column and write `r.priceWithTax` in the hook). 
+
+Reusing the same name keeps the enriched value tied to a column the rest of AdminForth knows about. In particular, the [Agent plugin](/docs/tutorial/Plugins/agent/) selects records by column name when answering questions — if the hook writes to a different field than the virtual column, the agent selects the (empty) virtual column and never sees your enriched value.
+:::
+
 ### Dropdown list of foreignResource
 
 By default if there is `foreignResource` like we use for demo on `realtor_id` column, the filter will suggest a

adminforth/documentation/docs/tutorial/06-Adapters/04-storage-adapters.md

@@ -55,10 +55,12 @@ If you don't want to use a key/value adapter and you don't need to clean up file
 
 Since the adapter uses a key/value adapter to store keys for deletion, it is important to use persistent storage, so the data will be safe:
 
-- (⛔️) [RAM adapter](07-key-value-adapters.md#ram-adapter) - not recommended, because after a server restart all data will be lost
-- (✅) [Redis adapter](07-key-value-adapters.md#redis-adapter) - Redis itself stores data in-memory, but you can set it up to write data to an `.rdb` file so the database is restored on server restart. However, it requires regular database snapshots and persistent Docker storage setup
-- (✅✅) [LevelDB adapter](07-key-value-adapters.md#leveldb-adapter) - can be used, but you need to set up persistent storage in your Docker container, so data won't be lost between restarts
-- (✅✅✅) [Resource adapter](07-key-value-adapters.md#resource-based-adapter) - uses a database to store key/value pairs, so data will be safe between restarts, but you need to create an extra table for this storage
+- (⛔️) [RAM adapter](07-key-value-adapters.md#ram-adapter) - not recommended, because after an admin process restart (e.g. redeployment) all data and orphan file tracking info will be lost (and files will not be cleaned up)
+- (✅) [LevelDB adapter](07-key-value-adapters.md#leveldb-adapter) - can be used, but you need to set up persistent storage in your Docker container by monting leveldb data directory into a volume, so data won't be lost between restarts
+- (✅✅) [Redis adapter](07-key-value-adapters.md#redis-adapter) - Redis itself stores data in RAM memory but modern versions also able to persist it into disk. If you are running Redis in docker we recommend you to ensure that CI/CD pipeline does not force it to restarts during each redeployment, also ensure that you mount `/data` dir into volume. ()
+- (✅✅✅) [Resource adapter](07-key-value-adapters.md#resource-based-adapter) - uses a database to store key/value pairs, so data will be safe between restarts, but you need to create an extra table for this storage. 
+
+Please note that one adapter instance can be also reused for any other purposes or plugins, so if your application need KV adapter to multiple purposes, you can instantiate it once in dedicated utility file and reuse this instance in other places. Internally each KV method exposes 'collection' parameter which allows to separate data for different purposes or by different plugins. 
 
 
 ### Cloudflare R2 setup example

adminforth/documentation/docs/tutorial/06-Adapters/07-key-value-adapters.md

@@ -78,6 +78,7 @@ model key_values {
   key String @id
   value String
   collection String?
+  expire_at DateTime? //optional column
 
   @@index([key])
   @@index([collection])
@@ -117,6 +118,10 @@ export default {
     {
       name: 'collection',
       type: AdminForthDataTypes.STRING,
+    },
+    {
+      name: 'expire_at',
+      type: AdminForthDataTypes.DATETIME,
     }
   ],
   options: {
@@ -157,5 +162,6 @@ const adapter = new ResourceKeyValueAdapter({
   keyField: 'key',
   valueField: 'value',
   collectionField: 'collection',
+  expireField: 'expire_at'
 })
 ```

adminforth/documentation/docs/tutorial/09-Plugins/11-oauth.md

@@ -373,7 +373,7 @@ Register the same `redirectUri` in BotFather under **Login Widget → Redirect U
 
 If you use `@adminforth/chat-surface-adapter-telegram`, users must connect Telegram from **Settings → Connected Accounts** before the Telegram bot can identify them.
 
-### Kaycloack Adapter
+### Keycloak Adapter
 
 Install Adapter:
 

adminforth/modules/utils.ts

@@ -6,7 +6,6 @@ import crypto from 'crypto';
 import { AdminForthConfig, AdminForthResource, AdminForthResourceColumnInputCommon,Filters, IAdminForth, Predicate } from '../index.js';
 import { RateLimiterMemory, RateLimiterAbstract } from "rate-limiter-flexible";
 import { PERIOD_UNITS, type PeriodString, type PeriodUnit } from '../types/Back.js';
-import { z } from "zod";
 
 // @ts-ignore-next-line
 
@@ -646,21 +645,4 @@ export function applyRegexValidation(value, validation) {
   ╚${horizontal}╝
   ${RESET}
 `;
-  }
-
-
-export function parseBody<T>(
-  schema: z.ZodType<T>,
-  body: unknown,
-  response: { setStatus: (code: number, message: string) => void },
-): { ok: true; data: T } | { ok: false; error: { error: string; details: unknown } } {
-  const parsed = schema.safeParse(body ?? {});
-  if (!parsed.success) {
-    response.setStatus(400, '');
-    return {
-      ok: false,
-      error: { error: 'Request body validation failed', details: parsed.error.issues },
-    };
-  }
-  return { ok: true, data: parsed.data };
-}
+  }

adminforth/servers/express.ts

@@ -109,7 +109,7 @@ function normalizeExpressRuntimeSchema(schema: unknown): AnySchemaObject | undef
   }
 
   if (isZodSchemaLike(schema)) {
-    return z.toJSONSchema(schema as any, { target: 'openapi-3.0' }) as AnySchemaObject;
+    return z.toJSONSchema(schema as any, { target: 'draft-07' }) as AnySchemaObject;
   }
 
   return schema as AnySchemaObject;
@@ -602,22 +602,22 @@ class ExpressServer implements IExpressHttpServer {
       description,
       request_schema,
       response_schema,
-      responce_schema,
       agent,
       target='json'
     } = options;
     if (!path.startsWith('/')) {
       throw new Error(`Path must start with /, got: ${path}`);
     }
     const fullPath = `${this.adminforth.config.baseUrl}/adminapi/v1${path}`;
-    const normalizedResponseSchema = response_schema ?? responce_schema;
-    const registeredApiSchema = (request_schema || normalizedResponseSchema)
+    const normalizedRequestSchema = normalizeExpressRuntimeSchema(request_schema);
+    const normalizedResponseSchema = normalizeExpressRuntimeSchema(response_schema);
+    const registeredApiSchema = (normalizedRequestSchema || normalizedResponseSchema)
       ? this.adminforth.openApi.registerApiSchema({
         method,
         noAuth,
         path: fullPath,
         description,
-        request_schema,
+        request_schema: normalizedRequestSchema,
         response_schema: normalizedResponseSchema,
         agent,
         handler,

adminforth/servers/openapi.ts

@@ -51,14 +51,13 @@ class OpenApiRegistry implements IOpenApiRegistry {
   }
 
   registerApiSchema(options: IAdminForthEndpointOptions): IRegisteredApiSchema {
-    const responseSchema = options.response_schema ?? options.responce_schema;
     const route: IRegisteredApiSchema = {
       method: options.method.toLowerCase(),
       path: options.path,
       description: options.description,
       agent: options.agent,
       request_schema: options.request_schema,
-      response_schema: responseSchema,
+      response_schema: options.response_schema,
       meta: options.meta,
       handler: options.handler,
     };

adminforth/types/Back.ts

@@ -73,7 +73,6 @@ export interface IAdminForthEndpointOptionsBase {
   description?: string,
   request_schema?: AnySchemaObject,
   response_schema?: AnySchemaObject,
-  responce_schema?: AnySchemaObject,
   agent?: AgentToolMeta,
   meta?: Record<string, unknown>,
   target?: 'json' | 'upload',

dev-demo/migrations/prisma/sqlite/migrations/20260702070424_add_adminforth_key_value_expiry_field/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "key_values" ADD COLUMN "expire_at" DATETIME;