receipt.go

package mppx

import (
	"encoding/base64"
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
	"time"
)

// Receipt is a payment receipt returned by a server after successful payment verification.
type Receipt struct {
	// Method is the payment method used (e.g. "tempo", "stripe").
	Method string `json:"method"`
	// Reference is a method-specific payment reference (e.g. transaction hash).
	Reference string `json:"reference"`
	// Status is always "success". Failures use HTTP 402 + Problem Details.
	Status string `json:"status"`
	// Timestamp is the RFC 3339 settlement timestamp.
	Timestamp string `json:"timestamp"`
	// ExternalID is an optional external reference ID echoed from the credential payload.
	ExternalID string `json:"externalId,omitempty"`
}

// ReceiptParams holds parameters for creating a Receipt.
type ReceiptParams struct {
	Method     string
	Reference  string
	Timestamp  time.Time // defaults to time.Now() if zero
	ExternalID string
}

// NewReceipt creates a Receipt. Status is always set to "success".
func NewReceipt(p ReceiptParams) Receipt {
	ts := p.Timestamp
	if ts.IsZero() {
		ts = time.Now().UTC()
	}
	return Receipt{
		Method:     p.Method,
		Reference:  p.Reference,
		Status:     ReceiptStatusSuccess,
		Timestamp:  ts.Format(time.RFC3339),
		ExternalID: p.ExternalID,
	}
}

// SerializeReceipt serializes a Receipt to a base64url-encoded JSON string
// suitable for the Payment-Receipt response header.
func SerializeReceipt(r Receipt) string { //nolint:gocritic // Public API keeps value params for backward compatibility.
	data, err := json.Marshal(r)
	if err != nil {
		return ""
	}
	return base64.RawURLEncoding.EncodeToString(data)
}

// DeserializeReceipt decodes a base64url-encoded Payment-Receipt header value.
func DeserializeReceipt(encoded string) (Receipt, error) {
	data, err := base64.RawURLEncoding.DecodeString(encoded)
	if err != nil {
		return Receipt{}, fmt.Errorf("mpp: invalid base64url in receipt: %w", err)
	}
	var r Receipt
	if err := json.Unmarshal(data, &r); err != nil {
		return Receipt{}, fmt.Errorf("mpp: invalid JSON in receipt: %w", err)
	}
	return r, nil
}

// ExtractReceipt extracts the Receipt from an HTTP response's Payment-Receipt header.
func ExtractReceipt(resp *http.Response) (Receipt, error) {
	header := resp.Header.Get(PaymentReceiptHeader)
	if header == "" {
		return Receipt{}, errors.New("mpp: missing " + PaymentReceiptHeader + " header")
	}
	return DeserializeReceipt(header)
}