Sagents.Presence (Sagents v0.7.0)

Copy Markdown

Convenience wrappers for Phoenix.Presence operations.

This module provides thin wrappers around Phoenix.Presence to make presence tracking more convenient in agent-based applications. These functions always track the calling process (self()). Phoenix.Presence automatically cleans up presence entries when the tracked process terminates, so no manual cleanup is needed.

Examples

# Track presence in a LiveView mount
if connected?(socket) do
  {:ok, ref} = Sagents.Presence.track(
    MyApp.Presence,
    "conversation:123",
    "user-1",
    %{name: "Alice"}
  )
end

# Track presence in multiple topics from the same process
Sagents.Presence.track(MyApp.Presence, "conversation:123", "user-1")
Sagents.Presence.track(MyApp.Presence, "conversation:456", "user-1")

Summary

Functions

list(presence_module, topic)

List all presence entries for a topic.

track(presence_module, topic, id, metadata \\ %{})

Track presence for the calling process on the given topic and identifier.

untrack(presence_module, topic, id)

Untrack presence for the calling process on the given topic and identifier.

update(presence_module, topic, id, new_meta)

Update presence metadata for a tracked entity.

Functions

list(presence_module, topic)

List all presence entries for a topic.

This is a convenience wrapper around the presence module's list function.

track(presence_module, topic, id, metadata \\ %{})

Track presence for the calling process on the given topic and identifier.

Tracks self() — must be called from the process you want to track. Phoenix.Presence automatically removes the entry when the tracked process terminates, so manual cleanup is typically not needed.

Parameters

  • presence_module - The Presence module (e.g., MyApp.Presence)
  • topic - The topic string for presence tracking
  • id - Unique identifier for this presence entry (e.g., user_id)
  • metadata - Optional metadata map (default: empty map)

Returns

  • {:ok, ref} - Presence tracked successfully
  • {:error, reason} - Failed to track presence

Examples

# In a LiveView after connected
{:ok, ref} = Sagents.Presence.track(
  MyApp.Presence,
  "conversation:123",
  "user-1",
  %{joined_at: System.system_time(:second)}
)

# Track in multiple topics
{:ok, _} = Sagents.Presence.track(MyApp.Presence, "topic:123", "user-1")
{:ok, _} = Sagents.Presence.track(MyApp.Presence, "topic:456", "user-1")

untrack(presence_module, topic, id)

Untrack presence for the calling process on the given topic and identifier.

Untracks self() — must be called from the same process that originally tracked. Note: This is rarely needed since Phoenix.Presence automatically cleans up when the tracked process terminates. Only use this for explicit early cleanup.

update(presence_module, topic, id, new_meta)

Update presence metadata for a tracked entity.

This atomically updates the metadata for an existing presence entry by merging in the new values. Must be called from the same process that originally tracked the presence (typically self()).

Uses Phoenix.Presence's atomic update which sends a single presence_diff with phx_ref_prev set, allowing consumers to distinguish updates from leave+join.

Parameters

  • presence_module - The Presence module (e.g., MyApp.Presence)
  • topic - The topic string for presence tracking
  • id - Unique identifier for this presence entry
  • new_meta - Map of new/updated metadata fields to merge

Returns

  • {:ok, ref} - Presence updated successfully
  • {:error, reason} - Update failed (e.g., not tracked)

Examples

# Update agent status in presence (from the agent process)
{:ok, _ref} = Sagents.Presence.update(
  MyApp.Presence,
  "agent_server:presence",
  "agent-123",
  %{status: :running}
)