teems 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5932afeb278892c20e7e3fbb92980da31ff45cd9a528a3e2463de38ee7ea3f70
-  data.tar.gz: 331a38b48c8bb1d87ff770a0579e1846aa643b5d1d1daf5061c0bbf8f0589264
+  metadata.gz: 554acde76f11331b9a92ba84e7a0972f0951b0e26f90019801550ab6767a3493
+  data.tar.gz: 39b410aaf606f2298871bb9f90f463f021dee51d08814fce7f0260d8432de8a5
 SHA512:
-  metadata.gz: 5d750e3b09de3a6ce07612398e0e00a7eb5ac647aa9cd38d45023cd0605777625a9ec212aa81c111b69118d068ffd3b4bd946280d4194cc1ecd34f40708adf7f
-  data.tar.gz: 355288361bbfa4e21166b18b248793403a023411e3588be731e205c9fe4f6994684426ae7037a09cf009bdb699e9a17caf932572aea9ab1588449c3298224624
+  metadata.gz: 209764374cdd5674d1f9d5398d33fd2bccf6a1869d0ff0ec11dd5d5202e78de3cb2a24eb3dc4a2431df348cda73ee7d928816ae1210690bdca9ba8138596fcdc
+  data.tar.gz: 06ad5d91c6ae16bb936910d5dbd1f9d6fa85df7a7bb27caaed5b652acd1ee265cd3a8408be8842aa3f2a7d6c06099c9580fa40e089a5ebd18b70d6cf91169c0d

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [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
+- `teems transcripts sync` discovers calendar Teams meetings and downloads available WebVTT transcripts into a private XDG data directory. The first run scans 30 days; subsequent runs scan seven, with an idempotent manifest and catch-up after time away. `--date`, `--since`, and `--dry-run` are supported. Recordings and audio are not downloaded.
+- Transcript sync writes speaker-turn Markdown copies to `~/.local/share/teems/transcripts-md/` for local search indexes such as qmd.
+- Transcript sync can run a `transcripts.post_sync_command` from `config.json` (for example, a qmd index refresh) after a sync that changed Markdown. The command gets the changed paths in `TEEMS_TRANSCRIPTS_*` environment variables, is bounded by `post_sync_timeout` (default 300 seconds), and warns rather than failing the sync. `--no-post-sync` skips it for one run.
+- Transcript sync keeps one transcript per recording, so meetings that were restarted mid-session no longer lose the later recording's transcript. Existing per-meeting downloads are reused when identical rather than duplicated.
+- `teems meeting --json` prints call events, recording links, and transcript markers as JSON (the option was documented but ignored).
+- `teems meeting --transcript --recording-url URL` downloads the transcript for a specific recording in the meeting instead of the first one.
+
 ## [0.3.1] - 2026-09-02
 
 ### Added

data/README.md

@@ -56,8 +56,12 @@ teems cal delete 3           # Delete event #3
 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
@@ -87,11 +91,48 @@ teems meeting <thread-id> --transcript -o ~/Downloads  # Download transcript (VT
 teems meeting <thread-id> --recording -o ~/Downloads   # Download recording (MP4)
 teems meeting <thread-id> --recording --transcript -o ~/Downloads  # Both, with embedded subtitles
 teems meeting <event-id>                           # By calendar event ID (AAMk...)
+teems meeting <event-id> --date 2026-09-29 --json  # Call events + recording links as JSON
+teems meeting <event-id> --date 2026-09-29 --transcript --recording-url <url>  # A specific recording
 teems meeting "https://teams.microsoft.com/..."    # By Teams URL or recap link
 ```
 
 Recording download requires `ffmpeg` (`brew install ffmpeg`) and downloads via DASH streaming with 5 parallel threads. No browser required.
 
+#### Transcript sync
+
+```bash
+teems transcripts sync --dry-run          # Preview meetings and recording counts
+teems transcripts sync                    # First run: 30 days; later: 7 days
+teems transcripts sync --date 2026-09-28  # Retry a specific day
+teems transcripts sync --since 30         # Explicit historical backfill
+teems transcripts sync --no-post-sync     # Skip the configured post-sync command once
+```
+
+This saves **only WebVTT transcripts** in `~/.local/share/teems/transcripts/` on the machine running the command, separate from live-caption `meeting-capture` files. Each sync also writes speaker-turn Markdown copies to `~/.local/share/teems/transcripts-md/` (regenerated when missing or older than the VTT) for local search tools such as [qmd](https://github.com/tobi/qmd). Each recording keeps its own transcript, so a meeting restarted mid-session yields one VTT per recording. A private manifest in `~/.local/state/teems/transcript-sync.json` makes repeats idempotent and catches up after time away (up to 30 days). Data and state directories are mode 0700; transcripts and the manifest are mode 0600. The calendar scan retries unavailable transcripts within the lookback window; errors return a nonzero exit code. To run every evening on a GFE, schedule `teems transcripts sync` there via launchd.
+
+Coverage is **calendar Teams meetings with a saved and accessible recording transcript**, not every meeting attended: ad-hoc calls, meetings with no saved transcript/recording, and inaccessible organizer-owned artifacts cannot be recovered by this route. No audio/video is downloaded, and nothing is copied to another machine.
+
+To search the Markdown locally with qmd, keep it in a dedicated index so refreshes don't re-scan other collections:
+
+```bash
+qmd --index teems-transcripts collection add ~/.local/share/teems/transcripts-md --name teems-transcripts --mask '**/*.md'
+qmd --index teems-transcripts update && qmd --index teems-transcripts embed
+qmd --index teems-transcripts query "what did we decide about monitoring?"
+```
+
+To refresh that index automatically, set a post-sync command in `~/.config/teems/config.json`:
+
+```json
+{
+  "transcripts": {
+    "post_sync_command": "qmd --index teems-transcripts update && qmd --index teems-transcripts embed",
+    "post_sync_timeout": 900
+  }
+}
+```
+
+The command runs via `sh -c` only after a sync writes or regenerates Markdown; not on `--dry-run`, when nothing changed, or with `--no-post-sync`. It receives `TEEMS_TRANSCRIPTS_CHANGED` (newline-separated Markdown paths), `TEEMS_TRANSCRIPTS_CHANGED_COUNT`, `TEEMS_TRANSCRIPTS_MARKDOWN_DIR`, and `TEEMS_TRANSCRIPTS_DIR`, and is killed after `post_sync_timeout` seconds (default 300). A failure or timeout prints a warning but does not change the sync's exit code.
+
 ### People
 
 ```bash
@@ -114,8 +155,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/lib/teems/cli.rb

@@ -48,6 +48,7 @@ module Teems
       'channels' => Commands::Channels,
       'chats' => Commands::Chats,
       'meeting' => Commands::Meeting,
+      'transcripts' => Commands::Transcripts,
       'messages' => Commands::Messages,
       'sync' => Commands::Sync,
       'who' => Commands::Who,

data/lib/teems/commands/help.rb

@@ -9,6 +9,7 @@ module Teems
       ['channels', 'List joined teams and channels'],
       ['chats', 'List recent chats'],
       ['meeting', 'View meeting details, chat, transcripts, and recordings'],
+      ['transcripts', 'Sync saved meeting transcripts to this machine'],
       ['messages', 'Read messages from a channel or chat'],
       ['sync', 'Sync chat history locally'],
       ['who', "Look up a user's profile"],
@@ -83,6 +84,7 @@ module Teems
             teems channels                 List all channels
             teems chats                    List recent chats
             teems messages <channel-id>    Read messages from a channel
+            teems transcripts sync         Download recent meeting transcripts
             teems who                      Show your profile
             teems who john                 Search for a user
             teems org                      Show your org chart

data/lib/teems/commands/meeting.rb

@@ -24,10 +24,12 @@ module Teems
         --chat           Show meeting chat messages
         --date YYYY-MM-DD  Pick a single occurrence of a recurring meeting by date
                            (filters call events, recordings, and transcripts)
+        --recording-url URL  With --transcript, use this recording's transcript
+                             (a meeting restarted mid-session has several)
         -o, --output-dir Directory for downloads (default: current directory)
         -v, --verbose    Show debug output
         -q, --quiet      Suppress output
-        --json           Output as JSON
+        --json           Output meeting details (call events, recordings) as JSON
         -h, --help       Show this help
 
       EXAMPLES:
@@ -39,6 +41,7 @@ module Teems
         teems meeting 19:meeting_abc123@thread.v2 --recording -o ~/Downloads
         teems meeting 19:meeting_abc123@thread.v2 --recording --transcript -o ~/Downloads
         teems meeting "<recurring-url>" --date 2026-05-04 --audio --no-video --transcript
+        teems meeting AAMkAGVmMDEz... --date 2026-05-04 --json  # List recordings
         teems meeting AAMkAGVmMDEz...        # By calendar event ID
     HELP
 
@@ -51,6 +54,7 @@ module Teems
         '--no-video' => ->(opts, _args) { opts[:no_video] = true },
         '--chat' => ->(opts, _args) { opts[:chat] = true },
         '--date' => ->(opts, args) { opts[:date] = args.shift },
+        '--recording-url' => ->(opts, args) { opts[:recording_url] = args.shift },
         '-o' => ->(opts, args) { opts[:output_dir] = args.shift },
         '--output-dir' => ->(opts, args) { opts[:output_dir] = args.shift }
       }.freeze
@@ -604,11 +608,30 @@ module Teems
       end
     end
 
+    # Machine-readable meeting details; `teems transcripts sync` uses these to enumerate recordings.
+    module MeetingJsonSummary
+      private
+
+      def output_meeting_json(target, classified)
+        call_events, recordings, transcripts = classified.values_at(:call_events, :recordings, :transcripts)
+        output_json(thread_id: target[:thread_id],
+                    call_events: call_events.map { |event| json_call_event(event) },
+                    recordings: recordings.map { |rec| rec.slice(:time, :url, :call_id) },
+                    transcripts: transcripts.map { |item| item.slice(:time) })
+        0
+      end
+
+      def json_call_event(event)
+        event.slice(:time, :call_id, :duration).merge(participants: event[:participants].map { |part| part[:name] })
+      end
+    end
+
     # View meeting details, chat, transcripts, and recordings
     class Meeting < Base
       include MeetingTargetResolver
       include MeetingMessageParser
       include MeetingDisplay
+      include MeetingJsonSummary
       include MeetingChatDisplay
       include MeetingCallFilter
       include MeetingDateFilter
@@ -691,6 +714,7 @@ module Teems
         media = media_output_spec
         return download_media_with_transcript(target, classified, media) if media
         return download_transcript(target, classified) || 0 if @options[:transcript]
+        return output_meeting_json(target, classified) if @options[:json]
 
         display_meeting_summary(target, classified)
         0

data/lib/teems/commands/meeting_transcript.rb

@@ -138,24 +138,39 @@ module Teems
       end
     end
 
+    # Chooses which recording's transcript to fetch (--recording-url, else the first link).
+    module MeetingRecordingSelection
+      private
+
+      def first_recording_url(classified)
+        @options[:recording_url] || recording_urls(classified).first
+      end
+
+      def unknown_recording_url?(classified)
+        requested = @options[:recording_url]
+        requested && !recording_urls(classified).include?(requested)
+      end
+
+      def recording_urls(classified) = classified[:recordings].filter_map { |rec| rec[:url] }
+    end
+
     # Downloads meeting transcripts via SharePoint API (no Safari required)
     module MeetingTranscript
+      include MeetingRecordingSelection
       include EmbedPageParser
       include MeetingFilename
 
       private
 
       def download_transcript(target, classified)
+        return error('--recording-url is not a recording in this meeting') if unknown_recording_url?(classified)
+
         sharing_url = target[:fileUrl] || first_recording_url(classified)
         return error('No recording sharing link found for transcript download') unless sharing_url
 
         execute_transcript_pipeline(sharing_url)
       end
 
-      def first_recording_url(classified)
-        classified[:recordings].filter_map { |rec| rec[:url] }.first
-      end
-
       def execute_transcript_pipeline(sharing_url)
         info('Fetching transcript via SharePoint...')
         embed_url = fetch_embed_url(sharing_url)

data/lib/teems/commands/messages.rb

@@ -14,7 +14,7 @@ module Teems
       OPTIONS:
         -t, --team ID    Team ID (required for channel messages)
         -n, --limit N    Number of messages (default: 20)
-        --download       Download file attachments
+        --download       Download file attachments and inline images
         -o, --output-dir Directory for downloads (default: ~/.local/share/teems/downloads)
         -v, --verbose    Show debug output
         -q, --quiet      Suppress output
@@ -23,10 +23,13 @@ module Teems
       EXAMPLES:
         teems messages 19:abc123@thread.v2         # Read chat messages
         teems messages 19:abc123@thread.v2 -n 50   # Show 50 messages
+        teems messages 19:abc123@thread.v2 --download  # Save attachments + pasted images
         teems messages "https://teams.microsoft.com/l/message/19:abc@thread.v2/123?context=..."
                                                    # Show the linked message and its thread replies
     HELP
 
+    IMAGE_ICON = "\u{1F5BC}\u{FE0F}"
+
     # Display formatting for messages command
     module MessagesDisplay
       REACTION_EMOJI = {
@@ -45,6 +48,7 @@ module Teems
         puts format_message_header(message)
         puts "  #{formatted_content(message)}"
         display_attachments(message)
+        display_images(message)
         display_reactions(message)
         puts
       end
@@ -66,6 +70,11 @@ module Teems
         puts "  #{output.gray("\u{1F4CE} #{names.join(', ')}")}"
       end
 
+      def display_images(message)
+        summary = Formatters::FormatUtils.image_summary(message.images)
+        puts "  #{output.gray("#{IMAGE_ICON} #{summary}")}" unless summary.empty?
+      end
+
       def display_reactions(message)
         reactions = message.reactions
         return unless reactions.any?
@@ -85,7 +94,7 @@ module Teems
           created_at: message.created_at&.iso8601,
           importance: message.importance, reactions: message.reactions,
           attachments: message.attachments, edited: message.edited,
-          mentions: message.mentions }
+          mentions: message.mentions, images: message.images.map(&:as_json) }
       end
     end
 
@@ -95,14 +104,15 @@ module Teems
 
       def download_attachments(messages)
         attachments = find_downloadable(messages)
-        return puts('No downloadable attachments found') if attachments.empty?
+        images = inline_images(messages)
+        return puts('No downloadable attachments found') if attachments.empty? && images.empty?
 
-        execute_downloads(attachments)
+        execute_downloads(attachments, images)
       end
 
-      def execute_downloads(attachments)
+      def execute_downloads(attachments, images)
         dir = prepare_output_dir
-        count = attachments.sum { |att| download_one(att, dir) }
+        count = attachments.sum { |att| download_one(att, dir) } + images.sum { |entry| download_image(entry, dir) }
         puts "Downloaded #{count} file#{'s' if count != 1} to #{dir}" if count.positive?
       end
 
@@ -168,6 +178,29 @@ module Teems
       end
     end
 
+    # Download logic for images pasted inline into message bodies (Teams AMS objects)
+    module InlineImageDownload
+      private
+
+      # [message, image, 1-based position within the message] for every inline image
+      def inline_images(messages) = messages.flat_map { |msg| numbered_images(msg) }
+
+      def numbered_images(msg) = msg.images.map.with_index(1) { |image, number| [msg, image, number] }
+
+      def download_image(entry, dir)
+        msg, image, number = entry
+        print "#{IMAGE_ICON} Downloading #{image.label}..."
+        result = with_token_refresh { image_downloader.fetch(image) }
+        path = unique_path(dir, "image-#{msg.short_hash}-#{number}.#{result.extension}")
+        puts " done (#{Formatters::FormatUtils.format_bytes(File.binwrite(path, result.body))}) #{path}"
+        1
+      rescue StandardError => e
+        handle_download_error(e)
+      end
+
+      def image_downloader = @image_downloader ||= runner.inline_image_downloader
+    end
+
     # Fetch and render a single message and its thread replies
     module ThreadFetch
       private
@@ -175,7 +208,7 @@ module Teems
       def fetch_thread(thread_id, message_id)
         api = runner.messages_api
         parent_data = with_token_refresh { api.message(thread_id: thread_id, message_id: message_id) }
-        replies_data = with_token_refresh do
+        replies_data = fetch_replies do
           api.replies(thread_id: thread_id, message_id: message_id, limit: @options[:limit])
         end
         display_thread(parent_data, extract_messages_data(replies_data))
@@ -183,10 +216,19 @@ module Teems
         error("Failed to fetch message: #{e.message}")
       end
 
+      # Group and 1:1 chats have no reply threads; their replies endpoint returns 404
+      def fetch_replies(&)
+        with_token_refresh(&)
+      rescue ApiError => e
+        raise unless e.not_found?
+
+        {}
+      end
+
       def display_thread(parent_data, replies_data)
         parent = Models::Message.from_api(parent_data)
         replies = replies_data.map { |data| Models::Message.from_api(data) }.reject(&:system_message?).reverse
-        return output_json(thread_to_hash(parent, replies)) if @options[:json]
+        return output_json(thread_to_hash(parent, replies)) || 0 if @options[:json]
 
         render_thread(parent, replies)
         download_attachments([parent, *replies]) if @options[:download]
@@ -212,6 +254,7 @@ module Teems
     class Messages < Base
       include MessagesDisplay
       include AttachmentDownload
+      include InlineImageDownload
       include ThreadFetch
 
       def initialize(args, runner:)

data/lib/teems/commands/sync.rb

@@ -11,6 +11,7 @@ module Teems
       OPTIONS:
         --since DAYS     Number of days of history to sync (default: 180)
         --chat CHAT_ID   Sync only this chat
+        --images         Also download inline (pasted) images into each chat's images/ dir
         --auth           Authenticate via Safari before syncing
         --dry-run        Show what would be synced without writing files
         -v, --verbose    Show debug output
@@ -20,11 +21,13 @@ module Teems
         teems sync                         # Sync 6 months of all chats
         teems sync --since 30              # Sync last 30 days
         teems sync --chat 19:abc@thread.v2 # Sync a single chat
+        teems sync --images                # Include pasted screenshots
         teems sync --dry-run               # Preview what would be synced
 
       OUTPUT:
         Files are stored in ~/.local/share/teems/sync/chats/
         Each chat gets: messages.md, messages.json, chat_metadata.json
+        (plus images/ with --images; messages.md links saved images, otherwise [image: ...])
     HELP
 
     # Handles syncing individual chats: fetch, merge, retry on 404
@@ -70,7 +73,9 @@ module Teems
 
       def process_fetched_messages(chat, new_messages)
         chat_id = chat.id
-        return skip_unchanged(chat_id) if new_messages.empty? && @sync_store.last_synced_time(@state, chat_id)
+        # --images rewrites unchanged chats too, so images in already-synced messages are backfilled
+        unchanged = new_messages.empty? && !@options[:images]
+        return skip_unchanged(chat_id) if unchanged && @sync_store.last_synced_time(@state, chat_id)
 
         merge_and_update(chat, new_messages)
       end
@@ -83,7 +88,9 @@ module Teems
 
       def merge_and_update(chat, new_messages)
         existing_raw = @sync_store.read_messages_json(chat.id, state: @state)
-        all_messages = sync_engine.merge_and_write(chat, existing_raw, new_messages)
+        all_messages = sync_engine.merge_and_write(chat, existing_raw, new_messages) do |chat_dir, messages|
+          save_chat_images(chat_dir, messages)
+        end
         update_chat_state(chat, all_messages)
       end
 
@@ -138,6 +145,23 @@ module Teems
       end
     end
 
+    # Opt-in (--images) download of inline images into each synced chat directory
+    module SyncImageHandler
+      private
+
+      def save_chat_images(chat_dir, messages)
+        return unless @options[:images]
+
+        saved = sync_images.save(chat_dir, messages)
+        debug("  Saved #{saved} image(s)")
+        @stats[:images] += saved
+      end
+
+      def sync_images
+        @sync_images ||= Services::SyncImages.new(downloader: runner.inline_image_downloader, output: output)
+      end
+    end
+
     # Chat list fetching, dry-run display, and summary reporting
     module SyncDisplay
       private
@@ -211,6 +235,7 @@ module Teems
         skipped = @stats[:skipped]
         info("  Chats skipped (no new messages): #{skipped}") if skipped.positive?
         info("  Total messages: #{@stats[:messages_total]}")
+        info("  Images downloaded: #{@stats[:images]}") if @options[:images]
         display_error_count
       end
 
@@ -287,6 +312,7 @@ module Teems
     # Sync chat history locally as Markdown + JSON files
     class Sync < Base
       include SyncChatHandler
+      include SyncImageHandler
       include SyncDisplay
       include SyncAuth
 
@@ -318,6 +344,7 @@ module Teems
         '--since' => ->(opts, args) { opts[:since_days] = args.shift.to_i },
         '--chat' => ->(opts, args) { opts[:chat_id] = args.shift },
         '--dry-run' => ->(opts, _args) { opts[:dry_run] = true },
+        '--images' => ->(opts, _args) { opts[:images] = true },
         '--auth' => ->(opts, _args) { opts[:auth] = true }
       }.freeze
 
@@ -353,7 +380,7 @@ module Teems
       def init_sync_state
         @sync_store = Services::SyncStore.new
         @state = @sync_store.load_state
-        @stats = { synced: 0, skipped: 0, errors: 0, messages_total: 0 }
+        @stats = { synced: 0, skipped: 0, errors: 0, messages_total: 0, images: 0 }
         setup_api_logging
       end