@adminforth/upload 2.13.0 → 2.14.0

package/build.log

@@ -11,5 +11,5 @@ custom/preview.vue
 custom/tsconfig.json
 custom/uploader.vue
 
-sent 59,817 bytes  received 134 bytes  119,902.00 bytes/sec
+sent 59,824 bytes  received 134 bytes  119,916.00 bytes/sec
 total size is 59,335  speedup is 0.99

package/dist/index.js

@@ -10,8 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { AdminForthPlugin, Filters, suggestIfTypo, RateLimiter } from "adminforth";
 import { Readable } from "stream";
 import { randomUUID } from "crypto";
-import { interpretResource } from 'adminforth';
-import { ActionCheckSource } from 'adminforth';
+import { interpretResource, ActionCheckSource } from 'adminforth';
 const ADMINFORTH_NOT_YET_USED_TAG = 'adminforth-candidate-for-cleanup';
 const jobs = new Map();
 export default class UploadPlugin extends AdminForthPlugin {
@@ -691,4 +690,230 @@ export default class UploadPlugin extends AdminForthPlugin {
             };
         });
     }
+    /**
+     * 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(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ recordId, filename, contentType, size, }) {
+            if (!filename || !contentType) {
+                throw new Error('filename and contentType are required');
+            }
+            if (!this.resourceConfig) {
+                throw new Error('resourceConfig is not initialized yet');
+            }
+            const pkColumn = this.resourceConfig.columns.find((column) => column.primaryKey);
+            const pkName = pkColumn === null || pkColumn === void 0 ? void 0 : pkColumn.name;
+            if (!pkName) {
+                throw new Error('Primary key column not found in resource configuration');
+            }
+            let existingRecord = undefined;
+            if (recordId !== undefined && recordId !== null) {
+                existingRecord = yield this.adminforth
+                    .resource(this.resourceConfig.resourceId)
+                    .get([Filters.EQ(pkName, recordId)]);
+                if (!existingRecord) {
+                    throw new Error(`Record with id ${recordId} not found`);
+                }
+            }
+            const lastDotIndex = filename.lastIndexOf('.');
+            if (lastDotIndex === -1) {
+                throw new Error('filename must contain an extension');
+            }
+            const originalExtension = filename.substring(lastDotIndex + 1).toLowerCase();
+            const originalFilename = filename.substring(0, lastDotIndex);
+            if (this.options.allowedFileExtensions &&
+                !this.options.allowedFileExtensions.includes(originalExtension)) {
+                throw new Error(`File extension "${originalExtension}" is not allowed, allowed extensions are: ${this.options.allowedFileExtensions.join(', ')}`);
+            }
+            if (size != null && this.options.maxFileSize && size > this.options.maxFileSize) {
+                throw new Error(`File size ${size} is too large. Maximum allowed size is ${this.options.maxFileSize}`);
+            }
+            const existingValue = existingRecord === null || existingRecord === void 0 ? void 0 : existingRecord[this.options.pathColumnName];
+            const existingPaths = existingValue ? this.normalizePaths(existingValue) : undefined;
+            const filePath = this.options.filePath({
+                originalFilename,
+                originalExtension,
+                contentType,
+                record: existingRecord,
+            });
+            if (filePath.startsWith('/')) {
+                throw new Error('s3Path should not start with /, please adjust s3path function to not return / at the start of the path');
+            }
+            if (existingPaths && existingPaths.includes(filePath)) {
+                throw new Error('New file path cannot be the same as existing path to avoid caching issues');
+            }
+            const { uploadUrl, uploadExtraParams } = yield this.options.storageAdapter.getUploadSignedUrl(filePath, contentType, 1800);
+            return {
+                uploadUrl,
+                filePath,
+                uploadExtraParams,
+                pathColumnName: this.options.pathColumnName,
+            };
+        });
+    }
+    /**
+     * 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(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ recordId, filePath, adminUser, extra, }) {
+            var _b;
+            if (recordId === undefined || recordId === null) {
+                throw new Error('recordId is required');
+            }
+            if (!filePath) {
+                throw new Error('filePath is required');
+            }
+            if (!this.resourceConfig) {
+                throw new Error('resourceConfig is not initialized yet');
+            }
+            const pkColumn = this.resourceConfig.columns.find((column) => column.primaryKey);
+            const pkName = pkColumn === null || pkColumn === void 0 ? void 0 : pkColumn.name;
+            if (!pkName) {
+                throw new Error('Primary key column not found in resource configuration');
+            }
+            const existingRecord = yield this.adminforth
+                .resource(this.resourceConfig.resourceId)
+                .get([Filters.EQ(pkName, recordId)]);
+            if (!existingRecord) {
+                throw new Error(`Record with id ${recordId} not found`);
+            }
+            const existingValue = existingRecord[this.options.pathColumnName];
+            const existingPaths = this.normalizePaths(existingValue);
+            if (existingPaths.includes(filePath)) {
+                throw new Error('New file path cannot be the same as existing path to avoid caching issues');
+            }
+            const { error: updateError } = yield this.adminforth.updateResourceRecord({
+                resource: this.resourceConfig,
+                recordId,
+                oldRecord: existingRecord,
+                adminUser,
+                extra,
+                updates: {
+                    [this.options.pathColumnName]: filePath,
+                },
+            });
+            if (updateError) {
+                try {
+                    yield this.markKeyForDeletion(filePath);
+                }
+                catch (e) {
+                    // best-effort cleanup, ignore error
+                }
+                throw new Error(`Error updating record after upload: ${updateError}`);
+            }
+            let previewUrl;
+            if ((_b = this.options.preview) === null || _b === void 0 ? void 0 : _b.previewUrl) {
+                previewUrl = this.options.preview.previewUrl({ filePath });
+            }
+            else {
+                previewUrl = yield this.options.storageAdapter.getDownloadUrl(filePath, 1800);
+            }
+            return {
+                path: filePath,
+                previewUrl,
+            };
+        });
+    }
+    /**
+     * 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(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ filePath, adminUser, extra, recordAttributes, }) {
+            var _b;
+            if (!filePath) {
+                throw new Error('filePath is required');
+            }
+            if (!this.resourceConfig) {
+                throw new Error('resourceConfig is not initialized yet');
+            }
+            // Mark this key as used so lifecycle rules do not delete it.
+            yield this.markKeyForNotDeletion(filePath);
+            const { error: createError, createdRecord, newRecordId } = yield this.adminforth.createResourceRecord({
+                resource: this.resourceConfig,
+                record: Object.assign(Object.assign({}, (recordAttributes !== null && recordAttributes !== void 0 ? recordAttributes : {})), { [this.options.pathColumnName]: filePath }),
+                adminUser,
+                extra,
+            });
+            if (createError) {
+                try {
+                    yield this.markKeyForDeletion(filePath);
+                }
+                catch (e) {
+                    // best-effort cleanup, ignore error
+                }
+                throw new Error(`Error creating record after upload: ${createError}`);
+            }
+            const pkColumn = this.resourceConfig.columns.find((column) => column.primaryKey);
+            const pkName = pkColumn === null || pkColumn === void 0 ? void 0 : pkColumn.name;
+            const newRecordPk = newRecordId !== null && newRecordId !== void 0 ? newRecordId : (pkName && createdRecord ? createdRecord[pkName] : undefined);
+            let previewUrl;
+            if ((_b = this.options.preview) === null || _b === void 0 ? void 0 : _b.previewUrl) {
+                previewUrl = this.options.preview.previewUrl({ filePath });
+            }
+            else {
+                previewUrl = yield this.options.storageAdapter.getDownloadUrl(filePath, 1800);
+            }
+            return {
+                path: filePath,
+                previewUrl,
+                newRecordPk,
+            };
+        });
+    }
 }

package/index.ts

@@ -1,10 +1,16 @@
 
-import { PluginOptions, UploadFromBufferParams, UploadFromBufferToExistingRecordParams } from './types.js';
-import { AdminForthPlugin, AdminForthResourceColumn, AdminForthResource, Filters, IAdminForth, IHttpServer, suggestIfTypo, RateLimiter, AdminUser, HttpExtra } from "adminforth";
+import {
+  PluginOptions,
+  UploadFromBufferParams,
+  UploadFromBufferToExistingRecordParams,
+  CommitUrlToUpdateExistingRecordParams,
+  CommitUrlToNewRecordParams,
+  GetUploadUrlParams,
+} from './types.js';
+import { AdminForthPlugin, AdminForthResource, Filters, IAdminForth, IHttpServer, suggestIfTypo, RateLimiter } from "adminforth";
 import { Readable } from "stream";
 import { randomUUID } from "crypto";
-import { interpretResource } from 'adminforth';
-import { ActionCheckSource } from 'adminforth'; 
+import { interpretResource, ActionCheckSource } from 'adminforth';
 
 const ADMINFORTH_NOT_YET_USED_TAG = 'adminforth-candidate-for-cleanup';
 const jobs = new Map();
@@ -806,4 +812,288 @@ export default class UploadPlugin extends AdminForthPlugin {
     };
   }
 
+  /**
+   * 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 }),
+   * });
+   * ```
+   */
+  async getUploadUrl({
+    recordId,
+    filename,
+    contentType,
+    size,
+  }: GetUploadUrlParams): Promise<{
+    uploadUrl: string;
+    filePath: string;
+    uploadExtraParams?: Record<string, string>;
+    pathColumnName: string;
+  }> {
+    if (!filename || !contentType) {
+      throw new Error('filename and contentType are required');
+    }
+    if (!this.resourceConfig) {
+      throw new Error('resourceConfig is not initialized yet');
+    }
+
+    const pkColumn = this.resourceConfig.columns.find((column: any) => column.primaryKey);
+    const pkName = pkColumn?.name;
+    if (!pkName) {
+      throw new Error('Primary key column not found in resource configuration');
+    }
+
+    let existingRecord: any = undefined;
+    if (recordId !== undefined && recordId !== null) {
+      existingRecord = await this.adminforth
+        .resource(this.resourceConfig.resourceId)
+        .get([Filters.EQ(pkName, recordId)]);
+
+      if (!existingRecord) {
+        throw new Error(`Record with id ${recordId} not found`);
+      }
+    }
+
+    const lastDotIndex = filename.lastIndexOf('.');
+    if (lastDotIndex === -1) {
+      throw new Error('filename must contain an extension');
+    }
+
+    const originalExtension = filename.substring(lastDotIndex + 1).toLowerCase();
+    const originalFilename = filename.substring(0, lastDotIndex);
+
+    if (
+      this.options.allowedFileExtensions &&
+      !this.options.allowedFileExtensions.includes(originalExtension)
+    ) {
+      throw new Error(
+        `File extension "${originalExtension}" is not allowed, allowed extensions are: ${this.options.allowedFileExtensions.join(
+          ', ',
+        )}`,
+      );
+    }
+
+    if (size != null && this.options.maxFileSize && size > this.options.maxFileSize) {
+      throw new Error(
+        `File size ${size} is too large. Maximum allowed size is ${this.options.maxFileSize}`,
+      );
+    }
+
+    const existingValue = existingRecord?.[this.options.pathColumnName];
+    const existingPaths = existingValue ? this.normalizePaths(existingValue) : undefined;
+
+    const filePath: string = this.options.filePath({
+      originalFilename,
+      originalExtension,
+      contentType,
+      record: existingRecord,
+    });
+
+    if (filePath.startsWith('/')) {
+      throw new Error(
+        's3Path should not start with /, please adjust s3path function to not return / at the start of the path',
+      );
+    }
+
+    if (existingPaths && existingPaths.includes(filePath)) {
+      throw new Error(
+        'New file path cannot be the same as existing path to avoid caching issues',
+      );
+    }
+
+    const { uploadUrl, uploadExtraParams } = await this.options.storageAdapter.getUploadSignedUrl(
+      filePath,
+      contentType,
+      1800,
+    );
+
+    return {
+      uploadUrl,
+      filePath,
+      uploadExtraParams,
+      pathColumnName: this.options.pathColumnName,
+    };
+  }
+
+  /**
+   * 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.
+   */
+  async commitUrlToUpdateExistingRecord({
+    recordId,
+    filePath,
+    adminUser,
+    extra,
+  }: CommitUrlToUpdateExistingRecordParams): Promise<{ path: string; previewUrl: string }> {
+    if (recordId === undefined || recordId === null) {
+      throw new Error('recordId is required');
+    }
+    if (!filePath) {
+      throw new Error('filePath is required');
+    }
+    if (!this.resourceConfig) {
+      throw new Error('resourceConfig is not initialized yet');
+    }
+
+    const pkColumn = this.resourceConfig.columns.find((column: any) => column.primaryKey);
+    const pkName = pkColumn?.name;
+    if (!pkName) {
+      throw new Error('Primary key column not found in resource configuration');
+    }
+
+    const existingRecord = await this.adminforth
+      .resource(this.resourceConfig.resourceId)
+      .get([Filters.EQ(pkName, recordId)]);
+
+    if (!existingRecord) {
+      throw new Error(`Record with id ${recordId} not found`);
+    }
+
+    const existingValue = existingRecord[this.options.pathColumnName];
+    const existingPaths = this.normalizePaths(existingValue);
+
+    if (existingPaths.includes(filePath)) {
+      throw new Error(
+        'New file path cannot be the same as existing path to avoid caching issues',
+      );
+    }
+
+    const { error: updateError } = await this.adminforth.updateResourceRecord({
+      resource: this.resourceConfig,
+      recordId,
+      oldRecord: existingRecord,
+      adminUser,
+      extra,
+      updates: {
+        [this.options.pathColumnName]: filePath,
+      },
+    } as any);
+
+    if (updateError) {
+      try {
+        await this.markKeyForDeletion(filePath);
+      } catch (e) {
+        // best-effort cleanup, ignore error
+      }
+      throw new Error(`Error updating record after upload: ${updateError}`);
+    }
+
+    let previewUrl: string;
+    if (this.options.preview?.previewUrl) {
+      previewUrl = this.options.preview.previewUrl({ filePath });
+    } else {
+      previewUrl = await this.options.storageAdapter.getDownloadUrl(filePath, 1800);
+    }
+
+    return {
+      path: filePath,
+      previewUrl,
+    };
+  }
+
+  /**
+   * 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.
+   */
+  async commitUrlToNewRecord({
+    filePath,
+    adminUser,
+    extra,
+    recordAttributes,
+  }: CommitUrlToNewRecordParams): Promise<{ path: string; previewUrl: string; newRecordPk: any }> {
+    if (!filePath) {
+      throw new Error('filePath is required');
+    }
+    if (!this.resourceConfig) {
+      throw new Error('resourceConfig is not initialized yet');
+    }
+
+    // Mark this key as used so lifecycle rules do not delete it.
+    await this.markKeyForNotDeletion(filePath);
+
+    const { error: createError, createdRecord, newRecordId }: any =
+      await this.adminforth.createResourceRecord({
+        resource: this.resourceConfig,
+        record: { ...(recordAttributes ?? {}), [this.options.pathColumnName]: filePath },
+        adminUser,
+        extra,
+      });
+
+    if (createError) {
+      try {
+        await this.markKeyForDeletion(filePath);
+      } catch (e) {
+        // best-effort cleanup, ignore error
+      }
+      throw new Error(`Error creating record after upload: ${createError}`);
+    }
+
+    const pkColumn = this.resourceConfig.columns.find((column: any) => column.primaryKey);
+    const pkName = pkColumn?.name;
+    const newRecordPk = newRecordId ?? (pkName && createdRecord ? createdRecord[pkName] : undefined);
+
+    let previewUrl: string;
+    if (this.options.preview?.previewUrl) {
+      previewUrl = this.options.preview.previewUrl({ filePath });
+    } else {
+      previewUrl = await this.options.storageAdapter.getDownloadUrl(filePath, 1800);
+    }
+
+    return {
+      path: filePath,
+      previewUrl,
+      newRecordPk,
+    };
+  }
+
 }

package/package.json

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

package/types.ts

@@ -212,4 +212,107 @@ export type UploadFromBufferToExistingRecordParams = UploadFromBufferParams & {
    * 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>;
 };