teems 0.3.3 → 0.8.0

data/lib/teems/models/event.rb

@@ -24,6 +24,7 @@ module Teems
       :event_type
     ) do
       extend Parsing
+      include EventDisplay
 
       def self.from_api(data)
         new(**event_attrs(data))
@@ -90,29 +91,6 @@ module Teems
       def cancelled? = is_cancelled
       def recurring? = %w[occurrence exception].include?(event_type)
 
-      def time_range_display
-        return 'ALL DAY' if all_day?
-        return '' unless start_time && end_time
-
-        "#{start_time.strftime('%H:%M')}-#{end_time.strftime('%H:%M')}"
-      end
-
-      def date_display
-        if all_day?
-          "#{start_time&.strftime('%Y-%m-%d')} (all day)"
-        elsif start_time && end_time
-          "#{start_time.strftime('%Y-%m-%d %H:%M')}-#{end_time.strftime('%H:%M')}"
-        end
-      end
-
-      def create_summary_lines
-        lines = []
-        lines << date_display if date_display
-        lines << "Location: #{location}" if location && !location.empty?
-        lines << "Teams link: #{online_meeting_url}" if online_meeting_url
-        lines
-      end
-
       def required_attendees = attendees.select { |att| att[:type] == 'required' }
       def optional_attendees = attendees.select { |att| att[:type] == 'optional' }
       def accepted_attendees = attendees.select { |att| att[:response] == 'accepted' }

data/lib/teems/models/event_display.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # Date and time labels for an Event (expects start_time, end_time, all_day?, location, online_meeting_url)
+    module EventDisplay
+      def time_range_display
+        return 'ALL DAY' if all_day?
+        return '' unless start_time && end_time
+
+        "#{start_time.strftime('%H:%M')}-#{end_time.strftime('%H:%M')}"
+      end
+
+      def date_display
+        if all_day?
+          "#{all_day_span} (all day)"
+        elsif start_time && end_time
+          "#{start_time.strftime('%Y-%m-%d %H:%M')}-#{end_time.strftime('%H:%M')}"
+        end
+      end
+
+      # Graph ends all-day events at midnight after the last day, so a span is "first to last"
+      def all_day_span
+        first_day = start_time&.to_date
+        last_day = end_time&.to_date&.prev_day
+        return first_day.to_s unless first_day && last_day && last_day > first_day
+
+        "#{first_day} to #{last_day}"
+      end
+
+      def create_summary_lines
+        lines = []
+        lines << date_display if date_display
+        lines << "Location: #{location}" if location && !location.empty?
+        lines << "Teams link: #{online_meeting_url}" if online_meeting_url
+        lines
+      end
+    end
+  end
+end

data/lib/teems/models/ics_event.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # A calendarView event as `teems cal ics` exports it. Built from Graph data requested
+    # with Prefer: outlook.timezone="UTC", so timed events carry UTC times and all-day
+    # events carry their (floating) dates.
+    IcsEvent = Data.define(:uid, :subject, :starts, :ends, :all_day, :location, :organizer, :attendees,
+                           :body, :join_url, :status) do
+      def self.from_api(data)
+        new(uid: data['iCalUId'] || data['id'], subject: data['subject'].to_s, **time_attrs(data),
+            location: data.dig('location', 'displayName').to_s, organizer: Event.parse_organizer(data['organizer']),
+            attendees: Event.parse_attendees(data['attendees']), body: data['body'] || {},
+            join_url: data.dig('onlineMeeting', 'joinUrl').to_s, status: status_attrs(data))
+      end
+
+      # Dates for all-day events (Graph sends their midnights without a zone), UTC Times otherwise
+      def self.time_attrs(data)
+        all_day = data['isAllDay'] || false
+        parser = all_day ? :graph_date : :graph_utc
+        { starts: send(parser, data['start']), ends: send(parser, data['end']), all_day: all_day }
+      end
+
+      def self.graph_date(value) = graph_stamp(value) { |stamp| Date.parse(stamp) }
+
+      def self.graph_utc(value) = graph_stamp(value) { |stamp| Time.parse("#{stamp.delete_suffix('Z')}Z").utc }
+
+      def self.graph_stamp(value)
+        stamp = Hash(value)['dateTime']
+        stamp && yield(stamp)
+      rescue ArgumentError
+        nil
+      end
+
+      def self.status_attrs(data) = { cancelled: data['isCancelled'] || false, show_as: data['showAs'].to_s }
+
+      def dated? = [starts, ends].all?
+
+      def cancelled? = status[:cancelled]
+
+      def free? = status[:show_as] == 'free'
+
+      # Plain-text body, links listed at the end
+      def description
+        content = body['content'].to_s
+        body['contentType'] == 'html' ? Formatters::HtmlText.convert(content).to_s : content.strip
+      end
+
+      # True when one of addresses organizes the event or has accepted it, so it is already
+      # on that address's own calendar. An invitation alone does not count.
+      def involves?(addresses)
+        return false if addresses.empty?
+
+        accepted = attendees.select { |attendee| attendee[:response] == 'accepted' }
+        [Hash(organizer)[:email], *accepted.map { |attendee| attendee[:email] }]
+          .any? { |email| addresses.include?(email.to_s.downcase) }
+      end
+    end
+  end
+end

data/lib/teems/models/mail_conversation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # A conversation's messages (oldest first), Graph folder ID => path for naming the folder
+    # each one sits in (a thread spans the Inbox, Sent Items, Archive and so on), message ID =>
+    # attachment names once with_attachment_names has fetched them, and message ID => how a
+    # decrypted message was opened (see MailEncryption)
+    MailConversation = Data.define(:messages, :folders, :attachments, :encryptions) do
+      def initialize(messages:, folders:, attachments: {}, encryptions: {}) = super
+
+      def folder(message) = folders[message.folder_id]
+
+      def with_attachment_names(api)
+        with(attachments: messages.to_h { |message| [message.id, message.attachment_names_from(api)] })
+      end
+
+      # Marks these messages S/MIME encrypted and not opened; the envelope is not listed as a file
+      def with_locked(message_ids)
+        no_files = message_ids.to_h { |id| [id, []] }
+        locked = no_files.transform_values { { type: 'smime', decrypted: false } }
+        with(encryptions: encryptions.merge(locked), attachments: attachments.merge(no_files))
+      end
+
+      # opened: message ID => Services::SmimeContent::Result for each message decrypted
+      def with_decrypted(opened)
+        with(messages: messages.map { |message| opened[message.id]&.apply_to(message) || message },
+             attachments: attachments.merge(opened.transform_values(&:attachment_names)),
+             encryptions: encryptions.merge(opened.transform_values { |content| MailEncryption.decrypted(content) }))
+      end
+
+      # Each message's JSON (from the block) with its folder path
+      def json = messages.map { |message| yield(message).merge(folder: folder(message)) }
+
+      # As `read --json` gives each message, plus its folder
+      def full_json
+        json do |message|
+          encryption = encryption(message)
+          hash = message.full_json_hash(attachments: names(message))
+          encryption ? hash.merge(encryption: encryption) : hash
+        end
+      end
+
+      # As `read` prints each message, with its folder (and how it was protected) before the ID
+      def texts = messages.map { |message| message.to_text(attachments: names(message), notes: notes(message)) }
+
+      # list's tab-separated columns plus the folder path
+      def tsv_rows = messages.map { |message| "#{message.tsv_row}\t#{folder(message).to_s.tr("\t", ' ')}" }
+
+      private
+
+      def names(message) = attachments.fetch(message.id, [])
+
+      def encryption(message) = message.encryption_in(encryptions)
+
+      def notes(message)
+        protection = MailEncryption.notes(encryption(message), web_link: message.web_link)
+        { 'Folder' => folder(message) }.compact.merge(protection)
+      end
+    end
+  end
+end

data/lib/teems/models/mail_encryption.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # How protected mail was shown, as { type: 'smime' | 'purview', decrypted:, signed: } (signed
+    # only once decrypted), and the header lines `read` and `thread --full` print for it. Purview
+    # mail gets its Outlook on the web link, where Exchange decrypts it for you.
+    module MailEncryption
+      LOCKED_HINT = 'S/MIME encrypted; read it with --decrypt (macOS asks for your PIV PIN)'
+
+      # 'purview' (rights-managed, Content-Class rpmsg.message), 'smime' (an S/MIME envelope),
+      # or nil, from a message's internet headers. Drafts have none, and Exchange wraps most
+      # S/MIME mail as TNEF (see envelope?), so nil is not proof of plain mail.
+      def self.from_headers(headers)
+        fields = Array(headers).to_h { |header| [header['name'].to_s.downcase, header['value'].to_s.downcase] }
+        return 'purview' if fields['content-class'].to_s.start_with?('rpmsg.message')
+
+        type, params = Support::MimeHeader.field(fields['content-type'])
+        'smime' if Support::MimePart::PKCS7_TYPES.include?(type) && params['smime-type'] != 'signed-data'
+      end
+
+      def self.notes(encryption, web_link: nil)
+        return {} unless encryption
+
+        type = encryption[:type]
+        return { 'Encryption' => MailMessage::PROTECTION_NOTES[type], 'Open' => web_link }.compact if type == 'purview'
+        return { 'Encryption' => LOCKED_HINT } unless encryption[:decrypted]
+
+        { 'Encryption' => 'S/MIME, decrypted', 'Signature' => encryption[:signed] ? 'Signed (not checked)' : '' }
+          .reject { |_name, value| value.empty? }
+      end
+
+      def self.decrypted(content) = { type: 'smime', decrypted: true, signed: content.signed }
+
+      # An S/MIME envelope (smime.p7m) among a message's Graph attachments
+      def self.envelope?(attachment)
+        Support::MimePart::PKCS7_TYPES.include?(Support::MimeHeader.field(attachment['contentType']).first)
+      end
+    end
+  end
+end

data/lib/teems/models/mail_folder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # A mail folder from Microsoft Graph (/me/mailFolders); path joins parent names with "/"
+    MailFolder = Data.define(:id, :name, :path, :unread_count, :total_count, :child_count) do
+      def self.from_api(data, parent_path: nil)
+        name = data['displayName'].to_s
+        new(id: data['id'], name: name, path: [parent_path, name].compact.join('/'),
+            unread_count: data['unreadItemCount'].to_i, total_count: data['totalItemCount'].to_i,
+            child_count: data['childFolderCount'].to_i)
+      end
+
+      # The folder whose full path is name, else the one whose display name is (both ignore
+      # case), or nil. A display name several folders share raises rather than guessing.
+      def self.find_named(folders, name)
+        matches = matching(folders, name)
+        return matches.first unless matches.length > 1
+
+        raise Error, "Mail folder name is ambiguous: #{name} matches #{matches.map(&:path).join(', ')} " \
+                     '(use the full path)'
+      end
+
+      def self.matching(folders, name)
+        wanted = name.strip
+        candidates = folders.select { |folder| folder.named?(wanted) }
+        by_path = candidates.select { |folder| folder.path.casecmp?(wanted) }
+        by_path.empty? ? candidates : by_path
+      end
+
+      def to_json_hash = to_h
+
+      def tsv_row = [path, unread_count, total_count].join("\t")
+
+      # Matches a display name or full path, ignoring case
+      def named?(wanted) = [path, name].any? { |candidate| candidate.casecmp?(wanted) }
+
+      def id_and_path = [id, path]
+
+      # [id, path] to list this folder's children with, or nil when it has none
+      def child_lookup = child_count.positive? ? [id, path] : nil
+    end
+  end
+end

data/lib/teems/models/mail_message.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # A mail message from Microsoft Graph (/me/messages). Text a sender controls is kept free
+    # of terminal control characters (see Support::ControlChars), whichever way it is shown.
+    MailMessage = Data.define(
+      :id, :subject, :from, :to, :cc, :received_at, :is_read, :has_attachments, :flagged,
+      :categories, :body_type, :body, :internet_message_id, :web_link, :protection, :folder_id
+    ) do
+      extend Parsing
+
+      def self.from_api(data)
+        new(**header_attrs(data), **body_attrs(data))
+      end
+
+      def self.header_attrs(data)
+        { id: data['id'], subject: clean(data['subject']), from: recipient(data['from']),
+          to: recipients(data['toRecipients']), cc: recipients(data['ccRecipients']),
+          received_at: parse_time(data['receivedDateTime']), is_read: data['isRead'] == true,
+          has_attachments: data['hasAttachments'] == true, flagged: Hash(data['flag'])['flagStatus'] == 'flagged' }
+      end
+
+      def self.body_attrs(data)
+        body = data['body'] || {}
+        { categories: Array(data['categories']).map { |category| clean(category) },
+          body_type: body['contentType'].to_s.downcase, body: clean(body['content']),
+          internet_message_id: data['internetMessageId'], web_link: data['webLink'],
+          protection: MailEncryption.from_headers(data['internetMessageHeaders']), folder_id: data['parentFolderId'] }
+      end
+
+      def self.recipient(data)
+        email = Hash(data)['emailAddress'] || {}
+        { name: clean(email['name']), address: clean(email['address']) }
+      end
+
+      def self.clean(text) = Support::ControlChars.strip(text)
+
+      def self.recipients(list) = Array(list).map { |entry| recipient(entry) }
+
+      # Names of the attachments a person attached (inline images left out)
+      def self.attachment_names(attachments)
+        attachments.reject { |item| item['isInline'] }.map { |item| clean(item['name']) }
+      end
+
+      # Short handle shown in lists; `teems mail read` accepts it after a list or search
+      def short_id = self.class.short_id(id)
+
+      def self.short_id(id) = Digest::SHA256.hexdigest(id.to_s)[0, 8]
+
+      def read? = is_read
+      def status = is_read ? 'Read' : 'Unread'
+      def html? = body_type == 'html'
+
+      # What to show instead of a protected message's body, or nil for plain mail
+      def protection_note = self.class::PROTECTION_NOTES[protection]
+
+      # { type:, decrypted: false } for protected mail, as `read --json` has it (see MailEncryption); else nil
+      def encryption = protection && { type: protection, decrypted: false }
+
+      # How this message was shown when overrides (message ID => encryption) say, else #encryption
+      def encryption_in(overrides) = overrides.fetch(id) { encryption }
+
+      # Names of attached files, fetched through api only if there are any
+      def attachment_names_from(api) = files? ? self.class.attachment_names(api.attachments(id)) : []
+
+      # An S/MIME message's one attachment is its envelope, not a file
+      def files? = has_attachments && protection != 'smime'
+
+      # True for S/MIME encrypted mail, which Graph returns with no body (the envelope is an attachment)
+      def bodyless? = body.strip.empty?
+
+      # Graph says it has attachments, or it may hide an S/MIME envelope
+      def attachments_to_list? = has_attachments || envelope_candidate?
+
+      # Worth looking for an S/MIME envelope: no body, and not Purview. Exchange often wraps
+      # encrypted mail as TNEF, so neither its headers nor hasAttachments give it away.
+      def envelope_candidate? = bodyless? && protection != 'purview'
+
+      def from_label = self.class.label(from)
+      def from_display = self.class.display(from)
+      def to_display = to.map { |entry| self.class.display(entry) }.join(', ')
+      def cc_display = cc.map { |entry| self.class.display(entry) }.join(', ')
+
+      def self.label(entry)
+        name = entry[:name]
+        name.empty? ? entry[:address] : name
+      end
+
+      def self.display(entry)
+        name, address = entry.values_at(:name, :address)
+        return address if name.empty? || name == address
+        return name if address.empty?
+
+        "#{name} <#{address}>"
+      end
+
+      # Plain-text body with a links footer; plain-text messages come back unchanged
+      def text_body
+        return Formatters::HtmlText.convert(body) if html?
+
+        Formatters::HtmlText::Result.new(text: body.gsub("\r\n", "\n").rstrip, footer: '')
+      end
+
+      # short id, received (local), sender, one-line subject
+      def list_columns
+        [short_id, Formatters::MailDates.short(received_at), from_label, subject.tr("\r\n", '  ')]
+      end
+
+      # Tab-separated: full id, received (ISO 8601 local), sender address, subject, Read/Unread
+      def tsv_row
+        [id, Formatters::MailDates.iso(received_at), from[:address], subject, status]
+          .map { |field| field.to_s.tr("\t\r\n", '   ') }.join("\t")
+      end
+
+      # Header lines for `teems mail read`, in Outlook's order; Cc, Categories and Attachments
+      # only when present. notes (e.g. Encryption) go just before the ID.
+      def headers(attachments: [], notes: {})
+        cc_line = cc_display
+        names = attachments.join(', ')
+        { 'Subject' => subject, 'From' => from_display, 'To' => to_display, 'Cc' => cc_line,
+          'Date' => Formatters::MailDates.long(received_at), 'Categories' => categories.join(', '),
+          'Status' => status, 'Attachments' => names, **notes, 'ID' => id }
+          .reject { |name, value| value.empty? && %w[Cc Categories Attachments].include?(name) }
+      end
+
+      # `teems mail read` output: header block, blank line, plain-text body with links at the end
+      def to_text(attachments: [], notes: {})
+        lines = headers(attachments: attachments, notes: notes).map { |name, value| "#{name}: #{value}" }
+        [*lines, '', text_body.to_s].join("\n")
+      end
+
+      # JSON for `teems mail read --json`: summary plus plain-text body and links
+      def full_json_hash(attachments: [])
+        text = text_body
+        to_json_hash.merge(body: text.text, links: text.footer, attachments: attachments)
+      end
+
+      def to_json_hash
+        { id: id, short_id: short_id, subject: subject, from: from, to: to, cc: cc,
+          received_at: received_at&.iso8601, is_read: is_read, has_attachments: has_attachments, flagged: flagged,
+          categories: categories, internet_message_id: internet_message_id, web_link: web_link }
+      end
+    end
+
+    # Constants set inside Data.define's block would land on Models, so they go here
+    MailMessage::PROTECTION_NOTES = {
+      'purview' => 'Protected by Purview; open in Outlook on the web',
+      'smime' => 'S/MIME encrypted; read it with teems mail read --decrypt'
+    }.freeze
+  end
+end

data/lib/teems/models/mail_rule.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # An Inbox rule from Microsoft Graph. conditions, exceptions and actions keep Graph's shape
+    # (camelCase keys) because they are passed back unchanged and described as they are.
+    MailRule = Data.define(:id, :name, :sequence, :enabled, :has_error, :conditions, :exceptions, :actions) do
+      def self.from_api(data)
+        new(id: data['id'], name: Support::ControlChars.strip(data['displayName'].to_s),
+            sequence: data['sequence'].to_i, enabled: data['isEnabled'] == true, has_error: data['hasError'] == true,
+            conditions: data['conditions'] || {}, exceptions: data['exceptions'] || {},
+            actions: data['actions'] || {})
+      end
+
+      # Rules that send mail on; teems lists them but will not turn them on
+      def forwards? = actions.keys.intersect?(MAIL_RULE_SENDING_ACTIONS)
+
+      def folder_ids = actions.values_at('moveToFolder', 'copyToFolder').compact
+
+      def state
+        return 'error' if has_error
+
+        enabled ? 'on' : 'off'
+      end
+
+      def columns = [sequence, state, name]
+
+      def tsv_row(description) = [id, sequence, state, name, description].join("\t")
+
+      def to_json_hash(description)
+        { id: id, name: name, sequence: sequence, enabled: enabled, has_error: has_error,
+          description: description, conditions: conditions, exceptions: exceptions, actions: actions }
+      end
+    end
+
+    MAIL_RULE_SENDING_ACTIONS = %w[forwardTo forwardAsAttachmentTo redirectTo].freeze
+  end
+end

data/lib/teems/runner.rb

@@ -8,6 +8,12 @@ module Teems
     def chats_api = Api::Chats.new(api_client, account)
     def messages_api = Api::Messages.new(api_client, account)
     def calendar_api = Api::Calendar.new(api_client, account)
+    def mail_api = Api::Mail.new(api_client, account)
+    def mail_actions = Api::MailActions.new(api_client, account)
+    def mail_rules_api = Api::MailRules.new(api_client, account)
+    def smime_decryptor = @smime_decryptor ||= Services::SmimeDecryptor.new
+    def browser = @browser ||= Services::Browser.new
+    def clipboard = @clipboard ||= Services::Clipboard.new
     def users_api = Api::Users.new(api_client, account)
     def files_api = Api::Files.new(api_client, account)
   end

data/lib/teems/services/api_client.rb

@@ -47,20 +47,22 @@ module Teems
 
     # POST/PATCH request methods, extracted to manage class size
     module WriteRequests
+      # options: account:, and optionally body: (sent as JSON) and headers:
       def post(endpoint_key, path, **options)
-        account = options.delete(:account)
-        body = options.delete(:body)
-        req = Net::HTTP::Post.new(URI("#{resolve_endpoint(endpoint_key)}#{path}"))
-        apply_auth(req, account, endpoint_key)
-        req.body = JSON.generate(body) if body
-        run_request(path, get_http_for_endpoint(endpoint_key)) { |http| http.request(req) }
+        send_body(Net::HTTP::Post, options.merge(endpoint: endpoint_key, path: path))
       end
 
       def patch(endpoint_key, path, **options)
-        account = options.delete(:account)
-        body = options.delete(:body)
-        req = Net::HTTP::Patch.new(URI("#{resolve_endpoint(endpoint_key)}#{path}"))
-        apply_auth(req, account, endpoint_key)
+        send_body(Net::HTTP::Patch, options.merge(endpoint: endpoint_key, path: path))
+      end
+
+      private
+
+      def send_body(request_class, request)
+        endpoint_key, path, body = request.values_at(:endpoint, :path, :body)
+        req = request_class.new(URI("#{resolve_endpoint(endpoint_key)}#{path}"))
+        apply_headers(req, request.fetch(:headers, {}))
+        apply_auth(req, request[:account], endpoint_key)
         req.body = JSON.generate(body) if body
         run_request(path, get_http_for_endpoint(endpoint_key)) { |http| http.request(req) }
       end
@@ -83,10 +85,20 @@ module Teems
         when Net::HTTPTooManyRequests then raise_rate_limit(response)
         else
           code = response.code
-          raise ApiError.new("HTTP #{code}: #{response.message}", status_code: code.to_i)
+          raise ApiError.new("HTTP #{code}: #{response.message}",
+                             status_code: code.to_i, error_code: error_code(response.body))
         end
       end
 
+      # Graph explains a 4xx as {"error": {"code": ...}}; other services may not
+      def error_code(body)
+        text = body.to_s
+        error = JSON.parse(text)['error'] if text.start_with?('{')
+        error['code'] if error.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+
       def raise_rate_limit(response)
         retry_after = response['Retry-After']
         suffix = retry_after ? "retry after #{retry_after} seconds" : 'please wait and try again'

data/lib/teems/services/browser.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Opens a URL in the default browser with macOS's `open`
+    class Browser
+      def open(url)
+        _out, errors, status = Support::Subprocess.capture3('open', url)
+        raise Error, "Could not open the browser: #{errors.strip}" unless status.success?
+
+        url
+      rescue Errno::ENOENT
+        raise Error, 'Opening a browser needs the macOS open command'
+      end
+    end
+  end
+end

data/lib/teems/services/clipboard.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Copies text to the macOS clipboard with pbcopy
+    class Clipboard
+      def copy(text)
+        _out, errors, status = Support::Subprocess.capture3('pbcopy', stdin_data: text)
+        raise Error, "Could not copy to the clipboard: #{errors.strip}" unless status.success?
+
+        text
+      rescue Errno::ENOENT
+        raise Error, 'Copying needs the macOS pbcopy command'
+      end
+    end
+  end
+end

data/lib/teems/services/mail_folders.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Resolves mail folder names ("Inbox", "Sent Items", "Projects/EERT") to Graph folders.
+    # Well-known folders resolve without listing the mailbox; other names match a folder's
+    # display name or full path, case-insensitively.
+    class MailFolders
+      WELL_KNOWN = {
+        'inbox' => 'inbox', 'archive' => 'archive', 'drafts' => 'drafts', 'outbox' => 'outbox',
+        'sent' => 'sentitems', 'sent items' => 'sentitems', 'sentitems' => 'sentitems',
+        'deleted' => 'deleteditems', 'deleted items' => 'deleteditems', 'deleteditems' => 'deleteditems',
+        'trash' => 'deleteditems', 'junk' => 'junkemail', 'junk email' => 'junkemail', 'junkemail' => 'junkemail'
+      }.freeze
+      # Graph folder IDs are long base64url strings; nothing a person names a folder looks like one
+      FOLDER_ID = /\A[A-Za-z0-9_=-]{60,}\z/
+
+      def initialize(api)
+        @api = api
+        @all = nil
+      end
+
+      # Every folder, depth first, with "/"-joined paths
+      def all
+        @all ||= walk(@api.folders, nil)
+      end
+
+      # ID usable in a /me/mailFolders/{id} path, without a lookup where possible
+      def resolve_id(name)
+        well_known = well_known(name)
+        return well_known if well_known
+        return name if name.match?(FOLDER_ID)
+
+        resolve(name).id
+      end
+
+      # Graph folder ID => path, for naming folders other responses refer to by ID
+      def paths_by_id = all.to_h(&:id_and_path)
+
+      def resolve(name)
+        known = well_known(name)
+        return fetch(known) if known
+        return by_id(name) if name.match?(FOLDER_ID)
+
+        find(name)
+      end
+
+      private
+
+      def well_known(name) = WELL_KNOWN[name.to_s.strip.downcase]
+
+      def fetch(id) = Models::MailFolder.from_api(@api.folder(id))
+
+      # A folder fetched by ID alone has no parent path (and so a different sync directory
+      # than by name), so look for it in the tree first
+      def by_id(id) = all.find { |folder| folder.id == id } || fetch(id)
+
+      def find(name)
+        Models::MailFolder.find_named(all, name) or
+          raise Error, "Mail folder not found: #{name} (run: teems mail folders)"
+      end
+
+      def walk(items, parent_path)
+        items.flat_map do |data|
+          folder = Models::MailFolder.from_api(data, parent_path: parent_path)
+          [folder, *children(folder)]
+        end
+      end
+
+      def children(folder)
+        parent_id, path = folder.child_lookup
+        parent_id ? walk(@api.folders(parent_id: parent_id), path) : []
+      end
+    end
+  end
+end