growth

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: 28 Imported by: 0

Documentation

Overview

Package growth implements Audience › Growth (audience-insights brief §3.4, M23): how contacts first joined and whether they left, by source (each form, the subscribe page, each import, API key and integration, people adding contacts; later referrals and recommendations), with the first touch's UTM parameters and referring page, monthly cohort retention, and bounce, complaint and human-open rates per source.

Moving a list isn't growth: imports are counted apart unless asked for.

Index

Constants

View Source
const (
	KindForm             = "form"              // a signup form (embedded, popup or hosted)
	KindSubscribePage    = "subscribe_page"    // the built-in subscribe page
	KindImport           = "import"            // an import that gave contacts the import day as their join date
	KindCarried          = "carried"           // the source an import carried over from the old platform
	KindAPIKey           = "api_key"           // an API key
	KindIntegration      = "integration"       // an integration, with the workflow that calls it
	KindPerson           = "person"            // added by someone in ReputeCast
	KindPreferenceCenter = "preference_center" // a list added in the preference center (one-list view)
	KindUnknown          = "unknown"
)

Source kinds of the growth registry.

Variables

This section is empty.

Functions

func DomainOf

func DomainOf(page string) string

DomainOf is a page's host ("blog.acme.io/2026/10/x" → "blog.acme.io").

func EnglishLabel

func EnglishLabel(src GrowthSource) string

EnglishLabel names a source in English, for places that have no app text of their own (CSV exports, agents).

func Erasure

func Erasure() erasure.Source

Erasure is where the contact came from. Source, medium, campaign, page and referrer stay: they are kept as a host and path only and Audience › Growth counts joins by them. The free-form UTM content and term go (review 2026-11 DP-1).

func Label

func Label(l i18n.Lang, src GrowthSource) string

Label names a source in a reader's language (the segment builder's growth sources): "Added by a person", "Brevo import (18 Sep)".

func PageOf

func PageOf(raw string) string

PageOf is an address without its scheme, query string or fragment ("https://acme.io/pricing?plan=team#top" → "acme.io/pricing"). It returns "" for anything that isn't an http(s) address.

func Register

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

Register adds the growth operations.

func RegisterAttributor

func RegisterAttributor(f Attributor)

RegisterAttributor adds a way to attribute joins to a registered kind.

func RegisterJobs

func RegisterJobs(reg *jobs.Registry, s *Service)

RegisterJobs adds the growth workers and their schedules.

func RegisterKind

func RegisterKind(k Kind)

RegisterKind adds a source kind (phase 5: referral, recommendation).

func RegisterNamer

func RegisterNamer(kind string, f Namer)

RegisterNamer adds the names of a registered kind's sources.

func SaveTouch

func SaveTouch(ctx context.Context, q *store.Queries, contact uuid.UUID, at time.Time, t Touch) error

SaveTouch stores a touch on the consent records a signup wrote at a moment (inside the signup's transaction).

func SourceKey

func SourceKey(kind, id string) string

SourceKey joins a kind and an id: "form:01a1…", "person".

Types

type Attributor

type Attributor func(contactSource, consentSource string) (kind, id string, ok bool)

Attributor reads a registered kind's source from a contact's own source and its first consent record's (phase 5: "referral:<link>" on a contact who joined through a referral link, "partner:<link>" on a partner signup's consent).

type ContactJoin

type ContactJoin struct {
	Attributed  bool         `json:"attributed"`
	Source      GrowthSource `json:"source"`
	JoinedAt    *time.Time   `json:"joinedAt,omitempty"`
	UTMSource   string       `json:"utmSource"`
	UTMMedium   string       `json:"utmMedium"`
	UTMCampaign string       `json:"utmCampaign"`
	Referrer    string       `json:"referrer"`
	Page        string       `json:"page"`
	LeftAt      *time.Time   `json:"leftAt,omitempty"`
	LeftKind    string       `json:"leftKind,omitempty"`
}

ContactJoin is how a contact first joined, for the profile's join line: "Joined Mon 13 Oct · Newsletter signup · linkedin / social / flags-ga · from docs.acme.io/flags".

type GrowthChart

type GrowthChart struct {
	Series []GrowthSeries   `json:"series"`
	Days   []GrowthChartDay `json:"days"`
}

GrowthChart is joins above the axis and departures below, by day.

type GrowthChartDay

type GrowthChartDay struct {
	Day     string  `json:"day"`
	Joined  []int64 `json:"joined"`
	Left    []int64 `json:"left"`
	Imports int64   `json:"imports"`
}

GrowthChartDay is one day of the chart: joins and departures per series (in Series order), and imports when they are included.

type GrowthCohort

type GrowthCohort struct {
	Month    string          `json:"month" doc:"YYYY-MM"`
	Contacts int64           `json:"contacts"`
	After30  GrowthRetention `json:"after30"`
	After90  GrowthRetention `json:"after90"`
}

GrowthCohort is the contacts who joined in one month.

type GrowthDepartures

type GrowthDepartures struct {
	Unsubscribed int64 `json:"unsubscribed"`
	HardBounced  int64 `json:"hardBounced"`
	Complained   int64 `json:"complained"`
	Erased       int64 `json:"erased"`
}

GrowthDepartures are departures by kind.

type GrowthFile

type GrowthFile struct {
	ContentType        string `header:"Content-Type"`
	ContentDisposition string `header:"Content-Disposition"`
	CacheControl       string `header:"Cache-Control"`
	Body               []byte
}

GrowthFile is a CSV download.

type GrowthImportItem

type GrowthImportItem struct {
	Key   string `json:"key"`
	Name  string `json:"name"`
	Day   string `json:"day"`
	Count int64  `json:"count"`
}

GrowthImportItem is one import of the period.

type GrowthListRef

type GrowthListRef struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

GrowthListRef is the list counted in the one-list view.

type GrowthPage

type GrowthPage struct {
	Period GrowthPeriod   `json:"period"`
	List   *GrowthListRef `json:"list,omitempty"`
	// Members is true in the one-list view: it counts list members.
	Members        bool               `json:"members"`
	IncludeImports bool               `json:"includeImports"`
	Contacts       int64              `json:"contacts"`
	Tiles          GrowthTiles        `json:"tiles"`
	Chart          GrowthChart        `json:"chart"`
	Sources        []GrowthSourceRow  `json:"sources"`
	Total          GrowthTotals       `json:"total"`
	Workspace      GrowthRates        `json:"workspace"`
	Departures     GrowthDepartures   `json:"departures"`
	UTM            GrowthUTM          `json:"utm"`
	Referrers      GrowthReferrers    `json:"referrers"`
	Cohorts        []GrowthCohort     `json:"cohorts"`
	CohortSource   string             `json:"cohortSource"`
	CohortSources  []GrowthSource     `json:"cohortSources"`
	Lists          []GrowthListRef    `json:"lists"`
	OnlyImports    bool               `json:"onlyImports"`
	Imports        []GrowthImportItem `json:"imports" doc:"Every finished import, for the only-imports state"`
	// MinContacts and MinDelivered are the "too few to compare" limits;
	// FlagFactor is how many times the workspace's rate flags a source.
	MinContacts  int64   `json:"minContacts"`
	MinDelivered int64   `json:"minDelivered"`
	FlagFactor   float64 `json:"flagFactor"`
}

GrowthPage is Audience › Growth.

type GrowthPeriod

type GrowthPeriod struct {
	Kind string `json:"kind" enum:"30d,90d,12m,custom"`
	From string `json:"from" doc:"YYYY-MM-DD"`
	To   string `json:"to" doc:"YYYY-MM-DD"`
	Days int    `json:"days"`
}

GrowthPeriod is the period counted, in the workspace timezone.

type GrowthQuery

type GrowthQuery struct {
	Period string `query:"period" enum:"30d,90d,12m,custom," doc:"30d (default), 90d, 12m or custom"`
	From   string `query:"from" maxLength:"10" doc:"First day of a custom period (YYYY-MM-DD)"`
	To     string `query:"to" maxLength:"10" doc:"Last day of a custom period"`
	List   string `query:"list" doc:"A list id: count its members instead of contacts"`
	// Imports adds imported contacts to the joins (a marker on the chart).
	Imports bool `query:"imports"`
	// CohortSource limits cohort retention to one source key.
	CohortSource string `query:"cohortSource" maxLength:"200"`
}

GrowthQuery is what Audience › Growth shows: a period, all lists or one, with or without imports.

type GrowthRates

type GrowthRates struct {
	Sent      int64   `json:"sent"`
	Delivered int64   `json:"delivered"`
	Bounce    float64 `json:"bounce"`
	Complaint float64 `json:"complaint"`
	HumanOpen float64 `json:"humanOpen"`
}

GrowthRates are the workspace's own rates over the period's sends.

type GrowthReferrerRow

type GrowthReferrerRow struct {
	Page  string `json:"page"`
	Joins int64  `json:"joins"`
}

GrowthReferrerRow is one referring page.

type GrowthReferrers

type GrowthReferrers struct {
	Rows  []GrowthReferrerRow `json:"rows"`
	None  int64               `json:"none"`
	Other GrowthRest          `json:"other"`
	Joins int64               `json:"joins"`
}

GrowthReferrers is the referring pages table.

type GrowthRest

type GrowthRest struct {
	Count         int      `json:"count"`
	Joins         int64    `json:"joins"`
	HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
}

GrowthRest is the "Other, N …" row of a table.

type GrowthRetention

type GrowthRetention struct {
	// State is done, in_progress (some members haven't reached the mark)
	// or not_started (none have).
	State string   `json:"state" enum:"done,in_progress,not_started"`
	Rate  *float64 `json:"rate,omitempty"`
	// CompleteOn is when every member reaches the mark; From is when the
	// first one does (a source whose first join is in this cohort).
	CompleteOn string `json:"completeOn,omitempty"`
	From       string `json:"from,omitempty"`
}

GrowthRetention is one cohort's share still subscribed after a mark.

type GrowthSeries

type GrowthSeries struct {
	Key    string       `json:"key"`
	Other  bool         `json:"other"`
	Source GrowthSource `json:"source"`
	Joined int64        `json:"joined"`
	Left   int64        `json:"left"`
}

GrowthSeries is one colour of the chart: one of the four biggest sources, or everything else ("other").

type GrowthSource

type GrowthSource struct {
	Key  string `json:"key"`
	Kind string `json:"kind"`
	// Name is the form, API key, integration or import platform.
	Name string `json:"name"`
	// Imported sources are counted apart from growth.
	Imported bool `json:"imported"`
	// FormKind is embedded, popup or hosted.
	FormKind string `json:"formKind,omitempty"`
	// ListChoice is true when the form offers more than one list to pick.
	ListChoice bool `json:"listChoice,omitempty"`
	// Hosts are the sites a form's signups came from in the period.
	Hosts []string `json:"hosts"`
	// URL is the subscribe page's or a hosted form's address.
	URL string `json:"url,omitempty"`
	// KeyPrefix is an API key's masked prefix ("rc_live_8f2c…a91d").
	KeyPrefix string `json:"keyPrefix,omitempty"`
	// Integration and Workflow name an integration source ("Zapier",
	// "Beta application (Typeform)").
	Integration string `json:"integration,omitempty"`
	Workflow    string `json:"workflow,omitempty"`
	// ImportedAt and ImportCount describe an import; TookImportDay is how
	// many of its contacts got the import day as their join date (the
	// others kept the date and source they came with).
	ImportedAt    *time.Time `json:"importedAt,omitempty"`
	ImportCount   int64      `json:"importCount,omitempty"`
	TookImportDay int64      `json:"tookImportDay,omitempty"`
	// Carried is the source an import kept ("import:csv", "form:docs");
	// CarriedLabel says it in words.
	Carried      string `json:"carried,omitempty"`
	CarriedLabel string `json:"carriedLabel,omitempty"`
	// FirstJoin is the source's first join ever.
	FirstJoin *time.Time `json:"firstJoin,omitempty"`
	Order     int        `json:"-"`
}

GrowthSource names a source and says what the app needs to describe it. Names are workspace content (a form's or key's name); the app writes the words around them.

type GrowthSourceList

type GrowthSourceList struct {
	Items []GrowthSourceOption `json:"items"`
}

GrowthSourceList is every source contacts joined through.

type GrowthSourceOption

type GrowthSourceOption struct {
	Source   GrowthSource `json:"source"`
	Contacts int64        `json:"contacts"`
}

GrowthSourceOption is a source the contacts filter offers, with how many contacts came from it.

type GrowthSourceRow

type GrowthSourceRow struct {
	Source GrowthSource `json:"source"`
	// Joined is nil for an import while imports are counted apart.
	Joined *int64 `json:"joined,omitempty"`
	Left   int64  `json:"left"`
	Net    *int64 `json:"net,omitempty"`
	// Contacts is how many contacts came from the source; with one list
	// picked, how many members it brought to the list in the period.
	Contacts  int64 `json:"contacts"`
	Sent      int64 `json:"sent"`
	Delivered int64 `json:"delivered"`
	// Rates are nil when there are too few to compare.
	BounceRate    *float64 `json:"bounceRate,omitempty"`
	ComplaintRate *float64 `json:"complaintRate,omitempty"`
	HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
	// TooFew says why rates aren't shown: contacts (under 50) or messages (under 100 delivered).
	TooFew string `json:"tooFew,omitempty" enum:"contacts,messages,"`
	// BounceFlag and ComplaintFlag are how many times the workspace's rate a
	// flagged source has.
	BounceFlag    *float64 `json:"bounceFlag,omitempty"`
	ComplaintFlag *float64 `json:"complaintFlag,omitempty"`
	// contains filtered or unexported fields
}

GrowthSourceRow is one row of the sources table.

type GrowthTiles

type GrowthTiles struct {
	Joined int64 `json:"joined"`
	Left   int64 `json:"left"`
	Net    int64 `json:"net"`
	// NetPct is the net change against the contacts (or members) at the
	// start of the period.
	NetPct      float64            `json:"netPct"`
	Imports     int64              `json:"imports"`
	ImportItems []GrowthImportItem `json:"importItems"`
}

GrowthTiles are the four numbers at the top.

type GrowthTotals

type GrowthTotals struct {
	Joined int64 `json:"joined"`
	Left   int64 `json:"left"`
	Net    int64 `json:"net"`
}

GrowthTotals is the sources table's last row.

type GrowthUTM

type GrowthUTM struct {
	CaptureStartedAt *time.Time `json:"captureStartedAt,omitempty"`
	// Joins counts the joins through forms and the subscribe page;
	// Captured those since capture began.
	Joins       int64          `json:"joins"`
	Captured    int64          `json:"captured"`
	NotCaptured int64          `json:"notCaptured"`
	NotCapRate  *float64       `json:"notCapturedHumanOpenRate,omitempty"`
	None        GrowthUTMRow   `json:"none"`
	Rows        []GrowthUTMRow `json:"rows"`
	Other       GrowthRest     `json:"other"`
}

GrowthUTM is the UTM table.

type GrowthUTMRow

type GrowthUTMRow struct {
	Source   string `json:"source"`
	Medium   string `json:"medium"`
	Campaign string `json:"campaign"`
	Joins    int64  `json:"joins"`
	// HumanOpenRate is nil until the combination's contacts got emails.
	HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
}

GrowthUTMRow is one UTM combination.

type Kind

type Kind struct {
	Key string
	// Imported kinds are counted apart from growth unless "Include
	// imports" is on.
	Imported bool
	// Order groups sources in the table (forms first, imports last).
	Order int
}

Kind is a source kind the registry knows. Later phases (referrals, recommendations) register theirs.

type Namer

type Namer func(ctx context.Context, q *store.Queries, ws *store.Workspace) (map[string]string, error)

Namer names a registered kind's sources by id ("Partner · Ops Weekly").

type RollupArgs

type RollupArgs struct {
	WorkspaceID uuid.UUID `json:"workspaceId,omitempty"`
}

RollupArgs adds up the days before today's sends per source.

func (RollupArgs) InsertOpts

func (RollupArgs) InsertOpts() river.InsertOpts

InsertOpts runs on the maintenance queue.

func (RollupArgs) Kind

func (RollupArgs) Kind() string

Kind implements river.JobArgs.

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Log   *slog.Logger
	Now   func() time.Time
	// SubscribeURL is the address of a workspace's subscribe page
	// ("https://news.acme.io/subscribe"), for the source's second line.
	SubscribeURL func(ctx context.Context, ws *store.Workspace) string
}

Service is the growth domain.

func (*Service) Attribute

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

Attribute runs the attribution step for one workspace: the first time it attributes every existing contact; after that what joined or left since.

func (*Service) ContactJoin

func (s *Service) ContactJoin(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (ContactJoin, error)

ContactJoin returns a contact's attribution.

func (*Service) Export

func (s *Service) Export(ctx context.Context, ws *store.Workspace, in GrowthQuery) ([]byte, string, error)

Export writes the Growth tables as CSV: totals only, never an address. Each export is in the audit log, as report exports are.

func (*Service) Page

func (s *Service) Page(ctx context.Context, ws *store.Workspace, in GrowthQuery) (GrowthPage, error)

Page returns everything Audience › Growth shows.

func (*Service) Rollup

func (s *Service) Rollup(ctx context.Context, wsID uuid.UUID, tz string, through *time.Time) error

Rollup writes the days after through (or the last 90) up to yesterday.

func (*Service) RollupAll

func (s *Service) RollupAll(ctx context.Context, only uuid.UUID) error

RollupAll writes the days not rolled up yet in every workspace (or one).

func (*Service) Sources

func (s *Service) Sources(ctx context.Context, ws *store.Workspace) (GrowthSourceList, error)

Sources lists the sources of the workspace's contacts, biggest first.

func (*Service) Tick

func (s *Service) Tick(ctx context.Context) error

Tick attributes every workspace's new joins and departures.

type TickArgs

type TickArgs struct{}

TickArgs attributes new joins and departures in every workspace.

func (TickArgs) InsertOpts

func (TickArgs) InsertOpts() river.InsertOpts

InsertOpts runs on the events queue, once a minute.

func (TickArgs) Kind

func (TickArgs) Kind() string

Kind implements river.JobArgs.

type Touch

type Touch struct {
	UTMSource, UTMMedium, UTMCampaign, UTMContent, UTMTerm string
	// Page is the page with the form and Referrer the page before it,
	// both without their query string or fragment ("acme.io/pricing").
	Page, Referrer string
}

Touch is where one signup came from.

func TouchOf

func TouchOf(pageURL, referrerURL string) Touch

TouchOf reads a touch from the page's address and the referrer the browser reported.

func (Touch) Empty

func (t Touch) Empty() bool

Empty reports whether the touch says nothing.

Jump to

Keyboard shortcuts

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