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 %}
@@ -13,7 +13,7 @@ import aiohttp
 from ..auth.dependencies import get_current_user
 from ..database.engine import get_session
 from ..database.models import ServiceProvider, User
-from ..services import make_immich_provider, make_gitea_provider
+from ..services import make_immich_provider, make_gitea_provider, make_planka_provider

 _LOGGER = logging.getLogger(__name__)

@@ -57,6 +57,12 @@ class GiteaProviderConfig(BaseModel):
    api_token: str | None = None


+class PlankaProviderConfig(BaseModel):
+    url: str
+    webhook_secret: str
+    api_key: str | None = None
+
+
 class SchedulerProviderConfig(BaseModel):
    """Scheduler is a virtual provider — no required fields."""

@@ -66,6 +72,7 @@ class SchedulerProviderConfig(BaseModel):
 _PROVIDER_CONFIG_MODELS: dict[str, type[BaseModel]] = {
    "immich": ImmichProviderConfig,
    "gitea": GiteaProviderConfig,
+    "planka": PlankaProviderConfig,
    "scheduler": SchedulerProviderConfig,
 }

@@ -141,6 +148,21 @@ async def create_provider(
                        detail=test_result.get("message", "Cannot connect to Gitea"),
                    )

+    elif body.type == "planka":
+        config = body.config
+        if config.get("api_key"):
+            async with aiohttp.ClientSession() as http_session:
+                from notify_bridge_core.providers.planka import PlankaServiceProvider
+                planka = PlankaServiceProvider(
+                    http_session, config.get("url", ""), config.get("api_key", ""), body.name,
+                )
+                test_result = await planka.test_connection()
+                if not test_result.get("ok"):
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=test_result.get("message", "Cannot connect to Planka"),
+                    )
+
    # Scheduler: no validation needed (virtual provider)

    provider = ServiceProvider(
@@ -258,6 +280,22 @@ async def update_provider(
                    status_code=status.HTTP_400_BAD_REQUEST,
                    detail=f"Connection error: {err}",
                )
+    elif config_changed and provider.type == "planka":
+        if provider.config.get("api_key"):
+            try:
+                async with aiohttp.ClientSession() as http_session:
+                    planka = make_planka_provider(http_session, provider)
+                    test_result = await planka.test_connection()
+                    if not test_result.get("ok"):
+                        raise HTTPException(
+                            status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=test_result.get("message", "Cannot connect to Planka"),
+                        )
+            except aiohttp.ClientError as err:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Connection error: {err}",
+                )

    session.add(provider)
    await session.commit()
@@ -300,6 +338,13 @@ async def test_provider(
            gitea = make_gitea_provider(http_session, provider)
            return await gitea.test_connection()

+    if provider.type == "planka":
+        if not provider.config.get("api_key"):
+            return {"ok": True, "message": "Planka webhook-only mode (no API key for testing)"}
+        async with aiohttp.ClientSession() as http_session:
+            planka = make_planka_provider(http_session, provider)
+            return await planka.test_connection()
+
    if provider.type == "scheduler":
        return {"ok": True, "message": "Virtual provider — always available"}

@@ -327,6 +372,13 @@ async def list_collections(
            gitea = make_gitea_provider(http_session, provider)
            return await gitea.list_collections()

+    if provider.type == "planka":
+        if not provider.config.get("api_key"):
+            return []
+        async with aiohttp.ClientSession() as http_session:
+            planka = make_planka_provider(http_session, provider)
+            return await planka.list_collections()
+
    return []


@@ -14,6 +14,7 @@ from sqlmodel.ext.asyncio.session import AsyncSession
 from notify_bridge_core.models.events import ServiceEvent
 from notify_bridge_core.notifications.dispatcher import NotificationDispatcher, TargetConfig
 from notify_bridge_core.providers.gitea.event_parser import parse_webhook as parse_gitea_webhook
+from notify_bridge_core.providers.planka.event_parser import parse_webhook as parse_planka_webhook

 from ..database.engine import get_engine
 from ..database.models import (
@@ -174,6 +175,118 @@ async def gitea_webhook(provider_id: int, request: Request):
    return {"ok": True, "dispatched": dispatched}


+# ---------------------------------------------------------------------------
+# Planka webhook endpoint
+# ---------------------------------------------------------------------------
+
+def _verify_planka_token(expected_token: str, request: Request) -> bool:
+    """Verify Planka webhook Bearer token."""
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        token = auth_header[7:]
+        return hmac.compare_digest(token, expected_token)
+    return False
+
+
+@router.post("/planka/{provider_id}")
+async def planka_webhook(provider_id: int, request: Request):
+    """Receive a Planka webhook, parse it, filter, and dispatch notifications."""
+    engine = get_engine()
+
+    # --- Load provider and validate token ---
+    async with AsyncSession(engine) as session:
+        provider = await session.get(ServiceProvider, provider_id)
+        if not provider or provider.type != "planka":
+            raise HTTPException(status_code=404, detail="Provider not found")
+
+        webhook_secret = (provider.config or {}).get("webhook_secret", "")
+
+    if not webhook_secret:
+        raise HTTPException(
+            status_code=403,
+            detail="Webhook secret not configured on this provider",
+        )
+
+    if not _verify_planka_token(webhook_secret, request):
+        raise HTTPException(status_code=403, detail="Invalid token")
+
+    # Parse payload
+    try:
+        payload = await request.json()
+    except Exception:
+        raise HTTPException(status_code=400, detail="Invalid JSON")
+
+    event_type = payload.get("type", "")
+    if not event_type:
+        return {"ok": True, "skipped": "no event type"}
+
+    base_url = (provider.config or {}).get("url", "")
+    event = parse_planka_webhook(event_type, payload, provider.name, base_url=base_url)
+    if event is None:
+        return {"ok": True, "skipped": "unmapped event"}
+
+    # --- Find trackers for this provider and dispatch ---
+    dispatched = 0
+    async with AsyncSession(engine) as session:
+        tracker_result = await session.exec(
+            select(NotificationTracker).where(
+                NotificationTracker.provider_id == provider_id,
+                NotificationTracker.enabled == True,
+            )
+        )
+        trackers = tracker_result.all()
+
+        for tracker in trackers:
+            filters = tracker.filters or {}
+            if not _passes_filters(event, filters):
+                _LOGGER.debug(
+                    "Event filtered out for tracker %d (%s)", tracker.id, tracker.name
+                )
+                continue
+
+            link_data = await load_link_data(session, tracker.id)
+            if not link_data:
+                continue
+
+            # Log event
+            session.add(EventLog(
+                tracker_id=tracker.id,
+                tracker_name=tracker.name,
+                provider_id=provider_id,
+                provider_name=provider.name,
+                event_type=event.event_type.value,
+                collection_id=event.collection_id,
+                collection_name=event.collection_name,
+                assets_count=0,
+                details={
+                    "provider_type": event.provider_type.value,
+                    **{k: v for k, v in event.extra.items() if k in (
+                        "sender", "card_name", "board_name",
+                        "list_name", "old_list_name", "new_list_name",
+                        "comment_text", "task_name", "attachment_name",
+                        "label_name",
+                    )},
+                },
+            ))
+            await session.commit()
+
+            # Dispatch to targets
+            dispatcher = NotificationDispatcher()
+            target_configs = _build_target_configs(event, link_data, provider.config or {})
+            if target_configs:
+                results = await dispatcher.dispatch(event, target_configs)
+                for r in results:
+                    if r.get("success"):
+                        dispatched += 1
+                    else:
+                        _LOGGER.error(
+                            "Notification failed for tracker %d: %s",
+                            tracker.id, r.get("error", "unknown"),
+                        )
+
+    return {"ok": True, "dispatched": dispatched}
+
+
 def _build_target_configs(
    event: ServiceEvent,
    link_data: list[dict[str, Any]],
@@ -31,9 +31,11 @@ def _auto_register() -> None:
    """Auto-register all built-in handlers."""
    from .immich import ImmichCommandHandler
    from .gitea_handler import GiteaCommandHandler
+    from .planka_handler import PlankaCommandHandler

    register_handler(ImmichCommandHandler())
    register_handler(GiteaCommandHandler())
+    register_handler(PlankaCommandHandler())


 # Auto-register on import
@@ -0,0 +1,193 @@
+"""Planka-specific bot command handler."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from ..database.engine import get_engine
+from ..database.models import (
+    CommandConfig, CommandTracker, EventLog,
+    NotificationTracker, ServiceProvider, TelegramBot,
+)
+from ..services import make_planka_provider
+from .base import ProviderCommandHandler
+from .handler import _render_cmd_template, _get_notification_trackers_for_providers
+
+_LOGGER = logging.getLogger(__name__)
+
+_PLANKA_COMMANDS = {"status", "boards", "cards", "lists"}
+
+
+class PlankaCommandHandler(ProviderCommandHandler):
+    """Handles Planka-specific bot commands."""
+
+    provider_type = "planka"
+
+    def get_provider_commands(self) -> set[str]:
+        return _PLANKA_COMMANDS
+
+    def get_rate_categories(self) -> dict[str, str]:
+        return {
+            "boards": "api", "cards": "api", "lists": "api",
+        }
+
+    async def handle(
+        self,
+        cmd: str,
+        args: str,
+        count: int,
+        locale: str,
+        response_mode: str,
+        providers_map: dict[int, ServiceProvider],
+        cmd_templates: dict[str, dict[str, str]],
+        bot: TelegramBot,
+        ctx_tuples: list[tuple[CommandTracker, CommandConfig, ServiceProvider]],
+    ) -> str | list[dict[str, Any]] | None:
+        if cmd == "status":
+            ctx = await _cmd_status(providers_map)
+            return _render_cmd_template(cmd_templates, "status", locale, ctx)
+        if cmd == "boards":
+            ctx = await _cmd_boards(providers_map)
+            return _render_cmd_template(cmd_templates, "boards", locale, ctx)
+        if cmd == "cards":
+            ctx = await _cmd_cards(providers_map, count)
+            return _render_cmd_template(cmd_templates, "cards", locale, ctx)
+        if cmd == "lists":
+            ctx = await _cmd_lists(providers_map)
+            return _render_cmd_template(cmd_templates, "lists", locale, ctx)
+        return None
+
+
+def _get_tracked_board_ids(
+    providers_map: dict[int, ServiceProvider],
+    trackers: list[NotificationTracker],
+) -> list[tuple[ServiceProvider, str]]:
+    """Get (provider, board_id) tuples from tracked collection_ids."""
+    boards: list[tuple[ServiceProvider, str]] = []
+    for tracker in trackers:
+        provider = providers_map.get(tracker.provider_id)
+        if not provider or provider.type != "planka":
+            continue
+        if not provider.config.get("api_key"):
+            continue
+        for board_id in (tracker.collection_ids or []):
+            entry = (provider, board_id)
+            if entry not in boards:
+                boards.append(entry)
+        # Also check filters.collections
+        for board_id in (tracker.filters or {}).get("collections", []):
+            entry = (provider, board_id)
+            if entry not in boards:
+                boards.append(entry)
+    return boards[:20]
+
+
+async def _cmd_status(providers_map: dict[int, ServiceProvider]) -> dict[str, Any]:
+    provider_ids = set(providers_map.keys())
+    trackers = await _get_notification_trackers_for_providers(provider_ids)
+    tracked_boards = _get_tracked_board_ids(providers_map, trackers)
+
+    # Last event
+    engine = get_engine()
+    async with AsyncSession(engine) as session:
+        tracker_ids = [t.id for t in trackers]
+        if tracker_ids:
+            result = await session.exec(
+                select(EventLog)
+                .where(EventLog.tracker_id.in_(tracker_ids))
+                .order_by(EventLog.created_at.desc()).limit(1)
+            )
+            last_event = result.first()
+        else:
+            last_event = None
+    last_str = last_event.created_at.strftime("%Y-%m-%d %H:%M") if last_event else "-"
+
+    return {
+        "boards_count": len(tracked_boards),
+        "last_event": last_str,
+    }
+
+
+async def _cmd_boards(providers_map: dict[int, ServiceProvider]) -> dict[str, Any]:
+    provider_ids = set(providers_map.keys())
+    trackers = await _get_notification_trackers_for_providers(provider_ids)
+    tracked_boards = _get_tracked_board_ids(providers_map, trackers)
+
+    boards_data: list[dict[str, Any]] = []
+    async with aiohttp.ClientSession() as http:
+        for provider, board_id in tracked_boards:
+            planka = make_planka_provider(http, provider)
+            all_boards = await planka.client.get_boards()
+            for b in all_boards:
+                if str(b.get("id", "")) == board_id:
+                    boards_data.append({"name": b.get("name", board_id)})
+                    break
+            else:
+                boards_data.append({"name": board_id})
+
+    return {"boards": boards_data}
+
+
+async def _cmd_cards(
+    providers_map: dict[int, ServiceProvider], count: int,
+) -> dict[str, Any]:
+    provider_ids = set(providers_map.keys())
+    trackers = await _get_notification_trackers_for_providers(provider_ids)
+    tracked_boards = _get_tracked_board_ids(providers_map, trackers)
+
+    all_cards: list[dict[str, Any]] = []
+    async with aiohttp.ClientSession() as http:
+        for provider, board_id in tracked_boards:
+            planka = make_planka_provider(http, provider)
+            cards = await planka.client.get_board_cards(board_id, limit=count)
+            lists = await planka.client.get_board_lists(board_id)
+            lists_by_id = {str(lst.get("id", "")): lst.get("name", "") for lst in lists}
+
+            boards = await planka.client.get_boards()
+            board_name = board_id
+            for b in boards:
+                if str(b.get("id", "")) == board_id:
+                    board_name = b.get("name", board_id)
+                    break
+
+            for card in cards:
+                list_id = str(card.get("listId", ""))
+                all_cards.append({
+                    "name": card.get("name", ""),
+                    "list_name": lists_by_id.get(list_id, ""),
+                    "board_name": board_name,
+                })
+
+    return {"cards": all_cards[:count]}
+
+
+async def _cmd_lists(providers_map: dict[int, ServiceProvider]) -> dict[str, Any]:
+    provider_ids = set(providers_map.keys())
+    trackers = await _get_notification_trackers_for_providers(provider_ids)
+    tracked_boards = _get_tracked_board_ids(providers_map, trackers)
+
+    all_lists: list[dict[str, Any]] = []
+    async with aiohttp.ClientSession() as http:
+        for provider, board_id in tracked_boards:
+            planka = make_planka_provider(http, provider)
+            lists = await planka.client.get_board_lists(board_id)
+
+            boards = await planka.client.get_boards()
+            board_name = board_id
+            for b in boards:
+                if str(b.get("id", "")) == board_id:
+                    board_name = b.get("name", board_id)
+                    break
+
+            for lst in lists:
+                all_lists.append({
+                    "name": lst.get("name", ""),
+                    "board_name": board_name,
+                })
+
+    return {"lists": all_lists}
@@ -9,6 +9,8 @@ _RATE_CATEGORY: dict[str, str] = {
    "place": "search", "favorites": "search", "people": "search",
    # Gitea (API calls share a category)
    "repos": "api", "issues": "api", "prs": "api", "commits": "api",
+    # Planka (API calls share a category)
+    "boards": "api", "cards": "api", "lists": "api",
 }


@@ -159,6 +159,32 @@ async def migrate_schema(engine: AsyncEngine) -> None:
                    )
                    logger.info("Added %s column to tracking_config table", col_name)

+        # Add Planka tracking flags to tracking_config if missing
+        if await _has_table(conn, "tracking_config"):
+            planka_flags = [
+                ("track_card_created", "INTEGER DEFAULT 1"),
+                ("track_card_updated", "INTEGER DEFAULT 0"),
+                ("track_card_moved", "INTEGER DEFAULT 1"),
+                ("track_card_deleted", "INTEGER DEFAULT 0"),
+                ("track_card_commented", "INTEGER DEFAULT 1"),
+                ("track_comment_updated", "INTEGER DEFAULT 0"),
+                ("track_board_created", "INTEGER DEFAULT 1"),
+                ("track_board_updated", "INTEGER DEFAULT 0"),
+                ("track_board_deleted", "INTEGER DEFAULT 1"),
+                ("track_list_created", "INTEGER DEFAULT 0"),
+                ("track_list_updated", "INTEGER DEFAULT 0"),
+                ("track_list_deleted", "INTEGER DEFAULT 0"),
+                ("track_attachment_created", "INTEGER DEFAULT 1"),
+                ("track_card_label_added", "INTEGER DEFAULT 0"),
+                ("track_task_completed", "INTEGER DEFAULT 1"),
+            ]
+            for col_name, col_type in planka_flags:
+                if not await _has_column(conn, "tracking_config", col_name):
+                    await conn.execute(
+                        text(f"ALTER TABLE tracking_config ADD COLUMN {col_name} {col_type}")
+                    )
+                    logger.info("Added %s column to tracking_config table", col_name)
+
        # Add collection_name and shared to tracker_state if missing
        state_table = "notification_tracker_state" if await _has_table(conn, "notification_tracker_state") else "tracker_state"
        if await _has_table(conn, state_table):
@@ -128,6 +128,23 @@ class TrackingConfig(SQLModel, table=True):
    track_pr_commented: bool = Field(default=False)
    track_release_published: bool = Field(default=True)

+    # Planka event tracking
+    track_card_created: bool = Field(default=True)
+    track_card_updated: bool = Field(default=False)
+    track_card_moved: bool = Field(default=True)
+    track_card_deleted: bool = Field(default=False)
+    track_card_commented: bool = Field(default=True)
+    track_comment_updated: bool = Field(default=False)
+    track_board_created: bool = Field(default=True)
+    track_board_updated: bool = Field(default=False)
+    track_board_deleted: bool = Field(default=True)
+    track_list_created: bool = Field(default=False)
+    track_list_updated: bool = Field(default=False)
+    track_list_deleted: bool = Field(default=False)
+    track_attachment_created: bool = Field(default=True)
+    track_card_label_added: bool = Field(default=False)
+    track_task_completed: bool = Field(default=True)
+
    # Scheduler event tracking
    track_scheduled_message: bool = Field(default=True)

@@ -183,6 +183,7 @@ async def _seed_default_templates() -> None:
    async with AsyncSession(engine) as session:
        await _seed_provider_template(session, "immich", "Immich")
        await _seed_provider_template(session, "gitea", "Gitea")
+        await _seed_provider_template(session, "planka", "Planka")
        await _seed_provider_template(session, "scheduler", "Scheduler")
        await session.commit()

@@ -201,6 +202,9 @@ async def _seed_default_command_templates() -> None:
        await _seed_provider_command_template(
            session, "gitea", "Default Gitea Commands", "Default Gitea command templates",
        )
+        await _seed_provider_command_template(
+            session, "planka", "Default Planka Commands", "Default Planka command templates",
+        )
        await session.commit()


@@ -227,6 +231,25 @@ async def _seed_default_tracking_configs() -> None:
                "track_pr_commented": False,
                "track_release_published": True,
            },
+            {
+                "provider_type": "planka",
+                "name": "Default Planka",
+                "track_card_created": True,
+                "track_card_updated": False,
+                "track_card_moved": True,
+                "track_card_deleted": False,
+                "track_card_commented": True,
+                "track_comment_updated": False,
+                "track_board_created": True,
+                "track_board_updated": False,
+                "track_board_deleted": True,
+                "track_list_created": False,
+                "track_list_updated": False,
+                "track_list_deleted": False,
+                "track_attachment_created": True,
+                "track_card_label_added": False,
+                "track_task_completed": True,
+            },
            {
                "provider_type": "scheduler",
                "name": "Default Scheduler",
@@ -280,6 +303,16 @@ async def _seed_default_command_configs() -> None:
                "default_count": 10,
                "rate_limits": {"api": 15, "default": 10},
            },
+            {
+                "provider_type": "planka",
+                "name": "Default Planka",
+                "enabled_commands": [
+                    "help", "status", "boards", "cards", "lists",
+                ],
+                "response_mode": "text",
+                "default_count": 10,
+                "rate_limits": {"api": 15, "default": 10},
+            },
        ]

        for cfg in defaults:
@@ -2,6 +2,7 @@

 from notify_bridge_core.providers.immich import ImmichServiceProvider
 from notify_bridge_core.providers.gitea import GiteaServiceProvider
+from notify_bridge_core.providers.planka import PlankaServiceProvider

 from ..database.models import ServiceProvider

@@ -27,3 +28,14 @@ def make_gitea_provider(http_session, provider: ServiceProvider) -> GiteaService
        config.get("api_token", ""),
        provider.name,
    )
+
+
+def make_planka_provider(http_session, provider: ServiceProvider) -> PlankaServiceProvider:
+    """Create a PlankaServiceProvider from a DB provider model."""
+    config = provider.config or {}
+    return PlankaServiceProvider(
+        http_session,
+        config.get("url", ""),
+        config.get("api_key", ""),
+        provider.name,
+    )
@@ -62,6 +62,22 @@ def event_allowed_by_config(event: ServiceEvent, tc: TrackingConfig) -> bool:
        "pr_merged": tc.track_pr_merged,
        "pr_commented": tc.track_pr_commented,
        "release_published": tc.track_release_published,
+        # Planka events
+        "card_created": tc.track_card_created,
+        "card_updated": tc.track_card_updated,
+        "card_moved": tc.track_card_moved,
+        "card_deleted": tc.track_card_deleted,
+        "card_commented": tc.track_card_commented,
+        "comment_updated": tc.track_comment_updated,
+        "board_created": tc.track_board_created,
+        "board_updated": tc.track_board_updated,
+        "board_deleted": tc.track_board_deleted,
+        "list_created": tc.track_list_created,
+        "list_updated": tc.track_list_updated,
+        "list_deleted": tc.track_list_deleted,
+        "attachment_created": tc.track_attachment_created,
+        "card_label_added": tc.track_card_label_added,
+        "task_completed": tc.track_task_completed,
        # Scheduler events
        "scheduled_message": tc.track_scheduled_message,
    }
@@ -142,6 +142,30 @@ _SAMPLE_CONTEXT = {
    "release_body": "Initial release",
    "release_draft": False,
    "release_prerelease": False,
+    # Planka variables (for planka provider templates)
+    "board_name": "My Project",
+    "board_id": "123456",
+    "board_url": "https://planka.example.com/boards/123456",
+    "card_name": "Fix login bug",
+    "card_id": "789012",
+    "card_url": "https://planka.example.com/cards/789012",
+    "card_description": "Users cannot log in with SSO",
+    "card_due_date": "2026-04-01T00:00:00.000Z",
+    "list_name": "In Progress",
+    "list_id": "list-1",
+    "old_list_name": "To Do",
+    "new_list_name": "In Progress",
+    "old_list_id": "list-0",
+    "new_list_id": "list-1",
+    "comment_text": "Looks good, ready for review!",
+    "comment_id": "comment-1",
+    "task_name": "Write unit tests",
+    "task_id": "task-1",
+    "task_completed": True,
+    "attachment_name": "screenshot.png",
+    "attachment_id": "att-1",
+    "label_name": "bug",
+    "label_color": "berry-red",
    # Scheduler variables (for scheduler provider templates)
    "schedule_name": "Daily Reminder",
    "fire_count": 42,
@@ -111,6 +111,9 @@ async def check_tracker(tracker_id: int) -> dict[str, Any]:
        # Gitea is webhook-based — events arrive via /api/webhooks/gitea endpoint.
        # The scheduler still calls check_tracker but there's nothing to poll.
        return {"status": "ok", "events_detected": 0, "collections_checked": 0}
+    elif provider_type == "planka":
+        # Planka is webhook-based — events arrive via /api/webhooks/planka endpoint.
+        return {"status": "ok", "events_detected": 0, "collections_checked": 0}
    elif provider_type == "scheduler":
        from notify_bridge_core.providers.scheduler import SchedulerServiceProvider
        custom_vars = tracker_filters.get("custom_variables", {})
				`@@ -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>`