invoice.go

package gopay

import (
	"context"
	"time"
)

// InvoiceProvider extends Provider with read access to invoices — the billing
// documents providers generate for recurring subscription charges.
//
// It is an optional interface: providers implement it only when their API
// exposes invoices. The Client gates each method with a runtime type assertion
// and returns ErrUnsupported for providers that don't implement it. Invoices are
// most useful alongside SubscriptionProvider, where each recurring cycle
// produces an invoice carrying the charged amount and a customer-facing hosted
// URL. Creation, voiding, and payment of invoices are intentionally out of
// scope; this interface is read-only.
type InvoiceProvider interface {
	Provider

	// GetInvoice retrieves an invoice by ID.
	GetInvoice(ctx context.Context, invoiceID string) (*Invoice, error)
}

// InvoiceStatus represents the lifecycle status of an invoice, normalized across
// providers.
type InvoiceStatus string

// Invoice status values.
const (
	// InvoiceStatusDraft is an invoice that has not yet been finalized.
	InvoiceStatusDraft InvoiceStatus = "draft"
	// InvoiceStatusOpen is a finalized invoice awaiting payment.
	InvoiceStatusOpen InvoiceStatus = "open"
	// InvoiceStatusPaid is a fully paid invoice.
	InvoiceStatusPaid InvoiceStatus = "paid"
	// InvoiceStatusVoid is an invoice that was voided before payment.
	InvoiceStatusVoid InvoiceStatus = "void"
	// InvoiceStatusUncollectible is an invoice marked as unlikely to be paid.
	InvoiceStatusUncollectible InvoiceStatus = "uncollectible"
)

// String returns the string representation.
func (s InvoiceStatus) String() string { return string(s) }

// Invoice represents a billing document generated by a provider, typically for a
// recurring subscription charge.
type Invoice struct {
	// ID is the invoice ID.
	ID string

	// Status is the normalized invoice status.
	Status InvoiceStatus

	// SubscriptionID is the subscription this invoice bills, when it originates
	// from recurring billing; empty otherwise.
	SubscriptionID string

	// CustomerID is the customer the invoice is addressed to, when available.
	CustomerID string

	// Number is the provider's human-readable invoice number, when assigned.
	Number string

	// Amount is the total amount due in minor units; nil when the provider does
	// not report it.
	Amount *Amount

	// AmountPaid is the amount already paid in minor units; nil when the provider
	// does not report it.
	AmountPaid *Amount

	// HostedInvoiceURL is a customer-facing URL where the invoice can be viewed
	// and paid (Stripe's hosted_invoice_url, Razorpay's short_url); empty when
	// the provider does not expose one.
	HostedInvoiceURL string

	// PDFURL is a link to a downloadable PDF of the invoice, when the provider
	// offers one (Stripe); empty otherwise.
	PDFURL string

	// CreatedAt is the creation timestamp.
	CreatedAt time.Time

	// DueDate is when payment is due; zero when the provider does not set one.
	DueDate time.Time

	// PaidAt is when the invoice was paid; zero when unpaid or not reported.
	PaidAt time.Time

	// Metadata holds additional data.
	Metadata map[string]string

	// Provider is the provider name.
	Provider string

	// Raw contains the raw provider response.
	Raw map[string]any
}

// IsPaid returns true if the invoice has been fully paid.
func (i *Invoice) IsPaid() bool {
	return i.Status == InvoiceStatusPaid
}