msaas-feedback 0.1.0__py3-none-any.whl

feedback/__init__.py

@@ -0,0 +1,43 @@
+"""User feedback and feature request management for SaaS."""
+
+from feedback.analysis import FeedbackAnalyzer
+from feedback.config import Feedback, get_feedback, init_feedback, reset_feedback
+from feedback.models import (
+    FeedbackCategory,
+    FeedbackComment,
+    FeedbackConfig,
+    FeedbackFilter,
+    FeedbackItem,
+    FeedbackPriority,
+    FeedbackSortBy,
+    FeedbackStats,
+    FeedbackStatus,
+    FeedbackVote,
+    PaginatedResult,
+)
+from feedback.router import create_feedback_router
+from feedback.service import FeedbackService
+from feedback.store import FeedbackStore, InMemoryStore
+
+__all__ = [
+    "Feedback",
+    "FeedbackAnalyzer",
+    "FeedbackCategory",
+    "FeedbackComment",
+    "FeedbackConfig",
+    "FeedbackFilter",
+    "FeedbackItem",
+    "FeedbackPriority",
+    "FeedbackService",
+    "FeedbackSortBy",
+    "FeedbackStats",
+    "FeedbackStatus",
+    "FeedbackStore",
+    "FeedbackVote",
+    "InMemoryStore",
+    "PaginatedResult",
+    "create_feedback_router",
+    "get_feedback",
+    "init_feedback",
+    "reset_feedback",
+]

feedback/analysis.py

@@ -0,0 +1,70 @@
+"""Feedback analytics and insights."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from feedback.models import (
+    FeedbackItem,
+    FeedbackStatus,
+)
+from feedback.store import FeedbackStore
+
+_TERMINAL_STATUSES = {FeedbackStatus.DONE, FeedbackStatus.DECLINED}
+
+
+class FeedbackAnalyzer:
+    """Provides analytical views over the feedback dataset."""
+
+    def __init__(self, store: FeedbackStore) -> None:
+        self._store = store
+
+    async def trending(self, *, days: int = 7, limit: int = 10) -> list[FeedbackItem]:
+        """Return the most-voted feedback items created within the last *days*.
+
+        Items that have been merged or resolved are excluded.
+        """
+        cutoff = datetime.now(UTC) - timedelta(days=days)
+        all_items = await self._store.list_all_items()
+
+        recent = [
+            item
+            for item in all_items
+            if item.created_at >= cutoff
+            and item.merged_into is None
+            and item.status not in _TERMINAL_STATUSES
+        ]
+        recent.sort(key=lambda i: i.vote_count, reverse=True)
+        return recent[:limit]
+
+    async def stale(self, *, days: int = 30) -> list[FeedbackItem]:
+        """Return open items that have not been updated in *days*."""
+        cutoff = datetime.now(UTC) - timedelta(days=days)
+        all_items = await self._store.list_all_items()
+
+        return [
+            item
+            for item in all_items
+            if item.updated_at < cutoff
+            and item.merged_into is None
+            and item.status not in _TERMINAL_STATUSES
+        ]
+
+    async def category_distribution(self) -> dict[str, int]:
+        """Return a breakdown of non-merged items by category."""
+        stats = await self._store.get_stats()
+        return stats.by_category
+
+    async def resolution_rate(self) -> float:
+        """Return the percentage of items that have been resolved (done/declined).
+
+        Returns 0.0 if there are no items.
+        """
+        all_items = await self._store.list_all_items()
+        non_merged = [i for i in all_items if i.merged_into is None]
+
+        if not non_merged:
+            return 0.0
+
+        resolved = sum(1 for i in non_merged if i.status in _TERMINAL_STATUSES)
+        return (resolved / len(non_merged)) * 100

feedback/config.py

@@ -0,0 +1,71 @@
+"""Global configuration and singleton management for the feedback system."""
+
+from __future__ import annotations
+
+from feedback.models import FeedbackConfig
+from feedback.service import FeedbackService
+from feedback.store import FeedbackStore, InMemoryStore
+
+
+class Feedback:
+    """Facade grouping the feedback service, store, and config."""
+
+    def __init__(
+        self,
+        *,
+        config: FeedbackConfig,
+        store: FeedbackStore,
+        service: FeedbackService,
+    ) -> None:
+        self.config = config
+        self.store = store
+        self.service = service
+
+
+# Module-level singleton
+_instance: Feedback | None = None
+
+
+def init_feedback(
+    config: FeedbackConfig | None = None,
+    *,
+    store: FeedbackStore | None = None,
+) -> Feedback:
+    """Initialize the global feedback system.
+
+    Call once at application startup. If no store is provided, an
+    InMemoryStore is used (suitable for testing/development).
+
+    Args:
+        config: Feedback configuration. Defaults to FeedbackConfig().
+        store: Storage backend. Defaults to InMemoryStore.
+
+    Returns:
+        The initialized Feedback facade.
+    """
+    global _instance  # noqa: PLW0603
+    config = config or FeedbackConfig()
+    store = store or InMemoryStore()
+
+    service = FeedbackService(store, config=config)
+
+    _instance = Feedback(config=config, store=store, service=service)
+    return _instance
+
+
+def get_feedback() -> Feedback:
+    """Retrieve the global Feedback instance.
+
+    Raises:
+        RuntimeError: If init_feedback() has not been called.
+    """
+    if _instance is None:
+        msg = "Feedback not initialized. Call init_feedback() first."
+        raise RuntimeError(msg)
+    return _instance
+
+
+def reset_feedback() -> None:
+    """Reset global feedback state. Useful for testing."""
+    global _instance  # noqa: PLW0603
+    _instance = None

feedback/models.py

@@ -0,0 +1,124 @@
+"""Pydantic v2 domain models for the feedback system."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class FeedbackCategory(StrEnum):
+    """Type of feedback submitted by a user."""
+
+    BUG = "bug"
+    FEATURE = "feature"
+    IMPROVEMENT = "improvement"
+    QUESTION = "question"
+
+
+class FeedbackStatus(StrEnum):
+    """Lifecycle status of a feedback item."""
+
+    NEW = "new"
+    UNDER_REVIEW = "under_review"
+    PLANNED = "planned"
+    IN_PROGRESS = "in_progress"
+    DONE = "done"
+    DECLINED = "declined"
+
+
+class FeedbackPriority(StrEnum):
+    """Urgency/importance level of a feedback item."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class FeedbackSortBy(StrEnum):
+    """Sorting options for feedback listings."""
+
+    NEWEST = "newest"
+    OLDEST = "oldest"
+    VOTES = "votes"
+
+
+class FeedbackConfig(BaseModel):
+    """Configuration for the feedback module."""
+
+    categories: list[FeedbackCategory] = Field(
+        default_factory=lambda: list(FeedbackCategory),
+    )
+    allow_anonymous: bool = True
+    require_moderation: bool = False
+    max_votes_per_user: int = 50
+
+
+class FeedbackItem(BaseModel):
+    """A single piece of user feedback or feature request."""
+
+    id: str
+    title: str
+    description: str
+    category: FeedbackCategory
+    status: FeedbackStatus = FeedbackStatus.NEW
+    priority: FeedbackPriority = FeedbackPriority.MEDIUM
+    author_id: str | None = None
+    author_email: str | None = None
+    is_anonymous: bool = False
+    tags: list[str] = Field(default_factory=list)
+    vote_count: int = 0
+    merged_into: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    resolved_at: datetime | None = None
+
+
+class FeedbackVote(BaseModel):
+    """A vote cast by a user on a feedback item."""
+
+    item_id: str
+    user_id: str
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class FeedbackComment(BaseModel):
+    """A comment on a feedback item."""
+
+    id: str
+    item_id: str
+    author_id: str
+    content: str
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class FeedbackFilter(BaseModel):
+    """Filtering and sorting criteria for feedback listings."""
+
+    category: FeedbackCategory | None = None
+    status: FeedbackStatus | None = None
+    priority: FeedbackPriority | None = None
+    tag: str | None = None
+    search_query: str | None = None
+    sort_by: FeedbackSortBy = FeedbackSortBy.NEWEST
+
+
+class PaginatedResult(BaseModel):
+    """Paginated list of feedback items."""
+
+    items: list[FeedbackItem]
+    total: int
+    page: int
+    per_page: int
+
+
+class FeedbackStats(BaseModel):
+    """Aggregate statistics for the feedback system."""
+
+    total: int = 0
+    by_category: dict[str, int] = Field(default_factory=dict)
+    by_status: dict[str, int] = Field(default_factory=dict)
+    by_priority: dict[str, int] = Field(default_factory=dict)
+    avg_resolution_hours: float | None = None

feedback/router.py

@@ -0,0 +1,218 @@
+"""FastAPI router factory for feedback endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from errors import (
+    NotFoundError,
+    ValidationError,
+)
+from fastapi import APIRouter, Query
+from pydantic import BaseModel
+
+from feedback.config import get_feedback
+from feedback.models import (
+    FeedbackCategory,
+    FeedbackComment,
+    FeedbackFilter,
+    FeedbackItem,
+    FeedbackPriority,
+    FeedbackSortBy,
+    FeedbackStats,
+    FeedbackStatus,
+    PaginatedResult,
+)
+
+# --- Request / Response models ---
+
+
+class SubmitFeedbackRequest(BaseModel):
+    """Request body for submitting new feedback."""
+
+    title: str
+    description: str
+    category: FeedbackCategory
+    author_id: str | None = None
+    author_email: str | None = None
+    tags: list[str] | None = None
+
+
+class UpdateStatusRequest(BaseModel):
+    """Request body for updating feedback status."""
+
+    status: FeedbackStatus
+
+
+class UpdatePriorityRequest(BaseModel):
+    """Request body for updating feedback priority."""
+
+    priority: FeedbackPriority
+
+
+class VoteRequest(BaseModel):
+    """Request body for voting."""
+
+    user_id: str
+
+
+class AddCommentRequest(BaseModel):
+    """Request body for adding a comment."""
+
+    author_id: str
+    content: str
+
+
+class TrendingItem(BaseModel):
+    """Response model for trending items."""
+
+    items: list[FeedbackItem]
+
+
+# --- Router factory ---
+
+
+def create_feedback_router(
+    *,
+    prefix: str = "/feedback",
+    tags: list[str] | None = None,
+    dependencies: list[Any] | None = None,
+) -> APIRouter:
+    """Create a FastAPI router for feedback endpoints.
+
+    Args:
+        prefix: URL prefix for all routes. Defaults to ``/feedback``.
+        tags: OpenAPI tags for the router.
+        dependencies: Optional list of FastAPI dependencies for all routes.
+
+    Returns:
+        A configured APIRouter.
+    """
+    router = APIRouter(
+        prefix=prefix,
+        tags=tags or ["feedback"],
+        dependencies=dependencies or [],
+    )
+
+    @router.post("", response_model=FeedbackItem, status_code=201)
+    async def submit_feedback(body: SubmitFeedbackRequest) -> FeedbackItem:
+        """Submit new feedback."""
+        fb = get_feedback()
+        try:
+            return await fb.service.submit(
+                title=body.title,
+                description=body.description,
+                category=body.category,
+                author_id=body.author_id,
+                author_email=body.author_email,
+                tags=body.tags,
+            )
+        except ValueError as exc:
+            raise ValidationError(str(exc)) from exc
+
+    @router.get("/stats", response_model=FeedbackStats)
+    async def get_stats() -> FeedbackStats:
+        """Get aggregate feedback statistics."""
+        fb = get_feedback()
+        return await fb.service.get_stats()
+
+    @router.get("/trending", response_model=TrendingItem)
+    async def get_trending(
+        days: int = Query(7, ge=1, description="Number of days to look back"),
+        limit: int = Query(10, ge=1, le=100, description="Maximum items to return"),
+    ) -> TrendingItem:
+        """Get trending feedback items."""
+        from feedback.analysis import FeedbackAnalyzer
+
+        fb = get_feedback()
+        analyzer = FeedbackAnalyzer(fb.store)
+        items = await analyzer.trending(days=days, limit=limit)
+        return TrendingItem(items=items)
+
+    @router.get("", response_model=PaginatedResult)
+    async def list_feedback(
+        category: FeedbackCategory | None = Query(None, description="Filter by category"),
+        status: FeedbackStatus | None = Query(None, description="Filter by status"),
+        priority: FeedbackPriority | None = Query(None, description="Filter by priority"),
+        tag: str | None = Query(None, description="Filter by tag"),
+        search: str | None = Query(None, description="Search in title/description"),
+        sort_by: FeedbackSortBy = Query(FeedbackSortBy.NEWEST, description="Sort order"),
+        page: int = Query(1, ge=1, description="Page number"),
+        per_page: int = Query(20, ge=1, le=100, description="Items per page"),
+    ) -> PaginatedResult:
+        """List feedback items with pagination and filters."""
+        fb = get_feedback()
+        filter_ = FeedbackFilter(
+            category=category,
+            status=status,
+            priority=priority,
+            tag=tag,
+            search_query=search,
+            sort_by=sort_by,
+        )
+        return await fb.service.list_items(filter_, page=page, per_page=per_page)
+
+    @router.get("/{item_id}", response_model=FeedbackItem)
+    async def get_feedback_item(item_id: str) -> FeedbackItem:
+        """Get a single feedback item."""
+        fb = get_feedback()
+        item = await fb.service.get_item(item_id)
+        if item is None:
+            raise NotFoundError("Feedback item not found")
+        return item
+
+    @router.put("/{item_id}/status", response_model=FeedbackItem)
+    async def update_status(item_id: str, body: UpdateStatusRequest) -> FeedbackItem:
+        """Update the status of a feedback item."""
+        fb = get_feedback()
+        try:
+            return await fb.service.update_status(item_id, body.status)
+        except ValueError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    @router.put("/{item_id}/priority", response_model=FeedbackItem)
+    async def update_priority(item_id: str, body: UpdatePriorityRequest) -> FeedbackItem:
+        """Update the priority of a feedback item."""
+        fb = get_feedback()
+        try:
+            return await fb.service.update_priority(item_id, body.priority)
+        except ValueError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    @router.post("/{item_id}/vote", response_model=FeedbackItem)
+    async def vote_feedback(item_id: str, body: VoteRequest) -> FeedbackItem:
+        """Vote on a feedback item."""
+        fb = get_feedback()
+        try:
+            return await fb.service.vote(item_id, body.user_id)
+        except ValueError as exc:
+            raise ValidationError(str(exc)) from exc
+
+    @router.delete("/{item_id}/vote", response_model=FeedbackItem)
+    async def unvote_feedback(item_id: str, body: VoteRequest) -> FeedbackItem:
+        """Remove a vote from a feedback item."""
+        fb = get_feedback()
+        try:
+            return await fb.service.unvote(item_id, body.user_id)
+        except ValueError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    @router.post("/{item_id}/comments", response_model=FeedbackComment, status_code=201)
+    async def add_comment(item_id: str, body: AddCommentRequest) -> FeedbackComment:
+        """Add a comment to a feedback item."""
+        fb = get_feedback()
+        try:
+            return await fb.service.add_comment(item_id, body.author_id, body.content)
+        except ValueError as exc:
+            raise ValidationError(str(exc)) from exc
+
+    @router.get("/{item_id}/comments", response_model=list[FeedbackComment])
+    async def list_comments(item_id: str) -> list[FeedbackComment]:
+        """List comments for a feedback item."""
+        fb = get_feedback()
+        try:
+            return await fb.service.get_comments(item_id)
+        except ValueError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    return router

feedback/service.py

@@ -0,0 +1,260 @@
+"""Core business logic for the feedback system."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from errors import NotFoundError, ValidationError
+
+from feedback.models import (
+    FeedbackCategory,
+    FeedbackComment,
+    FeedbackConfig,
+    FeedbackFilter,
+    FeedbackItem,
+    FeedbackPriority,
+    FeedbackStats,
+    FeedbackStatus,
+    FeedbackVote,
+    PaginatedResult,
+)
+from feedback.store import FeedbackStore
+
+_TERMINAL_STATUSES = {FeedbackStatus.DONE, FeedbackStatus.DECLINED}
+
+
+class FeedbackService:
+    """Orchestrates feedback operations with business rules."""
+
+    def __init__(self, store: FeedbackStore, *, config: FeedbackConfig) -> None:
+        self._store = store
+        self._config = config
+
+    async def submit(
+        self,
+        title: str,
+        description: str,
+        category: FeedbackCategory | str,
+        *,
+        author_id: str | None = None,
+        author_email: str | None = None,
+        tags: list[str] | None = None,
+    ) -> FeedbackItem:
+        """Create a new feedback item.
+
+        Raises:
+            ValueError: If anonymous submissions are disabled and no author is given,
+                        or if the category is not allowed.
+        """
+        resolved_category = FeedbackCategory(category) if isinstance(category, str) else category
+
+        if resolved_category not in self._config.categories:
+            msg = f"Category '{resolved_category.value}' is not allowed"
+            raise ValidationError(msg)
+
+        is_anonymous = author_id is None and author_email is None
+        if is_anonymous and not self._config.allow_anonymous:
+            msg = "Anonymous feedback is not allowed"
+            raise ValidationError(msg)
+
+        now = datetime.now(UTC)
+        item = FeedbackItem(
+            id=uuid.uuid4().hex,
+            title=title,
+            description=description,
+            category=resolved_category,
+            author_id=author_id,
+            author_email=author_email,
+            is_anonymous=is_anonymous,
+            tags=tags or [],
+            created_at=now,
+            updated_at=now,
+        )
+        return await self._store.save_item(item)
+
+    async def update_status(self, item_id: str, status: FeedbackStatus | str) -> FeedbackItem:
+        """Change the status of a feedback item.
+
+        Raises:
+            ValueError: If the item does not exist.
+        """
+        item = await self._store.get_item(item_id)
+        if item is None:
+            msg = f"Feedback item '{item_id}' not found"
+            raise NotFoundError(msg)
+
+        resolved_status = FeedbackStatus(status) if isinstance(status, str) else status
+        now = datetime.now(UTC)
+        resolved_at = now if resolved_status in _TERMINAL_STATUSES else item.resolved_at
+
+        updated = item.model_copy(
+            update={
+                "status": resolved_status,
+                "updated_at": now,
+                "resolved_at": resolved_at,
+            }
+        )
+        return await self._store.save_item(updated)
+
+    async def update_priority(self, item_id: str, priority: FeedbackPriority | str) -> FeedbackItem:
+        """Change the priority of a feedback item.
+
+        Raises:
+            ValueError: If the item does not exist.
+        """
+        item = await self._store.get_item(item_id)
+        if item is None:
+            msg = f"Feedback item '{item_id}' not found"
+            raise NotFoundError(msg)
+
+        resolved_priority = FeedbackPriority(priority) if isinstance(priority, str) else priority
+        updated = item.model_copy(
+            update={
+                "priority": resolved_priority,
+                "updated_at": datetime.now(UTC),
+            }
+        )
+        return await self._store.save_item(updated)
+
+    async def vote(self, item_id: str, user_id: str) -> FeedbackItem:
+        """Cast a vote on a feedback item.
+
+        Raises:
+            ValueError: If the item does not exist, or the user has reached the vote limit.
+        """
+        item = await self._store.get_item(item_id)
+        if item is None:
+            msg = f"Feedback item '{item_id}' not found"
+            raise NotFoundError(msg)
+
+        existing = await self._store.get_vote(item_id, user_id)
+        if existing is not None:
+            return item  # Already voted, idempotent
+
+        user_vote_count = await self._store.count_user_votes(user_id)
+        if user_vote_count >= self._config.max_votes_per_user:
+            msg = f"User '{user_id}' has reached the maximum of {self._config.max_votes_per_user} votes"
+            raise ValidationError(msg)
+
+        vote = FeedbackVote(item_id=item_id, user_id=user_id)
+        await self._store.save_vote(vote)
+
+        updated = item.model_copy(update={"vote_count": item.vote_count + 1})
+        return await self._store.save_item(updated)
+
+    async def unvote(self, item_id: str, user_id: str) -> FeedbackItem:
+        """Remove a vote from a feedback item.
+
+        Raises:
+            ValueError: If the item does not exist.
+        """
+        item = await self._store.get_item(item_id)
+        if item is None:
+            msg = f"Feedback item '{item_id}' not found"
+            raise NotFoundError(msg)
+
+        removed = await self._store.remove_vote(item_id, user_id)
+        if not removed:
+            return item  # No vote to remove, idempotent
+
+        updated = item.model_copy(update={"vote_count": max(0, item.vote_count - 1)})
+        return await self._store.save_item(updated)
+
+    async def add_comment(self, item_id: str, author_id: str, content: str) -> FeedbackComment:
+        """Add a comment to a feedback item.
+
+        Raises:
+            ValueError: If the item does not exist or content is empty.
+        """
+        item = await self._store.get_item(item_id)
+        if item is None:
+            msg = f"Feedback item '{item_id}' not found"
+            raise NotFoundError(msg)
+
+        if not content.strip():
+            msg = "Comment content cannot be empty"
+            raise ValidationError(msg)
+
+        comment = FeedbackComment(
+            id=uuid.uuid4().hex,
+            item_id=item_id,
+            author_id=author_id,
+            content=content,
+        )
+        return await self._store.save_comment(comment)
+
+    async def list_items(
+        self,
+        filter_: FeedbackFilter | None = None,
+        *,
+        page: int = 1,
+        per_page: int = 20,
+    ) -> PaginatedResult:
+        """List feedback items with pagination, filtering, and sorting."""
+        filter_ = filter_ or FeedbackFilter()
+        return await self._store.list_items(filter_, page=page, per_page=per_page)
+
+    async def get_item(self, item_id: str) -> FeedbackItem | None:
+        """Get a single feedback item by ID."""
+        return await self._store.get_item(item_id)
+
+    async def get_comments(self, item_id: str) -> list[FeedbackComment]:
+        """List comments for a feedback item.
+
+        Raises:
+            ValueError: If the item does not exist.
+        """
+        item = await self._store.get_item(item_id)
+        if item is None:
+            msg = f"Feedback item '{item_id}' not found"
+            raise NotFoundError(msg)
+        return await self._store.list_comments(item_id)
+
+    async def get_stats(self) -> FeedbackStats:
+        """Get aggregate feedback statistics."""
+        return await self._store.get_stats()
+
+    async def merge(self, source_id: str, target_id: str) -> FeedbackItem:
+        """Merge duplicate feedback by folding source votes into target.
+
+        The source item is marked as merged and its votes are transferred.
+
+        Raises:
+            ValueError: If source or target does not exist, or they are the same.
+        """
+        if source_id == target_id:
+            msg = "Cannot merge an item into itself"
+            raise ValidationError(msg)
+
+        source = await self._store.get_item(source_id)
+        if source is None:
+            msg = f"Source feedback item '{source_id}' not found"
+            raise NotFoundError(msg)
+
+        target = await self._store.get_item(target_id)
+        if target is None:
+            msg = f"Target feedback item '{target_id}' not found"
+            raise NotFoundError(msg)
+
+        # Mark source as merged
+        merged_source = source.model_copy(
+            update={
+                "merged_into": target_id,
+                "status": FeedbackStatus.DECLINED,
+                "updated_at": datetime.now(UTC),
+            }
+        )
+        await self._store.save_item(merged_source)
+
+        # Transfer vote count to target
+        new_vote_count = target.vote_count + source.vote_count
+        merged_tags = list(dict.fromkeys([*target.tags, *source.tags]))
+        updated_target = target.model_copy(
+            update={
+                "vote_count": new_vote_count,
+                "tags": merged_tags,
+                "updated_at": datetime.now(UTC),
+            }
+        )
+        return await self._store.save_item(updated_target)

feedback/store.py

@@ -0,0 +1,177 @@
+"""Storage backends for feedback items, votes, and comments."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from feedback.models import (
+    FeedbackComment,
+    FeedbackFilter,
+    FeedbackItem,
+    FeedbackSortBy,
+    FeedbackStats,
+    FeedbackVote,
+    PaginatedResult,
+)
+
+
+class FeedbackStore(ABC):
+    """Abstract base class for feedback persistence."""
+
+    @abstractmethod
+    async def save_item(self, item: FeedbackItem) -> FeedbackItem: ...
+
+    @abstractmethod
+    async def get_item(self, item_id: str) -> FeedbackItem | None: ...
+
+    @abstractmethod
+    async def delete_item(self, item_id: str) -> bool: ...
+
+    @abstractmethod
+    async def list_items(
+        self, filter_: FeedbackFilter, *, page: int = 1, per_page: int = 20
+    ) -> PaginatedResult: ...
+
+    @abstractmethod
+    async def save_vote(self, vote: FeedbackVote) -> bool: ...
+
+    @abstractmethod
+    async def remove_vote(self, item_id: str, user_id: str) -> bool: ...
+
+    @abstractmethod
+    async def get_vote(self, item_id: str, user_id: str) -> FeedbackVote | None: ...
+
+    @abstractmethod
+    async def count_user_votes(self, user_id: str) -> int: ...
+
+    @abstractmethod
+    async def save_comment(self, comment: FeedbackComment) -> FeedbackComment: ...
+
+    @abstractmethod
+    async def list_comments(self, item_id: str) -> list[FeedbackComment]: ...
+
+    @abstractmethod
+    async def get_stats(self) -> FeedbackStats: ...
+
+    @abstractmethod
+    async def list_all_items(self) -> list[FeedbackItem]: ...
+
+
+class InMemoryStore(FeedbackStore):
+    """Dict-backed in-memory store for testing and development."""
+
+    def __init__(self) -> None:
+        self._items: dict[str, FeedbackItem] = {}
+        self._votes: dict[str, FeedbackVote] = {}  # key: "item_id:user_id"
+        self._comments: dict[str, FeedbackComment] = {}
+
+    async def save_item(self, item: FeedbackItem) -> FeedbackItem:
+        self._items[item.id] = item
+        return item
+
+    async def get_item(self, item_id: str) -> FeedbackItem | None:
+        return self._items.get(item_id)
+
+    async def delete_item(self, item_id: str) -> bool:
+        if item_id in self._items:
+            del self._items[item_id]
+            return True
+        return False
+
+    async def list_items(
+        self, filter_: FeedbackFilter, *, page: int = 1, per_page: int = 20
+    ) -> PaginatedResult:
+        items = [i for i in self._items.values() if i.merged_into is None]
+        items = self._apply_filter(items, filter_)
+        items = self._apply_sort(items, filter_.sort_by)
+
+        total = len(items)
+        start = (max(1, page) - 1) * per_page
+        end = start + per_page
+        page_items = items[start:end]
+
+        return PaginatedResult(items=page_items, total=total, page=page, per_page=per_page)
+
+    async def save_vote(self, vote: FeedbackVote) -> bool:
+        key = f"{vote.item_id}:{vote.user_id}"
+        if key in self._votes:
+            return False
+        self._votes[key] = vote
+        return True
+
+    async def remove_vote(self, item_id: str, user_id: str) -> bool:
+        key = f"{item_id}:{user_id}"
+        if key in self._votes:
+            del self._votes[key]
+            return True
+        return False
+
+    async def get_vote(self, item_id: str, user_id: str) -> FeedbackVote | None:
+        return self._votes.get(f"{item_id}:{user_id}")
+
+    async def count_user_votes(self, user_id: str) -> int:
+        return sum(1 for v in self._votes.values() if v.user_id == user_id)
+
+    async def save_comment(self, comment: FeedbackComment) -> FeedbackComment:
+        self._comments[comment.id] = comment
+        return comment
+
+    async def list_comments(self, item_id: str) -> list[FeedbackComment]:
+        comments = [c for c in self._comments.values() if c.item_id == item_id]
+        comments.sort(key=lambda c: c.created_at)
+        return comments
+
+    async def get_stats(self) -> FeedbackStats:
+        items = [i for i in self._items.values() if i.merged_into is None]
+        by_category: dict[str, int] = {}
+        by_status: dict[str, int] = {}
+        by_priority: dict[str, int] = {}
+        resolution_hours: list[float] = []
+
+        for item in items:
+            by_category[item.category.value] = by_category.get(item.category.value, 0) + 1
+            by_status[item.status.value] = by_status.get(item.status.value, 0) + 1
+            by_priority[item.priority.value] = by_priority.get(item.priority.value, 0) + 1
+            if item.resolved_at is not None:
+                delta = item.resolved_at - item.created_at
+                resolution_hours.append(delta.total_seconds() / 3600)
+
+        avg_hours = sum(resolution_hours) / len(resolution_hours) if resolution_hours else None
+
+        return FeedbackStats(
+            total=len(items),
+            by_category=by_category,
+            by_status=by_status,
+            by_priority=by_priority,
+            avg_resolution_hours=avg_hours,
+        )
+
+    async def list_all_items(self) -> list[FeedbackItem]:
+        return list(self._items.values())
+
+    @staticmethod
+    def _apply_filter(items: list[FeedbackItem], filter_: FeedbackFilter) -> list[FeedbackItem]:
+        if filter_.category is not None:
+            items = [i for i in items if i.category == filter_.category]
+        if filter_.status is not None:
+            items = [i for i in items if i.status == filter_.status]
+        if filter_.priority is not None:
+            items = [i for i in items if i.priority == filter_.priority]
+        if filter_.tag is not None:
+            items = [i for i in items if filter_.tag in i.tags]
+        if filter_.search_query:
+            query = filter_.search_query.lower()
+            items = [i for i in items if query in i.title.lower() or query in i.description.lower()]
+        return items
+
+    @staticmethod
+    def _apply_sort(items: list[FeedbackItem], sort_by: FeedbackSortBy) -> list[FeedbackItem]:
+        match sort_by:
+            case FeedbackSortBy.NEWEST:
+                return sorted(items, key=lambda i: i.created_at, reverse=True)
+            case FeedbackSortBy.OLDEST:
+                return sorted(items, key=lambda i: i.created_at)
+            case FeedbackSortBy.VOTES:
+                return sorted(items, key=lambda i: i.vote_count, reverse=True)
+            case _:
+                return items

msaas_feedback-0.1.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: msaas-feedback
+Version: 0.1.0
+Summary: User feedback and feature request management for SaaS
+Requires-Python: >=3.12
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110.0; extra == 'fastapi'

msaas_feedback-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+feedback/__init__.py,sha256=4_Kq2VVD6L91dRv58OY9OQzCri772qtSMQziBqnfLHE,1052
+feedback/analysis.py,sha256=s8w6O1bmVJuLwBUmDSQ0o09aVZ561NgdM3ddhZ-Bq14,2305
+feedback/config.py,sha256=aVqsekzOXpHHG7JkIIZCjkbmvLB-Ba9t4VvpupbC_BY,1871
+feedback/models.py,sha256=Sc-PqHXU6nqW6qAsz2-eBPEddE-eIVNePvjInWBCfqE,3163
+feedback/router.py,sha256=Mp2i1Z90iwsItoJq1UeHLymfqra2UiThQZ-_F2syyYQ,7291
+feedback/service.py,sha256=YkY0UsPjXY8ZUfXkEdAm6Ai-X8FK1tTxPgzmRGSjSdA,8999
+feedback/store.py,sha256=WBXR-zSuFqF-I1m87lnhKVhgKgjthh-cZc1nt4qkdHM,6348
+msaas_feedback-0.1.0.dist-info/METADATA,sha256=onTA3TR1c3UQjmEKZW4ZgVG5PMm7DNvQRZB7_8_6hz4,555
+msaas_feedback-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+msaas_feedback-0.1.0.dist-info/RECORD,,

msaas_feedback-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any