# `PhoenixKit.Integrations.Providers` [🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v2.55.1/lib/phoenix_kit/integrations/providers.ex#L1) Registry of known integration providers. Each provider definition describes how to connect to an external service: what auth type it uses, what fields the admin needs to fill in, and how to validate the connection. Providers are defined in code, not in the database. New providers are added here as needed. External modules can also contribute providers via the `integration_providers/0` callback on `PhoenixKit.Module`. # `auth_type` ```elixir @type auth_type() :: :oauth2 | :api_key | :key_secret | :bot_token | :credentials ``` # `provider` ```elixir @type provider() :: %{ :key => String.t(), :name => String.t(), :description => String.t(), :icon => String.t(), :auth_type => auth_type(), :oauth_config => map() | nil, :setup_fields => [setup_field()], :capabilities => [atom()], optional(:base_url) => String.t(), optional(:validation) => map(), optional(:instructions) => [map()], optional(:setup_module) => module(), optional(:scopes) => [:system | :personal], optional(:personal_default) => boolean(), optional(:personal_also_while) => String.t() } ``` # `setup_field` ```elixir @type setup_field() :: %{ key: String.t(), label: String.t(), type: :text | :password | :textarea | :number | :select, required: boolean(), placeholder: String.t(), help: String.t() | nil, options: [%{value: String.t(), label: String.t()}] | nil } ``` # `all` ```elixir @spec all() :: [provider()] ``` Returns all known providers, including those contributed by external modules. Results are cached in `persistent_term` after the first call. `PhoenixKit.ModuleRegistry` calls `clear_cache/0` for you whenever the registered-module set changes (`register/1`, `unregister/1`, `rescan/0`), so a module discovered after the cache was warmed still contributes its providers. Call it yourself only when something outside the registry changes what `integration_providers/0` would return. # `also_while_on?` ```elixir @spec also_while_on?(provider()) :: boolean() ``` Whether `provider` is offered to users only because a setting it names is on. # `base_url` ```elixir @spec base_url(String.t()) :: String.t() | nil ``` Returns the API base URL declared by a provider, or `nil` if it has none. Accepts the same plain or named keys as `get/1` (`"openai"` / `"openai:work"`). Only providers with a primary REST API (currently the `:ai_completions` providers) declare a `:base_url`; everything else is `nil`. # `clear_cache` ```elixir @spec clear_cache() :: :ok ``` Clears the cached provider list and used-by map. Call this when modules are added or removed at runtime so the next call to `all/0` or `used_by_modules/0` recomputes from the module registry. # `dynamic_setup?` ```elixir @spec dynamic_setup?(provider() | nil) :: boolean() ``` Whether the form's fields depend on what has been typed. # `for_scope` ```elixir @spec for_scope(:system | :personal) :: [provider()] ``` All providers usable under `scope` (`:system` or `:personal`). Drives the provider grid on each page — the system setup lists `for_scope(:system)`, the personal setup lists `for_scope(:personal)`. # `get` ```elixir @spec get(String.t()) :: provider() | nil ``` Look up a single provider by key. Accepts both plain keys (`"google"`) and named keys (`"google:personal"`) — the name is stripped before lookup since provider definitions are per-type. # `personal_enabled_keys` ```elixir @spec personal_enabled_keys([provider()]) :: [String.t()] ``` The provider keys a site admin has enabled for users. Until one saves a choice (`put_personal_enabled/1`) they are the providers that declare `:personal_default`, which is what users were offered before the choice existed. # `personal_offered` ```elixir @spec personal_offered() :: [provider()] ``` Providers offered on the personal integrations "add" picker: the providers that may be personal (`for_scope(:personal)`) and that a site admin has enabled for users (`personal_enabled_keys/0`), plus any that declares `:personal_also_while` and whose setting is on. Returned in `for_scope/1`'s order. # `put_personal_enabled` ```elixir @spec put_personal_enabled([String.t()]) :: {:ok, [String.t()]} | {:error, term()} ``` Saves which providers users may add on their own. Only providers that may be personal are kept; everything else in `keys` is dropped. # `scopes_of` ```elixir @spec scopes_of(String.t() | provider()) :: [:system | :personal] ``` The scopes a provider may hold a connection under. Defaults to `[:system]` when the provider omits `:scopes` (so an external module's provider never lands on the personal page unless it opts in). # `setup_attrs` ```elixir @spec setup_attrs(provider() | nil, map()) :: map() ``` The attributes to save for a submitted form. Only keys the provider declares are kept, so form params cannot add keys to the stored data. Blanks are dropped for `:password` fields only: an untouched secret (never re-rendered) must not be blanked by submitting the form, while a cleared optional field must clear. # `setup_changed` ```elixir @spec setup_changed(provider() | nil, map(), map()) :: map() ``` The typed values once `incoming` (the form as just sent, declared keys only) arrives over `previous`. Providers without a `:setup_module` just merge. # `setup_fields` ```elixir @spec setup_fields(provider(), map()) :: [map()] ``` The setup fields a form shows. `values` are the saved and typed values merged (typed over saved); a provider without a `:setup_module` always shows its declared `setup_fields`. # `setup_label` ```elixir @spec setup_label(provider() | nil, map()) :: String.t() | nil ``` What kind of account a connection is, for a provider whose one entry covers many (Object Storage: Tigris, Cloudflare R2, …) — shown next to the provider name in the lists, since "Object Storage (S3-compatible)" alone does not say which. nil when the provider has nothing to add. # `setup_saved` ```elixir @spec setup_saved(provider() | nil, map(), map()) :: map() ``` The saved values a form may show next to the typed ones (see `ObjectStorageServices.saved/2`). # `used_by_modules` ```elixir @spec used_by_modules() :: %{required(String.t()) => [String.t()]} ``` Returns a map of provider_key => [module_name] showing which modules use each integration. # `with_capability` ```elixir @spec with_capability(atom()) :: [provider()] ``` Returns all providers (built-in + external) that declare the given capability. Lets consumers discover providers by what they can do rather than by a hardcoded list. For example, an AI module can render its provider picker from `with_capability(:ai_completions)`, so adding a new chat provider to the registry surfaces it automatically. Order follows `all/0` (built-ins first, in definition order). --- *Consult [api-reference.md](api-reference.md) for complete listing*