Merge pull request #207 from devforth/next

Next

Author: ivictbor

README.md

@@ -67,17 +67,20 @@ cd adminforth
 npm ci
 npm run build
 
-# this will install all official plugins and link adminforth package, if plugin installed it will git pull and npm ci
-npm run install-plugins
 
-# same for official adapters
-npm run install-adapters
 ```
 
 To run dev demo:
 ```sh
 cd dev-demo
 cp .env.sample .env
+
+# this will install all official plugins and link adminforth package, if plugin installed it will git pull and npm ci
+npm run install-plugins
+
+# same for official adapters
+npm run install-adapters
+
 npm ci
 npm run migrate
 npm start

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-google-oauth-adapter adminforth-github-oauth-adapter adminforth-facebook-oauth-adapter adminforth-keycloak-oauth-adapter adminforth-microsoft-oauth-adapter adminforth-image-generation-adapter-openai"
+ADAPTERS="adminforth-completion-adapter-open-ai-chat-gpt adminforth-email-adapter-aws-ses adminforth-google-oauth-adapter adminforth-github-oauth-adapter adminforth-facebook-oauth-adapter adminforth-keycloak-oauth-adapter adminforth-microsoft-oauth-adapter adminforth-image-generation-adapter-openai adminforth-storage-adapter-amazon-s3 adminforth-storage-adapter-local"
 
 # for each
 install_adapter() {

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

@@ -6,6 +6,7 @@ This plugin allows you to upload files to Amazon S3 bucket.
 
 ```
 npm i @adminforth/upload --save
+npm i @adminforth/storage-adapter-amazon-s3 --save
 ```
 
 ## S3
@@ -58,6 +59,16 @@ AWS_ACCESS_KEY_ID=your_access_key_id
 AWS_SECRET_ACCESS_KEY=your_secret_access_key
 ```
 
+8. Add credentials in your `.env.local` file:
+
+```ts title=".env.local"
+...
+//diff-add
+AWS_REGION=your_bucket_region
+//diff-add
+AWS_BUCKET_NAME=your_bucket_name
+```
+
 Now add a column for storing the path to the file in the database, add this statement to the `./schema.prisma`:
 
 ```ts title="./schema.prisma"
@@ -89,6 +100,8 @@ Add column to `aparts` resource configuration:
 //diff-add
 import UploadPlugin from '@adminforth/upload';
 //diff-add
+import AdminForthAdapterS3Storage from '@adminforth/storage-adapter-amazon-s3'
+//diff-add
 import { v4 as uuid } from 'uuid';
 
 export const admin = new AdminForth({
@@ -108,27 +121,31 @@ export const admin = new AdminForth({
   ],
   plugins: [
     ...
-//diff-add
+  //diff-add
     new UploadPlugin({
-//diff-add
+    //diff-add
+      storageAdapter: new AdminForthAdapterS3Storage({
+      //diff-add
+        bucket: process.env.AWS_BUCKET_NAME,
+      //diff-add
+        region: process.env.AWS_REGION,
+      //diff-add
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      //diff-add
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    //diff-add
+      }),
+    //diff-add
       pathColumnName: 'apartment_image',
-//diff-add
-      s3Bucket: 'my-bucket', // ❗ Your bucket name
-//diff-add
-      s3Region: 'us-east-1', // ❗ Selected region
-//diff-add
-      s3AccessKeyId: process.env.AWS_ACCESS_KEY_ID,
-//diff-add
-      s3SecretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-//diff-add
+    //diff-add
       allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm', 'webp'],
-//diff-add
+    //diff-add
       maxFileSize: 1024 * 1024 * 20, // 20 MB
-//diff-add
-      s3Path: ({originalFilename, originalExtension, contentType}) => 
-//diff-add
+    //diff-add
+      filePath: ({originalFilename, originalExtension, contentType}) => 
+    //diff-add
             `aparts/${new Date().getFullYear()}/${uuid()}-${originalFilename}.${originalExtension}`,
-//diff-add
+  //diff-add
     })
 //diff-add
   ]
@@ -153,13 +170,13 @@ which are generated by plugin:
 ![alt text](Upload.png)
 
 
-> ☝ When upload feature is used on record which already exists in database (from 'edit' page), s3path callback will
+> ☝ When upload feature is used on record which already exists in database (from 'edit' page), filePath callback will
 > receive additional parameter `record` with all values of record. Generally we don't recommend denormalizing any state
 > of record into s3 path (and instead store links to unique path on s3 in the record field, like in example above).
 > But if you are 100% sure this kind of sate will be static, you might link to it:
 >
 > ```ts
-> s3Path: ({originalExtension, record}) => `game_images/${record.static_game_code}.${originalExtension}`
+> filePath: ({originalExtension, record}) => `game_images/${record.static_game_code}.${originalExtension}`
 > ```
 >
 > ! Please note that when upload is done from create view, record will be `undefined`.
@@ -196,27 +213,29 @@ Then you can change ACL in plugin configuration:
 
 ```ts title="./index.ts"
 
-      new UploadPlugin({
-        pathColumnName: 'apartment_image',
-        s3Bucket: 'my-bucket',
-        s3Region: 'us-east-1',
-        s3AccessKeyId: process.env.AWS_ACCESS_KEY_ID,
-        s3SecretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  new UploadPlugin({
+      storageAdapter: new AdminForthAdapterS3Storage({
+        bucket: process.env.AWS_BUCKET_NAME,
+        region: process.env.AWS_REGION,
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
 //diff-add
         s3ACL: 'public-read',
-        allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm'],
-        maxFileSize: 1024 * 1024 * 20, // 5MB
-        s3Path: ({originalFilename, originalExtension, contentType}) => 
-                  `aparts/${new Date().getFullYear()}/${uuid()}-${originalFilename}.${originalExtension}`,
-      })
+      }),
+      pathColumnName: 'apartment_image',
+      allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm', 'webp'],
+      maxFileSize: 1024 * 1024 * 20, // 20 MB
+      filePath: ({originalFilename, originalExtension, contentType}) => 
+            `aparts/${new Date().getFullYear()}/${uuid()}-${originalFilename}.${originalExtension}`,
+    })
 
 ```
 
-Now every uploaded file will be public so in your custom app you can easily concatenate bucket URL with `s3Path` to get public URL:
+Now every uploaded file will be public so in your custom app you can easily concatenate bucket URL with `filePath` to get public URL:
 
 ```ts
-export async function getPublicUrl(s3Path: string): string {
-  return `https://my-bucket.s3.${region}.amazonaws.com/${s3Path}`
+export async function getPublicUrl(filePath: string): string {
+  return `https://my-bucket.s3.${region}.amazonaws.com/${filePath}`
 }
 ```
 
@@ -226,7 +245,7 @@ For preview in AdminForth plugin will still use presigned URLs, but you can chan
 
   preview: {
 //diff-add
-      previewUrl: ({s3Path}) => `https://my-bucket.s3.us-east-1.amazonaws.com/${s3Path}`, 
+      previewUrl: ({filePath}) => `https://my-bucket.s3.us-east-1.amazonaws.com/${filePath}`, 
   }
 ```
 > Make sure that you change "my-bucket" and "us-east-1" to your own settings.
@@ -240,10 +259,10 @@ If for example your domain is `my-domain.com` and you bucket has name `static.my
 
   preview: {
 //diff-remove
-      previewUrl: ({s3Path}) => `https://my-bucket.s3.us-east-1.amazonaws.com/${s3Path}`,
+      previewUrl: ({filePath}) => `https://my-bucket.s3.us-east-1.amazonaws.com/${filePath}`,
 
 //diff-add
-      previewUrl: ({s3Path}) => `https://static.my-domain.com/${s3Path}`,
+      previewUrl: ({filePath}) => `https://static.my-domain.com/${filePath}`,
   }
 ```
 
@@ -339,6 +358,59 @@ generation: {
 }
 ```
 
+`attachFiles` function can return an array of URLs to images which will be used as input for image generation. 
+URLs can be absolute HTTP URLs (should be public in this case) or data-URLs (`data:image/png;base64,<base64 content of image>`).
+
+For example you can use `getKeyAsDataURL` function from any storage adapter to get image as data-URL:
+
+```ts title="./apartments.ts"
+
+import { StorageAdapter } from 'adminforth'
+
+let sourceAdapter: StorageAdapter = null;
+
+columns: [
+  ...
+  {
+    name: 'source_image',
+  },
+  {
+    name: 'destination_image',
+  }
+],
+plugins: [ 
+  ...
+  new UploadPlugin({
+    pathColumnName: 'apartment_source',
+    storageAdapter: (sourcesAdapter = new AdminForthStorageAdapterLocalFilesystem({
+      fileSystemFolder: "./db/uploads",
+      mode: "public",
+      signingSecret: process.env.ADMINFORTH_SECRET, // secret used to generate presigned URLs
+    }), sourcesAdapter),
+  }),
+  new UploadPlugin({
+    pathColumnName: 'apartment_image',
+    storageAdapter: new AdminForthAdapterLocalFilesystem({
+      fileSystemFolder: "./db/uploads",
+      mode: "public",
+      signingSecret: process.env.ADMINFORTH_SECRET, // secret used to generate presigned URLs
+    }),
+    generation: {
+      attachFiles: ({ record }) => {
+        // get picture stored in apartment_source column as data-URL
+        return [sourceAdapter.getKeyAsDataURL(record.apartment_source)];
+      },
+      generationPrompt: "Remove text from the image",
+      countToGenerate: 3,
+      outputSize: '1024x1024',
+    }
+  })
+]
+```
+
+With thus setup you can upload image to `apartment_source` column, save entity and then generate new image by clicking on `Generate` button in the `apartment_image` to remove any text from the image.
+
+
 ### Rate limits
 
 You can set rate limits for image generation per IP address:
@@ -364,14 +436,17 @@ You can set the maximum width for the preview image in the `./resources/apartmen
 ```ts title="./resources/apartments.ts"
   ...
   new UploadPlugin({
+    storageAdapter: new AdminForthAdapterS3Storage({
+        bucket: process.env.AWS_BUCKET_NAME,
+        region: process.env.AWS_REGION,
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        s3ACL: "public-read",
+    }),
     pathColumnName: 'apartment_image',
-    s3Bucket: 'my-bucket', // ❗ Your bucket name
-    s3Region: 'us-east-1', // ❗ Selected region
-    s3AccessKeyId: process.env.AWS_ACCESS_KEY_ID,
-    s3SecretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
     allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm', 'webp'],
-    maxFileSize: 1024 * 1024 * 20, // 20 MB
-    s3Path: ({originalFilename, originalExtension, contentType}) => 
+    maxFileSize: 5 * 1024 * 1024, // 5MB
+    filePath: ({originalFilename, originalExtension, contentType}) => 
       `aparts/${new Date().getFullYear()}/${uuid()}-${originalFilename}.${originalExtension}`,
     preview: {
       // Global width settings (applies to all views if specific view settings not provided)

adminforth/index.ts

@@ -125,6 +125,10 @@ class AdminForth implements IAdminForth {
   }
 
   constructor(config: AdminForthInputConfig) {
+    if (global.adminforth) {
+      throw new Error('AdminForth instance already created in this process. '+
+        'If you want to use multiple instances, consider using different process for each instance');
+    }
     this.codeInjector = new CodeInjector(this);
     this.configValidator = new ConfigValidator(this, config);
     this.restApi = new AdminForthRestAPI(this);
@@ -145,6 +149,7 @@ class AdminForth implements IAdminForth {
 
 
     console.log(`${this.formatAdminForth()} v${ADMINFORTH_VERSION} initializing...`);
+    global.adminforth = this;
   }
 
   formatAdminForth() {

adminforth/modules/codeInjector.ts

@@ -129,7 +129,7 @@ class CodeInjector implements ICodeInjector {
     });
     process.env.HEAVY_DEBUG && console.timeEnd(`npm ${command} done in`);
 
-    process.env.HEAVY_DEBUG && console.log(`🪲 npm ${command} output:`, out);
+    // process.env.HEAVY_DEBUG && console.log(`🪲 npm ${command} output:`, out);
     if (err) {
       process.env.HEAVY_DEBUG && console.error(`🪲npm ${command} errors/warnings:`, err);
     }

adminforth/package-lock.json

@@ -20,9 +20,7 @@
     "rollout-doc": "cd documentation && npm run build && npm run deploy",
     "docs": "typedoc",
     "--comment_postinstall": "postinstall executed after package installed in other project package and when we do npm ci in the package",
-    "postinstall": "if test -d ./dist/spa/; then cd ./dist/spa/ && npm ci && echo 'installed spa dependencies'; fi",
-    "install-plugins": "cd ../plugins && bash install-plugins.sh",
-    "install-adapters": "cd ../adapters && bash install-adapters.sh"
+    "postinstall": "if test -d ./dist/spa/; then cd ./dist/spa/ && npm ci && echo 'installed spa dependencies'; fi"
   },
   "release": {
     "plugins": [
@@ -62,7 +60,7 @@
     "@clickhouse/client": "^1.4.0",
     "@faker-js/faker": "^9.0.3",
     "@inquirer/prompts": "^7.4.1",
-    "@types/express": "^5.0.0",
+    "@types/express": "^4.17.21",
     "arg": "^5.0.2",
     "better-sqlite3": "^11.5.0",
     "chalk": "^5.4.1",

adminforth/package.json

@@ -118,6 +118,7 @@ class ExpressServer implements IExpressHttpServer {
         }
       }
       this.expressApp.get(`${slashedPrefix}assets/*`, handler);
+      process.env.HEAVY_DEBUG && console.log('®️ Registering SPA serve handler', `${slashedPrefix}assets/*`);
       this.expressApp.get(`${prefix}*`, handler);