analytics

type Attribution struct {
	Org     string
	Project string
}

type Breakdown struct {
	// Available is false when the product-event table could not be read.
	Available bool `json:"available"`
	// Reason says why the lens is unavailable. Omitted when it is available.
	Reason string `json:"reason,omitempty"`
	// Items is the ranked buckets, most pageviews first. Empty rather than absent.
	Items []BreakdownRow `json:"items"`
	// Source is the warehouse table the lens read.
	Source string `json:"source"`
}

type BreakdownRow struct {
	// Key is the bucket: a requested path, a referrer domain ("(direct)" for none or
	// a same-origin one), or a utm_source ("(none)" when absent).
	Key string `json:"key"`
	// Pageviews is how many $pageview events fell in this bucket.
	Pageviews int64 `json:"pageviews"`
	// Visitors is how many distinct people they came from.
	Visitors int64 `json:"visitors"`
	// Pct is this bucket's share of ALL in-window pageviews, 0..100, one decimal —
	// not of the returned rows, so a top-N shows the long tail honestly.
	Pct float64 `json:"pct"`
}

type CampaignEvents struct {
	Available   bool    `json:"available"`
	Impressions int64   `json:"impressions"`
	Clicks      int64   `json:"clicks"`
	Conversions int64   `json:"conversions"`
	Revenue     float64 `json:"revenue"`
	Visitors    int64   `json:"visitors"`
	Source      string  `json:"source"`
}

type CaptureBatch struct {
	Batch  []CaptureEvent `json:"batch"`
	Events []CaptureEvent `json:"events"`
}

type CaptureEvent struct {
	MessageID   string `json:"messageId"`  // client idempotency id; server mints one if empty
	Type        string `json:"type"`       // pageview | event | identify | group
	Event       string `json:"event"`      // event name (type=event); pageview→$pageview
	Timestamp   string `json:"timestamp"`  // RFC3339; clamped to server-now on skew/absent
	DistinctID  string `json:"distinctId"` // resolved person/visitor id
	AnonymousID string `json:"anonymousId"`
	PersonID    string `json:"personId"`
	SessionID   string `json:"sessionId"`
	Product     string `json:"product"` // emitting surface: console|chat|app|site|admin
	URL         string `json:"url"`
	Path        string `json:"path"`
	Referrer    string `json:"referrer"`
	UTM         UTM    `json:"utm"`
	RefCode     string `json:"refCode"`
	Channel     string `json:"channel"`
	GroupID     string `json:"groupId"`
	// GroupType names WHICH grouping the id belongs to (organization, workspace,
	// account). It is a map key rather than a column so the second grouping is a data
	// change: the plane stores `groups[type] = id`, never group0..group4, because a
	// fifth positional slot is a sixth one waiting to become a version suffix.
	// Absent means the only grouping anything sends today, `organization`.
	GroupType  string     `json:"groupType"`
	SignupWeek string     `json:"signupWeek"`
	ProductID  string     `json:"productId"`
	Quantity   uint32     `json:"quantity"`
	Revenue    float64    `json:"revenue"`
	Currency   string     `json:"currency"`
	Error      *Exception `json:"error"` // set on type:'error' events (folded into properties.$exception)

	// THE OTEL SIGNALS. One envelope carries all four — event, log, span, metric —
	// because they differ in their BODY, not in who sent them or when. Splitting the
	// envelope per signal duplicates org, time, session and identity four ways and
	// lets them drift; the fact plane (fact.go) reads one shape and writes one row.
	//
	// Each is a pointer so absent is distinct from empty: a pageview carries no Span,
	// and a zero-valued one would be a span of duration 0 rather than no span at all.
	Log    *LogBody    `json:"log"`
	Span   *SpanBody   `json:"span"`
	Metric *MetricBody `json:"metric"`
	Clip   *ClipBody   `json:"clip"`

	// Kind narrows Type when the surface knows more than the wire word does — a
	// span's client/server role, a page's navigation kind. Empty means the route's
	// own default, which is what every existing client sends.
	Kind string `json:"kind"`

	// SITE is the deployed property a signal came from, and it is carried on EVERY
	// event, not only on a failure.
	//
	// It lived on the exception alone, so sentry.hanzo.ai could group faults by site
	// while analytics.hanzo.ai — reading the event stream — had no site column at
	// all, and "all sites" was a question the data could not answer. One property
	// per row is what makes the two surfaces read the same world.
	Site string `json:"site"`

	// Level, Release, Environment and Service qualify a signal the same way for
	// every kind: which severity, which build, which deployment, which service. They
	// are not error-only either, for the same reason Site is not.
	Level       string `json:"level"`
	Release     string `json:"release"`
	Environment string `json:"environment"`
	Service     string `json:"service"`

	// TraceID and SpanID correlate a signal to a trace whatever its body is, so a log
	// and the span it was emitted inside join without either owning the other.
	TraceID string `json:"traceId"`
	SpanID  string `json:"spanId"`

	// Resource is the fingerprint of the emitting resource — the host, pod and
	// service attributes a collector already deduplicates into its own dimension
	// table. It joins event.log_resource / event.span_resource on `fingerprint`.
	// ONE name for it: the plane previously carried this fact as `resource UInt64`
	// AND `resource_fingerprint String` on the same row, one of them always zero.
	Resource string `json:"resource"`

	Properties map[string]any `json:"properties"`
	Library    string         `json:"library"`
	LibraryVer string         `json:"libraryVersion"`
}

type CaptureResult struct {
	Accepted int `json:"accepted"`
	Dropped  int `json:"dropped"`
}

type ClipBody struct {
	// Object is the blob's address in object storage.
	Object string `json:"object"`
	// Bytes is its size, so a session list can show weight without opening it.
	Bytes uint64 `json:"bytes"`
	// Duration is the wall time the clip covers, in nanoseconds — the same column a
	// span's elapsed time uses, because it is the same fact.
	Duration uint64 `json:"duration"`
}

type CommerceOverview struct {
	// Available is false when the product-event table could not be read — the lens is
	// reported missing rather than as zeros that look like no sales.
	Available bool `json:"available"`
	// Reason says why the lens is unavailable. Omitted when it is available.
	Reason string `json:"reason,omitempty"`
	// Orders is how many order_completed events landed in the window.
	Orders int64 `json:"orders"`
	// Revenue is the total those orders carried, in the events' own currency unit.
	Revenue float64 `json:"revenue"`
	// AOV is average order value — Revenue/Orders, rounded to two places. Zero when
	// there were no orders.
	AOV float64 `json:"aov"`
	// Source is the warehouse table the lens read.
	Source string `json:"source"`
}

type Event struct {
	Event      string         `json:"event"`      // event name (required; empty ⇒ dropped as unroutable)
	Type       string         `json:"type"`       // canonical kind: pageview | error | identify | group | event (default)
	DistinctID string         `json:"distinctId"` // the person/visitor id the caller owns
	Time       string         `json:"time"`       // optional RFC3339; clamped to server-now on skew/absent
	Properties map[string]any `json:"properties"` // everything non-core
}

type EventEnvelope struct {
	Org         string         `json:"org"`
	ID          string         `json:"id"`
	Name        string         `json:"name"`
	DistinctID  string         `json:"distinct_id,omitempty"`
	AnonymousID string         `json:"anonymous_id,omitempty"`
	Time        time.Time      `json:"time"`
	URL         string         `json:"url,omitempty"`
	Path        string         `json:"path,omitempty"`
	Referrer    string         `json:"referrer,omitempty"`
	Revenue     float64        `json:"revenue,omitempty"`
	Currency    string         `json:"currency,omitempty"`
	ProductID   string         `json:"product_id,omitempty"`
	Quantity    uint32         `json:"quantity,omitempty"`
	Properties  map[string]any `json:"properties,omitempty"`
}

type Exception struct {
	Type    string `json:"type,omitempty"`
	Message string `json:"message"`
	Stack   string `json:"stack,omitempty"`
	Handled *bool  `json:"handled,omitempty"`

	// Frames is the STRUCTURED stack, when the SDK sent one. Stack stays as the raw
	// text a client without a parser sends, so neither is derived from the other and
	// a client may send either or both.
	//
	// It is what lets a fault be grouped and rendered by function, file and line
	// rather than by a string compare over a whole trace — the raw text cannot
	// answer "is this frame ours" (framesOf marks own) and cannot be scrubbed field
	// by field.
	Frames []Frame `json:"frames,omitempty"`
}

type Frame struct {
	// Function is the called function's name.
	Function string `json:"function,omitempty"`
	// File is the source file. It is treated as a URL and scrubbed, because a
	// bundler emits one with a query string that can carry a token.
	File string `json:"file,omitempty"`
	// Line is the 1-based line number.
	Line uint32 `json:"line,omitempty"`
	// Column is the 1-based column number.
	Column uint32 `json:"column,omitempty"`
}

type KeyResolver interface {
	Resolve(ctx context.Context, key string) (Attribution, bool, error)
}

type LLMOverview struct {
	// Available is true whenever the ledger answered — including with no usage in the
	// window, which is honest zeros rather than a missing lens.
	Available bool `json:"available"`
	// Requests is how many LLM calls the org made in the window.
	Requests int64 `json:"requests"`
	// Tokens is prompt plus completion tokens over those calls.
	Tokens int64 `json:"tokens"`
	// PromptTokens is the input half of Tokens.
	PromptTokens int64 `json:"promptTokens"`
	// CompletionTokens is the output half of Tokens.
	CompletionTokens int64 `json:"completionTokens"`
	// SpendCents is what those calls cost, in cents.
	SpendCents int64 `json:"spendCents"`
	// Models is how many distinct models the org called.
	Models int64 `json:"models"`
	// Providers is how many distinct providers served them.
	Providers int64 `json:"providers"`
	// Errors is how many of Requests failed.
	Errors int64 `json:"errors"`
	// ErrorRate is Errors/Requests, 0..1, rounded to three places. Zero when there
	// were no requests.
	ErrorRate float64 `json:"errorRate"`
	// Source is the warehouse table the lens read.
	Source string `json:"source"`
}

type LogBody struct {
	// Severity is the OTel severity text, lowercased on the way into a fact.
	Severity string `json:"severity"`
	// Number is the OTel severity NUMBER (1..24), which orders severities without
	// parsing their text and survives a client that spells one differently.
	Number uint8 `json:"number"`
	// Body is the log message. It is scrubbed where it enters a fact, not here, so
	// there is one scrub on one path.
	Body string `json:"body"`
}

type MetricBody struct {
	// Name is what was measured, and it is also the fact's event name for a metric.
	Name string `json:"name"`
	// Value is the sample.
	Value float64 `json:"value"`
	// Labels are the dimensions the sample is sliced by.
	Labels map[string]any `json:"labels"`
}

type ModelRow struct {
	// Model is the model id, e.g. zen5-coder.
	Model string `json:"model"`
	// Provider is who served it.
	Provider string `json:"provider"`
	// Requests is how many calls went to this model.
	Requests int64 `json:"requests"`
	// Tokens is prompt plus completion tokens over those calls.
	Tokens int64 `json:"tokens"`
	// SpendCents is what they cost, in cents.
	SpendCents int64 `json:"spendCents"`
	// Pct is this model's share of the window's returned spend, 0..100, one decimal.
	Pct float64 `json:"pct"`
}

type Overview struct {
	// Range is the window that was actually applied: 24h, 7d, 30d or custom.
	Range string `json:"range"`
	// Start is the window's inclusive lower bound, RFC3339 UTC.
	Start string `json:"start"`
	// End is the window's exclusive upper bound, RFC3339 UTC.
	End string `json:"end"`
	// Interval is the bucket width the window implies: hour or day.
	Interval types.Interval `json:"interval"`
	// Scope names the tenant these numbers belong to.
	Scope Scope `json:"scope"`
	// LLM is the LLM usage lens — real per-org data.
	LLM LLMOverview `json:"llm"`
	// Web is the web-traffic lens over product events.
	Web WebOverview `json:"web"`
	// Commerce is the orders/revenue lens over product events.
	Commerce CommerceOverview `json:"commerce"`
}

type ProductRow struct {
	// ProductID is the product the order events named.
	ProductID string `json:"productId"`
	// Orders is how many order_completed events carried it.
	Orders int64 `json:"orders"`
	// Revenue is the total they carried, in the events' own currency unit.
	Revenue float64 `json:"revenue"`
	// Units is the summed quantity sold.
	Units int64 `json:"units"`
}

type Scope struct {
	// Org is the IAM org slug the rows were read under: the validated principal's,
	// resolved server-side.
	Org string `json:"org"`
}

type SinkEvent struct {
	MessageID   string
	Name        string
	DistinctID  string
	AnonymousID string
	Time        time.Time
	URL         string
	Path        string
	Referrer    string
	Revenue     float64
	Currency    string
	ProductID   string
	Quantity    uint32
	Properties  map[string]any
}

type SpanBody struct {
	// ID is this span's own id, which a client emitting a span knows precisely.
	ID string `json:"id"`
	// Trace is the trace this span belongs to.
	Trace string `json:"trace"`
	// Parent is the enclosing span's id, empty for a root span.
	Parent string `json:"parent"`
	// Kind is the span's role — client, server, producer, consumer, internal.
	Kind string `json:"kind"`
	// Status is how the span ended: ok, error, or unset.
	Status string `json:"status"`
	// Duration is the elapsed time in nanoseconds. Unsigned because a span cannot
	// take negative time.
	Duration uint64 `json:"duration"`
}

type SubjectOutcome struct {
	Subject   string
	Exposed   bool
	Converted bool
}

type Timeseries struct {
	// Range is the window that was actually applied: 24h, 7d, 30d or custom.
	Range string `json:"range"`
	// Start is the window's inclusive lower bound, RFC3339 UTC.
	Start string `json:"start"`
	// End is the window's exclusive upper bound, RFC3339 UTC.
	End string `json:"end"`
	// Interval is the bucket width: hour or day.
	Interval types.Interval `json:"interval"`
	// Scope names the tenant these numbers belong to.
	Scope Scope `json:"scope"`
	// Series is one point per bucket, oldest first, with empty buckets zero-filled.
	Series []UsagePoint `json:"series"`
	// Source is the warehouse table the series read.
	Source string `json:"source"`
}

type Top struct {
	// Range is the window that was actually applied: 24h, 7d, 30d or custom.
	Range string `json:"range"`
	// Start is the window's inclusive lower bound, RFC3339 UTC.
	Start string `json:"start"`
	// End is the window's exclusive upper bound, RFC3339 UTC.
	End string `json:"end"`
	// Scope names the tenant these rankings belong to.
	Scope Scope `json:"scope"`
	// Models ranks the window's LLM models by spend — real per-org data.
	Models TopModels `json:"models"`
	// Products ranks the window's products by revenue.
	Products TopProducts `json:"products"`
	// Pages ranks the paths visitors requested, by pageviews.
	Pages Breakdown `json:"topPages"`
	// Referrers ranks the external domains visitors arrived from, by pageviews.
	Referrers Breakdown `json:"topReferrers"`
	// Sources ranks the utm_source campaigns visitors arrived on, by pageviews.
	Sources Breakdown `json:"topSources"`
}

type TopModels struct {
	// Available is true whenever the ledger answered, including with no rows.
	Available bool `json:"available"`
	// Items is the ranked models, highest spend first.
	Items []ModelRow `json:"items"`
	// Source is the warehouse table the lens read.
	Source string `json:"source"`
}

type TopProducts struct {
	// Available is false when the product-event table could not be read.
	Available bool `json:"available"`
	// Reason says why the lens is unavailable. Omitted when it is available.
	Reason string `json:"reason,omitempty"`
	// Items is the ranked products, highest revenue first. Empty rather than absent.
	Items []ProductRow `json:"items"`
	// Source is the warehouse table the lens read.
	Source string `json:"source"`
}

type UTM struct {
	Source   string `json:"source"`
	Medium   string `json:"medium"`
	Campaign string `json:"campaign"`
	Term     string `json:"term"`
	Content  string `json:"content"`
}

type UsagePoint struct {
	// T is the bucket's start, RFC3339 UTC, aligned to the interval.
	T string `json:"t"`
	// Requests is how many LLM calls fell in this bucket.
	Requests int64 `json:"requests"`
	// Tokens is prompt plus completion tokens over those calls.
	Tokens int64 `json:"tokens"`
	// SpendCents is what they cost, in cents.
	SpendCents int64 `json:"spendCents"`
}

type WebOverview struct {
	// Available is false when the product-event table could not be read — the lens is
	// reported missing rather than as zeros that look like real traffic.
	Available bool `json:"available"`
	// Reason says why the lens is unavailable. Omitted when it is available.
	Reason string `json:"reason,omitempty"`
	// Pageviews is how many $pageview events landed in the window.
	Pageviews int64 `json:"pageviews"`
	// Visitors is how many distinct people those pageviews came from.
	Visitors int64 `json:"visitors"`
	// Sessions is how many distinct visits they span.
	Sessions int64 `json:"sessions"`
	// Source is the warehouse table the lens read.
	Source string `json:"source"`
}