overview

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package overview builds the workspace Overview (spec 7.1): sender health, the next scheduled campaign, provider cards, subscriber growth and tiers, and recent campaigns.

Each card has its own operation so one failing source never blanks the page (OverviewStates board), and the numbers come from the domains that own them so the Overview always agrees with the screens behind it.

Index

Constants

View Source
const RecentLimit = 4

RecentLimit is how many campaigns "Recent campaigns" shows.

Variables

This section is empty.

Functions

func Register

func Register(h huma.API, s *Service)

Register adds the Overview operations: one per card, each with the permission of the data it shows, so a card can fail or be hidden alone.

Types

type Audience

type Audience interface {
	Audience(ctx context.Context, ws *store.Workspace, days int) (OverviewAudience, error)
}

Audience supplies subscriber growth and engagement tiers (the audience domain's contacts, lists, tiers and sunset policy).

type AudienceCards

type AudienceCards struct {
	Service *audience.Service
	Q       *store.Queries
	Now     func() time.Time
}

AudienceCards builds "Subscriber growth" and "Engagement tiers" on the audience domain: the counts of the Audience header (contacts, tiers, lists), each list's joins and departures as List health counts them, and the sunset policy.

func (AudienceCards) Audience

func (a AudienceCards) Audience(ctx context.Context, ws *store.Workspace, days int) (OverviewAudience, error)

Audience returns the subscribers (list memberships) with their net change over the period and a point a day, the unique contacts, each list's size and change, the engagement tiers and the sunset policy.

type OverviewAudience

type OverviewAudience struct {
	// Total is the unique contacts (the Audience header's count).
	Total int64 `json:"total"`
	// Subscribers is the lists' subscribed members added up.
	Subscribers int64 `json:"subscribers"`
	Days        int   `json:"days"`
	// Net is the subscribers' change over Days (the lists' joins minus
	// departures); NetPercent is relative to the start.
	Net        int64                   `json:"net"`
	NetPercent *float64                `json:"netPercent,omitempty"`
	Series     []OverviewAudiencePoint `json:"series"`
	Lists      []OverviewListGrowth    `json:"lists"`
	Tiers      []OverviewTier          `json:"tiers"`
	// Policy is the sunset policy in one sentence.
	Policy        string `json:"policy"`
	PolicyEnabled bool   `json:"policyEnabled"`
}

OverviewAudience is "Subscriber growth" and "Engagement tiers".

type OverviewAudiencePoint

type OverviewAudiencePoint struct {
	Day         string `json:"day" format:"date"`
	Subscribers int64  `json:"subscribers"`
}

OverviewAudiencePoint is the subscribers on a day of the period (at the time of day the period started; the last point is now).

type OverviewHealthAction

type OverviewHealthAction struct {
	Label string `json:"label" doc:"request delisting"`
	// Kind says where it goes: request delisting of Asset, Deliverability,
	// Sending providers, the warm-up plan or Settings › Integrations.
	Kind  string `json:"kind" enum:"delisting,deliverability,providers,warmup,integrations"`
	Asset string `json:"asset,omitempty"`
}

OverviewHealthAction is the link at the end of a reason.

type OverviewHealthReason

type OverviewHealthReason struct {
	Key    string                `json:"key" enum:"blocklist_domain,auth,rates,blocklist_ip,warmup,provider_status,checks"`
	Tone   string                `json:"tone" enum:"ok,warn,bad"`
	Text   string                `json:"text"`
	Action *OverviewHealthAction `json:"action,omitempty"`
}

OverviewHealthReason is one line under the score.

type OverviewListGrowth

type OverviewListGrowth struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Contacts int64  `json:"contacts"`
	Net      int64  `json:"net"`
}

OverviewListGrowth is one list's subscribers and their net change over the period (joins minus departures, as on List health).

type OverviewNextCampaign

type OverviewNextCampaign struct {
	Campaign *OverviewScheduledCampaign `json:"campaign,omitempty"`
	// Drafts is the draft count, for the card when nothing is scheduled.
	Drafts int64 `json:"drafts"`
	// Issue is a recurring digest's next issue; the card shows it when it
	// goes out before the next scheduled campaign.
	Issue *OverviewNextIssue `json:"issue,omitempty"`
}

OverviewNextCampaign is "Next scheduled campaign".

type OverviewNextIssue

type OverviewNextIssue struct {
	DigestID   string    `json:"digestId"`
	DigestName string    `json:"digestName"`
	Number     int       `json:"number"`
	SendAt     time.Time `json:"sendAt"`
	Timezone   string    `json:"timezone"`
	Posts      int       `json:"posts"`
	Status     string    `json:"status" enum:"collecting,preparing,prepared,waiting,held,draft"`
	// NeedsApproval: the approval rules match the issue.
	NeedsApproval bool `json:"needsApproval"`
}

OverviewNextIssue is a recurring digest's next issue: "Engineering blog roundup #3 · Fri 17 Oct, 08:00 · 2 posts so far · needs approval".

type OverviewProviderCard

type OverviewProviderCard struct {
	Card manage.ProviderCard `json:"card"`
	// DisplayName: "Postal (self-hosted)".
	DisplayName string `json:"displayName"`
	// Detail: "us-east-1 · Broadcasts, Automations".
	Detail string `json:"detail"`
	// Refresh is set while account health can't be refreshed.
	Refresh *OverviewRefreshFailure `json:"refresh,omitempty"`
	// StatusLabel and StatusURL point to the provider's public status page.
	StatusLabel string `json:"statusLabel,omitempty"`
	StatusURL   string `json:"statusUrl,omitempty"`
}

OverviewProviderCard is one sending provider on the Overview: the providers screen's card (same numbers) and how the Overview names it.

type OverviewProviders

type OverviewProviders struct {
	// Connected is 0 on the first run: the Overview leads into connecting one.
	Connected  int                    `json:"connected"`
	MonthStart time.Time              `json:"monthStart"`
	Providers  []OverviewProviderCard `json:"providers"`
}

OverviewProviders is "Sending providers".

type OverviewReadiness

type OverviewReadiness struct {
	Verdict string                   `json:"verdict" enum:"ready,warnings,blocked"`
	Issues  []OverviewReadinessIssue `json:"issues"`
	RanAt   time.Time                `json:"ranAt"`
}

OverviewReadiness is the campaign's latest Send Readiness verdict.

type OverviewReadinessIssue

type OverviewReadinessIssue struct {
	Status string `json:"status" enum:"warn,block"`
	Title  string `json:"title"`
}

OverviewReadinessIssue is a warning or block of the latest readiness run.

type OverviewRecentCampaigns

type OverviewRecentCampaigns struct {
	Items []campaigns.CampaignListItem `json:"items"`
}

OverviewRecentCampaigns is "Recent campaigns": the campaigns list's rows.

type OverviewRefreshFailure

type OverviewRefreshFailure struct {
	Op      string `json:"op" doc:"GetAccount"`
	Status  int    `json:"status,omitempty"`
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
	// Attempts are the failed calls since the last success, oldest first.
	Attempts      []time.Time `json:"attempts"`
	LastSuccessAt *time.Time  `json:"lastSuccessAt,omitempty"`
	StatusLabel   string      `json:"statusLabel,omitempty"`
	StatusURL     string      `json:"statusUrl,omitempty"`
}

OverviewRefreshFailure says a provider's account health couldn't be refreshed while it still sends: the card shows the last good numbers.

type OverviewRouteShare

type OverviewRouteShare struct {
	Short   string  `json:"short"`
	Adapter string  `json:"adapter"`
	Color   string  `json:"color" enum:"ses,postal,postmark,other"`
	Percent float64 `json:"percent"`
	Planned int64   `json:"planned"`
}

OverviewRouteShare is a sending provider's share of the planned send.

type OverviewScheduledCampaign

type OverviewScheduledCampaign struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	ScheduledAt time.Time `json:"scheduledAt"`
	Timezone    string    `json:"timezone"`
	Recipients  int64     `json:"recipients"`
	// Readiness is nil until Send Readiness has run.
	Readiness *OverviewReadiness   `json:"readiness,omitempty"`
	Routes    []OverviewRouteShare `json:"routes"`
	// Cost is the estimate in dollars from each provider's price.
	Cost float64 `json:"cost"`
	// DurationMinutes estimates the send from each provider's rate limit
	// (the warm-up ramp for a warming provider); nil when a rate is unknown.
	DurationMinutes *float64 `json:"durationMinutes,omitempty"`
}

OverviewScheduledCampaign is the next campaign due to go out.

type OverviewSenderHealth

type OverviewSenderHealth struct {
	// State is pending until a sending domain is set up (first run).
	State string `json:"state" enum:"ready,pending"`
	Score int    `json:"score"`
	Label string `json:"label" enum:"Good,Fair,Poor,"`
	Tone  string `json:"tone" enum:"ok,warn,bad,neutral"`
	// Domain is the main sending domain ("news.acme.io").
	Domain    string                 `json:"domain"`
	Sources   int                    `json:"sources" doc:"Blocklists checked"`
	Via       string                 `json:"via" enum:"hostrepute,builtin,none"`
	CheckedAt *time.Time             `json:"checkedAt,omitempty"`
	Reasons   []OverviewHealthReason `json:"reasons"`
}

OverviewSenderHealth is "Sender health": a 0–100 score with a word and the reasons behind it, from the same checks the Deliverability screen shows.

type OverviewTier

type OverviewTier struct {
	Tier  string  `json:"tier" enum:"active,cooling,at_risk,sunset"`
	Count int64   `json:"count"`
	Pct   float64 `json:"pct" doc:"Share of all contacts, percent"`
	// Description: "opened in the last 30 days".
	Description string `json:"description"`
}

type Service

type Service struct {
	Pool           *pgxpool.Pool
	Q              *store.Queries
	Deliverability *deliverability.Service
	Providers      *manage.Service
	Campaigns      *campaigns.Service
	Audience       Audience
	// NextIssue finds the soonest issue of the workspace's recurring digests
	// (internal/digests); nil leaves digests out.
	NextIssue func(ctx context.Context, ws *store.Workspace) (*OverviewNextIssue, error)
	Now       func() time.Time
}

func (*Service) NextCampaign

func (s *Service) NextCampaign(ctx context.Context, ws *store.Workspace) (OverviewNextCampaign, error)

NextCampaign is the next scheduled campaign with its latest Send Readiness run, recipients, route split and the cost and duration estimates.

func (*Service) ProviderCards

func (s *Service) ProviderCards(ctx context.Context, ws *store.Workspace) (OverviewProviders, error)

ProviderCards are the sending providers as the providers screen sees them, named the Overview's way, with any failing health refresh.

func (*Service) Recent

Recent returns the latest campaigns that went out (sending or sent, latest start first), as the campaigns list shows them, so both screens agree: one page of the list without its totals (review 2026-11 CA-7).

func (*Service) SenderHealth

func (s *Service) SenderHealth(ctx context.Context, ws *store.Workspace) (OverviewSenderHealth, error)

SenderHealth scores the workspace's sending from the Deliverability checks (blocklists, authentication) and the providers' own numbers (bounce and complaint rates against each provider's limits, warm-up, status).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL