plan

type Limits struct {
	// Subscription (API) limits
	RequestsPerMinute *int `json:"requestsPerMinute,omitempty"`
	TokensPerMinute   *int `json:"tokensPerMinute,omitempty"`
	FreeCredit        *int `json:"freeCredit,omitempty"`
	MaxMembers        *int `json:"maxMembers,omitempty"`

	// MinSeats is the minimum billable seat count for per-seat plans
	// (price_ref.recurring.per_seat) — the ONE canonical home for seat minimums.
	// Billing charges at least this many seats.
	MinSeats *int `json:"minSeats,omitempty"`

	// TeamGuests is the back-compat source for the team.guests entitlement:
	// max invited guests on the holder's hanzo.team workspace (-1 = unlimited).
	TeamGuests *int `json:"teamGuests,omitempty"`

	// IncludedCreditUsd is a legacy alias (entitlements["commerce.included_credit_usd"]).
	// IncludedCloudCredits(+PerUser) is the cloud allowance the monthly allotment
	// grants (the canonical cloud.included_credits_usd entitlement).
	IncludedCreditUsd           *int `json:"includedCreditUsd,omitempty"`
	IncludedCloudCredits        *int `json:"includedCloudCredits,omitempty"`
	IncludedCloudCreditsPerUser *int `json:"includedCloudCreditsPerUser,omitempty"`

	// DNS limits
	Zones          *int `json:"zones,omitempty"`
	RecordsPerZone *int `json:"recordsPerZone,omitempty"`
	QueriesPerDay  *int `json:"queriesPerDay,omitempty"`
}

type Plan struct {
	mixin.Model[Plan]

	// Unique human readable id
	Slug string `json:"slug"`
	// Internal id
	SKU string `json:"sku"`

	// Human readable name
	Name        string `json:"name"`
	Description string `json:"description"`

	// Category is the plan family ("personal"/"team"/"enterprise"/"world"/
	// "social"/"dns"); GET /v1/billing/plans?category= filters on it.
	Category string `json:"category"`

	Price currency.Cents `json:"price"`
	// PriceAnnual is the per-month price when billed annually, in cents — the
	// authoritative annual price (previously derived at the read edge from the
	// embed). Like Price it is a TYPED money field, never an untyped Metadata
	// value, so a stored/spoofed plan copy can never inflate it.
	PriceAnnual     currency.Cents `json:"priceAnnual"`
	Currency        currency.Type  `json:"currency"`
	Interval        Interval       `json:"interval"`
	IntervalCount   int            `json:"intervalCount"`
	TrialPeriodDays int            `json:"trialPeriodDays"`

	// PerSeat marks a plan billed per seat (catalog price_ref.recurring.per_seat):
	// invoices charge Price × subscription quantity, floored at 1.
	PerSeat bool `json:"perSeat"`

	// ContactSales marks a custom / "contact sales" plan whose price is NULL, not
	// $0 — the ONE way to preserve the free($0)-vs-custom(null) distinction while
	// keeping Price a typed, non-nullable Cents (mirrors the embed's staticPlan).
	// A null-priced plan is stored Price=0 + ContactSales=true; a free plan is
	// Price=0 + ContactSales=false. Never coerce null→0 WITHOUT this flag, or a
	// custom plan spuriously reads as a $0 charge.
	ContactSales bool `json:"contactSales,omitempty"`
	// Popular flags the highlighted tier within a category (display only).
	Popular bool `json:"popular,omitempty"`

	// Managed marks a row OWNED by the seed or the SuperAdmin CRUD (authoritative).
	// The corrective boot seed force-corrects UNMANAGED rows — accidental partials
	// written by a subscription-flow path (Red: the bundle expansion wrote a
	// Price=0, envelope-less row that under-charged a direct sub) — to the embed,
	// and LEAVES managed rows so an admin price edit is preserved. One flag
	// distinguishes "authoritative" from "accidental", closing the divergence.
	Managed bool `json:"managed,omitempty"`

	// Status is the row's lifecycle, on the Shopify product model: a plan is
	// ACTIVE (sold and listed), DRAFT (exists, not yet listed) or ARCHIVED
	// (retired, kept). Only ACTIVE rows reach the public catalog.
	//
	// It exists because without it "stop selling this" and "destroy this" were the
	// SAME operation. The public read returned every stored row, so the only way to
	// unlist a plan was DELETE — which takes the row's history with it and orphans
	// any subscription that recorded the slug. Retiring a tier should never be
	// destructive; archiving keeps the row resolvable for invoices and renewals
	// that already reference it.
	//
	// EMPTY MEANS ACTIVE, deliberately. Every row written before this field existed
	// has no value for it, and a zero-value that meant "draft" would unlist the
	// entire catalog on deploy. Use Listed() rather than comparing this directly.
	Status string `json:"status,omitempty"`

	// The DISPLAY ENVELOPE: presentation, not money. The typed columns above are
	// what charges; these are what the pricing page renders.
	//
	// They are JSON-visible and datastore-SKIPPED on purpose. JSON-visible so the
	// model's shape IS the wire shape — the admin CRUD decodes a request body
	// straight onto a Plan, so whatever GET /v1/billing/plans emits, PUT
	// /v1/plans/entries/:slug accepts. Before they existed the envelope lived ONLY
	// inside Metadata as a packed JSON string, so an admin PUT carrying `features`
	// set the price and silently discarded the copy: a tier could be repriced but
	// never re-described, which is how a plan comes to be sold at one price while
	// its own feature list quotes another.
	//
	// Datastore-skipped because they still PERSIST packed into Metadata_ (Save
	// packs, Load unpacks) — one storage location, unchanged on disk, so existing
	// rows keep working and there is no migration.
	Features   []string `json:"features,omitempty" datastore:"-"`
	Bundles    []string `json:"bundles,omitempty" datastore:"-"`
	IncludedIn []string `json:"includedIn,omitempty" datastore:"-"`
	Limits     *Limits  `json:"limits,omitempty" datastore:"-"`

	// Metadata carries anything else a plan needs to hold, plus the packed
	// envelope above. Metadata_ MUST be datastore:",noindex" (persisted), NOT "-"
	// (skipped): with "-" the whole blob Save()s but never round-trips, so a DB
	// read drops limits/minSeats/features (prod: team.minSeats served null).
	// Mirrors catalogentry exactly — the persisted-blob pattern is the one way.
	Metadata  Map    `json:"metadata,omitempty" datastore:"-"`
	Metadata_ string `json:"-" datastore:",noindex"`

	Ref refs.EcommerceRef `json:"ref,omitempty"`
}