index.ts

import {
  PluginOptions,
  UploadFromBufferParams,
  UploadFromBufferToExistingRecordParams,
  CommitUrlToUpdateExistingRecordParams,
  CommitUrlToNewRecordParams,
  GetUploadUrlParams,
} from './types.js';
import { AdminForthPlugin, AdminForthResource, AdminUser, AllowedActionsEnum, Filters, HttpExtra, IAdminForth, IHttpServer, suggestIfTypo, RateLimiter } from "adminforth";
import { Readable } from "stream";
import { randomUUID } from "crypto";
import { interpretResource, ActionCheckSource } from 'adminforth';
import { z } from "zod";

const getFileUploadUrlBodySchema = z.object({
  originalFilename: z.string(),
  contentType: z.string(),
  size: z.number(),
  originalExtension: z.string(),
  recordPk: z.union([z.string(), z.number()]).nullish(),
}).strict();

const createImageGenerationJobBodySchema = z.object({
  prompt: z.string(),
  recordId: z.union([z.string(), z.number()]).nullish(),
  requestAttachmentFiles: z.array(z.string()),
}).strict();

const jobStatusBodySchema = z.object({
  jobId: z.string(),
}).strict();

const recordIdBodySchema = z.object({
  recordId: z.union([z.string(), z.number()]).nullish(),
}).strict();

const filePathBodySchema = z.object({
  filePath: z.string(),
}).strict();

const ADMINFORTH_NOT_YET_USED_TAG = 'adminforth-candidate-for-cleanup';

const EXTENSION_CONTENT_TYPES: Record<string, string> = {
  // images
  png: 'image/png',
  jpg: 'image/jpeg',
  jpeg: 'image/jpeg',
  gif: 'image/gif',
  webp: 'image/webp',
  bmp: 'image/bmp',
  ico: 'image/x-icon',
  tif: 'image/tiff',
  tiff: 'image/tiff',
  avif: 'image/avif',
  heic: 'image/heic',
  heif: 'image/heif',
  // video
  mp4: 'video/mp4',
  webm: 'video/webm',
  mov: 'video/quicktime',
  avi: 'video/x-msvideo',
  mkv: 'video/x-matroska',
  // audio
  mp3: 'audio/mpeg',
  wav: 'audio/wav',
  ogg: 'audio/ogg',
  oga: 'audio/ogg',
  m4a: 'audio/mp4',
  flac: 'audio/flac',
  aac: 'audio/aac',
  // documents
  pdf: 'application/pdf',
  txt: 'text/plain',
  md: 'text/plain',
  csv: 'text/csv',
  json: 'application/json',
  doc: 'application/msword',
  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
  xls: 'application/vnd.ms-excel',
  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  ppt: 'application/vnd.ms-powerpoint',
  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
  // archives
  zip: 'application/zip',
  gz: 'application/gzip',
  tar: 'application/x-tar',
  '7z': 'application/x-7z-compressed',
  rar: 'application/vnd.rar',
  // fonts
  woff: 'font/woff',
  woff2: 'font/woff2',
  ttf: 'font/ttf',
  otf: 'font/otf',
};
const jobs = new Map();
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, contentType, size, originalExtension, recordPk, preloadedRecord?: any ) => Promise<{ uploadUrl: string, contentType?: string, tagline?: string, filePath?: string, uploadExtraParams?: Record<string, string>, previewUrl?: string, error?: string } | {error: string}>;

  constructor(options: PluginOptions) {
    super(options, import.meta.url);
    this.options = options;

    // for calcualting average time
    this.totalCalls = 0;
    this.totalDuration = 0;
    this.getFileDownloadUrl = async (path: string, expiresInSeconds: number = 1800) : Promise<string> => {
      if (!path) {
        return '';
      }
      return this.options.storageAdapter.getDownloadUrl(path, expiresInSeconds);
    }

    this.getFileUploadUrl = async ( originalFilename, contentType, size, originalExtension, recordPk, preloadedRecord = undefined ) : Promise<{ uploadUrl: string, contentType?: string, tagline?: string, filePath?: string, uploadExtraParams?: Record<string, string>, previewUrl?: string, error?: string } | {error: string}> => {
        const extension = (originalExtension || '').replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
        if (!extension) {
          return { error: 'File extension is required' };
        }
        if (this.options.allowedFileExtensions && !this.options.allowedFileExtensions.includes(extension)) {
          return {
            error: `File extension "${originalExtension}" is not allowed, allowed extensions are: ${this.options.allowedFileExtensions.join(', ')}`
          };
        }

        if (size != null && this.options.maxFileSize && size > this.options.maxFileSize) {
          return {
            error: `File size ${size} is too large. Maximum allowed size is ${this.options.maxFileSize}`
          };
        }

        const safeContentType = this.resolveContentType(extension);

        let record = preloadedRecord;
        if (record === undefined && recordPk) {
          // get record by recordPk
          const pkName = this.resourceConfig.columns.find((column: any) => column.primaryKey)?.name;
          record = await this.adminforth.resource(this.resourceConfig.resourceId).get(
            [Filters.EQ(pkName, recordPk)]
          )
        }

        const sanitizeFileName = (name) => {
          return name
            .normalize("NFKD")                
            .replace(/[^a-zA-Z0-9._-]/g, "_")
        }        
        const fileName = sanitizeFileName(originalFilename);  
        const filePath: string = this.options.filePath({ originalFilename: fileName, originalExtension: extension, contentType: safeContentType, record });
        if (filePath.startsWith('/')) {
          throw new Error('s3Path should not start with /, please adjust s3path function to not return / at the start of the path');
        }
        // the URL is bound to the declared size, so the client can't declare a small file and upload a bigger one;
        // server-side callers may pass no size, their uploads are not limited as before
        const { uploadUrl, uploadExtraParams } = await this.options.storageAdapter.getUploadSignedUrl(filePath, safeContentType, 1800, size ?? undefined);
        let previewUrl;
        if (this.options.preview?.previewUrl) {
          previewUrl = this.options.preview.previewUrl({ filePath });
        } else {
          previewUrl = await this.options.storageAdapter.getDownloadUrl(filePath, 1800);
        }
        const tagline = `${ADMINFORTH_NOT_YET_USED_TAG}=true`;
        
        return {
          uploadUrl,
          contentType: safeContentType,
          tagline,
          filePath,
          uploadExtraParams,
          previewUrl,
        };
    };

    if (this.options.generation?.rateLimit?.limit) {
      this.rateLimiter = new RateLimiter(this.options.generation.rateLimit?.limit)
    }
  }

  private resolveContentType(extension: string): string {
    if (this.options.contentTypeByExtension?.[extension]) {
      return this.options.contentTypeByExtension[extension];
    } else if (EXTENSION_CONTENT_TYPES[extension]) {
      return EXTENSION_CONTENT_TYPES[extension];
    } else {
      throw new Error('Provided incorrect file extension. Do not return upload url.');
    }
  }

  private normalizePaths(value: any): string[] {
    if (!value) return [];
    if (Array.isArray(value)) return value.filter(Boolean).map(String);
    return [String(value)];
  }

  // an isArray path column keeps a list of paths, so the new file is added to the existing ones
  private pathColumnValue(filePath: string, existingPaths: string[] = []): string | string[] {
    const pathColumn = this.resourceConfig.columns.find((column: any) => column.name === this.options.pathColumnName);
    return pathColumn.isArray?.enabled ? [...existingPaths, filePath] : filePath;
  }

  public markKeyForNotDeletion(filePath: string) {
    return this.options.storageAdapter.markKeyForNotDeletion(filePath);
  }

  public markKeyForDeletion(filePath: string) {
    return this.options.storageAdapter.markKeyForDeletion(filePath);
  }

  private async generateImages(jobId: string, prompt: string,requestAttachmentFiles: string[], recordId: any, adminUser: any, headers: any) {
    if (this.options.generation.rateLimit?.limit) {
      if (!await this.rateLimiter.consume(`${this.pluginInstanceId}-${this.adminforth.auth.getClientIp(headers)}`)) {
        jobs.set(jobId, { status: "failed", error: this.options.generation.rateLimit.errorMessage });
        return { error: this.options.generation.rateLimit.errorMessage };
      }
    }
    let attachmentFiles = requestAttachmentFiles;
    
    let error: string | undefined = undefined;

    const STUB_MODE = false;

    const images = await Promise.all(
      (new Array(this.options.generation.countToGenerate)).fill(0).map(async () => {
        if (STUB_MODE) {
          await new Promise((resolve) => setTimeout(resolve, 2000));
          return `https://picsum.photos/200/300?random=${Math.floor(Math.random() * 1000)}`;
        }
        const start = +new Date();
        let resp;
        try {
          resp = await this.options.generation.adapter.generate(
            {
              prompt,
              inputFiles: attachmentFiles,
              n: 1,
              size: this.options.generation.outputSize,
            }
          )
        } catch (e: any) {
          error = `No response from image generation provider: ${e.message}. Please check your prompt or try again later.`;
          return;
        }

        if (resp.error) {
          console.error('Error generating image', resp.error);
          error = resp.error;
          return;
        }

        this.totalCalls++;
        this.totalDuration += (+new Date() - start) / 1000;
        
        return resp.imageURLs[0]

      })
    );
    jobs.set(jobId, { status: "completed", images, error });
    return { ok: true };
  };

  async isInternalUrl(url: string): Promise<boolean> {
    const adapter = this.options.storageAdapter as any;
    if (adapter && typeof adapter.isInternalUrl === 'function') {
      try {
        if(this.options.preview?.previewUrl) {
          const previewUrl = this.options.preview.previewUrl({ filePath: 'test_filepath' });
          if (url.startsWith(previewUrl.replace('test_filepath', ''))) {
            return true;
          }
          return false;
        }
        return await adapter.isInternalUrl(url);
      } catch (err) {
        console.error(`[UploadPlugin] Error calling isInternalUrl on adapter:`, err);
        return false;
      }
    } else {
      throw new Error ('Plese update storage adapter')
    }
    return false;
  }

  instanceUniqueRepresentation(pluginOptions: any) : string {
    return `${pluginOptions.pathColumnName}`;
  }

  async setupLifecycleRule() {
    const adapterUserUniqueRepresentation = `${this.resourceConfig.resourceId}-${this.pluginInstanceId}`;
    this.options.storageAdapter.setupLifecycle(adapterUserUniqueRepresentation);
  }

  async genPreviewUrl(record: any) {
    const value = record?.[this.options.pathColumnName];
    const paths = this.normalizePaths(value);
    if (!paths.length) return;

    const makeUrl = async (filePath: string) => {
      if (this.options.preview?.previewUrl) {
        return this.options.preview.previewUrl({ filePath });
      }
      return await this.options.storageAdapter.getDownloadUrl(filePath, 1800);
    };

    const urls = await Promise.all(paths.map(makeUrl));
    record[`previewUrl_${this.pluginInstanceId}`] = Array.isArray(value) ? urls : urls[0];
  }

  async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
    super.modifyResourceConfig(adminforth, resourceConfig);
    this.resourceConfig = resourceConfig;
    // after column to store the path of the uploaded file, add new VirtualColumn,
    // show only in edit and create views
    // use component uploader.vue
    const { pathColumnName } = this.options;
    const pathColumnIndex = resourceConfig.columns.findIndex((column: any) => column.name === pathColumnName);
    if (pathColumnIndex === -1) {
      throw new Error(`Column with name "${pathColumnName}" not found in resource "${resourceConfig.label}"`);
    }

    for(const extintion of this.options.allowedFileExtensions || []){
      try {
        this.resolveContentType(extintion);
      } catch(e){
        throw new Error(`Upload plugin can't resolve content type for extension "${extintion}". Provide contentTypeByExtension in plugin options`);
      }
    } 

    const pluginFrontendOptions = {
      allowedExtensions: this.options.allowedFileExtensions,
      maxFileSize: this.options.maxFileSize,
      pluginInstanceId: this.pluginInstanceId,
      resourceLabel: resourceConfig.label,
      generateImages: this.options.generation ? true : false,
      pathColumnLabel: resourceConfig.columns[pathColumnIndex].label,
      maxWidth: this.options.preview?.maxWidth,
      maxListWidth: this.options.preview?.maxListWidth,
      maxShowWidth: this.options.preview?.maxShowWidth,
      minWidth: this.options.preview?.minWidth,
      minListWidth: this.options.preview?.minListWidth,
      minShowWidth: this.options.preview?.minShowWidth,
      generationPrompt: this.options.generation?.generationPrompt,
      recorPkFieldName: this.resourceConfig.columns.find((column: any) => column.primaryKey)?.name,
      pathColumnName: this.options.pathColumnName,
    };
    // define components which will be imported from other components
    this.componentPath('imageGenerator.vue');

    if (!resourceConfig.columns[pathColumnIndex].components) {
      resourceConfig.columns[pathColumnIndex].components = {};
    }
    const pathColumn = resourceConfig.columns[pathColumnIndex];
    
    // add preview column to list
    if (this.options.preview?.usePreviewComponents !== false) {
      resourceConfig.columns[pathColumnIndex].components.list = {
        file: this.componentPath('preview.vue'),
        meta: pluginFrontendOptions,
      };

      resourceConfig.columns[pathColumnIndex].components.show = {
        file: this.componentPath('preview.vue'),
        meta: pluginFrontendOptions,
      };
    }

    resourceConfig.columns[pathColumnIndex].components.create = {
      file: this.componentPath('uploader.vue'),
      meta: pluginFrontendOptions,
    }

    resourceConfig.columns[pathColumnIndex].components.edit = {
      file: this.componentPath('uploader.vue'),
      meta: pluginFrontendOptions,
    }

    // ** HOOKS FOR CREATE **//


    // in afterSave hook, aremove tag adminforth-not-yet-used from the file
    resourceConfig.hooks.create.afterSave.push(async ({ record }: { record: any }) => {
      process.env.HEAVY_DEBUG && console.log('💾💾  after save ', record?.id);
      
      const paths = this.normalizePaths(record?.[pathColumnName]);
      await Promise.all(paths.map(async (p) => {
        process.env.HEAVY_DEBUG && console.log('🪥🪥 remove ObjectTagging', p);
        // let it crash if it fails: this is a new file which just was uploaded.
        await this.markKeyForNotDeletion(p);
      }));
      return { ok: true };
    });

    // ** HOOKS FOR SHOW **//


    // add show hook to get presigned URL
    if (pathColumn.showIn.show) {

      resourceConfig.hooks.show.afterDatasourceResponse.push(async ({ response }: { response: any }) => {
        const record = response[0];
        if (!record) {
          return { ok: true };
        }
        if (record[pathColumnName]) {
          await this.genPreviewUrl(record)
        }
        return { ok: true };
      });
    }

    // ** HOOKS FOR LIST **//


    if (pathColumn.showIn.list) {
      resourceConfig.hooks.list.afterDatasourceResponse.push(async ({ response }: { response: any }) => {
       await Promise.all(response.map(async (record: any) => {
          if (record[this.options.pathColumnName]) {
            await this.genPreviewUrl(record)
          }
        }));
        return { ok: true };
      })
    }

    // ** HOOKS FOR DELETE **//

    // add delete hook which sets tag adminforth-candidate-for-cleanup to true
    resourceConfig.hooks.delete.afterSave.push(async ({ record }: { record: any }) => {
      const paths = this.normalizePaths(record?.[pathColumnName]);
      await Promise.all(paths.map(async (p) => {
        try {
          await this.markKeyForDeletion(p);
        } catch (e) {
          // file might be e.g. already deleted, so we catch error
          console.error(`Error setting tag ${ADMINFORTH_NOT_YET_USED_TAG} to true for object ${p}. File will not be auto-cleaned up`, e);
        }
      }));
      return { ok: true };
    });


    // ** HOOKS FOR EDIT **//



    // add edit postSave hook to delete old file and remove tag from new file
    resourceConfig.hooks.edit.afterSave.push(async ({ updates, oldRecord }: { updates: any, oldRecord: any }) => {

      if (updates[pathColumnName] || updates[pathColumnName] === null) {
        const oldValue = oldRecord?.[pathColumnName];
        const newValue = updates?.[pathColumnName];

        const oldPaths = this.normalizePaths(oldValue);
        const newPaths = newValue === null ? [] : this.normalizePaths(newValue);

        const oldSet = new Set(oldPaths);
        const newSet = new Set(newPaths);

        const toDelete = oldPaths.filter((p) => !newSet.has(p));
        const toKeep = newPaths.filter((p) => !oldSet.has(p));

        await Promise.all(toDelete.map(async (p) => {
          // put tag to delete old file
          try {
            await this.markKeyForDeletion(p);
          } catch (e) {
            // file might be e.g. already deleted, so we catch error
            console.error(`Error setting tag ${ADMINFORTH_NOT_YET_USED_TAG} to true for object ${p}. File will not be auto-cleaned up`, e);
          }
        }));

        await Promise.all(toKeep.map(async (p) => {
          // remove tag from new file
          // in this case we let it crash if it fails: this is a new file which just was uploaded.
          await this.markKeyForNotDeletion(p);
        }));
      }
      return { ok: true };
    });

    
  }

  validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: any) {
    this.adminforth = adminforth;
    
    if (this.options.generation) {
      const template = this.options.generation?.generationPrompt || '';
      const regex = /{{(.*?)}}/g;
      const matches = template.match(regex);
      if (matches) {
        matches.forEach((match) => {
          const field = match.replace(/{{|}}/g, '').trim();
          if (!resourceConfig.columns.find((column: any) => column.name === field)) {
            const similar = suggestIfTypo(resourceConfig.columns.map((column: any) => column.name), field);
            throw new Error(`Field "${field}" specified in generationPrompt not found in resource "${resourceConfig.label}". ${similar ? `Did you mean "${similar}"?` : ''}`);
          } else {
            let column = resourceConfig.columns.find((column: any) => column.name === field);
            if (column.backendOnly === true) {
              throw new Error(`Field "${field}" specified in generationPrompt is marked as backendOnly in resource "${resourceConfig.label}". Please remove backendOnly or choose another field.`);
            }
          }
        });
      }
    }
    // called here because modifyResourceConfig can be called in build time where there is no environment and AWS secrets
    this.setupLifecycleRule();
  }
  

  /**
   * Writes of the upload helpers (`uploadFromBuffer*`, `commitUrl*`). They are called from the
   * app's own endpoints, which decide who may upload, so they are system writes on behalf of
   * `adminUser` that run the resource hooks and validation.
   */
  private recordWriter(adminUser: AdminUser, extra?: HttpExtra, oldRecord?: any) {
    return this.adminforth.resource(this.resourceConfig.resourceId).asSystem({ adminUser, extra, oldRecord });
  }

  private async checkUploadAllowed(adminUser: AdminUser, recordPk: any): Promise<{ allowed: boolean, error?: string, record?: any }> {
    if (recordPk === undefined || recordPk === null || recordPk === '') {
      const { allowedActions } = await interpretResource(
        adminUser,
        this.resourceConfig,
        {},
        ActionCheckSource.CreateRequest,
        this.adminforth
      );
      const createAllowed = allowedActions[AllowedActionsEnum.create] as boolean | string | undefined;
      if (createAllowed !== true) {
        return { allowed: false, error: typeof createAllowed === 'string' ? createAllowed : 'You do not have permission to upload files to this resource' };
      }
      return { allowed: true };
    }

    const pkName = this.resourceConfig.columns.find((column: any) => column.primaryKey)?.name;
    const resource = this.adminforth.resource(this.resourceConfig.resourceId);
    const filter = Filters.EQ(pkName, recordPk);
    // looked up as the user, so a record outside their row scope is treated as missing;
    // both are reported as a permission error to not leak which records exist
    const visibleRecord = await resource.asUser(adminUser).get(filter).catch(() => null);
    if (!visibleRecord) {
      return { allowed: false, error: 'You do not have permission to upload files to this record' };
    }
    // filePath and attachFiles are server-side and get the full row, backendOnly columns included
    const record = await resource.get(filter);
    const { allowedActions } = await interpretResource(
      adminUser,
      this.resourceConfig,
      { oldRecord: record, pk: recordPk },
      ActionCheckSource.EditRequest,
      this.adminforth
    );
    const editAllowed = allowedActions[AllowedActionsEnum.edit] as boolean | string | undefined;
    if (editAllowed !== true) {
      return { allowed: false, error: typeof editAllowed === 'string' ? editAllowed : 'You do not have permission to upload files to this record' };
    }
    return { allowed: true, record };
  }

  setupEndpoints(server: IHttpServer) {
    server.endpoint({
      method: 'GET',
      path: `/plugin/${this.pluginInstanceId}/averageDuration`,
      handler: async () => {
        return {
          totalCalls: this.totalCalls,
          totalDuration: this.totalDuration,
          averageDuration: this.totalCalls ? this.totalDuration / this.totalCalls : null,
        };
      }
    });

    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get_file_upload_url`,
      request_schema: getFileUploadUrlBodySchema,
      handler: async ({ body, adminUser, response }) => {
        const data = body as z.infer<typeof getFileUploadUrlBodySchema>;
        const { originalFilename, contentType, size, originalExtension, recordPk } = data;

        if (!originalFilename || !originalExtension || !contentType) {
          return { error: 'originalFilename, originalExtension and contentType are required' };
        }

        const { allowed, error, record } = await this.checkUploadAllowed(adminUser, recordPk);
        if (!allowed) {
          response.setStatus(403);
          return { error };
        }

        return this.getFileUploadUrl( originalFilename, contentType, size, originalExtension, recordPk, record );

      }
    });

    // generation: {
    //   provider: 'openai-dall-e',
    //   countToGenerate: 3,
    //   openAiOptions: {
    //     model: 'dall-e-3',
    //     size: '1792x1024',
    //     apiKey: process.env.OPENAI_API_KEY as string,
    //   },
    // },

  //   curl https://api.openai.com/v1/images/generations \
  // -H "Content-Type: application/json" \
  // -H "Authorization: Bearer $OPENAI_API_KEY" \
  // -d '{
  //   "model": "dall-e-3",
  //   "prompt": "A cute baby sea otter",
  //   "n": 1,
  //   "size": "1024x1024"
  // }'

    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/create-image-generation-job`,
      request_schema: createImageGenerationJobBodySchema,
      handler: async ({ body, adminUser, headers, response }) => {
        const data = body as z.infer<typeof createImageGenerationJobBodySchema>;
        const { prompt, recordId, requestAttachmentFiles } = data;
        // generating an image is uploading one, so it needs the same permission
        const { allowed, error } = await this.checkUploadAllowed(adminUser, recordId);
        if (!allowed) {
          response.setStatus(403);
          return { ok: false, error };
        }
        const jobId = randomUUID();
        jobs.set(jobId, { status: "in_progress" });

        this.generateImages(jobId, prompt, requestAttachmentFiles, recordId, adminUser, headers);
        setTimeout(() => jobs.delete(jobId), 1_800_000);
        setTimeout(() => {jobs.set(jobId, { status: "timeout" });}, 300_000);

        return { ok: true, jobId };
      }
    });

    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get-image-generation-job-status`,
      request_schema: jobStatusBodySchema,
      handler: async ({ body, adminUser, headers, response }) => {
        const data = body as z.infer<typeof jobStatusBodySchema>;
        const jobId = data.jobId;
        if (!jobId) {
          response.setStatus(400);
          return { ok: false, error: "Can't find job id" };
        }
        const job = jobs.get(jobId);
        if (!job) {
          response.setStatus(404);
          return { ok: false, error: "Job not found" };
        }
        if (job.status === 'failed' || job.error) {
          response.setStatus(500);

          return {
            ok: false,
            job,
          };
        }
        return { ok: true, job };
      }
    });
    
    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get_attachment_files`,
      request_schema: recordIdBodySchema,
      handler: async ({ body, adminUser, response }) => {
        const data = body as z.infer<typeof recordIdBodySchema>;
        const { recordId } = data;

        if (!recordId) return { error: 'Missing recordId' };

        // the files feed an image generation for this record, so it needs the upload permission on it
        const { allowed, error, record } = await this.checkUploadAllowed(adminUser, recordId);
        if (!allowed) {
          response.setStatus(403);
          return { error };
        }

        if (!this.options.generation.attachFiles) return { files: [] };
    
        const files = await this.options.generation.attachFiles({ record, adminUser });
    
        return {
          files: Array.isArray(files) ? files : [files],
        };
      },
    });

    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get-file-download-url`,
      request_schema: filePathBodySchema,
      handler: async ({ body, adminUser, response }) => {
        const data = body as z.infer<typeof filePathBodySchema>;
        const { filePath } = data;
        if (!filePath) {
          return { error: 'Missing filePath' };
        }
        // the path comes from the client, so it is signed only when a record the user can see stores it,
        // otherwise any key in the bucket could be downloaded by guessing its path
        const record = await this.adminforth.resource(this.resourceConfig.resourceId)
          .asUser(adminUser)
          .get(Filters.EQ(this.options.pathColumnName, filePath))
          .catch(() => null);
        if (!record) {
          response.setStatus(403);
          return { error: 'You do not have permission to download this file' };
        }
        const url = await this.options.storageAdapter.getDownloadUrl(filePath, 1800);
        return { url };
      },
    });

    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get-file-preview-url`,
      request_schema: filePathBodySchema,
      handler: async ({ body, adminUser, response }) => {
        const data = body as z.infer<typeof filePathBodySchema>;
        const { filePath } = data;
        if (!filePath) {
          return { error: 'Missing filePath' };
        }
        if (this.options.preview?.previewUrl) {
          const url = this.options.preview.previewUrl({ filePath });
          return { url };
        }
        return { error: 'failed to generate preview URL' };
      },
    });
  }
  
  /*
   * Uploads a file from a buffer, creates a record in the resource, and returns the file path and preview URL.
   */
  async uploadFromBufferToNewRecord({
    filename,
    contentType,
    buffer,
    adminUser,
    extra,
    recordAttributes,
  }: UploadFromBufferParams): Promise<{ path: string; previewUrl: string; newRecordPk: any }> {
    if (!filename || !contentType || !buffer) {
      throw new Error('filename, contentType and buffer are required');
    }

    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(', ')}`
      );
    }

    let nodeBuffer: Buffer;
    if (Buffer.isBuffer(buffer)) {
      nodeBuffer = buffer;
    } else if (buffer instanceof ArrayBuffer) {
      nodeBuffer = Buffer.from(buffer);
    } else if (ArrayBuffer.isView(buffer)) {
      nodeBuffer = Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
    } else {
      throw new Error('Unsupported buffer type');
    }

    const size = nodeBuffer.byteLength;
    if (this.options.maxFileSize && size > this.options.maxFileSize) {
      throw new Error(
        `File size ${size} is too large. Maximum allowed size is ${this.options.maxFileSize}`
      );
    }
    const filePath: string = this.options.filePath({
      originalFilename,
      originalExtension,
      contentType,
      record: undefined,
    });

    if (filePath.startsWith('/')) {
      throw new Error('s3Path should not start with /, please adjust s3path function to not return / at the start of the path');
    }

    const { uploadUrl, uploadExtraParams } = await this.options.storageAdapter.getUploadSignedUrl(
      filePath,
      contentType,
      1800,
      size,
    );

    const headers: Record<string, string> = {
      'Content-Type': contentType,
    };
    if (uploadExtraParams) {
      Object.entries(uploadExtraParams).forEach(([key, value]) => {
        headers[key] = value as string;
      });
    }

    const resp = await fetch(uploadUrl as any, {
      method: 'PUT',
      headers,
      body: nodeBuffer as any,
    });

    if (!resp.ok) {
      let bodyText = '';
      try {
        bodyText = await resp.text();
      } catch (e) {
        // ignore
      }
      throw new Error(`Upload failed with status ${resp.status}: ${bodyText}`);
    }

    await this.markKeyForNotDeletion(filePath);

    if (!this.resourceConfig) {
      throw new Error('resourceConfig is not initialized yet');
    }

    const { error: createError, createdRecord } = await this.recordWriter(adminUser, extra)
      .create({ ...(recordAttributes ?? {}), [this.options.pathColumnName]: this.pathColumnValue(filePath) });

    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 = 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,
    };
  }

  /*
   * Uploads a file from a buffer and updates an existing record's path column.
   * For an isArray path column the file is added to the existing files instead of replacing them.
   * If the newly generated storage path would be the same as the current path,
   * throws an error to avoid potential caching issues.
   */
  async uploadFromBufferToExistingRecord({
    recordId,
    filename,
    contentType,
    buffer,
    adminUser,
    extra,
  }: UploadFromBufferToExistingRecordParams): Promise<{ path: string; previewUrl: string }> {
    if (recordId === undefined || recordId === null) {
      throw new Error('recordId is required');
    }

    if (!filename || !contentType || !buffer) {
      throw new Error('filename, contentType and buffer 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');
    }

    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 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(', ')}`
      );
    }

    let nodeBuffer: Buffer;
    if (Buffer.isBuffer(buffer)) {
      nodeBuffer = buffer;
    } else if (buffer instanceof ArrayBuffer) {
      nodeBuffer = Buffer.from(buffer);
    } else if (ArrayBuffer.isView(buffer)) {
      nodeBuffer = Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
    } else {
      throw new Error('Unsupported buffer type');
    }

    const size = nodeBuffer.byteLength;
    if (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 = this.normalizePaths(existingValue);

    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.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,
      size,
    );

    const headers: Record<string, string> = {
      'Content-Type': contentType,
    };
    if (uploadExtraParams) {
      Object.entries(uploadExtraParams).forEach(([key, value]) => {
        headers[key] = value as string;
      });
    }

    const resp = await fetch(uploadUrl as any, {
      method: 'PUT',
      headers,
      body: nodeBuffer as any,
    });

    if (!resp.ok) {
      let bodyText = '';
      try {
        bodyText = await resp.text();
      } catch (e) {
        // ignore
      }
      throw new Error(`Upload failed with status ${resp.status}: ${bodyText}`);
    }

    const { error: updateError } = await this.recordWriter(adminUser, extra, existingRecord)
      .update(recordId, { [this.options.pathColumnName]: this.pathColumnValue(filePath, existingPaths) });

    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,
    };
  }

  /**
   * 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
   *
   * The file is always stored with the content type derived from its extension (see
   * {@link PluginOptions.contentTypeByExtension}), not with the passed one, so that an uploader can't
   * make the storage serve executable content. The URL is signed for the returned `contentType`, so
   * the upload request has to use it.
   *
   * ```ts
   * const file = input.files[0];
   *
   * // 1) Ask your backend to call getUploadUrlForExistingRecord
   * const { uploadUrl, contentType, 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());
   *
   * // 2) Direct upload from the browser to storage: the file itself as the body, with the returned content type
   * const uploadResp = await fetch(uploadUrl, {
   *   method: 'PUT',
   *   headers: { 'Content-Type': contentType, ...uploadExtraParams },
   *   body: file,
   * });
   * 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;
    contentType: 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 safeContentType = this.resolveContentType(originalExtension);

    const filePath: string = this.options.filePath({
      originalFilename,
      originalExtension,
      contentType: safeContentType,
      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,
      safeContentType,
      1800,
      size ?? undefined,
    );

    return {
      uploadUrl,
      contentType: safeContentType,
      filePath,
      uploadExtraParams,
      pathColumnName: this.options.pathColumnName,
    };
  }

  /**
   * Commits a previously generated upload URL to an existing record.
   * For an isArray path column the file is added to the existing files instead of replacing them.
   *
   * 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.recordWriter(adminUser, extra, existingRecord)
      .update(recordId, { [this.options.pathColumnName]: this.pathColumnValue(filePath, existingPaths) });

    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 } = await this.recordWriter(adminUser, extra)
      .create({ ...(recordAttributes ?? {}), [this.options.pathColumnName]: this.pathColumnValue(filePath) });

    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 = 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,
    };
  }

}