contracts

type CancelParams struct {
	// AtPeriodEnd keeps access until the paid period runs out rather than
	// revoking immediately — the usual, humane default for a cancellation.
	AtPeriodEnd bool
	// Comment is recorded with the gateway where supported.
	Comment string
}

type Charge struct {
	Gateway     string // "stripe" | "razorpay" | …
	ID          string // Checkout session (Stripe) or order (Razorpay)
	RedirectURL string // set for hosted-checkout gateways; empty for widgets
	Amount      int64
	Currency    string
	Raw         map[string]any // decoded gateway response
}

type ChargeParams struct {
	Amount   int64  // smallest currency unit (paise for INR, cents for USD)
	Currency string // "INR", "USD", …

	Mode    string // "subscription" | "payment" (Stripe). Default "payment".
	PriceID string // Stripe Price (price_…) for recurring billing.

	CustomerID    string
	CustomerEmail string

	SuccessURL string // redirect (hosted-checkout) gateways
	CancelURL  string

	Reference string // your order id (Razorpay receipt / correlation)
	Metadata  map[string]string
}

type Customer struct {
	Gateway string
	ID      string
	Email   string
	Subject string
	Raw     map[string]any
}

type CustomerGateway interface {
	CreateCustomer(ctx context.Context, p CustomerParams) (*Customer, error)
	GetCustomer(ctx context.Context, id string) (*Customer, error)
}

type CustomerParams struct {
	Subject  string // your user id
	Email    string
	Name     string
	Phone    string
	Metadata map[string]string
}

type IAPEntitlement struct {
	Platform      IAPPlatform
	ProductID     string
	Subject       string
	TransactionID string
	// OriginalTransactionID ties every renewal of one subscription together;
	// it is the stable key to mirror against, not the per-renewal id.
	OriginalTransactionID string

	Subscription bool
	Active       bool
	ExpiresAt    *time.Time

	// PriceMicros is the transaction value in millionths of a currency unit
	// (1_000_000 = one dollar), and Currency its ISO code. Metering bills on
	// this, so a store that does not report a price yields zero and is treated
	// as non-billable rather than guessed at.
	PriceMicros int64
	Currency    string
	// AutoRenewing is the store's current intent; a subscription can be active
	// now yet set not to renew.
	AutoRenewing bool

	// Environment is "production" or "sandbox"; a sandbox receipt reaching a
	// production server is the classic test-purchase-as-real bug.
	Environment string

	Raw map[string]any
}

type IAPPlatform string

type IAPVerifier interface {
	Platform() IAPPlatform
	// VerifyReceipt checks a client-supplied purchase against the store and
	// returns the entitlement the store actually vouches for.
	VerifyReceipt(ctx context.Context, p ReceiptParams) (*IAPEntitlement, error)
	// ParseNotification verifies and decodes a server-to-server notification.
	ParseNotification(payload []byte) (*StoreNotification, error)
}

type PaymentGateway interface {
	Name() string
	CreateCharge(ctx context.Context, p ChargeParams) (*Charge, error)
	VerifyPayment(ctx context.Context, proof PaymentProof) (bool, error)
	VerifyWebhook(payload []byte, headers http.Header) (*WebhookEvent, error)
}

type PaymentProof struct {
	OrderID   string
	PaymentID string
	Signature string
}

type ReceiptParams struct {
	Platform IAPPlatform
	// ProductID is the store product the app reports buying; verification must
	// confirm the signed payload names the same product.
	ProductID string
	Subject   string // your user id

	// Apple: the JWS transaction from StoreKit 2 (or a legacy base64 receipt).
	// Google: the purchase token returned by the Play Billing library.
	Token string

	// Google needs the product kind to pick the right API; Apple does not.
	Subscription bool
}

type Refund struct {
	Gateway   string
	ID        string
	PaymentID string
	Amount    int64
	Currency  string
	Status    RefundStatus
	Raw       map[string]any
}

type RefundGateway interface {
	Refund(ctx context.Context, p RefundParams) (*Refund, error)
}

type RefundParams struct {
	PaymentID   string
	Amount      int64 // smallest unit; 0 → full refund
	Currency    string
	Reason      string // "requested_by_customer" | "duplicate" | "fraudulent" | provider-specific
	Idempotency string
	Metadata    map[string]string
}

type RefundStatus string

type StoreNotification struct {
	Platform              IAPPlatform
	Type                  string // canonical: "renewed" | "canceled" | "expired" | "refunded" | "grace_period" | provider-specific
	ProductID             string
	OriginalTransactionID string
	ExpiresAt             *time.Time
	Raw                   []byte
}

type Subscription struct {
	Gateway    string
	ID         string             // gateway subscription id
	Status     SubscriptionStatus // canonical
	PlanID     string
	CustomerID string
	Subject    string

	CurrentPeriodEnd *time.Time
	TrialEnd         *time.Time
	CancelAt         *time.Time // set when scheduled to cancel at period end
	CanceledAt       *time.Time
	EndedAt          *time.Time

	// AuthURL is a redirect the customer must complete to authorise the mandate
	// (e-mandate / SCA). Empty when the subscription is active immediately.
	AuthURL string

	Raw map[string]any
}

type SubscriptionGateway interface {
	CreateSubscription(ctx context.Context, p SubscriptionParams) (*Subscription, error)
	GetSubscription(ctx context.Context, id string) (*Subscription, error)
	CancelSubscription(ctx context.Context, id string, p CancelParams) (*Subscription, error)
}

type SubscriptionParams struct {
	PlanID     string // Stripe price_… / Razorpay plan_… / provider plan ref
	CustomerID string // gateway customer id, when the gateway needs one
	Subject    string // your user id, mirrored onto the local record

	Quantity    int64
	TrialDays   int
	TrialEnd    *time.Time
	CouponCode  string
	Metadata    map[string]string
	Idempotency string // caller-supplied key; gateways that support it dedupe on it

	// TotalCycles bounds a fixed-length subscription (0 = until cancelled).
	TotalCycles int
	// NotifyURL / ReturnURL for gateways that authenticate the mandate via a
	// redirect (Indian e-mandate flows).
	NotifyURL string
	ReturnURL string
}

type SubscriptionPauser interface {
	PauseSubscription(ctx context.Context, id string) (*Subscription, error)
	ResumeSubscription(ctx context.Context, id string) (*Subscription, error)
}

type SubscriptionStatus string

type SubscriptionSwapper interface {
	SwapSubscription(ctx context.Context, id string, p SwapParams) (*Subscription, error)
}

type SwapParams struct {
	NewPlanID string
	Quantity  int64
	// Prorate bills or credits the difference immediately. Off defers the new
	// price to the next cycle.
	Prorate bool
}

type WebhookEvent struct {
	Gateway string
	Type    string // gateway event type, e.g. "payment.captured"
	ID      string
	Raw     []byte // raw verified body
}