defmodule CCXT.Signing.Behaviour do
  @moduledoc """
  Behaviour for signing pattern implementations.

  Any module implementing `sign/3` can be used as a signing pattern.
  Built-in patterns are dispatched via `CCXT.Signing.sign/4`. Custom
  modules are wired via `CCXT.Signing.Custom`.

  ## Implementing a Custom Pattern

      defmodule MyApp.Signing.MyExchange do
        @behaviour CCXT.Signing.Behaviour

        @impl true
        def sign(request, credentials, config) do
          timestamp = CCXT.Signing.timestamp_ms()
          signature = CCXT.Signing.hmac_sha256(
            request.path <> to_string(timestamp),
            credentials.secret
          )

          %{
            url: request.path,
            method: request.method,
            headers: [
              {"X-API-KEY", credentials.api_key},
              {"X-TIMESTAMP", to_string(timestamp)},
              {"X-SIGNATURE", CCXT.Signing.encode_hex(signature)}
            ],
            body: request.body
          }
        end
      end

  ## Available Helpers

  `CCXT.Signing` provides crypto and encoding helpers:
  `timestamp_ms/0`, `hmac_sha256/2`, `hmac_sha384/2`, `hmac_sha512/2`,
  `sha256/1`, `sha512/1`, `encode_hex/1`, `encode_base64/1`,
  `decode_base64/1`, `urlencode/1`, `urlencode_raw/1`.
  """

  alias CCXT.Credentials
  alias CCXT.Signing

  @doc """
  Signs a request using the pattern's authentication method.

  ## Parameters

  - `request` - Map with `:method`, `:path`, `:body`, and `:params`
  - `credentials` - `CCXT.Credentials` struct with API key and secret
  - `config` - Pattern-specific configuration from the exchange spec

  ## Returns

  A signed request map with `:url`, `:method`, `:headers`, and `:body`.
  """
  @callback sign(
              request :: Signing.request(),
              credentials :: Credentials.t(),
              config :: Signing.config()
            ) :: Signing.signed_request()
end