diff --git a/packages/core/js-sdk/src/admin/product.ts b/packages/core/js-sdk/src/admin/product.ts index 1cba6b970f..9e3969ba13 100644 --- a/packages/core/js-sdk/src/admin/product.ts +++ b/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. diff --git a/packages/core/types/src/file/provider.ts b/packages/core/types/src/file/provider.ts index 5faba81c7d..7a4fb761ca 100644 --- a/packages/core/types/src/file/provider.ts +++ b/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 diff --git a/packages/core/types/src/file/service.ts b/packages/core/types/src/file/service.ts index 832ac82f43..d4e15e86c5 100644 --- a/packages/core/types/src/file/service.ts +++ b/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} 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 /** - * 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} A buffer of the file contents. * * @example * const contents = await fileModuleService.getAsBuffer("file_123") diff --git a/packages/core/types/src/http/file/admin/payloads.ts b/packages/core/types/src/http/file/admin/payloads.ts index 7681c87afb..8a4897c0ca 100644 --- a/packages/core/types/src/http/file/admin/payloads.ts +++ b/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" } diff --git a/packages/core/types/src/http/product/admin/payloads.ts b/packages/core/types/src/http/product/admin/payloads.ts index 805af828d4..40d94e38a8 100644 --- a/packages/core/types/src/http/product/admin/payloads.ts +++ b/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 } diff --git a/packages/core/utils/src/file/abstract-file-provider.ts b/packages/core/utils/src/file/abstract-file-provider.ts index 6a62d7cce3..62149b1fdb 100644 --- a/packages/core/utils/src/file/abstract-file-provider.ts +++ b/packages/core/utils/src/file/abstract-file-provider.ts @@ -136,7 +136,8 @@ export class AbstractFileProviderService implements IFileProvider { * // ... * async delete(file: ProviderDeleteFileDTO): Promise { * // 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 { * // 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} The file's stream. + * + * @version 2.8.0 * * @example * class MyFileProviderService extends AbstractFileProviderService { * // ... * async getAsStream(file: ProviderDeleteFileDTO): Promise { + * // 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} The file's buffer. + * + * @version 2.8.0 * * @example * class MyFileProviderService extends AbstractFileProviderService { * // ... * async getAsBuffer(file: ProviderDeleteFileDTO): Promise { + * // 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) * } * }