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 IAPAcknowledger interface {
	Acknowledge(ctx context.Context, productID, token string, subscription bool) error
}

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

	// PeriodType is "trial", "intro" or "normal" where the store says which
	// kind of period this transaction pays for ("" when it does not say).
	PeriodType string
	// PurchasedAt is when this transaction (this renewal) was bought.
	PurchasedAt *time.Time
	// Revoked is set when the store took the purchase back (a refund, a
	// family-sharing removal). A revoked purchase never grants access.
	Revoked bool
	// BillingIssue is set while the store is retrying a failed renewal. With
	// GraceExpiresAt in the future the user keeps access through the store's
	// own grace period; without it, access has already lapsed (billing retry
	// or Google's account hold).
	BillingIssue   bool
	GraceExpiresAt *time.Time

	// Token is Google's purchase token: the handle every later API call and
	// notification uses. LinkedToken is the token this purchase replaced
	// (an upgrade, a downgrade, a resubscribe), so the replaced row can be
	// retired instead of expiring as if the user had left. Apple leaves both
	// empty.
	Token       string
	LinkedToken string
	// Acknowledged is Google's acknowledgement state. Google refunds any
	// purchase that is not acknowledged within three days.
	Acknowledged bool
	// AppAccountToken is the UUID an iOS app attached to the purchase
	// (StoreKit 2's appAccountToken); it names the buyer's account.
	AppAccountToken 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

	// RenewalInfo is Apple's optional signed renewal info JWS (StoreKit 2's
	// Product.SubscriptionInfo.RenewalInfo). With it the verifier knows
	// whether the subscription will renew and whether it is in grace.
	RenewalInfo string
}

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 is canonical: "purchased" | "renewed" | "canceled" | "uncanceled" |
	// "expired" | "refunded" | "grace_period" | "billing_issue" |
	// "product_change" | "paused" | "recovered" | "test", or provider-specific.
	Type string
	// Subtype is the store's own type and subtype, for logs
	// ("DID_CHANGE_RENEWAL_STATUS/AUTO_RENEW_DISABLED", "google_3").
	Subtype               string
	ProductID             string
	OriginalTransactionID string
	TransactionID         string
	ExpiresAt             *time.Time
	// ID is the store's delivery id (Apple's notificationUUID, Pub/Sub's
	// messageId); a store retries deliveries, so handlers dedupe on it.
	ID string
	// Environment is "production" or "sandbox".
	Environment string
	// Token is Google's purchase token (empty for Apple).
	Token string
	// Entitlement is the purchase state the notification itself vouches for.
	// Apple signs the latest transaction and renewal info into every
	// notification, so it is set there; Google's notifications carry only a
	// token, so it is nil and the handler re-verifies against the API.
	Entitlement *IAPEntitlement
	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
}