feat: make card events compatible with webhook listener

docs/events.md

@@ -0,0 +1,65 @@
+<!--
+  - SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+## Webhook Events
+
+Currently, Deck sends the following events that can be received by the [`webhook_listener`](https://docs.nextcloud.com/server/latest/admin_manual/webhook_listeners/index.html) app for Nextcloud Flow automations:
+
+### `CardCreatedEvent`
+
+Fired when a new card is created. Payload:
+
+```text
+{
+  "title": string,
+  "description": string,
+  "boardId": int,
+  "stackId": int,
+  "lastModified": string,
+  "createdAt": string
+  "labels": [
+    {
+      "id": int,
+      "title": string
+    },
+  ],
+  "assignedUsers": string[],
+  "order": int,
+  "archived": bool,
+  "commentsUnread": int,
+  "commentsCount": int,
+  "owner": string | null,
+  "lastEditor": string | null,
+  "duedate": string | null,
+  "doneAt": string | null,
+  "deletedAt": string | null
+}
+```
+
+Note: All timestamps are in ISO8601 format: `2025-01-11T12:34:56+00:00`
+
+### `CardUpdatedEvent`
+
+Fired when a card is changed. Contains the values before and after the update. Payload:
+
+```text
+{
+    "before": {
+        //...same format as CardCreatedEvent...
+    },
+    "after": {
+        //...same format as CardCreatedEvent...
+    }
+}
+```
+
+### `CardDeletedEvent`
+
+Fired when a card is deleted. Payload:
+
+```text
+{
+    //...same as CardCreatedEvent...
+}
+```

lib/Db/Card.php

@@ -11,6 +11,7 @@
 
 use DateTime;
 use DateTimeZone;
+use OCA\Deck\Model\Public\CardEventData;
 use Sabre\VObject\Component\VCalendar;
 
 /**
@@ -175,4 +176,31 @@ public function getCalendarPrefix(): string {
 	public function getETag(): string {
 		return md5((string)$this->getLastModified());
 	}
+
+	public function toEventData(): CardEventData {
+		return new CardEventData(
+			title: $this->getTitle(),
+			description: $this->getDescription(),
+			boardId: $this->getRelatedBoard()->getId(),
+			stackId: $this->getStackId(),
+			lastModified: new DateTime('@' . $this->getLastModified()),
+			createdAt: new DateTime('@' . $this->getCreatedAt()),
+			labels: array_map(fn ($label) => [
+				'id' => $label->getId(),
+				'title' => $label->getTitle()
+			], $this->getLabels() ?? []),
+			assignedUsers: $this->getAssignedUsers() ? array_map(fn ($user) => $user->getUID(), $this->getAssignedUsers()) : [],
+			order: $this->getOrder(),
+			archived: $this->getArchived(),
+			commentsUnread: $this->getCommentsUnread(),
+			commentsCount: $this->getCommentsCount(),
+			owner: $this->getOwner(),
+			lastEditor: $this->getLastEditor(),
+			duedate: $this->getDuedate(),
+			doneAt: $this->getDone(),
+			deletedAt: ($this->getDeletedAt() > 0)
+				? new DateTime('@' . $this->getDeletedAt())
+				: null
+		);
+	}
 }

lib/Event/CardCreatedEvent.php

@@ -10,5 +10,10 @@
 
 namespace OCA\Deck\Event;
 
-class CardCreatedEvent extends ACardEvent {
+use OCP\EventDispatcher\IWebhookCompatibleEvent;
+
+class CardCreatedEvent extends ACardEvent implements IWebhookCompatibleEvent {
+	public function getWebhookSerializable(): array {
+		return $this->getCard()->toEventData()->jsonSerialize();
+	}
 }

lib/Event/CardDeletedEvent.php

@@ -10,5 +10,11 @@
 
 namespace OCA\Deck\Event;
 
-class CardDeletedEvent extends ACardEvent {
+use OCP\EventDispatcher\IWebhookCompatibleEvent;
+
+class CardDeletedEvent extends ACardEvent implements IWebhookCompatibleEvent {
+
+	public function getWebhookSerializable(): array {
+		return $this->getCard()->toEventData()->jsonSerialize();
+	}
 }

lib/Event/CardUpdatedEvent.php

@@ -11,8 +11,9 @@
 namespace OCA\Deck\Event;
 
 use OCA\Deck\Db\Card;
+use OCP\EventDispatcher\IWebhookCompatibleEvent;
 
-class CardUpdatedEvent extends ACardEvent {
+class CardUpdatedEvent extends ACardEvent implements IWebhookCompatibleEvent {
 	private $cardBefore;
 
 	public function __construct(Card $card, ?Card $before = null) {
@@ -23,4 +24,11 @@ public function __construct(Card $card, ?Card $before = null) {
 	public function getCardBefore() {
 		return $this->cardBefore;
 	}
+
+	public function getWebhookSerializable(): array {
+		return [
+			'before' => $this->getCardBefore()->toEventData()->jsonSerialize(),
+			'after' => $this->getCard()->toEventData()->jsonSerialize()
+		];
+	}
 }

lib/Model/Public/CardEventData.php

@@ -0,0 +1,124 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Deck\Model\Public;
+
+use JsonSerializable;
+
+/**
+ * A data transfer object representation of the card data to be used as a
+ * public-facing event payload.
+ *
+ * @since 2.0.0
+ */
+final class CardEventData implements JsonSerializable {
+
+	/**
+	 * @param string $title
+	 * @param string $description
+	 * @param int $boardId
+	 * @param int $stackId
+	 * @param \DateTime $lastModified
+	 * @param \DateTime $createdAt
+	 * @param array<array{ id: int, title: string }> $labels
+	 * @param string[] $assignedUsers
+	 * @param int $order
+	 * @param bool $archived
+	 * @param int $commentsUnread
+	 * @param int $commentsCount
+	 * @param ?string $owner
+	 * @param ?string $lastEditor
+	 * @param ?\DateTime $duedate
+	 * @param ?\DateTime $doneAt
+	 * @param ?\DateTime $deletedAt
+	 *
+	 * @since 2.0.0
+	 */
+	public function __construct(
+		/** @readonly */
+		public string $title,
+		/** @readonly */
+		public string $description,
+		/** @readonly */
+		public int $boardId,
+		/** @readonly */
+		public int $stackId,
+		/** @readonly */
+		public \DateTime $lastModified,
+		/** @readonly */
+		public \DateTime $createdAt,
+		/** @readonly */
+		public array $labels = [],
+		/** @readonly */
+		public array $assignedUsers = [],
+		/** @readonly */
+		public int $order = 0,
+		/** @readonly */
+		public bool $archived = false,
+		/** @readonly */
+		public int $commentsUnread = 0,
+		/** @readonly */
+		public int $commentsCount = 0,
+		/** @readonly */
+		public ?string $owner = null,
+		/** @readonly */
+		public ?string $lastEditor,
+		/** @readonly */
+		public ?\DateTime $duedate = null,
+		/** @readonly */
+		public ?\DateTime $doneAt = null,
+		/** @readonly */
+		public ?\DateTime $deletedAt = null,
+	) {
+	}
+
+
+	/**
+	 * Serialize the object to a JSON-compatible array.
+	 *
+	 * @return array{
+	 *     title: string,
+	 *     description: string,
+	 *     boardId: int,
+	 *     stackId: int,
+	 *     lastModified: string,
+	 *     createdAt: string,
+	 *     labels: array<array{id: int, title: string}>,
+	 *     assignedUsers: string[],
+	 *     order: int,
+	 *     archived: bool,
+	 *     commentsUnread: int,
+	 *     commentsCount: int,
+	 *     owner: ?string,
+	 *     lastEditor: ?string,
+	 *     duedate: ?string,
+	 *     doneAt: ?string,
+	 *     deletedAt: ?string,
+	 * }
+	 */
+	public function jsonSerialize(): array {
+		return [
+			'title' => $this->title,
+			'description' => $this->description,
+			'boardId' => $this->boardId,
+			'stackId' => $this->stackId,
+			'lastModified' => $this->lastModified->format(DATE_ATOM),
+			'createdAt' => $this->createdAt->format(DATE_ATOM),
+			'labels' => $this->labels,
+			'assignedUsers' => $this->assignedUsers,
+			'order' => $this->order,
+			'archived' => $this->archived,
+			'commentsUnread' => $this->commentsUnread,
+			'commentsCount' => $this->commentsCount,
+			'owner' => $this->owner,
+			'lastEditor' => $this->lastEditor,
+			'duedate' => $this->duedate?->format(DATE_ATOM),
+			'doneAt' => $this->doneAt?->format(DATE_ATOM),
+			'deletedAt' => $this->deletedAt?->format(DATE_ATOM),
+		];
+	}
+}