Add migration guide for brevo module v2 to v3 (#3256)

Co-authored-by: Johannes Obermair <[email protected]>

docs/docs/3-features-modules/9-brevo-module/index.md

@@ -0,0 +1,3 @@
+---
+title: Brevo Module
+---

docs/docs/3-features-modules/9-brevo-module/migration-guide/index.md

@@ -0,0 +1,3 @@
+---
+title: Brevo Module Migration Guide
+---

docs/docs/3-features-modules/9-brevo-module/migration-guide/migration-from-brevo-v2-to-v3.md

@@ -0,0 +1,110 @@
+---
+title: Migrating from v2 to v3
+---
+
+:::caution
+Make sure that your project uses COMET v7.10.0 or later.
+:::
+
+## API
+
+### Create `EmailCampaign` and `TargetGroup` entities
+
+Use `createEmailCampaignEntity` for creating the `EmailCampaign` entity. Pass `EmailCampaignContentBlock`, `Scope` and `TargetGroup`:
+
+```ts
+export const EmailCampaign = createEmailCampaignEntity({
+    EmailCampaignContentBlock: EmailCampaignContentBlock,
+    Scope: EmailCampaignContentScope,
+    TargetGroup: TargetGroup,
+});
+```
+
+Use `createTargetGroupEntity` for creating the `TargetGroup` entity. Pass `Scope` and optionally `BrevoFilterAttributes`:
+
+```ts
+export const TargetGroup = createTargetGroupEntity({
+    Scope: EmailCampaignContentScope,
+    BrevoFilterAttributes: BrevoContactFilterAttributes,
+});
+```
+
+Pass both to the `AppModule`:
+
+```diff
+    BrevoModule.register({
+        brevo: {
+            //...
++           EmailCampaign
++           TargetGroup
+        }
+        //...
+    });
+```
+
+### Import `FileUploadsModule` in the project's `AppModule`
+
+It is now required to import the `FileUploadsModule` in the project's `AppModule` and configure it to accept CSV files.
+
+```ts
+FileUploadsModule.register({
+    acceptedMimeTypes: ["text/csv"],
+    maxFileSize: config.fileUploads.maxFileSize,
+    directory: `${config.blob.storageDirectoryPrefix}-file-uploads`,
+}),
+```
+
+The files for the Brevo contact import now get temporarily stored in the file uploads until the import is concluded.
+This change prepares for future imports to be handled in a separate job, allowing more than 100 contacts to be imported without exhausting API resources or blocking the event loop.
+
+### Remove Brevo configuration variables from environment variables
+
+Environment variables containing Brevo configuration information can be removed and are set on the `BrevoConfigurationPage` in the admin interface from now on.
+
+-   BREVO_SENDER_NAME
+-   BREVO_SENDER_EMAIL
+-   BREVO_DOUBLE_OPT_IN_TEMPLATE_ID
+-   BREVO_ALLOWED_REDIRECT_URL
+
+### Remove `allowedRedirectionUrl` from the Brevo module configuration
+
+```diff
+BrevoModule.register({
+    brevo: {
+-       allowedRedirectionUrl: config.brevo.allowedRedirectionUrl,
+        //...
+    },
+    //..
+})
+```
+
+## Admin
+
+### Add Brevo configuration page to admin interface
+
+Import `BrevoConfigPage` from `@comet/brevo-admin` and add it to your project's `MasterMenu`. All necessary Brevo configuration (for each scope) must be configured within this page for email campaigns to be sent.
+
+### Define `scopeParts` in `BrevoConfig`
+
+Previously, the `scopeParts` were passed to `createBrevoContactsPage`, `createTargetGroupsPage`, and `createEmailCampaignsPage`.
+Remove `scopeParts` from those functions.
+Instead define them in the `BrevoConfigProvider` once:
+
+```tsx
+<BrevoConfigProvider
+    value={{
+        scopeParts: ["domain", "language"],
+        ...otherProps,
+    }}
+>
+    {children}
+</BrevoConfigProvider>
+```
+
+## Site
+
+### Optional: use new `@comet/brevo-mail-rendering` package
+
+Install `@comet/brevo-mail-rendering` in your project's site.
+This package offers reuseable components for rendering emails.
+You can use the `NewsletterImageBlock` for rendering images in your newsletter campaigns.

project-words.txt

@@ -18,3 +18,4 @@ subcomponent
 subpage
 typesafe
 exif
+brevo