teems 0.3.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdc6ea71a9d23f39629fd24d240992925cca1482b53b69df377a84870d66367f
-  data.tar.gz: 1d563de02f05c8a120130e3e792b508bbf4d1b2467937951a63f2a3efbb19410
+  metadata.gz: 85e10318e8ea5814ce7caeec5186ec86589ac7cbc6a1400e5174cdbd7a4112af
+  data.tar.gz: 0bab10db1f970e7d45ca782ae8ac9d52ef866b5691be6105c2be0d0f89c251be
 SHA512:
-  metadata.gz: 8c903fdae8e9946614e093ab4370e74abc03f7fab0d0a76509da02d07814e0083382f4a8f46e0e9131dd1eb3b16f0c36c5eeb96bb381778679bb92028574ad13
-  data.tar.gz: b3e6ff9fa9ec3adb9708a3ab97b30929d53a820e9d6239daaf4d359cee179c32448b306a7ac3ab26f336aa3c723402868a1206711637af791a974aa0e3f0e832
+  metadata.gz: 79a9bbeb61fa5b1dd8f7fe7ce73d300694bdc53fdf263c64c067ae78a6e4d8fa530e4b518f86b1c7d2af9a401c6a4f85a6f16ab8f94eb9f53f2c73273fbbc56e
+  data.tar.gz: 6fb30e2bf57862725981303e3818448e666c6aa1a0ecc0e1e81063e818d401ef010adcf45dfd575fbd600a9add0356b02552bd063d01dce8d5507e16390a939a

data/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [0.8.0] - 2026-10-28
+
+### Added
+- `teems meet [minutes]` puts a Teams meeting on your calendar, starting now for 30 minutes unless `--at` and the minutes say otherwise, and prints its join link alone on stdout. `--title` names it, it opens the link here to join, since people from organizations yours does not trust wait in the lobby until a member of yours joins (`--no-open` skips that), `--copy` copies the link, and `--json` gives the event. `--with` invites people after asking, since Exchange emails each an invitation (`--yes` skips the question).
+- `teems cal create --start now`, and `--start` may be left out for now.
+
+## [0.7.0] - 2026-10-28
+
+### Added
+- `teems mail thread <id>` lists every message in a message's conversation, from any folder, oldest first, with the folder each sits in (`--tsv`, `--json`). `--full` prints them all as `read` does, Purview and S/MIME labels included, and `--full --decrypt` opens the S/MIME messages with the PIV card on the way.
+- `--thread` on the triage commands (`mark-read`, `flag`, `archive`, `move`, `delete` and the rest) takes in the rest of each named message's conversation, skipping messages in Sent Items, Drafts, Deleted Items and Junk Email unless named. It is confirmed like a selection, and `--dry-run` lists it.
+
+- `teems mail open <id>` opens a message in Outlook on the web, which can show Purview protected mail; `--print` prints the link instead.
+
+### Changed
+- Purview protected mail now reads "Protected by Purview; open in Outlook on the web", and `read`, `thread --full` and synced Markdown give its Outlook on the web link (an `Open:` line in the headers), where Exchange decrypts it.
+
+### Fixed
+- `teems mail sync` now labels S/MIME encrypted mail that Exchange wraps as TNEF, which is most of it: its headers do not say S/MIME and Graph reports no attachments, so sync lists the attachments of a message with no body and looks for an `smime.p7m` envelope. The envelope is not listed or saved as a file. Files synced before keep their old content until the message changes.
+
+## [0.6.0] - 2026-10-27
+
+### Added
+- `teems mail rules` lists Inbox rules with what each does, and `rules add`, `enable`, `disable` and `delete` manage them. A new rule takes conditions (`--from`, `--sent-to`, `--subject`, `--body`) and actions (`--move-to`, `--copy-to`, `--mark-read`, `--category`, `--importance`, `--delete`, `--stop`), and `--dry-run` shows it first. Rules never forward or redirect mail, and a forwarding rule made elsewhere is not turned on.
+- `teems mail read --decrypt` opens S/MIME encrypted mail with the PIV card (or any keychain identity) through macOS's `security cms -D`, which asks for the PIN. The decrypted message shows like any other: HTML or text body, links, attachment names, and a note when it was also signed (the signature is unwrapped, not checked). Plaintext never touches the disk. Without `--decrypt`, an encrypted message is labelled instead of showing an empty body.
+- Purview (rights-managed) mail is labelled "Protected by Purview; open in Outlook" in `teems mail read` (`encryption` in `--json`), and synced Markdown of protected mail gets that note above the body plus a `protection:` frontmatter field. Graph's `hasAttachments` is unreliable for such mail, so protection is read from the internet headers, which makes a full sync download more.
+
+### Changed
+- `teems mail read` leaves out the `Categories:` line when a message has none.
+
+## [0.5.0] - 2026-10-26
+
+### Added
+- `teems mail` triage: `mark-read`, `mark-unread`, `flag` (with `--due YYYY-MM-DD`, `today`, `tomorrow` or a weekday), `unflag`, `archive`, `move --to FOLDER`, and `delete` (to Deleted Items; nothing is purged). They take message IDs, or a selection: `--search QUERY` (optionally in `--folder`) or `--folder NAME` with `--unread`/`--flagged`, up to 1,000 messages. A selection asks before changing anything (`--yes` skips the question, and without a terminal is required), and `--dry-run` lists the messages instead. One message failing does not stop the rest. Nothing sends mail.
+- `teems mail list --flagged` lists flagged messages, and the table marks them.
+
+## [0.4.0] - 2026-10-20
+
+### Added
+- `teems mail`, read-only Outlook mail over Microsoft Graph with the same tokens as the rest of teems. `list [folder] [count]` (alias `recent`) shows the newest messages, with `--unread` for unread only. `read <id>` prints headers and a plain-text body with a numbered list of links (tracking redirects such as Safe Links unwrapped), or the raw HTML with `--html`. `folders` shows unread and total counts, and `search <query>` runs a KQL `$search`, optionally limited to one folder. List and search IDs are short handles that `read` accepts. Reading a message does not mark it read.
+- `teems mail sync [folder...]` keeps one Markdown file per message plus an `index.json` per folder, fetching only changes after the first run (Graph delta). It is safe to run from launchd: `--no-login` never opens Safari, a lock prevents overlapping runs, and the index is only rewritten when something changed. Messages that leave a folder keep their file and get `removed_at` in the index. Files written by the AppleScript outlook-cli sync in the same directory are adopted, matched on received time, subject and sender, instead of being duplicated. `--attachments` also downloads file attachments.
+- `teems cal ics` prints the calendar as an iCalendar feed (default 7 days back through 60 ahead; `--days`, `--days-back`), with attendees, responses, descriptions and Teams join links. `--exclude-attendee` leaves out events given addresses organize or have accepted, `--name` sets the calendar name, and `--no-login` keeps it from opening Safari. `--all-calendars` adds the user's other calendars; one that refuses access (free/busy rights only, owner gone) is skipped with a warning, but the default calendar never is. This replaces the outlook-cli calendar feed, which stopped updating when Outlook lost EWS.
+
+### Fixed
+- `teems sync` no longer merges different chats into one folder. Folder names used to identify generic chats ("Group Chat", "1:1 Chat") by the first 20 characters of the chat ID, which every 1:1 chat with the same person starts with, and named chats by their title alone. New chats, and chats whose title or type changes, now get a folder name ending with the chat's full ID. A name already used by another chat is never handed out, and a name that would still clash (IDs differing only in letter case on a case-insensitive filesystem) falls back to the ID plus a hash.
+- 1:1 chats are classified as 1:1 chats (`dms/`, "1:1 Chat") instead of group chats.
+- Piping a command into something that stops reading early (`teems help | head`) exits quietly instead of printing "Unexpected error: Broken pipe" and logging it. The same holds when stderr's reader is gone.
+- Started without a locale (launchd, `env -i`), teems read its files as US-ASCII and failed on any non-ASCII name it had saved, and arguments with accents matched nothing. It now reads files and arguments as UTF-8 regardless of locale.
+
+### Changed
+- Existing chat folders keep their names when only one chat uses them, so links into the sync folder keep working. 1:1 chats an older version filed under `groups/` move to `dms/`. `teems sync --migrate-dirs` renames every folder to the full-ID naming and writes an old to new map to `sync/dir-maps/`.
+- `teems sync` detaches folders that an older version gave to more than one chat that has synced into them. The folders and their files are left untouched (the path is recorded as `legacy_shared_dir` in `sync_state.json`). Each affected chat gets its own folder and re-fetches history back to the oldest message in the old folder, or `--since` days if that is earlier. `teems sync --chat ID` only detaches that chat. Chats that never synced don't count toward a folder being shared.
+- `teems sync` lists each folder move as old → new, warns when the new folder already exists and the old one is left in place, and keeps listing old shared folders while they are still on disk. `teems sync --dry-run` previews every folder move and detach without changing anything.
+
+## [0.3.4] - 2026-10-05
+
+### Added
+- `teems cal create --all-day --end YYYY-MM-DD` creates one multi-day all-day event. `--end` is the last day, inclusive (like `teems ooo --end`), so `--date 2026-11-12 --end 2026-11-13` covers both days. Leaving out `--end` still creates a single-day event.
+- `teems cal create --all-day --start YYYY-MM-DD` works as an alias for `--date`.
+
+### Changed
+- `teems cal create --all-day` now rejects options it used to silently ignore: `--duration`, an `--end` before the first day, a time of day in `--start` or `--end`, and `--date` combined with `--start`.
+- The created-event summary shows the date range of a multi-day all-day event (`2026-11-12 to 2026-11-13 (all day)`).
+
+### Fixed
+- `teems cal --help` examples that continue onto a second line render as two lines instead of being run together.
+
+## [0.3.3] - 2026-10-02
+
+### Added
+- Inline images (screenshots pasted into a message) are no longer dropped when message HTML is stripped. `teems messages` lists them under the message, and `--json` includes an `images` array with the AMS URL, full-size URL, alt text, and dimensions.
+- `teems messages --download` saves inline images alongside file attachments, fetching the original-resolution AMS view (falling back to the message's preview URL) with the skype token. The token is only sent to Teams/AMS hosts over HTTPS and is dropped on redirects elsewhere.
+- `teems sync` records inline images in `messages.json` and renders `[image: alt (WxH)]` placeholders in `messages.md`. `teems sync --images` downloads them into each chat's `images/` directory, links them from `messages.md`, and backfills already-synced chats.
+
+### Fixed
+- `teems messages <teams-url>` for a message in a group or 1:1 chat no longer fails with "Failed to fetch message"; those chats have no reply threads, so the replies endpoint's 404 now means no replies.
+- `teems messages --json <teams-url>` no longer crashes with "no implicit conversion from nil to integer" after printing the thread.
+
 ## [0.3.2] - 2026-09-29
 
 ### Added

data/README.md

@@ -47,17 +47,98 @@ teems cal show 3             # View details for event #3
 teems cal accept 3           # Accept event #3
 teems cal decline 3          # Decline event #3
 teems cal create "Standup" --start "tomorrow 09:00" --attendees alice@example.com
+teems cal create "PTO" --all-day --date 2026-11-12 --end 2026-11-13 --show-as oof
+teems cal create "Pairing" --teams   # Starts now (the default), 30 minutes
 teems cal delete 3           # Delete event #3
 ```
 
+`--start` defaults to now and takes `now` too; the end defaults to 30 minutes later.
+
+#### Instant Teams meetings
+
+```bash
+teems meet                           # A Teams meeting now, 30 minutes; prints the link and joins here
+teems meet 60 --title "Pairing"      # An hour
+teems meet --copy                    # Also copy the link
+teems meet --no-open | pbcopy        # Just the link
+teems meet --at 14:30 --with alice@example.com   # Asks before inviting (--yes skips)
+```
+
+`teems meet` puts a Teams meeting on your calendar and prints its join link alone on stdout (`teems meet | pbcopy` works; `--json` gives the event too). With nobody invited, nothing is sent; `--with` invites people, and since Exchange emails each an invitation it asks first. It also opens the link here to join (`--no-open` skips that), because people from organizations yours does not trust wait in the lobby until a member of yours joins: setting "Everyone" to bypass the lobby in Meeting options does not change that, and neither does inviting them. Once you are in you can admit them, and the meeting usually carries on after you leave.
+
+All-day events cover `--date` (or `--start YYYY-MM-DD`; default today). Add `--end YYYY-MM-DD` for a multi-day event: like `teems ooo --end`, it is the last day of the event, inclusive. The example above is one event covering November 12 and 13.
+
+#### ICS feed
+
+```bash
+teems cal ics > work.ics                       # 7 days back through 60 days ahead
+teems cal ics --days 30 --days-back 0          # A different window
+teems cal ics --exclude-attendee me@other.example --name "Work" --no-login
+```
+
+`teems cal ics` prints your calendar as an iCalendar file, for a local server that Calendar.app subscribes to. Every occurrence of a recurring meeting is its own event. Events keep their invitees, responses and description, and Teams meetings carry their join link (`URL`, `CONFERENCE`) so Calendar.app shows a Join button. Cancelled meetings are marked `STATUS:CANCELLED` and free time is `TRANSP:TRANSPARENT`. It reads your default calendar; `--all-calendars` adds the others (holidays, shared calendars), keeping an event that is on two of them once and skipping, with a warning, a shared calendar you cannot read. `--exclude-attendee` leaves out events those addresses organize or have accepted, such as ones already on another calendar you subscribe to. `--no-login` never opens Safari: expired tokens are renewed silently from the cached sign-in session when possible, and otherwise the command fails, which is what you want from launchd or a server.
+
+### Mail
+
+```bash
+teems mail list                     # 20 newest Inbox messages (alias: recent)
+teems mail list Archive 50 --unread # Folder and count, unread only
+teems mail read 3fa2c1              # Headers, plain-text body, numbered links
+teems mail read 3fa2c1 --html       # Raw HTML body
+teems mail read 3fa2c1 --decrypt    # S/MIME encrypted mail, opened with your PIV card
+teems mail thread 3fa2c1            # Its whole conversation, any folder, oldest first
+teems mail thread 3fa2c1 --full     # Every message in it, as read prints them
+teems mail thread 3fa2c1 --full --decrypt  # Opening the S/MIME ones with your PIV card
+teems mail open 3fa2c1              # In Outlook on the web (--print prints the link)
+teems mail folders                  # Unread and total counts
+teems mail search "from:alice subject:report" --folder Inbox
+teems mail sync Inbox "Sent Items" --since 30
+teems mail list --flagged           # Flagged messages
+```
+
+Triage changes a message's read state or flag, or moves it. Name messages by ID, or select them with `--search` (optionally within `--folder`) or `--folder` with `--unread`/`--flagged`:
+
+```bash
+teems mail mark-read 3fa2c1 9b0e44            # mark-unread for the reverse
+teems mail flag 3fa2c1 --due friday           # unflag clears it
+teems mail archive 3fa2c1
+teems mail move 3fa2c1 --to Projects/EERT
+teems mail delete 3fa2c1                      # To Deleted Items, never purged
+teems mail archive 3fa2c1 --thread            # The whole conversation (asks first)
+teems mail archive --search "from:jira" --dry-run   # List what would move
+teems mail mark-read --folder Inbox --unread --yes
+```
+
+teems never sends mail, and reading a message does not mark it read. Message IDs in `list` and `search` output are short handles that `read` and the triage commands accept (`--tsv` prints the full Graph IDs). `search` and `--search` use Graph's KQL `$search`. A selection is confirmed before anything changes (or pass `--yes`) and stops at 1,000 messages (`-n` for fewer). `delete` moves messages to Deleted Items, as Outlook does. `thread` finds a conversation's messages in every folder and names the folder each sits in. `--thread` takes in the rest of each named message's conversation, except what sits in Sent Items, Drafts, Deleted Items or Junk Email, so archiving a thread leaves your replies and deleted mail where they are. It counts as a selection: confirmed first, or listed with `--dry-run`.
+
+Inbox rules, which Exchange applies as mail arrives:
+
+```bash
+teems mail rules                                   # In order: number, on/off, name, what it does
+teems mail rules add Jira --from jira@example.com --move-to Projects/Jira --mark-read --stop
+teems mail rules add Builds --subject "build failed" --category Red --dry-run
+teems mail rules disable Jira                      # By name, number, or ID; enable turns it on
+teems mail rules delete Jira                       # Asks first; --yes skips
+```
+
+A new rule needs at least one condition (`--from`, `--sent-to`, `--subject`, `--body`, each repeatable) and one action (`--move-to`, `--copy-to`, `--mark-read`, `--category`, `--importance`, `--delete` to Deleted Items, `--stop`). It goes last in order, and `--disabled` adds it turned off. teems never creates a rule that forwards or redirects mail, and won't turn on an existing one that does.
+
+S/MIME encrypted mail reaches Graph with an empty body, so `read` labels it (`Encryption:` in the headers, `encryption` in `--json`) instead of showing nothing. `--decrypt` opens it with macOS's `security cms -D`, which finds the matching key in your keychain or on your PIV card (the current key management key or a retired one) and asks for the PIN in the system dialog. The ciphertext and plaintext travel over pipes, never to disk, and `sync` never decrypts. `thread --full --decrypt` opens every S/MIME message in a conversation the same way; one that none of your keys opens is shown locked, with a warning, and the rest still print. A signed message inside is unwrapped but its signature is not checked. Mail protected by Microsoft Purview (`message.rpmsg`, "Do Not Forward") uses Microsoft's rights management service rather than certificates, so `read` labels it "Protected by Purview; open in Outlook on the web" and adds an `Open:` line with the message's Outlook on the web link, where Exchange decrypts it for you; `teems mail open <id>` goes straight there. Synced copies of protected mail carry the same note above the body and a `protection:` field (`purview` or `smime`) in the frontmatter.
+
+`teems mail sync` keeps a Markdown copy of each message in `~/.local/share/teems/sync/mail/<Folder>/` (or `--dir`) with an `index.json` per folder. The first run of a folder fetches `--since` days (default 90, or `all`); later runs fetch only what changed, using Graph delta links stored in `~/.local/state/teems/mail-sync.json`. Messages that leave the folder keep their file and are marked `removed_at` in the index. `--attachments` also saves file attachments. A lock file keeps overlapping runs (launchd) from colliding. Syncing into a directory filled by the older AppleScript-based outlook-cli sync adopts its files instead of writing duplicates.
+
 ### Messages
 
 ```bash
 teems messages <chat-id>                    # Read from a chat
 teems messages <channel-id> -t <team-id>    # Read from a channel
 teems messages <chat-id> -n 50              # Show more messages
+teems messages <chat-id> --json             # JSON, including inline image refs
+teems messages <chat-id> --download         # Save attachments and pasted images
 ```
 
+Screenshots pasted into a message are listed under it (`🖼️ image (881x179)`) and included in `--json` as `images` (AMS `url`, `full_size_url`, `alt`, `width`, `height`). `--download` saves the original-resolution image to the downloads directory as `image-<hash>-<n>.<ext>`, using your Teams skype token. The token is only sent to Teams/AMS hosts over HTTPS.
+
 ### Channels and Chats
 
 ```bash
@@ -151,8 +232,11 @@ teems activity                        # Show activity feed
 
 ```bash
 teems sync             # Sync chat history locally
+teems sync --images    # Also save pasted images beside each chat
 ```
 
+Each chat gets `messages.md`, `messages.json`, and `chat_metadata.json` under `~/.local/share/teems/sync/chats/`. Inline images are recorded in `messages.json` and rendered in `messages.md` as `[image: alt (WxH)]`. With `--images`, they are downloaded to the chat's `images/` directory (named by AMS object id, so each is fetched once) and `messages.md` links the saved copy instead. `--images` also rewrites already-synced chats so images in older messages are backfilled.
+
 ## Global Options
 
 | Option | Description |

data/bin/teems

@@ -1,7 +1,14 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# launchd and `env -i` start teems without a locale, where Ruby reads files (tokens, sync
+# indexes, legacy mail) as US-ASCII and fails on the first accented name, and passes
+# arguments as raw bytes, so "Événements" matches no folder. Everything teems reads, writes
+# and is given is UTF-8.
+Encoding.default_external = Encoding::UTF_8
+args = ARGV.map { |arg| arg.dup.force_encoding(Encoding::UTF_8) }
+
 $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
 require 'teems'
 
-exit Teems::CLI.new(ARGV).run
+exit Teems::CLI.new(args).run

data/lib/teems/api/calendar.rb

@@ -16,6 +16,14 @@ module Teems
         responseStatus sensitivity
       ].join(',').freeze
 
+      # The default calendar's view; #feed_events never skips it
+      DEFAULT_VIEW = '/v1.0/me/calendarView'
+      FEED_HEADERS = { 'Prefer' => 'outlook.timezone="UTC", IdType="ImmutableId"' }.freeze
+      FEED_SELECT = %w[
+        id iCalUId subject start end location isAllDay organizer attendees
+        body onlineMeeting showAs isCancelled
+      ].join(',').freeze
+
       # List events in a date range using CalendarView
       def list_events(time_range:, top: 50)
         params = calendar_view_params(time_range[:start_dt], time_range[:end_dt], top)
@@ -23,6 +31,29 @@ module Teems
         paginate_events('/v1.0/me/calendarView', params: params, headers: headers)
       end
 
+      # Every event (each occurrence of a series on its own) between two Times, for `teems cal ics`,
+      # from the default calendar or the given views (calendarView path => calendar name, see
+      # #calendar_views). Times come back in UTC and IDs are immutable, so UIDs stay stable
+      # between exports. An event on two calendars is kept once. Given a block, a calendar
+      # other than the default one that refuses its events (403 or 404: free/busy rights only,
+      # or its owner left) is yielded by name with the error and left out, instead of failing
+      # the whole feed.
+      def feed_events(from:, to:, views: { DEFAULT_VIEW => 'Calendar' }, &unreadable)
+        params = { 'startDateTime' => from.utc.iso8601, 'endDateTime' => to.utc.iso8601,
+                   '$select' => FEED_SELECT, '$orderby' => 'start/dateTime', '$top' => 250 }
+        views.flat_map { |path, name| view_events(path, name, params, &unreadable) }.uniq(&:uid)
+      end
+
+      # calendarView path => name for every calendar (holidays, shared ones). The default
+      # calendar comes first, as DEFAULT_VIEW, so its copy of an event on two calendars is the
+      # one kept and it is never skipped.
+      def calendar_views
+        params = { '$select' => 'id,name,isDefaultCalendar' }
+        collect_pages(get('/v1.0/me/calendars', params: params))
+          .sort_by { |calendar| calendar['isDefaultCalendar'] ? 0 : 1 }
+          .to_h { |calendar| [calendar_view_path(calendar), calendar['name'].to_s] }
+      end
+
       # Get a single event by ID with full details
       def get_event(event_id:, timezone:)
         encoded_id = URI.encode_www_form_component(event_id)
@@ -67,27 +98,27 @@ module Teems
       end
 
       def paginate_events(path, params:, headers:)
-        events = []
-        response = get(path, params: params, headers: headers)
-        collect_paginated_events(events, response, headers)
+        collect_pages(get(path, params: params, headers: headers), headers: headers).map { |data| Models::Event.from_api(data) }
       end
 
-      def collect_paginated_events(events, response, headers)
-        loop do
-          events.concat(parse_events(response))
-          next_link = response['@odata.nextLink']
-          break events unless next_link
+      def calendar_view_path(calendar)
+        return DEFAULT_VIEW if calendar['isDefaultCalendar']
 
-          response = get(next_link, headers: headers)
-        end
+        "/v1.0/me/calendars/#{URI.encode_www_form_component(calendar['id'])}/calendarView"
       end
 
-      def timezone_header(timezone)
-        { 'Prefer' => "outlook.timezone=\"#{timezone}\"" }
+      def view_events(path, name, params)
+        collect_pages(get(path, params: params, headers: FEED_HEADERS), headers: FEED_HEADERS)
+          .map { |data| Models::IcsEvent.from_api(data) }
+      rescue ApiError => e
+        raise unless block_given? && path != DEFAULT_VIEW && (e.forbidden? || e.not_found?)
+
+        yield name, e
+        []
       end
 
-      def parse_events(response)
-        (response['value'] || []).map { |data| Models::Event.from_api(data) }
+      def timezone_header(timezone)
+        { 'Prefer' => "outlook.timezone=\"#{timezone}\"" }
       end
     end
   end

data/lib/teems/api/client.rb

@@ -19,12 +19,13 @@ module Teems
         @api.get(endpoint, path, account: @account, params: params, headers: headers)
       end
 
-      def post(path, body: nil)
-        @api.post(endpoint, path, account: @account, body: body)
+      # options: body: (sent as JSON) and headers:
+      def post(path, **)
+        @api.post(endpoint, path, account: @account, **)
       end
 
-      def patch(path, body: nil)
-        @api.patch(endpoint, path, account: @account, body: body)
+      def patch(path, **)
+        @api.patch(endpoint, path, account: @account, **)
       end
 
       def post_to(target_endpoint, request)
@@ -34,6 +35,20 @@ module Teems
       def delete(path)
         @api.delete(endpoint, path, account: @account)
       end
+
+      # The items of a Graph collection from its first response, following @odata.nextLink
+      # (sent with the same headers) until the last page, or until limit items are in hand
+      # (no page is fetched past them)
+      def collect_pages(response, headers: {}, limit: nil)
+        items = Enumerator.new do |yielder|
+          loop do
+            Array(response['value']).each(&yielder)
+            link = response['@odata.nextLink'] or break
+            response = get(link, headers: headers)
+          end
+        end
+        limit ? items.first(limit) : items.to_a
+      end
     end
   end
 end

data/lib/teems/api/mail.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # Paths and headers shared by the Graph mail wrappers. Message IDs are requested as immutable
+    # IDs so they survive moves between folders.
+    module MailPaths
+      private
+
+      def prefer_header = { 'Prefer' => 'IdType="ImmutableId"' }
+
+      def folder_path(folder_id) = "/v1.0/me/mailFolders/#{encode(folder_id)}"
+
+      def message_path(message_id) = "/v1.0/me/messages/#{encode(message_id)}"
+
+      def encode(segment) = URI.encode_www_form_component(segment)
+    end
+
+    # API wrapper for reading Microsoft Graph mail (see MailActions for changing it)
+    class Mail < Client
+      include MailPaths
+
+      LIST_FIELDS = %w[id receivedDateTime from subject isRead hasAttachments flag].freeze
+      # internetMessageHeaders only to tell protected mail apart (MailEncryption.from_headers); delta
+      # has no lighter way, since hasAttachments is unreliable for it and $expand is refused
+      MESSAGE_FIELDS = (LIST_FIELDS + %w[toRecipients ccRecipients categories body internetMessageId webLink
+                                         internetMessageHeaders]).freeze
+      PAGE_MAX = 250
+      # Delta pages carry full bodies, so keep them small
+      DELTA_PAGE_SIZE = 50
+      # $filter conditions messages can be limited to
+      FILTERS = { unread: 'isRead eq false', flagged: "flag/flagStatus eq 'flagged'" }.freeze
+
+      # Top-level folders, or the children of parent_id
+      def folders(parent_id: nil)
+        path = parent_id ? "#{folder_path(parent_id)}/childFolders" : '/v1.0/me/mailFolders'
+        collect(path, { '$top' => PAGE_MAX, '$select' => folder_fields }, limit: nil)
+      end
+
+      def folder(folder_id)
+        get(folder_path(folder_id), params: { '$select' => folder_fields })
+      end
+
+      # Newest first; only names FILTERS that every message must match, e.g. [:unread]
+      def messages(folder:, count:, only: [])
+        params = list_params(count).merge('$orderby' => 'receivedDateTime desc', '$filter' => filter(only)).compact
+        parse_messages(collect("#{folder_path(folder)}/messages", params, limit: count))
+      end
+
+      def message(message_id)
+        data = get(message_path(message_id), params: { '$select' => MESSAGE_FIELDS.join(',') },
+                                             headers: prefer_header)
+        Models::MailMessage.from_api(data)
+      end
+
+      # The message's Outlook on the web address
+      def web_link(message_id)
+        get(message_path(message_id), params: { '$select' => 'webLink' }, headers: prefer_header)['webLink']
+      end
+
+      # The conversation (thread) a message belongs to
+      def conversation_id(message_id)
+        get(message_path(message_id), params: { '$select' => 'conversationId' },
+                                      headers: prefer_header)['conversationId']
+      end
+
+      # Every message in a conversation, in any folder, oldest first: Graph refuses $orderby
+      # alongside this filter, so the sorting happens here. MESSAGE_FIELDS as fields adds bodies.
+      def conversation(conversation_id, fields: LIST_FIELDS)
+        params = { '$filter' => "conversationId eq '#{conversation_id.gsub("'", "''")}'", '$top' => PAGE_MAX,
+                   '$select' => [*fields, 'parentFolderId'].join(',') }
+        parse_messages(collect('/v1.0/me/messages', params, limit: nil)).sort_by { |message| message.received_at.to_i }
+      end
+
+      # Every message in the conversations these messages belong to, each once
+      def conversations_of(message_ids)
+        message_ids.filter_map { |id| conversation_id(id) }.uniq.flat_map { |id| conversation(id) }.uniq(&:id)
+      end
+
+      # KQL search (Graph $search) across the mailbox, or within one folder
+      def search(query:, count:, folder: nil)
+        path = folder ? "#{folder_path(folder)}/messages" : '/v1.0/me/messages'
+        params = list_params(count).merge('$search' => "\"#{query.gsub(/["\\]/) { |char| "\\#{char}" }}\"")
+        parse_messages(collect(path, params, limit: count))
+      end
+
+      # First page of a delta query for one folder; since limits it to messages received after that time
+      def delta(folder:, since: nil)
+        params = { '$select' => MESSAGE_FIELDS.join(',') }
+        params['$filter'] = "receivedDateTime ge #{since.utc.strftime('%Y-%m-%dT%H:%M:%SZ')}" if since
+        get("#{folder_path(folder)}/messages/delta", params: params, headers: delta_header)
+      end
+
+      # Follows an @odata.nextLink or @odata.deltaLink from a delta query
+      def delta_page(link) = get(link, headers: delta_header)
+
+      # Attachment metadata (no content) for one message
+      def attachments(message_id)
+        path = "#{message_path(message_id)}/attachments"
+        collect(path, { '$select' => 'id,name,size,contentType,isInline' }, limit: nil)
+      end
+
+      # One attachment including its base64 contentBytes (file attachments only)
+      def attachment(message_id, attachment_id)
+        get("#{message_path(message_id)}/attachments/#{encode(attachment_id)}", headers: prefer_header)
+      end
+
+      private
+
+      # Graph wants each $orderby property (receivedDateTime) to lead the $filter, or it may
+      # refuse the query as InefficientFilter
+      def filter(names)
+        return if names.empty?
+
+        ['receivedDateTime ge 1900-01-01T00:00:00Z', *FILTERS.values_at(*names)].join(' and ')
+      end
+
+      def list_params(count) = { '$top' => count.clamp(1, PAGE_MAX), '$select' => LIST_FIELDS.join(',') }
+
+      def collect(path, params, limit:)
+        headers = prefer_header
+        collect_pages(get(path, params: params, headers: headers), headers: headers, limit: limit)
+      end
+
+      def folder_fields = 'id,displayName,parentFolderId,childFolderCount,unreadItemCount,totalItemCount'
+
+      def parse_messages(items) = items.map { |data| Models::MailMessage.from_api(data) }
+
+      def delta_header = { 'Prefer' => "IdType=\"ImmutableId\", odata.maxpagesize=#{DELTA_PAGE_SIZE}" }
+    end
+  end
+end

data/lib/teems/api/mail_actions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # Changes to Microsoft Graph mail messages. Nothing here sends mail: a message's read state
+    # and flag can change, and it can move between folders (deleting is a move to Deleted Items,
+    # where Outlook still shows it).
+    class MailActions < Client
+      include MailPaths
+
+      # Sets message properties, e.g. { isRead: true } or { flag: { flagStatus: 'flagged' } }
+      def update(message_id, changes)
+        patch(message_path(message_id), body: changes, headers: prefer_header)
+      end
+
+      # Moves a message to a folder ID or well-known name ('archive', 'deleteditems')
+      def move(message_id, destination)
+        post("#{message_path(message_id)}/move", body: { destinationId: destination }, headers: prefer_header)
+      end
+    end
+  end
+end

data/lib/teems/api/mail_rules.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # Inbox rules (Graph /me/mailFolders/inbox/messageRules), which Exchange applies to mail as
+    # it arrives. teems builds rules without forwarding or redirecting actions (see
+    # Commands::MailRules), so nothing here makes the mailbox send mail.
+    class MailRules < Client
+      RULES_PATH = '/v1.0/me/mailFolders/inbox/messageRules'
+
+      def list = collect_pages(get(RULES_PATH)).to_a
+
+      def create(rule) = post(RULES_PATH, body: rule)
+
+      def update(rule_id, changes) = patch(rule_path(rule_id), body: changes)
+
+      def destroy(rule_id) = delete(rule_path(rule_id))
+
+      private
+
+      def rule_path(rule_id) = "#{RULES_PATH}/#{URI.encode_www_form_component(rule_id)}"
+    end
+  end
+end

data/lib/teems/cli.rb

@@ -48,8 +48,10 @@ module Teems
       'channels' => Commands::Channels,
       'chats' => Commands::Chats,
       'meeting' => Commands::Meeting,
+      'meet' => Commands::Meet,
       'transcripts' => Commands::Transcripts,
       'messages' => Commands::Messages,
+      'mail' => Commands::Mail,
       'sync' => Commands::Sync,
       'who' => Commands::Who,
       'org' => Commands::Org,

data/lib/teems/commands/base.rb

@@ -14,6 +14,11 @@ module Teems
       def puts(message = '') = @options[:quiet] || output.puts(message)
       def print(msg) = @options[:quiet] || output.print(msg)
       def output_json(data) = output.puts(JSON.pretty_generate(data))
+
+      def api_error_result(prefix, err)
+        error("#{prefix}: #{err.message}")
+        1
+      end
     end
 
     # Option validation helpers for CLI commands
@@ -127,25 +132,44 @@ module Teems
 
       # Execute a block with automatic token refresh on 401
       # Usage: with_token_refresh { runner.messages_api.chat_messages(chat_id: id) }
-      def with_token_refresh
+      def with_token_refresh(&)
         yield
       rescue ApiError => e
-        raise unless e.unauthorized? || e.message.include?('expired')
+        raise unless token_expired?(e)
 
-        attempt_token_refresh
-        yield
+        attempt_token_refresh == :refreshed ? retry_with_login(&) : yield
       end
 
+      def token_expired?(error) = error.unauthorized? || error.message.include?('expired')
+
+      # :refreshed, or :logged_in when only a new login worked; raises when neither did
       def attempt_token_refresh
         debug('Token expired, attempting refresh...')
-        return debug('Token refreshed, retrying request...') if runner.refresh_tokens
+        return :refreshed.tap { debug('Token refreshed, retrying request...') } if runner.refresh_tokens
 
         debug('Token refresh failed, re-authenticating...')
         raise ApiError, 'Re-authentication failed' unless auto_login
+
+        :logged_in
       end
 
-      def auto_login
-        tokens = runner.token_extractor.extract
+      # A refresh can succeed without renewing the Graph token (the authsvc fallback renews
+      # only the skype token), so a request still rejected after one gets a login attempt
+      def retry_with_login
+        yield
+      rescue ApiError => e
+        raise unless token_expired?(e) && auto_login
+
+        debug('Logged in again, retrying request...')
+        yield
+      end
+
+      # Under --no-login (for commands that take it) only the silent headless login is tried,
+      # never Safari, so servers, launchd and cron jobs never open a window
+      def auto_login = save_extracted_tokens(&(@options[:no_login] ? :extract_silently : :extract))
+
+      def save_extracted_tokens
+        tokens = yield(runner.token_extractor)
         return unless tokens&.[](:auth_token) && tokens[:skype_token]
 
         runner.token_store.save(**tokens)