chore(js-sdk,types,utils): updates to file TSDocs (#12426)

* chore(js-sdk,types,utils): updates to file TSDocs

* remove ignore tag for file provider

* update file service tsdocs

packages/core/js-sdk/src/admin/product.ts

@@ -63,8 +63,15 @@ export class Product {
    * the import is confirmed using the {@link confirmImport} method.
    *
    * This method sends a request to the
-   * [Create Product Import](https://docs.medusajs.com/api/admin#products_postproductsimport)
+   * [Create Product Import](https://docs.medusajs.com/api/admin#products_postproductsimports)
    * API route.
+   * 
+   * @version 2.8.0
+   * @ignore
+   * @privateRemarks
+   * The ignore tag to be removed once the feature is ready.
+   * Also, the version indicates the version where the method was added.
+   * Maybe we should change the version once the feature is ready.
    *
    * @param body - The import's details.
    * @param query - Query parameters to pass to the request.

packages/core/types/src/file/provider.ts

@@ -30,7 +30,12 @@ export type ProviderFileResultDTO = {
  */
 export type ProviderGetFileDTO = {
   /**
-   * The file's key as returned during upload.
+   * The file's key allowing you to later
+   * identify the file in the third-party
+   * system. For example, the S3 Module Provider
+   * returns the file's key in S3, whereas the
+   * Local File Module Provider returns the file's
+   * path.
    */
   fileKey: string
   [x: string]: unknown

packages/core/types/src/file/service.ts

@@ -166,7 +166,14 @@ export interface IFileModuleService extends IModuleService {
   ): Promise<[FileDTO[], number]>
 
   /**
-   * Get the file contents as a readable stream.
+   * This method retrieves a file by its ID and returns a stream to download the file. Under the hood, it will use the
+   * file provider that was used to upload the file to retrievethe stream.
+   * 
+   * @version 2.8.0
+   * 
+   * @param {string} id - The ID of the file.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<Readable>} A readable stream of the file contents.
    *
    * @example
    * const stream = await fileModuleService.getDownloadStream("file_123")
@@ -175,7 +182,14 @@ export interface IFileModuleService extends IModuleService {
   getDownloadStream(id: string, sharedContext?: Context): Promise<Readable>
 
   /**
-   * Get the file contents as a Node.js Buffer
+   * This method retrieves a file by its ID and returns the file contents as a buffer. Under the hood, it will use the
+   * file provider that was used to upload the file to retrieve the buffer.
+   * 
+   * @version 2.8.0
+   * 
+   * @param {string} id - The ID of the file.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<Buffer>} A buffer of the file contents.
    *
    * @example
    * const contents = await fileModuleService.getAsBuffer("file_123")

packages/core/types/src/http/file/admin/payloads.ts

@@ -3,8 +3,20 @@ import { BaseUploadFile } from "../common"
 export type AdminUploadFile = BaseUploadFile
 
 export interface AdminUploadPreSignedUrlRequest {
+  /**
+   * The original name of the file on the user's computer (aka clientName)
+   */
   originalname: string
+  /**
+   * The mime type of the file.
+   */
   mime_type: string
+  /**
+   * The size of the file in bytes.
+   */
   size: number
+  /**
+   * The access level of the file.
+   */
   access?: "public" | "private"
 }

packages/core/types/src/http/product/admin/payloads.ts

@@ -572,9 +572,28 @@ interface AdminDeleteProductVariantInventoryItem {
 }
 
 export interface AdminImportProductsRequest {
+  /**
+   * The file's identifier in the third-party system.
+   * For example, the S3 Module Provider
+   * returns the file's key in S3, whereas the
+   * Local File Module Provider returns the file's
+   * path.
+   */
   file_key: string
+  /**
+   * The original name of the file on the user's computer (aka clientName)
+   */
   originalname: string
+  /**
+   * The file's extension.
+   */
   extension: string
+  /**
+   * The file's size in bytes.
+   */
   size: number
+  /**
+   * The file's mime type.
+   */
   mime_type: string
 }

packages/core/utils/src/file/abstract-file-provider.ts

@@ -136,7 +136,8 @@ export class AbstractFileProviderService implements IFileProvider {
    *   // ...
    *   async delete(file: ProviderDeleteFileDTO): Promise<void> {
    *     // TODO logic to remove the file from storage
-   *     // Use the `file.fileKey` to delete the file
+   *     // Use the `file.fileKey` to delete the file, which is the identifier of the file
+   *    // in the provider's storage.
    *     // for example:
    *     this.client.delete(file.fileKey)
    *   }
@@ -164,7 +165,8 @@ export class AbstractFileProviderService implements IFileProvider {
    *     fileData: ProviderGetFileDTO
    *   ): Promise<string> {
    *     // TODO logic to get the presigned URL
-   *     // Use the `file.fileKey` to delete the file
+   *     // Use the `file.fileKey` to delete the file, which is the identifier of the file
+   *    // in the provider's storage.
    *     // for example:
    *     return this.client.getPresignedUrl(fileData.fileKey)
    *   }
@@ -177,12 +179,22 @@ export class AbstractFileProviderService implements IFileProvider {
   }
 
   /**
-   * Get the file contents as a readable stream.
+   * This method retrieves an uploaded file as a stream. This is useful when streaming
+   * a file to clients or you want to process the file in chunks.
+   * 
+   * @param {FileTypes.ProviderGetFileDTO} fileData - The details of the file to get its stream.
+   * @returns {Promise<Readable>} The file's stream.
+   * 
+   * @version 2.8.0
    *
    * @example
    * class MyFileProviderService extends AbstractFileProviderService {
    *   // ...
    *   async getAsStream(file: ProviderDeleteFileDTO): Promise<Readable> {
+   *    // TODO logic to get the file as a stream
+   *    // Use the `file.fileKey` to get the file, which is the identifier of the file
+   *    // in the provider's storage.
+   *    // for example:
    *     this.client.getAsStream(file.fileKey)
    *   }
    * }
@@ -192,12 +204,22 @@ export class AbstractFileProviderService implements IFileProvider {
   }
 
   /**
-   * Get the file contents as a Node.js Buffer
+   * This method retrieves an uploaded file as a buffer. This is useful when you want to
+   * process the entire file in memory or send it as a response.
+   * 
+   * @param {FileTypes.ProviderGetFileDTO} fileData - The details of the file to get its buffer.
+   * @returns {Promise<Buffer>} The file's buffer.
+   * 
+   * @version 2.8.0
    *
    * @example
    * class MyFileProviderService extends AbstractFileProviderService {
    *   // ...
    *   async getAsBuffer(file: ProviderDeleteFileDTO): Promise<Buffer> {
+   *     // TODO logic to get the file as a buffer
+   *     // Use the `file.fileKey` to get the file, which is the identifier of the file
+   *     // in the provider's storage.
+   *     // for example:
    *     this.client.getAsBuffer(file.fileKey)
    *   }
    * }