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

apps/sharebymail/composer/composer/autoload_classmap.php

@@ -10,6 +10,10 @@
     'OCA\\ShareByMail\\Activity' => $baseDir . '/../lib/Activity.php',
     'OCA\\ShareByMail\\AppInfo\\Application' => $baseDir . '/../lib/AppInfo/Application.php',
     'OCA\\ShareByMail\\Capabilities' => $baseDir . '/../lib/Capabilities.php',
+    'OCA\\ShareByMail\\Event\\AbstractBeforeShareMailSentEvent' => $baseDir . '/../lib/Event/AbstractBeforeShareMailSentEvent.php',
+    'OCA\\ShareByMail\\Event\\BeforeShareMailSentEvent' => $baseDir . '/../lib/Event/BeforeShareMailSentEvent.php',
+    'OCA\\ShareByMail\\Event\\BeforeShareNoteMailSentEvent' => $baseDir . '/../lib/Event/BeforeShareNoteMailSentEvent.php',
+    'OCA\\ShareByMail\\Event\\BeforeSharePasswordMailSentEvent' => $baseDir . '/../lib/Event/BeforeSharePasswordMailSentEvent.php',
     'OCA\\ShareByMail\\Settings\\Admin' => $baseDir . '/../lib/Settings/Admin.php',
     'OCA\\ShareByMail\\Settings\\SettingsManager' => $baseDir . '/../lib/Settings/SettingsManager.php',
     'OCA\\ShareByMail\\ShareByMailProvider' => $baseDir . '/../lib/ShareByMailProvider.php',

apps/sharebymail/composer/composer/autoload_static.php

@@ -25,6 +25,10 @@ class ComposerStaticInitShareByMail
         'OCA\\ShareByMail\\Activity' => __DIR__ . '/..' . '/../lib/Activity.php',
         'OCA\\ShareByMail\\AppInfo\\Application' => __DIR__ . '/..' . '/../lib/AppInfo/Application.php',
         'OCA\\ShareByMail\\Capabilities' => __DIR__ . '/..' . '/../lib/Capabilities.php',
+        'OCA\\ShareByMail\\Event\\AbstractBeforeShareMailSentEvent' => __DIR__ . '/..' . '/../lib/Event/AbstractBeforeShareMailSentEvent.php',
+        'OCA\\ShareByMail\\Event\\BeforeShareMailSentEvent' => __DIR__ . '/..' . '/../lib/Event/BeforeShareMailSentEvent.php',
+        'OCA\\ShareByMail\\Event\\BeforeShareNoteMailSentEvent' => __DIR__ . '/..' . '/../lib/Event/BeforeShareNoteMailSentEvent.php',
+        'OCA\\ShareByMail\\Event\\BeforeSharePasswordMailSentEvent' => __DIR__ . '/..' . '/../lib/Event/BeforeSharePasswordMailSentEvent.php',
         'OCA\\ShareByMail\\Settings\\Admin' => __DIR__ . '/..' . '/../lib/Settings/Admin.php',
         'OCA\\ShareByMail\\Settings\\SettingsManager' => __DIR__ . '/..' . '/../lib/Settings/SettingsManager.php',
         'OCA\\ShareByMail\\ShareByMailProvider' => __DIR__ . '/..' . '/../lib/ShareByMailProvider.php',

apps/sharebymail/lib/Event/AbstractBeforeShareMailSentEvent.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\ShareByMail\Event;
+
+use OCP\EventDispatcher\Event;
+use OCP\Mail\IMessage;
+use OCP\Share\IShare;
+
+/**
+ * Base class for all BeforeShare*MailSentEvent types.
+ *
+ * Carries the fully-prepared IMessage (already rendered) and the resolved
+ * recipient list. Listeners call markMailHandled() to suppress the native
+ * mailer->send().
+ */
+abstract class AbstractBeforeShareMailSentEvent extends Event {
+	private bool $mailHandled = false;
+
+	/**
+	 * @param string[] $resolvedEmails resolved recipient addresses (not guaranteed to be validated)
+	 */
+	public function __construct(
+		private readonly IShare $share,
+		private readonly array $resolvedEmails,
+		private readonly IMessage $message,
+	) {
+		parent::__construct();
+	}
+
+	public function getShare(): IShare {
+		return $this->share;
+	}
+
+	/** @return string[] */
+	public function getResolvedEmails(): array {
+		return $this->resolvedEmails;
+	}
+
+	public function getMessage(): IMessage {
+		return $this->message;
+	}
+
+	/**
+	 * Call to suppress the native mailer->send() for this message.
+	 * Must be called before any send attempt — if the listener's own send
+	 * throws, the exception propagates and the native send is also skipped.
+	 */
+	public function markMailHandled(): void {
+		$this->mailHandled = true;
+	}
+
+	public function isMailHandled(): bool {
+		return $this->mailHandled;
+	}
+}

apps/sharebymail/lib/Event/BeforeShareMailSentEvent.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\ShareByMail\Event;
+
+use OCP\Mail\IMessage;
+use OCP\Share\IShare;
+
+/**
+ * Fired by ShareByMailProvider::sendEmail() immediately before the native
+ * mailer->send() call for share-link notifications to recipients.
+ *
+ * @psalm-type TemplateData = array{
+ *   senderUserId: string,
+ *   filename: string,
+ *   link: string,
+ *   initiator: string,
+ *   expiration: \DateTime|null,
+ *   shareWith: string,
+ *   note: string,
+ * }
+ *
+ * @psalm-api
+ */
+class BeforeShareMailSentEvent extends AbstractBeforeShareMailSentEvent {
+	/**
+	 * @param string[] $resolvedEmails
+	 * @param TemplateData $templateData
+	 */
+	public function __construct(
+		IShare $share,
+		array $resolvedEmails,
+		IMessage $message,
+		private readonly array $templateData,
+	) {
+		parent::__construct($share, $resolvedEmails, $message);
+	}
+
+	public function getSenderUserId(): string {
+		return $this->templateData['senderUserId'];
+	}
+
+	public function getFileName(): string {
+		return $this->templateData['filename'];
+	}
+
+	public function getResourceUrl(): string {
+		return $this->templateData['link'];
+	}
+
+	public function getNote(): string {
+		return $this->templateData['note'];
+	}
+
+	public function getShareWith(): string {
+		return $this->templateData['shareWith'];
+	}
+
+	public function getInitiatorDisplayName(): string {
+		return $this->templateData['initiator'];
+	}
+
+	public function getExpiration(): ?\DateTime {
+		return $this->templateData['expiration'];
+	}
+}

apps/sharebymail/lib/Event/BeforeShareNoteMailSentEvent.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\ShareByMail\Event;
+
+use OCP\Mail\IMessage;
+use OCP\Share\IShare;
+
+/**
+ * Fired by ShareByMailProvider::sendNote() immediately before the native
+ * mailer->send() call for note-update notifications to recipients.
+ *
+ * @psalm-type TemplateData = array{
+ *   filename: string,
+ *   note: string,
+ * }
+ *
+ * @psalm-api
+ */
+class BeforeShareNoteMailSentEvent extends AbstractBeforeShareMailSentEvent {
+	/**
+	 * @param string[] $resolvedEmails
+	 * @param TemplateData $templateData
+	 */
+	public function __construct(
+		IShare $share,
+		array $resolvedEmails,
+		IMessage $message,
+		private readonly array $templateData,
+	) {
+		parent::__construct($share, $resolvedEmails, $message);
+	}
+
+	public function getFileName(): string {
+		return $this->templateData['filename'];
+	}
+
+	public function getNote(): string {
+		return $this->templateData['note'];
+	}
+}

apps/sharebymail/lib/Event/BeforeSharePasswordMailSentEvent.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\ShareByMail\Event;
+
+use OCP\Mail\IMessage;
+use OCP\Share\IShare;
+
+/**
+ * Fired by ShareByMailProvider::sendPassword() and sendPasswordToOwner()
+ * immediately before the native mailer->send() call for password emails.
+ *
+ * For sendPassword(), initiatorEmail may be null when the initiator has no
+ * email address configured. For sendPasswordToOwner() it is always a non-null
+ * string (the call site throws earlier if the owner has no email address).
+ *
+ * @psalm-type TemplateData = array{
+ *   filename: string,
+ *   password: string,
+ *   initiator: string,
+ *   initiatorEmail: string|null,
+ *   shareWith: string,
+ * }
+ *
+ * @psalm-api
+ */
+class BeforeSharePasswordMailSentEvent extends AbstractBeforeShareMailSentEvent {
+	/**
+	 * @param string[] $resolvedEmails
+	 * @param TemplateData $templateData
+	 */
+	public function __construct(
+		IShare $share,
+		array $resolvedEmails,
+		IMessage $message,
+		private readonly array $templateData,
+	) {
+		parent::__construct($share, $resolvedEmails, $message);
+	}
+
+	public function getFileName(): string {
+		return $this->templateData['filename'];
+	}
+
+	public function getPassword(): string {
+		return $this->templateData['password'];
+	}
+
+	public function getInitiatorDisplayName(): string {
+		return $this->templateData['initiator'];
+	}
+
+	public function getInitiatorEmail(): ?string {
+		return $this->templateData['initiatorEmail'];
+	}
+
+	public function getShareWith(): string {
+		return $this->templateData['shareWith'];
+	}
+}