Merge branch 'main' of github.com:devforth/adminforth

Author: SerVitasik

AGENTS.md

@@ -1,6 +1,23 @@
 
 # AGENTS.md
 
+## Package manager
+
+All packages and projects in this repo use `pnpm` and not `npm`. 
+Howeverer internally (e.g. in `codeInjector`) adminforth still supports both `npm` and `pnpm` style install commands, so users of framework itself can use it with either package manager. But in all dev demo/live demo, plugins, adapters, and documentation, we use `pnpm` as the standard.
+
+## Package names rules
+
+
+All adapters and plugins always have `@adminforth/` prefix in their package name, followed by short lowercase kebab-case plugin/adpater slug.
+
+Every plugin has at least one Docusaurus docs page, which should use the path `/docs/tutorial/Plugins/<plugin-slug>/`.
+
+Same for adapters, but with `/docs/tutorial/Adapters/<adapter-slug>/` path.
+
+Page names in docusarus should be human readabale. We should not use `AuditLog` but instead we should have `Audit Log` via whitespace.
+
+
 ## General engineering rules
 
 Write code as if the system contracts are already defined and trusted.

adminforth/dataConnectors/baseConnector.ts

@@ -22,6 +22,14 @@ type AdminForthFilterNormalizationResult = {
   normalizedFilters?: AdminForthFilterInput;
 };
 
+async function publishShowPageUpdate(resource: AdminForthResource, recordId: string, updates: Record<string, any>) {
+  await global.adminforth.websocket.publish(`/showPage/${resource.resourceId}/${String(recordId)}`, {
+    resourceId: resource.resourceId,
+    recordId,
+    updates,
+  });
+}
+
 
 export default class AdminForthBaseConnector implements IAdminForthDataSourceConnectorBase {
 
@@ -578,6 +586,7 @@ export default class AdminForthBaseConnector implements IAdminForthDataSourceCon
     afLogger.trace(`🪲✏️ updating record id:${recordId}, values: ${JSON.stringify(recordWithOriginalValues)}`);
 
     await this.updateRecordOriginalValues({ resource, recordId, newValues: recordWithOriginalValues });
+    await publishShowPageUpdate(resource, recordId, newValues);
 
     return { ok: true };
   }

adminforth/dataConnectors/sqlite.ts

@@ -9,6 +9,20 @@ class SQLiteConnector extends AdminForthBaseConnector implements IAdminForthData
 
   async setupClient(url: string): Promise<void> {
     this.client = betterSqlite3(url.replace('sqlite://', ''));
+    this.client.aggregate('median', {
+      start: (): number[] => [],
+      step: (acc: number[], val: any) => {
+        if (val != null) acc.push(Number(val));
+      },
+      result: (acc: number[]): number | null => {
+        if (acc.length === 0) return null;
+        const sorted = acc.slice().sort((a, b) => a - b);
+        const mid = Math.floor(sorted.length / 2);
+        return sorted.length % 2 === 0
+          ? (sorted[mid - 1] + sorted[mid]) / 2
+          : sorted[mid];
+      },
+    });
   }
   async getAllTables(): Promise<Array<string>> {
     const stmt = this.client.prepare(
@@ -358,7 +372,7 @@ class SQLiteConnector extends AdminForthBaseConnector implements IAdminForthData
             case 'avg':    selectParts.push(`AVG("${rule.field}") AS "${alias}"`); break;
             case 'min':    selectParts.push(`MIN("${rule.field}") AS "${alias}"`); break;
             case 'max':    selectParts.push(`MAX("${rule.field}") AS "${alias}"`); break;
-            case 'median': throw new Error('Aggregates.median() with GroupBy.Field is not supported in SQLite.');
+            case 'median': selectParts.push(`median("${rule.field}") AS "${alias}"`); break;
           }
         }
 

adminforth/documentation/blog/2024-10-01-ai-blog/index.md

@@ -47,7 +47,7 @@ Add modules:
 
 ```bash
 cd ai-blog
-npm i @adminforth/upload @adminforth/rich-editor @adminforth/text-complete @adminforth/chat-gpt slugify http-proxy @adminforth/image-generation-adapter-openai @adminforth/completion-adapter-open-ai-chat-gpt
+npm i @adminforth/upload @adminforth/rich-editor @adminforth/text-complete @adminforth/chat-gpt slugify http-proxy @adminforth/image-generation-adapter-openai @adminforth/completion-adapter-openai-responses
 ```
 
 
@@ -475,7 +475,7 @@ import UploadPlugin from '@adminforth/upload';
 import RichEditorPlugin from '@adminforth/rich-editor';
 import ChatGptPlugin from '@adminforth/chat-gpt';
 import slugify from 'slugify';
-import CompletionAdapterOpenAIChatGPT from "@adminforth/completion-adapter-open-ai-chat-gpt";
+import CompletionAdapterOpenAIResponses from "@adminforth/completion-adapter-openai-responses";
 import ImageGenerationAdapterOpenAI from '@adminforth/image-generation-adapter-openai';
 
 export default {
@@ -591,7 +591,7 @@ export default {
     new RichEditorPlugin({
       htmlFieldName: 'content',
       completion: {
-        adapter: new CompletionAdapterOpenAIChatGPT({
+        adapter: new CompletionAdapterOpenAIResponses({
           openAiApiKey: process.env.OPENAI_API_KEY as string,
           model: 'gpt-4o',
           expert: {

adminforth/documentation/docs/tutorial/001-gettingStarted.md

@@ -197,7 +197,7 @@ After the resource file is generated, extend it with display and validation sett
 To properly apply these changes, refer to the example below and adjust the configuration according to your settings
 
 ```ts title="./resources/apartments.ts"
-import { AdminForthDataTypes, AdminForthResourceInput } from 'adminforth';
+import { AdminForthResourceInput, AdminForthDataTypes } from 'adminforth';
 
 export default {
   dataSource: 'maindb',
@@ -206,32 +206,41 @@ export default {
   resourceId: 'apartments'
   //diff-add
   resourceId: 'aparts', // resourceId is defaulted to table name but you can redefine it like this e.g. 
+  //diff-add
   // in case of same table names from different data sources
   label: 'Apartments',   // label is defaulted to table name but you can change it
   //diff-add
   recordLabel: (r) => `🏡 ${r.title}`,
   columns: [
     {
       name: 'id',
+      //diff-add
       type: AdminForthDataTypes.STRING,
       //diff-add
       label: 'Identifier',  // if you wish you can redefine label, defaulted to uppercased name
       showIn: { // show column in filter and in show page
-      //diff-add
+        //diff-remove
+        all:true,
+        //diff-add
         list: false,
         //diff-add
         edit: false,
         //diff-add
         create: false,
       },
+      //diff-add
       primaryKey: true,
       //diff-add
       fillOnCreate: ({ initialRecord, adminUser }) => Math.random().toString(36).substring(7),  // called during creation to generate content of field, initialRecord is values user entered, adminUser object of user who creates record
     },
     {
-      name: 'title',
+      name: "title",
+      //diff-add
       required: true,
-      showIn: { all: true },  // all available options
+      showIn: {
+        all:true, // all available options
+      },
+      //diff-add
       type: AdminForthDataTypes.STRING,
       //diff-add
       maxLength: 255,  // you can set max length for string fields
@@ -240,14 +249,24 @@ export default {
     },
     {
       name: 'created_at',
+      //diff-add
       type: AdminForthDataTypes.DATETIME,
+      //diff-add
       allowMinMaxQuery: true,
-      showIn: { create: false },
+      showIn: {
+        //diff-remove
+        all:true,
+        //diff-add
+        create: false,
+      },
       //diff-add
       fillOnCreate: ({ initialRecord, adminUser }) => (new Date()).toISOString(),
     },
     {
       name: 'price',
+      showIn: {
+        all:true,
+      },
       //diff-add
       inputSuffix: 'USD', // you can add a suffix to an input field that will be displayed when creating or editing records
       //diff-add
@@ -257,16 +276,25 @@ export default {
     },
     {
       name: 'square_meter',
+      //diff-add
       label: 'Square',
+      //diff-add
       allowMinMaxQuery: true,
+      showIn: {
+        all:true,
+      },
       //diff-add
       minValue: 1,  // you can set min /max value for number columns so users will not be able to enter more/less
       //diff-add
       maxValue: 1000,
     },
     {
       name: 'number_of_rooms',
+      //diff-add
       allowMinMaxQuery: true,
+      showIn: {
+        all:true,
+      },
       //diff-add
       enum: [
         //diff-add
@@ -284,11 +312,20 @@ export default {
     },
     {
       name: 'description',
+      //diff-add
       sortable: false,
-      showIn: { list: false },
+      showIn: {
+        //diff-remove
+        all:true,
+        //diff-add
+        list: false,
+      }
     },
     {
       name: 'country',
+      showIn: {
+        all:true,
+      },
       //diff-add
       enum: [{
         //diff-add
@@ -362,18 +399,27 @@ export default {
       name: 'listed',
       //diff-add
       required: true,  // will be required on create/edit
+      showIn: {
+        all:true,
+      }
     },
     {
       name: 'realtor_id',
+      //diff-add
       foreignResource: {
+        //diff-add
         resourceId: 'adminuser',
         //diff-add
         searchableFields: ["id", "email"], // fields available for search in filter
+        //diff-add
+      },
+      showIn: {
+        all:true,
       }
     }
   ],
   options: {
-    listPageSize: 12,
+    listPageSize: 10,
     //diff-add
     allowedActions: {
       //diff-add
@@ -439,8 +485,17 @@ export const admin = new AdminForth({
     },
     {
       label: 'Users',
-      ...
-    }
+      icon: 'flowbite:user-solid',
+      resourceId: 'adminuser'
+    },
+    {
+      label: "Apartments",
+      icon: "flowbite:user-solid",
+      //diff-remove
+      resourceId: "apartments",
+      //diff-add
+      resourceId: "aparts",
+    },
   ],
   ...
 });
@@ -467,7 +522,7 @@ async function seedDatabase() {
 //diff-add
       title: `Apartment ${i}`,
 //diff-add
-      square_meter: (Math.random() * 100).toFixed(1),
+      square_meter: Number((Math.random() * 100).toFixed(1)),
 //diff-add
       price: (Math.random() * 10000).toFixed(2),
 //diff-add

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

@@ -44,7 +44,7 @@ When user opens edit page, AdminForth makes a request to the backend to get the
 
 Practically you can use `show.afterDatasourceResponse` to modify or add some data before it is displayed on the edit page. 
 
-For example [upload plugin](/docs/tutorial/Plugins/05-0-upload/) uses this hook to generate signed preview URL so user can see existing uploaded file preview  in form, and at the same time database stores only original file path which might be not accessible without presigned URL.
+For example [upload plugin](/docs/tutorial/Plugins/upload/) uses this hook to generate signed preview URL so user can see existing uploaded file preview  in form, and at the same time database stores only original file path which might be not accessible without presigned URL.
 
 ## Saving data on edit page
 

adminforth/documentation/docs/tutorial/03-Customization/10-menuConfiguration.md

@@ -277,7 +277,7 @@ auth: {
 
 ```
 
-This syntax can be use to get unique avatar for each user of hardcode avatar, but it makes more sense to use it with [upload plugin](https://adminforth.dev/docs/tutorial/Plugins/05-0-upload/#using-plugin-for-uploading-avatar)
+This syntax can be use to get unique avatar for each user of hardcode avatar, but it makes more sense to use it with [upload plugin](https://adminforth.dev/docs/tutorial/Plugins/upload/#using-plugin-for-uploading-avatar)
 
 
 ## Custom URL

adminforth/documentation/docs/tutorial/03-Customization/16-websocket.md

@@ -20,6 +20,18 @@ On server you can publish data to the topic by calling
 admin.websocket.publish('/topic-name', {some: 'data'});
 ```
 
+If you need to unsubscribe from a whole family of topics, for example when route changes can leave old dynamic subscriptions behind, you can use `unsubscribeByPrefix`:
+
+```javascript
+import websocket from '@/websocket';
+
+websocket.unsubscribeByPrefix('/topic-name/');
+```
+
+This will unsubscribe from all topics whose name starts with the prefix.
+
+It is useful for dynamic topics like `/topic-name/<resourceId>/<recordId>` where a stale subscription can update the wrong page if component unmount does not happen exactly when you expect.
+
 Let's consider a real-world example.
 
 ## Usage example

adminforth/documentation/docs/tutorial/05-Adapters/01-email-adapters.md

@@ -0,0 +1,21 @@
+# Email Adapters
+
+Used to send emails.
+
+[Email adapter base class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/EmailAdapter.ts#L17)
+
+## AWS SES Email Adapter
+
+```bash
+pnpm i @adminforth/email-adapter-aws-ses
+```
+
+Enables email delivery via [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/), suitable for high-volume, programmatic email sending.
+
+## Mailgun Email Adapter
+
+```bash
+pnpm i @adminforth/email-adapter-mailgun
+```
+
+Allows sending transactional or marketing emails using [Mailgun](https://www.mailgun.com/), a developer-friendly email service.