messagelifecycle

type AccountMetrics struct {
	// Totals covers the whole account and is always complete — it is computed
	// across every agent, never from the possibly-truncated Agents slice.
	Totals AgentMetrics

	// Agents is the optional per-agent breakdown, busiest first. Empty when
	// the caller did not ask for it.
	Agents []AgentMetricsGroup

	// AgentsTruncated reports that the account owns more agents with traffic
	// than Agents contains. Totals remain accurate; only the breakdown is cut.
	AgentsTruncated bool

	// Days is the optional per-day breakdown, oldest first. Empty when the
	// caller did not ask for it.
	//
	// It is produced inside the SAME transaction as Totals, not by a separate
	// read. The API promises that bucket counters sum to the window totals, and
	// two independent reads cannot honour that: a write landing between them
	// makes the chart contradict the tiles it sits under, which is precisely
	// the failure a documented sum-to-totals contract must not have.
	Days []DayBucket
}

type AgentMetrics struct {
	// Counts holds one entry per reason code observed in the window, ordered
	// by reason code. Codes with no observations are absent rather than zero.
	Counts []ReasonCodeCount

	// MessagesInWindow and MessagesWithLifecycle expose ledger coverage.
	//
	// This aggregate reads only PERSISTED transitions. The per-message read
	// path (ListForMessage) additionally reconstructs observations from
	// durable message state, so a message written before the ledger shipped —
	// or by a path that never appended — shows a lifecycle there while
	// contributing nothing here. Reporting both counts turns that gap into a
	// number the caller can see instead of a silent undercount that reads as
	// a delivery problem.
	MessagesInWindow      int64
	MessagesWithLifecycle int64

	// ReconstructedObservations counts ledger rows in the window that were
	// derived from durable state rather than observed at the boundary. They
	// are included in Counts; this field makes the inferred share visible.
	ReconstructedObservations int64
}

type AgentMetricsGroup struct {
	AgentEmail string
	Metrics    AgentMetrics
}

type AppendInput struct {
	MessageID      string
	DedupeKey      string
	Direction      string
	Recipient      string
	ReasonCode     ReasonCode
	Evidence       map[string]any
	CorrelationIDs map[string]string
	OccurredAt     time.Time
}

type DayBucket struct {
	// Day is midnight UTC starting the bucket. Buckets are contiguous and
	// gap-filled by the caller, because a day with no traffic must render as
	// a zero on a chart rather than vanish and distort the line's slope.
	Day    time.Time
	Counts []ReasonCodeCount
}

type Definition struct {
	Stage     Stage
	Outcome   Outcome
	Retryable bool
}

type EventSnapshot struct {
	ID        string
	Type      string
	Envelope  json.RawMessage
	CreatedAt time.Time
}

type MessageLifecycleTransition struct {
	ID                 string            `json:"id"`
	MessageID          string            `json:"message_id"`
	DedupeKey          string            `json:"-"`
	SourceTransitionID string            `json:"-"`
	Direction          string            `json:"direction" enum:"inbound,outbound"`
	Recipient          string            `json:"recipient,omitempty" nullable:"true"`
	Stage              Stage             `json:"stage" enum:"accepted,authentication,review,suppression,queued,submission,delivery,complaint"`
	Outcome            Outcome           `` /* 145-byte string literal not displayed */
	ReasonCode         ReasonCode        `` /* 842-byte string literal not displayed */
	Retryable          bool              `json:"retryable"`
	Evidence           map[string]any    `json:"evidence"`
	CorrelationIDs     map[string]string `json:"correlation_ids"`
	OccurredAt         time.Time         `json:"occurred_at"`
	Reconstructed      bool              `json:"reconstructed"`
}

type Outcome string

type ReasonCode string

type ReasonCodeCount struct {
	ReasonCode   ReasonCode
	Stage        Stage
	Outcome      Outcome
	Retryable    bool
	Observations int64
	Messages     int64
}

type RecipientSnapshot struct {
	ID        string
	Address   string
	Status    string
	Detail    string
	UpdatedAt time.Time
}

type Snapshot struct {
	MessageID             string
	AgentID               string
	UserID                string
	Direction             string
	Method                string
	CreatedAt             time.Time
	Authentication        json.RawMessage
	Status                string
	ApprovalExpiresAt     *time.Time
	ReviewedAt            *time.Time
	SendJobID             *int64
	JobCreatedAt          *time.Time
	ProviderAcceptedAt    *time.Time
	ProviderMessageID     string
	EmailMessageID        string
	DeliveryStatus        string
	DeliveryFailureSource string
	Recipients            []RecipientSnapshot
	Suppressions          []SuppressionSnapshot
	Events                []EventSnapshot
}

type Stage string

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

type SuppressionSnapshot struct {
	ID              string
	Address         string
	Source          string
	SourceMessageID string
	CreatedAt       time.Time
}