Merge branch 'AdminForth/765' of https://github.com/devforth/adminforth into AdminForth/765

Author: yaroslav8765

adapters/install-adapters.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-ADAPTERS="adminforth-completion-adapter-open-ai-chat-gpt adminforth-email-adapter-aws-ses adminforth-email-adapter-mailgun adminforth-google-oauth-adapter adminforth-github-oauth-adapter 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"
+ADAPTERS="adminforth-completion-adapter-open-ai-chat-gpt adminforth-email-adapter-aws-ses adminforth-email-adapter-mailgun adminforth-google-oauth-adapter adminforth-github-oauth-adapter 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"
 
 # for each
 install_adapter() {

adminforth/dataConnectors/clickhouse.ts

@@ -231,6 +231,12 @@ class ClickhouseConnector extends AdminForthBaseConnector implements IAdminForth
         const column = resource.dataSourceColumns.find((col) => col.name == field);
         let placeholder = `{f$?:${column._underlineType}}`;
         let operator = this.OperatorsMap[filter.operator];
+
+        if (column._underlineType.startsWith('Decimal')) {
+          field = `toDecimal64(${field}, 8)`;
+          placeholder = `toDecimal64({f$?:String}, 8)`;
+        }
+
         if ((filter.operator == AdminForthFilterOperators.LIKE || filter.operator == AdminForthFilterOperators.ILIKE) && column._underlineType == 'UUID') {
           placeholder = '{f$?:String}';
           field = `toString(${field})`;

adminforth/documentation/docs/tutorial/03-Customization/06-customPages.md

@@ -468,9 +468,13 @@ import { Link } from '@/afcl';
 
 If you set `customLayout: true` in the `meta` object, it will not include default layout like sidebar and header, so you can create your own layout for this page. 
 
-> **Redirects to login page**: Any route which has sidebar and header (e.g. default CRUD pages or menu item with `component`) uses internal AdminForth REST API to fetch menu items and user information, so it passes authentication check and if authentication cookie is not provided or has expired JWT user gets redirected to the login page.
-> In case if you set `customLayout: true`, it will not call these APIs so user will not be automatically redirected to the login page in case of expired or not-provided authentication cookie. That feature allows you to implement public pages without authentication, e.g. Terms of Service, Privacy Policy and many others. In case if you need to check if user is logged in just call any custom API which has `admin.express.authorize` middleware. Obviously for public pages you should create API endpoint WITHOUT `admin.express.authorize` middleware.
+### Disable redirects to login page (Public pages)
 
+Any route which has sidebar and header (e.g. default CRUD pages or menu item with `component`) uses internal AdminForth REST API to fetch menu items and user information, so it passes authentication check and if authentication cookie is not provided or has expired JWT user gets redirected to the login page.
+
+In case if you set `customLayout: true`, it will not call these APIs so user will not be automatically redirected to the login page in case of expired or not-provided authentication cookie. That feature allows you to implement public pages without authentication, e.g. Terms of Service, Privacy Policy and many others. In case if you need to check if user is logged in just call any custom API which has `admin.express.authorize` middleware. Obviously for public pages if they use any APIs you should create API endpoint WITHOUT `admin.express.authorize` middleware.
+
+> Please note that AdminForth uses classic SPA Vue app, so even public pages will be rendered by JavaScript in the browser and not on the server side. If your public page should be indexed by search engines, you should use some SSR framework like Nuxt.js to create such pages. At the same time public pages can still be usefull if you don't focus on old-fashioned search engines (modern search engines can index SPA pages as well) or if indexing is not important for such pages at all (e.g. Terms of Service, Privacy Policy, Contact Us and many others).
 
 ### Passing meta attributes to the page
 

adminforth/documentation/docs/tutorial/03-Customization/15-afcl.md

@@ -595,6 +595,41 @@ const closeDialog = () => {
 }
 ```
 
+### Before open/close dialog handlers
+If you want to run custom logic before the dialog opens or closes by passing callback props:
+
+```ts
+<Dialog 
+  class="w-96" 
+  :beforeCloseFunction="onBeforeOpen" 
+  :beforeOpenFunction="onBeforeClose"
+>
+  <template #trigger>
+    <Button>Dialog Toggle</Button>
+  </template>
+
+  <div class="space-y-4">
+    <p>This is the first paragraph of dialog content.</p>
+    <p>And this is the second paragraph.</p>
+  </div>
+</Dialog>
+```
+Now you can pass before open/close functions:
+```ts
+const counter = ref(0);
+
+function onBeforeOpen() {
+  counter.value++;
+  console.log(`custom open function called ${counter.value}`);
+}
+
+function onBeforeClose() {
+  counter.value++;
+  console.log(`custom close function called ${counter.value}`);
+}
+```
+
+
 ## Dropzone
 
 ```ts

adminforth/documentation/docs/tutorial/07-Plugins/16-email-invite.md

@@ -93,14 +93,25 @@ export default {
     },
   },
   plugins: [
+    //diff-add
     new EmailInvitePlugin({
+     //diff-add
       emailField: 'email',
+     //diff-add
+      passwordField: 'password_hash',
+     //diff-add
       sendFrom: 'noreply@yourapp.com',
+     //diff-add
       adapter: new EmailAdapterAwsSes({
+     //diff-add
         region: 'us-east-1',
+     //diff-add
         accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+     //diff-add
         secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+     //diff-add
       }),
+     //diff-add
     }),
   ],
 };
@@ -153,6 +164,7 @@ export default {
     new EmailInvitePlugin({
       emailField: 'email',
       sendFrom: 'noreply@yourapp.com',
+      passwordField: 'password_hash',
       adapter: new EmailAdapterAwsSes(/* ... */),
       //diff-add
       emailConfirmedField: 'email_confirmed', // Enable email confirmation
@@ -161,3 +173,37 @@ export default {
 };
 ```
 
+## Mailgun usage example
+If you want to use this plugin with Mailgun, first install it:
+
+```bash
+npm install @adminforth/email-adapter-mailgun
+```
+
+Then, in the adapter options, add:
+
+``` ts
+//diff-add
+import EmailAdapterMailgun from "@adminforth/email-adapter-mailgun";
+ 
+...
+
+  plugins: [
+    new EmailInvitePlugin({
+      emailField: 'email',
+      passwordField: 'password_hash',
+      sendFrom: 'noreply@yourapp.com',
+      //diff-add
+      adapter: new EmailAdapterMailgun({
+      //diff-add
+        apiKey: process.env.MAILGUN_API_KEY as string,
+      //diff-add
+        domain: process.env.MAILGUN_DOMAIN as string,
+      //diff-add
+        baseUrl: process.env.MAILGUN_REGION_URL as string,
+      //diff-add
+      }),
+    }),
+  ],
+
+```

adminforth/documentation/docs/tutorial/07-Plugins/17-bulk-ai-flow.md

@@ -42,7 +42,7 @@ model apartments {
   listed            Boolean
   realtor_id        String?
 //diff-add
-  apartment_image         String?
+  apartment_image   String?
 }
 ```
 
@@ -73,6 +73,12 @@ Add column to `aparts` resource configuration:
 import BulkAiFlowPlugin  from '@adminforth/bulk-ai-flow';
 //diff-add
 import AdminForthImageVisionAdapterOpenAi from '@adminforth/image-vision-adapter-openai';
+//diff-add
+import UploadPlugin from '@adminforth/upload';
+//diff-add
+import { randomUUID } from 'crypto';
+//diff-add
+import AdminForthAdapterS3Storage from '@adminforth/storage-adapter-amazon-s3'
 
 export const admin = new AdminForth({
   ...
@@ -126,6 +132,12 @@ export const admin = new AdminForth({
         actionName: 'Analyze',
       //diff-add
         attachFiles: async ({ record }: { record: any }) => {
+      //diff-add
+        if (!record.apartment_image) {
+      //diff-add
+          return [];
+      //diff-add
+        }
       //diff-add
           return [`https://tmpbucket-adminforth.s3.eu-central-1.amazonaws.com/${record.apartment_image}`];
       //diff-add
@@ -166,6 +178,7 @@ export const admin = new AdminForth({
 
 });
 ```
+> ⚠️ Make sure your attachFiles function returns a valid array of image URLs or an empty array. Returning anything else may cause an error.
 
 ## Usage
 1. Select fields you want to fill
@@ -177,3 +190,125 @@ export const admin = new AdminForth({
 ![alt text](Bulk-vision-2.png)
 6. Save changhes
 ![alt text](Bulk-vision-3.png)
+
+
+## Text-to-Text Processing
+This is the most basic plugin usage. You can connect any text completion adapter to fill one or several string/number/boolean fields from other fields.
+
+### Example: Translate Names to English
+Normalize user names by translating them from any language to English for internal processing.
+
+```ts
+import CompletionAdapterOpenAIChatGPT from '@adminforth/completion-adapter-open-ai-chat-gpt/index.js';
+
+// Add to your resource plugins array
+new BulkAiFlowPlugin({
+  actionName: 'Translate surnames',
+  textCompleteAdapter: new CompletionAdapterOpenAIChatGPT({
+    openAiApiKey: process.env.OPENAI_API_KEY as string,
+    model: 'gpt-4o',
+    expert: {
+      temperature: 0.7
+    }
+  }),
+  fillPlainFields: {
+    'full_name_en': 'Translate this name to English: {{users_full_name}}',
+  },
+}),
+```
+
+## Image-to-Text Analysis (Vision)
+Analyze images and extract information to fill text, number, enum, or boolean fields.
+
+### Example: Age Detection from Photos
+
+```ts
+import AdminForthImageVisionAdapterOpenAi from '@adminforth/image-vision-adapter-openai/index.js';
+
+// Add to your resource plugins array
+new BulkAiFlowPlugin({
+  actionName: 'Guess age',
+  visionAdapter: new AdminForthImageVisionAdapterOpenAi({
+    openAiApiKey: process.env.OPENAI_API_KEY as string,
+    model: 'gpt-4.1-mini',
+  }),
+  fillFieldsFromImages: { 
+    'age': 'Analyze the image and estimate the age of the person. Return only a number.',
+  },
+  attachFiles: async ({ record }) => {
+    if (!record.image_url) {
+      return [];
+    }
+    return [`https://users-images.s3.eu-north-1.amazonaws.com/${record.image_url}`];
+  },
+}),
+```
+
+## Text-to-Image generation or image editing
+Generate new images based on existing data and/or images using AI image generation adapters.
+
+### Example: Creating Cartoon Avatars
+
+```ts
+import ImageGenerationAdapterOpenAI from '@adminforth/image-generation-adapter-openai/index.js';
+
+// Add to your resource plugins array
+new BulkAiFlowPlugin({
+  actionName: 'Generate cartoon avatars',
+  imageGenerationAdapter: new ImageGenerationAdapterOpenAI({
+    openAiApiKey: process.env.OPENAI_API_KEY as string,
+    model: 'gpt-image-1',
+  }),
+  attachFiles: async ({ record }) => {
+    if (!record.user_photo) {
+      return [];
+    }
+    return [`https://bulk-ai-flow-playground.s3.eu-north-1.amazonaws.com/${record.users_photo}`];
+  },
+  generateImages: {
+    users_avatar: {
+      prompt: 'Transform this photo into a cartoon-style avatar. Maintain the person\'s features but apply cartoon styling. Do not add text or logos.',
+      outputSize: '1024x1024',
+      countToGenerate: 2,
+      rateLimit: '3/1h'
+    },
+  },
+  bulkGenerationRateLimit: "1/1h"
+}),
+```
+
+## Rate Limiting and Best Practices
+
+- Use `rateLimit` for individual image generation operations and for the bulk image generation
+```ts
+  new BulkAiFlowPlugin({
+  ...
+
+  generateImages: {
+    users_avatar: {
+      ... //image re-generation limits
+      //diff-add
+      rateLimit: '1/5m' // one request per 5 minutes
+    }
+  },
+
+  ...
+
+  //diff-add
+  rateLimits: { // bulk generation limits
+  //diff-add
+    fillFieldsFromImages: "5/1d", // 5 requests per day
+  //diff-add
+    fillPlainFields: "3/1h",      // 3 requests per one hour
+  //diff-add
+    generateImages: "1/2m",       // 2 request per one minute
+  //diff-add
+  }
+
+  ...
+
+  })
+```
+
+- Consider using lower resolution (`512x512`) for faster generation and lower costs
+- Test prompts thoroughly before applying to large datasets

adminforth/spa/src/App.vue

@@ -195,7 +195,7 @@
       </div>
     </div>
     <AcceptModal />
-    <div v-if="toastStore.toasts.length>0" class="fixed bottom-5 right-5 flex gap-1 flex-col-reverse z-50">
+    <div v-if="toastStore.toasts.length>0" class="fixed bottom-5 right-5 flex gap-1 flex-col-reverse z-[100]">
       <transition-group
         name="fade"
         tag="div"

adminforth/spa/src/adminforth.ts

@@ -35,6 +35,10 @@ class FrontendAPI implements FrontendAPIInterface {
     refreshMenuBadges: () => void;
   }
 
+  public show: {
+    refresh(): void;
+  }
+
   closeUserMenuDropdown(): void {
     console.log('closeUserMenuDropdown')
   }
@@ -72,6 +76,12 @@ class FrontendAPI implements FrontendAPIInterface {
       updateFilter: this.updateListFilter.bind(this),
       clearFilters: this.clearListFilters.bind(this),
     }
+
+    this.show = {
+      refresh: () => {
+        console.log('show.refresh')
+      }
+    }
   }
 
   confirm(params: ConfirmParams): Promise<boolean> {