[owl] Notification Scope to Audience Column Rename (#917)

haoshan98 · haoshan98 · commit 7058601d27cc · 2026-04-09T03:08:33.000Z
* Renamed column

* DB migration

* Enum retype
diff --git a/clients/python/src/jamaibase/types/__init__.py b/clients/python/src/jamaibase/types/__init__.py
@@ -87,12 +87,12 @@
     ModelProvider,
     ModelType,
     Notification_,
+    NotificationAudience,
     NotificationCreate,
     NotificationGroup_,
     NotificationGroupCreate,
     NotificationGroupRead,
     NotificationRead,
-    NotificationScope,
     NotificationType,
     OnPremProvider,
     Organization_,
diff --git a/clients/python/src/jamaibase/types/db.py b/clients/python/src/jamaibase/types/db.py
@@ -1323,7 +1323,7 @@ class ProjectKeyRead(ProjectKey_):
     pass
 
 
-class NotificationScope(StrEnum):
+class NotificationAudience(StrEnum):
     SYSTEM = "SYSTEM"
     ORGANIZATION = "ORGANIZATION"
     PROJECT = "PROJECT"
@@ -1356,8 +1356,8 @@ class NotificationType(StrEnum):
 
 
 class NotificationGroupCreate(_BaseModel):
-    scope: NotificationScope = Field(
-        description="Notification scope.",
+    audience: NotificationAudience = Field(
+        description="Notification audience.",
     )
     event_type: NotificationType = Field(
         description="Notification event type.",
diff --git a/services/api/src/owl/db/__init__.py b/services/api/src/owl/db/__init__.py
@@ -654,49 +654,72 @@ async def _migrate_notification_schema(engine: AsyncEngine) -> bool:
     Migrate NotificationGroup and Notification tables:
     - Add `subject_id` (FK→User SET NULL) and `message` columns to NotificationGroup
     - Rename `body` → `message` in Notification
+    - Rename `scope` → `audience` in NotificationGroup
+    - Retype audience column from PG enum `notificationscope` to `notificationaudience`, drop old enum
     """
     group_table = "NotificationGroup"
     notif_table = "Notification"
-
-    async with engine.connect() as conn:
-        group_has_message = await _check_column_exists(conn, group_table, "message")
-        group_has_subject = await _check_column_exists(conn, group_table, "subject_id")
-        notif_has_message = await _check_column_exists(conn, notif_table, "message")
-
-    if group_has_message and group_has_subject and notif_has_message:
-        return False
+    migrated = False
 
     async with engine.begin() as conn:
-        if not group_has_subject:
+        if not await _check_column_exists(conn, group_table, "subject_id"):
             await conn.execute(
                 text(
-                    f"""
-                    ALTER TABLE {SCHEMA}."{group_table}"
-                    ADD COLUMN subject_id TEXT DEFAULT NULL
-                    REFERENCES {SCHEMA}."User"(id) ON DELETE SET NULL;
-                    """
+                    f'ALTER TABLE {SCHEMA}."{group_table}" '
+                    f"ADD COLUMN subject_id TEXT DEFAULT NULL "
+                    f'REFERENCES {SCHEMA}."User"(id) ON DELETE SET NULL'
                 )
             )
-        if not group_has_message:
+            migrated = True
+
+        if not await _check_column_exists(conn, group_table, "message"):
             await conn.execute(
                 text(
-                    f"""
-                    ALTER TABLE {SCHEMA}."{group_table}"
-                    ADD COLUMN message TEXT NOT NULL DEFAULT '';
-                    """
+                    f'ALTER TABLE {SCHEMA}."{group_table}" '
+                    f"ADD COLUMN message TEXT NOT NULL DEFAULT ''"
                 )
             )
-        if not notif_has_message:
+            migrated = True
+
+        if await _check_column_exists(conn, notif_table, "body"):
+            if not await _check_column_exists(conn, notif_table, "message"):
+                await conn.execute(
+                    text(f'ALTER TABLE {SCHEMA}."{notif_table}" RENAME COLUMN body TO message')
+                )
+                migrated = True
+
+        if await _check_column_exists(conn, group_table, "scope"):
+            if not await _check_column_exists(conn, group_table, "audience"):
+                await conn.execute(
+                    text(f'ALTER TABLE {SCHEMA}."{group_table}" RENAME COLUMN scope TO audience')
+                )
+                migrated = True
+
+        # Retype audience column: PG enum notificationscope → notificationaudience
+        old_enum_exists = (
             await conn.execute(
                 text(
-                    f"""
-                    ALTER TABLE {SCHEMA}."{notif_table}"
-                    RENAME COLUMN body TO message;
-                    """
+                    f"SELECT EXISTS (SELECT 1 FROM pg_type t "
+                    f"JOIN pg_namespace n ON n.oid = t.typnamespace "
+                    f"WHERE n.nspname = '{SCHEMA}' AND t.typname = 'notificationscope')"
                 )
             )
-    logger.info("Successfully migrated notification schema (subject_id, message, body→message).")
-    return True
+        ).scalar()
+        if old_enum_exists:
+            await conn.execute(
+                text(
+                    f'ALTER TABLE {SCHEMA}."{group_table}" '
+                    f"ALTER COLUMN audience TYPE {SCHEMA}.notificationaudience "
+                    f"USING audience::text::{SCHEMA}.notificationaudience"
+                )
+            )
+            await conn.execute(text(f"DROP TYPE {SCHEMA}.notificationscope"))
+            logger.info("Retyped audience column and dropped old PG enum notificationscope.")
+            migrated = True
+
+    if migrated:
+        logger.info("Successfully migrated notification schema.")
+    return migrated
 
 
 async def migrate_db():
diff --git a/services/api/src/owl/db/models/oss.py b/services/api/src/owl/db/models/oss.py
@@ -48,7 +48,7 @@
     LanguageCodeList,
     ModelCapability,
     ModelType,
-    NotificationScope,
+    NotificationAudience,
     NotificationType,
     Page,
     PaymentState,
@@ -1597,8 +1597,8 @@ class NotificationGroup(_TableBase, table=True):
         primary_key=True,
         description="Notification group ID.",
     )
-    scope: NotificationScope = SqlField(
-        description="Notification scope.",
+    audience: NotificationAudience = SqlField(
+        description="Notification audience.",
     )
     event_type: NotificationType = SqlField(
         index=True,
diff --git a/services/api/src/owl/routers/notification.py b/services/api/src/owl/routers/notification.py
@@ -53,7 +53,7 @@ async def create_notification_group(
 
     # Fan-out in background
     intent = NotificationIntent(
-        scope=body.scope,
+        audience=body.audience,
         event_type=body.event_type,
         message=body.message,
         actor_id=body.actor_id,
diff --git a/services/api/src/owl/types/__init__.py b/services/api/src/owl/types/__init__.py
@@ -111,12 +111,12 @@
     MultiRowCompletionResponse,
     MultiRowDeleteRequest,
     Notification_,
+    NotificationAudience,
     NotificationCreate,
     NotificationGroup_,
     NotificationGroupCreate,
     NotificationGroupRead,
     NotificationRead,
-    NotificationScope,
     NotificationType,
     NullableStr,
     OkResponse,
diff --git a/services/api/src/owl/utils/notifications.py b/services/api/src/owl/utils/notifications.py
@@ -7,7 +7,7 @@
 
 from owl.db import SCHEMA, async_session
 from owl.db.models import NotificationGroup
-from owl.types import NotificationScope, NotificationType, ProductType, Role
+from owl.types import NotificationAudience, NotificationType, ProductType, Role
 from owl.utils.dates import now
 
 # Mapping from ProductType to NotificationType for limit alerts
@@ -49,7 +49,7 @@
 class NotificationIntent:
     """Plain data carrier for a notification to be dispatched in the background."""
 
-    scope: NotificationScope
+    audience: NotificationAudience
     event_type: NotificationType
     message: str
     actor_id: str | None = None
@@ -65,7 +65,7 @@ async def _fan_out_notifications(
     *,
     group_id: str,
     message: str,
-    scope: NotificationScope,
+    audience: NotificationAudience,
     organization_id: str | None = None,
     project_id: str | None = None,
     recipient_ids: list[str] | None = None,
@@ -76,27 +76,27 @@ async def _fan_out_notifications(
     base_vals = ":group_id, :message, '{}'::jsonb, :ts, :ts"
     params: dict = dict(group_id=group_id, message=message, ts=now())
 
-    if scope == NotificationScope.ORGANIZATION:
+    if audience == NotificationAudience.ORGANIZATION:
         where = "om.organization_id = :org_id"
         params["org_id"] = organization_id
         if notif_admin_only:
             where += " AND om.role = :role"
             params["role"] = Role.ADMIN.value
         sql = f'INSERT INTO {base_cols} SELECT om.user_id, {base_vals} FROM {SCHEMA}."OrgMember" om WHERE {where}'
 
-    elif scope == NotificationScope.PROJECT:
+    elif audience == NotificationAudience.PROJECT:
         where = "pm.project_id = :proj_id"
         params["proj_id"] = project_id
         if notif_admin_only:
             where += " AND pm.role = :role"
             params["role"] = Role.ADMIN.value
         sql = f'INSERT INTO {base_cols} SELECT pm.user_id, {base_vals} FROM {SCHEMA}."ProjectMember" pm WHERE {where}'
 
-    elif scope == NotificationScope.USER:
+    elif audience == NotificationAudience.USER:
         params["user_ids"] = recipient_ids or []
         sql = f'INSERT INTO {base_cols} SELECT u.id, {base_vals} FROM {SCHEMA}."User" u WHERE u.id = ANY(:user_ids)'
 
-    elif scope == NotificationScope.SYSTEM:
+    elif audience == NotificationAudience.SYSTEM:
         sql = f'INSERT INTO {base_cols} SELECT u.id, {base_vals} FROM {SCHEMA}."User" u'
 
     else:
@@ -115,7 +115,7 @@ async def dispatch_notification_intent(
         async with async_session() as session:
             if group_id is None:
                 group = NotificationGroup(
-                    scope=intent.scope,
+                    audience=intent.audience,
                     event_type=intent.event_type,
                     organization_id=intent.organization_id,
                     project_id=intent.project_id,
@@ -131,7 +131,7 @@ async def dispatch_notification_intent(
                 session,
                 group_id=group_id,
                 message=intent.message,
-                scope=intent.scope,
+                audience=intent.audience,
                 organization_id=intent.organization_id,
                 project_id=intent.project_id,
                 recipient_ids=intent.recipient_ids,
@@ -142,7 +142,7 @@ async def dispatch_notification_intent(
             if row_count == 0:
                 logger.warning(
                     f"No recipients resolved for notification {intent.event_type} "
-                    f"(scope={intent.scope}, org={intent.organization_id}, proj={intent.project_id})"
+                    f"(audience={intent.audience}, org={intent.organization_id}, proj={intent.project_id})"
                 )
             else:
                 logger.bind(
@@ -165,7 +165,7 @@ def notify_org_invitation(
     role: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.USER,
+        audience=NotificationAudience.USER,
         event_type=NotificationType.ORG_INVITATION,
         message=f"**{actor_name}** invited you to join organization **{org_name}** with role **{role}**.",
         actor_id=actor_id,
@@ -186,7 +186,7 @@ def notify_project_invitation(
     role: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.USER,
+        audience=NotificationAudience.USER,
         event_type=NotificationType.PROJECT_INVITATION,
         message=f"**{actor_name}** invited you to join project **{project_name}** with role **{role}**.",
         actor_id=actor_id,
@@ -206,7 +206,7 @@ def notify_org_invitation_revoked(
     org_name: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.USER,
+        audience=NotificationAudience.USER,
         event_type=NotificationType.ORG_INVITATION_REVOKED,
         message=f"**{actor_name}** revoked your invitation to organization **{org_name}**.",
         actor_id=actor_id,
@@ -226,7 +226,7 @@ def notify_project_invitation_revoked(
     organization_id: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.USER,
+        audience=NotificationAudience.USER,
         event_type=NotificationType.PROJECT_INVITATION_REVOKED,
         message=f"**{actor_name}** revoked your invitation to project **{project_name}**.",
         actor_id=actor_id,
@@ -245,7 +245,7 @@ def notify_org_member_joined(
     subject_name: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.ORGANIZATION,
+        audience=NotificationAudience.ORGANIZATION,
         event_type=NotificationType.ORG_MEMBER_JOINED,
         message=f"**{subject_name}** joined organization **{org_name}**.",
         subject_id=subject_id,
@@ -262,7 +262,7 @@ def notify_project_member_joined(
     subject_name: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.PROJECT,
+        audience=NotificationAudience.PROJECT,
         event_type=NotificationType.PROJECT_MEMBER_JOINED,
         message=f"**{subject_name}** joined project **{project_name}**.",
         subject_id=subject_id,
@@ -281,7 +281,7 @@ def notify_org_role_updated(
     role: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.USER,
+        audience=NotificationAudience.USER,
         event_type=NotificationType.ORG_ROLE_UPDATED,
         message=f"**{actor_name}** changed your role to **{role}** in organization **{org_name}**.",
         actor_id=actor_id,
@@ -302,7 +302,7 @@ def notify_project_role_updated(
     role: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.USER,
+        audience=NotificationAudience.USER,
         event_type=NotificationType.PROJECT_ROLE_UPDATED,
         message=f"**{actor_name}** changed your role to **{role}** in project **{project_name}**.",
         actor_id=actor_id,
@@ -323,7 +323,7 @@ def notify_org_owner_updated(
     subject_name: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.ORGANIZATION,
+        audience=NotificationAudience.ORGANIZATION,
         event_type=NotificationType.ORG_OWNER_UPDATED,
         message=f"**{actor_name}** transferred ownership of organization **{org_name}** to **{subject_name}**.",
         actor_id=actor_id,
@@ -343,7 +343,7 @@ def notify_project_owner_updated(
     subject_name: str,
 ) -> NotificationIntent:
     return NotificationIntent(
-        scope=NotificationScope.PROJECT,
+        audience=NotificationAudience.PROJECT,
         event_type=NotificationType.PROJECT_OWNER_UPDATED,
         message=f"**{actor_name}** transferred ownership of project **{project_name}** to **{subject_name}**.",
         actor_id=actor_id,
@@ -365,7 +365,7 @@ def notify_quota_limit(
     event_type = _PRODUCT_TO_NOTIFICATION_TYPE[product_type]
     label = _PRODUCT_LABEL[product_type]
     return NotificationIntent(
-        scope=NotificationScope.ORGANIZATION,
+        audience=NotificationAudience.ORGANIZATION,
         event_type=event_type,
         message=f"{label} usage has reached **{threshold}%** of quota ({usage:,.2f}/{quota:,.2f} {unit}).",
         organization_id=organization_id,
diff --git a/services/api/tests/routers/test_notifications.py b/services/api/tests/routers/test_notifications.py
