feat(sharebymail): dispatch BeforeShare*MailSentEvent before each mail send

[printminion-co]

Summary

ShareByMailProvider sends share-by-mail notifications straight through the native mailer with no
extension point. This adds a typed PSR-14 event dispatched immediately before every
mailer->send(), so an app can intercept and replace delivery (e.g. route through a different
transport) without patching the provider.

A listener calls markMailHandled() to take ownership of delivery; the native mailer->send() is
then skipped. If the listener throws, the exception propagates and the native send is still skipped
— no silent SMTP fallback. With no listener registered, behaviour is unchanged.

Before — native SMTP only

sequenceDiagram
    participant C as Caller (share flow)
    participant P as ShareByMailProvider
    participant M as IMailer
    C->>P: sendEmail / sendPassword / sendPasswordToOwner / sendNote
    P->>M: mailer->send(message)
    M-->>P: failedRecipients

Loading

After — event dispatched before send

sequenceDiagram
    participant C as Caller (share flow)
    participant P as ShareByMailProvider
    participant D as IEventDispatcher
    participant L as App listener (optional)
    participant M as IMailer
    C->>P: sendEmail / sendPassword / sendPasswordToOwner / sendNote
    P->>D: dispatchTyped(BeforeShare*MailSentEvent)
    D->>L: handle(event)
    alt listener took over delivery
        L->>L: deliver via own transport
        L->>P: markMailHandled()
        Note over P,M: native send skipped, activity not logged
    else no listener / not handled (default)
        P->>M: mailer->send(message)
        M-->>P: failedRecipients
    end

Loading

Notes

• New public API under OCA\ShareByMail\Event\*; each concrete event carries typed getters for the
  data already computed before building the IMessage (no re-derivation in listeners).
• createPasswordSendActivity() now runs only when the mail is actually sent (moved inside the
  isMailHandled() guard), so a suppressed password mail no longer logs a false activity entry.

TODO

• Maintainer feedback on the event API shape before marking ready for review

Checklist

• Code is properly formatted (php-cs-fixer clean)
• Sign-off message is added to all commits
• Tests (unit) are included — apps/sharebymail/tests/ShareByMailProviderTest.php
• Screenshots before/after — n/a (no front-end changes)
• Documentation not required (developer-facing event API)
• Backports requested — n/a (feature)
• Labels added — maintainer
• Milestone added — maintainer

AI (if applicable)

• The content of this PR was partly or fully generated using AI

[artonge]

This is motivated by two problematics:

1. The limitation of our templating system that prevent them from using their mail own templates with all the metadata (template variables, sender/recipient, type of email).
2. The limitation of our IMailer that does not allow them to use a non-SMTP backend

[github-actions]

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)