Tink.Connectivity (Tink v0.1.1)

Copy Markdown View Source

Connectivity API for checking provider and service availability.

This module provides functionality to check the connectivity status of:

  • Financial institution providers
  • Tink API services
  • Provider credentials
  • Data refresh status

Features

  • Provider Status: Check if providers are operational
  • Credential Health: Monitor credential connectivity
  • Service Health: Verify Tink API availability
  • Market Coverage: Check provider availability by market

Use Cases

Check Provider Availability Before Connection

@spec can_connect_to_provider?(String.t(), String.t()) :: boolean()

def can_connect_to_provider?(provider_id, market) do
  case Tink.Connectivity.check_provider_status(provider_id, market) do
    {:ok, %{"status" => "ENABLED"}} ->
      {:ok, :available}

    {:ok, %{"status" => "DISABLED"}} ->
      {:error, :temporarily_unavailable}

    {:ok, %{"status" => "OBSOLETE"}} ->
      {:error, :no_longer_supported}

    {:error, error} ->
      {:error, error}
  end
end

Monitor Credential Connectivity

@spec check_user_connections(Client.t()) :: {:ok, list(map())} | {:error, Error.t()}

def check_user_connections(user_client) do
  {:ok, credentials} = Tink.Users.list_credentials(user_client)

  Enum.map(credentials["credentials"], fn cred ->
    status = check_credential_connectivity(cred)

    %{
      provider: cred["providerName"],
      status: cred["status"],
      connectivity: status,
      last_updated: cred["statusUpdated"]
    }
  end)
end

defp check_credential_connectivity(%{"status" => "UPDATED"}), do: :healthy
defp check_credential_connectivity(%{"status" => "TEMPORARY_ERROR"}), do: :degraded
defp check_credential_connectivity(%{"status" => "AUTHENTICATION_ERROR"}), do: :auth_failed
defp check_credential_connectivity(%{"status" => "PERMANENT_ERROR"}), do: :failed
defp check_credential_connectivity(_), do: :unknown

Provider Health Dashboard

@spec get_provider_health_by_market(String.t()) :: {:ok, map()} | {:error, Error.t()}

def get_provider_health_by_market(market) do
  {:ok, providers} = Tink.Connectivity.list_providers_by_market(market)

  providers["providers"]
  |> Enum.group_by(& &1["status"])
  |> Enum.map(fn {status, providers} ->
    {status, %{
      count: length(providers),
      providers: Enum.map(providers, & &1["name"])
    }}
  end)
  |> Map.new()
end

Provider Status Types

  • ENABLED - Provider is operational
  • DISABLED - Temporarily unavailable
  • OBSOLETE - No longer supported
  • UNKNOWN - Status cannot be determined

Credential Status Types

  • CREATED - Just created, not yet authenticated
  • AUTHENTICATING - Authentication in progress
  • UPDATING - Refreshing data
  • UPDATED - Successfully updated
  • TEMPORARY_ERROR - Temporary connectivity issue
  • AUTHENTICATION_ERROR - Invalid credentials
  • PERMANENT_ERROR - Permanent failure
  • AWAITING_MOBILE_BANKID_AUTHENTICATION - Waiting for BankID
  • AWAITING_THIRD_PARTY_APP_AUTHENTICATION - Waiting for external app

Summary

Functions

check_api_health()

Checks if the Tink API is accessible.

check_credential_connectivity(client, opts \\ [])

Checks the connectivity status of user credentials.

check_provider_status(provider_id, market \\ nil)

Checks the status of a specific provider.

get_credential_connectivity(client, credential_id)

Gets detailed connectivity information for a specific credential.

list_providers_by_market(market)

Lists providers by market (unauthenticated).

list_providers_by_market_authenticated(client, market)

Lists providers by market (authenticated).

provider_operational?(provider_id, market \\ nil)

Checks if a provider is operational (enabled).

Functions

check_api_health()

@spec check_api_health() :: {:ok, :healthy} | {:error, binary()}

Checks if the Tink API is accessible.

Performs a basic connectivity check to verify the API is reachable.

Returns

  • {:ok, :healthy} - API is accessible
  • {:error, reason} - API is not accessible

Examples

case Tink.Connectivity.check_api_health() do
  {:ok, :healthy} ->
    Logger.info("Tink API is operational")
    :ok

  {:error, reason} ->
    Logger.error("Tink API unreachable: #{inspect(reason)}")
    {:error, :api_unavailable}
end

Use Cases

  • Health Checks: Verify service availability
  • Monitoring: Track API uptime
  • Diagnostics: Debug connectivity issues

check_credential_connectivity(client, opts \\ [])

@spec check_credential_connectivity(
  Tink.Client.t(),
  keyword()
) :: {:ok, map()} | {:error, Tink.Error.t()}

Checks the connectivity status of user credentials.

Parameters

  • client - Tink client with user access token and credentials:read scope
  • opts - Options:
    • :include_healthy - Include healthy credentials (default: true)
    • :include_errors - Include error credentials (default: true)

Returns

  • {:ok, connectivity_report} - Credential connectivity status
  • {:error, error} - If the request fails

Examples

user_client = Tink.client(access_token: user_access_token)

{:ok, report} = Tink.Connectivity.check_credential_connectivity(user_client)
#=> {:ok, %{
#     "total" => 3,
#     "healthy" => 2,
#     "degraded" => 1,
#     "failed" => 0,
#     "credentials" => [
#       %{
#         "credentialId" => "cred_123",
#         "provider" => "Example Bank",
#         "status" => "UPDATED",
#         "connectivity" => "healthy",
#         "lastUpdated" => "2024-01-15T10:00:00Z"
#       },
#       %{
#         "credentialId" => "cred_456",
#         "provider" => "Another Bank",
#         "status" => "TEMPORARY_ERROR",
#         "connectivity" => "degraded",
#         "lastUpdated" => "2024-01-15T09:00:00Z",
#         "errorMessage" => "Temporary connection issue"
#       }
#     ]
#   }}

# Check only problematic credentials
{:ok, issues} = Tink.Connectivity.check_credential_connectivity(
  user_client,
  include_healthy: false
)

Connectivity Classifications

  • healthy: Credential is working normally
  • degraded: Temporary issues but may recover
  • auth_failed: Authentication failed, requires user action
  • failed: Permanent failure
  • authenticating: Authentication in progress
  • updating: Data refresh in progress

Required Scope

credentials:read

check_provider_status(provider_id, market \\ nil)

@spec check_provider_status(String.t(), String.t() | nil) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Checks the status of a specific provider.

Parameters

  • provider_id - Provider ID
  • market - Market code (optional, for verification)

Returns

  • {:ok, status} - Provider status information
  • {:error, error} - If the request fails

Examples

{:ok, status} = Tink.Connectivity.check_provider_status("provider_123", "GB")
#=> {:ok, %{
#     "id" => "provider_123",
#     "name" => "Example Bank",
#     "status" => "ENABLED",
#     "statusMessage" => nil,
#     "lastChecked" => "2024-01-15T10:00:00Z"
#   }}

# Check if provider is operational
case status do
  {:ok, %{"status" => "ENABLED"}} ->
    :operational

  {:ok, %{"status" => "DISABLED"}} ->
    :temporarily_unavailable

  {:ok, %{"status" => "OBSOLETE"}} ->
    :no_longer_supported
end

Status Values

  • ENABLED - Provider is working normally
  • DISABLED - Provider is temporarily unavailable
  • OBSOLETE - Provider is no longer supported

No Authentication Required

get_credential_connectivity(client, credential_id)

@spec get_credential_connectivity(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Gets detailed connectivity information for a specific credential.

Parameters

  • client - Tink client with user access token and credentials:read scope
  • credential_id - Credential ID

Returns

  • {:ok, connectivity_info} - Detailed connectivity information
  • {:error, error} - If the request fails

Examples

user_client = Tink.client(access_token: user_access_token)

{:ok, info} = Tink.Connectivity.get_credential_connectivity(
  user_client,
  "cred_123"
)
#=> {:ok, %{
#     "credentialId" => "cred_123",
#     "provider" => "Example Bank",
#     "providerId" => "provider_123",
#     "status" => "UPDATED",
#     "connectivity" => "healthy",
#     "lastUpdated" => "2024-01-15T10:00:00Z",
#     "lastSuccess" => "2024-01-15T10:00:00Z",
#     "canRefresh" => true
#   }}

Required Scope

credentials:read

list_providers_by_market(market)

@spec list_providers_by_market(String.t()) :: {:ok, map()} | {:error, Tink.Error.t()}

Lists providers by market (unauthenticated).

This endpoint can be called without authentication to check provider availability in a specific market.

Parameters

  • market - Market code (e.g., "GB", "SE", "DE")

Returns

  • {:ok, providers} - List of providers for the market
  • {:error, error} - If the request fails

Examples

# Check UK providers (no auth required)
{:ok, providers} = Tink.Connectivity.list_providers_by_market("GB")
#=> {:ok, %{
#     "providers" => [
#       %{
#         "id" => "provider_123",
#         "name" => "Example Bank",
#         "displayName" => "Example Bank",
#         "status" => "ENABLED",
#         "type" => "BANK",
#         "financialInstitutionId" => "fi_example_gb",
#         "capabilities" => ["TRANSFERS", "ACCOUNT_VERIFICATION"]
#       }
#     ]
#   }}

# Check German providers
{:ok, de_providers} = Tink.Connectivity.list_providers_by_market("DE")

Provider Fields

  • id: Provider identifier
  • name: Provider name
  • displayName: Display name
  • status: ENABLED, DISABLED, or OBSOLETE
  • type: BANK, CREDIT_CARD, BROKER, OTHER
  • capabilities: Supported features

No Authentication Required

This endpoint is publicly accessible and does not require authentication.

list_providers_by_market_authenticated(client, market)

@spec list_providers_by_market_authenticated(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Lists providers by market (authenticated).

Authenticated version that may return additional provider details.

Parameters

  • client - Tink client with providers:read scope
  • market - Market code (e.g., "GB", "SE", "DE")

Returns

  • {:ok, providers} - List of providers for the market
  • {:error, error} - If the request fails

Examples

client = Tink.client(scope: "providers:read")

{:ok, providers} = Tink.Connectivity.list_providers_by_market_authenticated(
  client,
  "GB"
)

Required Scope

providers:read

provider_operational?(provider_id, market \\ nil)

@spec provider_operational?(String.t(), String.t() | nil) :: boolean()

Checks if a provider is operational (enabled).

Parameters

  • provider_id - Provider ID
  • market - Market code (optional)

Returns

  • true if provider is enabled
  • false if provider is disabled or obsolete

Examples

if Tink.Connectivity.provider_operational?("provider_123", "GB") do
  # Proceed with connection
  initiate_connection(provider_id)
else
  # Show error message
  show_provider_unavailable_message()
end