nextcloud-workflow-deck-automation/lib/Service/NotificationPolicy.php

<?php

declare(strict_types=1);

namespace OCA\WorkflowDeckAutomation\Service;

/**
 * Who hears about a moved card, and how — pure logic, no Nextcloud or Deck
 * dependencies, so it is unit-testable like WorkflowRunner::hasPassed().
 */
class NotificationPolicy {
	/** No mail at all. */
	public const MODE_OFF = 'off';
	/** Only the workflow's owner (the board owner), regardless of Deck settings. */
	public const MODE_OWNER = 'owner';
	/** Everyone with access to the board, filtered by their own Deck setting. */
	public const MODE_BOARD = 'board';

	public const MODES = [self::MODE_OFF, self::MODE_OWNER, self::MODE_BOARD];

	/** One mail per recipient and run. */
	public const CHANNEL_MAIL = 'mail';
	/** One Nextcloud notification (bell, push to the mobile apps) per card. */
	public const CHANNEL_NOTIFICATION = 'notification';
	public const CHANNEL_BOTH = 'both';

	public const CHANNELS = [self::CHANNEL_MAIL, self::CHANNEL_NOTIFICATION, self::CHANNEL_BOTH];

	/**
	 * Values of Deck's per-user, per-board preference
	 * `deck` / `board:<boardId>:notify-due` (Deck's
	 * ConfigService::SETTING_BOARD_NOTIFICATION_DUE_*), inlined so a renamed
	 * constant cannot fatal this app. It is the board's "Notifications" menu
	 * in Deck — the due-date reminder setting, which is exactly what fits a
	 * card being moved because it fell due.
	 */
	public const DECK_OFF = 'off';
	public const DECK_ASSIGNED = 'assigned';
	public const DECK_ALL = 'all';
	/** What Deck assumes for a user who never touched the setting. */
	public const DECK_DEFAULT = self::DECK_ASSIGNED;

	public static function isValidMode(string $mode): bool {
		return in_array($mode, self::MODES, true);
	}

	public static function isValidChannel(string $channel): bool {
		return in_array($channel, self::CHANNELS, true);
	}

	/**
	 * An unknown channel counts as `mail`, the column default — mail was the
	 * only channel before the column existed.
	 */
	public static function sendsMail(string $channel): bool {
		return $channel !== self::CHANNEL_NOTIFICATION;
	}

	public static function sendsNotification(string $channel): bool {
		return $channel === self::CHANNEL_NOTIFICATION || $channel === self::CHANNEL_BOTH;
	}

	/**
	 * Mirrors Deck's own decision in NotificationHelper::sendCardDuedate():
	 *
	 * - `off` never notifies — not even the owner of an unshared board;
	 * - `all` always notifies;
	 * - the owner of an unshared board is notified for every card, since on a
	 *   board nobody else can see "assigned" would otherwise mean nothing;
	 * - `assigned` notifies users assigned to the card, directly or through a
	 *   group or circle.
	 *
	 * An unknown value is treated as Deck's default. Deck rejects anything
	 * else when storing the setting, so that only happens if the preference
	 * was edited by hand.
	 *
	 * @param bool|callable(): bool $isAssigned a callable is only invoked when
	 *        the answer actually depends on it — it costs a query per user
	 */
	public static function shouldNotify(string $deckSetting, bool $isOwnerOfUnsharedBoard, bool|callable $isAssigned): bool {
		if (!in_array($deckSetting, [self::DECK_OFF, self::DECK_ASSIGNED, self::DECK_ALL], true)) {
			$deckSetting = self::DECK_DEFAULT;
		}

		if ($deckSetting === self::DECK_OFF) {
			return false;
		}
		if ($deckSetting === self::DECK_ALL || $isOwnerOfUnsharedBoard) {
			return true;
		}

		return is_callable($isAssigned) ? (bool)$isAssigned() : $isAssigned;
	}
}