@adminforth/upload 2.15.12 → 2.15.14

package/build.log

@@ -12,5 +12,5 @@ custom/preview.vue
 custom/tsconfig.json
 custom/uploader.vue
 
-sent 68,643 bytes  received 153 bytes  137,592.00 bytes/sec
-total size is 68,081  speedup is 0.99
+sent 68,663 bytes  received 153 bytes  137,632.00 bytes/sec
+total size is 68,101  speedup is 0.99

package/custom/imageGenerator.vue

@@ -210,7 +210,6 @@ import { callAdminForthApi } from '@/utils';
 import { useI18n } from 'vue-i18n';
 import adminforth from '@/adminforth';
 import { ProgressBar } from '@/afcl';
-import * as Handlebars from 'handlebars';
 import { IconCloseOutline } from '@iconify-prerendered/vue-flowbite';
 import { Tooltip, Skeleton } from '@/afcl'
 import { useRoute } from 'vue-router';
@@ -245,6 +244,7 @@ onMounted(async () => {
   }
   // iterate over all variables in template and replace them with their values from props.record[field]. 
   // if field is not present in props.record[field] then replace it with empty string and drop warning
+  const { default: Handlebars } = await import('handlebars');
   const tpl = Handlebars.compile(template);
   const compiledTemplate = tpl(props.record);
   prompt.value = compiledTemplate;

package/dist/custom/imageGenerator.vue

@@ -210,7 +210,6 @@ import { callAdminForthApi } from '@/utils';
 import { useI18n } from 'vue-i18n';
 import adminforth from '@/adminforth';
 import { ProgressBar } from '@/afcl';
-import * as Handlebars from 'handlebars';
 import { IconCloseOutline } from '@iconify-prerendered/vue-flowbite';
 import { Tooltip, Skeleton } from '@/afcl'
 import { useRoute } from 'vue-router';
@@ -245,6 +244,7 @@ onMounted(async () => {
   }
   // iterate over all variables in template and replace them with their values from props.record[field]. 
   // if field is not present in props.record[field] then replace it with empty string and drop warning
+  const { default: Handlebars } = await import('handlebars');
   const tpl = Handlebars.compile(template);
   const compiledTemplate = tpl(props.record);
   prompt.value = compiledTemplate;

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { PluginOptions, UploadFromBufferParams, UploadFromBufferToExistingRecordParams, CommitUrlToUpdateExistingRecordParams, CommitUrlToNewRecordParams, GetUploadUrlParams } from './types.js';
+import { AdminForthPlugin, AdminForthResource, IAdminForth, IHttpServer, RateLimiter } from "adminforth";
+export default class UploadPlugin extends AdminForthPlugin {
+    options: PluginOptions;
+    adminforth: IAdminForth;
+    totalCalls: number;
+    totalDuration: number;
+    resourceConfig: AdminForthResource;
+    rateLimiter: RateLimiter;
+    getFileDownloadUrl: ((path: string) => Promise<string>);
+    getFileUploadUrl: (originalFilename: any, contentType: any, size: any, originalExtension: any, recordPk: any) => Promise<{
+        uploadUrl: string;
+        tagline?: string;
+        filePath?: string;
+        uploadExtraParams?: Record<string, string>;
+        previewUrl?: string;
+        error?: string;
+    } | {
+        error: string;
+    }>;
+    constructor(options: PluginOptions);
+    private normalizePaths;
+    private callStorageAdapter;
+    markKeyForNotDeletion(filePath: string): Promise<void>;
+    markKeyForDeletion(filePath: string): Promise<void>;
+    private generateImages;
+    isInternalUrl(url: string): Promise<boolean>;
+    instanceUniqueRepresentation(pluginOptions: any): string;
+    setupLifecycleRule(): Promise<void>;
+    genPreviewUrl(record: any): Promise<void>;
+    modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource): Promise<void>;
+    validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: any): void;
+    setupEndpoints(server: IHttpServer): void;
+    uploadFromBufferToNewRecord({ filename, contentType, buffer, adminUser, extra, recordAttributes, }: UploadFromBufferParams): Promise<{
+        path: string;
+        previewUrl: string;
+        newRecordPk: any;
+    }>;
+    uploadFromBufferToExistingRecord({ recordId, filename, contentType, buffer, adminUser, extra, }: UploadFromBufferToExistingRecordParams): Promise<{
+        path: string;
+        previewUrl: string;
+    }>;
+    /**
+     * Generates a new signed upload URL for future uploading from the frontend via a direct upload (e.g. using fetch + FormData).
+     *
+     * After the upload, file still will be marked for auto-deletion after short time, so to keep it permanently,
+     * you need to either:
+     *  * Use commitUrlToExistingRecord to commit the URL to an existing record. This will replace the path in the existing record and will do a cleanup of the old
+     *    file pointed in this path column.
+     *  * If you want to create a new record with this URL, you can call commitUrlToNewRecord, which will create a new record and set the path column to the uploaded file path.
+     *  * Write URL to special field called pathColumnName so afterSave hook installed by the plugin will automatically mark as not candidate for auto-deletion
+     *
+     * ```ts
+     * const file = input.files[0];
+     *
+     * // 1) Ask your backend to call getUploadUrlForExistingRecord
+     * const { uploadUrl, filePath, uploadExtraParams } = await fetch('/api/uploads/get-url-existing', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({
+     *     recordId,
+     *     filename: file.name,
+     *     contentType: file.type,
+     *     size: file.size,
+     *   }),
+     * }).then(r => r.json());
+     *
+     * const formData = new FormData();
+     * if (uploadExtraParams) {
+     *   Object.entries(uploadExtraParams).forEach(([key, value]) => {
+     *     formData.append(key, value as string);
+     *   });
+     * }
+     * formData.append('file', file);
+     *
+     * // 2) Direct upload from the browser to storage (multipart/form-data)
+     * const uploadResp = await fetch(uploadUrl, {
+     *   method: 'POST',
+     *   body: formData,
+     * });
+     * if (!uploadResp.ok) {
+     *   throw new Error('Upload failed');
+     * }
+     *
+     * // 3) Tell your backend to commit the URL to the record e.g. from rest API call
+     * await fetch('/api/uploads/commit-existing', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({ recordId, filePath }),
+     * });
+     * ```
+     */
+    getUploadUrl({ recordId, filename, contentType, size, }: GetUploadUrlParams): Promise<{
+        uploadUrl: string;
+        filePath: string;
+        uploadExtraParams?: Record<string, string>;
+        pathColumnName: string;
+    }>;
+    /**
+     * Commits a previously generated upload URL to an existing record.
+     *
+     * Never call this method from edit afterSave and beforeSave hooks of the same resource,
+     * as it would create infinite loop of record updates.
+     * You should call this method from your own custom API endpoint after the upload is done.
+     */
+    commitUrlToUpdateExistingRecord({ recordId, filePath, adminUser, extra, }: CommitUrlToUpdateExistingRecordParams): Promise<{
+        path: string;
+        previewUrl: string;
+    }>;
+    /**
+     * Commits a previously generated upload URL to a new record.
+     *
+     * Never call this method from create afterSave and beforeSave hooks of the same resource,
+     * as it would create infinite loop of record creations.
+     *
+     * You should call this method from your own custom API endpoint after the upload is done.
+     */
+    commitUrlToNewRecord({ filePath, adminUser, extra, recordAttributes, }: CommitUrlToNewRecordParams): Promise<{
+        path: string;
+        previewUrl: string;
+        newRecordPk: any;
+    }>;
+}

package/dist/types.d.ts

@@ -0,0 +1,270 @@
+import { AdminUser, ImageGenerationAdapter, StorageAdapter, HttpExtra } from "adminforth";
+import { type PluginsCommonOptions } from "adminforth";
+export interface PluginOptions extends PluginsCommonOptions {
+    /**
+     * The name of the column where the path to the uploaded file is stored.
+     * On place of this column, a file upload field will be shown.
+     */
+    pathColumnName: string;
+    /**
+     * the list of allowed file extensions
+     */
+    allowedFileExtensions?: string[];
+    /**
+     * the maximum file size in bytes
+     */
+    maxFileSize?: number;
+    /**
+     * The path where the file will be uploaded to the S3 bucket, same path will be stored in the database
+     * in the column specified in {@link pathColumnName}
+     *
+     * example:
+     *
+     * ```typescript
+     * s3Path: ({originalFilename}) => `/aparts/${originalFilename}`
+     * ```
+     *
+     */
+    filePath: ({ originalFilename, originalExtension, contentType, record }: {
+        originalFilename: string;
+        originalExtension: string;
+        contentType: string;
+        record?: any;
+    }) => string;
+    preview?: {
+        /**
+         * Whether to use preview components provided by the plugin. BY default true
+         */
+        usePreviewComponents?: boolean;
+        /**
+         * Maximum width of the preview image
+         */
+        maxWidth?: string;
+        /**
+         * Maximum width of the preview image in list view
+         */
+        maxListWidth?: string;
+        /**
+         * Maximum width of the preview image in show view
+         */
+        maxShowWidth?: string;
+        /**
+         * Minimum width of the preview image
+         */
+        minWidth?: string;
+        /**
+         * Minimum width of the preview image in list view
+         */
+        minListWidth?: string;
+        /**
+         * Minimum width of the preview image in show view
+         */
+        minShowWidth?: string;
+        /**
+         * Used to display preview (if it is image) in list and show views.
+         * Defaulted to the AWS S3 presigned URL if resource is private or public URL if resource is public.
+         * Can be used to generate custom e.g. CDN(e.g. Cloudflare) URL to worm up cache and deliver preview faster.
+         *
+         * Example:
+         *
+         * ```typescript
+         * previewUrl: ({record, path}) => `https://my-bucket.s3.amazonaws.com/${path}`,
+         * ```
+         *
+         */
+        previewUrl?: ({ filePath }: {
+            filePath: any;
+        }) => string;
+    };
+    /**
+     * AI image generation options
+     */
+    generation?: {
+        adapter: ImageGenerationAdapter;
+        /**
+         * The size of the generated image.
+         */
+        outputSize?: string;
+        /**
+         * The number of images to generate
+         * in one request
+         */
+        countToGenerate: number;
+        /**
+         * Prompt which will be suggested to user during image generation. You can use record fields with mustache brackets:
+         * E.g. 'Generate a photo of car {{ model }} from {{ brand }} in {{ color }} color of {{ year }} year'. For now plugin get's these fields from open create/edit form
+         * so they should be present in the form.
+         *
+         * Reserved variables:
+         * - {{field}} - label of resource
+         * - {{resource}} - label of resource
+         */
+        generationPrompt?: string;
+        /**
+         * If you want to use some image as reference for generation, you can use this function to get the path to the image.
+         */
+        attachFiles?: ({ record, adminUser }: {
+            record: any;
+            adminUser: AdminUser;
+        }) => string[] | Promise<string[]>;
+        /**
+         * Since AI generation can be expensive, we can limit the number of requests per IP.
+         */
+        rateLimit?: {
+            /**
+             * E.g. 5/1d - 5 requests per day
+             * 3/1h - 3 requests per hour
+             */
+            limit: string;
+            /**
+             * !Not used now
+             * Message shown to user when rate limit is reached
+             */
+            errorMessage: string;
+        };
+    };
+    /**
+     * The adapter used to store the files.
+     * For now only S3 adapter is supported.
+     */
+    storageAdapter: StorageAdapter;
+}
+/**
+ * Parameters for the UploadPlugin.uploadFromBuffer API.
+ * Used to upload a binary file buffer, create a record in the resource,
+ * and return the stored path and preview URL.
+ */
+export type UploadFromBufferParams = {
+    /**
+     * Original file name including extension, used to derive storage path
+     * and validate the file extension. Example: "photo.png".
+     */
+    filename: string;
+    /**
+     * MIME type of the uploaded file. Will be used as Content-Type
+     * when uploading to the storage adapter. Example: "image/png".
+     */
+    contentType: string;
+    /**
+     * Binary contents of the file. Can be a Node.js Buffer, Uint8Array,
+     * or ArrayBuffer. The plugin uploads this directly without converting
+     * to base64.
+     */
+    buffer: Buffer | Uint8Array | ArrayBuffer;
+    /**
+     * Authenticated admin user on whose behalf the record is created.
+     * Passed through to AdminForth createResourceRecord hooks.
+     */
+    adminUser: AdminUser;
+    /**
+     * Optional HTTP context (headers, IP, etc.) forwarded to AdminForth
+     * createResourceRecord hooks. Needed to execute hooks on creation resource record for the upload.
+     */
+    extra?: HttpExtra;
+    /**
+     * Optional additional attributes to set on the created record
+     * together with the path column managed by the plugin.
+     * Values here do NOT affect the generated storage path.
+     */
+    recordAttributes?: Record<string, any>;
+};
+/**
+ * Parameters for the UploadPlugin.uploadFromBufferToExistingRecord API.
+ * Used to upload a binary file buffer and update the path column
+ * of an already existing record identified by its primary key.
+ */
+export type UploadFromBufferToExistingRecordParams = UploadFromBufferParams & {
+    /**
+     * Primary key value of the existing record whose file path
+     * should be replaced.
+     */
+    recordId: any;
+};
+/**
+ * Parameters for generating an upload URL for an existing record
+ * that will be uploaded directly from the browser.
+ */
+export type GetUploadUrlParams = {
+    /**
+     * Primary key of the record whose file is being replaced.
+     */
+    recordId?: any;
+    /**
+     * Full file name including extension, as provided by the browser.
+     */
+    filename: string;
+    /**
+     * MIME type reported by the browser, used as Content-Type for storage.
+     */
+    contentType: string;
+    /**
+     * Optional file size in bytes. If provided, it will be validated
+     * against {@link PluginOptions.maxFileSize}.
+     */
+    size?: number;
+};
+/**
+ * Parameters for generating an upload URL for a new record
+ * that will be uploaded directly from the browser.
+ */
+export type GetUploadUrlForNewRecordParams = {
+    /**
+     * Full file name including extension, as provided by the browser.
+     */
+    filename: string;
+    /**
+     * MIME type reported by the browser, used as Content-Type for storage.
+     */
+    contentType: string;
+    /**
+     * Optional file size in bytes. If provided, it will be validated
+     * against {@link PluginOptions.maxFileSize}.
+     */
+    size?: number;
+};
+/**
+ * Parameters for committing a previously generated upload URL
+ * to an existing record. This is used after the browser finished
+ * uploading directly to the storage provider.
+ */
+export type CommitUrlToUpdateExistingRecordParams = {
+    /**
+     * Primary key of the record whose file is being replaced.
+     */
+    recordId: any;
+    /**
+     * Storage path (key) that was returned by getUploadUrlForExistingRecord.
+     */
+    filePath: string;
+    /**
+     * Authenticated admin user on whose behalf the record is updated.
+     */
+    adminUser: AdminUser;
+    /**
+     * Optional HTTP context (headers, IP, etc.).
+     */
+    extra?: HttpExtra;
+};
+/**
+ * Parameters for committing a previously generated upload URL
+ * to a new record. This is used after the browser finished
+ * uploading directly to the storage provider.
+ */
+export type CommitUrlToNewRecordParams = {
+    /**
+     * Storage path (key) that was returned by getUploadUrlForNewRecord.
+     */
+    filePath: string;
+    /**
+     * Authenticated admin user on whose behalf the record is created.
+     */
+    adminUser: AdminUser;
+    /**
+     * Optional HTTP context (headers, IP, etc.).
+     */
+    extra?: HttpExtra;
+    /**
+     * Optional additional attributes for the new record.
+     */
+    recordAttributes?: Record<string, any>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/upload",
-  "version": "2.15.12",
+  "version": "2.15.14",
   "description": "Plugin for uploading files for adminforth",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/tsconfig.json

@@ -51,7 +51,7 @@
     // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
 
     /* Emit */
-    // "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
     // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
     // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
     // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */