metering

type AuthInput struct {
	User     string
	Actor    string
	Org      string
	Currency string
	// Amount, when non-zero, gates on available >= Amount instead of the bare
	// available > 0. Use it to authorize a known up-front charge (e.g. the first
	// hour of a machine) so a 1-cent balance cannot green-light an arbitrarily
	// expensive request. Zero preserves the "any positive balance" gate.
	//
	// It is the exact, typed value — the same one Usage.Amount carries, at the
	// ledger's own 18-decimal precision — so the gate and the debit that follows
	// it weigh the SAME number. A cents-rounded gate admitted a charge the debit
	// then wrote in full, which is how a sub-cent price gets authorized against a
	// figure nobody spent.
	Amount money.Amount

	// AmountCents is the same charge in whole cents, for the HTTP path to
	// commerce and for callers that have not got a typed value. Amount wins when
	// both are set.
	AmountCents int64

	// Project and Service scope the per-scope spend cap + rate limit (issue #70).
	// Service is server-derived (route/provider). Empty = the org-wide default
	// scope. Forwarded to commerce so the right scope cap is resolved; they never
	// change which BALANCE is gated — that is the address (Org, User), always.
	Project string
	Service string

	// ProjectValidated reports whether Project is bound to a VALIDATED identity
	// claim. When false, commerce DEGRADES a project-scoped hard cap to a soft warn
	// (records + warns, never 402) so a forgeable X-Project-Id can neither hard-stop
	// nor be evaded. The org and service axes are always validated. Today IAM mints
	// no project claim, so cloud sends false; when it does, cloud sends true and
	// project caps auto-harden.
	ProjectValidated bool
}

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

type Config struct {
	// BaseURL is the commerce service base, e.g.
	// "http://commerce.hanzo.svc.cluster.local:8001". No trailing /v1 — the
	// client appends the canonical billing paths itself.
	BaseURL string

	// Token is the commerce service token (admin-scoped). MUST come from KMS;
	// never hard-code or read from a file. Sent as "Authorization: Bearer".
	Token string

	// Org is the tenant org slug (e.g. "hanzo") sent as X-Org-Id so
	// commerce resolves the right tenant namespace. Per-request Org on the
	// Usage/AuthInput overrides this default.
	Org string

	// TierAware, when true, makes Authorize consult GET /v1/billing/tier and
	// gate on the effective balance (prepaid + included plan allotment such as
	// the free-tier daily credit) instead of the bare prepaid balance. This is
	// the same effectiveAvailable commerce computes in GetTier.
	TierAware bool

	// FailOpen inverts the default fail-closed posture: when commerce cannot be
	// reached, Authorize allows the request instead of denying it. Leave false
	// for paid products; set true only where availability outranks billing
	// (and accept the revenue leak). Mirrors the gateway, which is fail-closed.
	FailOpen bool

	// Test routes every call to commerce's TEST ledger (X-Hanzo-Test: true) so
	// balances and debits hit the sandbox books, not real money. Production
	// metering leaves this false. Used for end-to-end proofs and staging.
	Test bool

	// Timeout bounds each commerce HTTP call. Default 5s (the gateway's value).
	Timeout time.Duration

	// HTTPClient overrides the underlying HTTP client. When nil a client with
	// Timeout is created.
	HTTPClient HTTPDoer
}

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

type MiddlewareConfig struct {
	// Price computes the per-request cost in cents. Required — without it the
	// middleware would gate but never charge, which is not metering.
	Price PriceFunc

	// Provider labels the recorded usage (e.g. "search", "functions"). It is
	// stored on the commerce transaction so spend can be attributed per product.
	Provider string

	// Identify extracts the billing identity (IAM user + org) from a request.
	// Defaults to IdentityFromGatewayHeaders, which reads the gateway-minted
	// X-User-Id / X-Org-Id headers.
	Identify func(*http.Request) AuthInput

	// Skip lets a request bypass metering entirely (health checks, public
	// paths). Returning true means: no gate, no record. Optional.
	Skip func(*http.Request) bool

	// OnDenied renders the response when Authorize denies. Defaults to a JSON
	// 402 (insufficient balance) / 503 (balance unknown, fail-closed) — the
	// same status mapping the gateway uses.
	OnDenied func(w http.ResponseWriter, r *http.Request, err error)

	// OnRecordError is invoked (best-effort, async) if recording usage fails.
	// Optional — typically wired to the product's logger/metrics. The request
	// has already succeeded; recording failure must not affect the response.
	OnRecordError func(r *http.Request, u Usage, err error)
}

type PriceFunc func(r *http.Request, status int, in AuthInput) int64

type RecordResult struct {
	TransactionID string `json:"transactionId"`
	User          string `json:"user"`
	Amount        int64  `json:"amount"`
	Currency      string `json:"currency"`
	Type          string `json:"type"`
}

type ScopeRule struct {
	Project      string
	Service      string
	RateLimitRpm int
}

type Usage struct {
	User     string `json:"user"`            // the ACCOUNT half of the debit's address (see AuthInput.User) — a pooled org's slug, or the payer subject the gate authorized.
	Actor    string `json:"actor,omitempty"` // org/sub identity for the audit trail (commerce ignores unknown fields today; forward-compatible).
	Org      string `json:"-"`               // routed via X-Org-Id, not the body.
	Currency string `json:"currency,omitempty"`

	// Amount is the exact debit, typed. Not serialized: the co-resident finance
	// path reads it directly; the HTTP path derives the wire fields below from it.
	Amount money.Amount `json:"-"`

	// AmountCents is the debit in whole cents (legacy wire field). Set by older
	// callers and by Record when serializing a typed Amount for commerce. When
	// Amount is set, this is ignored on the co-resident path.
	AmountCents int64 `json:"amount"`
	// AmountMicros is the debit in micro-USD (1e6 = $1), sub-cent precision for the
	// HTTP path so a tiny per-call cost is not lost to cent rounding. Commerce
	// prefers it over AmountCents (usage.go: effMicros); when set, AmountCents may
	// be 0. Zero/absent → commerce falls back to AmountCents*10000. Ignored on the
	// co-resident path when Amount is set.
	AmountMicros int64 `json:"amountMicros,omitempty"`

	Model    string `json:"model,omitempty"`
	Provider string `json:"provider,omitempty"`
	// Project and Service attribute this debit to a scope so commerce records the
	// dimensions the per-scope spend cap sums over (issue #70). Empty = the
	// org-wide default scope.
	Project          string `json:"project,omitempty"`
	Service          string `json:"service,omitempty"`
	PromptTokens     int    `json:"promptTokens,omitempty"`
	CompletionTokens int    `json:"completionTokens,omitempty"`
	TotalTokens      int    `json:"totalTokens,omitempty"`
	RequestID        string `json:"requestId,omitempty"`
	Premium          bool   `json:"premium,omitempty"`
	Stream           bool   `json:"stream,omitempty"`
	Status           string `json:"status,omitempty"`
	ClientIP         string `json:"clientIp,omitempty"`
}

type Verdict struct {
	Allow      bool
	Reason     string // "", "insufficient_balance", "spend_cap"
	WarnPct    int
	CapCents   int64
	SpentCents int64
}