diff --git a/www/docs/content/upgrade-guides/medusa-core/1-15-0.md b/www/docs/content/upgrade-guides/medusa-core/1-15-0.md new file mode 100644 index 0000000000..41143e0b9a --- /dev/null +++ b/www/docs/content/upgrade-guides/medusa-core/1-15-0.md @@ -0,0 +1,121 @@ +--- +description: 'Actions Required for v.1.15.0' +sidebar_custom_props: + iconName: 'server-stack-solid' +--- + +# v1.15.0 + +Version 1.15.0 of Medusa comes with improvements to the Import and Export features, leading to several breaking changes. + +## Overview + +This release contains breaking changes in the Import/Export and File Service domains. + +--- + +## How to Update + +Run the following command in the root directory of your Medusa Backend: + +```bash npm2yarn +npm install @medusajs/medusa@1.15.0 +``` + +To avoid unexpected issues with dependencies, it is also recommended to update all other Medusa plugins or packages you have installed. For this release in particular, you must update file service plugins to ensure they work as expected. + +--- + +## File Services + +The file service streaming API to upload to public/private buckets has been updated to be consistent across all plugins. + +### File Service Interface + +The following types specific to file services have moved from `@medusajs/medusa` to `@medusajs/types`: + +```ts +export type FileServiceUploadResult = { + url: string + key: string +} + +export type FileServiceGetUploadStreamResult = { + writeStream: stream.PassThrough + promise: Promise + url: string + fileKey: string + [x: string]: unknown +} + +export type GetUploadedFileType = { + fileKey: string + isPrivate?: boolean + [x: string]: unknown +} + +export type DeleteFileType = { + fileKey: string + [x: string]: unknown +} + +export type UploadStreamDescriptorType = { + name: string + ext?: string + isPrivate?: boolean + [x: string]: unknown +} +``` + +Also, previously, the `getUploadStreamDescriptor` method of file services didn't require a specific option to specify whether a file should be uploaded to a private or public bucket. For example, if you used the MinIO plugin, you passed the `usePrivateBucket` option, whereas with the S3 and Spaces plugins, you passed the `acl` option. + +With this update, the option is now specified within the signature of the method in the `IFileService` interface that all file services extend. The `getUploadStreamDescriptor` now accepts as part of its option the `isPrivate` option: + + + +```ts +getUploadStreamDescriptor({ + // ... other options + isPrivate // boolean value +}): Promise +``` + +### File Service Plugins + +Following the updates in the previous section, all the official plugins (MinIO, S3, and Spaces) now implement the new `getUploadStreamDescriptor` signature. The `isPrivate` option is optional and defaults to `true`. + +For example, here's a comparison of how you previously specified whether a file should be uploaded to a private or public bucket, and how you must do it now: + + + +```ts +// before +// MinIO +fileService.getUploadStreamDescriptor({..., usePrivateBucket: false}) +// S3 & Spaces +fileService.getUploadStreamDescriptor({..., acl: "public-read"}) + +// after +fileService.getUploadStreamDescriptor({..., isPrivate: true}) // private bucket (default) +fileService.getUploadStreamDescriptor({..., isPrivate: false}) // public bucket +``` + +--- + +## Import/Export + +The following method signatures in the Price List and Product import batch job strategies have been updated: + + + +```ts +// before +downloadImportOpsFile(batchJobId: string, op: OperationType) +deleteOpsFiles(batchJobId: string) + +// after +downloadImportOpsFile(batchJob: BatchJob, op: OperationType) +deleteOpsFiles(batchJob: BatchJob) +``` + +Mainly, both the `downloadImportOpsFile` and `deleteOpsFiles` methods now requires the batch job instance as the first parameter. Previously, they required only the ID of the batch job.