# `PhoenixKit.Users.Sessions`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v2.22.16/lib/phoenix_kit/users/sessions.ex#L1)

Context for managing user sessions in PhoenixKit.

This module provides functions for listing, viewing, and managing active user sessions.
It's primarily used by the admin interface to monitor and control user sessions.

## Functions

- `list_active_sessions/0` - Get all currently active sessions
- `list_user_sessions/1` - Get all active sessions for a specific user
- `get_session_info/1` - Get detailed information about a specific session
- `revoke_session/1` - Revoke a specific session token
- `revoke_user_sessions/1` - Revoke all sessions for a specific user
- `count_active_sessions/0` - Get total count of active sessions

## Session Information

Each session includes:
- User information (id, email, status)
- Session creation time
- Session token (first 8 chars for identification)
- Session age and validity status

# `count_active_sessions`

Counts the total number of active sessions.

## Examples

    iex> count_active_sessions()
    15

# `get_session_info`

Gets detailed information about a specific session by token ID.

## Examples

    iex> get_session_info("019b5704-3680-7b95-...")
    %{token_uuid: "019b5704-...", user: %User{}, created_at: ~N[...], ...}

    iex> get_session_info("019b5704-0000-0000-...")
    nil

# `get_session_stats`

Gets session statistics including total, unique users, expired sessions etc.

## Examples

    iex> get_session_stats()
    %{
      total_active: 15,
      unique_users: 8,
      expired_sessions: 5,
      sessions_today: 3
    }

# `list_active_sessions`

Lists all currently active sessions with user information.

Returns a list of maps containing session and user details.

## Examples

    iex> list_active_sessions()
    [
      %{
        token_uuid: "019b5704-3680-7b95-...",
        token_preview: "abc12345",
        user: %User{uuid: "019b5704-...", email: "user@example.com"},
        created_at: ~N[2024-01-01 12:00:00],
        expires_at: ~N[2024-03-02 12:00:00],
        is_current: false
      }
    ]

# `list_sessions_paginated`

One page of sessions for the admin list, filtered and paginated in SQL.

Options:

  * `:scope` — `:active` (default), `:today` or `:expired`, as
    `list_active_sessions/1`
  * `:search` — case-insensitive match on the user's email or the token
    preview (the first 8 hex chars shown in the UI)
  * `:user_status` — `"all"` (default), `"active"`, `"inactive"`,
    `"confirmed"` or `"pending"`
  * `:page` / `:per_page` — defaults `1` / `20`

Returns `%{sessions: [...], total_count: n, total_pages: n}`. The page is
clamped into `[1, total_pages]` before the offset is applied, so a stale
link past the end shows the last page rather than an empty one — mirror
the returned `page` back into the assigns.

# `list_user_device_sessions`

Lists a user's active sessions enriched with device info, for the
self-service "Active Sessions" UI.

Each session's `(ip_address, user_agent_hash)` is matched against the
user's `KnownDevice` history to recover browser/OS/location/last-active
(session tokens store only the hashed UA, never the raw string). Sessions
predating fingerprinting — or from a device never recorded as "known" —
degrade gracefully to an "Unknown device" with nil fields.

`current_token` is the raw session token of the browser making the
request (from the session's `"user_token"`); the matching row is flagged
`is_current: true` so the UI can mark it and omit its "Sign out" button.

# `list_user_sessions`

Lists all active sessions for a specific user.

## Examples

    iex> list_user_sessions(%User{uuid: "019b5704-..."})
    [%{token_uuid: "019b5704-...", user: %User{}, created_at: ~N[...], ...}]

# `revoke_other_user_sessions`

Revokes all of a user's sessions except the one identified by
`current_token` (kept so the acting browser stays signed in). Returns the
number revoked. With a nil token, revokes every session for the user.

# `revoke_session`

Revokes a specific session by token ID.

Returns :ok if successful, {:error, :not_found} if session doesn't exist.

## Examples

    iex> revoke_session("019b5704-3680-7b95-...")
    :ok

    iex> revoke_session("019b5704-0000-0000-...")
    {:error, :not_found}

# `revoke_user_session`

Revokes one of a user's *own* sessions by token uuid.

Scoped to `user` so a user can never revoke another user's session by
guessing a token uuid. Returns `:ok` or `{:error, :not_found}`.

# `revoke_user_sessions`

Revokes all sessions for a specific user.

Returns the number of sessions revoked.

## Examples

    iex> revoke_user_sessions(%User{uuid: "019b5704-..."})
    3

---

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