mpp

type ChallengeEcho struct {
	// ID is the challenge identifier from the WWW-Authenticate header.
	ID string `json:"id"`

	// Realm is the protection space from the challenge.
	Realm string `json:"realm"`

	// Method is the payment method identifier from the challenge.
	Method string `json:"method"`

	// Intent is the payment intent type from the challenge.
	Intent string `json:"intent"`

	// Request is the base64url-encoded payment request from the challenge.
	Request string `json:"request"`

	// Expires is the challenge expiration timestamp, if present in the
	// original challenge.
	Expires string `json:"expires,omitempty"`

	// Description is the human-readable description, if present in the
	// original challenge.
	Description string `json:"description,omitempty"`

	// Opaque is the server correlation data, if present in the original
	// challenge.
	Opaque string `json:"opaque,omitempty"`

	// Digest is the content digest, if present in the original challenge.
	Digest string `json:"digest,omitempty"`
}

type ChallengeParams struct {
	// ID is the unique challenge identifier. Servers bind this value to
	// the challenge parameters via HMAC-SHA256 to enable stateless
	// verification.
	ID string

	// Realm is the protection space identifier per RFC 9110.
	Realm string

	// Method is the payment method identifier (e.g., "lightning").
	Method string

	// Intent is the payment intent type (e.g., "charge", "session").
	Intent string

	// Request is the base64url-encoded JCS-serialized JSON containing
	// payment-method-specific data needed to complete payment.
	Request string

	// Expires is an optional RFC 3339 timestamp indicating when this
	// challenge expires.
	Expires string

	// Digest is an optional content digest of the request body, formatted
	// per RFC 9530.
	Digest string

	// Description is an optional human-readable description of the
	// resource or payment purpose.
	Description string

	// Opaque is optional base64url-encoded JCS-serialized JSON containing
	// server-defined correlation data.
	Opaque string
}

type ChargeMethodDetails struct {
	// Invoice is the full BOLT11-encoded payment request string. This
	// field is authoritative; all other payment parameters are derived
	// from it.
	Invoice string `json:"invoice"`

	// PaymentHash is an optional convenience field containing the payment
	// hash embedded in the invoice, as a lowercase hex-encoded string.
	PaymentHash string `json:"paymentHash,omitempty"`

	// Network identifies the Lightning Network the invoice is issued on.
	// Must be one of "mainnet", "regtest", or "signet". Defaults to
	// "mainnet" if omitted.
	Network string `json:"network,omitempty"`
}

type ChargePayload struct {
	// Preimage is the 32-byte payment preimage revealed upon successful
	// HTLC settlement, encoded as a lowercase hex string (64 characters).
	Preimage string `json:"preimage"`
}

type ChargeRequest struct {
	// Amount is the invoice amount in base units (satoshis), encoded as a
	// decimal string.
	Amount string `json:"amount"`

	// Currency identifies the unit for Amount. Must be "sat" for
	// Lightning.
	Currency string `json:"currency"`

	// Description is an optional human-readable memo describing the
	// resource or service being paid for.
	Description string `json:"description,omitempty"`

	// Recipient is an optional payment recipient in method-native format.
	Recipient string `json:"recipient,omitempty"`

	// ExternalID is an optional merchant reference (e.g., order ID).
	ExternalID string `json:"externalId,omitempty"`

	// MethodDetails contains Lightning-specific fields nested under
	// methodDetails in the request JSON.
	MethodDetails ChargeMethodDetails `json:"methodDetails"`
}

type Credential struct {
	// Challenge contains the echoed challenge parameters from the original
	// WWW-Authenticate header.
	Challenge ChallengeEcho `json:"challenge"`

	// Source is an optional payer identifier. The recommended format is a
	// DID per W3C-DID.
	Source string `json:"source,omitempty"`

	// Payload contains the payment-method-specific proof of payment. The
	// structure depends on the method and intent. We use json.RawMessage
	// to defer parsing until the method/intent is known.
	Payload json.RawMessage `json:"payload"`
}

type NeedTopUpEvent struct {
	// SessionID is the session identifier (paymentHash of the deposit
	// invoice).
	SessionID string `json:"sessionId"`

	// BalanceSpent is the total satoshis spent from the current deposit at
	// the point of exhaustion.
	BalanceSpent int64 `json:"balanceSpent"`

	// BalanceRequired is the satoshis needed for the next unit of service.
	BalanceRequired int64 `json:"balanceRequired"`
}

type ProblemDetails struct {
	// Type is a URI reference that identifies the problem type.
	Type string `json:"type"`

	// Title is a short, human-readable summary of the problem.
	Title string `json:"title"`

	// Status is the HTTP status code.
	Status int `json:"status"`

	// Detail is a human-readable explanation specific to this occurrence.
	Detail string `json:"detail,omitempty"`

	// ChallengeID is the associated challenge identifier, if applicable.
	ChallengeID string `json:"challengeId,omitempty"`
}

type Receipt struct {
	// Status is always "success". Receipts are only issued on successful
	// payment responses.
	Status string `json:"status"`

	// Method is the payment method used (e.g., "lightning").
	Method string `json:"method"`

	// Timestamp is the RFC 3339 settlement timestamp.
	Timestamp string `json:"timestamp"`

	// Reference is a method-specific reference (e.g., payment hash hex
	// for Lightning).
	Reference string `json:"reference"`

	// ChallengeID is the challenge identifier for audit and traceability.
	ChallengeID string `json:"challengeId,omitempty"`
}

type SessionAction string

type SessionPayload struct {
	// Action is the session operation type: "open", "bearer", "topUp", or
	// "close".
	Action SessionAction `json:"action"`

	// Preimage is the hex-encoded payment preimage. Used for open, bearer,
	// and close actions. SHA-256(preimage) must equal the session's
	// paymentHash.
	Preimage string `json:"preimage,omitempty"`

	// SessionID is the paymentHash of the original deposit invoice,
	// identifying the session. Used for bearer, topUp, and close actions.
	SessionID string `json:"sessionId,omitempty"`

	// ReturnInvoice is a BOLT11 invoice with no encoded amount, created
	// by the client at session open. The server pays this invoice with the
	// unspent session balance on close. Used for open action only.
	ReturnInvoice string `json:"returnInvoice,omitempty"`

	// TopUpPreimage is the preimage of the top-up invoice. Used for topUp
	// action only. SHA-256(topUpPreimage) must equal the paymentHash of
	// the fresh invoice issued for this top-up.
	TopUpPreimage string `json:"topUpPreimage,omitempty"`
}

type SessionReceipt struct {
	// Method is always "lightning".
	Method string `json:"method"`

	// Reference is the session ID (paymentHash).
	Reference string `json:"reference"`

	// Status is always "success".
	Status string `json:"status"`

	// Timestamp is the settlement time in RFC 3339 format.
	Timestamp string `json:"timestamp"`

	// RefundSats is the unspent balance that was refunded on close. Only
	// present for close actions.
	RefundSats int64 `json:"refundSats,omitempty"`

	// RefundStatus indicates the outcome of the refund attempt on close.
	// One of "succeeded", "failed", or "skipped". Only present for close
	// actions.
	RefundStatus string `json:"refundStatus,omitempty"`
}

type SessionRequest struct {
	// Amount is the cost per unit of service in base units (satoshis),
	// encoded as a decimal string.
	Amount string `json:"amount"`

	// Currency identifies the unit for Amount. Must be "sat".
	Currency string `json:"currency"`

	// Description is an optional human-readable description of the
	// service.
	Description string `json:"description,omitempty"`

	// UnitType is an optional human-readable label for the unit being
	// priced (e.g., "token", "chunk", "request").
	UnitType string `json:"unitType,omitempty"`

	// DepositInvoice is a BOLT11 invoice the client must pay to open or
	// top up the session. Required for open and topUp challenges.
	DepositInvoice string `json:"depositInvoice,omitempty"`

	// PaymentHash is the SHA-256 hash of the deposit invoice preimage, as
	// a lowercase hex string.
	PaymentHash string `json:"paymentHash"`

	// DepositAmount is the exact deposit amount in satoshis, as a decimal
	// string. When present, must equal the amount encoded in
	// DepositInvoice.
	DepositAmount string `json:"depositAmount,omitempty"`

	// IdleTimeout is the server's idle timeout policy for open sessions,
	// in seconds, as a decimal string.
	IdleTimeout string `json:"idleTimeout,omitempty"`
}