contracts

type Cancelled struct {
	SubscriptionID uuid.UUID `json:"subscriptionId"`
	EndsAt         time.Time `json:"endsAt"`
	Immediate      bool      `json:"immediate"`
	Reason         string    `json:"reason,omitempty"`
	At             time.Time `json:"at"`
}

type Charge struct {
	// Subject is what is being paid for. Here it is the subscription's id; the
	// field is named for the role rather than for this module's entity because
	// the private catalogue's payment module fills it with the payment's own
	// id, and a field called Subscription holding a payment id is a field that
	// lies in every log line it appears in. It was Subscription until E5.fix.
	Subject     uuid.UUID `json:"subjectId"`
	PlanCode    string    `json:"planCode"`
	AmountCents int64     `json:"amountCents"`
	Currency    string    `json:"currency"`
	PeriodEnd   time.Time `json:"periodEnd"`

	// IdempotencyKey is what the provider must key its own record on, so that
	// this charge attempted twice — a job that ran again after a crash, a
	// retry after a timeout whose answer was lost — takes the money once.
	//
	// It is derived and not generated: the subject and the period being paid
	// for are the whole identity of a charge, so the same period asked for
	// twice is the same key. A provider that ignores it will double-charge a
	// customer the first time a worker is killed between the call and the
	// commit, which is why this is stated as a requirement of the interface
	// below rather than as a hint.
	IdempotencyKey string `json:"idempotencyKey"`
}

type Features []string

type PastDue struct {
	SubscriptionID uuid.UUID `json:"subscriptionId"`
	AmountCents    int64     `json:"amountCents"`
	Currency       string    `json:"currency"`
	Since          time.Time `json:"since"`
	// Attempt is how many consecutive charges have failed, so a subscriber
	// writing to the customer can say "we tried again" without keeping a count
	// of its own, and EndsAt is when the grace period runs out.
	Attempt int       `json:"attempt"`
	EndsAt  time.Time `json:"endsAt"`
	At      time.Time `json:"at"`
}

type PaymentProvider interface {
	Charge(ctx context.Context, c Charge) (Receipt, error)
}

type Plan struct {
	crud.Base

	// Code is what an invoice, a price page and an integration call this plan,
	// unique within the tenant and unchanged when somebody renames it.
	Code string `` /* 165-byte string literal not displayed */
	// Name is what a price page shows.
	Name string `` /* 144-byte string literal not displayed */

	// PriceCents is one interval's price in the minor unit of Currency. Zero is
	// free, and a free plan renews without asking a provider for anything.
	PriceCents int64  `` /* 157-byte string literal not displayed */
	Currency   string `` /* 126-byte string literal not displayed */
	// Interval is a closed set; the enum tag is what a form renders as a select.
	Interval string `` /* 166-byte string literal not displayed */

	// Features are names and not permissions: what a name entitles somebody to
	// is the consuming module's business, so a plan can be re-priced without
	// touching an authorization.
	Features Features `json:"features,omitempty" gorm:"type:text[];not null;default:'{}'" required:"false" doc:"Feature names this plan includes"`

	// Active gates enrollment and not existence: a deactivated plan refuses new
	// subscriptions and the ones already on it keep running, because a price
	// somebody agreed to is not something a price-list edit may withdraw.
	//
	// It is required because it could not be defaulted. A Go bool has no third
	// state, so false and absent are one value, and both layers below guess:
	// GORM leaves a zero-valued field out of an INSERT when its tag declares a
	// default, and huma fills a zero-valued property from the schema's. Declare
	// true on either and {"active": false} stores an active plan. The
	// alternative is a *bool in every use of the field to fix one write.
	Active bool `json:"active" gorm:"not null" ui:"widget:checkbox" doc:"Whether this plan accepts new subscriptions" example:"true"`
}

type Receipt struct {
	// Reference is the provider's own identifier, kept so a payment can be
	// found in somebody else's system.
	Reference string    `json:"reference"`
	Settled   bool      `json:"settled"`
	Pending   bool      `json:"pending,omitempty"`
	At        time.Time `json:"at"`
}

type Renewed struct {
	SubscriptionID uuid.UUID `json:"subscriptionId"`
	PeriodStart    time.Time `json:"periodStart"`
	PeriodEnd      time.Time `json:"periodEnd"`
	Receipt        string    `json:"receipt,omitempty"`
	At             time.Time `json:"at"`
}

type Service interface {
	// Current is the tenant's subscription, or ErrNotFound when it has never
	// had one.
	Current(ctx context.Context, tx db.Tx[db.Tenant]) (*Subscription, error)

	// Subscribe enrolls the tenant in a plan. The same plan again says nothing;
	// a different one swaps the plan and leaves the period alone, so the new
	// price applies at the next renewal and nobody is refunded or
	// double-charged for days already served — this module does not prorate.
	// An inactive plan is refused, and a subscription that has ended is
	// resubscribed rather than duplicated, because a tenant has one.
	//
	// A plan change is refused while the subscription is past due, with
	// ErrConflict. That is the review's escape route closed: a tenant that owed
	// money moved itself to a cheaper plan and the debt went with the old
	// price. What is owed is owed for a period already served, and it is
	// settled or the grace period runs out; it is not renegotiated.
	//
	// The trial is issued once per tenant, ever, and TrialUsedAt is what says
	// so: it is read across every row this tenant has, deleted ones included,
	// rather than inferred from there being no live subscription. A first
	// subscription is served before any money is asked for; a resubscribe is
	// not, because four cancellations used to be four free periods.
	//
	// A resubscribe carries the outstanding period, the attempt count and the
	// grace clock forward untouched. A tenant that owed money when it left owes
	// it when it comes back, and comes back past due.
	Subscribe(ctx context.Context, tx db.Tx[db.Tenant], planID uuid.UUID) (*Subscription, error)

	// Cancel ends the subscription: at the end of the period it is serving, or
	// now. Cancelling twice the same way changes nothing; ending it now after
	// asking to end later is a second decision and says so; asking to end later
	// after it has ended is a conflict.
	//
	// Ending it now is refused with ErrConflict while a period is outstanding,
	// naming that period. That is the dunning ceiling's other escape route
	// closed: cancelling now and resubscribing took the subscription out of
	// past_due, and a review did it live for as many free periods as it liked.
	// A customer who owes money may still leave at the end of the period.
	Cancel(ctx context.Context, tx db.Tx[db.Tenant], atPeriodEnd bool) (*Subscription, error)

	// Renew advances a subscription whose period has run out, and it is the
	// half of a renewal where no money moves: a period still running is left
	// alone, a subscription whose customer cancelled is ended — silently,
	// because Cancel already said when it would — and a free subscription
	// starts its next period and publishes billing.renewed. A past-due one
	// whose grace period has run out is cancelled, with
	// billing.cancelled{reason: dunning}, which is the ceiling on retrying a
	// dead card. Otherwise it returns the charge and changes nothing; the
	// caller takes that money outside every transaction and brings the answer
	// to Settle.
	//
	// The charge is for the price stamped on the subscription and not the
	// plan's current one, so a price list edit applies from the next period.
	Renew(ctx context.Context, tx db.Tx[db.Tenant]) (*Subscription, *Charge, error)

	// Settle records what a provider said. A settled receipt starts the next
	// period and publishes billing.renewed; a refused one leaves the period
	// alone, marks the subscription past due and publishes billing.past_due —
	// once, because the job runs every night and a customer whose card is dead
	// must not be an event a night forever. A pending receipt is neither: the
	// subscription is left exactly as it was, nothing is published, and the
	// same charge is presented again tomorrow under the same idempotency key.
	// A charge for a period the subscription has moved past is ignored and says
	// nothing.
	Settle(ctx context.Context, tx db.Tx[db.Tenant], c Charge, r Receipt) (*Subscription, error)
}

type Subscribed struct {
	SubscriptionID uuid.UUID `json:"subscriptionId"`
	PlanID         uuid.UUID `json:"planId"`
	PlanCode       string    `json:"planCode"`
	Status         string    `json:"status"`
	PeriodEnd      time.Time `json:"periodEnd"`
	At             time.Time `json:"at"`
}

type Subscription struct {
	crud.Base

	// PlanID is the plan being billed, and a plan of this tenant: every query
	// here runs under the tenant's own policy.
	PlanID uuid.UUID `json:"planId" gorm:"type:uuid;not null" format:"uuid" doc:"The plan this subscription is for"`
	// Status is a closed set, moved only by the commands.
	Status string `` /* 175-byte string literal not displayed */

	// The period being served. The next one starts exactly where this one
	// ended, so periods chain rather than drift with the hour a job ran.
	CurrentPeriodStart time.Time `` /* 151-byte string literal not displayed */
	CurrentPeriodEnd   time.Time `` /* 147-byte string literal not displayed */

	// CancelAtPeriodEnd is a customer who has left and is still owed what they
	// paid for. Nothing shortens the period: cancelling is not a refund.
	CancelAtPeriodEnd bool `` /* 174-byte string literal not displayed */

	// PriceCents and Currency are the plan's price as it was when this
	// subscription last started a period, stamped here rather than read from
	// the plan at renewal.
	//
	// Without them a price list edit was retroactive: raising a plan's price
	// changed what every live subscriber was charged that night, and changing
	// its currency charged them in another one. Stamping is what makes
	// re-pricing apply from the next period — the renewal charges what is here,
	// and then copies the plan's current price forward for the period after.
	PriceCents int64  `` /* 172-byte string literal not displayed */
	Currency   string `` /* 167-byte string literal not displayed */

	// TrialUsedAt is when this tenant's trial was issued, and it is never
	// cleared. A subscription that cancelled and resubscribed used to get a
	// fresh trial, so four cancellations were four free periods; now the first
	// one is the only one, and a resubscribe starts active with a charge due at
	// the end of the period it has just been given.
	TrialUsedAt *time.Time `` /* 129-byte string literal not displayed */

	// AttemptCount and PastDueSince are the dunning state. A charge that does
	// not settle increments the count and starts the clock; a charge that does
	// clears both. Past GraceDays the subscription is cancelled, which is the
	// ceiling the old module had and this one had lost: without it a dead card
	// was retried every night forever.
	AttemptCount int        `` /* 139-byte string literal not displayed */
	PastDueSince *time.Time `` /* 133-byte string literal not displayed */

	// AnchorDay is the day of the month this subscription bills on, and it is
	// stored rather than derived from the period being served because a period
	// that had to be clamped must not become the anniversary. See Advance.
	AnchorDay int `` /* 150-byte string literal not displayed */
}