usage

type Cost struct {
	NanoUSD  int64  `json:"nano_usd"`
	Currency string `json:"currency"`
}

type Media struct {
	GeneratedImages int64 `json:"generated_images,omitempty"`
	// GeneratedVideos counts finished videos. A provider prices a video per
	// video, not per second and not per token, so this is the whole meter for
	// the operation rather than a share of another one.
	GeneratedVideos int64 `json:"generated_videos,omitempty"`
}

type Options struct {
	// Retention bounds record and counter lifetime; DefaultRetention
	// when zero.
	Retention time.Duration
}

type Page struct {
	Records []Record
	// NextCursor continues the listing; empty when the page is the last.
	NextCursor string
}

type Query struct {
	KeyID string
	// AccountID selects one account's records across every key it holds.
	// Records are keyed by gateway API key, so a query that names only an
	// account scans the record namespace and filters. That cost belongs to
	// reporting: budget enforcement reads the aggregate counters instead.
	AccountID string
	Model     string
	Provider  string
	Status    string
	Since     time.Time
	Until     time.Time
	Limit     int
	// Cursor continues a previous page: the opaque NextCursor value.
	Cursor string
}

type Record struct {
	RequestID string `json:"request_id"`
	KeyID     string `json:"key_id"`
	// AccountID is the account the key belongs to. It is what an account-wide
	// spend cap counts, and a key ID cannot stand in for it because an account
	// holds many keys. It is optional so that a record written before account
	// attribution stays readable; such a record counts toward no account.
	AccountID      string    `json:"account_id,omitempty"`
	Timestamp      time.Time `json:"timestamp"`
	Protocol       string    `json:"protocol,omitempty"`
	Operation      string    `json:"operation"`
	ModelRequested string    `json:"model_requested,omitempty"`
	ModelUsed      string    `json:"model_used,omitempty"`
	Provider       string    `json:"provider,omitempty"`
	// CredentialSource names which credential plane paid for the request:
	// `environment`, `shared`, `byok`, or `anonymous` for a provider that
	// accepted the call without one. It is what lets an operator see an
	// account drawing on the deployment's credential rather than its own. It
	// is empty on a record written before a route was chosen, and on one
	// written before the gateway recorded the plane.
	CredentialSource string `json:"credential_source,omitempty"`
	Streaming        bool   `json:"streaming,omitempty"`
	Status           string `json:"status"`
	StatusCode       int    `json:"status_code,omitempty"`
	ErrorClass       string `json:"error_class,omitempty"`
	Tokens           Tokens `json:"tokens"`
	// Media is nil on a text turn, which is what every record written before
	// media accounting existed reads back as.
	Media *Media `json:"media,omitempty"`
	// SearchUnits counts what a rerank provider that bills by search unit
	// billed. It sits beside Media rather than inside it because reranking
	// produces no media, and it sits outside Tokens because no token total
	// converts into it: a Cohere turn reports a search unit and no tokens at
	// all, and a record that read tokens alone would meter it as free.
	SearchUnits int64 `json:"search_units,omitempty"`
	// TokensEstimated marks counts the gateway synthesized with a
	// tokenizer because the provider reported none.
	TokensEstimated bool  `json:"tokens_estimated,omitempty"`
	LatencyMS       int64 `json:"latency_ms"`
	RoutingMS       int64 `json:"routing_ms,omitempty"`
	// OverheadMS is the gateway-added latency: total handling time
	// minus upstream provider waits.
	OverheadMS int64 `json:"overhead_ms,omitempty"`
	// TTFTMS is the time from request start to the first stream event.
	// Only streamed requests carry it.
	TTFTMS      int64  `json:"ttft_ms,omitempty"`
	Attempts    int    `json:"attempts,omitempty"`
	CacheStatus string `json:"cache_status,omitempty"`

	// ParserEngine names which engine read the documents this turn attached:
	// `native` for the in-process reader, `recognition` for a catalogued model.
	// It is empty on a turn that attached none.
	ParserEngine string `json:"parser_engine,omitempty"`
	// DocumentPages is how many pages those attachments held, whether this turn
	// read them or the cache answered for them.
	DocumentPages int64 `json:"document_pages,omitempty"`
	// RecognizedPages is how many of those pages this turn sent to a
	// recognition model. It is what ExtractionCost is charged for, and it is
	// zero on a cached read: the pages were recognized once, on an earlier turn
	// that paid for them.
	RecognizedPages int64 `json:"recognized_pages,omitempty"`
	// NativePages is how many pages this turn read in process. They cost
	// nothing: no provider saw them.
	NativePages int64 `json:"native_pages,omitempty"`
	// ExtractionCached reports that every attachment came back from the
	// extraction cache. A cached read and a native read both record no cost,
	// and only this field separates a page an earlier turn already paid for
	// from a page no provider ever charged for.
	ExtractionCached bool `json:"extraction_cached,omitempty"`
	// ExtractionMillis is how long the document reads took. A recognition read
	// is a provider call inside a provider call, so it is latency an operator
	// cannot find anywhere else in this record.
	ExtractionMillis int64 `json:"extraction_millis,omitempty"`
	// ExtractionCost is the recognized share of Cost below, reported on its own
	// so an operator can see what reading a document cost apart from what
	// answering about it cost. It is nil when the turn recognized nothing.
	ExtractionCost *Cost `json:"extraction_cost,omitempty"`

	// Cost is nil when no cost could be computed; CostUnavailableReason
	// then names why. It covers the whole request, the document reads
	// included.
	Cost                  *Cost  `json:"cost,omitempty"`
	CostUnavailableReason string `json:"cost_unavailable_reason,omitempty"`
}

type Repository interface {
	// Put persists one record and advances the aggregate counters.
	Put(context.Context, Record) error
	// List returns records newest-first.
	List(context.Context, Query) (Page, error)
	// Totals reads the aggregate counters for one scope in the window
	// containing at.
	Totals(ctx context.Context, scope Scope, interval string, at time.Time) (Totals, error)
}

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

type Tokens struct {
	Input      int64 `json:"input"`
	Output     int64 `json:"output"`
	Total      int64 `json:"total"`
	Reasoning  int64 `json:"reasoning,omitempty"`
	CacheRead  int64 `json:"cache_read,omitempty"`
	CacheWrite int64 `json:"cache_write,omitempty"`
	// AudioInput and AudioOutput are the audio shares of Input and Output,
	// not additions to them. A provider meters audio at its own rate, so a
	// cost reclassifies these out of the plain rates rather than adding them.
	AudioInput  int64 `json:"audio_input,omitempty"`
	AudioOutput int64 `json:"audio_output,omitempty"`
}

type Totals struct {
	Requests     int64
	Tokens       int64
	SpendNanoUSD int64
}