package notify
// Workflows returns the definitions quarry provisions at startup (RFC
// 0011 §7). These are the same six workflows docs/running.md used to
// ask an operator to `curl` by hand — this is now the one source,
// created by EnsureWorkflow rather than typed.
//
// RFC 0011 §6's routing table is spelled here and nowhere else:
//
// quarry-mention in_app -> push -> email (immediate; email accepts replies)
// quarry-forum-reply in_app -> push -> email (immediate; email accepts replies)
// quarry-landing in_app -> push -> email (immediate; email accepts replies)
// quarry-activity digest 2 h -> in_app -> email
// quarry-error/slow in_app (admins; unchanged)
//
// Email is OFF by default for every family: notify reads an absent
// preference as enabled, so the forge writes the explicit "no" for each
// subscriber who has not chosen (emailOffByDefault in cmd/quarry). The
// step exists so the choice exists; nobody is mailed for not having
// made it.
//
// IMPORTANT for an EXISTING forge: EnsureWorkflow upserts with
// notify's `onConflict=keep`, which never rewrites a workflow that is
// already there (an operator may have edited its copy). So a forge
// provisioned before this phase keeps its single-in_app definitions:
// the push and digest steps below reach it only after the operator
// deletes those workflows in notify's console once and lets the next
// startup recreate them.
func Workflows() []WorkflowDef {
// Control values are notify's own per-step-type shapes, read off
// internal/steptype (channels.go for in_app/push, sleep.go for
// digest). They are typed map[string]any rather than map[string]string
// because a digest's `amount` is a NUMBER on notify's side: a
// quoted "15" fails its json.Unmarshal into int64 and the step
// never compiles.
// The redirect is what makes an inbox row a link. notify stores it
// on the message as extras.redirect.url, which is exactly where
// Message.Link reads from, and the inbox renders a row with no link
// as dead text — eight rows of "something happened" leading
// nowhere. Every trigger quarry sends carries payload.link for this
// reason; the push step has always used it.
inApp := func(id, subject, body string) WorkflowStep {
return WorkflowStep{
StepID: id,
Type: "in_app",
ControlValues: map[string]any{
"subject": subject,
"body": body,
"redirect": map[string]any{"url": "{{payload.link}}"},
},
}
}
// push carries the link in data_json, which notify's push step
// validates as a JSON object of STRING values (steptype.push) and
// passes to the browser as the notification's data — where sw.js
// reads data.url to decide what a click opens.
push := func(id, title, body string) WorkflowStep {
return WorkflowStep{
StepID: id,
Type: "push",
ControlValues: map[string]any{
// BOTH spellings, deliberately. notify's push editor
// authors "title", but the envelope its delivery
// renders from (runenv.StepControls) carries only
// "subject" — so a push authored the documented way
// arrives with an empty title and the service worker
// falls back to the word "quarry" for every
// notification (notify#334). "subject" is what renders
// today; "title" is what the editor will show an
// operator, and what will keep working when the two
// spellings meet.
"title": title,
"subject": title,
"body": body,
"data_json": `{"url":"{{payload.link}}"}`,
},
}
}
// email is plain text, one link, and — where the notification is
// something a person answers — accepts replies: notify then sends it
// with a tokenised Reply-To and hands the answer back on the
// delivery stream (RFC 0014 Phase 1). A digest is not answered, so
// the activity email does not opt in.
email := func(id, subject, body string, reply bool) WorkflowStep {
cv := map[string]any{"subject": subject, "body": body}
if reply {
cv["reply"] = true
}
return WorkflowStep{StepID: id, Type: "email", ControlValues: cv}
}
return []WorkflowDef{
{
// What changed on the forge: one inbox item and a push per
// announced changelog entry, to everyone with an account.
Name: "quarry-changelog",
TriggerIdentifier: "quarry-changelog",
Steps: []WorkflowStep{
inApp("S1", "What changed in quarry: {{payload.title}}",
"{{payload.from}} published a changelog entry — {{payload.link}}"),
push("S2", "What changed in quarry", "{{payload.title}}"),
},
},
{
Name: "quarry-mention",
TriggerIdentifier: "quarry-mention",
Steps: []WorkflowStep{
inApp("S1", "{{payload.from}} mentioned you in {{payload.repo}}",
"{{payload.repo}} — {{payload.text}}"),
push("S2", "{{payload.from}} mentioned you",
"{{payload.repo}} — {{payload.text}}"),
email("S3", "{{payload.from}} mentioned you in {{payload.repo}}",
"{{payload.from}} wrote:\n\n{{payload.text}}\n\n{{payload.link}}", true),
},
},
{
Name: "quarry-forum-reply",
TriggerIdentifier: "quarry-forum-reply",
Steps: []WorkflowStep{
inApp("S1", "{{payload.from}} replied in {{payload.title}}",
"{{payload.repo}} — {{payload.text}}"),
push("S2", "{{payload.from}} replied in {{payload.title}}",
"{{payload.repo}} — {{payload.text}}"),
email("S3", "{{payload.from}} replied in {{payload.title}}",
"{{payload.from}} wrote:\n\n{{payload.text}}\n\n{{payload.link}}", true),
},
},
{
// The one workflow with a digest: activity is a stream of
// small things, and a phone that buzzes per check-in is a
// phone somebody turns off. Fifteen minutes is RFC 0011 §6's
// window; the digest runs BEFORE the in_app step, so what
// lands in the inbox is the batch rather than each event.
Name: "quarry-activity",
TriggerIdentifier: "quarry-activity",
Steps: []WorkflowStep{
{
StepID: "S1",
Type: "digest",
ControlValues: map[string]any{
"type": "regular",
// Two hours, which is the number somebody who
// has not asked for anything should get: often
// enough to be news, rare enough that a busy
// repository does not become the reason people
// mute the forge. It is the DEFAULT, not the
// policy — a per-person window is notify#336.
"amount": 2,
"unit": "hours",
// Per REPOSITORY, not per person. Without it one
// window batches every repository somebody can
// see into a single row — "7 updates" across
// four projects, which answers no question
// anybody has.
//
// ROOTED at payload: notify resolves a
// single-segment path to the empty string and
// then merges every event into the base bucket,
// silently. "repo" looks right, provisions
// without complaint, and digests nothing.
"digestKey": "payload.repo",
},
},
// A digest is a COUNT and its parts; a single event is
// just that event. Both arrive through this one step, so
// the copy tells them apart rather than reading "1
// updates" for the commonest case. events.[1] is the
// only "more than one" test Handlebars gives us without
// a helper.
inApp("S2",
"{{#if digest.events.[1]}}{{digest.count}} updates in {{payload.repo}}"+
"{{else}}{{payload.summary}}{{/if}}",
"{{#if digest.events.[1]}}{{#each digest.events}}{{this.actor}} {{this.summary}}\n{{/each}}"+
"{{else}}{{payload.repo}} — by {{payload.actor}}{{/if}}"),
// One line per event, each with its own link; a single
// event reads as itself, as the inbox row does.
email("S3",
"{{#if digest.events.[1]}}{{digest.count}} updates in {{payload.repo}}"+
"{{else}}{{payload.summary}}{{/if}}",
"{{#if digest.events.[1]}}{{#each digest.events}}{{this.actor}} {{this.summary}}\n{{this.link}}\n\n{{/each}}"+
"{{else}}{{payload.actor}} {{payload.summary}}\n\n{{payload.link}}{{/if}}", false),
},
},
{
Name: "quarry-landing",
TriggerIdentifier: "quarry-landing",
Steps: []WorkflowStep{
inApp("S1", "{{payload.summary}}", "{{payload.repo}} — {{payload.link}}"),
push("S2", "{{payload.summary}}", "{{payload.repo}}"),
email("S3", "{{payload.summary}}",
"{{payload.summary}} in {{payload.repo}}\n\n{{payload.link}}", true),
},
},
{
Name: "quarry-error",
TriggerIdentifier: "quarry-error",
Steps: []WorkflowStep{inApp("S1",
"quarry error on {{payload.surface}}",
"{{payload.path}} — {{payload.summary}}",
)},
},
{
// A push a person asks for, to find out whether push
// reaches this device at all. Push ONLY: a test that also
// wrote to the inbox would make the inbox worse every time
// somebody checked their phone.
Name: "quarry-test",
TriggerIdentifier: "quarry-test",
Steps: []WorkflowStep{push("S1", "quarry",
"Test notification — push reaches this device.")},
},
{
Name: "quarry-slow",
TriggerIdentifier: "quarry-slow",
Steps: []WorkflowStep{inApp("S1",
"slow render: {{payload.path}}",
"{{payload.summary}}",
)},
},
}
}
// EmailFamilies are the workflows that carry an email step a person
// may switch on: the four families of quarry's preference matrix. Email
// is the one channel that is off until chosen, and this is the list the
// forge writes that choice against.
func EmailFamilies() []string {
return []string{"quarry-mention", "quarry-forum-reply", "quarry-landing", "quarry-activity"}
}