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"
	"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) {
	gmailID = strings.TrimSpace(gmailID)
	if gmailID == "" {
		return nil, errors.New("empty x-gm-msgid")
	}
	for _, r := range gmailID {
		if r < '0' || r > '9' {
			return nil, errors.New("x-gm-msgid must be numeric")
		}
	}
	var uids []uint32
	err := c.exec("UID SEARCH X-GM-MSGID "+gmailID, 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
}