Documentation
¶
Overview ¶
Package polls is the Poll block and surveys (design expansion, M21): a question in an email whose answers are plain links, the answer page that records the answer (never the click, so link scanners can't vote), the results in the campaign report, and hosted multi-question surveys built in Forms & pages.
A poll's settings live in the email's MJML, in the poll section's rc-poll attribute, so they are versioned with the content. When a test or a send needs the poll's links, Sync copies them into polls; each recipient's answer link carries a signed token (linktoken.Poll) naming the poll, the message and the contact.
Index ¶
- Constants
- Variables
- func AnswerText(q SurveyQuestion, v any) string
- func FaceWord(faces, key int) string
- func FixMJML(src, action string, params map[string]string) (next, label, applied string, err error)
- func PreviewLinks(src string) map[string]string
- func Register(h huma.API, s *Service)
- func Section(c PollConfig, faceURL func(faces, key int) string) string
- func SurveyVar(number int64) string
- func VarName(id string) string
- type Answer
- type AnswerPage
- type Export
- type FieldSource
- type FieldSources
- type PollAnswerConfig
- type PollAnswerCount
- type PollAutomatedVisits
- type PollBlock
- type PollBreakdownRow
- type PollBreakdowns
- type PollCampaignPath
- type PollClose
- type PollComment
- type PollCommentCounts
- type PollCommentList
- type PollCommentsFilter
- type PollConfig
- type PollContactPath
- type PollNPS
- type PollOption
- type PollOverTime
- type PollPath
- type PollResults
- type PollResultsList
- type PollShare
- type PollShares
- type PollSource
- type PollSourceList
- type PollTestAnswer
- type PollTestAnswers
- type PollTestAnswersCleared
- type ReadinessFacts
- type ReadinessPoll
- type ReadinessSurvey
- type RecipientLink
- type Service
- func (s *Service) BrowserLinks(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) map[string]string
- func (s *Service) CampaignPolls(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (PollResultsList, error)
- func (s *Service) CampaignReadiness(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, src string) ReadinessFacts
- func (s *Service) ClearTestAnswers(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (int64, error)
- func (s *Service) Comment(ctx context.Context, wsID uuid.UUID, token, text string) (*AnswerPage, error)
- func (s *Service) Comments(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID, ...) (PollCommentList, error)
- func (s *Service) ContactActivity(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, ...) ([]audience.ContactActivityItem, int64, error)
- func (s *Service) ContactFieldSources(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (FieldSources, error)
- func (s *Service) CreateSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, in SurveyCreate) (Survey, error)
- func (s *Service) DeleteSurvey(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) ExportPollAnswers(ctx context.Context, ws *store.Workspace, pollID uuid.UUID) (Export, error)
- func (s *Service) ExportPollResults(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID) (Export, error)
- func (s *Service) ExportSurveyAnswers(ctx context.Context, ws *store.Workspace, id uuid.UUID) (Export, error)
- func (s *Service) ExportSurveyResults(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (Export, error)
- func (s *Service) GetSurvey(ctx context.Context, ws *store.Workspace, id uuid.UUID) (Survey, error)
- func (s *Service) Page(ctx context.Context, wsID uuid.UUID, token string, picked int, v Visit) (*AnswerPage, error)
- func (s *Service) PollResultsOf(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID) (PollResults, error)
- func (s *Service) PublishSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (Survey, error)
- func (s *Service) Record(ctx context.Context, wsID uuid.UUID, token string, answer int, v Visit) (*AnswerPage, error)
- func (s *Service) Responses(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, ...) (SurveyResponseList, error)
- func (s *Service) SendLinks(ctx context.Context, wsID, campaignID uuid.UUID) ([]RecipientLink, error)
- func (s *Service) SetPollOpen(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID, ...) (PollResults, error)
- func (s *Service) SetSurveyOpen(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, ...) (Survey, error)
- func (s *Service) Sources(ctx context.Context, ws *store.Workspace) (PollSourceList, error)
- func (s *Service) SubmitSurvey(ctx context.Context, wsID uuid.UUID, slug, token string, form url.Values) (*SurveyPage, error)
- func (s *Service) SurveyPageFor(ctx context.Context, wsID uuid.UUID, slug, token string) (*SurveyPage, error)
- func (s *Service) SurveyResultsOf(ctx context.Context, ws *store.Workspace, id uuid.UUID) (SurveyResults, error)
- func (s *Service) Surveys(ctx context.Context, ws *store.Workspace) (SurveyList, error)
- func (s *Service) Sync(ctx context.Context, q *store.Queries, wsID, campaignID uuid.UUID, src string, ...) ([]Synced, error)
- func (s *Service) TestAnswers(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (PollTestAnswers, error)
- func (s *Service) TestLinks(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, email string) (map[string]string, error)
- func (s *Service) TextAnswers(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, ...) (SurveyTextAnswerList, error)
- func (s *Service) UpdateSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, ...) (Survey, error)
- type Survey
- type SurveyClose
- type SurveyCreate
- type SurveyError
- type SurveyLink
- type SurveyList
- type SurveyOption
- type SurveyPage
- type SurveyPath
- type SurveyProblem
- type SurveyQuestion
- type SurveyQuestionResult
- type SurveyReopen
- type SurveyResponse
- type SurveyResponseList
- type SurveyResults
- type SurveySave
- type SurveySettings
- type SurveyTextAnswer
- type SurveyTextAnswerList
- type SurveyUpdate
- type Synced
- type Visit
Constants ¶
const ( AnswererContact = "contact" AnswererNonContact = "non_contact" AnswererTest = "test" )
Who answers through a link.
const ( KindChoice = "choice" KindScale = "scale" KindEmoji = "emoji" )
Poll kinds.
const ( SaveNone = "none" SaveTag = "tag" SaveField = "field" )
Where an answer is saved on the contact.
const ( CloseDays = "days" CloseDate = "date" CloseManual = "manual" )
When a poll closes.
const ( MaxShortAnswer = 200 MaxLongAnswer = 2000 )
Longest text answers: a short answer, and a long one.
const ( QuestionSingle = "single" QuestionMulti = "multi" QuestionScale = "scale" QuestionEmoji = "emoji" QuestionShort = "short" QuestionLong = "long" )
Survey question types.
const ( SurveyDraft = "draft" SurveyOpen = "open" SurveyClosed = "closed" )
Survey statuses.
const FixCloseDays = "poll_close_days"
FixCloseDays makes a poll close N days after sending (Send Readiness' "Close 7 days after sending").
const MaxComment = 500
MaxComment is the longest comment: "Anything to add?", up to 500 characters.
const MaxQuestions = 20
MaxQuestions is how many questions a survey takes, all on one page.
const TooFew = 30
TooFew is the fewest answers a breakdown row compares: fewer read "Too few to compare".
const TriggerPollAnswered = "poll_answered"
TriggerPollAnswered is the automation trigger "Answered a poll or survey".
Variables ¶
var ErrBadLink = errors.New("polls: the link doesn't work")
ErrBadLink is a link that doesn't verify: cut short, changed, or for a poll that no longer exists. Nothing is recorded.
Functions ¶
func AnswerText ¶
func AnswerText(q SurveyQuestion, v any) string
AnswerText is a question's answer in words: "Daily", "Feature flags, Audit log exports", "9", or the text.
func PreviewLinks ¶
PreviewLinks are a preview's poll and survey link variables: links that go nowhere, so nothing is recorded from the composer.
func Section ¶
func Section(c PollConfig, faceURL func(faces, key int) string) string
Section writes a Poll block's MJML from its settings: the question, the answers as plain links (MJML buttons, or cells for a scale), the ends' words and the note. The composer writes the same structure; this one is for the API and the demo. faceURL gives an emoji face's image.
Types ¶
type Answer ¶
type Answer struct {
Key int `json:"key"`
Label string `json:"label"`
Emoji string `json:"emoji,omitempty"`
Tag string `json:"tag,omitempty"`
}
Answer is one answer of a poll with its key: 1… for choices and faces, 0–10 for a scale.
type AnswerPage ¶
type AnswerPage struct {
PollID uuid.UUID
WorkspaceID uuid.UUID
Config PollConfig
Answers []Answer
CampaignName string
// Who: a contact (Name is their first name), a non-contact (archive
// links) or a test address.
Answerer string
Name string
Email string
// ContactID and MessageID are the link's (the page's own links, such as
// Email preferences, are signed for the contact).
ContactID uuid.UUID
MessageID uuid.UUID
// SentAt is when the campaign started sending.
SentAt *time.Time
// Picked is the answer of the link; Answer the recorded one (nil
// before this person answered).
Picked int
Answer *int
// Previous is the answer this visit replaced (nil when it didn't).
Previous *int
Comment string
// Saved is true when this request recorded the answer (or the same
// answer was already recorded).
Saved bool
// Closed polls record nothing; ClosedAt is when they closed.
Closed bool
ClosedAt *time.Time
ClosesAt *time.Time
// Refused is a non-contact on a poll that doesn't take their answers.
Refused bool
// Automated is a visit the classifier attributed to a machine.
Automated bool
// Results are the shares, when the poll shows them after answering.
Results *PollShares
// SurveyURL continues to a survey when the poll says so.
SurveyURL string
}
AnswerPage is everything an answer page shows.
type FieldSource ¶
type FieldSource struct {
Field string `json:"field"`
Kind string `json:"kind" enum:"poll,survey"`
Name string `json:"name"`
At time.Time `json:"at"`
}
FieldSource says where a contact field's value came from.
type FieldSources ¶
type FieldSources struct {
Items []FieldSource `json:"items"`
}
FieldSources are the fields of a contact that a poll or a survey set.
type PollAnswerConfig ¶
type PollAnswerConfig struct {
Label string `json:"label"`
// Emoji is shown before the label; Tag is added when Save is "tag".
Emoji string `json:"emoji,omitempty"`
Tag string `json:"tag,omitempty"`
}
PollAnswerConfig is one answer of a Choice poll.
type PollAnswerCount ¶
type PollAnswerCount struct {
Key int `json:"key"`
Label string `json:"label"`
Emoji string `json:"emoji,omitempty"`
Tag string `json:"tag,omitempty"`
Count int64 `json:"count"`
Percent float64 `json:"percent"`
}
PollAnswerCount is one answer's count and share of the answers.
type PollAutomatedVisits ¶
type PollAutomatedVisits struct {
Total int64 `json:"total"`
Gateways int64 `json:"gateways"`
Prefetch int64 `json:"prefetch"`
}
PollAutomatedVisits are the visits ignored as a machine's.
type PollBlock ¶
type PollBlock struct {
Config PollConfig
// Path is the section's element path from mj-body.
Path []int
}
PollBlock is a Poll block found in an email.
type PollBreakdownRow ¶
type PollBreakdownRow struct {
Key string `json:"key"`
Label string `json:"label"`
Answers int64 `json:"answers"`
Percent float64 `json:"percent"`
TooFew bool `json:"tooFew"`
NPS *int `json:"nps,omitempty"`
Counts []PollAnswerCount `json:"counts"`
}
PollBreakdownRow is one row of a breakdown: a tier, a list or a language, with its answers and, when it has enough, its NPS or shares.
type PollBreakdowns ¶
type PollBreakdowns struct {
Tiers []PollBreakdownRow `json:"tiers"`
Lists []PollBreakdownRow `json:"lists"`
Languages []PollBreakdownRow `json:"languages"`
}
PollBreakdowns are the answers by engagement tier, list and language.
type PollCampaignPath ¶
type PollCampaignPath struct {
api.WorkspaceInput
CampaignID string `path:"campaignId" format:"uuid" doc:"Campaign id"`
}
type PollClose ¶
type PollClose struct {
Mode string `json:"mode" enum:"days,date,manual"`
Days int `json:"days,omitempty"`
// Date is "2026-10-28": the poll closes at the end of that day in the
// workspace's time zone.
Date string `json:"date,omitempty"`
}
PollClose says when the poll stops recording answers.
type PollComment ¶
type PollComment struct {
ID string `json:"id"`
Answer int `json:"answer"`
Label string `json:"label"`
// Group of a 0–10 answer: promoter, passive or detractor.
Group string `json:"group,omitempty" enum:"promoter,passive,detractor"`
Comment string `json:"comment"`
At time.Time `json:"at"`
// Contact is the contact's name (people with subscribers:view), empty
// otherwise; NonContact marks answers from people who aren't contacts.
Contact string `json:"contact,omitempty"`
ContactID string `json:"contactId,omitempty"`
NonContact bool `json:"nonContact"`
}
PollComment is one comment with its answer.
type PollCommentCounts ¶
type PollCommentCounts struct {
All int64 `json:"all"`
Promoters int64 `json:"promoters"`
Passives int64 `json:"passives"`
Detractors int64 `json:"detractors"`
}
PollCommentCounts are the comments by group, for the filter.
type PollCommentList ¶
type PollCommentList struct {
Items []PollComment `json:"items"`
Total int64 `json:"total"`
Counts PollCommentCounts `json:"counts"`
Names bool `json:"names"`
}
PollCommentList is a page of comments, newest first.
type PollCommentsFilter ¶
PollCommentsFilter narrows the comments.
type PollConfig ¶
type PollConfig struct {
ID string `json:"id"`
Kind string `json:"kind" enum:"choice,scale,emoji"`
Question string `json:"question"`
Answers []PollAnswerConfig `json:"answers"`
// Layout of Choice answers: stacked buttons or one row.
Layout string `json:"layout,omitempty" enum:"stacked,row"`
Save string `json:"save" enum:"none,tag,field"`
Field string `json:"field,omitempty"`
Close PollClose `json:"close"`
// After answering: the thank-you message, or continue to a survey whose
// first question the answer fills.
After string `json:"after" enum:"thanks,survey"`
Thanks string `json:"thanks,omitempty"`
Survey string `json:"survey,omitempty"`
// NonContacts: count answers from people who aren't contacts apart, or
// refuse them.
NonContacts string `json:"nonContacts" enum:"count,refuse"`
// Results shows the shares on the answer page after answering.
Results bool `json:"results"`
// NPS uses the Net Promoter Score wording on a 0–10 scale; Low and
// High are its ends' words.
NPS bool `json:"nps,omitempty"`
Low string `json:"low,omitempty"`
High string `json:"high,omitempty"`
// Faces of an emoji scale: three or five.
Faces int `json:"faces,omitempty"`
}
PollConfig is a Poll block's settings, as its rc-poll attribute stores them.
func ParseConfig ¶
func ParseConfig(raw string) (PollConfig, error)
ParseConfig reads an rc-poll attribute value.
func (PollConfig) AnswerList ¶
func (c PollConfig) AnswerList() []Answer
AnswerList is the answers a poll takes.
func (PollConfig) Encode ¶
func (c PollConfig) Encode() string
Encode writes the settings as the attribute value.
func (PollConfig) ProblemTexts ¶
func (c PollConfig) ProblemTexts() []i18n.Text
ProblemTexts are the poll's problems kept as messages, for text stored for later readers (a Send Readiness run).
func (PollConfig) Problems ¶
func (c PollConfig) Problems() []string
Problems are what keeps a poll from working, in English: a missing question, fewer than two or more than five answers, a tag or field missing where answers are saved.
func (PollConfig) ProblemsIn ¶
func (c PollConfig) ProblemsIn(l i18n.Lang) []string
ProblemsIn are the poll's problems in a reader's language.
type PollContactPath ¶
type PollContactPath struct {
api.WorkspaceInput
ContactID string `path:"contactId" format:"uuid" doc:"Contact id"`
}
type PollNPS ¶
type PollNPS struct {
Score int `json:"score"`
Promoters int64 `json:"promoters"`
Passives int64 `json:"passives"`
Detractors int64 `json:"detractors"`
PromoterPercent float64 `json:"promoterPercent"`
PassivePercent float64 `json:"passivePercent"`
DetractorPercent float64 `json:"detractorPercent"`
}
PollNPS is a 0–10 poll's Net Promoter Score: promoters (9–10) minus detractors (0–6), as percentages of the answers.
type PollOption ¶
PollOption is one answer a trigger can filter on.
type PollOverTime ¶
type PollOverTime struct {
Since *time.Time `json:"since,omitempty"`
// Cumulative has one point per hour: answers by the end of hour i.
Cumulative []int64 `json:"cumulative"`
// FirstSixPercent is the share that came in the first 6 hours; After
// the answers after 72 hours.
FirstSixPercent float64 `json:"firstSixPercent"`
After int64 `json:"after"`
}
PollOverTime is the cumulative answers by hour over the first 72 hours.
type PollPath ¶
type PollPath struct {
api.WorkspaceInput
PollID string `path:"pollId" format:"uuid" doc:"Poll id"`
}
type PollResults ¶
type PollResults struct {
ID string `json:"id"`
BlockID string `json:"blockId"`
CampaignID string `json:"campaignId,omitempty"`
Campaign string `json:"campaign"`
Kind string `json:"kind" enum:"choice,scale,emoji"`
Question string `json:"question"`
NPSWording bool `json:"npsWording"`
Low string `json:"low,omitempty"`
High string `json:"high,omitempty"`
Save string `json:"save" enum:"none,tag,field"`
Field string `json:"field,omitempty"`
// Status: open (closes at ClosesAt, or by hand) or closed (by a person,
// or as scheduled).
Status string `json:"status" enum:"open,closed"`
ClosesAt *time.Time `json:"closesAt,omitempty"`
ClosedAt *time.Time `json:"closedAt,omitempty"`
ClosedBy string `json:"closedBy,omitempty"`
ClosedAsScheduled bool `json:"closedAsScheduled"`
ReopenedAt *time.Time `json:"reopenedAt,omitempty"`
StartedAt *time.Time `json:"startedAt,omitempty"`
// Live is a poll still collecting its first 72 hours of answers.
Live bool `json:"live"`
// Answers are contacts' answers; Percent their share of Delivered.
Answers int64 `json:"answers"`
Delivered int64 `json:"delivered"`
Percent float64 `json:"percent"`
NonContacts int64 `json:"nonContacts"`
Tests int64 `json:"tests"`
Changed int64 `json:"changed"`
Comments int64 `json:"comments"`
Automated PollAutomatedVisits `json:"automated"`
Counts []PollAnswerCount `json:"counts"`
NPS *PollNPS `json:"nps,omitempty"`
Breakdown PollBreakdowns `json:"breakdown"`
OverTime PollOverTime `json:"overTime"`
// AnswerPage is where its answer links go (the publisher's domain),
// with "…" for the signed part; Config is the Poll block's settings
// (rc-poll), for a preview of the answer page.
AnswerPage string `json:"answerPage"`
Config string `json:"config"`
// Names is true when comments carry the contacts' names
// (subscribers:view).
Names bool `json:"names"`
// CanClose (campaigns:edit) and CanExportAnswers (subscribers:export)
// are the viewer's; the helpers are members to ask when not.
CanClose bool `json:"canClose"`
CloseHelpers []string `json:"closeHelpers"`
CanExportAnswers bool `json:"canExportAnswers"`
ExportHelpers []string `json:"exportHelpers"`
}
PollResults is a poll's section of the campaign report.
type PollResultsList ¶
type PollResultsList struct {
Items []PollResults `json:"items"`
}
PollResultsList are a campaign's polls with their results.
type PollShares ¶
type PollShares struct {
}
PollShares are a poll's results as the answer page shows them.
type PollSource ¶
type PollSource struct {
// Ref is "poll:<id>" or "survey:<id>", as the trigger stores it.
Ref string `json:"ref"`
Kind string `json:"kind" enum:"poll,survey"`
Name string `json:"name"`
Campaign string `json:"campaign,omitempty"`
PollKind string `json:"pollKind,omitempty" enum:"choice,scale,emoji"`
Status string `json:"status"`
ClosesAt *time.Time `json:"closesAt,omitempty"`
Answers []PollOption `json:"answers"`
}
PollSource is a poll or a survey the automation trigger "Answered a poll or survey" can start from.
type PollSourceList ¶
type PollSourceList struct {
Items []PollSource `json:"items"`
}
PollSourceList is the workspace's polls and surveys.
type PollTestAnswer ¶
type PollTestAnswer struct {
PollID string `json:"pollId"`
BlockID string `json:"blockId"`
Email string `json:"email"`
Answer int `json:"answer"`
At time.Time `json:"at"`
}
PollTestAnswer is one test address's answer to a campaign's poll.
type PollTestAnswers ¶
type PollTestAnswers struct {
Items []PollTestAnswer `json:"items"`
}
PollTestAnswers are the test answers of a campaign's polls, never counted.
type PollTestAnswersCleared ¶
type PollTestAnswersCleared struct {
Deleted int64 `json:"deleted"`
}
PollTestAnswersCleared says how many test answers were deleted.
type ReadinessFacts ¶
type ReadinessFacts struct {
Ran bool
Polls []ReadinessPoll
Surveys []ReadinessSurvey
// Domain is the custom domain set for the public pages; DomainStatus
// its check ("verified", "pending"…) and DomainDetail what the check
// found. Instance is the address links use until it is verified.
Domain string
DomainStatus string
DomainDetail string
Instance string
// TestAnswers counts the campaign's test answers (never counted).
TestAnswers int
}
ReadinessFacts are an email's polls and surveys and where their links go.
type ReadinessPoll ¶
type ReadinessPoll struct {
ID string
Question string
Path []int
Problems []string
// ProblemTexts are the Problems kept as messages, for a run that keeps
// its text for later readers.
ProblemTexts []i18n.Text
// Close says when it closes: Mode date with ClosesAt (the end of that
// day), days with Days after sending, or manual.
Close PollClose
ClosesAt *time.Time
}
ReadinessPoll is a poll of an email as Send Readiness checks it.
type ReadinessSurvey ¶
ReadinessSurvey is a survey an email links to.
type RecipientLink ¶
RecipientLink is a per-recipient link variable of an email.
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Links *linktoken.Signer
URLs publicurl.Builder
// Forms gives the workspace's public page links (its verified custom
// domain, else the instance's address).
Forms *forms.Service
Log *slog.Logger
Now func() time.Time
}
Service runs polls and surveys.
func (*Service) BrowserLinks ¶
func (s *Service) BrowserLinks(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) map[string]string
BrowserLinks are the link variables of an email shown on the web archive or "View in browser": its links carry no contact's token, so answers from there count as non-contacts' (or are refused, as each poll says). Polls are created when a test or the send needs them; until then the answer links go nowhere.
func (*Service) CampaignPolls ¶
func (s *Service) CampaignPolls(ctx context.Context, ws *store.Workspace, p *authz.Principal, campaignID uuid.UUID) (PollResultsList, error)
CampaignPolls are the results of a campaign's polls, in the email's order.
func (*Service) CampaignReadiness ¶
func (s *Service) CampaignReadiness(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, src string) ReadinessFacts
CampaignReadiness reads the facts of a campaign's content.
func (*Service) ClearTestAnswers ¶
func (s *Service) ClearTestAnswers(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (int64, error)
ClearTestAnswers deletes a campaign's test answers (audited: answers deleted).
func (*Service) Comment ¶
func (s *Service) Comment(ctx context.Context, wsID uuid.UUID, token, text string) (*AnswerPage, error)
Comment saves "Anything to add?" with a recorded answer.
func (*Service) Comments ¶
func (s *Service) Comments(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID, f PollCommentsFilter) (PollCommentList, error)
Comments are a poll's comments, newest first, with names for people with subscribers:view.
func (*Service) ContactActivity ¶
func (s *Service) ContactActivity(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, before *time.Time, beforeID string, limit int) ([]audience.ContactActivityItem, int64, error)
ContactActivity is audience.ActivitySource: the answers before the cursor, newest first, and how many there are.
func (*Service) ContactFieldSources ¶
func (s *Service) ContactFieldSources(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (FieldSources, error)
ContactFieldSources finds the fields a contact's answers set: the latest answer that saved to a field names it.
func (*Service) CreateSurvey ¶
func (s *Service) CreateSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, in SurveyCreate) (Survey, error)
CreateSurvey makes a draft survey with no questions yet.
func (*Service) DeleteSurvey ¶
DeleteSurvey removes a survey; its page stops answering.
func (*Service) ExportPollAnswers ¶
func (s *Service) ExportPollAnswers(ctx context.Context, ws *store.Workspace, pollID uuid.UUID) (Export, error)
ExportPollAnswers writes every answer with its contact (subscribers:export, audited).
func (*Service) ExportPollResults ¶
func (s *Service) ExportPollResults(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID) (Export, error)
ExportPollResults writes a poll's results as CSV: aggregate numbers only, audited like the other report exports.
func (*Service) ExportSurveyAnswers ¶
func (s *Service) ExportSurveyAnswers(ctx context.Context, ws *store.Workspace, id uuid.UUID) (Export, error)
ExportSurveyAnswers writes every response with its contact (subscribers:export, audited).
func (*Service) ExportSurveyResults ¶
func (s *Service) ExportSurveyResults(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (Export, error)
ExportSurveyResults writes a survey's results as CSV, aggregate only.
func (*Service) Page ¶
func (s *Service) Page(ctx context.Context, wsID uuid.UUID, token string, picked int, v Visit) (*AnswerPage, error)
Page shows an answer page without recording anything: what the link picked, and the answer already recorded. A machine's visit is counted as an automated visit.
func (*Service) PollResultsOf ¶
func (s *Service) PollResultsOf(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID) (PollResults, error)
PollResultsOf is one poll's results.
func (*Service) PublishSurvey ¶
func (s *Service) PublishSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (Survey, error)
PublishSurvey opens a survey's page. Every question must be complete.
func (*Service) Record ¶
func (s *Service) Record(ctx context.Context, wsID uuid.UUID, token string, answer int, v Visit) (*AnswerPage, error)
Record saves an answer from the page (its script's POST once the page was visible for a moment, or the Confirm button without JavaScript). The latest answer counts; a changed one replaces it, with the history kept.
func (*Service) Responses ¶
func (s *Service) Responses(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, offset, limit int) (SurveyResponseList, error)
Responses lists a survey's completed responses.
func (*Service) SendLinks ¶
func (s *Service) SendLinks(ctx context.Context, wsID, campaignID uuid.UUID) ([]RecipientLink, error)
SendLinks syncs a campaign's polls as its send starts and returns the link variables each recipient gets: every poll's answer link base and every survey's link.
func (*Service) SetPollOpen ¶
func (s *Service) SetPollOpen(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID, open bool) (PollResults, error)
SetPollOpen closes a poll now, or reopens it: answers made after reopening count as usual. Both are audited.
func (*Service) SetSurveyOpen ¶
func (s *Service) SetSurveyOpen(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, open bool, in SurveyReopen) (Survey, error)
SetSurveyOpen closes or reopens a survey.
func (*Service) Sources ¶
Sources lists the polls (of sent and scheduled campaigns and of drafts tested already) and the surveys of a workspace.
func (*Service) SubmitSurvey ¶
func (s *Service) SubmitSurvey(ctx context.Context, wsID uuid.UUID, slug, token string, form url.Values) (*SurveyPage, error)
SubmitSurvey saves a survey page's answers, when the person pressed Send: scanners don't. A required question left empty saves nothing.
func (*Service) SurveyPageFor ¶
func (s *Service) SurveyPageFor(ctx context.Context, wsID uuid.UUID, slug, token string) (*SurveyPage, error)
SurveyPageFor shows a survey page; it records nothing.
func (*Service) SurveyResultsOf ¶
func (s *Service) SurveyResultsOf(ctx context.Context, ws *store.Workspace, id uuid.UUID) (SurveyResults, error)
SurveyResultsOf counts a survey's responses.
func (*Service) Sync ¶
func (s *Service) Sync(ctx context.Context, q *store.Queries, wsID, campaignID uuid.UUID, src string, started *time.Time, tz string) ([]Synced, error)
Sync copies the polls of a campaign's content into polls, so their links can be signed (a test send, a send). started is when the send started, nil before.
func (*Service) TestAnswers ¶
func (s *Service) TestAnswers(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (PollTestAnswers, error)
TestAnswers lists a campaign's test answers.
func (*Service) TestLinks ¶
func (s *Service) TestLinks(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, email string) (map[string]string, error)
TestLinks are the link variables of a test email to one address: its answers are recorded as that address's test answers, never counted.
func (*Service) TextAnswers ¶
func (s *Service) TextAnswers(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, key, search string, offset, limit int) (SurveyTextAnswerList, error)
TextAnswers lists a text question's answers, newest first.
func (*Service) UpdateSurvey ¶
func (s *Service) UpdateSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, in SurveyUpdate) (Survey, error)
UpdateSurvey saves a survey's changes. Settings changes are audited with before and after; editing an open survey applies to new responses.
type Survey ¶
type Survey struct {
ID string `json:"id"`
Number int64 `json:"number"`
Slug string `json:"slug"`
Name string `json:"name"`
Description string `json:"description"`
Status string `json:"status" enum:"draft,open,closed"`
Questions []SurveyQuestion `json:"questions"`
Settings SurveySettings `json:"settings"`
ClosesAt *time.Time `json:"closesAt,omitempty"`
PublishedAt *time.Time `json:"publishedAt,omitempty"`
PublishedBy string `json:"publishedBy,omitempty"`
ClosedAt *time.Time `json:"closedAt,omitempty"`
ClosedBy string `json:"closedBy,omitempty"`
CreatedBy string `json:"createdBy"`
CreatedAt time.Time `json:"createdAt"`
UpdatedAt time.Time `json:"updatedAt"`
// URL is the public page; Variable the link variable for emails.
URL string `json:"url"`
Variable string `json:"variable"`
// Started and Completed count responses.
Started int64 `json:"started"`
Completed int64 `json:"completed"`
Linked []SurveyLink `json:"linked"`
Problems []SurveyProblem `json:"problems"`
// CanEdit is the viewer's forms:edit; EditHelpers are members to ask
// when they lack it.
CanEdit bool `json:"canEdit"`
EditHelpers []string `json:"editHelpers"`
}
Survey is a survey with its counts.
type SurveyClose ¶
type SurveyClose struct {
Mode string `json:"mode" enum:"date,manual"`
// Date and Time are local to the survey's time zone ("2026-10-31", "23:59").
Date string `json:"date,omitempty"`
Time string `json:"time,omitempty"`
}
SurveyClose is when a survey stops taking answers.
type SurveyCreate ¶
type SurveyCreate struct {
Name string `json:"name,omitempty" maxLength:"200"`
}
SurveyCreate starts a survey.
type SurveyError ¶
SurveyError is a question that needs an answer.
type SurveyLink ¶
type SurveyLink struct {
CampaignID string `json:"campaignId"`
Name string `json:"name"`
Status string `json:"status"`
SentAt *time.Time `json:"sentAt,omitempty"`
Recipients *int64 `json:"recipients,omitempty"`
// Via is how the email links to it: a link, or a poll that continues to it.
Via string `json:"via" enum:"link,poll"`
}
SurveyLink is a campaign that links to a survey.
type SurveyList ¶
type SurveyList struct {
Items []Survey `json:"items"`
}
SurveyList is the workspace's surveys.
type SurveyOption ¶
type SurveyOption struct {
Key int `json:"key" minimum:"1"`
Label string `json:"label" maxLength:"200"`
// Tag is added to the contact who picks it, when the question saves tags.
Tag string `json:"tag,omitempty" maxLength:"64"`
}
SurveyOption is one answer of a choice question.
func QuestionOptions ¶
func QuestionOptions(q SurveyQuestion) []SurveyOption
QuestionOptions are the answers a question takes, keys included: a scale's 0–10, an emoji scale's faces, a choice's answers.
type SurveyPage ¶
type SurveyPage struct {
SurveyID uuid.UUID
Number int64
Slug string
Name string
Description string
Questions []SurveyQuestion
Settings SurveySettings
ClosesAt *time.Time
// Closed surveys take no answers; ClosedAt is when they closed.
Closed bool
ClosedAt *time.Time
// Who answers: a contact (FirstName, Email), someone who isn't one, or a
// test address.
Answerer string
FirstName string
Email string
// Refused is someone who isn't a contact, on a survey that doesn't take
// their answers.
Refused bool
// Answers are the response's answers: question key → a choice's key, a
// multiple choice's keys, a number, or text.
Answers map[string]any
// FromPoll is a response whose first question came from the email's
// poll; CompletedAt an earlier completed response, editable while the
// survey is open.
FromPoll bool
CompletedAt *time.Time
// Saved is true when this request saved the answers.
Saved bool
// Errors are the questions left empty, in order, with their message.
Errors []SurveyError
Token string
}
SurveyPage is everything a survey page shows.
func (*SurveyPage) Error ¶
func (p *SurveyPage) Error(key string) string
Error returns a question's message, or "".
type SurveyPath ¶
type SurveyPath struct {
api.WorkspaceInput
SurveyID string `path:"surveyId" format:"uuid" doc:"Survey id"`
}
type SurveyProblem ¶
type SurveyProblem struct {
Question string `json:"question,omitempty"`
Field string `json:"field"`
Message string `json:"message"`
}
SurveyProblem is what keeps a survey from being published.
func SurveyProblems ¶
func SurveyProblems(l i18n.Lang, qs []SurveyQuestion) []SurveyProblem
SurveyProblems lists what keeps a survey from being published, in a reader's language.
type SurveyQuestion ¶
type SurveyQuestion struct {
Key string `json:"key" pattern:"^q[0-9]{1,3}$"`
Type string `json:"type" enum:"single,multi,scale,emoji,short,long"`
Text string `json:"text" maxLength:"500"`
Description string `json:"description,omitempty" maxLength:"1000"`
Required bool `json:"required"`
Answers []SurveyOption `json:"answers"`
Save SurveySave `json:"save"`
// NPS wording of a 0–10 scale, with its ends' words.
NPS bool `json:"nps,omitempty"`
Low string `json:"low,omitempty" maxLength:"60"`
High string `json:"high,omitempty" maxLength:"60"`
// Faces of an emoji scale: three or five.
Faces int `json:"faces,omitempty"`
// RequiredText is said under a required question left empty ("Pick
// the one closest to your job."); empty uses the type's sentence.
RequiredText string `json:"requiredText,omitempty" maxLength:"200"`
}
SurveyQuestion is one question of a survey.
type SurveyQuestionResult ¶
type SurveyQuestionResult struct {
Key string `json:"key"`
Number int `json:"number"`
Type string `json:"type"`
Text string `json:"text"`
Required bool `json:"required"`
Answered int64 `json:"answered"`
Counts []PollAnswerCount `json:"counts"`
NPS *PollNPS `json:"nps,omitempty"`
// SavedTo is the field the answers fill, when they do.
SavedTo string `json:"savedTo,omitempty"`
}
SurveyQuestionResult is one question's results over the completed responses.
type SurveyReopen ¶
type SurveyReopen struct {
Close *SurveyClose `json:"close,omitempty"`
}
SurveyReopen reopens a closed survey, with a new closing date or none.
type SurveyResponse ¶
type SurveyResponse struct {
ID string `json:"id"`
CompletedAt *time.Time `json:"completedAt,omitempty"`
// Contact is the contact's name for people with subscribers:view.
Contact string `json:"contact,omitempty"`
ContactID string `json:"contactId,omitempty"`
NonContact bool `json:"nonContact"`
// Answers are the answers in words, one per question ("" unanswered).
Answers []string `json:"answers"`
}
SurveyResponse is one completed response.
type SurveyResponseList ¶
type SurveyResponseList struct {
Items []SurveyResponse `json:"items"`
Total int64 `json:"total"`
Names bool `json:"names"`
}
SurveyResponseList is a page of completed responses, newest first.
type SurveyResults ¶
type SurveyResults struct {
Started int64 `json:"started"`
Completed int64 `json:"completed"`
CompletionPercent float64 `json:"completionPercent"`
// PollOnly answered question 1 in the email's poll and stopped there.
PollOnly int64 `json:"pollOnly"`
// Recipients of the emails that link to it.
Recipients int64 `json:"recipients"`
NonContacts int64 `json:"nonContacts"`
Questions []SurveyQuestionResult `json:"questions"`
}
SurveyResults are a survey's completion and per-question results.
type SurveySave ¶
type SurveySave struct {
To string `json:"to" enum:"none,field,tags"`
Field string `json:"field,omitempty" maxLength:"64"`
}
SurveySave says where a question's answer goes on the contact.
type SurveySettings ¶
type SurveySettings struct {
Close SurveyClose `json:"close"`
Timezone string `json:"timezone,omitempty" maxLength:"64"`
// OneResponse keeps one response per contact, editable until it closes.
OneResponse bool `json:"oneResponse"`
// AcceptNonContacts takes answers from links without a contact's token.
AcceptNonContacts bool `json:"acceptNonContacts"`
Thanks string `json:"thanks,omitempty" maxLength:"1000"`
}
SurveySettings are a survey's settings.
type SurveyTextAnswer ¶
type SurveyTextAnswer struct {
Text string `json:"text"`
At time.Time `json:"at"`
Contact string `json:"contact,omitempty"`
}
SurveyTextAnswer is one text answer.
type SurveyTextAnswerList ¶
type SurveyTextAnswerList struct {
Items []SurveyTextAnswer `json:"items"`
Total int64 `json:"total"`
Names bool `json:"names"`
}
SurveyTextAnswerList is a page of a text question's answers.
type SurveyUpdate ¶
type SurveyUpdate struct {
Name *string `json:"name,omitempty" minLength:"1" maxLength:"200"`
Slug *string `json:"slug,omitempty" pattern:"^[a-z0-9][a-z0-9-]{0,59}$"`
Description *string `json:"description,omitempty" maxLength:"1000"`
Questions []SurveyQuestion `json:"questions,omitempty" maxItems:"20"`
Settings *SurveySettings `json:"settings,omitempty"`
}
SurveyUpdate changes a survey: name, address, description, questions and settings. Omitted fields stay.