email_agent/internal/mailfetch/imap_write.go

// IMAP write operations for triage actions (Phase 4, FR-6/FR-9).
//
// The read path selects INBOX and fetches messages. The write path adds the
// operations a move needs: create the destination label, locate a message in
// the mailbox it currently lives in (Gmail gives each label its own UID, so the
// stable X-GM-MSGID is used), move it, and set or clear flags.
//
// Deletes are never hard-deletes: a "delete" is a move to a recoverable label.
package mailfetch

import (
	"errors"
	"fmt"
	"strconv"
	"strings"
)

// ErrMailboxExists is returned by CreateMailbox only when the server reports
// something other than "already exists".
var ErrMailboxExists = errors.New("mailbox already exists")

// CreateMailbox creates an IMAP mailbox (a Gmail label). An already-existing
// mailbox is not an error: triage creates "Delete" and "Saved" lazily.
func (c *Client) CreateMailbox(name string) error {
	err := c.exec("CREATE "+imapQuote(name), nil)
	if err == nil {
		return nil
	}
	var se *ServerError
	if errors.As(err, &se) {
		upper := strings.ToUpper(se.Response)
		if strings.Contains(upper, "ALREADYEXISTS") ||
			strings.Contains(upper, "ALREADY EXISTS") ||
			strings.Contains(upper, "MAILBOX EXISTS") {
			return nil
		}
	}
	return err
}

// Move moves a message to dest using the IMAP MOVE extension (RFC 6851, which
// Gmail supports). If the server rejects MOVE, it falls back to COPY followed
// by a source-side delete so the destination copy remains recoverable.
func (c *Client) Move(uid uint32, dest string) error {
	id := strconv.FormatUint(uint64(uid), 10)
	if err := c.exec("UID MOVE "+id+" "+imapQuote(dest), nil); err == nil {
		return nil
	} else {
		var se *ServerError
		if !errors.As(err, &se) {
			return err
		}
	}
	if err := c.exec("UID COPY "+id+" "+imapQuote(dest), nil); err != nil {
		return err
	}
	if err := c.exec("UID STORE "+id+" +FLAGS (\\Deleted)", nil); err != nil {
		return err
	}
	return c.Expunge(uid)
}

// Expunge removes a \Deleted message from the selected mailbox. UIDPLUS
// (RFC 4315) keeps the expunge scoped to one UID; the plain EXPUNGE fallback is
// only used by servers that do not advertise it.
func (c *Client) Expunge(uid uint32) error {
	id := strconv.FormatUint(uint64(uid), 10)
	if err := c.exec("UID EXPUNGE "+id, nil); err == nil {
		return nil
	} else {
		var se *ServerError
		if !errors.As(err, &se) {
			return err
		}
	}
	return c.exec("EXPUNGE", nil)
}

// StoreFlags adds (op "+") or removes (op "-") message flags.
func (c *Client) StoreFlags(uid uint32, op string, flag string) error {
	if op != "+" && op != "-" {
		return errors.New("flag operation must be + or -")
	}
	id := strconv.FormatUint(uint64(uid), 10)
	return c.exec("UID STORE "+id+" "+op+"FLAGS ("+flag+")", nil)
}

// SearchGmailID returns the UIDs of the messages with the given Gmail message
// id (X-GM-MSGID) in the currently selected mailbox. Gmail assigns a different
// UID per label, so this is how a message is located after a move.
func (c *Client) SearchGmailID(gmailID string) ([]uint32, error) {
	return c.searchNumeric("X-GM-MSGID", gmailID)
}

// SearchGmailThreadID returns the UIDs of the messages in the given Gmail
// thread (X-GM-THRID) in the currently selected mailbox. Phase 5 uses it to
// confirm that a reply landed in the same thread as the original message.
func (c *Client) SearchGmailThreadID(threadID string) ([]uint32, error) {
	return c.searchNumeric("X-GM-THRID", threadID)
}

// searchNumeric runs a UID SEARCH for a numeric Gmail extension key.
func (c *Client) searchNumeric(key, value string) ([]uint32, error) {
	value = strings.TrimSpace(value)
	if value == "" {
		return nil, fmt.Errorf("empty %s", strings.ToLower(key))
	}
	for _, r := range value {
		if r < '0' || r > '9' {
			return nil, fmt.Errorf("%s must be numeric", strings.ToLower(key))
		}
	}
	var uids []uint32
	err := c.exec("UID SEARCH "+key+" "+value, func(resp *response) error {
		if !strings.HasPrefix(strings.ToUpper(resp.line), "* SEARCH") {
			return nil
		}
		fields := strings.Fields(resp.line)
		for _, f := range fields[2:] {
			if n, err := strconv.ParseUint(f, 10, 32); err == nil {
				uids = append(uids, uint32(n))
			}
		}
		return nil
	})
	return uids, err
}