fastapi-plugin-notification 0.2.0__tar.gz → 0.2.1__tar.gz

{fastapi_plugin_notification-0.2.0 → fastapi_plugin_notification-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-plugin-notification
-Version: 0.2.0
+Version: 0.2.1
 Summary: Notification plugin for FastAPI projects using FastAPI SDK and Postmark provider.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -30,6 +30,7 @@ A notification plugin for FastAPI that integrates with FastAPI SDK and Postmark
   - Mark notifications as seen/acknowledged
   - Get unseen notification count
 - 🗞️ **Digests**: Daily or weekly digest emails, grouped by category
+- 🧹 **Retention**: Configurable cleanup of notifications past their retention window
 - 🚀 **FastAPI Integration**: Full CRUD API endpoints with authentication
 - 📦 **PyPI Package**: Easy to install and use in any FastAPI project
 
@@ -78,12 +79,15 @@ Full setup — client, router and dependencies — is in the [Quick Start](docs/
 | [Quick Start](docs/quickstart.md) | Initialize the client, mount the router, send your first notification |
 | [Usage Examples](docs/usage.md) | Storing, sending, listing and acknowledging notifications |
 | [Notification Digests](docs/digests.md) | Daily/weekly digests, category grouping, example payload, Postmark Mustachio templates |
+| [Cleaning Up Old Notifications](docs/cleanup.md) | Retention window and permanently removing stale notifications |
 | [API Endpoints](docs/api-endpoints.md) | HTTP routes with request parameters and response bodies |
 | [Model Structure](docs/model.md) | Fields on `NotificationModel` |
 | [Ownership and Permissions](docs/ownership.md) | Claim-based ownership and required permissions |
 | [Configuration](docs/configuration.md) | Router options, template variables, error handling |
 | [Development](docs/development.md) | Local setup and running the tests |
 
+Release history is in the [Changelog](CHANGELOG.md).
+
 ## License
 
 MIT License - see LICENSE file for details

{fastapi_plugin_notification-0.2.0 → fastapi_plugin_notification-0.2.1}/README.md

@@ -12,6 +12,7 @@ A notification plugin for FastAPI that integrates with FastAPI SDK and Postmark
   - Mark notifications as seen/acknowledged
   - Get unseen notification count
 - 🗞️ **Digests**: Daily or weekly digest emails, grouped by category
+- 🧹 **Retention**: Configurable cleanup of notifications past their retention window
 - 🚀 **FastAPI Integration**: Full CRUD API endpoints with authentication
 - 📦 **PyPI Package**: Easy to install and use in any FastAPI project
 
@@ -60,12 +61,15 @@ Full setup — client, router and dependencies — is in the [Quick Start](docs/
 | [Quick Start](docs/quickstart.md) | Initialize the client, mount the router, send your first notification |
 | [Usage Examples](docs/usage.md) | Storing, sending, listing and acknowledging notifications |
 | [Notification Digests](docs/digests.md) | Daily/weekly digests, category grouping, example payload, Postmark Mustachio templates |
+| [Cleaning Up Old Notifications](docs/cleanup.md) | Retention window and permanently removing stale notifications |
 | [API Endpoints](docs/api-endpoints.md) | HTTP routes with request parameters and response bodies |
 | [Model Structure](docs/model.md) | Fields on `NotificationModel` |
 | [Ownership and Permissions](docs/ownership.md) | Claim-based ownership and required permissions |
 | [Configuration](docs/configuration.md) | Router options, template variables, error handling |
 | [Development](docs/development.md) | Local setup and running the tests |
 
+Release history is in the [Changelog](CHANGELOG.md).
+
 ## License
 
 MIT License - see LICENSE file for details

{fastapi_plugin_notification-0.2.0 → fastapi_plugin_notification-0.2.1}/fastapi_plugin_notification/__init__.py

@@ -29,4 +29,4 @@ __all__ = [
     "create_notification_router",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"

{fastapi_plugin_notification-0.2.0 → fastapi_plugin_notification-0.2.1}/fastapi_plugin_notification/client.py

@@ -18,6 +18,8 @@ _DIGEST_PERIOD_DELTAS = {
     DigestPeriod.WEEK: timedelta(days=7),
 }
 
+DEFAULT_RETENTION_DAYS = 30
+
 
 class NotificationClient:
     """Client for storing and optionally sending notifications."""
@@ -28,6 +30,7 @@ class NotificationClient:
         default_template_id: Optional[int] = None,
         default_digest_template_id: Optional[int] = None,
         digest_template_ids: Optional[Dict[str, int]] = None,
+        retention_days: int = DEFAULT_RETENTION_DAYS,
     ):
         """Initialize the notification client.
 
@@ -36,11 +39,14 @@ class NotificationClient:
             default_template_id: Default Postmark template ID to use for emails
             default_digest_template_id: Default Postmark template ID for digests
             digest_template_ids: Per-period digest template IDs (keys: day, week)
+            retention_days: Age in days after which notifications become eligible
+                for cleanup (default: 30)
         """
         self.postmark_provider = postmark_provider
         self.default_template_id = default_template_id
         self.default_digest_template_id = default_digest_template_id
         self.digest_template_ids = digest_template_ids or {}
+        self.retention_days = retention_days
 
     async def store_notification(
         self,
@@ -543,3 +549,53 @@ class NotificationClient:
             claims=claims,
         )
         return result
+
+    async def cleanup_old_notifications(
+        self,
+        db_engine: AIOEngine,
+        retention_days: Optional[int] = None,
+        include_unseen: bool = False,
+        dry_run: bool = False,
+    ) -> int:
+        """Permanently remove notifications older than the retention window.
+
+        Unlike the controller's soft delete, this removes documents from the
+        database so the collection does not grow indefinitely. Unseen
+        notifications are preserved unless ``include_unseen`` is set, while
+        soft deleted notifications are always purged once old enough.
+
+        Args:
+            db_engine: MongoDB engine instance from odmantic
+            retention_days: Age in days to keep (defaults to the client's
+                ``retention_days``)
+            include_unseen: Also remove notifications the user has not seen
+            dry_run: Count the matching notifications without deleting them
+
+        Returns:
+            Number of notifications deleted, or that would be deleted for a dry run
+        """
+        days = self.retention_days if retention_days is None else retention_days
+        cutoff = datetime.now(timezone.utc).replace(tzinfo=None) - timedelta(days=days)
+
+        query: Dict[str, Any] = {"created_at": {"$lt": cutoff}}
+        if not include_unseen:
+            query["$or"] = [{"seen": True}, {"deleted": True}]
+
+        collection = db_engine.database[NotificationModel.__collection__]
+
+        if dry_run:
+            count = await collection.count_documents(query)
+            logger.info(
+                "Cleanup dry run: %s notifications older than %s days would be deleted",
+                count,
+                days,
+            )
+            return count
+
+        result = await collection.delete_many(query)
+        logger.info(
+            "Deleted %s notifications older than %s days",
+            result.deleted_count,
+            days,
+        )
+        return result.deleted_count

{fastapi_plugin_notification-0.2.0 → fastapi_plugin_notification-0.2.1}/fastapi_plugin_notification.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-plugin-notification
-Version: 0.2.0
+Version: 0.2.1
 Summary: Notification plugin for FastAPI projects using FastAPI SDK and Postmark provider.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -30,6 +30,7 @@ A notification plugin for FastAPI that integrates with FastAPI SDK and Postmark
   - Mark notifications as seen/acknowledged
   - Get unseen notification count
 - 🗞️ **Digests**: Daily or weekly digest emails, grouped by category
+- 🧹 **Retention**: Configurable cleanup of notifications past their retention window
 - 🚀 **FastAPI Integration**: Full CRUD API endpoints with authentication
 - 📦 **PyPI Package**: Easy to install and use in any FastAPI project
 
@@ -78,12 +79,15 @@ Full setup — client, router and dependencies — is in the [Quick Start](docs/
 | [Quick Start](docs/quickstart.md) | Initialize the client, mount the router, send your first notification |
 | [Usage Examples](docs/usage.md) | Storing, sending, listing and acknowledging notifications |
 | [Notification Digests](docs/digests.md) | Daily/weekly digests, category grouping, example payload, Postmark Mustachio templates |
+| [Cleaning Up Old Notifications](docs/cleanup.md) | Retention window and permanently removing stale notifications |
 | [API Endpoints](docs/api-endpoints.md) | HTTP routes with request parameters and response bodies |
 | [Model Structure](docs/model.md) | Fields on `NotificationModel` |
 | [Ownership and Permissions](docs/ownership.md) | Claim-based ownership and required permissions |
 | [Configuration](docs/configuration.md) | Router options, template variables, error handling |
 | [Development](docs/development.md) | Local setup and running the tests |
 
+Release history is in the [Changelog](CHANGELOG.md).
+
 ## License
 
 MIT License - see LICENSE file for details

{fastapi_plugin_notification-0.2.0 → fastapi_plugin_notification-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-plugin-notification"
-version = "0.2.0"
+version = "0.2.1"
 description = "Notification plugin for FastAPI projects using FastAPI SDK and Postmark provider."
 readme = "README.md"
 requires-python = ">=3.12"

{fastapi_plugin_notification-0.2.0 → fastapi_plugin_notification-0.2.1}/tests/test_client.py

@@ -722,3 +722,205 @@ class TestSendNotificationDigest:
 
         assert digest["count"] == 1
         assert digest["email_sent"] is False
+
+
+class TestCleanupOldNotifications:
+    """Tests for cleanup_old_notifications method."""
+
+    async def _create_notification_at(
+        self,
+        notification_client,
+        db_engine,
+        mock_claims,
+        name: str,
+        created_at: datetime,
+        seen: bool = False,
+        deleted: bool = False,
+    ) -> NotificationModel:
+        notification = await notification_client.store_notification(
+            db_engine=db_engine,
+            name=name,
+            user_id="user_123",
+            user_email="user@example.com",
+            claims=mock_claims,
+        )
+        notification.created_at = created_at
+        notification.updated_at = created_at
+        notification.seen = seen
+        notification.deleted = deleted
+        await db_engine.save(notification)
+        return notification
+
+    async def _remaining_names(self, db_engine) -> set:
+        collection = db_engine.database["notification"]
+        return {doc["name"] async for doc in collection.find({})}
+
+    def test_default_retention_is_thirty_days(self, notification_client):
+        """Test the client defaults to a 30 day retention window."""
+        assert notification_client.retention_days == 30
+
+    def test_retention_days_configurable_on_init(self, postmark_provider):
+        """Test the retention window can be overridden when instantiating."""
+        client = NotificationClient(
+            postmark_provider=postmark_provider,
+            retention_days=90,
+        )
+        assert client.retention_days == 90
+
+    @pytest.mark.asyncio
+    async def test_cleanup_removes_old_seen_notifications(
+        self, notification_client, db_engine, mock_claims
+    ):
+        """Test old seen notifications are hard deleted."""
+        now = datetime.now(timezone.utc).replace(tzinfo=None)
+
+        await self._create_notification_at(
+            notification_client,
+            db_engine,
+            mock_claims,
+            "old_seen",
+            now - timedelta(days=31),
+            seen=True,
+        )
+        await self._create_notification_at(
+            notification_client,
+            db_engine,
+            mock_claims,
+            "recent_seen",
+            now - timedelta(days=2),
+            seen=True,
+        )
+
+        deleted = await notification_client.cleanup_old_notifications(
+            db_engine=db_engine
+        )
+
+        assert deleted == 1
+        assert await self._remaining_names(db_engine) == {"recent_seen"}
+
+    @pytest.mark.asyncio
+    async def test_cleanup_preserves_old_unseen_notifications(
+        self, notification_client, db_engine, mock_claims
+    ):
+        """Test unseen notifications survive cleanup by default."""
+        now = datetime.now(timezone.utc).replace(tzinfo=None)
+
+        await self._create_notification_at(
+            notification_client,
+            db_engine,
+            mock_claims,
+            "old_unseen",
+            now - timedelta(days=60),
+            seen=False,
+        )
+
+        deleted = await notification_client.cleanup_old_notifications(
+            db_engine=db_engine
+        )
+
+        assert deleted == 0
+        assert await self._remaining_names(db_engine) == {"old_unseen"}
+
+    @pytest.mark.asyncio
+    async def test_cleanup_removes_old_unseen_when_included(
+        self, notification_client, db_engine, mock_claims
+    ):
+        """Test include_unseen also removes old unread notifications."""
+        now = datetime.now(timezone.utc).replace(tzinfo=None)
+
+        await self._create_notification_at(
+            notification_client,
+            db_engine,
+            mock_claims,
+            "old_unseen",
+            now - timedelta(days=60),
+            seen=False,
+        )
+        await self._create_notification_at(
+            notification_client,
+            db_engine,
+            mock_claims,
+            "recent_unseen",
+            now - timedelta(days=1),
+            seen=False,
+        )
+
+        deleted = await notification_client.cleanup_old_notifications(
+            db_engine=db_engine,
+            include_unseen=True,
+        )
+
+        assert deleted == 1
+        assert await self._remaining_names(db_engine) == {"recent_unseen"}
+
+    @pytest.mark.asyncio
+    async def test_cleanup_purges_old_soft_deleted_notifications(
+        self, notification_client, db_engine, mock_claims
+    ):
+        """Test soft deleted notifications are purged even when unseen."""
+        now = datetime.now(timezone.utc).replace(tzinfo=None)
+
+        await self._create_notification_at(
+            notification_client,
+            db_engine,
+            mock_claims,
+            "old_soft_deleted",
+            now - timedelta(days=45),
+            seen=False,
+            deleted=True,
+        )
+
+        deleted = await notification_client.cleanup_old_notifications(
+            db_engine=db_engine
+        )
+
+        assert deleted == 1
+        assert await self._remaining_names(db_engine) == set()
+
+    @pytest.mark.asyncio
+    async def test_cleanup_respects_per_call_retention_days(
+        self, notification_client, db_engine, mock_claims
+    ):
+        """Test retention_days argument overrides the client default."""
+        now = datetime.now(timezone.utc).replace(tzinfo=None)
+
+        await self._create_notification_at(
+            notification_client,
+            db_engine,
+            mock_claims,
+            "ten_days_old",
+            now - timedelta(days=10),
+            seen=True,
+        )
+
+        deleted = await notification_client.cleanup_old_notifications(
+            db_engine=db_engine,
+            retention_days=7,
+        )
+
+        assert deleted == 1
+        assert await self._remaining_names(db_engine) == set()
+
+    @pytest.mark.asyncio
+    async def test_cleanup_dry_run_reports_without_deleting(
+        self, notification_client, db_engine, mock_claims
+    ):
+        """Test dry_run returns the count without removing anything."""
+        now = datetime.now(timezone.utc).replace(tzinfo=None)
+
+        await self._create_notification_at(
+            notification_client,
+            db_engine,
+            mock_claims,
+            "old_seen",
+            now - timedelta(days=31),
+            seen=True,
+        )
+
+        deleted = await notification_client.cleanup_old_notifications(
+            db_engine=db_engine,
+            dry_run=True,
+        )
+
+        assert deleted == 1
+        assert await self._remaining_names(db_engine) == {"old_seen"}