usage

type Adjustment struct {
	ID                 string    `json:"id"`
	PreviousID         string    `json:"previous_id,omitempty"`
	Original           Record    `json:"original"`
	RecordedAt         time.Time `json:"recorded_at"`
	Cost               Cost      `json:"cost"`
	Tokens             int64     `json:"tokens"`
	BillingDisposition string    `json:"billing_disposition"`
}

type AdjustmentReader interface {
	InspectAdjustment(ctx context.Context, original Record, id string) (Adjustment, error)
}

type AdjustmentWriter interface {
	Adjust(context.Context, Adjustment) error
}

type BillingAdjustment struct {
	OriginalTokensUnknown         bool      `json:"original_tokens_unknown,omitempty"`
	OriginalTokensEstimated       bool      `json:"original_tokens_estimated,omitempty"`
	ID                            string    `json:"id"`
	PreviousID                    string    `json:"previous_id,omitempty"`
	RecordedAt                    time.Time `json:"recorded_at"`
	OriginalCost                  *Cost     `json:"original_cost,omitempty"`
	OriginalCostUnavailableReason string    `json:"original_cost_unavailable_reason,omitempty"`
	OriginalTokens                Tokens    `json:"original_tokens"`
	OriginalBillingDisposition    string    `json:"original_billing_disposition,omitempty"`
}

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

type Extraction struct {
	ProcessedPages         int64     `json:"processed_pages,omitzero"`
	ProcessedPagesKnown    bool      `json:"processed_pages_known,omitzero"`
	TokensUnknown          bool      `json:"tokens_unknown,omitempty"`
	CacheReadTokensUnknown bool      `json:"cache_read_tokens_unknown,omitempty"`
	StartedAt              time.Time `json:"started_at,omitzero"`
	Offering               string    `json:"offering"`
	GenerationID           string    `json:"generation_id,omitempty"`
	Pages                  int64     `json:"pages"`
	BillingBasis           string    `json:"billing_basis,omitempty"`
	Tokens                 *Tokens   `json:"tokens,omitempty"`
	Cost                   *Cost     `json:"cost,omitempty"`
	CostUnavailableReason  string    `json:"cost_unavailable_reason,omitempty"`
}

type Media struct {
	// ImageSize retains the requested dimensions for image valuation.
	ImageSize       string `json:"image_size,omitempty"`
	ImagesEdited    bool   `json:"images_edited,omitzero"`
	GeneratedImages int64  `json:"generated_images,omitempty"`
	// GeneratedVideos counts completed outputs. It does not establish billing units.
	GeneratedVideos int64 `json:"generated_videos,omitempty"`
	// VideoOutputSeconds preserves provider duration, including an explicit zero.
	VideoOutputSeconds      int64 `json:"video_output_seconds,omitempty"`
	VideoOutputSecondsKnown bool  `json:"video_output_seconds_known,omitzero"`
}

type Options struct {
	// Retention bounds lifetime from the event timestamp for records and
	// from each window end for counters. Zero selects DefaultRetention.
	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
	// RequestID selects the one record a request left, so an audit record
	// or a log line reaches its usage row.
	RequestID string
	// GuardrailVerdict keeps only records a guardrail closed with this
	// verdict: `refuse` or `redact`. Empty places no filter.
	GuardrailVerdict string
	Since            time.Time
	Until            time.Time
	Limit            int
	// Cursor continues a previous page: the opaque NextCursor value.
	Cursor string
}

type Record struct {
	// BillingAdjustment identifies corrected billing and preserves the original values.
	BillingAdjustment *BillingAdjustment `json:"billing_adjustment,omitempty"`
	// BillingDisposition distinguishes administrator decisions from provider measurements.
	BillingDisposition string `json:"billing_disposition,omitempty"`
	// InputCharacters preserves the measured Unicode code-point count for speech.
	InputCharacters      int64 `json:"input_characters,omitempty"`
	InputCharactersKnown bool  `json:"input_characters_known,omitzero"`

	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"`
	// TeamID is the team the serving key is attributed to, or empty for a
	// teamless key. It is what a team-wide spend cap counts: a team meters
	// every key attributed to it, across every account the team reaches, so
	// neither the key ID nor the account ID can stand in for it.
	TeamID string `json:"team_id,omitempty"`
	// BatchID names the batch this request ran inside, or is empty for an
	// online request. Every line of a batch draws its own record, and this
	// field is what sums them back into one bill.
	BatchID        string    `json:"batch_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"`
	// SearchUnitsKnown preserves explicit zero separately from missing usage.
	SearchUnitsKnown bool `json:"search_units_known,omitzero"`
	// TokensEstimated marks counts the gateway synthesized with a
	// tokenizer because the provider reported none.
	TokensEstimated bool `json:"tokens_estimated,omitempty"`
	// TokensUnknown marks incomplete or invalid provider token evidence.
	TokensUnknown bool  `json:"tokens_unknown,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"`
	// CacheSimilarity is the cosine similarity a semantic cache hit served
	// under. It is zero for an exact hit and for a miss.
	CacheSimilarity float64 `json:"cache_similarity,omitempty"`
	// CacheSemantic reports that the hit came from the semantic layer, so
	// a reader separates a near-duplicate answer from an exact replay
	// without a similarity threshold of its own.
	CacheSemantic bool `json:"cache_semantic,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 reports document size independently of billing units.
	// A cache hit adds no recognized pages.
	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"`
	// Extractions retain each recognition measurement and its selected offering.
	Extractions []Extraction `json:"extractions,omitempty"`

	// GuardrailVerdict is the strongest guardrail verdict of the turn:
	// `allow`, `redact`, or `refuse`. It is empty on a turn no guardrail
	// inspected, which is what every record written before the guardrail
	// seam existed reads back as.
	GuardrailVerdict string `json:"guardrail_verdict,omitempty"`
	// GuardrailCheck names the check behind a refusal, so an operator can
	// see which policy stopped the turn. It is empty unless the verdict
	// is `refuse`.
	GuardrailCheck string `json:"guardrail_check,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 atomically persists one record and its aggregate changes.
	// An exact retry is idempotent during retention. Conflicting reuse refuses.
	// Preserve the event timestamp and all recorded values across retries.
	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 Sink interface {
	Receive(record Record)
	Close(ctx context.Context) error
	// Dropped counts the records this sink could not deliver since it
	// opened. The admin surface reports it beside the target kind.
	Dropped() int64
}

type SinkOptions struct {
	// FlushInterval is how often buffered records flush without waiting for
	// Close.
	FlushInterval time.Duration
	// MaxPending bounds the buffer. When a flush target stalls long enough to
	// fill it, the oldest records drop and OnDrop counts them.
	MaxPending int
	// OnDrop observes every dropped record count. Nil observes nothing.
	OnDrop func(count int)
}

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 includes known extraction charges even if the total is unknown.
	// It is a known subtotal, not proof that every provider charge settled.
	SpendNanoUSD int64
}