referrals

package
v1.4.0 Latest Latest
Warning

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

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

Documentation

Overview

Package referrals implements Grow › Referrals (design expansion phase 5, M25; brief reputecast-design-addon-grow.md §3.1–3.7, §3.10–3.13): one referral program per list, personal links, the counting and suspicion rules, milestones and their rewards, the review queue, results and referrers, the public hub and leaderboard data, the Referral and Reward blocks and the referral tokens.

A referral is recorded when someone signs up through a link (the invite page, or a form or the hosted page opened with ?ref=). It starts its hold when its subscriber confirms (double opt-in is always on for referrals) and counts when the hold ends with the subscriber still on the list. Obvious abuse is excluded automatically and anything suspicious waits for a person. Automatic events stay in the program's referral log (referral_events), not the audit log; everything a person changes is audited.

Index

Constants

View Source
const (
	EventSignedUp         = "signed_up"         // joined through a referral link (on the referred contact)
	EventConfirmed        = "confirmed"         // confirmed: the hold starts
	EventHeld             = "held"              // held for review
	EventCounted          = "counted"           // counted (on the referrer)
	EventNotCounted       = "not_counted"       // excluded, with its reason
	EventDecided          = "decided"           // a person decided on held referrals
	EventMilestoneReached = "milestone_reached" // a referrer reached a milestone
	EventRewardSent       = "reward_sent"       // a reward became available
	EventRewardFailed     = "reward_failed"     // a webhook reward gave up
	EventRewardFulfilled  = "reward_fulfilled"  // a manual reward was sent by hand
	EventLinkPaused       = "link_paused"
	EventLinkResumed      = "link_resumed"
)

Kinds of the referral log (referral_events).

View Source
const (
	HookCounted          = "referral.counted"
	HookHeld             = "referral.held"
	HookNotCounted       = "referral.not_counted"
	HookMilestoneReached = "referral.milestone_reached"
	HookRewardSent       = "referral.reward_sent"
	HookRewardFailed     = "referral.reward_failed"
)

Webhook events of the Referrals group.

View Source
const (
	PeriodMonth = "month"
	PeriodAll   = "all"
)

Leaderboard periods.

View Source
const (
	StatusAwaiting   = "awaiting"    // signed up, hasn't confirmed yet
	StatusHold       = "hold"        // confirmed, waiting for the hold to end
	StatusReview     = "review"      // held for review: a person decides
	StatusCounted    = "counted"     // final; counts toward milestones
	StatusNotCounted = "not_counted" // excluded, with its reason
)

Statuses of a referral.

View Source
const (
	ReasonSelf           = "self"
	ReasonSameIP         = "same_ip"
	ReasonDisposable     = "disposable"
	ReasonLeft           = "left"
	ReasonAlready        = "already"
	ReasonNeverConfirmed = "never_confirmed"
	ReasonReviewer       = "reviewer"
)

Reasons a referral isn't counted.

View Source
const (
	SignalBurst    = "burst"
	SignalSharedIP = "shared_ip"
	SignalNumbered = "numbered"
)

Suspicion signals that hold a referral for review.

View Source
const (
	RewardDownload = "download"
	RewardCodes    = "codes"
	RewardManual   = "manual"
	RewardCoupon   = "coupon"
	RewardWebhook  = "webhook"
)

Reward types.

View Source
const (
	RewardPending      = "pending"
	RewardSent         = "sent"
	RewardWaitingCodes = "waiting_codes"
	RewardToFulfill    = "to_fulfill"
	RewardFulfilled    = "fulfilled"
	RewardFailed       = "failed"
	RewardExpired      = "expired"
)

Reward statuses.

View Source
const (
	// NeverConfirmedAfter: no confirmation within 7 days.
	NeverConfirmedAfter = 7 * 24 * time.Hour
	// SameIPWindow: the addresses a referrer used in the last 30 days.
	SameIPWindow = 30 * 24 * time.Hour
	// IPKeptFor: addresses are kept 90 days for review, then reduced to
	// their network.
	IPKeptFor = 90 * 24 * time.Hour
	// AddressKeptFor: shipping addresses are deleted 30 days after the
	// reward is marked fulfilled.
	AddressKeptFor = 30 * 24 * time.Hour
	// DownloadValid: links to uploaded files work 7 days.
	DownloadValid = 7 * 24 * time.Hour
	// HubValid: a hub link opens the hub for 60 days.
	HubValid = 60 * 24 * time.Hour
	// UndoFor: a review decision can be undone for 10 seconds.
	UndoFor = 10 * time.Second
	// WebhookRetryFor: webhook rewards are retried for 6 hours.
	WebhookRetryFor = 6 * time.Hour
)

Timing rules of the brief.

View Source
const (
	Period7    = "7d"
	Period30   = "30d"
	PeriodAll2 = "all"
)

Periods of the results.

View Source
const (
	DecisionCount     = "count"
	DecisionDont      = "dont"
	DecisionDontPause = "dont_pause"
)

Review decisions.

View Source
const (
	ViaCopy     = "copy"
	ViaEmail    = "email"
	ViaX        = "x"
	ViaLinkedIn = "linkedin"
	ViaWhatsApp = "whatsapp"
	ViaOther    = "other"
)

Channels where links are shared, as share buttons add them (?via=).

View Source
const CodeAlphabet = "23456789ABCDEFGHJKMNPQRSTUVWXYZ"

CodeAlphabet is what referral codes are made of: digits and capital letters without look-alikes (no 0, O, 1, I or L). A code says nothing about the person.

View Source
const CodeLength = 6

CodeLength is the length of a referral code ("K7Q2MX").

View Source
const MaxFileBytes = 100 << 20

MaxFileBytes: download rewards are up to 100 MB.

View Source
const MinConfirmedForResults = 20

MinConfirmedForResults: results show after 20 confirmed referrals.

View Source
const MinForQuality = 100

MinForQuality: below 100 referred subscribers the quality card waits.

View Source
const TriggerMilestoneReached = "milestone_reached"

TriggerMilestoneReached is the automation trigger kind "Reached a milestone": Ref is the milestone, the payload names the program, the milestone's count and the reward.

Variables

Channels in the order results list them.

View Source
var ErrLinkExpired = errors.New("referrals: the link has expired")

ErrLinkExpired: a personal link is past its date.

View Source
var ErrNoHub = errors.New("referrals: no hub for this contact")

ErrNoHub: the contact has no link in a program (not a referrer).

ShareButtons a program can show, in the order pages show them.

Functions

func ChannelOf

func ChannelOf(via string) string

ChannelOf reads ?via=: no value is a copied link, an unknown one "other".

func CodeOf

func CodeOf(page string) (code, via string)

CodeOf reads the referral code and the channel of a signup's page: the invite page (/join/K7Q2MX) or any page opened with ?ref=K7Q2MX; share buttons add ?via=.

func DefaultMilestoneEmail

func DefaultMilestoneEmail(programID uuid.UUID, list, reward, rewardType string) (subject, preheader, src string)

DefaultMilestoneEmail is a new milestone's email (subject, preheader and MJML), for the demo data.

func Erasure

func Erasure() erasure.Source

Erasure is the contact's referral link, hub and rewards (with any postal address) and the network details of their own referral; the referrals they made, and their own, stay counted without an address (design expansion X15; review 2026-11 DP-1).

func ExpandReferral

func ExpandReferral(b ReferralBlock) string

ExpandReferral is the Referral block as Liquid.

func ExpandReward

func ExpandReward(b RewardBlock) string

ExpandReward is the Reward block as Liquid (milestone emails).

func ExpiredLink(c linktoken.Claims, valid time.Duration, now time.Time) bool

ExpiredLink reports whether a day-stamped token is older than valid.

func GrowHelpers

func GrowHelpers(ctx context.Context, q *store.Queries, wsID uuid.UUID, perm authz.Permission) []string

GrowHelpers names who can help with a Grow permission: up to three active members holding it, the people who run the program first (Editors and custom roles, then Admins, then Owners), as the boards write them ("Ask Sofia Rossi, Marcus Chen or Linh Nguyen").

func IsBot

func IsBot(method, userAgent string) bool

IsBot reports whether a visit came from a bot, a link preview or a scanner.

func NetworkOf

func NetworkOf(ip netip.Addr) string

NetworkOf is the network an address belongs to, what an address is reduced to after 90 days: its /24 for IPv4, its /48 for IPv6.

func NewCode

func NewCode() string

NewCode returns a random referral code.

func NormalizeCode

func NormalizeCode(s string) (string, bool)

NormalizeCode reads a code as people type or paste it ("k7q2mx", " K7Q2MX/") and reports whether it can be a referral code at all.

func NumberedKey

func NumberedKey(email string) string

NumberedKey is an address with every run of digits in its local part replaced by "#", after folding plus tags and Gmail dots: ben.t01@outlook.com and ben.t02@outlook.com both give "ben.t#@outlook.com". It is empty for an address without a digit in its local part, so such addresses never match.

func Register

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

Register adds the referral operations.

func RegisterContact

func RegisterContact(h huma.API, s *Service, partners func() PartnerEvents)

RegisterContact adds the contact profile's Grow data; partners adds the partner requests to the timeline.

func RegisterJobs

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

RegisterJobs adds the referrals' workers and schedules.

func SameMailbox

func SameMailbox(a, b string) bool

SameMailbox reports whether two addresses reach the same mailbox: plus tags and dots in Gmail addresses are ignored (the self-referral rule).

Types

type BlockCheck

type BlockCheck struct {
	// Present: the email has the block.
	Present bool
	// Program is the program it reads; Off when it's off, None when the
	// workspace has none.
	ProgramID string
	ListName  string
	Off       bool
	None      bool
	// OffAt and OffBy say when and by whom it was turned off; Zone is the
	// workspace's timezone for the time.
	OffAt *time.Time
	OffBy string
	Zone  string
	// Shown recipients are on the program's list, of Total.
	Shown, Total int64
}

BlockCheck is what the Referral block does in an email, for Send Readiness and the composer's checks.

func (BlockCheck) ReadinessRow

func (c BlockCheck) ReadinessRow(campaignID string, when func(time.Time) any) ReadinessRow

ReadinessRow is the block's row: who it shows to, or why it won't. when writes the time the program was turned off in each reader's region ("2 Oct, 14:05": readiness.ArgDayMonthTime).

type CouponOffer

type CouponOffer struct {
	ID          string
	Name        string
	Discount    string
	AppliesTo   string
	Issued      int64
	Redeemed    int64
	PaidMembers bool
}

CouponOffer is an offer of the kind "Referral reward".

type CouponStatus

type CouponStatus struct {
	Connected bool
	// Account is the connected account's name ("Acme Inc").
	Account string
}

CouponStatus says whether a payment provider can issue coupons.

type Coupons

type Coupons interface {
	Status(ctx context.Context, ws *store.Workspace) (CouponStatus, error)
	Offers(ctx context.Context, ws *store.Workspace) ([]CouponOffer, error)
	Issue(ctx context.Context, ws *store.Workspace, offerID string, contact uuid.UUID, validDays int) (IssuedCoupon, error)
	// ClaimURL is an issued code's claim link as it stands: its referrer's
	// personal upgrade link with the code.
	ClaimURL(ctx context.Context, ws *store.Workspace, contact uuid.UUID, code string) string
}

Coupons is the payment provider's side of the Stripe coupon reward (phase 6): whether Stripe is connected, the offers of the kind "Referral reward" and a single-use promotion code with its claim link per reward.

type GrowBlockRender

type GrowBlockRender struct {
	HTML string `json:"html"`
	// Hidden: none (it shows); not_on_list (the reader isn't on the
	// program's list, or their link is paused); program_off; no_program.
	Hidden    string     `json:"hidden" enum:"none,not_on_list,program_off,no_program"`
	ProgramID string     `json:"programId"`
	ListName  string     `json:"listName"`
	OffAt     *time.Time `json:"offAt,omitempty"`
	OffBy     string     `json:"offBy"`
	// For is who the block was rendered for ("" for the sample); Count
	// their counted referrals (the text the block shows: none, one, many).
	For   string `json:"for"`
	Count int64  `json:"count"`
	// Settings are the block's effective settings (defaults filled in), for
	// the composer's inspector; Reward the Reward block's.
	Settings ReferralBlock `json:"settings"`
	Reward   RewardBlock   `json:"reward"`
}

GrowBlockRender is a block's HTML for the canvas, and why it is hidden.

type GrowBlockRenderInput

type GrowBlockRenderInput struct {
	Kind     string          `json:"kind" enum:"referral,reward"`
	Settings json.RawMessage `json:"settings,omitempty"`
	// ContactID previews the block as a reader; without it, a sample.
	ContactID string `json:"contactId,omitempty" format:"uuid"`
	// MilestoneID is the milestone email the block is in: a Reward block
	// shows its reward, and the sample is a reader who just reached it.
	MilestoneID string `json:"milestoneId,omitempty" format:"uuid"`
}

GrowBlockRenderInput renders a Grow block for the composer's canvas.

type GrowHelperSets

type GrowHelperSets struct {
	Edit    []string `json:"edit"`
	Review  []string `json:"review"`
	Connect []string `json:"connect"`
	Export  []string `json:"export"`
	Earn    []string `json:"earn"`
}

GrowHelperSets are who can help with each Grow permission, for the read-only lines and disabled controls.

type GrowPreviewContact

type GrowPreviewContact struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Email string `json:"email"`
	// OnList: on the program's list with an active link (the block shows).
	OnList  bool  `json:"onList"`
	Counted int64 `json:"counted"`
	// Lists names the reader's lists ("Product Updates").
	Lists []string `json:"lists"`
}

GrowPreviewContact is a reader the composer previews Grow blocks as.

type GrowPreviewContacts

type GrowPreviewContacts struct {
	Items     []GrowPreviewContact `json:"items"`
	ProgramID string               `json:"programId"`
	ListName  string               `json:"listName"`
	Status    string               `json:"status" enum:"on,off,"`
}

GrowPreviewContacts are the readers to preview Grow blocks as: the program's top referrers and a few readers outside it.

type Hook

type Hook struct {
	S func() *Service
}

Hook records referrals from signups and confirmations (forms.SignupHook).

func (Hook) Accepted

func (h Hook) Accepted(ctx context.Context, tx pgx.Tx, ws *store.Workspace, e forms.SignupEvent) error

Accepted implements forms.SignupHook.

func (Hook) Confirmed

func (h Hook) Confirmed(ctx context.Context, tx pgx.Tx, ws *store.Workspace, e forms.ConfirmEvent) error

Confirmed implements forms.SignupHook.

func (Hook) DoubleOptIn

func (h Hook) DoubleOptIn(ctx context.Context, ws *store.Workspace, sub forms.Submission) bool

DoubleOptIn implements forms.SignupHook: a signup through a working referral link confirms by email.

type HourlyArgs

type HourlyArgs struct{}

HourlyArgs is the hourly job: the leaderboards, and what privacy asks to forget (visit keys after 24 hours, referrers' addresses after 30 days, signup addresses reduced to their network after 90 days, shipping addresses 30 days after their reward was fulfilled).

func (HourlyArgs) InsertOpts

func (HourlyArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (HourlyArgs) Kind

func (HourlyArgs) Kind() string

Kind implements river.JobArgs.

type HourlyWorker

type HourlyWorker struct {
	river.WorkerDefaults[HourlyArgs]
	S *Service
}

HourlyWorker runs the hourly job.

func (*HourlyWorker) Work

func (w *HourlyWorker) Work(ctx context.Context, _ *river.Job[HourlyArgs]) error

Work implements river.Worker.

type HubDownload

type HubDownload struct {
	FileID      uuid.UUID
	FileName    string
	ContentType string
	Size        int64
	URL         string
}

HubDownload is a reward file to stream, or an address to send the reader to.

type HubReferral

type HubReferral struct {
	Number      int
	Status      string
	Reason      string
	SignedUpAt  time.Time
	ConfirmedAt *time.Time
	CountsOn    *time.Time
	CountedAt   *time.Time
}

HubReferral is one referral on the hub: numbers and dates only.

type HubReward

type HubReward struct {
	ID        uuid.UUID
	Name      string
	Count     int
	Type      string
	Status    string
	Reached   bool
	SentAt    *time.Time
	UsedAt    *time.Time
	ExpiresAt *time.Time
	FileName  string
	FileType  string
	FileSize  int64
	// DownloadURL is a fresh expiring link (or the reward's own URL).
	DownloadURL string
	ClaimURL    string
	Code        string
	AnswerURL   string
	Note        string
	AskAddress  bool
	Address     *ReferralShippingAddress
	// ToGo is how many more counted referrals reach it (not reached yet).
	ToGo int64
}

HubReward is a reward on the hub.

type HubView

type HubView struct {
	Workspace    *store.Workspace
	ProgramID    uuid.UUID
	LinkID       uuid.UUID
	ContactID    uuid.UUID
	ProgramOn    bool
	LinkActive   bool
	Email        string
	FirstName    string
	ShortName    string
	ListName     string
	Link         string // "news.acme.io/join/K7Q2MX"
	LinkURL      string
	Code         string
	Share        []ShareLink
	ShareButtons []string
	Visits       int64
	Signups      int64
	Intro        string
	HoldDays     int
	SameIP       bool
	Disposable   bool
	Track        ReferralTrack
	Rewards      []HubReward
	Referrals    []HubReferral
	ShowName     bool
	ShowBoard    bool
	BoardOn      bool
	Rank         int
	BoardURL     string
	Token        string
}

HubView is a reader's referral hub.

type Inserter

type Inserter interface {
	Insert(ctx context.Context, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
}

Inserter enqueues River jobs (the job client, read at call time).

type InviteView

type InviteView struct {
	ProgramID uuid.UUID
	LinkID    uuid.UUID
	ListID    uuid.UUID
	// Name is the referrer's first name when they allow it, else "".
	Name     string
	Headline string
	Text     string
}

InviteView is the invite page of a referral link: the hosted subscribe page in invite mode, limited to the program's list.

type IssuedCoupon

type IssuedCoupon struct {
	Code      string
	ClaimURL  string
	ExpiresAt time.Time
}

IssuedCoupon is a single-use promotion code and its claim link.

type LeaderboardRow

type LeaderboardRow struct {
	Rank    int
	Name    string // "Omar H.", or "" for "A reader"
	Counted int
	Me      bool
}

LeaderboardRow is one row of the public leaderboard.

type LeaderboardView

type LeaderboardView struct {
	Period     string
	Rows       []LeaderboardRow
	More       int // readers beyond the top rows with the last row's count
	MoreCount  int
	Me         *LeaderboardRow
	ComputedAt *time.Time
}

LeaderboardView is a period of the leaderboard as the public page shows it.

type MilestoneInput

type MilestoneInput struct {
	api.WorkspaceInput
	Milestone string `path:"milestone" format:"uuid"`
}

MilestoneInput is a milestone's path.

type MilestoneSender

type MilestoneSender interface {
	QueueMilestoneEmail(ctx context.Context, tx pgx.Tx, ws uuid.UUID, emailID, contactID uuid.UUID, to string) (uuid.UUID, error)
}

MilestoneSender queues a milestone email for a referrer on the Automations stream (the sending engine's automation outbox), inside the transaction that gave the reward.

type PartnerEvents

type PartnerEvents interface {
	ContactEvents(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) ([]ReferralTimelineEvent, error)
}

PartnerEvents adds the partner requests to a contact's timeline (the recommendations package).

type PreferenceCard

type PreferenceCard struct {
	Counted int64
	HubURL  string
	// ListName is the program's list; NextCount and NextReward the next
	// milestone (0 when every reward is earned).
	ListName   string
	NextCount  int
	NextReward string
}

PreferenceCard is the preference center's "Invite friends" card: for a contact on a program's list while it's on.

type ProgramInput

type ProgramInput struct {
	api.WorkspaceInput
	Program string `path:"program" format:"uuid"`
}

ProgramInput is a program's path. The input types are exported so Huma finds their parameters when an operation's input embeds them.

type ReadinessLink struct {
	Label i18n.Text
	Href  string
}

ReadinessLink is a link of a row: its label and the workspace path it opens.

type ReadinessRow

type ReadinessRow struct {
	Status                           string // pass or warn
	Title, Detail, Ack, Label, Short i18n.Text
	Links                            []ReadinessLink
}

ReadinessRow is a Referral row of Send Readiness. Its texts are kept messages: Send Readiness writes them in each reader's language.

type ReferralBlock

type ReferralBlock struct {
	// Program binds the block to a program; without it, the reader's first.
	Program string `json:"program,omitempty" format:"uuid"`
	// Layout: a single line, a card with progress, or a card with the next
	// rewards.
	Layout   string             `json:"layout" enum:"line,progress,rewards"`
	Texts    ReferralBlockTexts `json:"texts"`
	Button   string             `json:"button" maxLength:"60"`
	Share    []string           `json:"share" maxItems:"4"`
	Progress bool               `json:"progress"`
}

ReferralBlock is the Referral block's settings.

func DefaultReferralBlock

func DefaultReferralBlock() ReferralBlock

DefaultReferralBlock is a new Referral block.

type ReferralBlockTexts

type ReferralBlockTexts struct {
	None string `json:"none" maxLength:"300"`
	One  string `json:"one" maxLength:"300"`
	Many string `json:"many" maxLength:"300"`
}

ReferralBlockTexts are the block's headline for 0, 1 and several counted referrals, with referral tokens.

type ReferralBucket

type ReferralBucket struct {
	Start     time.Time `json:"start"`
	End       time.Time `json:"end"`
	Confirmed int64     `json:"confirmed"`
	// Partial: the bucket is still going ("3 days so far").
	Partial bool `json:"partial"`
	Days    int  `json:"days"`
}

ReferralBucket is confirmed referrals in a day or week.

type ReferralCSV

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

ReferralFile is a CSV download.

type ReferralCampaignRef

type ReferralCampaignRef struct {
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	ScheduledAt *time.Time `json:"scheduledAt,omitempty"`
}

ReferralCampaignRef names a campaign.

type ReferralChannel

type ReferralChannel struct {
	Channel string `json:"channel" enum:"copy,x,linkedin,whatsapp,email,other"`
	Visits  int64  `json:"visits"`
	Signups int64  `json:"signups"`
}

ReferralChannel is visits and signups by where links were shared.

type ReferralCheck

type ReferralCheck struct {
	Key    string `json:"key" enum:"milestones,emails,files,stripe,sender"`
	Status string `json:"status" enum:"pass,fail"`
	// Facts the sentence is written from (the app writes it).
	Count   int                 `json:"count"`
	Counts  []int               `json:"counts"`
	Files   []ReferralCheckFile `json:"files"`
	Rewards []string            `json:"rewards"`
	Account string              `json:"account"`
	Offer   string              `json:"offer"`
	Sender  string              `json:"sender"`
	Emails  int                 `json:"emails"`
	Missing []string            `json:"missing"`
}

ReferralCheck is one check before a program turns on.

type ReferralCheckFile

type ReferralCheckFile struct {
	Name string `json:"name"`
	Size int64  `json:"size"`
}

ReferralCheckFile is a download reward's file.

type ReferralChecks

type ReferralChecks struct {
	Checks []ReferralCheck `json:"checks"`
	Pass   bool            `json:"pass"`
	// Links is how many links turning on creates (confirmed subscribers).
	Links int64 `json:"links"`
	// NextIssue is the list's next draft, to add the Referral block to
	// (the guide's step 4).
	NextIssue *ReferralCampaignRef `json:"nextIssue,omitempty"`
}

ReferralChecks are the turn-on checks.

type ReferralClaimLink struct {
	URL       string     `json:"url"`
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
}

ReferralClaimLink is a coupon reward's claim link.

type ReferralCodesInput

type ReferralCodesInput struct {
	Text string `json:"text" maxLength:"5000000" doc:"The codes, one per line; for CSV the first column"`
}

ReferralCodesInput uploads codes: CSV or text, one per line.

type ReferralCodesResult

type ReferralCodesResult struct {
	Added      int64 `json:"added"`
	Duplicates int64 `json:"duplicates"`
	Left       int64 `json:"left"`
	// Released: rewards that were waiting for codes and can go out now.
	Released int64 `json:"released"`
}

ReferralCodesResult is what an upload did.

type ReferralContact

type ReferralContact struct {
	Referrer   *ReferralContactReferrer   `json:"referrer,omitempty"`
	ReferredBy *ReferralContactReferredBy `json:"referredBy,omitempty"`
	Events     []ReferralTimelineEvent    `json:"events"`
}

ReferralContact is Grow on a contact's profile.

type ReferralContactReferredBy

type ReferralContactReferredBy struct {
	ProgramID  string     `json:"programId"`
	LinkID     string     `json:"linkId"`
	ReferrerID string     `json:"referrerId"`
	Referrer   string     `json:"referrer"`
	Status     string     `json:"status" enum:"awaiting,hold,review,counted,not_counted"`
	Reason     string     `json:"reason"`
	CountsOn   *time.Time `json:"countsOn,omitempty"`
	CountedAt  *time.Time `json:"countedAt,omitempty"`
}

ReferralContactReferredBy is how a contact joined through a referral.

type ReferralContactReferrer

type ReferralContactReferrer struct {
	ProgramID  string                  `json:"programId"`
	ListName   string                  `json:"listName"`
	LinkID     string                  `json:"linkId"`
	Link       string                  `json:"link"`
	Code       string                  `json:"code"`
	LinkStatus string                  `json:"linkStatus" enum:"active,paused"`
	Counted    int64                   `json:"counted"`
	InHold     int64                   `json:"inHold"`
	Awaiting   int64                   `json:"awaiting"`
	Held       int64                   `json:"held"`
	Visits     int64                   `json:"visits"`
	Signups    int64                   `json:"signups"`
	Milestones []int                   `json:"milestones"`
	Rewards    []ReferralContactReward `json:"rewards"`
}

ReferralContactReferrer is a contact as a referrer: the profile's Referrals card.

type ReferralContactReward

type ReferralContactReward struct {
	Name      string     `json:"name"`
	Milestone int        `json:"milestone"`
	Status    string     `json:"status"`
	SentAt    *time.Time `json:"sentAt,omitempty"`
	UsedAt    *time.Time `json:"usedAt,omitempty"`
}

ReferralContactRewards is a reward on the contact profile's Referrals card.

type ReferralCounting

type ReferralCounting struct {
	HoldDays   int          `json:"holdDays" enum:"0,3,7,14,30"`
	SameIP     bool         `json:"sameIp"`
	Disposable bool         `json:"disposable"`
	Left       bool         `json:"left"`
	Burst      ReferralRule `json:"burst"`
	SharedIP   ReferralRule `json:"sharedIp"`
	Numbered   bool         `json:"numbered"`
}

ReferralCounting is the counting rules (brief §3.2). Self-referral, "already on the list" and "never confirmed" always apply.

type ReferralCouponOffer

type ReferralCouponOffer struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Discount  string `json:"discount"`
	AppliesTo string `json:"appliesTo"`
	Issued    int64  `json:"issued"`
	Redeemed  int64  `json:"redeemed"`
}

ReferralCouponOffer is an offer a coupon reward can use.

type ReferralCreateInput

type ReferralCreateInput struct {
	ListID string `json:"listId" format:"uuid"`
}

ReferralCreateInput starts a program on a list (the guide's first step).

type ReferralDecision

type ReferralDecision struct {
	ID        string                  `json:"id"`
	Preview   ReferralDecisionPreview `json:"preview"`
	UndoUntil time.Time               `json:"undoUntil"`
}

ReferralDecision is a decision made, with how long Undo works.

type ReferralDecisionInput

type ReferralDecisionInput struct {
	IDs      []string `json:"ids" minItems:"1" maxItems:"500"`
	Decision string   `json:"decision" enum:"count,dont,dont_pause"`
	Note     string   `json:"note,omitempty" maxLength:"500"`
}

ReferralDecisionInput decides on held referrals: one referrer's, all of them or some.

type ReferralDecisionPreview

type ReferralDecisionPreview struct {
	Decision string     `json:"decision"`
	Count    int        `json:"count"`
	Referrer string     `json:"referrer"`
	Counted  int64      `json:"counted"`
	After    int64      `json:"after"`
	HoldEnds *time.Time `json:"holdEnds,omitempty"`
	// Rewards are the milestones the decision reaches (their names).
	Rewards []string `json:"rewards"`
	// Now: the hold has ended, so they count at once.
	Now bool `json:"now"`
}

ReferralDecisionPreview is what a decision would do, before it's made: "Counting these 3 brings Mateo Silva to 5 when their hold ends on 21 Oct. The Field Guide goes out then."

type ReferralEmailOnInput

type ReferralEmailOnInput struct {
	On bool `json:"on"`
}

ReferralEmailOnInput turns a milestone's email on or off.

type ReferralEmailPreviewInput

type ReferralEmailPreviewInput struct {
	ContactID string `json:"contactId,omitempty" format:"uuid"`
	Subject   string `json:"subject,omitempty" maxLength:"500"`
	Preheader string `json:"preheader,omitempty" maxLength:"500"`
	HTML      string `json:"html,omitempty" maxLength:"4000000"`
}

ReferralEmailPreviewInput renders a milestone email's draft (or what the composer has) as a reader.

type ReferralEmailRender

type ReferralEmailRender struct {
	Subject   string `json:"subject"`
	Preheader string `json:"preheader"`
	HTML      string `json:"html"`
	// For names who the preview shows.
	For string `json:"for"`
}

ReferralEmailRender is a milestone email rendered for a reader.

type ReferralEmailSave

type ReferralEmailSave struct {
	Subject      string `json:"subject" maxLength:"500"`
	Preheader    string `json:"preheader" maxLength:"500"`
	MJML         string `json:"mjml" maxLength:"2000000"`
	HTML         string `json:"html" maxLength:"4000000"`
	BaseRevision int    `json:"baseRevision" minimum:"0"`
}

ReferralEmailSave is an autosave of a milestone email's draft.

type ReferralEmailSaved

type ReferralEmailSaved struct {
	Revision int       `json:"revision"`
	SavedAt  time.Time `json:"savedAt"`
	// Version is set when the save made a version (Save, ⌘S).
	Version int `json:"version,omitempty"`
}

ReferralEmailSaved is what a save did.

type ReferralEmailSettings

type ReferralEmailSettings struct {
	SenderID string `json:"senderId"`
	ReplyTo  string `json:"replyTo"`
	// On is how many milestones send an email, of Milestones.
	On         int `json:"on"`
	Milestones int `json:"milestones"`
}

ReferralEmailSettings is where milestone emails come from. The stream is always Automations.

type ReferralEmailTest

type ReferralEmailTest struct {
	To        []string `json:"to" minItems:"1" maxItems:"5"`
	ContactID string   `json:"contactId,omitempty" format:"uuid"`
	Subject   string   `json:"subject,omitempty" maxLength:"500"`
	Preheader string   `json:"preheader,omitempty" maxLength:"500"`
	HTML      string   `json:"html,omitempty" maxLength:"4000000"`
}

ReferralEmailTest sends a milestone email's draft to the member, or to teammates (campaigns:send).

type ReferralEmailTestResult

type ReferralEmailTestResult struct {
	Sent     []string `json:"sent"`
	Provider string   `json:"provider"`
}

ReferralEmailTestResult says where the test went.

type ReferralEmailVersion

type ReferralEmailVersion struct {
	Version int       `json:"version"`
	Subject string    `json:"subject"`
	SavedAt time.Time `json:"savedAt"`
	SavedBy string    `json:"savedBy"`
}

ReferralEmailVersion is a saved version of a milestone email.

type ReferralEngagement

type ReferralEngagement struct {
	// Opened are the campaigns opened ("Weekly Digest #142"), Short their
	// short names ("#142").
	Opened []string `json:"opened"`
	Short  []string `json:"short"`
	Clicks int64    `json:"clicks"`
	// JoinedAfter: nothing was sent since they confirmed; the last issue
	// went out before ("#142").
	JoinedAfter string `json:"joinedAfter"`
}

ReferralEngagement is what a referred subscriber opened or clicked since confirming.

type ReferralFile

type ReferralFile struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	ContentType string    `json:"contentType"`
	Size        int64     `json:"size"`
	Downloads   int64     `json:"downloads"`
	UploadedBy  string    `json:"uploadedBy"`
	UploadedAt  time.Time `json:"uploadedAt"`
}

ReferralFile is a file for download rewards.

type ReferralFilterOption

type ReferralFilterOption struct {
	LinkID string `json:"linkId"`
	Name   string `json:"name"`
	Count  int    `json:"count"`
}

ReferralFilterOption is a referrer in a filter.

type ReferralFulfillInput

type ReferralFulfillInput struct {
	Note string `json:"note,omitempty" maxLength:"500"`
}

ReferralFulfillInput marks a manual reward fulfilled, with a note the referrer sees (a tracking number).

type ReferralFulfillItem

type ReferralFulfillItem struct {
	RewardID   string                   `json:"rewardId"`
	ContactID  string                   `json:"contactId"`
	Referrer   string                   `json:"referrer"`
	Email      string                   `json:"email"`
	Milestone  int                      `json:"milestone"`
	RewardName string                   `json:"rewardName"`
	ReachedAt  time.Time                `json:"reachedAt"`
	Address    *ReferralShippingAddress `json:"address,omitempty"`
}

ReferralFulfillItem is a manual reward waiting to be sent by hand.

type ReferralFunnel

type ReferralFunnel struct {
	Visits      int64                 `json:"visits"`
	Signups     int64                 `json:"signups"`
	Confirmed   int64                 `json:"confirmed"`
	Counted     int64                 `json:"counted"`
	Unconfirmed int64                 `json:"unconfirmed" doc:"Never confirmed, or still waiting to confirm"`
	InHold      int64                 `json:"inHold"`
	HoldEndsBy  *time.Time            `json:"holdEndsBy,omitempty"`
	Held        int64                 `json:"held"`
	NotCounted  int64                 `json:"notCounted"`
	Reasons     []ReferralReasonCount `json:"reasons"`
	// RewardsSent and Referrers (with a counted referral) under Counted.
	RewardsSent int64 `json:"rewardsSent"`
	Referrers   int64 `json:"referrers"`
	Weeks       int   `json:"weeks"`
}

ReferralFunnel is visits → signups → confirmed → counted, with what branches off.

type ReferralHeldItem

type ReferralHeldItem struct {
	ID          string             `json:"id"`
	Email       string             `json:"email"`
	SignedUpAt  time.Time          `json:"signedUpAt"`
	ConfirmedAt *time.Time         `json:"confirmedAt,omitempty"`
	IP          string             `json:"ip"`
	Network     ReferralNetwork    `json:"network"`
	Engagement  ReferralEngagement `json:"engagement"`
	HoldEnds    *time.Time         `json:"holdEnds,omitempty"`
	Signals     []string           `json:"signals"`
}

ReferralHeldItem is a held referral with its evidence.

type ReferralImage

type ReferralImage struct {
	ID     string `json:"id"`
	URL    string `json:"url"`
	Name   string `json:"name"`
	Width  int    `json:"width"`
	Height int    `json:"height"`
	Size   int64  `json:"size"`
}

ReferralImage is a reward's picture, from the media library.

type ReferralItem

type ReferralItem struct {
	ID          string     `json:"id"`
	Number      int        `json:"number"`
	Email       string     `json:"email"`
	Status      string     `json:"status" enum:"awaiting,hold,review,counted,not_counted"`
	Reason      string     `json:"reason"`
	LeftKind    string     `json:"leftKind"`
	SignedUpAt  time.Time  `json:"signedUpAt"`
	ConfirmedAt *time.Time `json:"confirmedAt,omitempty"`
	CountsOn    *time.Time `json:"countsOn,omitempty"`
	CountedAt   *time.Time `json:"countedAt,omitempty"`
	RemindedAt  *time.Time `json:"remindedAt,omitempty"`
}

ReferralItem is one of a referrer's referrals.

type ReferralLeaderboardInput

type ReferralLeaderboardInput struct {
	On bool `json:"on"`
}

ReferralLeaderboardInput turns the leaderboard on or off.

type ReferralLeaderboardSettings

type ReferralLeaderboardSettings struct {
	On      bool       `json:"on"`
	At      *time.Time `json:"at,omitempty"`
	By      string     `json:"by"`
	Periods []string   `json:"periods" maxItems:"2" enum:"month,all"`
	Rows    int        `json:"rows" enum:"5,10,25"`
	URL     string     `json:"url"`
}

ReferralLeaderboardSettings is the public leaderboard (off by default).

type ReferralLinkPauseInput

type ReferralLinkPauseInput struct {
	Note string `json:"note,omitempty" maxLength:"500"`
}

ReferralLinkPauseInput pauses a referrer's link, with a note.

type ReferralListOption

type ReferralListOption struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Subscribers int64  `json:"subscribers"`
	// Taken: the list already has a program.
	Taken bool `json:"taken"`
}

ReferralListOption is a list a program can use.

type ReferralMilestoneCnt

type ReferralMilestoneCnt struct {
	Count     int   `json:"count"`
	Referrers int64 `json:"referrers"`
}

ReferralMilestoneCnt is how many referrers reached a milestone.

type ReferralMilestoneEmail

type ReferralMilestoneEmail struct {
	On       bool       `json:"on"`
	EmailID  string     `json:"emailId"`
	Subject  string     `json:"subject"`
	Versions int64      `json:"versions"`
	SavedAt  *time.Time `json:"savedAt,omitempty"`
}

ReferralMilestoneEmail is a milestone's email.

type ReferralMilestoneEmailDetail

type ReferralMilestoneEmailDetail struct {
	MilestoneID string `json:"milestoneId"`
	ProgramID   string `json:"programId"`
	Count       int    `json:"count"`
	RewardName  string `json:"rewardName"`
	RewardType  string `json:"rewardType"`
	ListName    string `json:"listName"`
	// Sender is the program's ("Acme Newsletter <digest@news.acme.io>");
	// SenderDefault says it's the list's default.
	Sender        string     `json:"sender"`
	SenderDefault bool       `json:"senderDefault"`
	On            bool       `json:"on"`
	Subject       string     `json:"subject"`
	Preheader     string     `json:"preheader"`
	MJML          string     `json:"mjml"`
	HTML          string     `json:"html"`
	Revision      int        `json:"revision"`
	SavedAt       *time.Time `json:"savedAt,omitempty"`
	// Versions are the saves (the email that goes out is the latest).
	Versions []ReferralEmailVersion `json:"versions"`
	// FileName and FileSize describe a download reward ("PDF, 18 MB").
	FileName    string `json:"fileName"`
	FileType    string `json:"fileType"`
	FileSize    int64  `json:"fileSize"`
	Description string `json:"description"`
	UploadedBy  string `json:"uploadedBy"`
}

ReferralMilestoneEmailDetail is a milestone email for the composer's milestone mode.

type ReferralMilestoneHealth

type ReferralMilestoneHealth struct {
	Status string `json:"status" enum:"ok,warn,bad"`
	// Kind: healthy, codes_low, codes_out, webhook_failing, stripe_missing,
	// file_missing.
	Kind string `json:"kind" enum:"healthy,codes_low,codes_out,webhook_failing,stripe_missing,file_missing"`
	// CodesLeft and RunOutDays (the current pace) for code rewards.
	CodesLeft  int64    `json:"codesLeft"`
	RunOutDays *float64 `json:"runOutDays,omitempty"`
	Waiting    int64    `json:"waiting"`
	// LastStatus and Failures describe a failing webhook.
	LastStatus int `json:"lastStatus"`
	Failures   int `json:"failures"`
}

ReferralMilestoneHealth says whether a reward can go out.

type ReferralMilestoneInput

type ReferralMilestoneInput struct {
	Count             int    `json:"count" minimum:"1" maximum:"100000"`
	RewardName        string `json:"rewardName" maxLength:"120"`
	RewardDescription string `json:"rewardDescription" maxLength:"200"`
	ImageID           string `json:"imageId,omitempty" format:"uuid"`
	Type              string `json:"type" enum:"download,codes,manual,coupon,webhook"`
	FileID            string `json:"fileId,omitempty" format:"uuid"`
	DownloadURL       string `json:"downloadUrl,omitempty" maxLength:"2000"`
	CodesAlertBelow   int    `json:"codesAlertBelow,omitempty" minimum:"0" maximum:"100000"`
	AskAddress        bool   `json:"askAddress,omitempty"`
	CouponOfferID     string `json:"couponOfferId,omitempty" maxLength:"200"`
	CouponValidDays   int    `json:"couponValidDays,omitempty" enum:"0,30,60,90"`
	WebhookURL        string `json:"webhookUrl,omitempty" maxLength:"2000"`
	// WebhookSecret is write-only: set it to replace the stored one.
	WebhookSecret *string `json:"webhookSecret,omitempty" maxLength:"200"`
	EmailOn       bool    `json:"emailOn"`
}

ReferralMilestoneInput creates or changes a milestone.

type ReferralMilestoneList

type ReferralMilestoneList struct {
	ProgramID string                  `json:"programId"`
	ListName  string                  `json:"listName"`
	Sender    string                  `json:"sender"`
	Items     []ReferralMilestoneView `json:"items"`
	Files     []ReferralFile          `json:"files"`
	ToFulfill []ReferralFulfillItem   `json:"toFulfill"`
	Stripe    ReferralStripe          `json:"stripe"`
	// ShowAddresses: shipping addresses show to members with subscribers:view.
	ShowAddresses bool           `json:"showAddresses"`
	Helpers       GrowHelperSets `json:"helpers"`
}

ReferralMilestoneList is Referrals › Milestones.

type ReferralMilestoneStats

type ReferralMilestoneStats struct {
	Reached      int64 `json:"reached"`
	Sent         int64 `json:"sent"`
	Used         int64 `json:"used"`
	Waiting      int64 `json:"waiting"`
	Failed       int64 `json:"failed"`
	WaitingCodes int64 `json:"waitingCodes"`
	ToFulfill    int64 `json:"toFulfill"`
}

ReferralMilestoneStats are a milestone's rewards: reached, sent, used, waiting and failed.

type ReferralMilestoneView

type ReferralMilestoneView struct {
	ID                string         `json:"id"`
	Count             int            `json:"count"`
	RewardName        string         `json:"rewardName"`
	RewardDescription string         `json:"rewardDescription"`
	Image             *ReferralImage `json:"image,omitempty"`
	Type              string         `json:"type" enum:"download,codes,manual,coupon,webhook"`
	File              *ReferralFile  `json:"file,omitempty"`
	DownloadURL       string         `json:"downloadUrl"`
	CodesUploaded     int64          `json:"codesUploaded"`
	CodesLeft         int64          `json:"codesLeft"`
	CodesAlertBelow   int            `json:"codesAlertBelow"`
	AskAddress        bool           `json:"askAddress"`
	CouponOfferID     string         `json:"couponOfferId"`
	CouponOfferName   string         `json:"couponOfferName"`
	CouponValidDays   int            `json:"couponValidDays"`
	WebhookURL        string         `json:"webhookUrl"`
	// WebhookSecretSet: a signing secret is stored (it's never returned).
	WebhookSecretSet bool                    `json:"webhookSecretSet"`
	WebhookStatus    *int                    `json:"webhookStatus,omitempty"`
	WebhookCalledAt  *time.Time              `json:"webhookCalledAt,omitempty"`
	Email            ReferralMilestoneEmail  `json:"email"`
	Stats            ReferralMilestoneStats  `json:"stats"`
	Health           ReferralMilestoneHealth `json:"health"`
}

ReferralMilestoneView is a milestone with its reward.

type ReferralNetwork

type ReferralNetwork struct {
	CIDR string `json:"cidr"`
	Name string `json:"name"`
	ASN  string `json:"asn"`
	Kind string `json:"kind" enum:"hosting,office,residential,mobile,"`
}

ReferralNetwork is where a signup came from: the address's network, with its name, autonomous system and kind when known.

type ReferralPageSettings

type ReferralPageSettings struct {
	// InviteHeadline holds {first_name}: the referrer's name when they allow
	// it, otherwise "A reader".
	InviteHeadline string `json:"inviteHeadline" maxLength:"200"`
	InviteText     string `json:"inviteText" maxLength:"600"`
	HubIntro       string `json:"hubIntro" maxLength:"600"`
	// ShareMessage holds {link}, the reader's own link.
	ShareMessage string   `json:"shareMessage" maxLength:"500"`
	ShareButtons []string `json:"shareButtons" maxItems:"5" enum:"copy,email,x,linkedin,whatsapp"`
}

ReferralPageSettings is what readers see when they share and when friends arrive.

type ReferralPerson

type ReferralPerson struct {
	ContactID string `json:"contactId"`
	Name      string `json:"name"`
	// Email shows to members with subscribers:view.
	Email      string     `json:"email"`
	FirstName  string     `json:"firstName"`
	Since      *time.Time `json:"since,omitempty" doc:"On the program's list since"`
	Counted    int64      `json:"counted"`
	LinkID     string     `json:"linkId"`
	LinkStatus string     `json:"linkStatus" enum:"active,paused"`
}

ReferralPerson is a referrer as the team sees them.

type ReferralProgramDetail

type ReferralProgramDetail struct {
	ID          string `json:"id"`
	ListID      string `json:"listId"`
	ListName    string `json:"listName"`
	Status      string `json:"status" enum:"off,on"`
	Subscribers int64  `json:"subscribers"`
	Links       int64  `json:"links"`
	SetupStep   int    `json:"setupStep"`
	// SetupSavedAt and SetupSavedBy say when the guide was left ("Welcome
	// back, Sofia").
	SetupSavedAt *time.Time `json:"setupSavedAt,omitempty"`
	SetupSavedBy string     `json:"setupSavedBy"`
	StartedAt    *time.Time `json:"startedAt,omitempty"`
	StartedBy    string     `json:"startedBy"`
	// StatusAt and StatusBy are the last change ("off since 15 Oct, 09:12").
	StatusAt *time.Time `json:"statusAt,omitempty"`
	StatusBy string     `json:"statusBy"`
	// AnnouncedIn is the first campaign sent with the Referral block.
	AnnouncedIn string                      `json:"announcedIn"`
	Counting    ReferralCounting            `json:"counting"`
	Pages       ReferralPageSettings        `json:"pages"`
	Leaderboard ReferralLeaderboardSettings `json:"leaderboard"`
	Emails      ReferralEmailSettings       `json:"emails"`
	Senders     []ReferralSenderOption      `json:"senders"`
	// LinkHost and LinkExample show the link format ("news.acme.io/join/K7Q2MX").
	LinkHost    string `json:"linkHost"`
	LinkExample string `json:"linkExample"`
	// Held is the review queue (the Review tab's badge) and its oldest.
	Held       int64          `json:"held"`
	HeldOldest *time.Time     `json:"heldOldest,omitempty"`
	InHold     int64          `json:"inHold"`
	Awaiting   int64          `json:"awaiting"`
	UpdatedAt  time.Time      `json:"updatedAt"`
	Helpers    GrowHelperSets `json:"helpers"`
}

ReferralProgramDetail is a program with its settings and the facts the pages' headers show.

type ReferralProgramList

type ReferralProgramList struct {
	Items   []ReferralProgramSummary `json:"items"`
	Lists   []ReferralListOption     `json:"lists"`
	Helpers GrowHelperSets           `json:"helpers"`
}

ReferralProgramList is the workspace's programs and the lists a new one can use.

type ReferralProgramSummary

type ReferralProgramSummary struct {
	ID          string     `json:"id"`
	ListID      string     `json:"listId"`
	ListName    string     `json:"listName"`
	Status      string     `json:"status" enum:"off,on"`
	SetupStep   int        `json:"setupStep" doc:"The set-up guide's step (1 to 5) until the program is first turned on; 0 afterwards"`
	Subscribers int64      `json:"subscribers"`
	StartedAt   *time.Time `json:"startedAt,omitempty"`
}

ReferralProgramSummary is one program of the workspace.

type ReferralQuality

type ReferralQuality struct {
	Referred int64 `json:"referred"`
	// Enough: 100 or more referred subscribers to compare.
	Enough bool `json:"enough"`
	// Opens on the list's last issue; Campaign names it.
	Campaign     string              `json:"campaign"`
	Opens        ReferralQualityLine `json:"opens"`
	Unsubscribed ReferralQualityLine `json:"unsubscribed"`
	Bounced      ReferralQualityLine `json:"bounced"`
}

ReferralQuality is the quality of referred subscribers.

type ReferralQualityLine

type ReferralQualityLine struct {
	Referred   float64 `json:"referred"`
	ReferredN  int64   `json:"referredN"`
	ReferredOf int64   `json:"referredOf"`
	Others     float64 `json:"others"`
	OthersN    int64   `json:"othersN"`
	OthersOf   int64   `json:"othersOf"`
}

ReferralQualityLine compares referred subscribers with others.

type ReferralReasonCount

type ReferralReasonCount struct {
	Reason   string `json:"reason" enum:"self,same_ip,disposable,left,already,never_confirmed,reviewer"`
	LeftKind string `json:"leftKind"`
	Count    int64  `json:"count"`
}

ReferralReasonCount is how many referrals weren't counted for a reason.

type ReferralReferrerList

type ReferralReferrerList struct {
	Items []ReferralReferrerRow `json:"items"`
	Total int64                 `json:"total"`
	Page  int                   `json:"page"`
	// WithCounted is how many referrers have a counted referral.
	WithCounted int64 `json:"withCounted"`
	// Filters' counts.
	HeldReferrers   int64                  `json:"heldReferrers"`
	PausedLinks     int64                  `json:"pausedLinks"`
	MilestoneCounts []ReferralMilestoneCnt `json:"milestoneCounts"`
	ShowAddresses   bool                   `json:"showAddresses"`
	Helpers         GrowHelperSets         `json:"helpers"`
}

ReferralReferrerList is a page of referrers.

type ReferralReferrerPanel

type ReferralReferrerPanel struct {
	Referrer ReferralPerson `json:"referrer"`
	// Link and its numbers.
	Link        string     `json:"link"`
	Code        string     `json:"code"`
	LinkCreated time.Time  `json:"linkCreated"`
	Visits      int64      `json:"visits"`
	Signups     int64      `json:"signups"`
	PausedAt    *time.Time `json:"pausedAt,omitempty"`
	PausedBy    string     `json:"pausedBy"`
	PauseNote   string     `json:"pauseNote"`
	// PauseReason summarizes the review decision that paused it.
	PausedNotCounted int64    `json:"pausedNotCounted"`
	PausedSignals    []string `json:"pausedSignals"`
	ShowName         bool     `json:"showName"`
	ShowLeaderboard  bool     `json:"showLeaderboard"`
	// FormsHost is where ?ref= also works ("acme.io forms").
	Track     ReferralTrack        `json:"track"`
	Referrals []ReferralItem       `json:"referrals"`
	Rewards   []ReferralRewardItem `json:"rewards"`
	// ShowAddresses: the referred addresses show to members with
	// subscribers:view.
	ShowAddresses bool           `json:"showAddresses"`
	Helpers       GrowHelperSets `json:"helpers"`
}

ReferralReferrerPanel is the referrer panel (it has its own link).

type ReferralReferrerRow

type ReferralReferrerRow struct {
	LinkID     string `json:"linkId"`
	ContactID  string `json:"contactId"`
	Name       string `json:"name"`
	Email      string `json:"email"`
	Counted    int64  `json:"counted"`
	InHold     int64  `json:"inHold"`
	Held       int64  `json:"held"`
	NotCounted int64  `json:"notCounted"`
	// Milestones reached (their counts).
	Milestones []int `json:"milestones"`
	// Rewards sent, and a coupon not claimed yet.
	RewardsSent  int64      `json:"rewardsSent"`
	Unclaimed    string     `json:"unclaimed"`
	LinkStatus   string     `json:"linkStatus" enum:"active,paused"`
	LastReferral *time.Time `json:"lastReferral,omitempty"`
}

ReferralReferrerRow is one row of Referrals › Referrers.

type ReferralRemoved

type ReferralRemoved struct {
	Removed int64 `json:"removed"`
}

ReferralRemoved says how many unused codes were removed.

type ReferralResults

type ReferralResults struct {
	Program   ReferralProgramDetail `json:"program"`
	Period    string                `json:"period" enum:"7d,30d,all"`
	From      time.Time             `json:"from"`
	To        time.Time             `json:"to"`
	Enough    bool                  `json:"enough" doc:"20 confirmed referrals or more"`
	Funnel    ReferralFunnel        `json:"funnel"`
	Grouping  string                `json:"grouping" enum:"day,week"`
	OverTime  []ReferralBucket      `json:"overTime"`
	Channels  []ReferralChannel     `json:"channels"`
	Top       []ReferralTopReferrer `json:"top"`
	WithThree int64                 `json:"withThree"`
	WithTen   int64                 `json:"withTen"`
	// MilestoneLadder: referrers who reached each milestone.
	Rewards []ReferralRewardRow `json:"rewards"`
	Quality ReferralQuality     `json:"quality"`
}

ReferralResults is Referrals › Results.

type ReferralReviewGroup

type ReferralReviewGroup struct {
	Referrer ReferralPerson     `json:"referrer"`
	Items    []ReferralHeldItem `json:"items"`
	Signals  []ReferralSignal   `json:"signals"`
	// Suggestion: dont_pause ("Suggested: don't count, and pause the
	// link") or count ("Why it may be fine").
	Suggestion string `json:"suggestion" enum:"dont_pause,count,"`
	// Evidence of a group that may be fine.
	SameDomain     string      `json:"sameDomain"`
	DifferentNames bool        `json:"differentNames"`
	Days           int         `json:"days"`
	Opened         int         `json:"opened"`
	OpenedIn       string      `json:"openedIn"`
	ConfirmedDays  []time.Time `json:"confirmedDays"`
	HoldEnds       []time.Time `json:"holdEnds"`
	Engaged        bool        `json:"engaged"`
}

ReferralReviewGroup is one referrer's held referrals.

type ReferralReviewQueue

type ReferralReviewQueue struct {
	Held     int                   `json:"held"`
	Oldest   *time.Time            `json:"oldest,omitempty"`
	HoldDays int                   `json:"holdDays"`
	Groups   []ReferralReviewGroup `json:"groups"`
	Signals  []ReferralSignalCount `json:"signals"`
	// Referrers are the filter's options: name and held count.
	Referrers []ReferralFilterOption `json:"referrers"`
	// ShowAddresses: addresses and IPs show to members with subscribers:view.
	ShowAddresses bool           `json:"showAddresses"`
	Helpers       GrowHelperSets `json:"helpers"`
}

ReferralReviewQueue is Referrals › Review.

type ReferralRewardItem

type ReferralRewardItem struct {
	ID        string `json:"id"`
	Milestone int    `json:"milestone"`
	Name      string `json:"name"`
	Type      string `json:"type" enum:"download,codes,manual,coupon,webhook"`
	Status    string `json:"status" enum:"pending,sent,waiting_codes,to_fulfill,fulfilled,failed,expired"`
	// Used: downloaded, claimed or fulfilled.
	ReachedAt time.Time  `json:"reachedAt"`
	SentAt    *time.Time `json:"sentAt,omitempty"`
	UsedAt    *time.Time `json:"usedAt,omitempty"`
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
	FileName  string     `json:"fileName"`
	FileType  string     `json:"fileType"`
	FileSize  int64      `json:"fileSize"`
	HasClaim  bool       `json:"hasClaim"`
	Note      string     `json:"note"`
	Error     string     `json:"error"`
	// Code is shown to members with grow:review.
	Code string `json:"code,omitempty"`
}

ReferralRewardItem is a reward a referrer received.

type ReferralRewardRow

type ReferralRewardRow struct {
	MilestoneID string `json:"milestoneId"`
	Count       int    `json:"count"`
	Name        string `json:"name"`
	Type        string `json:"type"`
	Reached     int64  `json:"reached"`
	Sent        int64  `json:"sent"`
	Used        int64  `json:"used"`
	Waiting     int64  `json:"waiting"`
	Failed      int64  `json:"failed"`
}

ReferralRewardRow is a milestone's rewards in the results.

type ReferralRule

type ReferralRule struct {
	On        bool `json:"on"`
	Threshold int  `json:"threshold" minimum:"1" maximum:"1000"`
}

ReferralRule is a suspicion rule with its threshold.

type ReferralSenderOption

type ReferralSenderOption struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Email    string `json:"email"`
	Verified bool   `json:"verified"`
	// Default: the list's default sender (the Automations stream's).
	Default bool `json:"default"`
}

ReferralSenderOption is a sender milestone emails can come from.

type ReferralSettingsImpact

type ReferralSettingsImpact struct {
	HoldFrom int   `json:"holdFrom"`
	HoldTo   int   `json:"holdTo"`
	InHold   int64 `json:"inHold"`
	// Awaiting referrals are checked against the exclusion and suspicion
	// rules when they confirm.
	Awaiting     int64    `json:"awaiting"`
	RulesChanged []string `json:"rulesChanged"`
}

ReferralSettingsImpact is what a change of the counting rules does to referrals not decided yet ("18 referrals in hold would count up to 7 days later").

type ReferralSettingsInput

type ReferralSettingsInput struct {
	Counting ReferralCounting     `json:"counting"`
	Pages    ReferralPageSettings `json:"pages"`
	// Leaderboard's periods and rows (its switch is its own action).
	LeaderboardPeriods []string `json:"leaderboardPeriods" maxItems:"2" enum:"month,all"`
	LeaderboardRows    int      `json:"leaderboardRows" enum:"5,10,25"`
	SenderID           string   `json:"senderId,omitempty" format:"uuid"`
	ReplyTo            string   `json:"replyTo" maxLength:"254"`
	// BaseUpdatedAt refuses the save when someone saved since.
	BaseUpdatedAt *time.Time `json:"baseUpdatedAt,omitempty"`
}

ReferralSettingsInput saves Referrals › Settings.

type ReferralSetupInput

type ReferralSetupInput struct {
	Step   int    `json:"step" minimum:"1" maximum:"5"`
	ListID string `json:"listId,omitempty" format:"uuid"`
}

ReferralSetupInput saves the guide's step ("Save and exit", Continue).

type ReferralShippingAddress

type ReferralShippingAddress struct {
	Name    string `json:"name" maxLength:"200"`
	Street  string `json:"street" maxLength:"300"`
	City    string `json:"city" maxLength:"200"`
	Country string `json:"country" maxLength:"100"`
}

ReferralShippingAddress is where a manual reward goes. It's deleted 30 days after the reward is marked fulfilled.

type ReferralSignal

type ReferralSignal struct {
	Kind      string          `json:"kind" enum:"burst,shared_ip,numbered"`
	Count     int             `json:"count"`
	Minutes   int             `json:"minutes"`
	From      *time.Time      `json:"from,omitempty"`
	To        *time.Time      `json:"to,omitempty"`
	Threshold int             `json:"threshold"`
	IP        string          `json:"ip"`
	Network   ReferralNetwork `json:"network"`
	// All: every held referral of the group shares it.
	All   bool   `json:"all"`
	First string `json:"first"`
	Last  string `json:"last"`
}

ReferralSignal is a suspicion rule that held a group, with the facts its sentence is written from.

type ReferralSignalCount

type ReferralSignalCount struct {
	Kind      string `json:"kind"`
	Referrers int    `json:"referrers"`
}

ReferralSignalCount is how many referrers a signal holds (the filter).

type ReferralStripe

type ReferralStripe struct {
	Connected bool                  `json:"connected"`
	Account   string                `json:"account"`
	Offers    []ReferralCouponOffer `json:"offers"`
}

ReferralStripe says whether coupon rewards can be picked.

type ReferralTimelineEvent

type ReferralTimelineEvent struct {
	Kind string    `json:"kind" enum:"joined,counted,milestone,reward_sent,partner_request"`
	At   time.Time `json:"at"`
	// Referrer names who referred them, Counted their count after.
	Referrer   string `json:"referrer"`
	ReferrerID string `json:"referrerId"`
	Counted    int64  `json:"counted"`
	Milestone  int    `json:"milestone"`
	Reward     string `json:"reward"`
	// Partner names the newsletter a partner request went to.
	Partner string `json:"partner"`
}

ReferralTimelineEvent is a Grow event on a contact's timeline.

type ReferralTopReferrer

type ReferralTopReferrer struct {
	LinkID       string     `json:"linkId"`
	Name         string     `json:"name"`
	Email        string     `json:"email"`
	Counted      int64      `json:"counted"`
	InHold       int64      `json:"inHold"`
	Held         int64      `json:"held"`
	Milestones   []int      `json:"milestones"`
	Unclaimed    string     `json:"unclaimed"`
	LastReferral *time.Time `json:"lastReferral,omitempty"`
}

ReferralTopReferrer is a row of the top referrers.

type ReferralTrack

type ReferralTrack struct {
	Counted   int64                `json:"counted"`
	InHold    int64                `json:"inHold"`
	Awaiting  int64                `json:"awaiting"`
	Held      int64                `json:"held"`
	Points    []ReferralTrackPoint `json:"points"`
	NextHold  *time.Time           `json:"nextHold,omitempty" doc:"When the next referral in hold counts"`
	NextCount int                  `json:"nextCount"`
	NextName  string               `json:"nextName"`
	ToNext    int64                `json:"toNext"`
	// NextBySeq is the referral whose hold brings the next milestone.
	NextBySeq int `json:"nextBySeq"`
}

ReferralTrack is a referrer's progress: counted, counting soon (in hold), waiting for confirmation, and the milestones.

type ReferralTrackPoint

type ReferralTrackPoint struct {
	Count     int        `json:"count"`
	Reward    string     `json:"reward"`
	ReachedAt *time.Time `json:"reachedAt,omitempty"`
}

ReferralTrackPoint is a milestone on a referrer's track.

type ReferralTurnedOn

type ReferralTurnedOn struct {
	Program      ReferralProgramDetail `json:"program"`
	LinksCreated int64                 `json:"linksCreated"`
	// NextIssue is the list's next draft, to add the Referral block to.
	NextIssue *ReferralCampaignRef `json:"nextIssue,omitempty"`
}

ReferralTurnedOn is what turning a program on did.

type ReferralWebhookTestResult

type ReferralWebhookTestResult struct {
	OK     bool   `json:"ok"`
	Status int    `json:"status"`
	Code   string `json:"code"`
	URL    string `json:"url"`
	Error  string `json:"error"`
}

ReferralWebhookTestResult is a webhook reward's test call.

type ReferrerInput

type ReferrerInput struct {
	ProgramInput
	Link string `path:"link" format:"uuid"`
}

ReferrerInput is a referrer's path: their program and link.

type ReferrerParams

type ReferrerParams struct {
	Query     string
	Milestone int // 0 any, -1 none yet, n reached n
	Held      bool
	Paused    bool
	Page      int
	PageSize  int
}

ReferrerParams filters the referrers.

type RewardBlock

type RewardBlock struct {
	Button      string `json:"button" maxLength:"80"`
	Image       bool   `json:"image"`
	Description bool   `json:"description"`
	Expiry      bool   `json:"expiry"`
	Hub         bool   `json:"hub"`
}

RewardBlock is the Reward block's settings (milestone emails).

type RewardInput

type RewardInput struct {
	api.WorkspaceInput
	Reward string `path:"reward" format:"uuid"`
}

RewardInput is a reward's path.

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Box   *secrets.Box
	Log   *slog.Logger
	Now   func() time.Time
	// Links signs the personal links of the hub, downloads and the
	// recommendations page.
	Links *linktoken.Signer
	// Pages are a workspace's public page addresses (its custom domain when
	// verified).
	Pages func(ctx context.Context, ws *store.Workspace) (forms.PageLinks, error)
	// Mail sends system mail: the hub's "Email me my link" (App.Mail, read
	// at call time).
	Mail func() mailer.Sender
	// Emails queues milestone emails on the Automations stream.
	Emails func() MilestoneSender
	// Coupons issues Stripe promotion codes once payments exist (phase 6);
	// nil means Stripe isn't connected.
	Coupons func() Coupons
	// HTTP posts webhook rewards through the SSRF guard.
	HTTP func() *http.Client
	// AllowPrivate lets webhook rewards reach private addresses (tests and
	// development, webhooks.allow_private_networks).
	AllowPrivate func() bool
	// Jobs enqueues River jobs.
	Jobs func() Inserter
	// Base is the instance's public URL (images in emails).
	Base func() string
}

Service is the referrals domain.

func (*Service) CheckBlock

func (s *Service) CheckBlock(ctx context.Context, ws *store.Workspace, html string, byList map[uuid.UUID]int64, total int64) (BlockCheck, error)

CheckBlock reads the Referral block of an email: its program and how many of the recipients it shows to (byList: recipients per list).

func (*Service) CheckTokens

func (s *Service) CheckTokens(ctx context.Context, ws *store.Workspace, html string, byList map[uuid.UUID]int64, total int64) (TokenCheck, error)

CheckTokens finds a referral token outside the Referral block and the recipients it prints nothing for: those who aren't on the program's list, or everyone while the program is off. A token with a fallback (| default: "…") is fine.

func (*Service) Checks

func (s *Service) Checks(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralChecks, error)

Checks are what has to be true before the program turns on.

func (s *Service) ClaimLink(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralClaimLink, error)

ClaimLink returns a coupon reward's claim link to copy; copying it is audited.

func (*Service) Contact

func (s *Service) Contact(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, partners PartnerEvents) (ReferralContact, error)

Contact is Grow on a contact's profile: their link and counts as a referrer, who referred them, and the timeline's events.

func (*Service) Create

Create starts a program on a list: off, at the guide's second step, with the default rules and copy.

func (*Service) CreateMilestone

func (s *Service) CreateMilestone(ctx context.Context, ws *store.Workspace, programID uuid.UUID, in ReferralMilestoneInput) (ReferralMilestoneView, error)

CreateMilestone adds a milestone with its reward and a milestone email that starts from the default (the Reward block, then the Referral block).

func (*Service) Decide

Decide decides on held referrals: count them (what is left of the hold still applies), don't count them, or don't count them and pause the referrer's link. Undo works for 10 seconds, before any reward goes out.

func (*Service) Delete

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

Delete removes a program that is off. Its links stop for good; counted referrals and sent rewards stay in contacts' timelines.

func (*Service) DeleteMilestone

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

DeleteMilestone removes a milestone. Rewards already sent stay with their referrers. A program that is on keeps at least one milestone.

func (*Service) DeliverDue

func (s *Service) DeliverDue(ctx context.Context) (int, error)

DeliverDue sends the rewards the job owes: webhook calls that are due, coupons, and rewards waiting for codes that have arrived since.

func (*Service) Detail

Detail is a program with its settings.

func (*Service) Download

func (s *Service) Download(ctx context.Context, c linktoken.Claims) (*HubDownload, error)

Download resolves a reward's download link and counts it.

func (*Service) DownloadToken

func (s *Service) DownloadToken(wsID, rewardID, contactID uuid.UUID, at time.Time) string

DownloadToken is a reward's expiring download link token: the hub makes a fresh one each time.

func (s *Service) EnsureLinks(ctx context.Context) (int64, error)

EnsureLinks gives the confirmed subscribers of every program that is on a link (subscribers added by an import or the API, which don't confirm through a form), a few thousand at a time.

func (*Service) ExportReferrers

func (s *Service) ExportReferrers(ctx context.Context, ws *store.Workspace, programID uuid.UUID) ([]byte, error)

ExportReferrers writes the referrers list as CSV (subscribers:export, audited).

func (*Service) ExportToFulfill

func (s *Service) ExportToFulfill(ctx context.Context, ws *store.Workspace, programID uuid.UUID) ([]byte, error)

ExportToFulfill writes the "To fulfill" queue as CSV, with the shipping addresses (subscribers:export, audited).

func (*Service) FileChunks

func (s *Service) FileChunks(ctx context.Context, fileID uuid.UUID, write func([]byte) error) error

FileChunks streams a reward file's bytes in order.

func (*Service) FulfillReward

func (s *Service) FulfillReward(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralFulfillInput) error

FulfillReward marks a manual reward sent by hand. Its shipping address is deleted 30 days later.

func (*Service) Hourly

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

Hourly is one pass of the hourly job.

func (*Service) Hub

func (s *Service) Hub(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, token string, ip *netip.Addr) (*HubView, error)

Hub is a reader's hub, opened from their signed link; ip is where they opened it (the same-IP rule).

func (*Service) HubExpired

func (s *Service) HubExpired(c linktoken.Claims) bool

HubExpired reports whether a hub token is past its 60 days.

func (*Service) HubToken

func (s *Service) HubToken(wsID, contactID uuid.UUID, at time.Time) string

HubToken is a reader's hub link token: it opens their hub for 60 days.

func (*Service) Impact

Impact says what a change of the counting rules does to referrals not decided yet.

func (*Service) Invite

func (s *Service) Invite(ctx context.Context, ws *store.Workspace, code string) (*InviteView, error)

Invite is a working link's invite page, or nil: an unknown or paused code, or a program that's off, shows the normal subscribe page.

func (*Service) Leaderboard

func (s *Service) Leaderboard(ctx context.Context, p store.ReferralProgram, period string, me *uuid.UUID) (LeaderboardView, error)

Leaderboard reads a period of a program's leaderboard; me (a hub's link) is the reader's own row, highlighted even outside the top rows.

func (*Service) MaskedEmail

func (s *Service) MaskedEmail(ctx context.Context, contactID uuid.UUID) string

MaskedEmail is a contact's address as the expired hub shows it: "s•••@outlook.com".

func (*Service) MilestoneEmail

func (s *Service) MilestoneEmail(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralMilestoneEmailDetail, error)

MilestoneEmail is a milestone email for the composer.

func (*Service) MilestoneView

func (s *Service) MilestoneView(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralMilestoneView, error)

MilestoneView is one milestone.

func (*Service) Milestones

func (s *Service) Milestones(ctx context.Context, ws *store.Workspace, programID uuid.UUID) (ReferralMilestoneList, error)

Milestones is Referrals › Milestones: the milestones with their rewards, health and emails, the files and the "To fulfill" queue.

func (*Service) PreferenceCardFor

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

PreferenceCardFor returns a contact's card, or nil.

func (*Service) PreviewContacts

func (s *Service) PreviewContacts(ctx context.Context, ws *store.Workspace, program *uuid.UUID) (GrowPreviewContacts, error)

PreviewContacts are the readers to preview Grow blocks as: the program's top referrers, then up to three readers the block hides for (on other lists).

func (*Service) PreviewDecision

func (s *Service) PreviewDecision(ctx context.Context, ws *store.Workspace, programID uuid.UUID, in ReferralDecisionInput) (ReferralDecisionPreview, error)

PreviewDecision says what a decision would do.

func (*Service) PreviewMilestoneEmail

func (s *Service) PreviewMilestoneEmail(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralEmailPreviewInput) (ReferralEmailRender, error)

PreviewMilestoneEmail renders a milestone email as a reader would get it: the contact's own referral and reward, or a sample.

func (*Service) ProcessHolds

func (s *Service) ProcessHolds(ctx context.Context) (int, error)

ProcessHolds counts the referrals whose hold has ended: still subscribed, not hard-bounced or complained (unless "Left during the hold" is off).

func (*Service) ProcessNeverConfirmed

func (s *Service) ProcessNeverConfirmed(ctx context.Context) (int, error)

ProcessNeverConfirmed excludes referrals with no confirmation within 7 days. The usual confirmation reminder still went out after 24 hours.

func (*Service) Programs

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

Programs lists the workspace's programs and the lists they can use.

func (*Service) RecordVisit

func (s *Service) RecordVisit(ctx context.Context, ws *store.Workspace, linkID, programID uuid.UUID, via, method, userAgent string, ip *netip.Addr) error

RecordVisit counts a visit to a link's invite page: once per network and browser a day, without cookies; bots are left out.

func (*Service) Referrer

func (s *Service) Referrer(ctx context.Context, ws *store.Workspace, programID, linkID uuid.UUID) (ReferralReferrerPanel, error)

Referrer is a referrer's panel.

func (*Service) Referrers

func (s *Service) Referrers(ctx context.Context, ws *store.Workspace, programID uuid.UUID, p ReferrerParams) (ReferralReferrerList, error)

Referrers is Referrals › Referrers: everyone whose link brought a signup, by counted referrals.

func (*Service) RefreshLeaderboard

func (s *Service) RefreshLeaderboard(ctx context.Context, programID uuid.UUID) error

RefreshLeaderboard recomputes a program's leaderboard: every referrer with a counted referral, this month and all time, by counted referrals; ties share a rank. The pages show the top rows and a referrer's own rank.

func (*Service) RefreshLeaderboards

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

RefreshLeaderboards recomputes the leaderboard of every program that has it on (the hourly job).

func (*Service) RemoveCodes

func (s *Service) RemoveCodes(ctx context.Context, ws *store.Workspace, milestoneID uuid.UUID) (int64, error)

RemoveCodes removes a code reward's codes nobody has received yet (the count only goes in the audit log).

func (*Service) RemoveFile

func (s *Service) RemoveFile(ctx context.Context, ws *store.Workspace, programID, fileID uuid.UUID) error

RemoveFile takes a file out of the program's files. Rewards already sent keep working until their links expire.

func (*Service) RenderBlock

RenderBlock renders a Referral or Reward block for the canvas, as a reader ("Preview as") or as the sample: a reader with no referrals yet (in a milestone email, one who just reached it).

func (*Service) ResendReward

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

ResendReward sends a reward's milestone email again (a coupon's claim link, a download's fresh link).

func (*Service) Results

func (s *Service) Results(ctx context.Context, ws *store.Workspace, programID uuid.UUID, period, grouping string) (ReferralResults, error)

Results is a program's results for a period.

func (*Service) RetryReward

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

RetryReward tries a failed webhook reward again.

func (*Service) Review

func (s *Service) Review(ctx context.Context, ws *store.Workspace, programID uuid.UUID, signal string, link *uuid.UUID) (ReferralReviewQueue, error)

Review is the review queue: held referrals grouped by referrer, with their evidence and the signals that held them.

func (*Service) Roots

func (s *Service) Roots() []string

Roots implements liquid.RecipientData.

func (*Service) SampleReferral

func (s *Service) SampleReferral(ctx context.Context, ws *store.Workspace, programID uuid.UUID, counted, soon int64) (map[string]any, error)

SampleReferral is referral.* for a preview without a reader ("A reader with no referrals yet").

func (*Service) SaveAddress

func (s *Service) SaveAddress(ctx context.Context, contactID, rewardID uuid.UUID, a ReferralShippingAddress) error

SaveAddress keeps where a manual reward goes (sealed; deleted 30 days after the reward is marked fulfilled).

func (*Service) SaveMilestoneEmail

func (s *Service) SaveMilestoneEmail(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralEmailSave, version bool) (ReferralEmailSaved, error)

SaveMilestoneEmail autosaves a milestone email's draft; version true also makes it the version that goes out.

func (*Service) SaveSetup

SaveSetup keeps the guide's step (and the list, which can change until the program has been on).

func (*Service) SeenReferrer

func (s *Service) SeenReferrer(ctx context.Context, linkID uuid.UUID, ip *netip.Addr)

SeenReferrer records an address a referrer used (their hub), for the "same IP address as the referrer" rule.

func (s *Service) SendHubLink(ctx context.Context, ws *store.Workspace, set *forms.Settings, contactID uuid.UUID) error

SendHubLink emails a reader a fresh link to their hub ("Email me my link"), from the System stream.

func (*Service) SetChoices

func (s *Service) SetChoices(ctx context.Context, linkID uuid.UUID, showName, showBoard bool) error

SetChoices saves a reader's two switches on their hub: their first name on their invite page, their name on the leaderboard.

func (*Service) SetLeaderboard

func (s *Service) SetLeaderboard(ctx context.Context, ws *store.Workspace, id uuid.UUID, on bool) (ReferralProgramDetail, error)

SetLeaderboard turns the public leaderboard on or off.

func (*Service) SetLinkStatus

func (s *Service) SetLinkStatus(ctx context.Context, ws *store.Workspace, programID, linkID uuid.UUID, status, note string) error

SetLinkStatus pauses or resumes a referrer's link. A paused link leads to the normal subscribe page, which doesn't say why.

func (*Service) SetMilestoneEmailOn

func (s *Service) SetMilestoneEmailOn(ctx context.Context, ws *store.Workspace, id uuid.UUID, on bool) error

SetMilestoneEmailOn turns a milestone's email on, or off ("No email, I'll use an automation").

func (*Service) TestMilestoneEmail

func (s *Service) TestMilestoneEmail(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralEmailTest) (ReferralEmailTestResult, error)

TestMilestoneEmail sends a test of a milestone email through the System route ("Send me a test").

func (*Service) TestWebhook

func (s *Service) TestWebhook(ctx context.Context, ws *store.Workspace, milestoneID uuid.UUID) (ReferralWebhookTestResult, error)

TestWebhook posts a sample referral.milestone_reached to a webhook reward's endpoint, signed like the real calls, and shows the answer. It changes neither the reward's health nor any referrer's reward.

func (*Service) Tick

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

Tick is one pass of the minute job.

func (*Service) TurnOff

TurnOff turns a program off: links lead to the normal subscribe page, Referral blocks are hidden and nothing new is attributed. Earned rewards stay available, and counting and rewards for referrals already made go on.

func (*Service) TurnOn

func (s *Service) TurnOn(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralTurnedOn, error)

TurnOn turns a program on: its checks must pass. Every confirmed subscriber of the list gets a link.

func (*Service) UndoDecision

func (s *Service) UndoDecision(ctx context.Context, ws *store.Workspace, programID, decisionID uuid.UUID) error

UndoDecision takes a decision back within 10 seconds, before any reward went out: the referrals wait for review again and a link the decision paused is active again.

func (*Service) UpdateMilestone

UpdateMilestone changes a milestone. Rewards already given stay as they were; changes apply to rewards given from now on.

func (*Service) UpdateSettings

UpdateSettings saves Referrals › Settings. Changes apply going forward: counted referrals and sent rewards never change.

func (*Service) UploadCodes

func (s *Service) UploadCodes(ctx context.Context, ws *store.Workspace, milestoneID uuid.UUID, in ReferralCodesInput) (ReferralCodesResult, error)

UploadCodes adds codes to a code reward. Codes are sealed and only their count goes in the audit log. Rewards waiting for codes go out at once.

func (*Service) UploadFile

func (s *Service) UploadFile(ctx context.Context, ws *store.Workspace, programID uuid.UUID, name string, r io.Reader) (ReferralFile, error)

UploadFile keeps a file for download rewards, in 1 MiB chunks.

func (*Service) Vars

func (s *Service) Vars(ctx context.Context, wsID uuid.UUID, recipients []liquid.Recipient, roots []string) (map[uuid.UUID]map[string]any, error)

Vars implements liquid.RecipientData: each reader's referral.* (their link and progress, when they're on a program's list while it's on) and, in milestone emails, reward.*.

type ShareLink struct {
	Channel string
	URL     string
}

ShareLink is a plain share link of a reader's referral link: no third-party scripts, no trackers.

func ShareLinks(link, message, subject string, buttons []string) []ShareLink

ShareLinks are a reader's share links, each adding its ?via=.

type TickArgs

type TickArgs struct{}

TickArgs is the minute job: holds that ended, referrals never confirmed, rewards to deliver, links for new subscribers and the notifications.

func (TickArgs) InsertOpts

func (TickArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (TickArgs) Kind

func (TickArgs) Kind() string

Kind implements river.JobArgs.

type TickWorker

type TickWorker struct {
	river.WorkerDefaults[TickArgs]
	S *Service
}

TickWorker runs the minute job.

func (*TickWorker) Timeout

func (w *TickWorker) Timeout(*river.Job[TickArgs]) time.Duration

Timeout implements river.Worker.

func (*TickWorker) Work

func (w *TickWorker) Work(ctx context.Context, _ *river.Job[TickArgs]) error

Work implements river.Worker.

type TokenCheck

type TokenCheck struct {
	// Token is the first one without a fallback ("referral.link"); empty
	// when there is none.
	Token string
	// Empty recipients aren't on the program's list (or the program is off,
	// Off; or there is none, None), of Total.
	Empty, Total int64
	ListName     string
	Off, None    bool
}

TokenCheck is a referral token typed outside the Referral block, and how many recipients it would print nothing for (ComposerGrowBlocks: "a check: referral.link is empty for 16,225 recipients who aren't on Weekly Digest").

func (TokenCheck) ReadinessRow

func (c TokenCheck) ReadinessRow(campaignID string) (row ReadinessRow, ok bool)

ReadinessRow is the token check's row; ok is false when there's nothing to say.

type WebhookCall

type WebhookCall struct {
	Status int
	Answer rewardAnswer
	Err    error
}

WebhookCall is one call of a webhook reward's endpoint.

Jump to

Keyboard shortcuts

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