# `PhoenixKit.Notifications`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.102/lib/phoenix_kit/notifications/notifications.ex#L1)

Per-user notifications driven by `PhoenixKit.Activity`.

When an activity is logged with a `target_uuid` that differs from the
`actor_uuid`, a row is inserted into `phoenix_kit_notifications` for the
target user. The user sees it in the bell dropdown (`count_unread/1`,
`recent_for_user/2`) and in the inbox at `/notifications` (`list_for_user/2`).
Each row carries its own `seen_at` and `dismissed_at` — the same activity
can be "seen but not dismissed" for one user and "unseen" for another.

The whole feature is gated by the global `notifications_enabled` setting
(default `"true"`); when `"false"`, `maybe_create_from_activity/1` is a no-op.

# `count_unread`

Counts undismissed, unseen notifications for a user. Drives the badge.

# `dismiss`

Dismisses a single notification. Idempotent.

# `dismiss_all`

Bulk-dismisses all undismissed notifications. Returns `{count, nil}`.

# `enabled?`

Is the notifications feature enabled? Default `true`.

# `get_notification`

Fetches one notification scoped to the recipient. Returns `nil` if missing.

# `list_for_user`

Returns `{notifications, total_count}` for the given user, newest first.

Options:
  * `:page` (default 1) / `:per_page` (default 25)
  * `:status` — `:unread` (seen_at nil) | `:all` (default)
  * `:include_dismissed` — include dismissed rows (default `false`)

# `mark_all_seen`

Bulk-marks all unseen notifications as seen. Returns `{count, nil}`.

# `mark_seen`

Marks a single notification as seen. Idempotent — already-seen rows return
`{:ok, notification}` unchanged.

# `maybe_create_from_activity`

Inserts a notification for the activity's target user, if the rules allow it.

Returns one of:
  * `{:ok, %Notification{}}` — row created; broadcast on the per-user topic
  * `{:ok, :skipped}` — filtered out (no target, self-action, feature disabled)
  * `{:error, changeset}` — insert failed (logged, never raised)

# `prune`

Deletes notifications whose underlying activity is older than `days`.

# `recent_for_user`

Returns the N most-recent undismissed notifications for a user.

Drives the bell dropdown. Activity (and actor) are preloaded.

# `retention_days`

Retention period in days. Falls back to activity retention if unset.

---

*Consult [api-reference.md](api-reference.md) for complete listing*