server

type BroadcastFunc func(
	ctx context.Context,
	credential *mpp.Credential,
	request map[string]any,
) (*mpp.Receipt, error)

type BroadcastingIntent interface {
	ValidatingIntent
	Broadcast(ctx context.Context, credential *mpp.Credential, request map[string]any) (*mpp.Receipt, error)
}

type ChargeOffersBuilder interface {
	BuildChargeRequests(params ChargeParams) ([]map[string]any, error)
}

type ChargeParams struct {
	// Authorization is the incoming Authorization header value. ChargeRequest
	// sets it from the request.
	Authorization string
	// PaymentAuthorization is the incoming Payment-Authorization header value.
	// Used when the handler was created with WithRequiresAuth(true).
	// ChargeRequest sets it from the request.
	PaymentAuthorization string
	// Amount is the human-readable charge amount.
	Amount string
	// Currency overrides the method's default currency.
	Currency string
	// Recipient overrides the method's default recipient.
	Recipient string
	// ExternalID is copied into the request and echoed back in the Receipt.
	ExternalID string
	// Body is the actual request body to bind via the challenge digest. It is
	// digested as VerifyParams.Body is. ChargeRequest sets it from a
	// non-empty request body.
	Body any
	// Expires overrides the default Challenge expiry.
	Expires string
	// Description is exposed in the server-generated Challenge.
	Description string
	// Splits adds Tempo split-payment transfers under methodDetails.splits.
	Splits []tempo.SplitParams
	// FeePayer requests the sponsored Tempo flow when the method supports it.
	FeePayer bool
	// FeePayerURL points at a remote fee-payer signer.
	FeePayerURL string
	// SupportedModes advertises the Tempo submission modes allowed for this challenge.
	SupportedModes []tempo.ChargeMode
	// ChainID overrides the method's default Tempo chain ID.
	ChainID int
	// Meta stores opaque Challenge metadata.
	Meta map[string]string
	// MppxScope binds framework route/resource/query context into the
	// request. When empty, ChargeRequest and the middlewares set it from the
	// request (see ScopeFromHTTPRequest); a non-empty value is kept as is.
	MppxScope map[string]string
}

type ChargeRequestBuilder interface {
	BuildChargeRequest(params ChargeParams) (map[string]any, error)
}

type ChargeResult struct {
	// Challenge is returned when the client still needs to satisfy the payment.
	// With several offers it is the offer the submitted Credential echoed, or
	// the first offer otherwise.
	Challenge *mpp.Challenge
	// Challenges lists every offered Challenge in presentation order whenever
	// Challenge is set. It contains a single element for single-offer methods.
	Challenges []*mpp.Challenge
	// Credential is the verified client credential on success.
	Credential *mpp.Credential
	// Receipt acknowledges a successfully verified payment.
	Receipt *mpp.Receipt
	// contains filtered or unexported fields
}

type ComposeConfig struct {
	Mpp    *Mpp
	Params ChargeParams
}

type Events struct {
	// ChallengeCreated is called for every Challenge returned to the client,
	// whether as the initial offer or as a retry offer after a failure. It
	// is called only once the whole set of Challenges for the response is
	// issued and can be serialized, never for an offer that is not returned.
	ChallengeCreated func(ctx context.Context, challenge *mpp.Challenge)
	// PaymentSucceeded is called after a Credential is verified and settled.
	PaymentSucceeded func(ctx context.Context, credential *mpp.Credential, receipt *mpp.Receipt)
	// PaymentFailed is called when a submitted Credential is rejected or
	// cannot be settled. credential is nil when it could not be parsed.
	PaymentFailed func(ctx context.Context, credential *mpp.Credential, err error)
}

type Intent interface {
	Name() string
	Verify(ctx context.Context, credential *mpp.Credential, request map[string]any) (*mpp.Receipt, error)
}

type IntentHooks struct {
	// Verify configures the legacy combined verification path.
	Verify VerifyFunc
	// Validate configures the advisory phase of a split verification path.
	Validate ValidateFunc
	// Broadcast configures the settlement phase of a split verification path.
	Broadcast BroadcastFunc
}

type Method interface {
	Name() string
	Intents() map[string]Intent
}

type Mpp struct {
	// contains filtered or unexported fields
}

type Offer = ComposeConfig

type Option func(*Mpp)

type ValidateFunc func(
	ctx context.Context,
	credential *mpp.Credential,
	request map[string]any,
) (*Validation, error)

type ValidatingIntent interface {
	Intent
	Validate(ctx context.Context, credential *mpp.Credential, request map[string]any) (*Validation, error)
}

type Validation struct {
	// Challenge is the server-issued challenge echoed by the credential.
	Challenge mpp.ChallengeEcho
	// Credential is the accepted credential.
	Credential *mpp.Credential
	// Details contains method-specific validation metadata.
	Details map[string]any
	// Intent is the validated payment intent.
	Intent string
	// Method is the validated payment method.
	Method string
	// Request is the challenge request bound to the credential.
	Request map[string]any
	// Source is the optional payer identity.
	Source string
}

type VerifyFunc func(
	ctx context.Context,
	credential *mpp.Credential,
	request map[string]any,
) (*mpp.Receipt, error)

type VerifyParams struct {
	// EnableChallengeNonce opts into unique issuance after every replica has
	// nonce-aware verification. The default preserves legacy issuance for
	// rollout. Mpp.Charge sets it for a handler created WithChallengeNonce.
	EnableChallengeNonce bool
	// Authorization is the incoming Authorization header value.
	Authorization string
	// Intent verifies Credentials for this request.
	Intent Intent
	// Request is the canonical request shape the Challenge binds to.
	Request map[string]any
	// Body is the actual request body bytes/string/object the digest binds to.
	// When set, issued challenges include a body digest and submitted
	// credentials must echo a digest matching this value (see
	// mpp.ComputeBodyDigest). A []byte or string, or a named type of either,
	// is digested as is; any other value as its json.Marshal output. An
	// io.Reader or a value json.Marshal cannot encode is an error.
	Body any
	// Realm is the expected server realm.
	Realm string
	// SecretKey signs and verifies Challenge IDs.
	SecretKey string
	// Method is the payment method token, for example "tempo".
	Method string
	// Description is copied into a newly issued Challenge.
	Description string
	// Meta stores opaque Challenge metadata.
	Meta map[string]string
	// Expires overrides the default Challenge expiry.
	Expires string
	// Header selects the HTTP field for the Payment credential. Empty defaults
	// to Authorization. Payment-Authorization is advertised when set.
	Header string
}

type VerifyResult struct {
	// Challenge is returned when the server needs the client to pay first.
	Challenge *mpp.Challenge
	// Credential is the parsed client credential on success.
	Credential *mpp.Credential
	// Receipt acknowledges successful verification.
	Receipt *mpp.Receipt
}