defmodule SaltEdgeClient do
  @moduledoc """
  Production-grade Elixir client for the **SaltEdge API v6**.

  Covers all three product areas:
  - **AIS** — Account Information Service
  - **PIS** — Payment Initiation Service
  - **Data Enrichment Platform** — Categorisation, Merchant ID & Financial Insights

  ## Installation

  Add to your `mix.exs`:

      {:salt_edge_client, "~> 1.0"}

  ## Configuration

      config :salt_edge_client,
        app_id:  System.get_env("SALTEDGE_APP_ID"),
        secret:  System.get_env("SALTEDGE_SECRET")

  ## Quick start

      # AIS — create a customer and open a connect session
      {:ok, customer} = SaltEdgeClient.AIS.Customers.create(identifier: "alice@example.com")

      {:ok, session} = SaltEdgeClient.AIS.Connections.connect(
        customer_id: customer["id"],
        consent: %{scopes: ["accounts", "transactions"]},
        attempt: %{return_to: "https://yourapp.com/callback"}
      )
      IO.puts session["connect_url"]

      # Paginate all accounts (lazy stream)
      SaltEdgeClient.AIS.Accounts.stream(connection_id: "conn-123")
      |> Enum.each(&IO.inspect/1)

      # PIS — initiate a SEPA payment
      {:ok, payment} = SaltEdgeClient.PIS.Payments.create(
        customer_id:   customer["id"],
        provider_code: "fake_client_xf",
        template_code: "sepa_credit_transfer",
        payment_attributes: %{
          amount:        "100.00",
          currency_code: "EUR",
          creditor_name: "Acme Corp",
          creditor_iban: "DE89370400440532013000"
        }
      )

  ## API modules

  ### AIS

  - `SaltEdgeClient.AIS.Countries` — list supported countries
  - `SaltEdgeClient.AIS.Providers` — list/show banks and institutions
  - `SaltEdgeClient.AIS.Customers` — create/list/remove customers
  - `SaltEdgeClient.AIS.Connections` — connect, reconnect, refresh, background refresh
  - `SaltEdgeClient.AIS.Consents` — list/revoke data access consents
  - `SaltEdgeClient.AIS.Accounts` — list bank accounts
  - `SaltEdgeClient.AIS.Transactions` — list and update transactions
  - `SaltEdgeClient.AIS.Rates` — exchange rates

  ### PIS

  - `SaltEdgeClient.PIS.Customers` — PIS customers
  - `SaltEdgeClient.PIS.Providers` — PIS providers
  - `SaltEdgeClient.PIS.Payments` — initiate, poll and refresh payments
  - `SaltEdgeClient.PIS.PaymentTemplates` — SEPA, Faster Payment, BACS, CHAPS, Domestic templates
  - `SaltEdgeClient.PIS.BulkPayments` — batch payment initiation

  ### Data Enrichment

  - `SaltEdgeClient.Enrichment.Buckets` — create enrichment buckets
  - `SaltEdgeClient.Enrichment.Accounts` — import accounts
  - `SaltEdgeClient.Enrichment.Transactions` — import and categorise transactions
  - `SaltEdgeClient.Enrichment.Merchants` — merchant identification
  - `SaltEdgeClient.Enrichment.Categories` — category list and learning
  - `SaltEdgeClient.Enrichment.CustomerRules` — custom categorisation rules
  - `SaltEdgeClient.Enrichment.FinancialInsights` — financial analysis reports

  ### Utilities

  - `SaltEdgeClient.Paginator` — `stream/2`, `collect/2`, `each_page/3`
  - `SaltEdgeClient.Error` — structured error type with helper predicates
  - `SaltEdgeClient.Webhook.Handler` — Plug-based webhook handler
  - `SaltEdgeClient.Webhook.Validator` — standalone HMAC signature validation
  - `SaltEdgeClient.Signer` — request signing and webhook verification
  - `SaltEdgeClient.Config` — runtime configuration

  ## Error handling

      case SaltEdgeClient.AIS.Customers.show("bad-id") do
        {:ok, customer} ->
          customer

        {:error, %SaltEdgeClient.Error{status: 404, class: "CustomerNotFound"}} ->
          {:error, :not_found}

        {:error, %SaltEdgeClient.Error{} = err} when SaltEdgeClient.Error.server_error?(err) ->
          {:error, :server_error}

        {:error, %SaltEdgeClient.Error{status: :network}} ->
          {:error, :network_error}
      end
  """

  @doc "Returns the SDK version string."
  @spec version() :: String.t()
  def version, do: Application.spec(:salt_edge_client, :vsn) |> to_string()
end