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
- Variables
- func ChannelOf(via string) string
- func CodeOf(page string) (code, via string)
- func DefaultMilestoneEmail(programID uuid.UUID, list, reward, rewardType string) (subject, preheader, src string)
- func Erasure() erasure.Source
- func ExpandReferral(b ReferralBlock) string
- func ExpandReward(b RewardBlock) string
- func ExpiredLink(c linktoken.Claims, valid time.Duration, now time.Time) bool
- func GrowHelpers(ctx context.Context, q *store.Queries, wsID uuid.UUID, perm authz.Permission) []string
- func IsBot(method, userAgent string) bool
- func NetworkOf(ip netip.Addr) string
- func NewCode() string
- func NormalizeCode(s string) (string, bool)
- func NumberedKey(email string) string
- func Register(h huma.API, s *Service)
- func RegisterContact(h huma.API, s *Service, partners func() PartnerEvents)
- func RegisterJobs(reg *jobs.Registry, s *Service)
- func SameMailbox(a, b string) bool
- type BlockCheck
- type CouponOffer
- type CouponStatus
- type Coupons
- type GrowBlockRender
- type GrowBlockRenderInput
- type GrowHelperSets
- type GrowPreviewContact
- type GrowPreviewContacts
- type Hook
- func (h Hook) Accepted(ctx context.Context, tx pgx.Tx, ws *store.Workspace, e forms.SignupEvent) error
- func (h Hook) Confirmed(ctx context.Context, tx pgx.Tx, ws *store.Workspace, e forms.ConfirmEvent) error
- func (h Hook) DoubleOptIn(ctx context.Context, ws *store.Workspace, sub forms.Submission) bool
- type HourlyArgs
- type HourlyWorker
- type HubDownload
- type HubReferral
- type HubReward
- type HubView
- type Inserter
- type InviteView
- type IssuedCoupon
- type LeaderboardRow
- type LeaderboardView
- type MilestoneInput
- type MilestoneSender
- type PartnerEvents
- type PreferenceCard
- type ProgramInput
- type ReadinessLink
- type ReadinessRow
- type ReferralBlock
- type ReferralBlockTexts
- type ReferralBucket
- type ReferralCSV
- type ReferralCampaignRef
- type ReferralChannel
- type ReferralCheck
- type ReferralCheckFile
- type ReferralChecks
- type ReferralClaimLink
- type ReferralCodesInput
- type ReferralCodesResult
- type ReferralContact
- type ReferralContactReferredBy
- type ReferralContactReferrer
- type ReferralContactReward
- type ReferralCounting
- type ReferralCouponOffer
- type ReferralCreateInput
- type ReferralDecision
- type ReferralDecisionInput
- type ReferralDecisionPreview
- type ReferralEmailOnInput
- type ReferralEmailPreviewInput
- type ReferralEmailRender
- type ReferralEmailSave
- type ReferralEmailSaved
- type ReferralEmailSettings
- type ReferralEmailTest
- type ReferralEmailTestResult
- type ReferralEmailVersion
- type ReferralEngagement
- type ReferralFile
- type ReferralFilterOption
- type ReferralFulfillInput
- type ReferralFulfillItem
- type ReferralFunnel
- type ReferralHeldItem
- type ReferralImage
- type ReferralItem
- type ReferralLeaderboardInput
- type ReferralLeaderboardSettings
- type ReferralLinkPauseInput
- type ReferralListOption
- type ReferralMilestoneCnt
- type ReferralMilestoneEmail
- type ReferralMilestoneEmailDetail
- type ReferralMilestoneHealth
- type ReferralMilestoneInput
- type ReferralMilestoneList
- type ReferralMilestoneStats
- type ReferralMilestoneView
- type ReferralNetwork
- type ReferralPageSettings
- type ReferralPerson
- type ReferralProgramDetail
- type ReferralProgramList
- type ReferralProgramSummary
- type ReferralQuality
- type ReferralQualityLine
- type ReferralReasonCount
- type ReferralReferrerList
- type ReferralReferrerPanel
- type ReferralReferrerRow
- type ReferralRemoved
- type ReferralResults
- type ReferralReviewGroup
- type ReferralReviewQueue
- type ReferralRewardItem
- type ReferralRewardRow
- type ReferralRule
- type ReferralSenderOption
- type ReferralSettingsImpact
- type ReferralSettingsInput
- type ReferralSetupInput
- type ReferralShippingAddress
- type ReferralSignal
- type ReferralSignalCount
- type ReferralStripe
- type ReferralTimelineEvent
- type ReferralTopReferrer
- type ReferralTrack
- type ReferralTrackPoint
- type ReferralTurnedOn
- type ReferralWebhookTestResult
- type ReferrerInput
- type ReferrerParams
- type RewardBlock
- type RewardInput
- type Service
- func (s *Service) CheckBlock(ctx context.Context, ws *store.Workspace, html string, ...) (BlockCheck, error)
- func (s *Service) CheckTokens(ctx context.Context, ws *store.Workspace, html string, ...) (TokenCheck, error)
- func (s *Service) Checks(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralChecks, error)
- func (s *Service) ClaimLink(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralClaimLink, error)
- func (s *Service) Contact(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, ...) (ReferralContact, error)
- func (s *Service) Create(ctx context.Context, ws *store.Workspace, in ReferralCreateInput) (ReferralProgramDetail, error)
- func (s *Service) CreateMilestone(ctx context.Context, ws *store.Workspace, programID uuid.UUID, ...) (ReferralMilestoneView, error)
- func (s *Service) Decide(ctx context.Context, ws *store.Workspace, programID uuid.UUID, ...) (ReferralDecision, error)
- func (s *Service) Delete(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) DeleteMilestone(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) DeliverDue(ctx context.Context) (int, error)
- func (s *Service) Detail(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralProgramDetail, error)
- func (s *Service) Download(ctx context.Context, c linktoken.Claims) (*HubDownload, error)
- func (s *Service) DownloadToken(wsID, rewardID, contactID uuid.UUID, at time.Time) string
- func (s *Service) EnsureLinks(ctx context.Context) (int64, error)
- func (s *Service) ExportReferrers(ctx context.Context, ws *store.Workspace, programID uuid.UUID) ([]byte, error)
- func (s *Service) ExportToFulfill(ctx context.Context, ws *store.Workspace, programID uuid.UUID) ([]byte, error)
- func (s *Service) FileChunks(ctx context.Context, fileID uuid.UUID, write func([]byte) error) error
- func (s *Service) FulfillReward(ctx context.Context, ws *store.Workspace, id uuid.UUID, ...) error
- func (s *Service) Hourly(ctx context.Context) error
- func (s *Service) Hub(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, token string, ...) (*HubView, error)
- func (s *Service) HubExpired(c linktoken.Claims) bool
- func (s *Service) HubToken(wsID, contactID uuid.UUID, at time.Time) string
- func (s *Service) Impact(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralCounting) (ReferralSettingsImpact, error)
- func (s *Service) Invite(ctx context.Context, ws *store.Workspace, code string) (*InviteView, error)
- func (s *Service) Leaderboard(ctx context.Context, p store.ReferralProgram, period string, me *uuid.UUID) (LeaderboardView, error)
- func (s *Service) MaskedEmail(ctx context.Context, contactID uuid.UUID) string
- func (s *Service) MilestoneEmail(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralMilestoneEmailDetail, error)
- func (s *Service) MilestoneView(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralMilestoneView, error)
- func (s *Service) Milestones(ctx context.Context, ws *store.Workspace, programID uuid.UUID) (ReferralMilestoneList, error)
- func (s *Service) PreferenceCardFor(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (*PreferenceCard, error)
- func (s *Service) PreviewContacts(ctx context.Context, ws *store.Workspace, program *uuid.UUID) (GrowPreviewContacts, error)
- func (s *Service) PreviewDecision(ctx context.Context, ws *store.Workspace, programID uuid.UUID, ...) (ReferralDecisionPreview, error)
- func (s *Service) PreviewMilestoneEmail(ctx context.Context, ws *store.Workspace, id uuid.UUID, ...) (ReferralEmailRender, error)
- func (s *Service) ProcessHolds(ctx context.Context) (int, error)
- func (s *Service) ProcessNeverConfirmed(ctx context.Context) (int, error)
- func (s *Service) Programs(ctx context.Context, ws *store.Workspace) (ReferralProgramList, error)
- func (s *Service) RecordVisit(ctx context.Context, ws *store.Workspace, linkID, programID uuid.UUID, ...) error
- func (s *Service) Referrer(ctx context.Context, ws *store.Workspace, programID, linkID uuid.UUID) (ReferralReferrerPanel, error)
- func (s *Service) Referrers(ctx context.Context, ws *store.Workspace, programID uuid.UUID, ...) (ReferralReferrerList, error)
- func (s *Service) RefreshLeaderboard(ctx context.Context, programID uuid.UUID) error
- func (s *Service) RefreshLeaderboards(ctx context.Context) error
- func (s *Service) RemoveCodes(ctx context.Context, ws *store.Workspace, milestoneID uuid.UUID) (int64, error)
- func (s *Service) RemoveFile(ctx context.Context, ws *store.Workspace, programID, fileID uuid.UUID) error
- func (s *Service) RenderBlock(ctx context.Context, ws *store.Workspace, in GrowBlockRenderInput) (GrowBlockRender, error)
- func (s *Service) ResendReward(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) Results(ctx context.Context, ws *store.Workspace, programID uuid.UUID, ...) (ReferralResults, error)
- func (s *Service) RetryReward(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) Review(ctx context.Context, ws *store.Workspace, programID uuid.UUID, signal string, ...) (ReferralReviewQueue, error)
- func (s *Service) Roots() []string
- func (s *Service) SampleReferral(ctx context.Context, ws *store.Workspace, programID uuid.UUID, ...) (map[string]any, error)
- func (s *Service) SaveAddress(ctx context.Context, contactID, rewardID uuid.UUID, a ReferralShippingAddress) error
- func (s *Service) SaveMilestoneEmail(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralEmailSave, ...) (ReferralEmailSaved, error)
- func (s *Service) SaveSetup(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralSetupInput) (ReferralProgramDetail, error)
- func (s *Service) SeenReferrer(ctx context.Context, linkID uuid.UUID, ip *netip.Addr)
- func (s *Service) SendHubLink(ctx context.Context, ws *store.Workspace, set *forms.Settings, ...) error
- func (s *Service) SetChoices(ctx context.Context, linkID uuid.UUID, showName, showBoard bool) error
- func (s *Service) SetLeaderboard(ctx context.Context, ws *store.Workspace, id uuid.UUID, on bool) (ReferralProgramDetail, error)
- func (s *Service) SetLinkStatus(ctx context.Context, ws *store.Workspace, programID, linkID uuid.UUID, ...) error
- func (s *Service) SetMilestoneEmailOn(ctx context.Context, ws *store.Workspace, id uuid.UUID, on bool) error
- func (s *Service) TestMilestoneEmail(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralEmailTest) (ReferralEmailTestResult, error)
- func (s *Service) TestWebhook(ctx context.Context, ws *store.Workspace, milestoneID uuid.UUID) (ReferralWebhookTestResult, error)
- func (s *Service) Tick(ctx context.Context) error
- func (s *Service) TurnOff(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralProgramDetail, error)
- func (s *Service) TurnOn(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralTurnedOn, error)
- func (s *Service) UndoDecision(ctx context.Context, ws *store.Workspace, programID, decisionID uuid.UUID) error
- func (s *Service) UpdateMilestone(ctx context.Context, ws *store.Workspace, id uuid.UUID, ...) (ReferralMilestoneView, error)
- func (s *Service) UpdateSettings(ctx context.Context, ws *store.Workspace, id uuid.UUID, ...) (ReferralProgramDetail, error)
- func (s *Service) UploadCodes(ctx context.Context, ws *store.Workspace, milestoneID uuid.UUID, ...) (ReferralCodesResult, error)
- func (s *Service) UploadFile(ctx context.Context, ws *store.Workspace, programID uuid.UUID, name string, ...) (ReferralFile, error)
- func (s *Service) Vars(ctx context.Context, wsID uuid.UUID, recipients []liquid.Recipient, ...) (map[uuid.UUID]map[string]any, error)
- type ShareLink
- type TickArgs
- type TickWorker
- type TokenCheck
- type WebhookCall
Constants ¶
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).
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.
const ( PeriodMonth = "month" PeriodAll = "all" )
Leaderboard periods.
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.
const ( ReasonSelf = "self" ReasonSameIP = "same_ip" ReasonDisposable = "disposable" ReasonLeft = "left" ReasonAlready = "already" ReasonNeverConfirmed = "never_confirmed" ReasonReviewer = "reviewer" )
Reasons a referral isn't counted.
const ( SignalBurst = "burst" SignalNumbered = "numbered" )
Suspicion signals that hold a referral for review.
const ( RewardDownload = "download" RewardCodes = "codes" RewardManual = "manual" RewardCoupon = "coupon" RewardWebhook = "webhook" )
Reward types.
const ( RewardPending = "pending" RewardSent = "sent" RewardWaitingCodes = "waiting_codes" RewardToFulfill = "to_fulfill" RewardFulfilled = "fulfilled" RewardFailed = "failed" RewardExpired = "expired" )
Reward statuses.
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.
const ( Period7 = "7d" Period30 = "30d" PeriodAll2 = "all" )
Periods of the results.
const ( DecisionCount = "count" DecisionDont = "dont" DecisionDontPause = "dont_pause" )
Review decisions.
const ( ViaCopy = "copy" ViaEmail = "email" ViaX = "x" ViaLinkedIn = "linkedin" ViaWhatsApp = "whatsapp" ViaOther = "other" )
Channels where links are shared, as share buttons add them (?via=).
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.
const CodeLength = 6
CodeLength is the length of a referral code ("K7Q2MX").
const MaxFileBytes = 100 << 20
MaxFileBytes: download rewards are up to 100 MB.
const MinConfirmedForResults = 20
MinConfirmedForResults: results show after 20 confirmed referrals.
const MinForQuality = 100
MinForQuality: below 100 referred subscribers the quality card waits.
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 ¶
var Channels = []string{ViaCopy, ViaX, ViaLinkedIn, ViaWhatsApp, ViaEmail, ViaOther}
Channels in the order results list them.
var ErrLinkExpired = errors.New("referrals: the link has expired")
ErrLinkExpired: a personal link is past its date.
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 CodeOf ¶
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 ¶
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 ¶
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 NetworkOf ¶
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 NormalizeCode ¶
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 ¶
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 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 ¶
RegisterJobs adds the referrals' workers and schedules.
func SameMailbox ¶
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 ¶
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.
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
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 ¶
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 ¶
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"`
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 ¶
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 ¶
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"`
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 ¶
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.
}
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 ¶
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 (*Service) ClaimLink ¶
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 ¶
func (s *Service) Create(ctx context.Context, ws *store.Workspace, in ReferralCreateInput) (ReferralProgramDetail, error)
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 ¶
func (s *Service) Decide(ctx context.Context, ws *store.Workspace, programID uuid.UUID, in ReferralDecisionInput) (ReferralDecision, error)
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 ¶
Delete removes a program that is off. Its links stop for good; counted referrals and sent rewards stay in contacts' timelines.
func (*Service) DeleteMilestone ¶
DeleteMilestone removes a milestone. Rewards already sent stay with their referrers. A program that is on keeps at least one milestone.
func (*Service) DeliverDue ¶
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 ¶
func (s *Service) Detail(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralProgramDetail, error)
Detail is a program with its settings.
func (*Service) DownloadToken ¶
DownloadToken is a reward's expiring download link token: the hub makes a fresh one each time.
func (*Service) EnsureLinks ¶
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 ¶
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) 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 ¶
HubExpired reports whether a hub token is past its 60 days.
func (*Service) Impact ¶
func (s *Service) Impact(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralCounting) (ReferralSettingsImpact, error)
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 ¶
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 ¶
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 ¶
ProcessNeverConfirmed excludes referrals with no confirmation within 7 days. The usual confirmation reminder still went out after 24 hours.
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 ¶
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 ¶
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 ¶
func (s *Service) RenderBlock(ctx context.Context, ws *store.Workspace, in GrowBlockRenderInput) (GrowBlockRender, error)
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 ¶
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 ¶
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) 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 ¶
func (s *Service) SaveSetup(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralSetupInput) (ReferralProgramDetail, error)
SaveSetup keeps the guide's step (and the list, which can change until the program has been on).
func (*Service) SeenReferrer ¶
SeenReferrer records an address a referrer used (their hub), for the "same IP address as the referrer" rule.
func (*Service) SendHubLink ¶
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 ¶
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) TurnOff ¶
func (s *Service) TurnOff(ctx context.Context, ws *store.Workspace, id uuid.UUID) (ReferralProgramDetail, error)
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 ¶
func (s *Service) UpdateMilestone(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralMilestoneInput) (ReferralMilestoneView, error)
UpdateMilestone changes a milestone. Rewards already given stay as they were; changes apply to rewards given from now on.
func (*Service) UpdateSettings ¶
func (s *Service) UpdateSettings(ctx context.Context, ws *store.Workspace, id uuid.UUID, in ReferralSettingsInput) (ReferralProgramDetail, error)
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 ¶
type ShareLink struct {
}
ShareLink is a plain share link of a reader's referral link: no third-party scripts, no trackers.
func ShareLinks ¶
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.
type TickWorker ¶
type TickWorker struct {
river.WorkerDefaults[TickArgs]
S *Service
}
TickWorker runs the minute job.
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 ¶
WebhookCall is one call of a webhook reward's endpoint.