teems 0.3.2 → 0.8.0

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/models/message.rb

@@ -7,10 +7,13 @@ module Teems
     Message = Data.define(
       :id, :sender_id, :sender_name, :content, :created_at,
       :message_type, :reply_to_id, :reactions, :attachments, :importance,
-      :edited, :mentions
+      :edited, :mentions, :images
     ) do
       extend Parsing
 
+      # `images` (inline AMS images) defaults to empty so callers can omit it
+      def initialize(images: [], **attrs) = super
+
       def self.from_api(data)
         if data['message'] then from_teams_internal_api(data)
         elsif data['imdisplayname'] || data['messagetype'] then from_ng_msg_api(data)
@@ -27,7 +30,7 @@ module Teems
         {
           id: data['id'], sender_id: data['from'],
           sender_name: data['imdisplayname'] || data['fromDisplayNameInToken'] || 'Unknown',
-          content: strip_html(data['content'] || ''),
+          **html_body_attrs(data['content']),
           created_at: parse_time(data['composetime'] || data['originalarrivaltime']),
           message_type: data['messagetype'],
           **ng_msg_extras(data, props)
@@ -57,7 +60,7 @@ module Teems
         new(
           id: data['id'], sender_id: msg['from'],
           sender_name: msg['imDisplayName'] || msg['fromDisplayNameInToken'] || 'Unknown',
-          content: strip_html(msg['content'] || ''),
+          **html_body_attrs(msg['content']),
           created_at: parse_time(msg['composeTime'] || data['latestMessageTime']),
           message_type: msg['type'], reply_to_id: nil, reactions: [],
           attachments: parse_files_json(msg.dig('properties', 'files')),
@@ -74,7 +77,7 @@ module Teems
           id: data['id'],
           sender_id: data.dig('from', 'user', 'id') || data.dig('from', 'application', 'id'),
           sender_name: extract_sender_name(data),
-          content: strip_html(data.dig('body', 'content') || ''),
+          **html_body_attrs(data.dig('body', 'content')),
           created_at: parse_time(data['createdDateTime']),
           **graph_extras(data)
         }

data/lib/teems/models/parsing.rb

@@ -13,6 +13,11 @@ module Teems
         CGI.unescapeHTML(html.gsub(/<[^>]+>/, ' ')).gsub('&nbsp;', ' ').gsub(/\s+/, ' ').strip
       end
 
+      # Plain-text content plus the inline images that strip_html would discard
+      def html_body_attrs(html)
+        { content: strip_html(html || ''), images: InlineImage.parse_html(html) }
+      end
+
       def parse_time(time_str)
         return nil unless time_str
 

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
@@ -72,6 +78,11 @@ module Teems
       Services::TokenRefresher.new(token_store: @token_store, output: @output)
     end
 
+    # Downloader for inline message images; reads the current skype token on each request
+    def inline_image_downloader
+      Services::InlineImageDownloader.new(token_provider: -> { account.skype_token })
+    end
+
     # Attempt to refresh the skype_token
     def refresh_tokens
       token_refresher.refresh

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/inline_image_downloader.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Error responses from AMS, mapped so the caller can fall back or refresh tokens
+    module InlineImageErrors
+      # The requested AMS view does not exist for this object (try another view)
+      class ViewUnavailable < ApiError; end
+
+      MISSING_VIEW_CODES = %w[400 404 410].freeze
+
+      private
+
+      def raise_failure(response)
+        code = response.code
+        status = code.to_i
+        raise ApiError.new('Invalid token or session expired', status_code: 401) if status == 401
+        raise ViewUnavailable.new("HTTP #{code}", status_code: status) if MISSING_VIEW_CODES.include?(code)
+
+        raise ApiError.new("HTTP #{code}", status_code: status)
+      end
+
+      def untrusted_host!(uri)
+        raise Error, "Refusing to send Teams credentials to untrusted image host: #{uri.host}"
+      end
+    end
+
+    # Identifies image bytes by their magic number
+    module ImageSignature
+      SIGNATURES = { 'png' => "\x89PNG".b, 'jpg' => "\xFF\xD8\xFF".b, 'gif' => 'GIF8'.b }.freeze
+
+      module_function
+
+      def extension_for(body)
+        bytes = body.to_s.b
+        found = SIGNATURES.find { |_ext, magic| bytes.start_with?(magic) }&.first
+        found || ('webp' if bytes.start_with?('RIFF') && bytes.byteslice(8, 4) == 'WEBP')
+      end
+    end
+
+    # Fetches inline message images from Teams' AMS object store. AMS accepts the
+    # skype token as `Authorization: skype_token <token>` (Bearer tokens get a 401).
+    # Credentials are only sent over HTTPS to Microsoft Teams/Skype hosts.
+    class InlineImageDownloader
+      include InlineImageErrors
+
+      # Downloaded image bytes, the file extension they imply, and the URL that served them
+      Result = Data.define(:body, :extension, :url)
+
+      TRUSTED_HOST = /(?:\A|\.)(?:asm\.skype\.com|teams\.microsoft\.com|teams\.microsoft\.us)\z/i
+      MAX_REDIRECTS = 3
+      TIMEOUTS = { open_timeout: 10, read_timeout: 60 }.freeze
+
+      # token_provider is called per request so a refreshed skype token is picked up
+      def initialize(token_provider:, http_client: nil)
+        @token_provider = token_provider
+        @http_client = http_client
+      end
+
+      # Prefers the original upload and falls back to the `src` preview when that view is missing
+      def fetch(image)
+        full_size = image.full_size_url
+        preview = image.url
+        fetch_url(full_size)
+      rescue ViewUnavailable
+        raise if full_size == preview
+
+        fetch_url(preview)
+      end
+
+      def self.trusted?(uri) = uri.is_a?(URI::HTTPS) && TRUSTED_HOST.match?(uri.host.to_s)
+
+      private
+
+      def fetch_url(url)
+        uri = URI(url)
+        untrusted_host!(uri) unless self.class.trusted?(uri)
+
+        follow(uri, MAX_REDIRECTS)
+      end
+
+      def follow(uri, redirects_left)
+        response = http_get(uri)
+        case response
+        when Net::HTTPSuccess then build_result(response.body, uri)
+        when Net::HTTPRedirection then follow_redirect(uri, response['location'], redirects_left)
+        else raise_failure(response)
+        end
+      end
+
+      def follow_redirect(uri, location, redirects_left)
+        raise Error, 'Too many redirects' unless redirects_left.positive? && location
+
+        follow(uri + location, redirects_left - 1)
+      end
+
+      def build_result(body, uri)
+        extension = ImageSignature.extension_for(body)
+        raise Error, 'Response was not an image' unless extension
+
+        Result.new(body: body.to_s, extension: extension, url: uri.to_s)
+      end
+
+      # Redirect targets outside Teams/Skype (e.g. a signed CDN URL) get no credentials
+      def http_get(uri)
+        headers = self.class.trusted?(uri) ? { 'Authorization' => "skype_token #{@token_provider.call}" } : {}
+        return @http_client.call(uri, headers) if @http_client
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, **TIMEOUTS) do |http|
+          http.request(Net::HTTP::Get.new(uri, headers))
+        end
+      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

data/lib/teems/services/mail_id_cache.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Remembers full Graph message IDs for the short IDs `teems mail list` and `search` print,
+    # so `teems mail read <short id>` works afterwards. Kept in the XDG cache dir.
+    class MailIdCache
+      MAX_ENTRIES = 2000
+
+      def initialize(paths: Support::XdgPaths.new)
+        @path = paths.cache_file('mail-ids.json')
+      end
+
+      def remember(messages)
+        return if messages.empty?
+
+        # Listed IDs move to the end, so the ones in use are the last evicted
+        listed = messages.to_h { |message| [message.short_id, message.id] }
+        ids = load.except(*listed.keys).merge(listed)
+        FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+        File.write(@path, JSON.generate(ids.to_a.last(MAX_ENTRIES).to_h))
+      end
+
+      # Full ID for a short ID or unique prefix of one (4+ hex digits); full IDs pass through
+      def resolve(token)
+        prefix = self.class.short_prefix(token)
+        return token.to_s.strip unless prefix
+
+        matches = ids_starting_with(prefix)
+        matches.one? ? matches.first : nil
+      end
+
+      # Lowercased short ID (or prefix) for a token that looks like one, else nil
+      def self.short_prefix(token)
+        stripped = token.to_s.strip
+        stripped.match?(/\A\h{4,16}\z/) ? stripped.downcase : nil
+      end
+
+      private
+
+      def ids_starting_with(prefix) = load.select { |short, _id| short.start_with?(prefix) }.values.uniq
+
+      def load
+        data = File.file?(@path) ? JSON.parse(File.read(@path)) : {}
+        data.is_a?(Hash) ? data : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end