Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/architecture/mail-sources-and-paging.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,3 +125,14 @@ and never carries the cursor back to the top.
All four sections wait on a `requestLane` — the journal's is one kind deep, since its whole
question is which day is selected — so "is this answer still the one the reader asked for"
has one answer in the TUI rather than one per section.

## Trash is a topic source

The TUI adds a virtual `KindTrash` source with no box ID. `mail.ReadPage` reads it
through the SDK's `Topics.GetTrashPage`, preserving the opaque `Link` cursor. The
adapter supplies topic IDs as row identities and `readPostingsPage` keeps those as
`TopicID`; they are never posting IDs. Trash rows are already seen so opening one
cannot send a posting observation. All posting mutations are blocked in Trash.
Restoring calls `Topics.Restore` with the topic ID, and removes the row only after
success. A restore response received after switching sources cannot remove a row
from the new source. Trash is excluded from box move destinations.
11 changes: 11 additions & 0 deletions docs/tui.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,17 @@ The Screener keeps up too. When a first-time sender writes, the count above the
changes on its own, and if you have The Screener open the new sender appears in the queue
without moving your place in it.

## Trash

Press `0` or select **Trash** at the end of the mail tab row. The list grows as you
scroll. Enter reads a trashed thread; `i` restores the selected or open thread through
HEY's normal restore action. A successful restore removes it from the Trash list and
closes its open reader. A failed restore leaves it available to retry.

Restore acts on one thread at a time. Trashed threads can be read and their attachments
opened or saved, but filing, replies, labels, bulk selection and trashing again are
unavailable until they are restored. Permanent deletion and Empty Trash are not exposed.

## The Screener

Press Ctrl+S from the mail list to open The Screener. When senders are waiting, the mail
Expand Down
2 changes: 2 additions & 0 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -125,3 +125,5 @@ require (
google.golang.org/protobuf v1.36.12 // indirect
k8s.io/klog/v2 v2.140.0 // indirect
)

replace github.com/basecamp/hey-sdk/go => github.com/WhiskeyTuesday/hey-sdk/go v0.36.1-0.20261121014628-998231a1a7ee
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6
github.com/ProtonMail/go-crypto v1.4.1 h1:9RfcZHqEQUvP8RzecWEUafnZVtEvrBVL9BiF67IQOfM=
github.com/ProtonMail/go-crypto v1.4.1/go.mod h1:e1OaTyu5SYVrO9gKOEhTc+5UcXtTUa+P3uLudwcgPqo=
github.com/RaveNoX/go-jsoncommentstrip v1.0.0/go.mod h1:78ihd09MekBnJnxpICcwzCMzGrKSKYe4AqU6PDYYpjk=
github.com/WhiskeyTuesday/hey-sdk/go v0.36.1-0.20261121014628-998231a1a7ee h1:8h7QOWcDXFIMrNOVS8DvZwafFoZVDaj7xpfxen8CxdY=
github.com/WhiskeyTuesday/hey-sdk/go v0.36.1-0.20261121014628-998231a1a7ee/go.mod h1:g4+w+Htmntp03iF9L7afzWyPVYeQzxFUYONlw9r4R+s=
github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
github.com/alecthomas/chroma/v2 v2.20.0 h1:sfIHpxPyR07/Oylvmcai3X/exDlE8+FA820NTz+9sGw=
Expand Down Expand Up @@ -91,8 +93,6 @@ github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuP
github.com/aymerick/douceur v0.2.0/go.mod h1:wlT5vV2O3h55X9m7iVYN0TBM0NH/MmbLnd30/FjWUq4=
github.com/basecamp/actioncable-client/go/v2 v2.0.2 h1:h2Sl15gj2lI/EX5E0EUxjyYgf0LF9Gn1zqEUInSrUpc=
github.com/basecamp/actioncable-client/go/v2 v2.0.2/go.mod h1:3Y0N9V5LXclT5nQWcPhq/+6rj4eKXgKAX8dx15X8yB8=
github.com/basecamp/hey-sdk/go v0.35.1 h1:azrn9JoilQaQ3QDBtZb4hiROmQFUyEIWWVWFq65wSTw=
github.com/basecamp/hey-sdk/go v0.35.1/go.mod h1:g4+w+Htmntp03iF9L7afzWyPVYeQzxFUYONlw9r4R+s=
github.com/basecamp/mcp v0.0.0-20261119020105-1a6d02c5380a h1:5SI0hmC3B5wLusmAG917J9HGWnU2JLV+S2Ek8A0ABxk=
github.com/basecamp/mcp v0.0.0-20261119020105-1a6d02c5380a/go.mod h1:K3sgTH90CIR6Ed0XPnivIBqNIpw6aeOlcXThBrZ+2gc=
github.com/bmatcuk/doublestar v1.1.1/go.mod h1:UD6OnuiIn0yFxxA2le/rnRU1G4RaI4UvFv1sNto9p6w=
Expand Down
34 changes: 32 additions & 2 deletions internal/mail/page.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ import (
)

// Page is one page of a source's postings. Cursor is whatever the next read needs to
// carry on where this page stopped — a geared_pagination cursor for a label or a
// collection, HEY's own next_history_url for a box — and is empty at the end of the
// carry on where this page stopped — a geared_pagination cursor for a label, a
// collection or Trash, HEY's own next_history_url for a box — and is empty at the end of the
// list. Total is HEY's count of everything in the source, zero where it does not say.
type Page struct {
Postings []generated.Posting
Expand All @@ -23,6 +23,8 @@ type Page struct {
// first page.
func ReadPage(ctx context.Context, client *hey.Client, source Source, cursor string) (Page, error) {
switch source.Kind {
case KindTrash:
return readTrashPage(ctx, client, cursor)
case KindBox:
return readBoxPage(ctx, client, source, cursor)
case KindFolder:
Expand Down Expand Up @@ -208,3 +210,31 @@ func readCollectionPage(ctx context.Context, client *hey.Client, source Source,
}
return Page{Postings: result.Collection.Postings, Cursor: result.NextPage, Total: result.TotalCount}, nil
}

// Trash serves topics, rather than postings. Their topic IDs are list identities
// only: callers must restore through Topics, never dispatch a posting mutation.
func readTrashPage(ctx context.Context, client *hey.Client, cursor string) (Page, error) {
var params *generated.GetTrashTopicsParams
if cursor != "" {
params = &generated.GetTrashTopicsParams{Page: &cursor}
}
result, err := client.Topics().GetTrashPage(ctx, params)
if err != nil {
return Page{}, err
}
if result == nil || result.Topics == nil {
return Page{}, fmt.Errorf("mail: Trash answered no page")
}
page := Page{Cursor: result.NextPage}
for _, topic := range result.Topics.Topics {
created := topic.LatestEntry.CreatedAt
if created.IsZero() {
created = topic.CreatedAt
}
page.Postings = append(page.Postings, generated.Posting{
Id: topic.Id, AppUrl: topic.AppUrl, Name: topic.Name, Summary: topic.LatestEntry.Summary,
Creator: topic.Creator, CreatedAt: created, Seen: true,
})
}
return page, nil
}
5 changes: 3 additions & 2 deletions internal/mail/source.go
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Package mail reads the places HEY keeps postings — a box, a label, a collection, a
// bundle's unseen threads, a contact's threads — through one Source type and one page
// bundle's unseen threads, a contact's threads, or Trash — through one Source type and one page
// read, so a caller never has to know which endpoint a source is served by.
package mail

Expand All @@ -19,11 +19,12 @@ const (
KindCollection Kind = "collection"
KindBundle Kind = "bundle"
KindContact Kind = "contact"
KindTrash Kind = "trash"
)

// Source is a place postings are read from. BoxKind carries HEY's own kind for a box
// (hey.BoxKindImbox and friends), which is what tells the named box routes apart; it is
// empty for a label or a collection.
// empty for the other source kinds.
type Source struct {
Kind Kind
ID int64
Expand Down
2 changes: 1 addition & 1 deletion internal/tui/collections_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ func TestMailViewLoadsAndPagesCollections(t *testing.T) {

loaded := runCmd(v.Init()).(mailSourcesLoadedMsg)
v.Update(loaded)
if len(v.boxes) != 2 || v.boxes[1].Kind != mail.KindCollection {
if len(v.boxes) != 3 || v.boxes[1].Kind != mail.KindCollection {
t.Fatalf("sources = %+v", v.boxes)
}
if cmd := v.SubnavRight(); cmd == nil || !v.seenActive {
Expand Down
70 changes: 59 additions & 11 deletions internal/tui/mail.go
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,9 @@ type mailLinkBody struct {
}

type mailView struct {
vc *viewContext
threadFromTrash bool
trashRestoreID int64
vc *viewContext

boxes []mail.Source
boxIndex int
Expand Down Expand Up @@ -572,6 +574,7 @@ func (v *mailView) Update(msg tea.Msg) (tea.Cmd, bool) {
if opened := v.openedPosting(msg.postingID); opened != nil {
v.threadPosting = *opened
}
v.threadFromTrash = msg.postingID != 0 && v.currentSourceKind() == mail.KindTrash && !v.searchActive && !v.bundleActive && !v.seenActive
v.threadBoxKind = v.postingBoxKind(v.threadPosting)
v.topicName = msg.title
v.entries = msg.entries
Expand Down Expand Up @@ -787,6 +790,9 @@ func (v *mailView) Update(msg tea.Msg) (tea.Cmd, bool) {
}
return notify("Opened attachment " + msg.filename), true

case trashRestoredMsg:
return v.trashRestored(msg), true

case postingActionDoneMsg:
v.finishMutation()
// A move of the open thread leaves it on screen in its new box, so later
Expand Down Expand Up @@ -1092,7 +1098,7 @@ func (v *mailView) HelpBindings() []helpBinding {
bindings = append(bindings, helpBinding{"enter", "open attachment"})
}
}
return bindings
return v.trashHelp(bindings)
}
if v.searchActive {
return []helpBinding{{"enter", "open"}, {"/", "new search"}}
Expand Down Expand Up @@ -1130,7 +1136,7 @@ func (v *mailView) HelpBindings() []helpBinding {
if v.lastBulkReplyID != 0 {
bindings = append(bindings, helpBinding{"ctrl+u", "undo bulk reply"})
}
return modifiersLast(bindings)
return modifiersLast(v.trashHelp(bindings))
}
ignoreBinding := helpBinding{"-", "ignore"}
if selected := v.postingList.selectedPosting(); selected != nil && selected.Muted {
Expand Down Expand Up @@ -1184,7 +1190,7 @@ func (v *mailView) HelpBindings() []helpBinding {
if v.lastBulkReplyID != 0 {
bindings = append(bindings, helpBinding{"ctrl+u", "undo bulk reply"})
}
return modifiersLast(bindings)
return modifiersLast(v.trashHelp(bindings))
}

func (v *mailView) SubnavItems() ([]navItem, int, string, bool) {
Expand Down Expand Up @@ -1251,14 +1257,20 @@ func (v *mailView) SubnavItems() ([]navItem, int, string, bool) {
selected = len(items) - 1
}
}
if v.trashIndex() >= 0 {
items = append(items, navItem{shortcut: "0", label: "Trash"})
if v.currentSourceKind() == mail.KindTrash && !v.seenActive {
selected = len(items) - 1
}
}
return items, selected, label, true
}

// tabBoxIndexes returns the sources shown as their own tabs.
func (v *mailView) tabBoxIndexes() []int {
indexes := make([]int, 0, len(v.boxes))
for i, source := range v.boxes {
if !isOrganizedMailSource(source.Kind) {
if source.Kind == mail.KindBox {
indexes = append(indexes, i)
}
}
Expand Down Expand Up @@ -1308,6 +1320,16 @@ func (v *mailView) SubnavLeft() tea.Cmd {
return nil
}
switch v.currentSourceKind() {
case mail.KindTrash:
if v.hasCollections() {
v.openCollections()
return nil
}
if v.hasLabels() {
v.openLabels()
return nil
}
return v.openPreviouslySeen()
case mail.KindCollection:
if v.hasLabels() {
v.openLabels()
Expand Down Expand Up @@ -1338,20 +1360,23 @@ func (v *mailView) SubnavRight() tea.Cmd {
v.openLabels()
} else if v.hasCollections() {
v.openCollections()
} else {
return v.switchBox(v.trashIndex())
}
return nil
}
switch v.currentSourceKind() {
case mail.KindTrash:
return nil
case mail.KindFolder:
if v.hasCollections() {
v.openCollections()
} else {
v.openLabels()
return v.switchBox(v.trashIndex())
}
return nil
case mail.KindCollection:
v.openCollections()
return nil
return v.switchBox(v.trashIndex())
case mail.KindBox:
tabIndexes := v.tabBoxIndexes()
for i, boxIndex := range tabIndexes {
Expand Down Expand Up @@ -1387,6 +1412,9 @@ func (v *mailView) HandleContentKey(msg tea.KeyPressMsg) tea.Cmd {
if cmd, handled := v.handleLinkKey(msg); handled {
return cmd
}
if cmd, handled := v.handleTrashKey(msg.String()); handled {
return cmd
}
// Enter opens what is selected: a link once Tab has picked one, which
// handleLinkKey has already answered, and otherwise the attachment.
if msg.Key().Code == tea.KeyEnter && len(v.attachments) > 0 {
Expand Down Expand Up @@ -1430,6 +1458,10 @@ func (v *mailView) HandleContentKey(msg tea.KeyPressMsg) tea.Cmd {
return cmd
}

if cmd, handled := v.handleTrashKey(msg.String()); handled {
return cmd
}

if v.searchActive {
switch msg.Key().Code {
case tea.KeyUp:
Expand Down Expand Up @@ -1854,6 +1886,8 @@ func (v *mailView) handleBoxShortcut(key string) tea.Cmd {
v.openCollections()
return func() tea.Msg { return nil }
}
case "0":
return v.switchBox(v.trashIndex())
case "9":
return v.openPreviouslySeen()
}
Expand Down Expand Up @@ -1983,6 +2017,9 @@ func sourceIndex(sources []mail.Source, id int64, kind mail.Kind) int {
func (v *mailView) applySources(sources []mail.Source) tea.Cmd {
currentID, currentKind := v.currentSourceIdentity()
v.boxes = orderBoxes(sources)
if len(sources) > 0 && v.trashIndex() < 0 {
v.boxes = append(v.boxes, mail.Source{Kind: mail.KindTrash, Name: "Trash"})
}
v.requests.loading = false
if len(v.boxes) == 0 {
return nil
Expand Down Expand Up @@ -2192,6 +2229,11 @@ func (v *mailView) requestTopic(boxID, topicID, postingID int64, title string) t
}

func (v *mailView) postingIndex(postingID int64) int {
// Trash identities are topic IDs; a posting completion from an overlaid search
// must never match one just because its numeric ID happens to be the same.
if v.currentSourceKind() == mail.KindTrash {
return -1
}
return postingIndexIn(v.postingList.postings, postingID)
}

Expand Down Expand Up @@ -2813,7 +2855,7 @@ func (v *mailView) openThreadPicker(key string) tea.Cmd {
// label files out of the box it is actually in rather than out of whatever list is
// behind it. Only a topic opened by its id has no row, and nothing to file.
func (v *mailView) fileablePosting() *mail.Posting {
if v.threadPosting.ID == 0 {
if v.threadFromTrash || v.threadPosting.ID == 0 {
return nil
}
return &v.threadPosting
Expand Down Expand Up @@ -3138,7 +3180,7 @@ func threadNoun(count int) string {
// for the same reason. An empty list keeps it, as it always has: there is nothing to
// refuse yet.
func (v *mailView) trashOffered() bool {
return bundlesIn(v.trashTargets()) == 0
return !v.inTrash() && bundlesIn(v.trashTargets()) == 0
}

func bundlesIn(postings []mail.Posting) int {
Expand Down Expand Up @@ -3474,7 +3516,13 @@ func (v *mailView) readPostingsPage(ctx context.Context, source mail.Source, pag
if err != nil {
return nil, "", err
}
return mail.Postings(read.Postings), read.Cursor, nil
postings := mail.Postings(read.Postings)
if source.Kind == mail.KindTrash {
for i := range postings {
postings[i].TopicID = read.Postings[i].Id
}
}
return postings, read.Cursor, nil
}

func (v *mailView) fetchSearchResults(ctx context.Context, requestID uint64, query string, page int) tea.Cmd {
Expand Down
10 changes: 5 additions & 5 deletions internal/tui/mail_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,8 @@ func TestMailViewHandlesBoxesLoaded(t *testing.T) {
if !consumed {
t.Error("boxesLoadedMsg should be consumed")
}
if len(v.boxes) != 3 {
t.Errorf("expected 3 boxes, got %d", len(v.boxes))
if len(v.boxes) != 4 {
t.Errorf("expected 3 boxes plus Trash, got %d sources", len(v.boxes))
}
}

Expand Down Expand Up @@ -1445,7 +1445,7 @@ func TestMailViewLoadsFolderSourcesAndPostings(t *testing.T) {
if !consumed || postingsCmd == nil {
t.Fatal("folder sources should be loaded and start the first mailbox request")
}
if len(v.boxes) != 2 || v.boxes[1].Kind != mail.KindFolder || v.boxes[1].Name != "Receipts" {
if len(v.boxes) != 3 || v.boxes[1].Kind != mail.KindFolder || v.boxes[1].Name != "Receipts" {
t.Fatalf("mail sources = %+v", v.boxes)
}

Expand Down Expand Up @@ -1699,7 +1699,7 @@ func TestMailViewFolderDiscoveryFailurePreservesMailAndRetries(t *testing.T) {

failed := runCmd(v.Init()).(mailSourcesLoadedMsg)
firstPostings, consumed := v.Update(failed)
if !consumed || firstPostings == nil || len(v.boxes) != 1 || v.folderDiscoveryErr == "" {
if !consumed || firstPostings == nil || len(v.boxes) != 2 || v.folderDiscoveryErr == "" {
t.Fatalf("folder failure state = consumed:%v command:%v sources:%+v error:%q", consumed, firstPostings != nil, v.boxes, v.folderDiscoveryErr)
}
if !strings.Contains(v.notice, "press b to retry") {
Expand All @@ -1713,7 +1713,7 @@ func TestMailViewFolderDiscoveryFailurePreservesMailAndRetries(t *testing.T) {
}
recovered := runCmd(retry).(mailSourcesLoadedMsg)
v.Update(recovered)
if v.folderDiscoveryErr != "" || len(v.boxes) != 2 || v.boxes[1].Name != "Receipts" {
if v.folderDiscoveryErr != "" || len(v.boxes) != 3 || v.boxes[1].Name != "Receipts" {
t.Errorf("recovered sources = %+v error=%q", v.boxes, v.folderDiscoveryErr)
}
if v.notice != "" {
Expand Down
2 changes: 1 addition & 1 deletion internal/tui/move.go
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ func newMovePicker(posting mail.Posting, boxes []mail.Source, currentSource mail
destinations := make([]mail.Source, 0, len(boxes))
for _, box := range boxes {
isCurrentSource := box.ID == currentSource.ID && box.Kind == currentSource.Kind
if isOrganizedMailSource(box.Kind) || isCurrentSource || box.BoxKind == hey.BoxKindBubbleUp {
if box.Kind == mail.KindTrash || isOrganizedMailSource(box.Kind) || isCurrentSource || box.BoxKind == hey.BoxKindBubbleUp {
continue
}
destinations = append(destinations, box)
Expand Down
Loading