Merge pull request #472 from devforth/next

Next

Author: ivictbor

adapters/install-adapters.sh

@@ -4,7 +4,8 @@ adminforth-email-adapter-mailgun adminforth-google-oauth-adapter adminforth-gith
 adminforth-facebook-oauth-adapter adminforth-keycloak-oauth-adapter adminforth-microsoft-oauth-adapter \
 adminforth-twitch-oauth-adapter adminforth-image-generation-adapter-openai adminforth-storage-adapter-amazon-s3 \
 adminforth-storage-adapter-local adminforth-image-vision-adapter-openai adminforth-key-value-adapter-ram \
-adminforth-login-captcha-adapter-cloudflare adminforth-login-captcha-adapter-recaptcha adminforth-completion-adapter-google-gemini"
+adminforth-login-captcha-adapter-cloudflare adminforth-login-captcha-adapter-recaptcha adminforth-completion-adapter-google-gemini \
+adminforth-key-value-adapter-redis adminforth-key-value-adapter-leveldb"
 
 # for each
 install_adapter() {
@@ -16,7 +17,7 @@ install_adapter() {
       git pull
   else
       echo "Repository for $adapter does not exist. Cloning..."
-      git clone git@github.com:devforth/$adapter.git "$adapter"
+      git clone https://github.com/devforth/$adapter.git "$adapter"
       cd "$adapter"
   fi
 

adminforth/commands/createApp/templates/.env.local.hbs

@@ -1,5 +1,8 @@
 ADMINFORTH_SECRET=123
 NODE_ENV=development
+DEBUG_LEVEL=info
+AF_DEBUG_LEVEL=info
+DB_DEBUG_LEVEL=info
 DATABASE_URL={{{dbUrl}}}
 {{#if prismaDbUrl}}
 PRISMA_DATABASE_URL={{{prismaDbUrl}}}

adminforth/commands/createApp/templates/api.ts.hbs

@@ -1,10 +1,13 @@
-import { Express } from "express";
+import { Express, Request, Response } from "express";
 import { IAdminForth } from "adminforth";
-
 export function initApi(app: Express, admin: IAdminForth) {
   app.get(`${admin.config.baseUrl}/api/hello/`,
-    (req, res) => {
-      res.json({ message: "Hello from AdminForth API!" });
+    async (req: Request, res: Response) => {
+      const allUsers = await admin.resource("adminuser").list([]);
+      res.json({
+        message: "Hello from AdminForth API!",
+        users: allUsers,
+      });
     }
   );
 }

adminforth/dataConnectors/postgres.ts

@@ -385,7 +385,7 @@ class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDa
         const tableName = resource.table;
         const result = {};
         await Promise.all(columns.map(async (col) => {
-            const q = `SELECT MIN(${col.name}) as min, MAX(${col.name}) as max FROM "${tableName}"`;
+            const q = `SELECT MIN("${col.name}") as min, MAX("${col.name}") as max FROM "${tableName}"`;
             dbLogger.trace(`🪲📜 PG Q: ${q}`);
             const stmt = await this.client.query(q);
             const { min, max } = stmt.rows[0];

adminforth/documentation/docs/tutorial/03-Customization/02-customFieldRendering.md

@@ -233,6 +233,97 @@ Now you can use this component in the configuration of the resource:
 }
 ```
 
+### Custom record editing (updating other fields)
+
+Sometimes a custom editor needs to update not only its own field, but also other fields of the record (for example, generate a slug from a title).
+
+For this, custom `edit`/`create` components can emit an `update:recordFieldValue` event with the payload `{ fieldName, fieldValue }`. AdminForth will update the corresponding field in the record.
+
+```html title='./custom/TitleWithSlugEditor.vue'
+<template>
+  <div class="flex flex-col gap-2">
+    <Input
+      :model-value="record[column.name]"
+      :placeholder="$t('Title')"
+      @update:model-value="onTitleChange"
+    />
+    <Input
+      :model-value="record.slug"
+      :placeholder="$t('Slug')"
+      readonly
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import Input from "@/afcl/Input.vue";
+import type {
+  AdminForthResourceColumnCommon,
+  AdminForthResourceCommon,
+  AdminUser,
+} from "@/types/Common";
+
+const props = defineProps<{
+  column: AdminForthResourceColumnCommon;
+  record: any;
+  meta: any;
+  resource: AdminForthResourceCommon;
+  adminUser: AdminUser;
+  readonly: boolean;
+}>();
+
+const emit = defineEmits([
+  "update:value", // update current column value
+  "update:recordFieldValue", // update any other field in the record
+]);
+
+function slugify(value: string) {
+  return value
+    ?.toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)+/g, "");
+}
+
+function onTitleChange(newTitle: string) {
+  // update current column value
+  emit("update:value", newTitle);
+
+  // update another field in the record (e.g. slug)
+  emit("update:recordFieldValue", {
+    fieldName: "slug",
+    fieldValue: slugify(newTitle),
+  });
+}
+</script>
+```
+
+And use it in the resource configuration for both `edit` and `create` views:
+
+```ts title='./resources/apartments.ts'
+{
+  ...
+  resourceId: 'aparts',
+  columns: [
+    ...
+    {
+      name: 'title',
+      components: {
+        edit: '@@/TitleWithSlugEditor.vue',
+        create: '@@/TitleWithSlugEditor.vue',
+      },
+    },
+    {
+      name: 'slug',
+      // standard input; value will be kept in sync
+      ...
+    },
+    ...
+  ],
+  ...
+}
+```
+
 ### Custom inValidity inside of the custom create/edit components
 
 Custom componets can emit `update:inValidity` event to parent to say that the field is invalid.

adminforth/documentation/docs/tutorial/05-ListOfAdapters.md

@@ -244,10 +244,52 @@ The RAM adapter is a simplest in-memory key-value storage. Stores data in proces
 
 Pros:
 * Simplest in use - does not reqauire any external daemon.
+
 Cones:
 * In production sutable for single-process installations only
 
 
+### Redis adapter
+
+```bash
+npm i @adminforth/key-value-adapter-redis
+```
+
+Redis adapter uses in-memory RAM-based Redis database with O(1) get complexity. It is great fit for most of lightweight tasks which fit in RAM. Also capable with multi-process or replica-based installations as centralized storage. Please note that Redis daemon might be not persisted to disk during restarts without additional settings, so if persistence is critical for your task - you might need to set up it separately (for many tasks like rate-limits ephemeral data are fine 
+
+
+```ts
+import RedisKeyValueAdapter from '@adminforth/key-value-adapter-redis';
+
+const adapter = new RedisKeyValueAdapter({
+  redisUrl: '127.0.0.1:6379'
+})
+
+adapeter.set('test-key', 'test-value', 120); //expiry in 120 seconds
+
+```
+
+### LevelDB adapter
+
+```bash
+npm i @adminforth/key-value-adapter-leveldb
+```
+
+LebelDB uses disk storage with o(log(n)) get complexity. Good fit for large and/or persistent KV datasets which still require fast KV access but don't efficently fit into RAM. Please not that this is a single-process adapter only, so if you will run severall processes of admin - they will not be able to work with this adapter (>=2 processes which look at same level database might lead to unpredicted behaviour - exceptions or crashes). 
+
+You can use replicas with isolated disks, however in this case state will be also separated between replicas.
+
+```ts
+import LevelDBKeyValueAdapter from '@adminforth/key-value-adapter-leveldb'
+
+const adapter = new LevelDBKeyValueAdapter({ 
+  dbPath: './testdb' 
+});
+
+adapeter.set('test-key', 'test-value', 120); //expiry in 120 seconds
+
+```
+
 ## 🤖Captcha adapters
 
 Used to add capthca to the login screen

adminforth/documentation/docs/tutorial/08-Plugins/02-TwoFactorsAuth.md

@@ -280,10 +280,6 @@ options: {
           adminUser: adminUser,
         //diff-add
           userPk: adminUser.pk,
-        //diff-add
-          cookies: extra.cookies,
-        //diff-add
-          response: response,
         //diff-add
           extra: extra,
         //diff-add
@@ -393,8 +389,6 @@ hooks: {
       const verifyRes = await t2fa.verify(confirmationResult, {
         adminUser,
         userPk: adminUser.pk,
-        cookies: extra?.cookies,
-        response,
         extra
       });
       if (!verifyRes || 'error' in verifyRes) {
@@ -404,7 +398,7 @@ hooks: {
     },
   },
   create: {
-    beforeSave: async ({ adminUser, adminforth, extra }) => {
+    beforeSave: async ({ adminUser, adminforth, response, extra }) => {
       const t2fa = adminforth.getPluginByClassName('TwoFactorsAuthPlugin');
       if (!t2fa) {
         return { ok: false, error: 'TwoFactorsAuthPlugin is not configured' };
@@ -418,7 +412,7 @@ hooks: {
       const verifyRes = await t2fa.verify(confirmationResult, {
         adminUser,
         userPk: adminUser.pk,
-        cookies: extra?.cookies,
+        extra
       });
       if (!verifyRes || 'error' in verifyRes) {
         return { ok: false, error: verifyRes?.error || 'Two-factor verification failed' };
@@ -534,12 +528,8 @@ app.post(`${ADMIN_BASE_URL}/myCriticalAction`,
         adminUser: adminUser,
       // diff-add
         userPk: adminUser.pk,
-      // diff-add
-        cookies: cookies,
-      //diff-add
-        response: res, 
       //diff-add
-        extra: {...req.headers},
+        extra: {...req.headers, ...req.cookies, response: res},
       //diff-add
       });
       // diff-add

adminforth/documentation/docs/tutorial/08-Plugins/04-RichEditor.md

@@ -145,7 +145,7 @@ To get completion suggestions for the text in the editor, you can use the `compl
 
 ![alt text](gptDemo.gif)
 
-### Imges in Rich editor
+### Images in Rich editor
 
 First, you need to create resource for images:
 ```prisma title="schema.prisma"

adminforth/documentation/docs/tutorial/08-Plugins/05-upload.md

@@ -305,6 +305,73 @@ new UploadPlugin({
 > adminServeBaseUrl defines the public path prefix. If your AdminForth base URL is /admin, files will be accessible under /admin/static/source/<key>.
 
 
+## API
+
+### uploadFromBufferToNewRecord
+
+In some cases you may want to upload a file directly from your backend (for example, a file generated by a background job or received from a webhook) without going through the browser. For this, the Upload plugin exposes the `uploadFromBufferToNewRecord` method.
+
+You can code it as custom logic or you can simply reuse Upload plugin for this purpose as well.
+
+This method uploads a file from a Node.js `Buffer`, automatically creates a record in the corresponding resource, and returns both the stored file path and a preview URL.
+
+```ts title="./some-backend-service.ts"
+import { admin } from './admin'; // your AdminForth instance
+
+...
+plugins: [
+  new UploadPlugin({
+    id: 'my_reports_plugin', // unique identifier for your plugin instance
+    ....
+  })
+]
+...
+
+const plugin = admin.getPluginById('my_reports_plugin');
+
+const { path, previewUrl } = await plugin.uploadFromBufferToNewRecord({
+  filename: 'report.pdf',
+  contentType: 'application/pdf',
+  buffer, // Node.js Buffer with file content
+  adminUser, // current admin user or system user
+  recordAttributes: {
+    title: 'Generated report',
+    listed: false,
+  },
+});
+```
+
+- `uploadFromBufferToNewRecord` uses the configured storage adapter (S3, local, etc.) to store the file.
+- It automatically creates a new record in the resource and stores the file path into the column defined by `pathColumnName`, together with any extra `recordAttributes` you pass.
+- It returns an object `{ path, previewUrl }`, where `previewUrl` is the same URL that would be used for previews inside AdminForth.
+
+> ⚠️ It is not recommended to upload large files from the backend using `uploadFromBuffer`, because the entire file must go through your server memory and network. For large uploads you should prefer frontend presigned uploads directly to storage. You can find an example of presigned upload flow using upload plugin in the Rich editor plugin source code (Rich editor actually uses Upload plugin to upload images in edited content).
+
+
+### uploadFromBufferToExistingRecord
+
+If you already have a record and just want to replace the file referenced in its `pathColumnName` field, you can use the `uploadFromBufferToExistingRecord` method. It uploads a file from a Node.js `Buffer`, updates the existing record, and returns the new file path and preview URL.
+
+```ts title="./some-backend-service.ts"
+const plugin = admin.getPluginById('my_reports_plugin');
+
+const { path, previewUrl } = await plugin.uploadFromBufferToExistingRecord({
+  recordId: existingRecordId, // primary key of the record to update
+  filename: 'report.pdf',
+  contentType: 'application/pdf',
+  buffer,        // Node.js Buffer with file content
+  adminUser,     // current admin user or system user
+  extra: {},     // optional extra meta for your hooks / audit
+});
+```
+
+- Uses the same storage adapter and validation rules as `uploadFromBufferToNewRecord` (file extension whitelist, `maxFileSize`, `filePath` callback, etc.).
+- Does not create a new record – it only updates the existing one identified by `recordId`, replacing the value in `pathColumnName` with the new storage path.
+- If the generated `filePath` would be the same as the current value in the record, it throws an error to help you avoid CDN/browser caching issues. To force a refresh, make sure your `filePath` callback produces a different key (for example, include a timestamp or random UUID).
+
+> ⚠️ The same recommendation about large files applies here: avoid using `uploadFromBufferToExistingRecord` for very large uploads; prefer a presigned upload flow from the frontend instead.
+
+
 
 ## Image generation
 

adminforth/documentation/docs/tutorial/08-Plugins/14-markdown.md

@@ -37,7 +37,7 @@ Here is how it looks in show view:
 ![alt text](markdown-show1.png)
 ![alt text](markdown-show2.png)
 
-### Imges in Markdown
+### Images in Markdown
 
 First, you need to create resource for images:
 ```prisma title="schema.prisma"