feat: recipe timeline backend api (#1685)

* added recipe_timeline_events table to db

* added schema and routes for recipe timeline events

* added missing mixin and fixed update schema

* added tests

* adjusted migration revision tree

* updated alembic revision test

* added initial timeline event for new recipes

* added additional tests

* added event bus support

* renamed event_dt to timestamp

* add timeline_events to ignore list

* run code-gen

* use new test routes implementation

* use doc string syntax

* moved event type enum from db to schema

Co-authored-by: Hayden <64056131+hay-kot@users.noreply.github.com>

mealie/db/models/recipe/recipe.py

@@ -18,6 +18,7 @@ from .ingredient import RecipeIngredient
 from .instruction import RecipeInstruction
 from .note import Note
 from .nutrition import Nutrition
+from .recipe_timeline import RecipeTimelineEvent
 from .settings import RecipeSettings
 from .shared import RecipeShareTokenModel
 from .tag import recipes_to_tags
@@ -82,6 +83,10 @@ class RecipeModel(SqlAlchemyBase, BaseMixins):
         "RecipeComment", back_populates="recipe", cascade="all, delete, delete-orphan"
     )
 
+    timeline_events: list[RecipeTimelineEvent] = orm.relationship(
+        "RecipeTimelineEvent", back_populates="recipe", cascade="all, delete, delete-orphan"
+    )
+
     # Mealie Specific
     settings = orm.relationship("RecipeSettings", uselist=False, cascade="all, delete-orphan")
     tags = orm.relationship("Tag", secondary=recipes_to_tags, back_populates="recipes")
@@ -117,6 +122,7 @@ class RecipeModel(SqlAlchemyBase, BaseMixins):
             "recipe_instructions",
             "settings",
             "comments",
+            "timeline_events",
         }
 
     @validates("name")

mealie/db/models/recipe/recipe_timeline.py

@@ -0,0 +1,38 @@
+from datetime import datetime
+
+from sqlalchemy import Column, DateTime, ForeignKey, String
+from sqlalchemy.orm import relationship
+
+from .._model_base import BaseMixins, SqlAlchemyBase
+from .._model_utils import auto_init
+from .._model_utils.guid import GUID
+
+
+class RecipeTimelineEvent(SqlAlchemyBase, BaseMixins):
+    __tablename__ = "recipe_timeline_events"
+    id = Column(GUID, primary_key=True, default=GUID.generate)
+
+    # Parent Recipe
+    recipe_id = Column(GUID, ForeignKey("recipes.id"), nullable=False)
+    recipe = relationship("RecipeModel", back_populates="timeline_events")
+
+    # Related User (Actor)
+    user_id = Column(GUID, ForeignKey("users.id"), nullable=False)
+    user = relationship("User", back_populates="recipe_timeline_events", single_parent=True, foreign_keys=[user_id])
+
+    # General Properties
+    subject = Column(String, nullable=False)
+    message = Column(String)
+    event_type = Column(String)
+    image = Column(String)
+
+    # Timestamps
+    timestamp = Column(DateTime)
+
+    @auto_init()
+    def __init__(
+        self,
+        timestamp=None,
+        **_,
+    ) -> None:
+        self.timestamp = timestamp or datetime.now()

mealie/db/models/users/users.py

@@ -52,6 +52,7 @@ class User(SqlAlchemyBase, BaseMixins):
 
     tokens = orm.relationship(LongLiveToken, **sp_args)
     comments = orm.relationship("RecipeComment", **sp_args)
+    recipe_timeline_events = orm.relationship("RecipeTimelineEvent", **sp_args)
     password_reset_tokens = orm.relationship("PasswordResetModel", **sp_args)
 
     owned_recipes_id = Column(GUID, ForeignKey("recipes.id"))

mealie/repos/repository_factory.py

@@ -21,6 +21,7 @@ from mealie.db.models.recipe.category import Category
 from mealie.db.models.recipe.comment import RecipeComment
 from mealie.db.models.recipe.ingredient import IngredientFoodModel, IngredientUnitModel
 from mealie.db.models.recipe.recipe import RecipeModel
+from mealie.db.models.recipe.recipe_timeline import RecipeTimelineEvent
 from mealie.db.models.recipe.shared import RecipeShareTokenModel
 from mealie.db.models.recipe.tag import Tag
 from mealie.db.models.recipe.tool import Tool
@@ -49,6 +50,7 @@ from mealie.schema.recipe import Recipe, RecipeCommentOut, RecipeToolOut
 from mealie.schema.recipe.recipe_category import CategoryOut, TagOut
 from mealie.schema.recipe.recipe_ingredient import IngredientFood, IngredientUnit
 from mealie.schema.recipe.recipe_share_token import RecipeShareToken
+from mealie.schema.recipe.recipe_timeline_events import RecipeTimelineEventOut
 from mealie.schema.reports.reports import ReportEntryOut, ReportOut
 from mealie.schema.server import ServerTask
 from mealie.schema.user import GroupInDB, LongLiveTokenInDB, PrivateUser
@@ -123,6 +125,10 @@ class AllRepositories:
     def recipe_share_tokens(self) -> RepositoryGeneric[RecipeShareToken, RecipeShareTokenModel]:
         return RepositoryGeneric(self.session, PK_ID, RecipeShareTokenModel, RecipeShareToken)
 
+    @cached_property
+    def recipe_timeline_events(self) -> RepositoryGeneric[RecipeTimelineEventOut, RecipeTimelineEvent]:
+        return RepositoryGeneric(self.session, PK_ID, RecipeTimelineEvent, RecipeTimelineEventOut)
+
     # ================================================================
     # User
 

mealie/routes/recipe/__init__.py

@@ -1,6 +1,6 @@
 from fastapi import APIRouter
 
-from . import all_recipe_routes, bulk_actions, comments, recipe_crud_routes, shared_routes
+from . import all_recipe_routes, bulk_actions, comments, recipe_crud_routes, shared_routes, timeline_events
 
 prefix = "/recipes"
 
@@ -12,3 +12,4 @@ router.include_router(recipe_crud_routes.router)
 router.include_router(comments.router, prefix=prefix, tags=["Recipe: Comments"])
 router.include_router(bulk_actions.router, prefix=prefix, tags=["Recipe: Bulk Exports"])
 router.include_router(shared_routes.router, prefix=prefix, tags=["Recipe: Shared"])
+router.include_router(timeline_events.events_router, prefix=prefix, tags=["Recipe: Timeline"])

mealie/routes/recipe/timeline_events.py

@@ -0,0 +1,146 @@
+from functools import cached_property
+
+from fastapi import Depends, HTTPException
+from pydantic import UUID4
+
+from mealie.routes._base import BaseCrudController, controller
+from mealie.routes._base.mixins import HttpRepo
+from mealie.routes._base.routers import MealieCrudRoute, UserAPIRouter
+from mealie.schema.recipe.recipe import Recipe
+from mealie.schema.recipe.recipe_timeline_events import (
+    RecipeTimelineEventCreate,
+    RecipeTimelineEventIn,
+    RecipeTimelineEventOut,
+    RecipeTimelineEventPagination,
+    RecipeTimelineEventUpdate,
+)
+from mealie.schema.response.pagination import PaginationQuery
+from mealie.services import urls
+from mealie.services.event_bus_service.event_types import EventOperation, EventRecipeTimelineEventData, EventTypes
+
+events_router = UserAPIRouter(route_class=MealieCrudRoute, prefix="/{slug}/timeline/events")
+
+
+@controller(events_router)
+class RecipeTimelineEventsController(BaseCrudController):
+    @cached_property
+    def repo(self):
+        return self.repos.recipe_timeline_events
+
+    @cached_property
+    def mixins(self):
+        return HttpRepo[RecipeTimelineEventCreate, RecipeTimelineEventOut, RecipeTimelineEventUpdate](
+            self.repo,
+            self.logger,
+            self.registered_exceptions,
+        )
+
+    def get_recipe_from_slug(self, slug: str) -> Recipe:
+        recipe = self.repos.recipes.by_group(self.group_id).get_one(slug)
+        if not recipe or self.group_id != recipe.group_id:
+            raise HTTPException(status_code=404, detail="recipe not found")
+
+        return recipe
+
+    @events_router.get("", response_model=RecipeTimelineEventPagination)
+    def get_all(self, slug: str, q: PaginationQuery = Depends(PaginationQuery)):
+        recipe = self.get_recipe_from_slug(slug)
+        recipe_filter = f"recipe_id = {recipe.id}"
+
+        if q.query_filter:
+            q.query_filter = f"({q.query_filter}) AND {recipe_filter}"
+
+        else:
+            q.query_filter = recipe_filter
+
+        response = self.repo.page_all(
+            pagination=q,
+            override=RecipeTimelineEventOut,
+        )
+
+        response.set_pagination_guides(events_router.url_path_for("get_all", slug=slug), q.dict())
+        return response
+
+    @events_router.post("", response_model=RecipeTimelineEventOut, status_code=201)
+    def create_one(self, slug: str, data: RecipeTimelineEventIn):
+        # if the user id is not specified, use the currently-authenticated user
+        data.user_id = data.user_id or self.user.id
+
+        recipe = self.get_recipe_from_slug(slug)
+        event_data = data.cast(RecipeTimelineEventCreate, recipe_id=recipe.id)
+        event = self.mixins.create_one(event_data)
+
+        self.publish_event(
+            event_type=EventTypes.recipe_updated,
+            document_data=EventRecipeTimelineEventData(
+                operation=EventOperation.create, recipe_slug=recipe.slug, recipe_timeline_event_id=event.id
+            ),
+            message=self.t(
+                "notifications.generic-updated-with-url",
+                name=recipe.name,
+                url=urls.recipe_url(slug, self.settings.BASE_URL),
+            ),
+        )
+
+        return event
+
+    @events_router.get("/{item_id}", response_model=RecipeTimelineEventOut)
+    def get_one(self, slug: str, item_id: UUID4):
+        recipe = self.get_recipe_from_slug(slug)
+        event = self.mixins.get_one(item_id)
+
+        # validate that this event belongs to the given recipe slug
+        if event.recipe_id != recipe.id:
+            raise HTTPException(status_code=404, detail="recipe event not found")
+
+        return event
+
+    @events_router.put("/{item_id}", response_model=RecipeTimelineEventOut)
+    def update_one(self, slug: str, item_id: UUID4, data: RecipeTimelineEventUpdate):
+        recipe = self.get_recipe_from_slug(slug)
+        event = self.mixins.get_one(item_id)
+
+        # validate that this event belongs to the given recipe slug
+        if event.recipe_id != recipe.id:
+            raise HTTPException(status_code=404, detail="recipe event not found")
+
+        event = self.mixins.update_one(data, item_id)
+
+        self.publish_event(
+            event_type=EventTypes.recipe_updated,
+            document_data=EventRecipeTimelineEventData(
+                operation=EventOperation.update, recipe_slug=recipe.slug, recipe_timeline_event_id=event.id
+            ),
+            message=self.t(
+                "notifications.generic-updated-with-url",
+                name=recipe.name,
+                url=urls.recipe_url(slug, self.settings.BASE_URL),
+            ),
+        )
+
+        return event
+
+    @events_router.delete("/{item_id}", response_model=RecipeTimelineEventOut)
+    def delete_one(self, slug: str, item_id: UUID4):
+        recipe = self.get_recipe_from_slug(slug)
+        event = self.mixins.get_one(item_id)
+
+        # validate that this event belongs to the given recipe slug
+        if event.recipe_id != recipe.id:
+            raise HTTPException(status_code=404, detail="recipe event not found")
+
+        event = self.mixins.delete_one(item_id)
+
+        self.publish_event(
+            event_type=EventTypes.recipe_updated,
+            document_data=EventRecipeTimelineEventData(
+                operation=EventOperation.delete, recipe_slug=recipe.slug, recipe_timeline_event_id=event.id
+            ),
+            message=self.t(
+                "notifications.generic-updated-with-url",
+                name=recipe.name,
+                url=urls.recipe_url(slug, self.settings.BASE_URL),
+            ),
+        )
+
+        return event

mealie/schema/recipe/__init__.py

@@ -70,6 +70,13 @@ from .recipe_scraper import ScrapeRecipe, ScrapeRecipeTest
 from .recipe_settings import RecipeSettings
 from .recipe_share_token import RecipeShareToken, RecipeShareTokenCreate, RecipeShareTokenSave, RecipeShareTokenSummary
 from .recipe_step import IngredientReferences, RecipeStep
+from .recipe_timeline_events import (
+    RecipeTimelineEventCreate,
+    RecipeTimelineEventIn,
+    RecipeTimelineEventOut,
+    RecipeTimelineEventPagination,
+    RecipeTimelineEventUpdate,
+)
 from .recipe_tool import RecipeToolCreate, RecipeToolOut, RecipeToolResponse, RecipeToolSave
 from .request_helpers import RecipeSlug, RecipeZipTokenResponse, SlugResponse, UpdateImageResponse
 
@@ -78,6 +85,11 @@ __all__ = [
     "RecipeToolOut",
     "RecipeToolResponse",
     "RecipeToolSave",
+    "RecipeTimelineEventCreate",
+    "RecipeTimelineEventIn",
+    "RecipeTimelineEventOut",
+    "RecipeTimelineEventPagination",
+    "RecipeTimelineEventUpdate",
     "RecipeAsset",
     "RecipeSettings",
     "RecipeShareToken",

mealie/schema/recipe/recipe_timeline_events.py

@@ -0,0 +1,53 @@
+from datetime import datetime
+from enum import Enum
+
+from pydantic import UUID4
+
+from mealie.schema._mealie.mealie_model import MealieModel
+from mealie.schema.response.pagination import PaginationBase
+
+
+class TimelineEventType(Enum):
+    system = "system"
+    info = "info"
+    comment = "comment"
+
+
+class RecipeTimelineEventIn(MealieModel):
+    user_id: UUID4 | None = None
+    """can be inferred in some contexts, so it's not required"""
+
+    subject: str
+    event_type: TimelineEventType
+
+    message: str | None = None
+    image: str | None = None
+
+    timestamp: datetime = datetime.now()
+
+    class Config:
+        use_enum_values = True
+
+
+class RecipeTimelineEventCreate(RecipeTimelineEventIn):
+    recipe_id: UUID4
+    user_id: UUID4
+
+
+class RecipeTimelineEventUpdate(MealieModel):
+    subject: str
+    message: str | None = None
+    image: str | None = None
+
+
+class RecipeTimelineEventOut(RecipeTimelineEventCreate):
+    id: UUID4
+    created_at: datetime
+    update_at: datetime
+
+    class Config:
+        orm_mode = True
+
+
+class RecipeTimelineEventPagination(PaginationBase):
+    items: list[RecipeTimelineEventOut]

mealie/services/event_bus_service/event_types.py

@@ -64,6 +64,7 @@ class EventDocumentType(Enum):
     shopping_list_item = "shopping_list_item"
     recipe = "recipe"
     recipe_bulk_report = "recipe_bulk_report"
+    recipe_timeline_event = "recipe_timeline_event"
     tag = "tag"
 
 
@@ -123,6 +124,12 @@ class EventRecipeBulkReportData(EventDocumentDataBase):
     report_id: UUID4
 
 
+class EventRecipeTimelineEventData(EventDocumentDataBase):
+    document_type = EventDocumentType.recipe_timeline_event
+    recipe_slug: str
+    recipe_timeline_event_id: UUID4
+
+
 class EventTagData(EventDocumentDataBase):
     document_type = EventDocumentType.tag
     tag_id: UUID4

mealie/services/recipe/recipe_service.py

@@ -1,5 +1,6 @@
 import json
 import shutil
+from datetime import datetime
 from pathlib import Path
 from shutil import copytree, rmtree
 from typing import Union
@@ -13,6 +14,7 @@ from mealie.schema.recipe.recipe import CreateRecipe, Recipe
 from mealie.schema.recipe.recipe_ingredient import RecipeIngredient
 from mealie.schema.recipe.recipe_settings import RecipeSettings
 from mealie.schema.recipe.recipe_step import RecipeStep
+from mealie.schema.recipe.recipe_timeline_events import RecipeTimelineEventCreate, TimelineEventType
 from mealie.schema.user.user import GroupInDB, PrivateUser
 from mealie.services._base_service import BaseService
 from mealie.services.recipe.recipe_data_service import RecipeDataService
@@ -132,7 +134,19 @@ class RecipeService(BaseService):
             else:
                 data.settings = RecipeSettings()
 
-        return self.repos.recipes.create(data)
+        new_recipe = self.repos.recipes.create(data)
+
+        # create first timeline entry
+        timeline_event_data = RecipeTimelineEventCreate(
+            user_id=new_recipe.user_id,
+            recipe_id=new_recipe.id,
+            subject="Recipe Created",
+            event_type=TimelineEventType.system,
+            timestamp=new_recipe.created_at or datetime.now(),
+        )
+
+        self.repos.recipe_timeline_events.create(timeline_event_data)
+        return new_recipe
 
     def create_from_zip(self, archive: UploadFile, temp_path: Path) -> Recipe:
         """