@spec apply_accept_payment_header([term()], String.t() | nil, (term() ->
                                                           {String.t(),
                                                            String.t()})) :: [
  term()
]

Filter and reorder server offers using an Accept-Payment header.

Returns offers unchanged when header is nil, malformed, or matches no offers (spec MAY-ignore).

@spec format_accept_payment([accept_payment_entry() | map()]) :: String.t()

Format preference entries into an Accept-Payment header value.

Omits ;q= when q is 1.0. Entries may be {method, intent, q} tuples or maps with :method, :intent, and :q keys.

@spec format_challenge(MPP.Challenge.t()) :: String.t()

Format a challenge as a WWW-Authenticate: Payment header value with RFC 9110 auth-param syntax.

Parameters

• challenge - Challenge struct to format (value)

Returns

Header value string with quoted auth-params (string)

Composes With

• parse_challenge

# descripex:contract
%{
  params: %{
    challenge: %{description: "Challenge struct to format", kind: :value}
  },
  returns: %{
    type: :string,
    description: "Header value string with quoted auth-params"
  },
  composes_with: [:parse_challenge]
}

@spec format_credential(MPP.Credential.t()) :: String.t()

Format a credential as an Authorization: Payment header value.

Parameters

• credential - Credential struct to format (value)

Returns

Header value with Payment scheme prefix and base64url JSON blob (string)

Composes With

• parse_credential

# descripex:contract
%{
  params: %{
    credential: %{description: "Credential struct to format", kind: :value}
  },
  returns: %{
    type: :string,
    description: "Header value with Payment scheme prefix and base64url JSON blob"
  },
  composes_with: [:parse_credential]
}

@spec format_receipt(MPP.Receipt.t()) :: String.t()

Format a receipt as a Payment-Receipt header value (bare base64url JSON, no scheme prefix).

Parameters

• receipt - Receipt struct to format (value)

Returns

Base64url-encoded JSON string (string)

Composes With

• parse_receipt

# descripex:contract
%{
  params: %{receipt: %{description: "Receipt struct to format", kind: :value}},
  returns: %{type: :string, description: "Base64url-encoded JSON string"},
  composes_with: [:parse_receipt]
}

@spec parse_accept_payment(String.t()) :: [accept_payment_entry()]

Parse an Accept-Payment header value into preference entries.

Each entry is {method, intent, q} where method and intent are lowercase tokens or *, and q is 0.0..1.0 (default 1.0).

Returns [] for empty, whitespace-only, or malformed input (spec MAY-ignore).

@spec parse_challenge(String.t()) :: {:ok, MPP.Challenge.t()} | {:error, atom()}

Parse a WWW-Authenticate: Payment header value into a challenge struct.

Parameters

• header - Raw WWW-Authenticate header value string (value)

Returns

{:ok, challenge} on success, {:error, reason} on failure (tagged_tuple)

Errors

• :invalid_scheme
• :missing_required_params
• :duplicate_param
• :invalid_auth_params
• :request_too_large

Composes With

• format_challenge

# descripex:contract
%{
  params: %{
    header: %{
      description: "Raw WWW-Authenticate header value string",
      kind: :value
    }
  },
  errors: [:invalid_scheme, :missing_required_params, :duplicate_param,
   :invalid_auth_params, :request_too_large],
  returns: %{
    type: :tagged_tuple,
    description: "`{:ok, challenge}` on success, `{:error, reason}` on failure"
  },
  composes_with: [:format_challenge]
}

@spec parse_challenges(String.t()) :: {:ok, [MPP.Challenge.t()]} | {:error, atom()}

Parse a WWW-Authenticate header containing one or more Payment challenges. Splits on scheme boundaries, skips non-Payment schemes. Partial failures are tolerated: if some challenges parse and others fail, only the successful ones are returned (matching mppx deserializeList semantics).

Parameters

• header - Raw WWW-Authenticate header value, possibly containing multiple challenges (value)

Returns

{:ok, [challenge]} on success, {:error, reason} if no Payment challenges found or all fail to parse (tagged_tuple)

Errors

• :no_payment_challenges
• :invalid_scheme
• :missing_required_params
• :duplicate_param
• :invalid_auth_params
• :request_too_large

Composes With

• parse_challenge
• format_challenge

# descripex:contract
%{
  params: %{
    header: %{
      description: "Raw WWW-Authenticate header value, possibly containing multiple challenges",
      kind: :value
    }
  },
  errors: [:no_payment_challenges, :invalid_scheme, :missing_required_params,
   :duplicate_param, :invalid_auth_params, :request_too_large],
  returns: %{
    type: :tagged_tuple,
    description: "`{:ok, [challenge]}` on success, `{:error, reason}` if no Payment challenges found or all fail to parse"
  },
  composes_with: [:parse_challenge, :format_challenge]
}

@spec parse_credential(String.t()) :: {:ok, MPP.Credential.t()} | {:error, atom()}

Parse an Authorization: Payment header value into a credential struct.

Parameters

• header - Raw Authorization header value string (value)

Returns

{:ok, credential} on success, {:error, reason} on failure (tagged_tuple)

Errors

• :invalid_scheme
• :invalid_base64
• :invalid_json
• :missing_required_fields
• :token_too_large

Composes With

• format_credential

# descripex:contract
%{
  params: %{
    header: %{
      description: "Raw Authorization header value string",
      kind: :value
    }
  },
  errors: [:invalid_scheme, :invalid_base64, :invalid_json,
   :missing_required_fields, :token_too_large],
  returns: %{
    type: :tagged_tuple,
    description: "`{:ok, credential}` on success, `{:error, reason}` on failure"
  },
  composes_with: [:format_credential]
}

@spec parse_receipt(String.t()) :: {:ok, MPP.Receipt.t()} | {:error, atom()}

Parse a Payment-Receipt header value into a receipt struct.

Parameters

• header - Raw Payment-Receipt header value (bare base64url JSON) (value)

Returns

{:ok, receipt} on success, {:error, reason} on failure (tagged_tuple)

Errors

• :invalid_base64
• :invalid_json
• :missing_required_fields
• :token_too_large

Composes With

• format_receipt

# descripex:contract
%{
  params: %{
    header: %{
      description: "Raw Payment-Receipt header value (bare base64url JSON)",
      kind: :value
    }
  },
  errors: [:invalid_base64, :invalid_json, :missing_required_fields,
   :token_too_large],
  returns: %{
    type: :tagged_tuple,
    description: "`{:ok, receipt}` on success, `{:error, reason}` on failure"
  },
  composes_with: [:format_receipt]
}

@spec rank_by_accept_payment([term()], [accept_payment_entry() | map()], (term() ->
                                                                      {String.t(),
                                                                       String.t()})) ::
  [term()]

Reorder server offers by client Accept-Payment preferences.

Offers with no matching preference or only q=0 matches are excluded. Sorting matches mpp-rs / mppx: highest effective q, then original offer order.

method_intent extracts {method, intent} from each offer (defaults to challenge fields when omitted).