types.ts

import { AdminUser, ImageGenerationAdapter, StorageAdapter, HttpExtra } from "adminforth";

export type PluginOptions = {

  /**
   * 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[]; // allowed file extensions

  /**
   * 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}) => 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>;
};