method.go

package mppx

import "context"

// ServerMethod is a payment method that verifies credentials on the server side.
// Implement this interface to add a custom payment method to your server.
//
// Example usage:
//
//	type MyChargeMethod struct {
//	    recipient string
//	    currency  string
//	}
//
//	func (m *MyChargeMethod) Name() string   { return "mymethod" }
//	func (m *MyChargeMethod) Intent() string { return "charge" }
//	func (m *MyChargeMethod) DefaultRequest() map[string]any {
//	    return map[string]any{"currency": m.currency, "recipient": m.recipient}
//	}
//	func (m *MyChargeMethod) Verify(ctx context.Context, cred Credential, req map[string]any) (Receipt, error) {
//	    // verify payment on-chain, via API, etc.
//	    return NewReceipt(ReceiptParams{Method: m.Name(), Reference: txHash}), nil
//	}
type ServerMethod interface {
	// Name returns the payment method identifier (e.g. "tempo", "stripe").
	Name() string
	// Intent returns the intent type (e.g. "charge", "session").
	Intent() string
	// DefaultRequest returns default request parameters merged with call-site options.
	// Return nil if no defaults.
	DefaultRequest() map[string]any
	// Verify verifies a payment credential and returns a Receipt.
	// Return a *PaymentError for payment-specific failures (will be serialized to RFC 9457).
	// Return any other error for internal failures (wrapped in VerificationFailedError).
	Verify(ctx context.Context, cred Credential, req map[string]any) (Receipt, error)
}

// ClientMethod is a payment method that creates credentials on the client side.
// Implement this interface to add a custom payment method to your client.
type ClientMethod interface {
	// Name returns the payment method identifier.
	Name() string
	// Intent returns the intent type.
	Intent() string
	// CreateCredential creates a payment credential from a challenge.
	// Returns the serialized credential string suitable for an Authorization header.
	CreateCredential(ctx context.Context, challenge Challenge) (string, error)
}

// MethodKey returns the canonical "name/intent" key for a ServerMethod.
func MethodKey(m ServerMethod) string {
	return m.Name() + "/" + m.Intent()
}

// MergeRequest merges method defaults with call-site request parameters.
// Call-site values take precedence over defaults.
func MergeRequest(method ServerMethod, callSiteRequest map[string]any) map[string]any {
	defaults := method.DefaultRequest()
	if len(defaults) == 0 {
		return callSiteRequest
	}
	merged := make(map[string]any, len(defaults)+len(callSiteRequest))
	for k, v := range defaults {
		merged[k] = v
	}
	for k, v := range callSiteRequest {
		merged[k] = v
	}
	return merged
}