feat: add Planka service provider with full notification and command support

Webhook-based provider for Planka (self-hosted Kanban board) with: - 15 event types (cards, boards, lists, comments, tasks, attachments, labels) - Bearer token webhook authentication - Async API client for boards/cards/lists - 30 notification templates (en/ru) + 26 command templates (en/ru) - Bot commands: /status, /boards, /cards, /lists - Default tracking config, template config, command config seeded on startup - DB migration for 15 new tracking_config columns - Frontend: provider config UI with auto-name, Planka-specific hints - Frontend: tracking config event toggles for all 15 Planka events
2026-03-23 15:54:00 +03:00
parent 39bac828fd
commit 0fde3c6b3d
83 changed files with 1827 additions and 3 deletions
@@ -32,6 +32,23 @@ class EventType(str, Enum):
    PR_COMMENTED = "pr_commented"
    RELEASE_PUBLISHED = "release_published"

+    # Planka events
+    CARD_CREATED = "card_created"
+    CARD_UPDATED = "card_updated"
+    CARD_MOVED = "card_moved"
+    CARD_DELETED = "card_deleted"
+    CARD_COMMENTED = "card_commented"
+    COMMENT_UPDATED = "comment_updated"
+    BOARD_CREATED = "board_created"
+    BOARD_UPDATED = "board_updated"
+    BOARD_DELETED = "board_deleted"
+    LIST_CREATED = "list_created"
+    LIST_UPDATED = "list_updated"
+    LIST_DELETED = "list_deleted"
+    ATTACHMENT_CREATED = "attachment_created"
+    CARD_LABEL_ADDED = "card_label_added"
+    TASK_COMPLETED = "task_completed"
+
    # Scheduler events
    SCHEDULED_MESSAGE = "scheduled_message"

@@ -16,6 +16,7 @@ class ServiceProviderType(str, Enum):

    IMMICH = "immich"
    GITEA = "gitea"
+    PLANKA = "planka"
    SCHEDULER = "scheduler"


@@ -216,6 +216,80 @@ SCHEDULER_CAPABILITIES = ProviderCapabilities(
    commands=[],
 )

+# ---------------------------------------------------------------------------
+# Planka provider capabilities
+# ---------------------------------------------------------------------------
+
+PLANKA_CAPABILITIES = ProviderCapabilities(
+    provider_type="planka",
+    display_name="Planka",
+    webhook_based=True,
+    supported_filters=[
+        {
+            "key": "collections",
+            "label": "Boards",
+            "type": "select",
+            "source": "api",
+        },
+    ],
+    notification_slots=[
+        {"name": "message_card_created", "description": "Card created"},
+        {"name": "message_card_updated", "description": "Card updated"},
+        {"name": "message_card_moved", "description": "Card moved between lists"},
+        {"name": "message_card_deleted", "description": "Card deleted"},
+        {"name": "message_card_commented", "description": "Comment added to card"},
+        {"name": "message_comment_updated", "description": "Comment updated"},
+        {"name": "message_board_created", "description": "Board created"},
+        {"name": "message_board_updated", "description": "Board updated"},
+        {"name": "message_board_deleted", "description": "Board deleted"},
+        {"name": "message_list_created", "description": "List created"},
+        {"name": "message_list_updated", "description": "List updated"},
+        {"name": "message_list_deleted", "description": "List deleted"},
+        {"name": "message_attachment_created", "description": "Attachment added to card"},
+        {"name": "message_card_label_added", "description": "Label added to card"},
+        {"name": "message_task_completed", "description": "Task completed"},
+    ],
+    events=[
+        {"name": "card_created", "description": "Card created"},
+        {"name": "card_updated", "description": "Card updated"},
+        {"name": "card_moved", "description": "Card moved between lists"},
+        {"name": "card_deleted", "description": "Card deleted"},
+        {"name": "card_commented", "description": "Comment added to card"},
+        {"name": "comment_updated", "description": "Comment updated"},
+        {"name": "board_created", "description": "Board created"},
+        {"name": "board_updated", "description": "Board updated"},
+        {"name": "board_deleted", "description": "Board deleted"},
+        {"name": "list_created", "description": "List created"},
+        {"name": "list_updated", "description": "List updated"},
+        {"name": "list_deleted", "description": "List deleted"},
+        {"name": "attachment_created", "description": "Attachment added"},
+        {"name": "card_label_added", "description": "Label added to card"},
+        {"name": "task_completed", "description": "Task completed"},
+    ],
+    command_slots=[
+        {"name": "start", "description": "/start greeting message"},
+        {"name": "help", "description": "/help command listing"},
+        {"name": "status", "description": "/status connection summary"},
+        {"name": "boards", "description": "/boards tracked boards"},
+        {"name": "cards", "description": "/cards recent cards"},
+        {"name": "lists", "description": "/lists board lists"},
+        {"name": "rate_limited", "description": "Rate limit warning message"},
+        {"name": "no_results", "description": "Empty results fallback"},
+        {"name": "desc_help", "description": "Menu description for /help"},
+        {"name": "desc_status", "description": "Menu description for /status"},
+        {"name": "desc_boards", "description": "Menu description for /boards"},
+        {"name": "desc_cards", "description": "Menu description for /cards"},
+        {"name": "desc_lists", "description": "Menu description for /lists"},
+    ],
+    commands=[
+        {"name": "status", "description": "Show connection status"},
+        {"name": "boards", "description": "List tracked boards"},
+        {"name": "cards", "description": "Recent cards"},
+        {"name": "lists", "description": "Board lists"},
+        {"name": "help", "description": "Show commands"},
+    ],
+)
+
 # ---------------------------------------------------------------------------
 # Registry
 # ---------------------------------------------------------------------------
@@ -223,6 +297,7 @@ SCHEDULER_CAPABILITIES = ProviderCapabilities(
 _REGISTRY: dict[str, ProviderCapabilities] = {
    "immich": IMMICH_CAPABILITIES,
    "gitea": GITEA_CAPABILITIES,
+    "planka": PLANKA_CAPABILITIES,
    "scheduler": SCHEDULER_CAPABILITIES,
 }

@@ -0,0 +1,19 @@
+"""Planka service provider implementation."""
+
+from notify_bridge_core.providers.base import ServiceProviderType
+from notify_bridge_core.templates.variables import registry
+
+from .client import PlankaClient, PlankaApiError
+from .event_parser import parse_webhook
+from .provider import PlankaServiceProvider, PLANKA_VARIABLES
+
+# Register Planka variables in the global registry
+registry.register_provider_variables(ServiceProviderType.PLANKA, PLANKA_VARIABLES)
+
+__all__ = [
+    "PlankaClient",
+    "PlankaApiError",
+    "PlankaServiceProvider",
+    "PLANKA_VARIABLES",
+    "parse_webhook",
+]
@@ -0,0 +1,101 @@
+"""Async Planka API client for connection testing and board/card listing."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class PlankaClient:
+    """Async client for the Planka REST API."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        api_key: str,
+    ) -> None:
+        self._session = session
+        self._url = url.rstrip("/")
+        self._api_key = api_key
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    async def ping(self) -> bool:
+        """Check connectivity via GET /api/boards."""
+        try:
+            async with self._session.get(
+                f"{self._url}/api/boards",
+                headers=self._headers,
+            ) as response:
+                return response.status == 200
+        except aiohttp.ClientError:
+            return False
+
+    async def get_boards(self) -> list[dict[str, Any]]:
+        """List all boards accessible to the authenticated user."""
+        try:
+            async with self._session.get(
+                f"{self._url}/api/boards",
+                headers=self._headers,
+            ) as response:
+                if response.status != 200:
+                    _LOGGER.warning("Failed to fetch boards: HTTP %s", response.status)
+                    return []
+                data = await response.json()
+                # Planka returns {"items": [...]} or a list directly
+                if isinstance(data, dict):
+                    return data.get("items", data.get("boards", []))
+                return data if isinstance(data, list) else []
+        except aiohttp.ClientError as err:
+            _LOGGER.warning("Failed to fetch boards: %s", err)
+            return []
+
+    async def get_board_lists(self, board_id: str) -> list[dict[str, Any]]:
+        """Fetch lists for a board."""
+        try:
+            async with self._session.get(
+                f"{self._url}/api/boards/{board_id}",
+                headers=self._headers,
+            ) as response:
+                if response.status != 200:
+                    _LOGGER.warning("Failed to fetch board %s: HTTP %s", board_id, response.status)
+                    return []
+                data = await response.json()
+                included = data.get("included", {})
+                return included.get("lists", [])
+        except aiohttp.ClientError as err:
+            _LOGGER.warning("Failed to fetch board %s: %s", board_id, err)
+            return []
+
+    async def get_board_cards(self, board_id: str, limit: int = 20) -> list[dict[str, Any]]:
+        """Fetch cards for a board."""
+        try:
+            async with self._session.get(
+                f"{self._url}/api/boards/{board_id}",
+                headers=self._headers,
+            ) as response:
+                if response.status != 200:
+                    _LOGGER.warning("Failed to fetch board %s: HTTP %s", board_id, response.status)
+                    return []
+                data = await response.json()
+                included = data.get("included", {})
+                cards = included.get("cards", [])
+                return cards[:limit]
+        except aiohttp.ClientError as err:
+            _LOGGER.warning("Failed to fetch board %s cards: %s", board_id, err)
+            return []
+
+
+class PlankaApiError(Exception):
+    """Raised when a Planka API call fails."""
@@ -0,0 +1,373 @@
+"""Parse Planka webhook payloads into ServiceEvent objects."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from notify_bridge_core.models.events import EventType, ServiceEvent
+from notify_bridge_core.providers.base import ServiceProviderType
+
+from .models import (
+    PlankaAttachment,
+    PlankaBoard,
+    PlankaCard,
+    PlankaComment,
+    PlankaLabel,
+    PlankaList,
+    PlankaTask,
+    PlankaUser,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+# Map Planka event types to our EventType.
+# cardUpdate is refined by beforeUpdate/afterUpdate.
+_PLANKA_EVENT_MAP: dict[str, EventType | None] = {
+    "cardCreate": EventType.CARD_CREATED,
+    "cardUpdate": None,  # refined: CARD_MOVED, CARD_UPDATED
+    "cardDelete": EventType.CARD_DELETED,
+    "commentCreate": EventType.CARD_COMMENTED,
+    "commentUpdate": EventType.COMMENT_UPDATED,
+    "boardCreate": EventType.BOARD_CREATED,
+    "boardUpdate": EventType.BOARD_UPDATED,
+    "boardDelete": EventType.BOARD_DELETED,
+    "listCreate": EventType.LIST_CREATED,
+    "listUpdate": EventType.LIST_UPDATED,
+    "listDelete": EventType.LIST_DELETED,
+    "attachmentCreate": EventType.ATTACHMENT_CREATED,
+    "cardMembershipCreate": EventType.CARD_LABEL_ADDED,
+    "taskUpdate": None,  # refined: TASK_COMPLETED only
+}
+
+
+def parse_webhook(
+    event_type: str,
+    payload: dict[str, Any],
+    provider_name: str,
+    base_url: str = "",
+) -> ServiceEvent | None:
+    """Parse a Planka webhook payload into a ServiceEvent.
+
+    Args:
+        event_type: The event type string from the webhook payload.
+        payload: Parsed JSON body of the webhook.
+        provider_name: Display name of the ServiceProvider instance.
+        base_url: Base URL for building card/board links.
+
+    Returns:
+        A ServiceEvent, or None if the event is not tracked.
+    """
+    if event_type not in _PLANKA_EVENT_MAP:
+        _LOGGER.debug("Ignoring untracked Planka event: %s", event_type)
+        return None
+
+    resolved_type = _resolve_event_type(event_type, payload)
+    if resolved_type is None:
+        _LOGGER.debug("Ignoring Planka event %s (not mapped)", event_type)
+        return None
+
+    user_data = payload.get("user", {})
+    user = PlankaUser.from_payload(user_data) if user_data else None
+
+    extra = _build_extra(event_type, resolved_type, payload, user, base_url)
+
+    # Determine collection (board) info
+    board_id = extra.get("board_id", "")
+    board_name = extra.get("board_name", "")
+
+    return ServiceEvent(
+        event_type=resolved_type,
+        provider_type=ServiceProviderType.PLANKA,
+        provider_name=provider_name,
+        collection_id=board_id,
+        collection_name=board_name,
+        timestamp=datetime.now(timezone.utc),
+        extra=extra,
+    )
+
+
+def _resolve_event_type(
+    event_type: str, payload: dict[str, Any],
+) -> EventType | None:
+    """Determine the EventType from event string + payload details."""
+    direct = _PLANKA_EVENT_MAP.get(event_type)
+    if direct is not None:
+        return direct
+
+    if event_type == "cardUpdate":
+        return _resolve_card_update(payload)
+
+    if event_type == "taskUpdate":
+        return _resolve_task_update(payload)
+
+    return None
+
+
+def _resolve_card_update(payload: dict[str, Any]) -> EventType | None:
+    """Determine if a cardUpdate is a move, completion, or general update."""
+    before = payload.get("beforeUpdate", {})
+    after = payload.get("afterUpdate", payload.get("item", {}))
+
+    # List change = card moved
+    old_list_id = before.get("listId")
+    new_list_id = after.get("listId")
+    if old_list_id and new_list_id and old_list_id != new_list_id:
+        return EventType.CARD_MOVED
+
+    return EventType.CARD_UPDATED
+
+
+def _resolve_task_update(payload: dict[str, Any]) -> EventType | None:
+    """Only emit TASK_COMPLETED when a task becomes completed."""
+    item = payload.get("item", {})
+    before = payload.get("beforeUpdate", {})
+
+    if item.get("isCompleted") and not before.get("isCompleted", True):
+        return EventType.TASK_COMPLETED
+
+    return None
+
+
+def _build_extra(
+    event_type: str,
+    resolved_type: EventType,
+    payload: dict[str, Any],
+    user: PlankaUser | None,
+    base_url: str,
+) -> dict[str, Any]:
+    """Build the provider-specific extra dict for template rendering."""
+    extra: dict[str, Any] = {}
+
+    if user:
+        extra["sender"] = user.username
+        extra["sender_name"] = user.name or user.username
+
+    item = payload.get("item", {})
+
+    if resolved_type in (
+        EventType.CARD_CREATED, EventType.CARD_UPDATED,
+        EventType.CARD_MOVED, EventType.CARD_DELETED,
+    ):
+        _enrich_card(extra, item, payload, base_url)
+
+    elif resolved_type in (EventType.CARD_COMMENTED, EventType.COMMENT_UPDATED):
+        _enrich_comment(extra, item, payload, base_url)
+
+    elif resolved_type in (
+        EventType.BOARD_CREATED, EventType.BOARD_UPDATED, EventType.BOARD_DELETED,
+    ):
+        _enrich_board(extra, item, base_url)
+
+    elif resolved_type in (
+        EventType.LIST_CREATED, EventType.LIST_UPDATED, EventType.LIST_DELETED,
+    ):
+        _enrich_list(extra, item, payload, base_url)
+
+    elif resolved_type == EventType.ATTACHMENT_CREATED:
+        _enrich_attachment(extra, item, payload, base_url)
+
+    elif resolved_type == EventType.CARD_LABEL_ADDED:
+        _enrich_label(extra, item, payload, base_url)
+
+    elif resolved_type == EventType.TASK_COMPLETED:
+        _enrich_task(extra, item, payload, base_url)
+
+    return extra
+
+
+def _enrich_card(
+    extra: dict[str, Any], item: dict[str, Any],
+    payload: dict[str, Any], base_url: str,
+) -> None:
+    card = PlankaCard.from_payload(item)
+    extra["card_name"] = card.name
+    extra["card_id"] = card.id
+    extra["card_description"] = card.description
+    extra["card_due_date"] = card.due_date
+    extra["board_id"] = card.board_id
+    extra["list_id"] = card.list_id
+
+    if base_url:
+        extra["card_url"] = f"{base_url}/cards/{card.id}"
+
+    # Resolve board and list names from included data
+    included = payload.get("included", {})
+    _resolve_board_name(extra, card.board_id, included)
+    _resolve_list_name(extra, card.list_id, included)
+
+    # For card moves, resolve old/new list names
+    before = payload.get("beforeUpdate", {})
+    old_list_id = before.get("listId")
+    new_list_id = item.get("listId")
+    if old_list_id and new_list_id and old_list_id != new_list_id:
+        extra["old_list_id"] = str(old_list_id)
+        extra["new_list_id"] = str(new_list_id)
+        _resolve_old_new_list_names(extra, old_list_id, new_list_id, included)
+
+
+def _enrich_comment(
+    extra: dict[str, Any], item: dict[str, Any],
+    payload: dict[str, Any], base_url: str,
+) -> None:
+    comment = PlankaComment.from_payload(item)
+    extra["comment_text"] = comment.text
+    extra["comment_id"] = comment.id
+
+    # Resolve card info from included
+    included = payload.get("included", {})
+    card_data = included.get("card", item)
+    card_id = str(comment.card_id or card_data.get("id", ""))
+    if card_id:
+        extra["card_id"] = card_id
+        extra["card_name"] = card_data.get("name", "")
+        if base_url:
+            extra["card_url"] = f"{base_url}/cards/{card_id}"
+
+    board_id = str(card_data.get("boardId", ""))
+    extra["board_id"] = board_id
+    _resolve_board_name(extra, board_id, included)
+
+
+def _enrich_board(
+    extra: dict[str, Any], item: dict[str, Any], base_url: str,
+) -> None:
+    board = PlankaBoard.from_payload(item)
+    extra["board_name"] = board.name
+    extra["board_id"] = board.id
+    if base_url:
+        extra["board_url"] = f"{base_url}/boards/{board.id}"
+
+
+def _enrich_list(
+    extra: dict[str, Any], item: dict[str, Any],
+    payload: dict[str, Any], base_url: str,
+) -> None:
+    lst = PlankaList.from_payload(item)
+    extra["list_name"] = lst.name
+    extra["list_id"] = lst.id
+    extra["board_id"] = lst.board_id
+
+    included = payload.get("included", {})
+    _resolve_board_name(extra, lst.board_id, included)
+
+
+def _enrich_attachment(
+    extra: dict[str, Any], item: dict[str, Any],
+    payload: dict[str, Any], base_url: str,
+) -> None:
+    attachment = PlankaAttachment.from_payload(item)
+    extra["attachment_name"] = attachment.name
+    extra["attachment_id"] = attachment.id
+    extra["card_id"] = attachment.card_id
+
+    included = payload.get("included", {})
+    card_data = included.get("card", {})
+    extra["card_name"] = card_data.get("name", "")
+    board_id = str(card_data.get("boardId", ""))
+    extra["board_id"] = board_id
+    _resolve_board_name(extra, board_id, included)
+
+    if base_url and attachment.card_id:
+        extra["card_url"] = f"{base_url}/cards/{attachment.card_id}"
+
+
+def _enrich_label(
+    extra: dict[str, Any], item: dict[str, Any],
+    payload: dict[str, Any], base_url: str,
+) -> None:
+    # cardMembershipCreate: item is the membership; label info in included
+    included = payload.get("included", {})
+    label_data = included.get("label", item)
+    label = PlankaLabel.from_payload(label_data)
+    extra["label_name"] = label.name
+    extra["label_color"] = label.color
+
+    card_data = included.get("card", {})
+    extra["card_id"] = str(card_data.get("id", item.get("cardId", "")))
+    extra["card_name"] = card_data.get("name", "")
+
+    board_id = str(card_data.get("boardId", label.board_id))
+    extra["board_id"] = board_id
+    _resolve_board_name(extra, board_id, included)
+
+    if base_url and extra.get("card_id"):
+        extra["card_url"] = f"{base_url}/cards/{extra['card_id']}"
+
+
+def _enrich_task(
+    extra: dict[str, Any], item: dict[str, Any],
+    payload: dict[str, Any], base_url: str,
+) -> None:
+    task = PlankaTask.from_payload(item)
+    extra["task_name"] = task.name
+    extra["task_id"] = task.id
+    extra["task_completed"] = task.is_completed
+    extra["card_id"] = task.card_id
+
+    included = payload.get("included", {})
+    card_data = included.get("card", {})
+    extra["card_name"] = card_data.get("name", "")
+
+    board_id = str(card_data.get("boardId", ""))
+    extra["board_id"] = board_id
+    _resolve_board_name(extra, board_id, included)
+
+    if base_url and task.card_id:
+        extra["card_url"] = f"{base_url}/cards/{task.card_id}"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_board_name(
+    extra: dict[str, Any], board_id: str, included: dict[str, Any],
+) -> None:
+    """Try to set board_name from included data."""
+    if "board_name" in extra and extra["board_name"]:
+        return
+    board_data = included.get("board", {})
+    if str(board_data.get("id", "")) == board_id:
+        extra["board_name"] = board_data.get("name", "")
+    elif not extra.get("board_name"):
+        extra["board_name"] = ""
+
+
+def _resolve_list_name(
+    extra: dict[str, Any], list_id: str, included: dict[str, Any],
+) -> None:
+    """Try to set list_name from included data."""
+    lists = included.get("lists", [])
+    if isinstance(lists, list):
+        for lst in lists:
+            if str(lst.get("id", "")) == list_id:
+                extra["list_name"] = lst.get("name", "")
+                return
+    elif isinstance(lists, dict) and str(lists.get("id", "")) == list_id:
+        extra["list_name"] = lists.get("name", "")
+        return
+    if "list_name" not in extra:
+        extra["list_name"] = ""
+
+
+def _resolve_old_new_list_names(
+    extra: dict[str, Any],
+    old_list_id: Any,
+    new_list_id: Any,
+    included: dict[str, Any],
+) -> None:
+    """Resolve old_list_name and new_list_name for card moves."""
+    old_id = str(old_list_id)
+    new_id = str(new_list_id)
+    lists = included.get("lists", [])
+    if isinstance(lists, list):
+        for lst in lists:
+            lid = str(lst.get("id", ""))
+            if lid == old_id:
+                extra["old_list_name"] = lst.get("name", "")
+            if lid == new_id:
+                extra["new_list_name"] = lst.get("name", "")
+    extra.setdefault("old_list_name", "")
+    extra.setdefault("new_list_name", "")
@@ -0,0 +1,164 @@
+"""Planka webhook payload data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PlankaUser:
+    """Planka user from webhook payload."""
+
+    id: str
+    username: str
+    name: str = ""
+    email: str = ""
+
+    @classmethod
+    def from_payload(cls, data: dict[str, Any]) -> PlankaUser:
+        return cls(
+            id=str(data.get("id", "")),
+            username=data.get("username", ""),
+            name=data.get("name", ""),
+            email=data.get("email", ""),
+        )
+
+
+@dataclass
+class PlankaBoard:
+    """Planka board from webhook payload."""
+
+    id: str
+    name: str
+    position: int = 0
+
+    @classmethod
+    def from_payload(cls, data: dict[str, Any]) -> PlankaBoard:
+        return cls(
+            id=str(data.get("id", "")),
+            name=data.get("name", ""),
+            position=data.get("position", 0),
+        )
+
+
+@dataclass
+class PlankaList:
+    """Planka list from webhook payload."""
+
+    id: str
+    name: str
+    position: int = 0
+    board_id: str = ""
+
+    @classmethod
+    def from_payload(cls, data: dict[str, Any]) -> PlankaList:
+        return cls(
+            id=str(data.get("id", "")),
+            name=data.get("name", ""),
+            position=data.get("position", 0),
+            board_id=str(data.get("boardId", "")),
+        )
+
+
+@dataclass
+class PlankaCard:
+    """Planka card from webhook payload."""
+
+    id: str
+    name: str
+    description: str = ""
+    position: int = 0
+    board_id: str = ""
+    list_id: str = ""
+    due_date: str = ""
+    is_completed: bool = False
+
+    @classmethod
+    def from_payload(cls, data: dict[str, Any]) -> PlankaCard:
+        return cls(
+            id=str(data.get("id", "")),
+            name=data.get("name", ""),
+            description=data.get("description", "") or "",
+            position=data.get("position", 0),
+            board_id=str(data.get("boardId", "")),
+            list_id=str(data.get("listId", "")),
+            due_date=data.get("dueDate", "") or "",
+            is_completed=data.get("isCompleted", False),
+        )
+
+
+@dataclass
+class PlankaComment:
+    """Planka comment (action) from webhook payload."""
+
+    id: str
+    text: str
+    card_id: str = ""
+    user_id: str = ""
+
+    @classmethod
+    def from_payload(cls, data: dict[str, Any]) -> PlankaComment:
+        return cls(
+            id=str(data.get("id", "")),
+            text=data.get("text", data.get("data", {}).get("text", "")),
+            card_id=str(data.get("cardId", "")),
+            user_id=str(data.get("userId", "")),
+        )
+
+
+@dataclass
+class PlankaTask:
+    """Planka task (checklist item) from webhook payload."""
+
+    id: str
+    name: str
+    is_completed: bool = False
+    card_id: str = ""
+
+    @classmethod
+    def from_payload(cls, data: dict[str, Any]) -> PlankaTask:
+        return cls(
+            id=str(data.get("id", "")),
+            name=data.get("name", ""),
+            is_completed=data.get("isCompleted", False),
+            card_id=str(data.get("cardId", "")),
+        )
+
+
+@dataclass
+class PlankaAttachment:
+    """Planka attachment from webhook payload."""
+
+    id: str
+    name: str
+    card_id: str = ""
+    url: str = ""
+
+    @classmethod
+    def from_payload(cls, data: dict[str, Any]) -> PlankaAttachment:
+        return cls(
+            id=str(data.get("id", "")),
+            name=data.get("name", data.get("filename", "")),
+            card_id=str(data.get("cardId", "")),
+            url=data.get("url", ""),
+        )
+
+
+@dataclass
+class PlankaLabel:
+    """Planka label from webhook payload."""
+
+    id: str
+    name: str
+    color: str = ""
+    board_id: str = ""
+
+    @classmethod
+    def from_payload(cls, data: dict[str, Any]) -> PlankaLabel:
+        return cls(
+            id=str(data.get("id", "")),
+            name=data.get("name", ""),
+            color=data.get("color", ""),
+            board_id=str(data.get("boardId", "")),
+        )
@@ -0,0 +1,236 @@
+"""Planka service provider — webhook-based implementation of ServiceProvider."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+
+from notify_bridge_core.models.events import ServiceEvent
+from notify_bridge_core.providers.base import ServiceProvider, ServiceProviderType
+from notify_bridge_core.templates.variables import TemplateVariableDefinition
+
+from .client import PlankaClient
+
+_LOGGER = logging.getLogger(__name__)
+
+
+# Planka-specific template variables
+PLANKA_VARIABLES: list[TemplateVariableDefinition] = [
+    TemplateVariableDefinition(
+        name="sender",
+        type="string",
+        description="Username of the user who triggered the event",
+        example="alexei",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="sender_name",
+        type="string",
+        description="Display name of the sender",
+        example="Alexei",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="board_name",
+        type="string",
+        description="Board name",
+        example="My Project",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="board_id",
+        type="string",
+        description="Board ID",
+        example="123456",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="board_url",
+        type="string",
+        description="URL to the board",
+        example="https://planka.example.com/boards/123456",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="card_name",
+        type="string",
+        description="Card name",
+        example="Fix login bug",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="card_id",
+        type="string",
+        description="Card ID",
+        example="789012",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="card_url",
+        type="string",
+        description="URL to the card",
+        example="https://planka.example.com/cards/789012",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="card_description",
+        type="string",
+        description="Card description text",
+        example="Users cannot log in with SSO",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="card_due_date",
+        type="string",
+        description="Card due date (if set)",
+        example="2026-04-01T00:00:00.000Z",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="list_name",
+        type="string",
+        description="Current list name",
+        example="In Progress",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="old_list_name",
+        type="string",
+        description="Previous list name (card move events)",
+        example="To Do",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="new_list_name",
+        type="string",
+        description="New list name (card move events)",
+        example="In Progress",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="comment_text",
+        type="string",
+        description="Comment body text",
+        example="Looks good, ready for review!",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="task_name",
+        type="string",
+        description="Task/checklist item name",
+        example="Write unit tests",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="task_completed",
+        type="bool",
+        description="Whether the task is completed",
+        example="true",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="attachment_name",
+        type="string",
+        description="Attachment filename",
+        example="screenshot.png",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="label_name",
+        type="string",
+        description="Label name",
+        example="bug",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+    TemplateVariableDefinition(
+        name="label_color",
+        type="string",
+        description="Label color",
+        example="berry-red",
+        provider_type=ServiceProviderType.PLANKA,
+    ),
+]
+
+
+class PlankaServiceProvider(ServiceProvider):
+    """Planka webhook-based provider.
+
+    Like Gitea, Planka pushes events to us via webhooks.
+    The poll() method is a no-op — events are parsed from incoming
+    webhook payloads by event_parser.parse_webhook().
+    """
+
+    provider_type = ServiceProviderType.PLANKA
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        api_key: str,
+        name: str = "Planka",
+    ) -> None:
+        self._client = PlankaClient(session, url, api_key)
+        self._name = name
+
+    @property
+    def client(self) -> PlankaClient:
+        return self._client
+
+    async def connect(self) -> bool:
+        return await self._client.ping()
+
+    async def disconnect(self) -> None:
+        pass  # session lifecycle managed by caller
+
+    async def poll(
+        self,
+        collection_ids: list[str],
+        tracker_state: dict[str, Any],
+    ) -> tuple[list[ServiceEvent], dict[str, Any]]:
+        # Planka is webhook-based — poll() is not used.
+        # Events arrive via the /api/webhooks/planka route.
+        return [], tracker_state
+
+    def get_available_variables(self) -> list[TemplateVariableDefinition]:
+        return list(PLANKA_VARIABLES)
+
+    def get_provider_config_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "Planka server URL",
+                    "example": "https://planka.example.com",
+                },
+                "api_key": {
+                    "type": "string",
+                    "description": "Planka API key or JWT token (for API access)",
+                    "secret": True,
+                },
+                "webhook_secret": {
+                    "type": "string",
+                    "description": "Bearer token used by Planka for webhook authentication",
+                    "secret": True,
+                },
+            },
+            "required": ["url", "webhook_secret"],
+        }
+
+    async def list_collections(self) -> list[dict[str, Any]]:
+        boards = await self._client.get_boards()
+        return [
+            {
+                "id": str(b.get("id", "")),
+                "name": b.get("name", ""),
+            }
+            for b in boards
+        ]
+
+    async def test_connection(self) -> dict[str, Any]:
+        ok = await self._client.ping()
+        if ok:
+            return {"ok": True, "message": "Connected to Planka"}
+        return {"ok": False, "message": "Failed to connect to Planka"}
@@ -0,0 +1,7 @@
+📌 <b>Tracked Boards</b>
+{%- for board in boards %}
+• <b>{{ board.name }}</b>
+{%- endfor %}
+{%- if not boards %}
+No boards tracked.
+{%- endif %}
@@ -0,0 +1,7 @@
+📋 <b>Recent Cards</b>
+{%- for card in cards %}
+• <b>{{ card.name }}</b>{% if card.list_name %} [{{ card.list_name }}]{% endif %}{% if card.board_name %} — {{ card.board_name }}{% endif %}
+{%- endfor %}
+{%- if not cards %}
+No cards found.
+{%- endif %}
@@ -0,0 +1 @@
+List tracked boards
@@ -0,0 +1 @@
+Show recent cards
@@ -0,0 +1 @@
+Show available commands
@@ -0,0 +1 @@
+Show board lists
@@ -0,0 +1 @@
+Show Planka connection status
@@ -0,0 +1,4 @@
+📋 <b>Available Commands</b>
+{%- for cmd in commands %}
+/{{ cmd.name }} — {{ cmd.description }}
+{%- endfor %}
@@ -0,0 +1,7 @@
+📝 <b>Board Lists</b>
+{%- for lst in lists %}
+• <b>{{ lst.name }}</b>{% if lst.board_name %} — {{ lst.board_name }}{% endif %}
+{%- endfor %}
+{%- if not lists %}
+No lists found.
+{%- endif %}
@@ -0,0 +1 @@
+🔍 No results found.
@@ -0,0 +1 @@
+⏳ Please wait {{ wait }}s before using this command again.
@@ -0,0 +1,2 @@
+👋 Hi! I'm your Notify Bridge bot for <b>Planka</b>.
+Use /help to see available commands.
@@ -0,0 +1,3 @@
+📊 <b>Planka Status</b>
+Boards tracked: {{ boards_count }}
+Last event: {{ last_event }}
@@ -32,6 +32,14 @@ PROVIDER_COMMAND_SLOTS: dict[str, list[str]] = {
        "desc_help", "desc_status", "desc_repos", "desc_issues",
        "desc_prs", "desc_commits",
    ],
+    "planka": [
+        # Response templates
+        "start", "help", "status", "boards", "cards", "lists",
+        "rate_limited", "no_results",
+        # Description slots
+        "desc_help", "desc_status", "desc_boards", "desc_cards",
+        "desc_lists",
+    ],
 }

 # Backward-compatible aliases
@@ -0,0 +1,7 @@
+📌 <b>Отслеживаемые доски</b>
+{%- for board in boards %}
+• <b>{{ board.name }}</b>
+{%- endfor %}
+{%- if not boards %}
+Нет отслеживаемых досок.
+{%- endif %}
@@ -0,0 +1,7 @@
+📋 <b>Последние карточки</b>
+{%- for card in cards %}
+• <b>{{ card.name }}</b>{% if card.list_name %} [{{ card.list_name }}]{% endif %}{% if card.board_name %} — {{ card.board_name }}{% endif %}
+{%- endfor %}
+{%- if not cards %}
+Карточки не найдены.
+{%- endif %}
@@ -0,0 +1 @@
+Список отслеживаемых досок
@@ -0,0 +1 @@
+Последние карточки
@@ -0,0 +1 @@
+Показать доступные команды
@@ -0,0 +1 @@
+Показать списки досок
@@ -0,0 +1 @@
+Показать статус Planka
@@ -0,0 +1,4 @@
+📋 <b>Доступные команды</b>
+{%- for cmd in commands %}
+/{{ cmd.name }} — {{ cmd.description }}
+{%- endfor %}
@@ -0,0 +1,7 @@
+📝 <b>Списки досок</b>
+{%- for lst in lists %}
+• <b>{{ lst.name }}</b>{% if lst.board_name %} — {{ lst.board_name }}{% endif %}
+{%- endfor %}
+{%- if not lists %}
+Списки не найдены.
+{%- endif %}
@@ -0,0 +1 @@
+🔍 Ничего не найдено.
@@ -0,0 +1 @@
+⏳ Подождите {{ wait }} сек. перед повторным использованием команды.
@@ -0,0 +1,2 @@
+👋 Привет! Я ваш бот Notify Bridge для <b>Planka</b>.
+Используйте /help для списка команд.
@@ -0,0 +1,3 @@
+📊 <b>Статус Planka</b>
+Отслеживаемые доски: {{ boards_count }}
+Последнее событие: {{ last_event }}
@@ -0,0 +1,5 @@
+📎 <b>{{ sender_name }}</b> attached <b>{{ attachment_name }}</b> to <b>{{ card_name }}</b>
+{%- if board_name %} in <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">View card</a>
+{%- endif %}
@@ -0,0 +1,4 @@
+📌 <b>{{ sender_name }}</b> created board <b>{{ board_name }}</b>
+{%- if board_url %}
+<a href="{{ board_url }}">View board</a>
+{%- endif %}
@@ -0,0 +1 @@
+🗑 <b>{{ sender_name }}</b> deleted board <b>{{ board_name }}</b>
@@ -0,0 +1,4 @@
+✏️ <b>{{ sender_name }}</b> updated board <b>{{ board_name }}</b>
+{%- if board_url %}
+<a href="{{ board_url }}">View board</a>
+{%- endif %}
@@ -0,0 +1,8 @@
+💬 <b>{{ sender_name }}</b> commented on <b>{{ card_name }}</b>
+{%- if board_name %} in <b>{{ board_name }}</b>{%- endif %}
+{%- if comment_text %}
+{{ comment_text | truncate(300) }}
+{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">View card</a>
+{%- endif %}
@@ -0,0 +1,9 @@
+📋 <b>{{ sender_name }}</b> created card <b>{{ card_name }}</b>
+{%- if board_name %} in board <b>{{ board_name }}</b>{%- endif %}
+{%- if list_name %} → {{ list_name }}{%- endif %}
+{%- if card_description %}
+{{ card_description | truncate(200) }}
+{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">View card</a>
+{%- endif %}
@@ -0,0 +1,2 @@
+🗑 <b>{{ sender_name }}</b> deleted card <b>{{ card_name }}</b>
+{%- if board_name %} from board <b>{{ board_name }}</b>{%- endif %}
@@ -0,0 +1,5 @@
+🏷 <b>{{ sender_name }}</b> added label <b>{{ label_name }}</b> to <b>{{ card_name }}</b>
+{%- if board_name %} in <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">View card</a>
+{%- endif %}
@@ -0,0 +1,6 @@
+➡️ <b>{{ sender_name }}</b> moved card <b>{{ card_name }}</b>
+{%- if old_list_name and new_list_name %} from <b>{{ old_list_name }}</b> → <b>{{ new_list_name }}</b>{%- endif %}
+{%- if board_name %} in board <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">View card</a>
+{%- endif %}
@@ -0,0 +1,5 @@
+✏️ <b>{{ sender_name }}</b> updated card <b>{{ card_name }}</b>
+{%- if board_name %} in <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">View card</a>
+{%- endif %}
@@ -0,0 +1,8 @@
+✏️ <b>{{ sender_name }}</b> updated a comment on <b>{{ card_name }}</b>
+{%- if board_name %} in <b>{{ board_name }}</b>{%- endif %}
+{%- if comment_text %}
+{{ comment_text | truncate(300) }}
+{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">View card</a>
+{%- endif %}
@@ -0,0 +1,2 @@
+📝 <b>{{ sender_name }}</b> created list <b>{{ list_name }}</b>
+{%- if board_name %} in board <b>{{ board_name }}</b>{%- endif %}
@@ -0,0 +1,2 @@
+🗑 <b>{{ sender_name }}</b> deleted list <b>{{ list_name }}</b>
+{%- if board_name %} from board <b>{{ board_name }}</b>{%- endif %}
@@ -0,0 +1,2 @@
+✏️ <b>{{ sender_name }}</b> updated list <b>{{ list_name }}</b>
+{%- if board_name %} in board <b>{{ board_name }}</b>{%- endif %}
@@ -0,0 +1,6 @@
+✅ <b>{{ sender_name }}</b> completed task <b>{{ task_name }}</b>
+{%- if card_name %} on card <b>{{ card_name }}</b>{%- endif %}
+{%- if board_name %} in <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">View card</a>
+{%- endif %}
@@ -33,6 +33,23 @@ PROVIDER_SLOT_FILE_MAP: dict[str, dict[str, str]] = {
        "message_pr_commented": "gitea_pr_commented.jinja2",
        "message_release_published": "gitea_release_published.jinja2",
    },
+    "planka": {
+        "message_card_created": "planka_card_created.jinja2",
+        "message_card_updated": "planka_card_updated.jinja2",
+        "message_card_moved": "planka_card_moved.jinja2",
+        "message_card_deleted": "planka_card_deleted.jinja2",
+        "message_card_commented": "planka_card_commented.jinja2",
+        "message_comment_updated": "planka_comment_updated.jinja2",
+        "message_board_created": "planka_board_created.jinja2",
+        "message_board_updated": "planka_board_updated.jinja2",
+        "message_board_deleted": "planka_board_deleted.jinja2",
+        "message_list_created": "planka_list_created.jinja2",
+        "message_list_updated": "planka_list_updated.jinja2",
+        "message_list_deleted": "planka_list_deleted.jinja2",
+        "message_attachment_created": "planka_attachment_created.jinja2",
+        "message_card_label_added": "planka_card_label_added.jinja2",
+        "message_task_completed": "planka_task_completed.jinja2",
+    },
    "scheduler": {
        "message_scheduled_message": "scheduled_message.jinja2",
    },
@@ -0,0 +1,5 @@
+📎 <b>{{ sender_name }}</b> прикрепил(а) <b>{{ attachment_name }}</b> к <b>{{ card_name }}</b>
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">Открыть карточку</a>
+{%- endif %}
@@ -0,0 +1,4 @@
+📌 <b>{{ sender_name }}</b> создал(а) доску <b>{{ board_name }}</b>
+{%- if board_url %}
+<a href="{{ board_url }}">Открыть доску</a>
+{%- endif %}
@@ -0,0 +1 @@
+🗑 <b>{{ sender_name }}</b> удалил(а) доску <b>{{ board_name }}</b>
@@ -0,0 +1,4 @@
+✏️ <b>{{ sender_name }}</b> обновил(а) доску <b>{{ board_name }}</b>
+{%- if board_url %}
+<a href="{{ board_url }}">Открыть доску</a>
+{%- endif %}
@@ -0,0 +1,8 @@
+💬 <b>{{ sender_name }}</b> оставил(а) комментарий к <b>{{ card_name }}</b>
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
+{%- if comment_text %}
+{{ comment_text | truncate(300) }}
+{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">Открыть карточку</a>
+{%- endif %}
@@ -0,0 +1,9 @@
+📋 <b>{{ sender_name }}</b> создал(а) карточку <b>{{ card_name }}</b>
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
+{%- if list_name %} → {{ list_name }}{%- endif %}
+{%- if card_description %}
+{{ card_description | truncate(200) }}
+{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">Открыть карточку</a>
+{%- endif %}
@@ -0,0 +1,2 @@
+🗑 <b>{{ sender_name }}</b> удалил(а) карточку <b>{{ card_name }}</b>
+{%- if board_name %} с доски <b>{{ board_name }}</b>{%- endif %}
@@ -0,0 +1,5 @@
+🏷 <b>{{ sender_name }}</b> добавил(а) метку <b>{{ label_name }}</b> к <b>{{ card_name }}</b>
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">Открыть карточку</a>
+{%- endif %}
@@ -0,0 +1,6 @@
+➡️ <b>{{ sender_name }}</b> переместил(а) карточку <b>{{ card_name }}</b>
+{%- if old_list_name and new_list_name %} из <b>{{ old_list_name }}</b> → <b>{{ new_list_name }}</b>{%- endif %}
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">Открыть карточку</a>
+{%- endif %}
@@ -0,0 +1,5 @@
+✏️ <b>{{ sender_name }}</b> обновил(а) карточку <b>{{ card_name }}</b>
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">Открыть карточку</a>
+{%- endif %}
@@ -0,0 +1,8 @@
+✏️ <b>{{ sender_name }}</b> обновил(а) комментарий к <b>{{ card_name }}</b>
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
+{%- if comment_text %}
+{{ comment_text | truncate(300) }}
+{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">Открыть карточку</a>
+{%- endif %}
@@ -0,0 +1,2 @@
+📝 <b>{{ sender_name }}</b> создал(а) список <b>{{ list_name }}</b>
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
@@ -0,0 +1,2 @@
+🗑 <b>{{ sender_name }}</b> удалил(а) список <b>{{ list_name }}</b>
+{%- if board_name %} с доски <b>{{ board_name }}</b>{%- endif %}
@@ -0,0 +1,2 @@
+✏️ <b>{{ sender_name }}</b> обновил(а) список <b>{{ list_name }}</b>
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
@@ -0,0 +1,6 @@
+✅ <b>{{ sender_name }}</b> завершил(а) задачу <b>{{ task_name }}</b>
+{%- if card_name %} в карточке <b>{{ card_name }}</b>{%- endif %}
+{%- if board_name %} на доске <b>{{ board_name }}</b>{%- endif %}
+{%- if card_url %}
+<a href="{{ card_url }}">Открыть карточку</a>
+{%- endif %}
				`@@ -0,0 +1 @@`
				`⏳ Please wait {{ wait }}s before using this command again.`
				`@@ -0,0 +1 @@`
				`Список отслеживаемых досок`
				`@@ -0,0 +1 @@`
				`Показать доступные команды`
				`@@ -0,0 +1 @@`
				`⏳ Подождите {{ wait }} сек. перед повторным использованием команды.`
				`@@ -0,0 +1 @@`
				`🗑 <b>{{ sender_name }}</b> deleted board <b>{{ board_name }}</b>`
				`@@ -0,0 +1 @@`
				`🗑 <b>{{ sender_name }}</b> удалил(а) доску <b>{{ board_name }}</b>`