"""Provider interfaces for tasks and notes integrations."""

from __future__ import annotations

from typing import Protocol

from sqlalchemy.orm import Session

from app.services.integrations.types import NotesHit, ProviderConnectionResult, UnifiedTask


class TaskProvider(Protocol):
    """Required contract for task providers."""

    provider_id: str
    display_name: str

    def list_tasks(self, *, include_completed: bool = False) -> list[UnifiedTask]:
        """List open tasks."""

    def create_task(self, *, content: str, description: str | None = None, due_string: str | None = None) -> UnifiedTask:
        """Create a task."""

    def complete_task(self, *, task_id: str) -> None:
        """Mark task as completed/closed."""

    def update_due(self, *, task_id: str, due_string: str) -> UnifiedTask | None:
        """Update due information when supported."""

    def test_connection(self) -> ProviderConnectionResult:
        """Verify provider credentials/connectivity."""


class NotesProvider(Protocol):
    """Required contract for notes providers."""

    provider_id: str
    display_name: str

    def search(self, *, query: str, limit: int = 5, db: Session | None = None) -> list[NotesHit]:
        """Search notes content."""

    def create_note(self, *, title: str, content: str, db: Session | None = None) -> str:
        """Create a note/page and return provider-specific id."""

    def append_note(self, *, target_id: str, content: str, db: Session | None = None) -> None:
        """Append content to an existing note/page."""

    def test_connection(self, db: Session | None = None) -> ProviderConnectionResult:
        """Verify provider credentials/connectivity."""
