Merge pull request #475 from Itqan-community/feat/recitation-folder-visibility-and-default

Feat/recitation folder visibility and default

Author: Amr-Bendary

apps/content/api/portal/recitation_folders.py

@@ -29,6 +29,7 @@ class FolderOut(Schema):
     name_en: str | None = None
     slug: str
     is_default: bool
+    is_visible: bool
     tracks_count: int = 0
     created_at: AwareDatetime
     updated_at: AwareDatetime
@@ -46,6 +47,8 @@ class FolderCreateIn(Schema):
 class FolderPatchIn(Schema):
     name_ar: str | None = Field(default=None, max_length=255)
     name_en: str | None = Field(default=None, max_length=255)
+    is_visible: bool | None = None
+    is_default: bool | None = None
 
 
 # --- Helpers ---
@@ -107,7 +110,14 @@ def create_folder(request: Request, recitation_slug: str, data: FolderCreateIn):
     "recitations/{recitation_slug}/folders/{folder_slug}/",
     response={
         200: FolderOut,
-        400: NinjaErrorResponse[Literal["folder_name_required"]],
+        400: NinjaErrorResponse[
+            Literal[
+                "folder_name_required",
+                "cannot_hide_default_folder",
+                "cannot_unset_default_folder",
+                "cannot_set_hidden_folder_as_default",
+            ]
+        ],
         401: NinjaErrorResponse[Literal["authentication_error"]],
         403: NinjaErrorResponse[Literal["permission_denied"]],
         404: NinjaErrorResponse[Literal["recitation_not_found"]] | NinjaErrorResponse[Literal["folder_not_found"]],

apps/content/api/portal/recitations.py

@@ -65,6 +65,7 @@ class FolderOut(Schema):
     name: str
     slug: str
     is_default: bool
+    is_visible: bool
 
 
 class RecitationListOut(Schema):
@@ -136,7 +137,7 @@ def resolve_ayah_timings_url(obj: Asset) -> str | None:
         versions = list(obj.versions.filter(state=VersionStateChoice.PUBLISHED))
 
         version = None
-        if default_folder:
+        if default_folder and default_folder.is_visible:
             version = next((v for v in versions if v.name == default_folder.slug), None)
         if version is None:
             # Recitations created before folders may still have a legacy version row.

apps/content/api/public/recitation_list.py

@@ -6,7 +6,7 @@
 
 from apps.content.repositories.recitation import RecitationRepository
 from apps.content.services.recitation import RecitationService
-from apps.content.services.recitation_folder_resolution import sorted_asset_folders
+from apps.content.services.recitation_folder_resolution import visible_asset_folders
 from apps.core.ninja_utils.ordering_base import ordering
 from apps.core.ninja_utils.router import ItqanRouter
 from apps.core.ninja_utils.searching_base import searching
@@ -77,7 +77,7 @@ def resolve_surahs_count(obj):
     @staticmethod
     def resolve_folders(obj):
         # Lets a consumer discover which ?folder= values this recitation accepts.
-        return sorted_asset_folders(obj)
+        return visible_asset_folders(obj)
 
 
 class RecitationFilter(FilterSchema):

apps/content/api/public/recitation_track_list.py

@@ -133,6 +133,7 @@ def list_recitation_tracks(
         Q(asset__restricted_for_tenant=False),
         prefetch_timings=True,
         folder=folder,
+        require_visible_folder=True,
     )
 
     all_results = []

apps/content/api/tenant/recitation_list.py

@@ -6,7 +6,7 @@
 from apps.content.models import Asset
 from apps.content.repositories.recitation import RecitationRepository
 from apps.content.services.recitation import RecitationService
-from apps.content.services.recitation_folder_resolution import sorted_asset_folders
+from apps.content.services.recitation_folder_resolution import visible_asset_folders
 from apps.core.ninja_utils.ordering_base import ordering
 from apps.core.ninja_utils.request import Request
 from apps.core.ninja_utils.router import ItqanRouter
@@ -54,7 +54,7 @@ class RecitationListOut(Schema):
     @staticmethod
     def resolve_folders(obj):
         # Lets a consumer discover which ?folder= values this recitation accepts.
-        return sorted_asset_folders(obj)
+        return visible_asset_folders(obj)
 
 
 class RecitationFilter(FilterSchema):

apps/content/api/tenant/recitation_track_list.py

@@ -62,6 +62,8 @@ def list_recitation_tracks(request: Request, asset_id: int, folder: str | None =
     if not asset:
         raise Http404(str(_("No asset matches the given query.")))
 
-    tracks = service.get_asset_tracks(asset_id, request.publisher_q("asset__publisher"), folder=folder)
+    tracks = service.get_asset_tracks(
+        asset_id, request.publisher_q("asset__publisher"), folder=folder, require_visible_folder=True
+    )
 
     return tracks

apps/content/cache.py

@@ -3,6 +3,8 @@
 
 from django.core.cache import cache
 
+from apps.core.ninja_utils.paginations import DEFAULT_PAGE_SIZE, PUBLIC_RECITATION_MAX_PAGE_SIZE
+
 # Stands in for "caller did not name a folder" in cache keys, so the default-folder
 # response gets its own entry without a DB lookup to resolve the real slug.
 DEFAULT_FOLDER_CACHE_TOKEN = "__default__"
@@ -62,3 +64,24 @@ def invalidate_recitation_tracks_cache(asset_id: int) -> None:
             recitation_asset_meta_cache_key(asset_id),
         ]
     )
+
+
+def invalidate_recitation_folder_cache(asset_id: int, folder) -> None:
+    """
+    Bust public recitation caches after a folder's visibility or default status changes.
+
+    Per-folder response keys for every page size cannot be enumerated cheaply, so the
+    asset meta key is cleared to force rebuilds; known folder tokens are deleted when
+    present so the common first-page case is immediate.
+    """
+    invalidate_recitation_tracks_cache(asset_id)
+
+    tokens = {folder.slug, folder_cache_token(folder.slug)}
+    for name in (folder.name, folder.name_ar, folder.name_en):
+        if name:
+            tokens.add(folder_cache_token(name))
+
+    for token in tokens:
+        for page in (1,):
+            for page_size in (DEFAULT_PAGE_SIZE, PUBLIC_RECITATION_MAX_PAGE_SIZE):
+                cache.delete(recitation_response_cache_key(asset_id, page, page_size, token))

apps/content/migrations/0053_recitationfolder_is_visible.py

@@ -0,0 +1,19 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("content", "0052_merge_20260826_1701"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="recitationfolder",
+            name="is_visible",
+            field=models.BooleanField(
+                db_index=True,
+                default=True,
+                help_text="When false, the folder is omitted from public/tenant APIs and its timings export is withdrawn.",
+            ),
+        ),
+    ]

apps/content/models.py

@@ -712,6 +712,11 @@ class RecitationFolder(BaseModel):
         default=False,
         help_text="The folder served when the API caller does not specify one. Exactly one per asset.",
     )
+    is_visible = models.BooleanField(
+        default=True,
+        db_index=True,
+        help_text="When false, the folder is omitted from public/tenant APIs and its timings export is withdrawn.",
+    )
 
     class Meta:
         constraints = [

apps/content/repositories/recitation_folder.py

@@ -56,7 +56,7 @@ def create_folder(
             is_default=is_default,
         )
 
-    def update_folder(self, folder: RecitationFolder, fields: dict[str, str | None]) -> RecitationFolder:
+    def update_folder(self, folder: RecitationFolder, fields: dict[str, str | bool | None]) -> RecitationFolder:
         """Apply field updates to a folder and save it."""
         for field, value in fields.items():
             setattr(folder, field, value)