fix: add storage adapter interface, add comments to existing adapters

Author: ivictbor

adminforth/types/Adapters.ts

@@ -1,6 +1,19 @@
 export interface EmailAdapter {
+
+  /**
+   * This method is called to validate the configuration of the adapter
+   * and should throw a clear user-readbale error if the configuration is invalid.
+   */
   validate(): Promise<void>;
 
+  /**
+   * This method should send an email using the adapter
+   * @param from - The sender's email address
+   * @param to - The recipient's email address
+   * @param text - The plain text version of the email
+   * @param html - The HTML version of the email
+   * @param subject - The subject of the email
+   */
   sendEmail(
     from: string,
     to: string,
@@ -15,8 +28,19 @@ export interface EmailAdapter {
 
 export interface CompletionAdapter {
 
+  /**
+   * This method is called to validate the configuration of the adapter
+   * and should throw a clear user-readbale error if the configuration is invalid.
+   */
   validate(): void;
 
+  /**
+   * This method should return a text completion based on the provided content and stop sequence.
+   * @param content - The input text to complete
+   * @param stop - An array of stop sequences to indicate where to stop the completion
+   * @param maxTokens - The maximum number of tokens to generate
+   * @returns A promise that resolves to an object containing the completed text and other metadata
+   */
   complete(
     content: string,
     stop: string[],
@@ -30,10 +54,14 @@ export interface CompletionAdapter {
 
 export interface ImageGenerationAdapter {
 
+  /**
+   * This method is called to validate the configuration of the adapter
+   * and should throw a clear user-readbale error if the configuration is invalid.
+   */
   validate(): void;
 
   /**
-   * Return 1 or 10, or Infinity if the adapter supports multiple images
+   * Return max number of images which model can generate in one request
    */
   outputImagesMaxCountSupported(): number;
 
@@ -47,6 +75,14 @@ export interface ImageGenerationAdapter {
    */
   inputFileExtensionSupported(): string[];
 
+  /**
+   * This method should generate an image based on the provided prompt and input files.
+   * @param prompt - The prompt to generate the image
+   * @param inputFiles - An array of input file paths (optional)
+   * @param n - The number of images to generate (default is 1)
+   * @param size - The size of the generated image (default is the lowest dimension supported)
+   * @returns A promise that resolves to an object containing the generated image URLs and any error message
+   */
   generate({
     prompt, 
     inputFiles,
@@ -68,11 +104,76 @@ export interface ImageGenerationAdapter {
 }
 
 
-
+/**
+ * This interface is used to implement OAuth2 authentication adapters.
+ */
 export interface OAuth2Adapter {
+  /**
+   * This method should return navigatable URL to the OAuth2 provider authentication page.
+   */
   getAuthUrl(): string;
+
+  /**
+   * This method should return the token from the OAuth2 provider using the provided code and redirect URI.
+   * @param code - The authorization code received from the OAuth2 provider
+   * @param redirect_uri - The redirect URI used in the authentication request
+   * @returns A promise that resolves to an object containing the email address of the authenticated user
+   */
   getTokenFromCode(code: string, redirect_uri: string): Promise<{ email: string }>;
+
+  /**
+   * This method should return text (content) of SVG icon which will be used in the UI.
+   * Use official SVG icons with simplest possible conent, omit icons which have base64 encoded raster images inside.
+   */
   getIcon(): string;
+
+  /**
+   * This method should return the text to be displayed on the button in the UI
+   */
   getButtonText?(): string;
+
+  /**
+   * This method should return the name of the adapter
+   */
   getName?(): string;
 }
+
+
+export interface StorageAdapter {
+  /**
+   * This method should return the presigned URL for the given key capable of upload.
+   * The PUT method should fail if the file already exists.
+   * @param key - The key of the file to be uploaded e.g. "uploads/file.txt"
+   * @param expiresIn - The expiration time in seconds for the presigned URL
+   */
+  getUploadSignedUrl(key: string, contentType: string, expiresIn?: number): Promise<string>;
+
+  /**
+   * This method should return the presigned URL for the given key capable of download
+   * @param key - The key of the file to be downloaded e.g. "uploads/file.txt"
+   * @param expiresIn - The expiration time in seconds for the presigned URL
+   */
+  getDownloadSignedUrl(key: string, expiresIn?: number): Promise<string>;
+
+  /**
+   * This method should mark the file for deletion.
+   * @param key - The key of the file to be uploaded e.g. "uploads/file.txt"
+   */
+  markKeyForDeletation(key: string): Promise<string>;
+
+
+  /**
+   * This method should return the list of files in the storage.
+   * @param key 
+   */
+  markKeyForNotDeletation(key: string): Promise<string>;
+
+
+  /**
+   * THis method can start needed schedullers, cron jobs, etc. to clean up the storage.
+   */
+  setupLifecycle(): Promise<void>;
+
+}
+
+