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

Activity feed for tracking business-level actions across the platform.

Provides a simple API for logging and querying activities. Any module can call
`Activity.log/1` to record an action. The admin dashboard shows a real-time
activity stream.

## Usage

    PhoenixKit.Activity.log(%{
      action: "post.created",
      actor_uuid: user.uuid,
      resource_type: "post",
      resource_uuid: post.uuid,
      metadata: %{"title" => post.title}
    })

## Action naming convention

Use dotted format: `resource.verb` — e.g., "post.created", "comment.liked",
"user.registered", "password.changed", "role.assigned".

# `action_badge_color`

Returns a CSS badge class based on the action verb.

# `count`

Counts activities matching the given filters.

# `get_entry`

Gets a single activity entry by UUID with preloaded associations.

# `get_entry!`

Gets a single activity entry by UUID. Raises if not found.

# `list`

Lists activities with filtering and pagination.

## Options

- `:action` — filter by action string (exact match or prefix with "post.*")
- `:actor_uuid` — filter by who performed the action
- `:resource_type` — filter by resource type
- `:target_uuid` — filter by who was affected
- `:since` — filter activities after this datetime
- `:until` — filter activities before this datetime
- `:page` — page number (default: 1)
- `:per_page` — items per page (default: 50)
- `:preload` — associations to preload (default: [:actor])

# `list_action_types`

Returns distinct action types that have been logged.

# `list_for_user`

Lists activities for a specific user (as actor).

# `list_modes`

Returns distinct modes that have been logged.

# `list_modules`

Returns distinct modules that have been logged.

# `list_resource_types`

Returns distinct resource types that have been logged.

# `log`

Logs an activity.

## Required fields

- `:action` — dotted action string (e.g., "post.created")

## Optional fields

- `:actor_uuid` — who performed the action
- `:resource_type` — type of resource acted on
- `:resource_uuid` — UUID of the resource
- `:target_uuid` — who was affected (e.g., follow target)
- `:metadata` — map of additional context

Returns `{:ok, entry}` or `{:error, changeset}`. Failures are logged but never crash.

# `log_user_change`

Logs a user change with automatic from/to diff extraction from a changeset.

Extracts changed fields from the changeset and builds `field_from` / `field_to`
metadata pairs. Skips logging if nothing actually changed.

## Options

- `:actor_uuid` — who performed the action (default: the user's own UUID)
- `:target_uuid` — who was affected (default: nil)
- `:mode` — "auto" or "manual" (default: "auto")
- `:actor_role` — "user" or "admin" (default: "user")
- `:extra_metadata` — additional metadata to merge in (default: %{})
- `:skip_fields` — fields to exclude from diff (default: [:custom_fields])

# `mode_badge_color`

Returns a CSS badge class based on the mode.

# `prune`

Deletes activities older than the given number of days.

# `pubsub_topic`

PubSub topic for activity events.

# `recent`

Returns the N most recent activities.

# `resolve_resource_users`

Resolves resource info for entries where `resource_type` is "user".

Returns a map of `resource_uuid => %{email: ..., first_name: ..., last_name: ...}`.
Batch-queries to avoid N+1.

# `retention_days`

Returns the configured retention period in days.

---

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