PhoenixKit.Integrations.Events (phoenix_kit v2.5.0)

Copy Markdown View Source

PubSub helpers for broadcasting integration changes in real-time.

Lets the settings pages update live without a refresh. There are two topic scopes:

  • the global system topic "phoenix_kit:integrations" — system-wide connection changes (the website-wide page + consumers subscribe here);
  • a per-user topic "phoenix_kit:integrations:<user_uuid>" — a user's own personal connection changes (the personal page subscribes here).

Each broadcaster routes by the connection's owner, so a personal change only reaches that user's page and a system change only reaches the system page.

Events

  • {:integration_setup_saved, provider_key, data} — setup credentials saved
  • {:integration_connected, provider_key, data} — OAuth flow completed
  • {:integration_disconnected, provider_key} — disconnected

  • {:integration_validated, provider_key, :ok | {:error, reason}} — health check

  • {:integration_connection_added | _removed, provider_key, name}

  • {:integration_connection_renamed, provider_key, old, new}

The data payload on setup_saved/connected is REDACTED — secret fields are stripped before broadcast so credentials never travel over PubSub (consumers reload from the owner-scoped context anyway).

Summary

Types

owner()

Owner scope for routing a broadcast (mirrors PhoenixKit.Integrations.owner/0).

Functions

broadcast_connected(provider_key, data)

Broadcast that an OAuth integration was connected. Routes + redacts by data's owner.

broadcast_connection_added(provider_key, name, owner \\ :system)

Broadcast that a new named connection was added for a provider.

broadcast_connection_removed(provider_key, name, owner \\ :system)

Broadcast that a named connection was removed from a provider.

broadcast_connection_renamed(provider_key, old_name, new_name, owner \\ :system)

Broadcast that a named connection was renamed.

broadcast_disconnected(provider_key, owner \\ :system)

Broadcast that an integration was disconnected.

broadcast_setup_saved(provider_key, data)

Broadcast that an integration's setup credentials were saved. Routes + redacts by data's owner.

broadcast_validated(provider_key, status, owner \\ :system)

Broadcast that an integration's health check completed.

subscribe()

Subscribe to system-wide integration change events (the global topic).

subscribe(user_uuid)

Subscribe to a user's personal integration change events.

topic_for_user(user_uuid)

The per-user personal-integrations topic.

Types

owner()

@type owner() :: :system | {atom(), String.t()}

Owner scope for routing a broadcast (mirrors PhoenixKit.Integrations.owner/0).

Functions

broadcast_connected(provider_key, data)

@spec broadcast_connected(String.t(), map()) :: :ok

Broadcast that an OAuth integration was connected. Routes + redacts by data's owner.

broadcast_connection_added(provider_key, name, owner \\ :system)

@spec broadcast_connection_added(String.t(), String.t(), owner()) :: :ok

Broadcast that a new named connection was added for a provider.

broadcast_connection_removed(provider_key, name, owner \\ :system)

@spec broadcast_connection_removed(String.t(), String.t(), owner()) :: :ok

Broadcast that a named connection was removed from a provider.

broadcast_connection_renamed(provider_key, old_name, new_name, owner \\ :system)

@spec broadcast_connection_renamed(
  String.t(),
  String.t(),
  String.t(),
  owner()
) :: :ok

Broadcast that a named connection was renamed.

broadcast_disconnected(provider_key, owner \\ :system)

@spec broadcast_disconnected(String.t(), owner()) :: :ok

Broadcast that an integration was disconnected.

broadcast_setup_saved(provider_key, data)

@spec broadcast_setup_saved(String.t(), map()) :: :ok

Broadcast that an integration's setup credentials were saved. Routes + redacts by data's owner.

broadcast_validated(provider_key, status, owner \\ :system)

@spec broadcast_validated(String.t(), :ok | {:error, term()}, owner()) :: :ok

Broadcast that an integration's health check completed.

subscribe()

@spec subscribe() :: :ok | {:error, term()}

Subscribe to system-wide integration change events (the global topic).

subscribe(user_uuid)

@spec subscribe(String.t()) :: :ok | {:error, term()}

Subscribe to a user's personal integration change events.

topic_for_user(user_uuid)

@spec topic_for_user(String.t()) :: String.t()

The per-user personal-integrations topic.