feat: add uploadFromBuffer method and associated types for file uploads

Author: ivictbor

index.ts

@@ -1,5 +1,5 @@
 
-import { PluginOptions } from './types.js';
+import { PluginOptions, UploadFromBufferParams } from './types.js';
 import { AdminForthPlugin, AdminForthResourceColumn, AdminForthResource, Filters, IAdminForth, IHttpServer, suggestIfTypo, RateLimiter, AdminUser, HttpExtra } from "adminforth";
 import { Readable } from "stream";
 import { randomUUID } from "crypto";
@@ -554,19 +554,17 @@ export default class UploadPlugin extends AdminForthPlugin {
   }
 
 
+  /*
+   * Uploads a file from a buffer, creates a record in the resource, and returns the file path and preview URL.
+   */
   async uploadFromBuffer({
     filename,
     contentType,
     buffer,
     adminUser,
     extra,
-  }: {
-    filename: string;
-    contentType: string;
-    buffer: Buffer | Uint8Array | ArrayBuffer;
-    adminUser: AdminUser;
-    extra?: HttpExtra;
-  }): Promise<{ path: string; previewUrl: string }> {
+    recordAttributes,
+  }: UploadFromBufferParams): Promise<{ path: string; previewUrl: string }> {
     if (!filename || !contentType || !buffer) {
       throw new Error('filename, contentType and buffer are required');
     }
@@ -644,22 +642,22 @@ export default class UploadPlugin extends AdminForthPlugin {
       throw new Error(`Upload failed with status ${resp.status}: ${bodyText}`);
     }
 
-    await this.options.storageAdapter.markKeyForNotDeletation(filePath);
+    await this.markKeyForNotDeletion(filePath);
 
     if (!this.resourceConfig) {
       throw new Error('resourceConfig is not initialized yet');
     }
 
     const { error: createError } = await this.adminforth.createResourceRecord({
       resource: this.resourceConfig,
-      record: { [this.options.pathColumnName]: filePath },
+      record: { ...(recordAttributes ?? {}), [this.options.pathColumnName]: filePath },
       adminUser,
       extra,
     });
 
     if (createError) {
       try {
-        await this.options.storageAdapter.markKeyForDeletation(filePath);
+        await this.markKeyForDeletion(filePath);
       } catch (e) {
         // best-effort cleanup, ignore error
       }

types.ts

@@ -1,4 +1,4 @@
-import { AdminUser, ImageGenerationAdapter, StorageAdapter } from "adminforth";
+import { AdminUser, ImageGenerationAdapter, StorageAdapter, HttpExtra } from "adminforth";
 
 export type PluginOptions = {
 
@@ -154,4 +154,49 @@ export type PluginOptions = {
    * 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>;
+};