teems 0.3.3 → 0.8.0

data/lib/teems/commands/mail_rules.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # Options for `teems mail rules add`
+    module MailRuleOptions
+      FLAGS = { '--mark-read' => :mark_read, '--stop' => :stop, '--delete' => :delete_mail,
+                '--disabled' => :disabled }.freeze
+      VALUES = { '--from' => :from, '--sent-to' => :sent_to, '--subject' => :subject, '--body' => :body,
+                 '--category' => :category, '--move-to' => :move_to, '--copy-to' => :copy_to,
+                 '--importance' => :importance }.freeze
+      # Values that add up when repeated (each one matches, or each category is assigned)
+      REPEATABLE = %i[from sent_to subject body category].freeze
+      KEYS = (FLAGS.values + VALUES.values).freeze
+    end
+
+    # Turns `rules add` options into a Graph messageRule. Only actions that keep mail in the
+    # mailbox exist here: a rule teems builds never forwards or redirects.
+    class MailRuleBuilder
+      CONDITIONS = { from: 'fromAddresses', sent_to: 'sentToAddresses', subject: 'subjectContains',
+                     body: 'bodyContains' }.freeze
+      ADDRESSES = %i[from sent_to].freeze
+      IMPORTANCE = %w[low normal high].freeze
+
+      def initialize(options, folders)
+        @options = options
+        @folders = folders
+      end
+
+      # String keys, as Graph returns rules, so a preview reads like a listed rule
+      def rule(name, sequence:)
+        conditions = self.conditions
+        actions = self.actions
+        raise Error, 'A rule needs a condition: --from, --sent-to, --subject or --body' if conditions.empty?
+        raise Error, 'A rule needs an action: --move-to, --copy-to, --mark-read, --category, --importance or --delete' \
+          if actions.empty?
+
+        { 'displayName' => name, 'sequence' => sequence, 'isEnabled' => !@options[:disabled],
+          'conditions' => conditions, 'actions' => actions }
+      end
+
+      def conditions
+        CONDITIONS.filter_map { |option, key| (values = @options[option]) && [key, condition(option, values)] }.to_h
+      end
+
+      def actions
+        raise Error, 'Use --move-to or --delete, not both' if @options[:move_to] && @options[:delete_mail]
+
+        { 'moveToFolder' => folder_id(:move_to), 'copyToFolder' => folder_id(:copy_to),
+          'markAsRead' => switch(:mark_read), 'assignCategories' => @options[:category],
+          'markImportance' => importance, 'delete' => switch(:delete_mail),
+          'stopProcessingRules' => switch(:stop) }.compact
+      end
+
+      private
+
+      def condition(option, values)
+        return values unless ADDRESSES.include?(option)
+
+        values.map { |address| { 'emailAddress' => { 'address' => address } } }
+      end
+
+      # Rules need the folder's real ID, not a well-known name
+      def folder_id(option)
+        name = @options[option]
+        name && @folders.resolve(name).id
+      end
+
+      def switch(option) = @options[option] || nil
+
+      def importance
+        level = @options[:importance] or return
+        level = level.downcase
+        return level if IMPORTANCE.include?(level)
+
+        raise Error, "--importance must be #{IMPORTANCE.join(', ')}"
+      end
+    end
+
+    # `teems mail rules`: list, add, enable, disable, and delete Inbox rules
+    module MailRules
+      RULE_ACTIONS = { 'list' => :list_rules, 'add' => :add_rule, 'enable' => :enable_rule,
+                       'disable' => :disable_rule, 'delete' => :delete_rule }.freeze
+
+      private
+
+      def mail_rules
+        verb = positional_args[1] || 'list'
+        handler = RULE_ACTIONS[verb]
+        return error("Usage: teems mail rules <#{RULE_ACTIONS.keys.join('|')}> (teems mail --help)") unless handler
+
+        send(handler)
+      end
+
+      def misplaced_rule_options?
+        positional_args.first(2) != %w[rules add] && MailRuleOptions::KEYS.any? { |key| @options.key?(key) }
+      end
+
+      def list_rules
+        rules = fetch_rules
+        formatter = rule_formatter(rules)
+        return json_result(formatter.json(rules)) if @options[:json]
+        return print_lines(formatter.tsv_rows(rules)) if @options[:tsv]
+
+        print_lines(rules.empty? ? [output.gray('No Inbox rules')] : formatter.rows(rules))
+      end
+
+      def add_rule
+        name = Support::ControlChars.strip(positional_args[2].to_s).strip
+        return error('Usage: teems mail rules add <name> <condition>... <action>...') if name.empty?
+
+        body = new_rule(name)
+        @options[:dry_run] ? rule_preview(body) : create_rule(body)
+      end
+
+      # Last in order, under a name no other rule has (so the name can pick it out later)
+      def new_rule(name)
+        rules = fetch_rules
+        raise Error, "A rule named #{name} already exists" if rules.any? { |rule| rule.name.casecmp?(name) }
+
+        MailRuleBuilder.new(@options, mail_folders).rule(name, sequence: rules.map(&:sequence).max.to_i + 1)
+      end
+
+      def rule_preview(body)
+        return json_result(body) if @options[:json]
+
+        rule = Models::MailRule.from_api(body)
+        print_lines(["#{rule.name}: #{rule_formatter([rule]).describe(rule)}",
+                     output.gray('Would add this rule (dry run, nothing changed)')])
+      end
+
+      def create_rule(body)
+        rule = Models::MailRule.from_api(rules_api.create(body))
+        formatter = rule_formatter([rule])
+        return json_result(formatter.json([rule]).first) if @options[:json]
+
+        done("Added rule #{rule.name}: #{formatter.describe(rule)}")
+      end
+
+      def enable_rule = switch_rule(true)
+      def disable_rule = switch_rule(false)
+
+      def switch_rule(enabled)
+        rule = find_rule
+        name = rule.name
+        state = enabled ? 'enabled' : 'disabled'
+        return noted("Rule #{name} is already #{state}") if rule.enabled == enabled
+        raise Error, "Rule #{name} forwards or redirects mail; teems will not enable it" if enabled && rule.forwards?
+
+        rules_api.update(rule.id, { isEnabled: enabled })
+        done("Rule #{name} #{state}")
+      end
+
+      def delete_rule
+        rule = find_rule
+        name = rule.name
+        return noted("Would delete rule #{name} (dry run, nothing changed)") if @options[:dry_run]
+        return error('Cancelled; nothing changed') unless rule_delete_confirmed?(name)
+
+        rules_api.destroy(rule.id)
+        done("Deleted rule #{name}")
+      end
+
+      # Kept for the retry after a token refresh, so the question is not asked twice
+      def rule_delete_confirmed?(name)
+        @rule_delete_confirmed ||= @options[:yes] ||
+                                   confirm?("Delete rule #{name}",
+                                            refusal: "Deleting rule #{name} needs --yes without a terminal")
+      end
+
+      # By ID, then name (ignoring case), then the number `rules` lists
+      def find_rule
+        ref = positional_args[2].to_s.strip
+        raise Error, "Usage: teems mail rules #{positional_args[1]} <name|number|id>" if ref.empty?
+
+        matches = rule_matches(fetch_rules, ref)
+        return matches.first if matches.one?
+        raise Error, "No Inbox rule matches #{ref} (see teems mail rules)" if matches.empty?
+
+        raise Error, "#{matches.length} rules are named #{ref}; use the ID (teems mail rules --tsv)"
+      end
+
+      def rule_matches(rules, ref)
+        [->(rule) { rule.id == ref }, ->(rule) { rule.name.casecmp?(ref) }, ->(rule) { rule.sequence.to_s == ref }]
+          .lazy.map { |test| rules.select(&test) }.find(&:any?) || []
+      end
+
+      def fetch_rules = rules_api.list.map { |data| Models::MailRule.from_api(data) }.sort_by(&:sequence)
+
+      # Folder paths only when a rule moves or copies mail (the folder tree costs requests)
+      def rule_formatter(rules)
+        names = rules.flat_map(&:folder_ids).empty? ? {} : mail_folders.paths_by_id
+        Formatters::MailRuleFormatter.new(output: output, folder_names: names)
+      end
+
+      def done(message) = 0.tap { success(message) }
+      def noted(message) = 0.tap { info(message) }
+      def rules_api = runner.mail_rules_api
+    end
+  end
+end

data/lib/teems/commands/mail_sync.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # `teems mail sync`: incremental local copy of mail folders via Graph delta queries
+    module MailSyncing
+      DEFAULT_SINCE_DAYS = 90
+
+      private
+
+      def sync_mail
+        since = sync_since
+        return error('--since must be a number of days or "all"') if since == :invalid
+
+        store = Services::MailSyncStore.new(**sync_store_args)
+        result = with_private_umask { store.with_lock { sync_folders(store, since) } }
+        return result unless result == :locked
+
+        info('Another teems mail sync is running; skipping')
+        0
+      end
+
+      def sync_store_args
+        dir = @options[:dir]
+        dir ? { root: dir } : {}
+      end
+
+      # Time limiting a folder's first sync, nil for everything, or :invalid
+      def sync_since
+        value = @options.fetch(:since, DEFAULT_SINCE_DAYS.to_s).to_s.strip.downcase
+        return nil if value == 'all'
+
+        days = Integer(value, exception: false)
+        days&.positive? ? Time.now - (days * 86_400) : :invalid
+      end
+
+      def sync_folder_names
+        names = [*positional_args.drop(1), *@options[:folders]]
+        names.empty? ? ['Inbox'] : names.uniq
+      end
+
+      # A folder that fails is reported and skipped so the others still sync; the exit
+      # status is 1 when any failed
+      def sync_folders(store, since)
+        engine = sync_engine(store, since)
+        names = sync_folder_names
+        results = names.filter_map { |name| sync_one(engine, store, name) }.to_h
+        output_json(results) if @options[:json]
+        results.size == names.size ? 0 : 1
+      end
+
+      def sync_engine(store, since)
+        options = { since: since, attachments: @options[:attachments], on_warning: ->(message) { warn(message) } }
+        Services::MailSyncEngine.new(api: mail_api, store: store, options: options)
+      end
+
+      # [path, stats], or nil when the folder failed. Expired tokens are raised for
+      # with_token_refresh; a folder interrupted by anything else, local file errors
+      # included, resumes on the next run.
+      def sync_one(engine, store, name)
+        folder = mail_folders.resolve(name)
+        path = folder.path
+        sync_info("Syncing #{path} -> #{store.folder_dir(path)}")
+        stats = engine.sync(folder)
+        sync_info("  #{sync_summary(stats)}")
+        [path, stats]
+      rescue Teems::Error, SystemCallError => e
+        raise if e.is_a?(ApiError) && token_expired?(e)
+
+        warn("#{name}: #{e.message}")
+        nil
+      end
+
+      # Progress lines go to stdout, so --json leaves them out to keep its output parseable
+      def sync_info(message) = @options[:json] || info(message)
+
+      def sync_summary(stats)
+        created, updated, unchanged, adopted, removed = stats.values_at(*Services::MailSyncFolder::STAT_KEYS)
+        "#{created} new, #{updated} updated, #{unchanged} unchanged, " \
+          "#{adopted} existing files adopted, #{removed} removed from folder"
+      end
+
+      # Synced mail is private: new files and directories are owner-only
+      def with_private_umask
+        previous = File.umask(0o077)
+        yield
+      ensure
+        File.umask(previous)
+      end
+    end
+  end
+end

data/lib/teems/commands/mail_thread.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # `teems mail thread <id>`: every message in a message's conversation, from any folder,
+    # oldest first. --full prints each one as `read` would, and --decrypt opens the S/MIME
+    # ones with the PIV card on the way (see MailDecrypting).
+    module MailThread
+      DIVIDER = '-' * 72
+
+      private
+
+      def show_thread
+        messages = thread_messages(resolve_message_id(thread_token))
+        id_cache.remember(messages)
+        conversation = Models::MailConversation.new(messages: messages, folders: mail_folders.paths_by_id)
+        @options[:full] ? show_full_thread(conversation) : show_thread_list(conversation)
+      end
+
+      def thread_token
+        token = positional_args[1] or raise Error, 'Usage: teems mail thread <id> [--full [--decrypt]]'
+        raise Error, '--decrypt works with --full' if @options[:decrypt] && !@options[:full]
+
+        token
+      end
+
+      def thread_messages(message_id)
+        fields = @options[:full] ? Api::Mail::MESSAGE_FIELDS : Api::Mail::LIST_FIELDS
+        mail_api.conversation(conversation_of(message_id), fields: fields)
+      end
+
+      def conversation_of(message_id)
+        mail_api.conversation_id(message_id) or raise Error, 'That message belongs to no conversation'
+      end
+
+      def show_thread_list(conversation)
+        return json_result(conversation.json(&:to_json_hash)) if @options[:json]
+        return print_lines(conversation.tsv_rows) if @options[:tsv]
+
+        print_lines(mail_formatter.thread_rows(conversation))
+      end
+
+      def show_full_thread(conversation)
+        full = full_conversation(conversation)
+        return json_result(full.full_json) if @options[:json]
+
+        print_lines([full.texts.join("\n\n#{output.gray(DIVIDER)}\n\n")])
+      end
+
+      # With attachment names, and encrypted messages marked (or opened, with --decrypt)
+      def full_conversation(conversation)
+        envelopes = envelopes_in(conversation.messages)
+        full = conversation.with_attachment_names(mail_api).with_locked(envelopes.keys)
+        @options[:decrypt] ? full.with_decrypted(open_envelopes(envelopes)) : full
+      end
+
+      # Message ID => S/MIME envelope (an smime.p7m attachment) for each encrypted message, found
+      # as `read` finds it: Graph hands encrypted mail over with no body
+      def envelopes_in(messages)
+        messages.select(&:envelope_candidate?).each_with_object({}) do |message, found|
+          id = message.id
+          envelope = envelope_attachment(id)
+          found[id] = envelope if envelope
+        end
+      end
+
+      # Message ID => decrypted content for each envelope that opens. One that will not (no
+      # matching key) stays locked with a warning, and the rest carry on.
+      def open_envelopes(envelopes)
+        warn('No S/MIME encrypted messages in this thread') if envelopes.empty?
+        envelopes.each_with_object({}) do |(id, envelope), opened|
+          content = open_envelope(id, envelope)
+          opened[id] = content if content
+        end
+      end
+
+      def open_envelope(message_id, envelope)
+        decrypt_content(message_id, envelope)
+      rescue ApiError
+        raise
+      rescue Error => e
+        warn("#{Models::MailMessage.short_id(message_id)}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/teems/commands/mail_triage.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # Due dates for `teems mail flag --due`: YYYY-MM-DD, today, tomorrow, or a weekday name
+    # (the next one, today included; three letters are enough)
+    module MailDueDate
+      WEEKDAYS = %w[sunday monday tuesday wednesday thursday friday saturday].freeze
+
+      def self.parse(text, today: Date.today)
+        word = text.to_s.strip.downcase
+        relative(word, today) || weekday(word, today) || Date.iso8601(word)
+      rescue Date::Error
+        nil
+      end
+
+      def self.relative(word, today) = { 'today' => today, 'tomorrow' => today + 1 }[word]
+
+      def self.weekday(word, today)
+        day = WEEKDAYS.index { |name| name.start_with?(word) } if word.length >= 3
+        day && (today + ((day - today.wday) % 7))
+      end
+    end
+
+    # Messages for `teems mail` triage: named by ID, or selected with --search or --folder
+    module MailSelection
+      # Graph's $search returns at most 1,000 messages; folder selections stop there too
+      BULK_MAX = 1000
+      # Where --thread leaves the rest of a conversation alone: your own messages, and ones already put away
+      THREAD_SKIPS = %w[sentitems drafts deleteditems junkemail].freeze
+
+      # Message IDs to act on; a selection (not IDs given by hand) also has the messages
+      Targets = Data.define(:ids, :messages, :selected) do
+        def self.named(ids) = new(ids: ids, messages: [], selected: false)
+        def self.selected(messages) = new(ids: messages.map(&:id), messages: messages, selected: true)
+
+        def count = ids.length
+        def empty? = ids.empty?
+        def short_ids = ids.map { |id| Models::MailMessage.short_id(id) }
+        def to_json_hash = selected ? { messages: messages.map(&:to_json_hash) } : { ids: ids }
+      end
+
+      private
+
+      def triage_targets
+        ids = positional_args.drop(1)
+        check_selection(ids)
+        return selected_targets if selecting?
+        raise Error, "Usage: teems mail #{triage_action} <id>... (or --search QUERY, --folder NAME)" if ids.empty?
+
+        named = ids.map { |token| resolve_message_id(token) }
+        @options[:thread] ? thread_targets(named) : Targets.named(named)
+      end
+
+      def selecting? = @options[:search] || @options[:folders]
+
+      def check_selection(ids)
+        check_thread
+        raise Error, 'Give message IDs or --search/--folder, not both' if selecting? && ids.any?
+        return if only_filters.empty? || (@options[:folders] && !@options[:search])
+
+        raise Error, '--unread and --flagged select with --folder alone'
+      end
+
+      def selected_targets
+        messages = @options[:search] ? search_selection : folder_selection
+        id_cache.remember(messages)
+        Targets.selected(messages)
+      end
+
+      def check_thread
+        raise Error, '--thread works with message IDs, not --search or --folder' if @options[:thread] && selecting?
+      end
+
+      # The named messages and the rest of their conversations, except what sits in THREAD_SKIPS
+      def thread_targets(named)
+        skipped = thread_skipped_folders
+        kept = mail_api.conversations_of(named).select do |message|
+          named.include?(message.id) || !skipped.include?(message.folder_id)
+        end
+        id_cache.remember(kept)
+        Targets.selected(kept)
+      end
+
+      def thread_skipped_folders
+        folders = mail_folders
+        THREAD_SKIPS.map { |name| folders.resolve(name).id }
+      end
+
+      def search_selection
+        folder = @options[:folders]&.last
+        mail_api.search(query: @options[:search], count: bulk_limit, folder: folder && mail_folders.resolve_id(folder))
+      end
+
+      def folder_selection
+        folder = mail_folders.resolve_id(@options[:folders].last)
+        mail_api.messages(folder: folder, count: bulk_limit, only: only_filters)
+      end
+
+      def bulk_limit
+        limit = @options[:limit] || BULK_MAX
+        raise Error, "-n must be between 1 and #{BULK_MAX}" unless limit.between?(1, BULK_MAX)
+
+        limit
+      end
+
+      def resolve_message_id(token)
+        id_cache.resolve(token) or
+          raise Error, "Unknown message ID: #{token} (run teems mail list, or pass the full ID)"
+      end
+    end
+
+    # mark-read, mark-unread, flag, unflag, archive, move, and delete for `teems mail`. A
+    # selection is confirmed first (or --yes), and --dry-run lists what would change without
+    # changing it.
+    module MailTriage
+      include MailSelection
+
+      # What to do, as [phrase for --dry-run and the prompt, phrase once done]
+      ACTIONS = {
+        'mark-read' => ['mark %<count>s read', 'Marked %<count>s read'],
+        'mark-unread' => ['mark %<count>s unread', 'Marked %<count>s unread'],
+        'flag' => ['flag %<count>s', 'Flagged %<count>s'],
+        'unflag' => ['unflag %<count>s', 'Unflagged %<count>s'],
+        'archive' => ['archive %<count>s', 'Archived %<count>s'],
+        'move' => ['move %<count>s to %<folder>s', 'Moved %<count>s to %<folder>s'],
+        'delete' => ['move %<count>s to Deleted Items', 'Moved %<count>s to Deleted Items']
+      }.freeze
+      # The change each action makes, as [:update, properties] or [:move, destination]
+      CHANGES = {
+        'mark-read' => [:update, { isRead: true }], 'mark-unread' => [:update, { isRead: false }],
+        'unflag' => [:update, { flag: { flagStatus: 'notFlagged' } }],
+        'archive' => %i[move archive], 'delete' => %i[move deleteditems]
+      }.freeze
+
+      private
+
+      def triage
+        change = triage_change
+        targets = triage_targets
+        return triage_preview(targets) if @options[:dry_run]
+        return 0.tap { info('No messages matched') } if targets.empty?
+        return error('Cancelled; nothing changed') unless confirmed?(targets)
+
+        triage_report(apply_change(change, targets.ids), targets)
+      end
+
+      def triage_action = positional_args.first
+
+      # [:update, properties] or [:move, destination folder]
+      def triage_change
+        action = triage_action
+        raise Error, '--due works with flag only' if @options[:due] && action != 'flag'
+        raise Error, '--to works with move only' if @options[:to] && action != 'move'
+
+        return [:update, flag_value] if action == 'flag'
+
+        CHANGES.fetch(action) { [:move, move_destination] }
+      end
+
+      def move_destination
+        name = @options[:to] or raise Error, 'Usage: teems mail move <id>... --to <folder>'
+        mail_folders.resolve_id(name)
+      end
+
+      def flag_value
+        due_text = @options[:due]
+        return { flag: { flagStatus: 'flagged' } } unless due_text
+
+        due = MailDueDate.parse(due_text) or
+          raise Error, "Unknown due date: #{due_text} (use YYYY-MM-DD, today, tomorrow, or a weekday)"
+        { flag: { flagStatus: 'flagged', startDateTime: graph_date([Date.today, due].min),
+                  dueDateTime: graph_date(due) } }
+      end
+
+      def graph_date(date) = { dateTime: "#{date.iso8601}T00:00:00", timeZone: detect_timezone }
+
+      # A selection needs --yes, or a "y" at the prompt; messages named by ID go ahead
+      def confirmed?(targets)
+        return true if @confirmed || !targets.selected || @options[:yes]
+
+        @confirmed = answered_yes?(targets.count)
+      end
+
+      def answered_yes?(count)
+        confirm?(triage_phrase(0, count).sub(/\A./, &:upcase),
+                 refusal: "#{count_text(count)} selected; pass --yes to go ahead (or --dry-run to list them)")
+      end
+
+      # { done: [ids], failed: { id => message } }. An expired token stops the run, so the retry
+      # after a refresh starts over (every action is safe to repeat)
+      def apply_change(change, ids)
+        kind, value = change
+        actions = runner.mail_actions
+        ids.each_with_object({ done: [], failed: {} }) do |id, result|
+          actions.public_send(kind, id, value)
+          result[:done] << id
+        rescue ApiError => e
+          raise if token_expired?(e)
+
+          result[:failed][id] = e.message
+        end
+      end
+
+      def triage_preview(targets)
+        return json_result({ action: triage_action, dry_run: true, **targets.to_json_hash }) if @options[:json]
+
+        rows = targets.selected ? mail_formatter.message_rows(targets.messages) : targets.short_ids
+        print_lines(rows)
+        info("Would #{triage_phrase(0, targets.count)} (dry run, nothing changed)")
+        0
+      end
+
+      def triage_report(result, targets)
+        done, failed = result.values_at(:done, :failed)
+        return triage_json(done, failed) if @options[:json]
+
+        success(triage_phrase(1, done.length)) if done.any?
+        failed.each { |id, message| warn("#{Models::MailMessage.short_id(id)}: #{message}") }
+        note_cap(targets)
+        failed.empty? ? 0 : error("#{count_text(failed.length)} failed")
+      end
+
+      def triage_json(done, failed)
+        output_json(action: triage_action, done: done, failed: failed.map { |id, message| { id: id, error: message } })
+        failed.empty? ? 0 : 1
+      end
+
+      def note_cap(targets)
+        limit = targets.selected && bulk_limit
+        info("Stopped at #{limit} messages; run again (or raise -n) for the rest") if limit && targets.count >= limit
+      end
+
+      def triage_phrase(index, count)
+        format(ACTIONS.fetch(triage_action)[index], count: count_text(count), folder: @options[:to])
+      end
+
+      def count_text(count) = count == 1 ? '1 message' : "#{count} messages"
+    end
+  end
+end