feat(email-plugin): Allow specify metadata for EmailSendEvent

[Anddrrew]

Description

Added metadata for EmailSendEvent and setMetadata function on EmailEventHandler
Closes #2849

Checklist

📌 Always:

• I have set a clear title
• My PR is small and contains a single feature
• I have checked my own PR

👍 Most of the time:

• I have added or updated test cases
• I have updated the README if needed

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	Jul 18, 2024 9:30pm

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[Anddrrew]

I have read the CLA Document and I hereby sign the CLA

[michaelbromley]

Hi, I'm glad you found time for this - very nice addition.

2 points:

1. Since this is a new feature, could you make the PR against the minor branch? I think you can just select it in the GH ui.
2. Good that you included basic documentation, but I think it would be good to expand on this in order to properly explain the use-case of the metadata. If you have some suggestions on what would be a good example, feel free to update the PR with example(s) in-line in the doc block.

[Anddrrew]

I believe I can add a good example of documentation after using it in my project and testing on real cases.

Brief description:
This will allow us to identify exactly what this EmailSendEvent belonged to and perform additional logic based on that.

Example of flow:

• An OrderStateTransitionEvent occurs, and the EmailEventListener starts processing it.
• We set metadata in this way

new EmailEventListener(EventType.ORDER_CONFIRMATION)
  .on(OrderStateTransitionEvent)
  .setMetadata(event => ({
    type: EventType.ORDER_CONFIRMATION,
    orderId: event.order.id,
  }))

• Then, the email-plugin tries to send the email and publishes EmailSendEvent, passing ctx, emailDetails, error or success, and this metadata.
• In another part of the server, we have an eventBus that subscribes to EmailSendEvent. We can use metadata.type and metadata.orderId to identify the related order. For example, we can indicate on the order that the email was successfully sent, or in case of an error, send a notification confirming the order in another available way.