defmodule DaProductApp.Acquirer.Behaviour do
  @moduledoc """
  Behaviour contract for acquirer processors.

  This behaviour defines the interface that all acquirer processors must implement
  to integrate with the Mercury Device Middleware transaction processing system.
  """

  @doc """
  Processes a transaction through the acquirer network.

  This is the main entry point for transaction processing. Implementations should
  handle the complete flow including message transformation, network communication,
  and response processing.

  ## Parameters

  - `config`: Acquirer network configuration map
  - `iso_message`: Transaction message in ISO8583 format
  - `opts`: Processing options (optional)

  ## Returns

  - `{:ok, response_message}`: Transaction processed successfully
  - `{:error, reason}`: Transaction processing failed

  ## Example

      config = %{
        network: "mastercard_mpgs",
        environment: "sandbox",
        merchant_id: "TEST123"
      }

      iso_message = %{
        "0" => "0200",    # Purchase request
        "2" => "4111111111111111",
        "3" => "000000",
        "4" => "000000001000"
      }

      {:ok, response} = MyProcessor.process_transaction(config, iso_message)
  """
  @callback process_transaction(config :: map(), iso_message :: map(), opts :: keyword()) ::
    {:ok, map()} | {:error, term()}

  @doc """
  Validates configuration for the acquirer processor.

  Implementations should verify that all required configuration parameters
  are present and valid for the specific acquirer network.

  ## Parameters

  - `config`: Configuration map to validate

  ## Returns

  - `:ok`: Configuration is valid
  - `{:error, reason}`: Configuration validation failed
  """
  @callback validate_config(config :: map()) :: :ok | {:error, term()}

  @doc """
  Initializes the acquirer processor with the given configuration.

  This callback is called during system startup to allow processors to
  perform any necessary initialization such as connection setup,
  credential validation, or resource allocation.

  ## Parameters

  - `config`: Processor configuration

  ## Returns

  - `{:ok, state}`: Initialization successful
  - `{:error, reason}`: Initialization failed
  """
  @callback init(config :: map()) :: {:ok, term()} | {:error, term()}

  @doc """
  Performs health check for the acquirer processor.

  This callback allows the system to verify that the processor is
  functioning correctly and can communicate with the acquirer network.

  ## Returns

  - `:ok`: Processor is healthy
  - `{:error, reason}`: Health check failed
  """
  @callback health_check() :: :ok | {:error, term()}

  @doc """
  Cleans up resources when the processor is shutting down.

  This callback is called during system shutdown to allow processors
  to clean up connections, close resources, and perform any necessary
  cleanup operations.

  ## Parameters

  - `state`: Current processor state

  ## Returns

  - `:ok`: Cleanup completed successfully
  """
  @callback terminate(state :: term()) :: :ok

  # Optional callbacks with default implementations
  @optional_callbacks [init: 1, health_check: 0, terminate: 1]

  defmacro __using__(_opts) do
    quote do
      @behaviour DaProductApp.Acquirer.Behaviour

      @doc false
      def init(_config), do: {:ok, nil}

      @doc false
      def health_check, do: :ok

      @doc false
      def terminate(_state), do: :ok

      defoverridable [init: 1, health_check: 0, terminate: 1]
    end
  end
end