MPP.Client.Transport.HTTP (mpp v0.6.2)

HTTP implementation of MPP.Client.Transport over Req.

Operates on Req.Response / Req.Request structs — this module does not construct Req clients itself. Callers (e.g. the payment-aware Req plugin) feed responses in and receive modified requests out.

Wire format

Payment-required response: HTTP status 402
Challenges: one or more WWW-Authenticate headers carrying the Payment scheme. Multiple challenges may appear as repeated header values or as a single comma-separated header value; both forms are handled.
Credential attachment: Authorization: Payment <base64url-json>, produced via MPP.Headers.format_credential/1.
Optional Accept-Payment advertisement via set_accept_payment/2 or set_accept_payment_from_providers/3 (gated by MPP.Client.AcceptPolicy).

API Functions

Function	Arity	Description	Param Kinds
`set_accept_payment_from_providers`	3	Attach `Accept-Payment` from supported `(method, intent)` pairs when policy allows.	`request: value`, `providers: value`, `policy: value`
`set_accept_payment`	2	Attach an `Accept-Payment` header built from preference entries.	`request: value`, `entries: value`
`set_credential`	2	Attach a credential to a Req.Request as `Authorization: Payment <...>`.	`request: value`, `credential: value`
`get_challenges`	1	Parse the Payment challenges from a 402 response's WWW-Authenticate headers.	`response: value`
`payment_required?`	1	Return true if the HTTP response is a 402 Payment Required.	`response: value`

Summary

Functions

get_challenges(response)

Parse the Payment challenges from a 402 response's WWW-Authenticate headers.

payment_required?(response)

Return true if the HTTP response is a 402 Payment Required.

set_accept_payment(request, entries)

Attach an Accept-Payment header from preference entries.

set_accept_payment_from_providers(request, providers, policy \\ :always)

Attach Accept-Payment from a list of supported {method, intent} pairs.

set_credential(request, credential)

Attach a credential to a Req.Request as Authorization: Payment <...>.

Functions

get_challenges(response)

@spec get_challenges(Req.Response.t()) ::
  {:ok, [MPP.Challenge.t()]} | {:error, term()}

Parse the Payment challenges from a 402 response's WWW-Authenticate headers.

Parameters

response - Req.Response struct (value)

Returns

{:ok, [challenge]} on success, {:error, reason} otherwise (tagged_tuple)

Errors

:no_payment_challenges
:missing_www_authenticate
:invalid_scheme
:missing_required_params
:duplicate_param
:invalid_auth_params

# descripex:contract
%{
  params: %{response: %{description: "Req.Response struct", kind: :value}},
  errors: [:no_payment_challenges, :missing_www_authenticate, :invalid_scheme,
   :missing_required_params, :duplicate_param, :invalid_auth_params],
  returns: %{
    type: :tagged_tuple,
    description: "`{:ok, [challenge]}` on success, `{:error, reason}` otherwise"
  }
}

payment_required?(response)

@spec payment_required?(Req.Response.t()) :: boolean()

@spec payment_required?(Req.Response.t()) :: false

Return true if the HTTP response is a 402 Payment Required.

Parameters

response - Req.Response struct (value)

Returns

true if status is 402 (boolean)

# descripex:contract
%{
  params: %{response: %{description: "Req.Response struct", kind: :value}},
  returns: %{type: :boolean, description: "true if status is 402"}
}

set_accept_payment(request, entries)

@spec set_accept_payment(Req.Request.t(), [MPP.Headers.accept_payment_entry() | map()]) ::
  Req.Request.t()

Attach an Accept-Payment header from preference entries.

Does not overwrite an existing Accept-Payment header on the request.

set_accept_payment_from_providers(request, providers, policy \\ :always)

@spec set_accept_payment_from_providers(
  Req.Request.t(),
  [{String.t(), String.t()}],
  MPP.Client.AcceptPolicy.t()
) :: Req.Request.t()

Attach Accept-Payment from a list of supported {method, intent} pairs.

Respects MPP.Client.AcceptPolicy — when allows?/2 is false the request is returned unchanged. Caller-set Accept-Payment headers are never overwritten.

set_credential(request, credential)

@spec set_credential(Req.Request.t(), MPP.Credential.t()) :: Req.Request.t()

Attach a credential to a Req.Request as Authorization: Payment <...>.

Parameters

request - Req.Request struct (value)
credential - MPP.Credential struct (value)

Returns

Req.Request with the Authorization header set (struct)

# descripex:contract
%{
  params: %{
    request: %{description: "Req.Request struct", kind: :value},
    credential: %{description: "MPP.Credential struct", kind: :value}
  },
  returns: %{
    type: :struct,
    description: "Req.Request with the Authorization header set"
  }
}