Metadata-Version: 2.5
Name: entirius-django-notifications
Version: 0.2.0
Summary: In-app, email and Google Chat notifications with escalation for Entirius
Project-URL: Homepage, https://docs.entirius.com/
Project-URL: Documentation, https://github.com/entirius/entirius-django-notifications/tree/develop/docs
Project-URL: Repository, https://github.com/entirius/entirius-django-notifications
Project-URL: Changelog, https://github.com/entirius/entirius-django-notifications/blob/develop/CHANGELOG.md
Project-URL: Issues, https://github.com/entirius/entirius-django-notifications/issues
Author: Entirius
Maintainer-email: Piotr Brzozowski <piotrb@entirius.com>, Paweł Kiełt <cptshooter12@gmail.com>, Mateusz Baran <mateuszbaranpv@gmail.com>, Michał Kloczkowski <michal@kloczkowski.pl>
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: celery,django,ecommerce,email,entirius,escalation,google-chat,notifications
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Requires-Dist: celery>=5.3
Requires-Dist: django>=4.2
Requires-Dist: djangorestframework-simplejwt>=5.3
Requires-Dist: djangorestframework>=3.14
Requires-Dist: drf-spectacular>=0.27
Requires-Dist: entirius-django-regional>=2.0.1
Requires-Dist: entirius-django-utils>=2.0.0
Requires-Dist: entirius-py-idx-normalizator>=2.0.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: email
Requires-Dist: entirius-django-email>=4.0.1; extra == 'email'
Provides-Extra: googlechat
Requires-Dist: entirius-py-googlechat>=0.1.0; extra == 'googlechat'
Provides-Extra: test
Requires-Dist: dj-database-url>=2.0; extra == 'test'
Requires-Dist: entirius-django-email>=4.0.1; extra == 'test'
Requires-Dist: entirius-py-googlechat>=0.1.0; extra == 'test'
Requires-Dist: factory-boy; extra == 'test'
Requires-Dist: psycopg[binary]>=3.1; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-django; extra == 'test'
Requires-Dist: respx; extra == 'test'
Description-Content-Type: text/markdown

# entirius-django-notifications

A Django module for staff notifications in Entirius, the open-source modular ecommerce platform.
It shows in-app notifications in the CMS and escalates them to email and Google Chat when nobody reads them.

[![PyPI](https://img.shields.io/pypi/v/entirius-django-notifications.svg)](https://pypi.org/project/entirius-django-notifications/)
[![Python](https://img.shields.io/pypi/pyversions/entirius-django-notifications.svg)](https://pypi.org/project/entirius-django-notifications/)
[![License: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](https://github.com/entirius/entirius-django-notifications/blob/develop/LICENSE)

## What it does

- Creates in-app notifications with a severity and a subject reference through one function, `notify()`.
- Counts repeats of an unread notification inside a dedup window instead of creating new rows.
- Escalates unread notifications along per-channel rules to email and Google Chat, each step once.
- Keeps real sends behind a gate outside production (`NOTIFICATIONS_ALLOW_LIVE_SENDS`).
- Exposes an admin API (JWT, Pydantic schemas, OpenAPI) for the CMS notification bar.

## Installation

```shell
uv add entirius-django-notifications
pip install entirius-django-notifications
```

Optional extras: `entirius-django-notifications[email]` (the email step, through `entirius-django-email`),
`entirius-django-notifications[googlechat]` (the Google Chat step, through `entirius-py-googlechat`).
Without an extra its step is recorded as `skipped`. The email step also needs `django_email` in `INSTALLED_APPS`.

```python
INSTALLED_APPS = [
    # ...
    "django_utils",
    "django_regional",
    "django_notifications",
]

# main/urls.py
urlpatterns.append(path("", include("django_notifications.urls")))
```

The module needs a Celery worker consuming the `notifications_default` queue and the escalation beat entry.
Settings (`NOTIFICATIONS_DEDUP_WINDOW_S`, `NOTIFICATIONS_DELIVERY_STALE_MINUTES`,
`NOTIFICATIONS_QUEUE_DEFAULT`, `NOTIFICATIONS_ALLOW_LIVE_SENDS`) and the bootstrap order: `docs/install.md` —
https://github.com/entirius/entirius-django-notifications/blob/develop/docs/install.md

## Quick start

```python
from django_notifications.services.notify_service import notify

notify(
    channel_idx="my-channel",
    recipient_role="sales",
    severity="high",  # a value of django_notifications.enums.Severity
    subject_ref="leads.Company:42",
    title="A reply needs an answer",
)
```

The notification appears in the CMS bar at once; escalation follows the rules of the channel.

## Requirements

- Python 3.11 or newer, Django 4.2 or newer.
- PostgreSQL.
- A Celery worker consuming the `notifications_default` queue, and Celery beat.
- Entirius packages pulled in: `entirius-django-utils`, `entirius-django-regional`,
  `entirius-py-idx-normalizator`.

## Documentation

- Module docs: https://github.com/entirius/entirius-django-notifications/tree/develop/docs
- Entirius documentation: https://docs.entirius.com/
- Changelog: https://github.com/entirius/entirius-django-notifications/blob/develop/CHANGELOG.md

## Part of Entirius

This module runs inside the Entirius backend service (Volkanos); other modules call `notify()` when a person must act.

- Backend service: https://github.com/entirius/entirius-service-volkanos
- Docker harness: https://github.com/entirius/entirius-zeno
- Sibling modules: https://github.com/entirius/entirius-django-communicator, https://github.com/entirius/entirius-django-leads,
  https://github.com/entirius/entirius-django-email

## Development

```shell
make install     # sync dependencies (uv, incl. extras)
make check       # lint + format check (ruff)
make test        # test suite (pytest; PostgreSQL through DATABASE_URL)
```

Development and agent instructions: https://github.com/entirius/entirius-django-notifications/blob/develop/AGENTS.md

## License

Mozilla Public License 2.0 (MPL-2.0) — see https://github.com/entirius/entirius-django-notifications/blob/develop/LICENSE.
