Thin wrapper around PhoenixKit.Activity.log/1 for the billing module.
Centralizes the Code.ensure_loaded?/1 guard, the rescue clause, and
the default metadata (module: "billing", actor_role) so every LV
call site stays consistent and logging failures never crash the
caller.
Where to call this
Activity logging happens at the LiveView layer, on the {:ok, _}
branch of each successful mutation — never inside context functions.
The LiveView is where the actor is unambiguously known (via
socket.assigns[:phoenix_kit_current_scope]) and where user intent is
clear ("admin clicked Save"). Context functions stay pure and keep
stable signatures.
Action strings
Actions follow "billing.<resource>_<verb>", e.g.
"billing.order_created", "billing.invoice_voided".
PII safety
Only ever pass PII-safe metadata: resource uuids, status strings, amounts, currency codes, order/invoice numbers, counts. Never log email, phone, person names, card data, tokens, or free text.
Summary
Types
Return value of log/2. Mirrors PhoenixKit.Activity.log/1 plus the unavailable/rescued sentinels.
Functions
Extracts the acting user's primary role-name string from the socket's
scope (first entry of cached_roles). Returns nil when no role is
cached. Role names are not PII.
Extracts the acting user's uuid from the LiveView socket assigns.
Logs a billing activity entry via PhoenixKit.Activity.
Types
Return value of log/2. Mirrors PhoenixKit.Activity.log/1 plus the unavailable/rescued sentinels.
Functions
@spec actor_role(Phoenix.LiveView.Socket.t()) :: String.t() | nil
Extracts the acting user's primary role-name string from the socket's
scope (first entry of cached_roles). Returns nil when no role is
cached. Role names are not PII.
@spec actor_uuid(Phoenix.LiveView.Socket.t()) :: String.t() | nil
Extracts the acting user's uuid from the LiveView socket assigns.
Reads socket.assigns[:phoenix_kit_current_scope] (the billing
convention; the production live_session :phoenix_kit_admin on_mount
hook populates it). Returns nil for an unauthenticated/absent scope.
@spec log( String.t(), keyword() ) :: log_result()
Logs a billing activity entry via PhoenixKit.Activity.
No-ops (returns :activity_unavailable) when core's PhoenixKit.Activity
module isn't loaded, and rescues/catches any failure so the calling
LiveView event handler can't crash on a logging error.
Options
:actor_uuid— uuid of the acting user (useactor_uuid/1):actor_role— role-name string of the actor (useactor_role/1):mode— defaults to"manual":resource_type— e.g."order","invoice","currency":resource_uuid— uuid of the mutated record:target_uuid— second-party uuid where applicable:metadata— extra PII-safe metadata map (merged over defaults)