@spec apns_configured?() :: boolean()

Checks if APNS is configured.

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

Gets the APNS Key ID.

@spec apns_mode() :: :prod | :sandbox

Gets the APNS mode (:prod or :sandbox).

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

Gets the APNS private key content. Supports file paths, environment variables, and raw strings.

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

Gets the APNS Team ID.

@spec batch_timeout_ms() :: pos_integer()

Default per-task timeout for batch sends, in milliseconds.

Retries block the sending task (see PushX.Retry), so a batch task can legitimately outlive any flat timeout while it backs off between attempts. When retries are enabled this covers the worst-case retry budget:

attempts × (receive_timeout + pool_timeout)
  + (attempts − 1) × max(retry_max_delay_ms, 60s rate-limit delay)

With retries disabled — globally (retry_enabled: false) or for the call (retry: :none, see batch_timeout_ms/1) — it is 30 seconds. An explicit :timeout option on PushX.push_batch/4 / send_batch/3 always takes precedence.

@spec batch_timeout_ms([{:retry, :blocking | :none}]) :: pos_integer()

Like batch_timeout_ms/0, but for a specific per-call retry policy: retry: :none means a single attempt, so the budget is the 30 s floor.

@spec circuit_breaker_cooldown_ms() :: pos_integer()

Gets the cooldown time in milliseconds before the circuit transitions from :open to :half_open. Default: 30 seconds.

@spec circuit_breaker_enabled?() :: boolean()

Checks if the circuit breaker is enabled. Default: false (opt-in feature).

@spec circuit_breaker_threshold() :: pos_integer()

Gets the number of consecutive failures before the circuit opens. Default: 5.

@spec connect_timeout() :: pos_integer()

Gets the TCP connection timeout in milliseconds. Default: 10 seconds.

@spec delivery() :: :live | :test

Delivery mode: :live (default) sends to the providers; :test records sends locally instead — see PushX.Test.

@spec fcm_configured?() :: boolean()

Checks if FCM is configured.

@spec fcm_credentials() :: map() | {:file, String.t()}

Gets the FCM credentials for Goth. Returns a map suitable for Goth configuration.

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

Gets the FCM project ID.

@spec fcm_token_fetcher() :: {module(), atom(), list()} | nil

Returns the custom FCM OAuth token fetcher, if one is configured.

By default PushX starts a Goth process (PushX.Goth) from :fcm_credentials and calls Goth.fetch/1 before every FCM send. Set :fcm_token_fetcher to an {module, function, args} tuple to supply the OAuth access token yourself instead — for example to reuse a Goth process your application already runs, or to fetch tokens from a secrets service:

# config/runtime.exs
config :pushx,
  fcm_project_id: "my-project",
  fcm_token_fetcher: {MyApp.PushOAuth, :fetch, []}

defmodule MyApp.PushOAuth do
  # PushX passes the Goth name it would have used as the first argument;
  # a fetcher that reuses your own Goth simply ignores it.
  def fetch(_goth_name), do: Goth.fetch(MyApp.Goth)
end

The function is invoked as apply(module, function, [goth_name | args]) and must return {:ok, %{token: access_token}} or {:error, reason}. It runs on the send path, so keep it cheap (Goth caches; do the same). PushX guards the call: a fetcher that raises, exits, or returns {:error, _} is reported as a retryable :connection_error; one that returns any other shape as :auth_error. Neither escapes as an exception.

When a fetcher is set, PushX starts no PushX.Goth process and :fcm_credentials becomes optional. This option applies to the static configuration only: named FCM instances (PushX.Instance) authenticate with their own :credentials, or their own per-instance :token_fetcher config key — a global fetcher never silently takes over a tenant's OAuth. The test suite uses this seam to exercise the real FCM send path without Google.

@spec finch_name() :: atom()

Gets the Finch pool name.

@spec finch_pool_count() :: pos_integer()

Gets the Finch pool count (number of connection pools).

Default: 2 (increased from 1 in v0.6.0 to handle traffic bursts better)

@spec finch_pool_size() :: pos_integer()

Gets the Finch pool size (connections per pool).

Default: 25 (increased from 10 in v0.6.0 to handle traffic bursts better)

@spec finch_request_opts() :: keyword()

Returns the Finch request options with configured timeouts.

@spec get(atom(), any()) :: any()

Gets a configuration value.

@spec get!(atom()) :: any()

Gets a required configuration value. Raises if the value is not configured.

@spec on_invalid_token() :: {module(), atom(), list()} | nil

Gets the callback for invalid token cleanup.

When set, this MFA tuple is called asynchronously whenever a push returns :invalid_token, :expired_token, or :unregistered.

The callback receives (provider, token, ...extra_args).

Example

config :pushx,
  on_invalid_token: {MyApp.Push, :handle_invalid_token, []}

@spec pool_timeout() :: pos_integer()

Gets the pool timeout (time to wait for a connection from pool) in milliseconds. Default: 5 seconds.

@spec receive_timeout() :: pos_integer()

Gets the receive timeout (time to wait for response data) in milliseconds. Default: 15 seconds.

@spec request_timeout() :: pos_integer()

Gets the overall request timeout in milliseconds. Default: 30 seconds.

Note: This value is not currently passed to Finch requests. Use :receive_timeout and :pool_timeout instead.

@spec retry_base_delay_ms() :: pos_integer()

Gets the base delay for exponential backoff in milliseconds. Default: 10 seconds (Google's recommended minimum).

@spec retry_enabled?() :: boolean()

Checks if retry is enabled.

@spec retry_max_attempts() :: pos_integer()

Gets the maximum number of retry attempts.

@spec retry_max_delay_ms() :: pos_integer()

Gets the maximum delay for exponential backoff in milliseconds. Default: 60 seconds.