recommendations

package
v1.5.0 Latest Latest
Warning

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

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

Documentation

Overview

Package recommendations implements Grow › Recommendations (design expansion phase 5, M25; brief reputecast-design-addon-grow.md §3.8–3.9): the newsletters a workspace recommends on its opt-in confirmation page, in the Recommendations block and on the hosted recommendations page, its partner profile, and partner links with newsletters on other ReputeCast instances.

A recommendation is a link to any subscribe page (readers subscribe there; clicks are counted) or a partner on another instance: readers press Subscribe on our pages and our server sends the partner a signed subscribe request; the partner runs its own double opt-in and tells us, signed, when the reader confirmed. We keep only the counts, never which reader confirmed. Partner links are set up with a single-use partner code and sign every message with a secret agreed over HTTPS (partnerproto; docs/grow/partners.md).

Changes people make are audited. Subscribe requests are automatic and high volume: the partner request logs (90 days) are their record.

Index

Constants

View Source
const (
	KindLink    = "link"
	KindPartner = "partner"
)

Kinds of recommendation.

View Source
const (
	DirOut = "out"
	DirIn  = "in"
)

Partner link directions: out, we recommend them (we send subscribe requests); in, they recommend us (we receive them).

View Source
const (
	LinkConnected = "connected"
	LinkPaused    = "paused"
	LinkInvalid   = "invalid"
	LinkEnded     = "ended"
)

Partner link statuses.

View Source
const (
	// ConfirmPageMax recommendations show under "While you're here".
	ConfirmPageMax = 3
	// RequestRetryFor: a subscribe request the partner didn't answer is
	// retried with back-off for 24 hours, then marked failed.
	RequestRetryFor = 24 * time.Hour
	// OptInRetryFor: a partner signup's confirmation email waits for a
	// System provider for 3 days, like the forms' confirmations.
	OptInRetryFor = 72 * time.Hour
	// LogKept: the partner request logs keep 90 days.
	LogKept = 90 * 24 * time.Hour
	// PageValid: the personal link to the recommendations page.
	PageValid = 30 * 24 * time.Hour
	// UnreachableAfter: members with grow:connect hear about a partner whose
	// requests have failed this long.
	UnreachableAfter = 30 * time.Minute
)

Timing.

View Source
const (
	// OutcomeAccepted: the partner will email the reader to confirm.
	OutcomeAccepted = "accepted"
	// OutcomePassed: the partner didn't answer yet; the request is retried
	// ("We've passed your request to Ops Weekly…").
	OutcomePassed = "passed"
	// OutcomeLimit: the partner's daily limit is reached.
	OutcomeLimit = "limit"
	// OutcomeUnavailable: the partner link is paused, ended or invalid.
	OutcomeUnavailable = "unavailable"
)

Outcomes of a reader's Subscribe on our pages.

View Source
const OverviewDays = 30

OverviewDays is the overview's period: the last 30 days, today included.

Variables

View Source
var ErrExpired = errors.New("recommendations: the link expired")

ErrExpired: the personal link expired; the page asks for an address.

Functions

func Erasure

func Erasure() erasure.Source

Erasure unlinks signups a partner sent for the contact; the requests stay counted (review 2026-11 DP-1).

func ExpandRecommendations

func ExpandRecommendations(b RecommendationsBlock) string

ExpandRecommendations is the block as Liquid reading recommendations.*.

func HiddenReason

func HiddenReason(state string) i18n.Text

HiddenReason is why a recommendation doesn't show, as a note reads it ("paused by the partner"): a kept message, which Send Readiness writes in each reader's language.

func Register

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

Register adds the recommendation and partner operations.

func RegisterJobs

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

RegisterJobs adds the recommendations' workers and schedules.

func RegisterOverview

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

RegisterOverview adds GET /grow/overview.

Types

type BlockCheck

type BlockCheck struct {
	Present bool
	Shows   int
	Hidden  []BlockHiddenRec
}

BlockCheck is what the Recommendations block of an email shows, for Send Readiness and the composer's checks.

func (BlockCheck) ReadinessRow

func (c BlockCheck) ReadinessRow() ReadinessRow

ReadinessRow is what the block shows, and what it hides and why.

type BlockHiddenRec

type BlockHiddenRec struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Initials string `json:"initials"`
	// State: paused, partner_paused, invalid, limit, ended, or not_in_emails
	// (it shows on the confirmation page only).
	State    string `json:"state"`
	PausedBy string `json:"pausedBy"`
}

BlockHiddenRec is a recommendation the block can't show now.

type BlockOption

type BlockOption struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Initials string `json:"initials"`
	Kind     string `json:"kind" enum:"link,partner"`
	State    string `json:"state"`
	// ShowBlock: it shows in emails (not only on the confirmation page);
	// Hidden: it can't show now (State says why).
	ShowBlock bool `json:"showBlock"`
	Hidden    bool `json:"hidden"`
}

BlockOption is a recommendation the block can show.

type BlockRender

type BlockRender struct {
	HTML string `json:"html"`
	// Shows is how many recommendations it shows; Hidden lists the
	// picked or showing ones that can't show now, with why.
	Shows  int              `json:"shows"`
	Hidden []BlockHiddenRec `json:"hidden"`
	// Settings are the block's effective settings, for the inspector.
	Settings RecommendationsBlock `json:"settings"`
	// Options are the recommendations the inspector picks from, in order;
	// PageURL the hosted page the buttons open ("news.acme.io/recommends").
	Options []BlockOption `json:"options"`
	PageURL string        `json:"pageUrl"`
}

BlockRender is the Recommendations block for the composer's canvas.

type BlockRenderInput

type BlockRenderInput struct {
	Settings json.RawMessage `json:"settings,omitempty"`
}

BlockRenderInput renders the block for the canvas.

type GrowNamedCount

type GrowNamedCount struct {
	Name  string `json:"name"`
	Count int64  `json:"count"`
}

GrowNamedCount is a person and a count ("Alex Moreau (6)").

type GrowNeed

type GrowNeed struct {
	Kind string `` /* 144-byte string literal not displayed */
	// At orders the list: the newest problem first.
	At    time.Time `json:"at"`
	Count int64     `json:"count"`
	// Held: the referrers and how many each; unclaimed: the referrers.
	People []GrowNamedCount `json:"people"`
	// Oldest held referral, or since when a partner link is broken.
	Since *time.Time `json:"since,omitempty"`
	// Partner problems: the newsletter and why.
	Partner string `json:"partner"`
	Reason  string `json:"reason" enum:"signature_rejected,ended,unknown_link,"`
	// Reward problems: the reward and its milestone; codes left; when
	// unclaimed codes expire.
	Reward      string      `json:"reward"`
	Milestone   int         `json:"milestone"`
	MilestoneID string      `json:"milestoneId"`
	CodesLeft   int64       `json:"codesLeft"`
	Expires     []time.Time `json:"expires"`
}

GrowNeed is an item of "Needs you".

type GrowOverview

type GrowOverview struct {
	From      time.Time `json:"from" doc:"The period's first day (workspace time zone)"`
	To        time.Time `json:"to" doc:"Today"`
	UpdatedAt time.Time `json:"updatedAt"`
	// The list the numbers are about: the referral program's, else the
	// partner profile's. Empty without either.
	ListID   string `json:"listId"`
	ListName string `json:"listName"`
	// The referral program (empty without one), its status and start.
	ProgramID     string     `json:"programId"`
	ProgramStatus string     `json:"programStatus" enum:"on,off,"`
	ProgramStart  *time.Time `json:"programStart,omitempty"`
	// Recommends: newsletters this workspace recommends; RecommendedBy:
	// partners that recommend it.
	Recommends    int                      `json:"recommends"`
	RecommendedBy int                      `json:"recommendedBy"`
	Tiles         GrowOverviewTiles        `json:"tiles"`
	NeedsYou      []GrowNeed               `json:"needsYou"`
	Weeks         []GrowWeek               `json:"weeks"`
	Helpers       referrals.GrowHelperSets `json:"helpers"`
}

GrowOverview is Grow › Overview.

type GrowOverviewTiles

type GrowOverviewTiles struct {
	// FromGrow: referred and partner subscribers who confirmed, of the
	// list's NewSubscribers (imports left out).
	FromGrow       int64 `json:"fromGrow"`
	NewSubscribers int64 `json:"newSubscribers"`
	// Referral conversion: Confirmed of Visits.
	Visits     int64   `json:"visits"`
	Confirmed  int64   `json:"confirmed"`
	Conversion float64 `json:"conversion" doc:"Percent"`
	// PartnerSignups confirmed through Partners.
	PartnerSignups int64    `json:"partnerSignups"`
	Partners       []string `json:"partners"`
	// RewardsSent, by reward.
	RewardsSent int64             `json:"rewardsSent"`
	Rewards     []GrowRewardCount `json:"rewards"`
}

GrowOverviewTiles are the numbers at the top.

type GrowRewardCount

type GrowRewardCount struct {
	Milestone int    `json:"milestone"`
	Name      string `json:"name"`
	Count     int64  `json:"count"`
}

GrowRewardCount is how many of a reward went out.

type GrowWeek

type GrowWeek struct {
	Start     time.Time `json:"start"`
	End       time.Time `json:"end"`
	Days      int       `json:"days"`
	Partial   bool      `json:"partial" doc:"The week is still going"`
	Other     int64     `json:"other" doc:"Forms and other sources (imports left out)"`
	Referrals int64     `json:"referrals"`
	Partners  int64     `json:"partners"`
}

GrowWeek is the list's new confirmed subscribers in a week, by source.

type Hook

type Hook struct {
	S func() *Service
}

Hook tells partners when a reader they sent us confirmed (forms.SignupHook): the partner counts it, never learning who.

func (Hook) Accepted

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: the partner requests of the contact on the lists just confirmed queue their signed confirmation.

func (Hook) DoubleOptIn

DoubleOptIn implements forms.SignupHook (partner signups don't come through forms).

type Inserter

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

Inserter enqueues River jobs (the App's client).

type LinkInput

type LinkInput struct {
	api.WorkspaceInput
	Link string `path:"link" format:"uuid"`
}

LinkInput is a partner link's path.

type PartnerCodeCreated

type PartnerCodeCreated struct {
	ID         string    `json:"id"`
	Code       string    `json:"code"`
	URL        string    `json:"url"`
	Label      string    `json:"label"`
	ListName   string    `json:"listName"`
	DailyLimit int       `json:"dailyLimit"`
	CreatedAt  time.Time `json:"createdAt"`
	ExpiresAt  time.Time `json:"expiresAt"`
}

PartnerCodeCreated is a new partner code, shown once.

type PartnerCodeInput

type PartnerCodeInput struct {
	Label      string `json:"label" maxLength:"120"`
	ListID     string `json:"listId" format:"uuid"`
	DailyLimit int    `json:"dailyLimit" minimum:"1" maximum:"100000"`
}

PartnerCodeInput creates a partner code ("Let a newsletter recommend you").

type PartnerCodeItem

type PartnerCodeItem struct {
	ID         string    `json:"id"`
	Label      string    `json:"label"`
	ListName   string    `json:"listName"`
	DailyLimit int       `json:"dailyLimit"`
	CreatedAt  time.Time `json:"createdAt"`
	CreatedBy  string    `json:"createdBy"`
	ExpiresAt  time.Time `json:"expiresAt"`
}

PartnerCodeItem is a partner code not used yet.

type PartnerCodeText

type PartnerCodeText struct {
	Code string `json:"code" maxLength:"500"`
}

PartnerCodeText is a pasted partner code.

type PartnerConnectInput

type PartnerConnectInput struct {
	Code        string `json:"code" maxLength:"500"`
	ShowConfirm bool   `json:"showConfirm"`
	ShowBlock   bool   `json:"showBlock"`
}

PartnerConnectInput connects a partner from its code.

type PartnerLimitInput

type PartnerLimitInput struct {
	DailyLimit int `json:"dailyLimit" minimum:"1" maximum:"100000"`
}

PartnerLimitInput changes the daily limit a partner has for its readers.

type PartnerPreview

type PartnerPreview struct {
	Code        string `json:"code"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Initials    string `json:"initials"`
	LogoURL     string `json:"logoUrl"`
	List        string `json:"list"`
	DailyLimit  int    `json:"dailyLimit"`
	DoubleOptIn bool   `json:"doubleOptIn"`
	Instance    string `json:"instance"`
}

PartnerPreview is a partner's profile before connecting.

type PartnerRequestItem

type PartnerRequestItem struct {
	ID          string     `json:"id"`
	At          time.Time  `json:"at"`
	Status      string     `json:"status" enum:"queued,accepted,limit,failed,rejected,paused"`
	Origin      string     `json:"origin" enum:"confirm,page,partner"`
	Attempts    int        `json:"attempts"`
	LastError   string     `json:"lastError"`
	ConfirmedAt *time.Time `json:"confirmedAt,omitempty"`
}

PartnerRequestItem is one row of a partner request log: no addresses.

type PartnerRequestLog

type PartnerRequestLog struct {
	LinkID    string               `json:"linkId"`
	Partner   string               `json:"partner"`
	Direction string               `json:"direction" enum:"out,in"`
	Items     []PartnerRequestItem `json:"items"`
	Total     int64                `json:"total"`
}

PartnerRequestLog is a partner link's requests of the last 90 days.

type PruneArgs

type PruneArgs struct{}

PruneArgs is the daily job: the partner request logs keep 90 days.

func (PruneArgs) InsertOpts

func (PruneArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (PruneArgs) Kind

func (PruneArgs) Kind() string

Kind implements river.JobArgs.

type PruneWorker

type PruneWorker struct {
	river.WorkerDefaults[PruneArgs]
	S *Service
}

PruneWorker runs PruneArgs.

func (*PruneWorker) Work

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

Work implements river.Worker.

type PublicRec

type PublicRec struct {
	ID          string
	Kind        string
	Name        string
	Description string
	Initials    string
	// LogoURL is the logo on this instance (never the partner's server).
	LogoURL string
	// Host is where Visit goes ("fabrikam.example").
	Host string
	// VisitURL counts the click and sends the reader to the link.
	VisitURL string
	// Outcome after Subscribe: accepted, passed, limit, unavailable.
	Outcome string
}

PublicRec is a recommendation on a public page.

type PublicRecs

type PublicRecs struct {
	// Publisher names the workspace ("Acme"); ListName the reader's list,
	// which subscribing doesn't change.
	Publisher string
	ListName  string
	Items     []PublicRec
	// Token lets the page's Subscribe buttons act for the reader; Email is
	// the address a partner will write to.
	Token string
	Email string
}

PublicRecs are the recommendations a public page shows.

type ReadinessRow

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

ReadinessRow is the Recommendations block's row of Send Readiness. Its texts are kept messages: Send Readiness writes them in each reader's language. Detail is a sentence per hidden recommendation.

type RecBlockUse

type RecBlockUse struct {
	EmailID string `json:"emailId"`
	// Automation names the flow ("Welcome series"), Name the email ("You're in").
	Automation   string `json:"automation"`
	AutomationID string `json:"automationId"`
	Name         string `json:"name"`
}

RecBlockUse is an email with the Recommendations block.

type RecImage

type RecImage struct {
	ID   string `json:"id"`
	URL  string `json:"url"`
	Name string `json:"name"`
}

RecImage is a logo from the media library.

type RecInput

type RecInput struct {
	api.WorkspaceInput
	Recommendation string `path:"recommendation" format:"uuid"`
}

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

type RecLinkInput

type RecLinkInput struct {
	Name        string `json:"name" maxLength:"120"`
	Description string `json:"description" maxLength:"120"`
	LogoID      string `json:"logoId,omitempty" format:"uuid"`
	URL         string `json:"url" maxLength:"2000"`
	ShowConfirm bool   `json:"showConfirm"`
	ShowBlock   bool   `json:"showBlock"`
}

RecLinkInput adds or changes a link recommendation (a partner's only changes where it shows).

type RecListOption

type RecListOption struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Subscribers int64  `json:"subscribers"`
}

RecListOption is a list a partner code can offer.

type RecOrderInput

type RecOrderInput struct {
	IDs []string `json:"ids" maxItems:"100"`
}

RecOrderInput is the recommendations in the order readers see them.

type RecPrefill

type RecPrefill struct {
	URL         string    `json:"url"`
	Name        string    `json:"name"`
	Description string    `json:"description"`
	// Found: the page answered and named itself.
	Found bool `json:"found"`
}

RecPrefill is what a page says about itself (its title, description and image), to start a link recommendation.

type RecPrefillInput

type RecPrefillInput struct {
	URL string `json:"url" maxLength:"2000"`
}

RecPrefillInput asks for a subscribe page's name, description and logo.

type RecProfile

type RecProfile struct {
	Name            string    `json:"name"`
	Description     string    `json:"description"`
	Initials        string    `json:"initials"`
	ListID          string    `json:"listId"`
	ListName        string    `json:"listName"`
	ListSubscribers int64     `json:"listSubscribers"`
	Instance        string    `json:"instance"`
}

RecProfile is the partner profile: what partners see and show.

type RecProfileInput

type RecProfileInput struct {
	Name        string `json:"name" maxLength:"120"`
	Description string `json:"description" maxLength:"120"`
	LogoID      string `json:"logoId,omitempty" format:"uuid"`
	ListID      string `json:"listId" format:"uuid"`
}

RecProfileInput changes the partner profile.

type RecSettingsInput

type RecSettingsInput struct {
	ConfirmPage bool `json:"confirmPage"`
}

RecSettingsInput is where recommendations show: the confirmation page.

type RecommendationItem

type RecommendationItem struct {
	ID          string    `json:"id"`
	Kind        string    `json:"kind" enum:"link,partner"`
	Name        string    `json:"name"`
	Description string    `json:"description"`
	Initials    string    `json:"initials"`
	// URL is a link's subscribe page; Host what a member recognizes
	// ("fabrikam.example/newsletter", "reputecast.opsweekly.example").
	URL         string `json:"url"`
	Host        string `json:"host"`
	ShowConfirm bool   `json:"showConfirm"`
	ShowBlock   bool   `json:"showBlock"`
	Position    int    `json:"position"`
	// State: a link shows or is paused; a partner is connected, paused by
	// us or by them, invalid (signature rejected or ended by them), at its
	// daily limit, or unreachable (requests failing, still shown).
	State  string `json:"state" enum:"showing,paused,connected,partner_paused,invalid,limit,unreachable,ended"`
	Hidden bool   `json:"hidden"`
	// Since: connected, paused, invalid or failing since.
	Since         *time.Time `json:"since,omitempty"`
	PausedBy      string     `json:"pausedBy"`
	InvalidReason string     `json:"invalidReason" enum:"signature_rejected,ended,unknown_link,"`
	LimitUntil    *time.Time `json:"limitUntil,omitempty"`
	// Today and DailyLimit: partner requests accepted today (UTC) of the
	// partner's limit for our readers.
	Today      int64 `json:"today"`
	DailyLimit int   `json:"dailyLimit"`
	// Waiting requests are retried (an unreachable partner).
	Waiting     int64      `json:"waiting"`
	LinkID      string     `json:"linkId"`
	ConnectedAt *time.Time `json:"connectedAt,omitempty"`
	ConnectedBy string     `json:"connectedBy"`
	// Numbers for the last 30 days.
	Shown        int64 `json:"shown"`
	ShownConfirm int64 `json:"shownConfirm"`
	ShownEmail   int64 `json:"shownEmail"`
	Clicks       int64 `json:"clicks"`
	Requests     int64 `json:"requests"`
	Confirmed    int64 `json:"confirmed"`
}

RecommendationItem is a row of "You recommend".

type RecommendationsBlock

type RecommendationsBlock struct {
	// Which: all that can show, or only the picked ones (IDs).
	Which   string   `json:"which" enum:"all,pick"`
	IDs     []string `json:"ids" maxItems:"20"`
	Layout  string   `json:"layout" enum:"stacked,columns,compact"`
	Heading string   `json:"heading" maxLength:"120"`
	Intro   string   `json:"intro" maxLength:"300"`
}

RecommendationsBlock is the block's settings.

func DefaultBlock

func DefaultBlock() RecommendationsBlock

DefaultBlock is a new Recommendations block.

type RecommendationsView

type RecommendationsView struct {
	Items           []RecommendationItem  `json:"items"`
	RecommendingYou []RecommendingYouItem `json:"recommendingYou"`
	Codes           []PartnerCodeItem     `json:"codes"`
	// ConfirmPage is the confirmation page's switch; ConfirmShows the
	// names it shows now (up to 3).
	ConfirmPage  bool          `json:"confirmPage"`
	ConfirmShows []string      `json:"confirmShows"`
	Blocks       []RecBlockUse `json:"blocks"`
	// BlockShows is how many recommendations the block shows now.
	BlockShows int                      `json:"blockShows"`
	PageURL    string                   `json:"pageUrl"`
	Profile    RecProfile               `json:"profile"`
	Lists      []RecListOption          `json:"lists"`
	Helpers    referrals.GrowHelperSets `json:"helpers"`
}

RecommendationsView is Grow › Recommendations.

type RecommendingYouItem

type RecommendingYouItem struct {
	LinkID      string    `json:"linkId"`
	Name        string    `json:"name"`
	Instance    string    `json:"instance"`
	Label       string    `json:"label"`
	ListName    string    `json:"listName"`
	Since       time.Time `json:"since"`
	ConnectedBy string    `json:"connectedBy"`
	// Requests and Confirmed in the last 30 days; Today since 00:00 UTC.
	Requests   int64      `json:"requests"`
	Confirmed  int64      `json:"confirmed"`
	Today      int64      `json:"today"`
	DailyLimit int        `json:"dailyLimit"`
	State      string     `json:"state" enum:"connected,paused,partner_paused,invalid"`
	PausedBy   string     `json:"pausedBy"`
	PausedAt   *time.Time `json:"pausedAt,omitempty"`
}

RecommendingYouItem is a partner that recommends this workspace.

type SendArgs

type SendArgs struct{}

SendArgs is the minute job, and the kick after a partner request arrives: subscribe requests to send or retry, partner signups' confirmation emails, confirmations to tell partners, daily limits that reset, and partners that can't be reached.

func (SendArgs) InsertOpts

func (SendArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (SendArgs) Kind

func (SendArgs) Kind() string

Kind implements river.JobArgs.

type SendWorker

type SendWorker struct {
	river.WorkerDefaults[SendArgs]
	S *Service
}

SendWorker runs SendArgs.

func (*SendWorker) Timeout

func (w *SendWorker) Timeout(*river.Job[SendArgs]) time.Duration

Timeout implements river.Worker.

func (*SendWorker) Work

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

Work implements river.Worker.

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 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)
	// Instance is this instance's public base URL: partners call it back.
	Instance func() string
	// AllowPrivate lets partner instances and link pages resolve to private
	// and loopback addresses (development and tests; providers.allow_private_networks).
	AllowPrivate func() bool
	// HTTP overrides the client of outbound calls (tests).
	HTTP func() *http.Client
	// Audience adds partner signups (double opt-in) on the partner side.
	Audience *audience.Service
	// Forms builds the confirmation link and the publisher's branding.
	Forms *forms.Service
	// Mail sends the partner signups' confirmation emails on the System
	// stream (App.Mail, read at call time).
	Mail func() mailer.Sender
	// Media keeps the logos fetched from pages and partners.
	Media *media.Service
	// Jobs enqueues River jobs (a request to send now).
	Jobs func() Inserter
	// Referrals reads the referral program for Grow's overview (nil: the
	// overview leaves out the milestones' problems).
	Referrals func() *referrals.Service
}

Service is the recommendations domain.

AddLink adds a link recommendation, last in the order.

func (*Service) CheckAgain

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

CheckAgain retries a partner's waiting requests now ("Check again").

func (*Service) CheckBlock

func (s *Service) CheckBlock(ctx context.Context, ws *store.Workspace, html string) (BlockCheck, error)

CheckBlock reads the Recommendations block of an email.

func (*Service) ConfirmSection

func (s *Service) ConfirmSection(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, count bool) (*PublicRecs, error)

ConfirmSection is "While you're here" on the opt-in confirmation page: up to 3 recommendations, counted as shown. Nil when it's off or nothing can show.

func (*Service) ConnectPartner

ConnectPartner uses a partner code: the two instances agree a signing secret over HTTPS, and the partner joins "You recommend".

func (*Service) ContactEvents

func (s *Service) ContactEvents(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) ([]referrals.ReferralTimelineEvent, error)

ContactEvents implements referrals.PartnerEvents: on a contact's timeline, the partner requests that brought them ("Asked to subscribe on the Acme Weekly Digest's page"). The recommending side keeps no contact for its requests, so only the partner side has these events.

func (*Service) CreateCode

CreateCode creates a single-use partner code valid 7 days. Only its hash is kept: the code is shown this once.

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

EndLink ends a partner link for good: requests stop, both sides drop it from their lists, and reconnecting needs a new partner code.

func (*Service) Item

Item is one recommendation as the tab shows it.

func (*Service) MessageEvent

func (s *Service) MessageEvent(ctx context.Context, tx pgx.Tx, _ store.Provider, messageID uuid.UUID, _ string, ev providers.Event) error

MessageEvent counts a delivered message's recommendations as shown in emails (an ingest message hook).

func (*Service) Overview

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

Overview computes Grow › Overview.

func (*Service) Page

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

Page is the hosted recommendations page: the recommendations the block shows, for a reader (contactID) or for an address they type (uuid.Nil).

func (*Service) PageToken

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

PageToken is the reader's signed link to the recommendations page.

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

PauseLink pauses or resumes a partner link from this side: requests stop (and the recommendation hides) until it resumes. The partner is told over the signed channel; if it can't be reached now, the change still holds here.

func (*Service) Prefill

func (s *Service) Prefill(ctx context.Context, ws *store.Workspace, in RecPrefillInput) (RecPrefill, error)

Prefill reads a subscribe page's name, description and logo, through the SSRF guard ("Filled in the name, description and logo from this page").

func (*Service) PreviewPartner

func (s *Service) PreviewPartner(ctx context.Context, ws *store.Workspace, raw string) (PartnerPreview, error)

PreviewPartner asks the partner's instance what a pasted code connects to.

func (*Service) Prune

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

Prune is one pass of the daily job.

func (*Service) Reader

func (s *Service) Reader(ws *store.Workspace, token string) (uuid.UUID, error)

Reader reads a recommendations page token: the reader, or ErrExpired.

func (*Service) Remove

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

Remove takes a link recommendation off every page; its numbers stay in the results. A partner is removed with its partner link (EndPartner).

func (*Service) RenderBlock

func (s *Service) RenderBlock(ctx context.Context, ws *store.Workspace, in BlockRenderInput) (BlockRender, error)

RenderBlock renders the block for the canvas with what can show now.

func (*Service) Reorder

func (s *Service) Reorder(ctx context.Context, ws *store.Workspace, in RecOrderInput) error

Reorder puts the recommendations in a new order.

func (*Service) RequestLog

func (s *Service) RequestLog(ctx context.Context, ws *store.Workspace, linkID uuid.UUID, page int) (PartnerRequestLog, error)

RequestLog is a partner link's request log, newest first.

func (*Service) RequestSubscribe

func (s *Service) RequestSubscribe(ctx context.Context, ws *store.Workspace, recID uuid.UUID, email, origin string) (string, error)

RequestSubscribe sends a reader's Subscribe to a partner: a signed request with only the address and our newsletter's name. It tries at once and, when the partner doesn't answer, keeps retrying for 24 hours.

func (*Service) RevokeCode

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

RevokeCode revokes a partner code nobody has used yet.

func (*Service) Roots

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

Roots implements liquid.RecipientData.

func (*Service) RotateSecret

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

RotateSecret agrees a new signing secret with the partner over the signed channel. Both secrets work for 24 hours.

func (*Service) Routes

func (s *Service) Routes(r chi.Router)

Routes mounts the partner endpoints on the public router.

func (*Service) SendDue

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

SendDue sends the subscribe requests whose next attempt is due.

func (*Service) SendNotices

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

SendNotices sends the partners' signed confirmations, retried for 24 hours.

func (*Service) SendOptIns

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

SendOptIns sends the confirmation emails of partner signups on the System stream: our usual double opt-in email with "You asked for this on the Acme Weekly Digest's page."

func (*Service) ServeCodePage

func (s *Service) ServeCodePage(w http.ResponseWriter, _ *http.Request)

ServeCodePage answers a partner code opened in a browser: it's meant to be pasted in another ReputeCast, not visited.

func (*Service) SetConfirmPage

func (s *Service) SetConfirmPage(ctx context.Context, ws *store.Workspace, on bool) error

SetConfirmPage turns the confirmation page's "While you're here" on or off.

func (*Service) SetLimit

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

SetLimit changes the daily limit of a partner recommending this workspace, and tells the partner.

func (*Service) SetPaused

func (s *Service) SetPaused(ctx context.Context, ws *store.Workspace, id uuid.UUID, paused bool) (RecommendationItem, error)

SetPaused pauses or resumes a link recommendation. A partner is paused with its partner link (PausePartner).

func (*Service) Subscribe

func (s *Service) Subscribe(ctx context.Context, ws *store.Workspace, recID uuid.UUID, contactID uuid.UUID, email, origin string) (string, error)

Subscribe is a reader's Subscribe on a public page: for the reader of a token, or an address they typed when their link expired.

func (*Service) Tick

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

Tick is one pass of the minute job.

func (*Service) Update

Update changes a recommendation: a link's name, description, logo, address and where it shows; a partner's where it shows.

func (*Service) UpdateProfile

func (s *Service) UpdateProfile(ctx context.Context, ws *store.Workspace, in RecProfileInput) (RecProfile, error)

UpdateProfile changes what partners see and show; partners that recommend this workspace get the new profile over the signed channel.

func (*Service) Vars

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

Vars implements liquid.RecipientData: recommendations.items, the recommendations the block can show now, each linking to the reader's recommendations page. A send records which ones each message showed: they count as shown once the message is delivered.

func (*Service) View

View is Grow › Recommendations: what this workspace recommends, who recommends it, where recommendations show and the partner profile.

func (*Service) Visit

func (s *Service) Visit(ctx context.Context, ws *store.Workspace, id uuid.UUID) (string, bool)

Visit counts a click on a link recommendation and returns where it goes.

Directories

Path Synopsis
Package partnerproto is the partner-link protocol between two ReputeCast instances (grow brief §3.9, docs/grow/partners.md): the messages, how they're signed and checked, partner codes, and how the two sides agree a signing secret without sending it.
Package partnerproto is the partner-link protocol between two ReputeCast instances (grow brief §3.9, docs/grow/partners.md): the messages, how they're signed and checked, partner codes, and how the two sides agree a signing secret without sending it.

Jump to

Keyboard shortcuts

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