link

type Link struct {
	ID       string
	Org      string
	User     string // the owning subject (validated principal); a user sees only their own
	Machine  string // stable machine id (the device key)
	Host     string // hostname (device label)
	OS       string // platform label (darwin|linux|windows|…)
	Provider string // matches @hanzo/usage providerRegistry id (claude|codex|hanzo|openai|…)
	Account  string // the subscription/account id or label (e.g. an account email)
	Plan     string // the plan name from the provider identity (e.g. "Claude Max"); display only
	Kind     string // subscription | apikey
	Status   string // linked | revoked
	LastSeen int64  // unix; bumped on every usage report
	Usage    string // JSON of the latest Usage projection ("" until first report)

	CreatedAt int64
	UpdatedAt int64
}

type RouteCandidate struct {
	Provider    string  `json:"provider"`
	Account     string  `json:"account,omitempty"`
	Plan        string  `json:"plan,omitempty"`
	Kind        string  `json:"kind"`    // subscription | apikey
	Billing     string  `json:"billing"` // plan | commerce (BillingMode(Kind))
	Available   bool    `json:"available"`
	HeadroomPct float64 `json:"headroomPct"` // remaining capacity 0..100
	Machine     string  `json:"machine,omitempty"`
	Host        string  `json:"host,omitempty"`
	LinkID      string  `json:"linkId"`
	Reason      string  `json:"reason,omitempty"` // why unavailable, when Available=false
}

type RoutePlan struct {
	Candidates  []RouteCandidate `json:"candidates"`
	Primary     *RouteCandidate  `json:"primary,omitempty"`
	GeneratedAt string           `json:"generatedAt"`
}

type Sample struct {
	Provider string // matches Link.Provider / @hanzo/usage providerRegistry id
	Account  string // the account label (an identifier, never a secret)
	Plan     string // the plan name from the provider identity; display only
	Kind     string // subscription | apikey (validKind) — mirrors Link.Kind
	Machine  string // the machine that OBSERVED this (an attribute, not a key)

	Lane          string    // the meter's lane id (five_hour|seven_day_opus|…) — the identity
	Window        string    // the canonical class (6h|day|week|month)
	WindowMinutes int32     // the duration the meter reported (300 for Claude's 5h)
	WindowStart   time.Time // WHICH instance of the window this measures — the dedup key
	ResetsAt      time.Time // when the window resets (RateWindow.resetsAt); zero = unknown

	// UsedPct is the lane's used percent, 0..100 — RateWindow.usedPercent. For a
	// subscription account this is THE quota signal and often the ONLY one.
	//
	// QUOTA GAP (deliberate, reported, not faked): there is NO absolute
	// used/limit token quota column, because nothing can populate one. The meter
	// reports a percent, not a limit (Claude: dataConfidence `percentOnly`). The
	// hanzoai/plans catalog expresses `ai.requests_per_min` / `ai.tokens_per_min`
	// — per-MINUTE rate limits, a different concept from a window quota — and in
	// any case it is HANZO's own plan catalog, which cannot know what Anthropic
	// grants a Claude Max plan. An always-zero quota_limit would read as "the
	// limit is zero"; absent is honest. It lands as an additive column when a
	// source for it exists.
	UsedPct    float64
	Confidence string // exact|estimated|percentOnly|unknown — see the const block
	// Synthetic marks a lane the meter FABRICATED (RateWindow.isSyntheticPlaceholder
	// — set when a provider returned null for a lane and the adapter filled it in).
	// Carried so a made-up lane is never rendered as observed truth.
	Synthetic bool

	// Absolute counters — UsageTotals. Present only when the source really reports
	// them (`exact`); zero otherwise, which Confidence disambiguates.
	Requests          int64
	InputTokens       int64
	OutputTokens      int64
	TotalTokens       int64
	CachedInputTokens int64

	// Money — ProviderCostSnapshot, in minor units (cents). CostCents is what the
	// PROVIDER says this account spent (Claude's extra_usage overage; 0 for a flat
	// subscription — the plan is the charge). CostLimitCents is that meter's budget
	// (ProviderCostSnapshot.limit) — a MONEY cap, never a token quota. Neither is a
	// Hanzo charge: this plane holds no metering client.
	CostCents      int64
	CostLimitCents int64
	Currency       string // ProviderCostSnapshot.currencyCode; "" = unknown
}

type SessionMatch struct {
	Subject  string
	Host     string
	Provider string
	Account  string
}

type Sessions interface {
	Stop(ctx context.Context, org string, m SessionMatch) (int, error)
	CountActive(ctx context.Context, org string, m SessionMatch) (int, error)
}

type Store struct {
	// contains filtered or unexported fields
}

type Total struct {
	Source     string
	Scope      string
	Provider   string
	Window     string
	Requests   int64
	Tokens     int64
	CostCents  int64
	UsedPct    float64
	Confidence string
	Windows    int64
}

type Usage struct {
	SessionPct   float64 `json:"sessionPct"`             // primary window used %, 0..100
	WeeklyPct    float64 `json:"weeklyPct"`              // secondary window used %, 0..100
	ResetsAt     string  `json:"resetsAt,omitempty"`     // primary window reset, RFC3339
	Tokens       int64   `json:"tokens"`                 // absolute token total when known
	InputTokens  int64   `json:"inputTokens,omitempty"`  //
	OutputTokens int64   `json:"outputTokens,omitempty"` //
	SpendCents   int64   `json:"spendCents"`             // provider spend (0 for a subscription)
	Currency     string  `json:"currency,omitempty"`     //
	Confidence   string  `json:"confidence,omitempty"`   // exact|estimated|percentOnly|unknown
	UpdatedAt    string  `json:"updatedAt,omitempty"`    // snapshot time, RFC3339
}