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
- Variables
- func Erasure() erasure.Source
- func ExpandRecommendations(b RecommendationsBlock) string
- func HiddenReason(state string) i18n.Text
- func Register(h huma.API, s *Service)
- func RegisterJobs(reg *jobs.Registry, s *Service)
- func RegisterOverview(h huma.API, s *Service)
- type BlockCheck
- type BlockHiddenRec
- type BlockOption
- type BlockRender
- type BlockRenderInput
- type GrowNamedCount
- type GrowNeed
- type GrowOverview
- type GrowOverviewTiles
- type GrowRewardCount
- type GrowWeek
- type Hook
- type Inserter
- type LinkInput
- type PartnerCodeCreated
- type PartnerCodeInput
- type PartnerCodeItem
- type PartnerCodeText
- type PartnerConnectInput
- type PartnerLimitInput
- type PartnerPreview
- type PartnerRequestItem
- type PartnerRequestLog
- type PruneArgs
- type PruneWorker
- type PublicRec
- type PublicRecs
- type ReadinessRow
- type RecBlockUse
- type RecImage
- type RecInput
- type RecLinkInput
- type RecListOption
- type RecOrderInput
- type RecPrefill
- type RecPrefillInput
- type RecProfile
- type RecProfileInput
- type RecSettingsInput
- type RecommendationItem
- type RecommendationsBlock
- type RecommendationsView
- type RecommendingYouItem
- type SendArgs
- type SendWorker
- type Service
- func (s *Service) AddLink(ctx context.Context, ws *store.Workspace, in RecLinkInput) (RecommendationItem, error)
- func (s *Service) CheckAgain(ctx context.Context, ws *store.Workspace, id uuid.UUID) (RecommendationItem, error)
- func (s *Service) CheckBlock(ctx context.Context, ws *store.Workspace, html string) (BlockCheck, error)
- func (s *Service) ConfirmSection(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, count bool) (*PublicRecs, error)
- func (s *Service) ConnectPartner(ctx context.Context, ws *store.Workspace, in PartnerConnectInput) (RecommendationItem, error)
- func (s *Service) ContactEvents(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) ([]referrals.ReferralTimelineEvent, error)
- func (s *Service) CreateCode(ctx context.Context, ws *store.Workspace, in PartnerCodeInput) (PartnerCodeCreated, error)
- func (s *Service) EndLink(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) Item(ctx context.Context, ws *store.Workspace, id uuid.UUID) (RecommendationItem, error)
- func (s *Service) MessageEvent(ctx context.Context, tx pgx.Tx, _ store.Provider, messageID uuid.UUID, ...) error
- func (s *Service) Overview(ctx context.Context, ws *store.Workspace) (GrowOverview, error)
- func (s *Service) Page(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (*PublicRecs, error)
- func (s *Service) PageToken(wsID, contactID uuid.UUID, at time.Time) string
- func (s *Service) PauseLink(ctx context.Context, ws *store.Workspace, id uuid.UUID, pause bool) error
- func (s *Service) Prefill(ctx context.Context, ws *store.Workspace, in RecPrefillInput) (RecPrefill, error)
- func (s *Service) PreviewPartner(ctx context.Context, ws *store.Workspace, raw string) (PartnerPreview, error)
- func (s *Service) Prune(ctx context.Context) error
- func (s *Service) Reader(ws *store.Workspace, token string) (uuid.UUID, error)
- func (s *Service) Remove(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) RenderBlock(ctx context.Context, ws *store.Workspace, in BlockRenderInput) (BlockRender, error)
- func (s *Service) Reorder(ctx context.Context, ws *store.Workspace, in RecOrderInput) error
- func (s *Service) RequestLog(ctx context.Context, ws *store.Workspace, linkID uuid.UUID, page int) (PartnerRequestLog, error)
- func (s *Service) RequestSubscribe(ctx context.Context, ws *store.Workspace, recID uuid.UUID, ...) (string, error)
- func (s *Service) RevokeCode(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) Roots() []string
- func (s *Service) RotateSecret(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) Routes(r chi.Router)
- func (s *Service) SendDue(ctx context.Context) (int, error)
- func (s *Service) SendNotices(ctx context.Context) (int, error)
- func (s *Service) SendOptIns(ctx context.Context) (int, error)
- func (s *Service) ServeCodePage(w http.ResponseWriter, _ *http.Request)
- func (s *Service) SetConfirmPage(ctx context.Context, ws *store.Workspace, on bool) error
- func (s *Service) SetLimit(ctx context.Context, ws *store.Workspace, id uuid.UUID, limit int) error
- func (s *Service) SetPaused(ctx context.Context, ws *store.Workspace, id uuid.UUID, paused bool) (RecommendationItem, error)
- func (s *Service) Subscribe(ctx context.Context, ws *store.Workspace, recID uuid.UUID, contactID uuid.UUID, ...) (string, error)
- func (s *Service) Tick(ctx context.Context) error
- func (s *Service) Update(ctx context.Context, ws *store.Workspace, id uuid.UUID, in RecLinkInput) (RecommendationItem, error)
- func (s *Service) UpdateProfile(ctx context.Context, ws *store.Workspace, in RecProfileInput) (RecProfile, error)
- func (s *Service) Vars(ctx context.Context, wsID uuid.UUID, recipients []liquid.Recipient, _ []string) (map[uuid.UUID]map[string]any, error)
- func (s *Service) View(ctx context.Context, ws *store.Workspace) (RecommendationsView, error)
- func (s *Service) Visit(ctx context.Context, ws *store.Workspace, id uuid.UUID) (string, bool)
Constants ¶
const ( KindLink = "link" KindPartner = "partner" )
Kinds of recommendation.
const ( DirOut = "out" DirIn = "in" )
Partner link directions: out, we recommend them (we send subscribe requests); in, they recommend us (we receive them).
const ( LinkConnected = "connected" LinkPaused = "paused" LinkInvalid = "invalid" LinkEnded = "ended" )
Partner link statuses.
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.
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 = "unavailable" )
Outcomes of a reader's Subscribe on our pages.
const OverviewDays = 30
OverviewDays is the overview's period: the last 30 days, today included.
Variables ¶
var ErrExpired = errors.New("recommendations: the link expired")
ErrExpired: the personal link expired; the page asks for an address.
Functions ¶
func Erasure ¶
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 ¶
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 RegisterJobs ¶
RegisterJobs adds the recommendations' workers and schedules.
func RegisterOverview ¶
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 ¶
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) 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.
type PruneWorker ¶
type PruneWorker struct {
river.WorkerDefaults[PruneArgs]
S *Service
}
PruneWorker runs PruneArgs.
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 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"`
Logo *RecImage `json:"logo,omitempty"`
// 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"`
Logo *RecImage `json:"logo,omitempty"`
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"`
Logo *RecImage `json:"logo,omitempty"`
// 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.
type SendWorker ¶
type SendWorker struct {
river.WorkerDefaults[SendArgs]
S *Service
}
SendWorker runs SendArgs.
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.
func (*Service) AddLink ¶
func (s *Service) AddLink(ctx context.Context, ws *store.Workspace, in RecLinkInput) (RecommendationItem, error)
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 ¶
func (s *Service) ConnectPartner(ctx context.Context, ws *store.Workspace, in PartnerConnectInput) (RecommendationItem, error)
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 ¶
func (s *Service) CreateCode(ctx context.Context, ws *store.Workspace, in PartnerCodeInput) (PartnerCodeCreated, error)
CreateCode creates a single-use partner code valid 7 days. Only its hash is kept: the code is shown this once.
func (*Service) EndLink ¶
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 ¶
func (s *Service) Item(ctx context.Context, ws *store.Workspace, id uuid.UUID) (RecommendationItem, error)
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) 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) PauseLink ¶
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) Remove ¶
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) 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 ¶
RevokeCode revokes a partner code nobody has used yet.
func (*Service) RotateSecret ¶
RotateSecret agrees a new signing secret with the partner over the signed channel. Both secrets work for 24 hours.
func (*Service) SendNotices ¶
SendNotices sends the partners' signed confirmations, retried for 24 hours.
func (*Service) SendOptIns ¶
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 ¶
SetConfirmPage turns the confirmation page's "While you're here" on or off.
func (*Service) SetLimit ¶
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) Update ¶
func (s *Service) Update(ctx context.Context, ws *store.Workspace, id uuid.UUID, in RecLinkInput) (RecommendationItem, error)
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.
Source Files
¶
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. |