Behaviour for lifecycle hooks around client payment creation.

X402.Client.build_payment/3 runs the callbacks in this order:

1. before_payment/2 — after a requirements entry has been selected and before anything is signed. Continue with {:cont, context} (the context's :requirements may be replaced, for example to pin a different accepts entry) or abort with {:halt, reason}, which surfaces as {:error, {:hook_halted, :before_payment, reason}}.
2. after_payment/2 — once the PaymentPayload has been signed, assembled and enriched. Continue with {:cont, context}; the context's :payload may be replaced and becomes the returned payload.
3. on_payment_failure/2 — when signing or enrichment fails after before_payment/2 has run. Continue with {:cont, context} (the context's :error may be replaced) or recover with {:recover, payload}, which returns {:ok, payload} instead.

These mirror the onBeforePaymentCreation, onAfterPaymentCreation, and onPaymentCreationFailure hooks of the reference TypeScript client. Selection failures (:no_acceptable_requirements) happen before any hook runs and never reach on_payment_failure/2.

A callback that raises or exits yields {:error, {:hook_callback_failed, callback, reason}}; one that returns anything outside its contract yields {:error, {:hook_invalid_return, callback, value}}.

Hooks are invoked in the process that calls X402.Client.build_payment/3 (through X402.Client.Finch.request/3 or X402.MCP.Client.call/3, the request process). X402.Client.Hooks.Default is the no-op implementation used when no :hooks option is given.

Example

defmodule MyApp.PaymentHooks do
  @behaviour X402.Client.Hooks

  @impl true
  def before_payment(context, _metadata) do
    case context.requirements["amount"] do
      amount when amount > "1000000" -> {:halt, :too_expensive}
      _amount -> {:cont, context}
    end
  end

  @impl true
  def after_payment(context, _metadata) do
    Logger.info("paying #{context.requirements["amount"]}")
    {:cont, context}
  end

  @impl true
  def on_payment_failure(context, _metadata), do: {:cont, context}
end