"""Abstract scheduled-task persistence API."""

from __future__ import annotations

from abc import ABC, abstractmethod
from datetime import datetime
from typing import Any


class ScheduledTaskStore(ABC):
    @abstractmethod
    async def get_or_create_scheduler_thread(self, user_id: str, thread_id_factory) -> dict:
        raise NotImplementedError

    @abstractmethod
    async def list_tasks(self, user_id: str) -> list[dict[str, Any]]:
        raise NotImplementedError

    @abstractmethod
    async def get_task(self, task_id: str, user_id: str) -> dict[str, Any] | None:
        raise NotImplementedError

    @abstractmethod
    async def create_task(self, data: dict[str, Any]) -> dict[str, Any]:
        raise NotImplementedError

    @abstractmethod
    async def update_task(self, task_id: str, user_id: str, data: dict[str, Any]) -> dict[str, Any] | None:
        raise NotImplementedError

    @abstractmethod
    async def delete_task(self, task_id: str, user_id: str) -> bool:
        raise NotImplementedError

    @abstractmethod
    async def due_tasks(self, now: datetime, *, limit: int = 20) -> list[dict[str, Any]]:
        raise NotImplementedError

    # --- Admin (cross-user) ---

    @abstractmethod
    async def list_all_tasks(self) -> list[dict[str, Any]]:
        """Return every task across all users. Admin-only callers."""
        raise NotImplementedError

    @abstractmethod
    async def update_task_any(self, task_id: str, data: dict[str, Any]) -> dict[str, Any] | None:
        """Update a task by id without restricting by owner. Admin-only callers."""
        raise NotImplementedError

    @abstractmethod
    async def delete_task_any(self, task_id: str) -> bool:
        """Delete a task by id without restricting by owner. Admin-only callers."""
        raise NotImplementedError

    @abstractmethod
    async def list_runs_any(self, task_id: str, *, limit: int = 50) -> list[dict[str, Any]]:
        """Return runs for a task without restricting by owner. Admin-only callers."""
        raise NotImplementedError

    @abstractmethod
    async def list_stuck_runs(self, cutoff: datetime, *, limit: int = 50) -> list[dict[str, Any]]:
        """Return runs still in a non-terminal state whose ``started_at`` is older
        than ``cutoff``. Used by the scheduler watchdog to recover runs that hung
        or were orphaned by a service restart."""
        raise NotImplementedError

    @abstractmethod
    async def create_run_once(self, data: dict[str, Any]) -> dict[str, Any] | None:
        raise NotImplementedError

    @abstractmethod
    async def update_run(self, run_id: str, data: dict[str, Any]) -> None:
        raise NotImplementedError

    @abstractmethod
    async def list_runs(self, task_id: str, user_id: str, *, limit: int = 50) -> list[dict[str, Any]]:
        raise NotImplementedError

    @abstractmethod
    async def get_run(self, run_id: str, user_id: str) -> dict[str, Any] | None:
        raise NotImplementedError

    @abstractmethod
    async def delete_run(self, run_id: str, user_id: str) -> bool:
        raise NotImplementedError

    @abstractmethod
    async def delete_run_any(self, run_id: str) -> bool:
        """Delete a run by id without restricting by owner. Admin-only callers."""
        raise NotImplementedError

    @abstractmethod
    async def get_delivery_profile(self, user_id: str) -> dict[str, Any]:
        raise NotImplementedError

    @abstractmethod
    async def update_delivery_profile(self, user_id: str, data: dict[str, Any]) -> dict[str, Any]:
        raise NotImplementedError

    # --- Publish / subscribe ---

    @abstractmethod
    async def get_task_any(self, task_id: str) -> dict[str, Any] | None:
        """Return a task by id without restricting by owner. Used for publish/subscribe lookups."""
        raise NotImplementedError

    @abstractmethod
    async def get_run_any(self, run_id: str) -> dict[str, Any] | None:
        """Return a run by id without restricting by owner. Used for subscriber visibility."""
        raise NotImplementedError

    @abstractmethod
    async def set_task_published(self, task_id: str, owner_user_id: str, *, published: bool) -> dict[str, Any] | None:
        """Toggle published flag. Returns updated task or ``None`` if missing / not owned."""
        raise NotImplementedError

    @abstractmethod
    async def list_published_tasks(self, *, limit: int = 50, offset: int = 0) -> list[dict[str, Any]]:
        raise NotImplementedError

    @abstractmethod
    async def list_subscribed_tasks(self, user_id: str) -> list[dict[str, Any]]:
        """Return tasks the user has subscribed to. Each item carries ``_subscription`` dict."""
        raise NotImplementedError

    @abstractmethod
    async def get_subscription(self, task_id: str, user_id: str) -> dict[str, Any] | None:
        raise NotImplementedError

    @abstractmethod
    async def upsert_subscription(self, task_id: str, user_id: str, *, notify_element: bool) -> dict[str, Any]:
        raise NotImplementedError

    @abstractmethod
    async def delete_subscription(self, task_id: str, user_id: str) -> bool:
        raise NotImplementedError

    @abstractmethod
    async def list_notify_subscribers(self, task_id: str) -> list[dict[str, Any]]:
        """Subscribers with ``notify_element=True`` for the given task."""
        raise NotImplementedError