teems 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5255a4b8e6b5e3e23bcbd8f5f341a8945022c380ab6c2f76fa18c2b74ecc1ba4
+  data.tar.gz: c31fd7ed82087b636fafabb34f2acc10b8697fe918061fcecce7056b0e54fbb7
+SHA512:
+  metadata.gz: 1128d0e53047f9cef7fca4111dabf95306cd98e06c83c539816838b3b7f21a75f84e45a0fdf111484bec7a17d91e56ad2c3c75254a2b40314a5c81d1d759cc3a
+  data.tar.gz: 506950f2200002e07101641e65282eae9018716f31a49fe1048ca83f87a7b759c403b2ffa1051183217d8fa9155ae9d98f06bd997d142439f2a5dd63145c728c

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [0.1.0] - 2026-04-10
+
+### Added
+- `teems auth login` - Headless, Safari OAuth, and Safari-based token extraction
+- `teems auth status` - Show authentication status
+- `teems auth logout` - Clear stored tokens
+- `teems channels` - List joined teams and channels
+- `teems chats` - List recent chats
+- `teems messages` - Read messages from channels and chats
+- `teems cal` - List calendar events, view details, accept/decline/tentative
+- `teems cal create` - Create calendar events with attendees, rooms, and all-day support
+- `teems cal delete` - Delete calendar events
+- `teems activity` - Show activity feed (mentions, reactions, calendar)
+- `teems who` - Look up user profiles
+- `teems org` - Show org chart
+- `teems ooo` - Manage out-of-office (auto-reply, status, presence, calendar event)
+- `teems status` - View and manage presence status
+- `teems sync` - Sync chat history locally
+- Automatic token refresh via OIDC
+- Configurable API endpoints for commercial and GCC environments
+- JSON output support with `--json` flag
+- Pure Ruby implementation with no runtime dependencies

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Boehs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,136 @@
+# teems
+
+A command-line interface for Microsoft Teams. Read messages, list channels and chats from the terminal.
+
+Pure Ruby, no dependencies.
+
+## Installation
+
+```bash
+gem install teems
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/ericboehs/teems
+cd teems
+gem build teems.gemspec
+gem install teems-*.gem
+```
+
+## Requirements
+
+- Ruby 3.2+
+- macOS (for Safari token extraction)
+- Microsoft Teams account
+
+## Authentication
+
+teems requires authentication tokens from Teams. The easiest way is Safari automation:
+
+```bash
+teems auth login
+```
+
+This opens Safari to teams.microsoft.com, waits for you to log in, then extracts the tokens.
+
+Alternatively, extract tokens manually:
+
+```bash
+teems auth manual
+```
+
+## Usage
+
+### List Teams and Channels
+
+```bash
+teems channels
+```
+
+### List Chats
+
+```bash
+teems chats
+teems chats -n 50  # Show 50 chats
+```
+
+### Read Messages
+
+```bash
+# Read from a chat
+teems messages <chat-id>
+
+# Read from a channel (requires team ID)
+teems messages <channel-id> -t <team-id>
+
+# Show more messages
+teems messages <chat-id> -n 50
+```
+
+### Check Authentication Status
+
+```bash
+teems auth status
+```
+
+### Clear Authentication
+
+```bash
+teems auth logout
+```
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-n, --limit N` | Number of items to show (default: 20) |
+| `-v, --verbose` | Show debug output |
+| `-q, --quiet` | Suppress output |
+| `--json` | Output as JSON |
+| `-h, --help` | Show help |
+
+## Configuration
+
+Configuration is stored in XDG-compliant directories:
+
+- Config: `~/.config/teems/`
+- Cache: `~/.cache/teems/`
+
+### Custom Endpoints
+
+By default, teems connects to commercial Microsoft Teams endpoints. To use a different environment (e.g., GCC, GCC High), add an `endpoints` section to `~/.config/teems/config.json`:
+
+```json
+{
+  "endpoints": {
+    "msgservice": "https://ng.msg.gcc.teams.microsoft.com",
+    "presence": "https://presence.gcc.teams.microsoft.com"
+  }
+}
+```
+
+Available endpoint keys: `graph`, `teams`, `msgservice`, `presence`.
+
+## Token Expiration
+
+Teams tokens expire after ~24 hours. When you see authentication errors, run:
+
+```bash
+teems auth login
+```
+
+## Development
+
+```bash
+git clone https://github.com/ericboehs/teems
+cd teems
+rake check   # Syntax check
+rake test    # Run tests
+rake console # Interactive console
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

data/bin/teems

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'teems'
+
+exit Teems::CLI.new(ARGV).run

data/lib/teems/api/calendar.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # API wrapper for Microsoft Graph Calendar endpoints
+    class Calendar < Client
+      CALENDAR_VIEW_SELECT = %w[
+        id subject start end location isAllDay organizer attendees
+        bodyPreview onlineMeeting showAs importance isCancelled
+        responseStatus sensitivity
+      ].join(',').freeze
+
+      EVENT_DETAIL_SELECT = %w[
+        id subject start end location isAllDay organizer attendees
+        body onlineMeeting showAs importance isCancelled
+        responseStatus sensitivity
+      ].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)
+        headers = timezone_header(time_range[:timezone])
+        paginate_events('/v1.0/me/calendarView', params: params, headers: headers)
+      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)
+        params = { '$select' => EVENT_DETAIL_SELECT }
+        headers = timezone_header(timezone)
+
+        response = get("/v1.0/me/events/#{encoded_id}", params: params, headers: headers)
+        Models::Event.from_api(response)
+      end
+
+      # Create a new calendar event
+      def create_event(body)
+        response = post('/v1.0/me/events', body: body)
+        Models::Event.from_api(response)
+      end
+
+      # Delete an event
+      def delete_event(event_id:)
+        encoded_id = URI.encode_www_form_component(event_id)
+        delete("/v1.0/me/events/#{encoded_id}")
+      end
+
+      # RSVP to an event (accept, decline, or tentatively accept)
+      def rsvp_event(event_id:, action:, **opts)
+        encoded_id = URI.encode_www_form_component(event_id)
+        api_action = action == 'tentative' ? 'tentativelyAccept' : action
+        post("/v1.0/me/events/#{encoded_id}/#{api_action}", body: rsvp_body(opts))
+      end
+
+      private
+
+      def rsvp_body(opts)
+        comment = opts[:comment]
+        body = { sendResponse: opts.fetch(:notify, :send) == :send }
+        body[:comment] = comment if comment
+        body
+      end
+
+      def calendar_view_params(start_dt, end_dt, top)
+        { 'startDateTime' => start_dt, 'endDateTime' => end_dt,
+          '$select' => CALENDAR_VIEW_SELECT, '$orderby' => 'start/dateTime', '$top' => top }
+      end
+
+      def paginate_events(path, params:, headers:)
+        events = []
+        response = get(path, params: params, headers: headers)
+        collect_paginated_events(events, response, headers)
+      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
+
+          response = get(next_link, headers: headers)
+        end
+      end
+
+      def timezone_header(timezone)
+        { 'Prefer' => "outlook.timezone=\"#{timezone}\"" }
+      end
+
+      def parse_events(response)
+        (response['value'] || []).map { |data| Models::Event.from_api(data) }
+      end
+    end
+  end
+end

data/lib/teems/api/channels.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # API wrapper for Teams and channels endpoints using Microsoft Graph API
+    class Channels < Client
+      # Get list of teams the user has joined
+      def list_teams
+        get('/v1.0/me/joinedTeams')
+      end
+
+      # Get channels for a specific team
+      def list_channels(team_id:)
+        encoded_team = URI.encode_www_form_component(team_id)
+        get("/v1.0/teams/#{encoded_team}/channels")
+      end
+
+      # Get details about a specific channel
+      def get_channel(team_id:, channel_id:)
+        encoded_team = URI.encode_www_form_component(team_id)
+        encoded_channel = URI.encode_www_form_component(channel_id)
+        get("/v1.0/teams/#{encoded_team}/channels/#{encoded_channel}")
+      end
+    end
+  end
+end

data/lib/teems/api/chats.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # API wrapper for chat endpoints
+    # Uses Teams ng.msg service for chat operations
+    class Chats < Client
+      ENDPOINT = :msgservice
+
+      # Get list of conversations (chats, meetings)
+      def list(limit: 50)
+        get('/v1/users/ME/conversations',
+            params: { pageSize: limit, view: 'msnp24Equivalent' })
+      end
+
+      # Get a specific chat
+      def get_chat(chat_id:)
+        encoded_id = URI.encode_www_form_component(chat_id)
+        get("/v1/users/ME/conversations/#{encoded_id}")
+      end
+
+      # Get members of a chat
+      def members(chat_id:)
+        encoded_id = URI.encode_www_form_component(chat_id)
+        get("/v1/threads/#{encoded_id}/members")
+      end
+    end
+  end
+end

data/lib/teems/api/client.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # Base API client for Teams endpoints
+    class Client
+      ENDPOINT = :graph
+
+      def initialize(api_client, account)
+        @api = api_client
+        @account = account
+      end
+
+      protected
+
+      def endpoint = self.class::ENDPOINT
+
+      def get(path, params: {}, headers: {})
+        @api.get(endpoint, path, account: @account, params: params, headers: headers)
+      end
+
+      def post(path, body: nil)
+        @api.post(endpoint, path, account: @account, body: body)
+      end
+
+      def patch(path, body: nil)
+        @api.patch(endpoint, path, account: @account, body: body)
+      end
+
+      def post_to(target_endpoint, request)
+        @api.post(target_endpoint, request[:path], account: @account, body: request[:body])
+      end
+
+      def delete(path)
+        base_url = Services::ConnectionPool::DEFAULT_ENDPOINTS[endpoint]
+        @api.delete("#{base_url}#{path}", endpoint_key: endpoint, account: @account)
+      end
+    end
+  end
+end

data/lib/teems/api/files.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # API wrapper for SharePoint file operations via Microsoft Graph
+    class Files < Client
+      def drive_item(site_id:, list_id:, item_id:)
+        get("/v1.0/sites/#{site_id}/lists/#{list_id}/items/#{item_id}/driveItem")
+      end
+    end
+  end
+end

data/lib/teems/api/messages.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # API wrapper for messages endpoints
+    # Uses Teams ng.msg service for reading messages
+    # Requires skypeToken from authsvc exchange (not the JWT from localStorage)
+    class Messages < Client
+      ENDPOINT = :msgservice
+
+      # Get messages from a channel using ng.msg API
+      def channel_messages(channel_id:, limit: 50)
+        # The ng.msg API uses /v1/users/ME/conversations/{threadId}/messages
+        encoded_id = URI.encode_www_form_component(channel_id)
+        get("/v1/users/ME/conversations/#{encoded_id}/messages",
+            params: { pageSize: limit, view: 'msnp24Equivalent|supportsMessageProperties' })
+      end
+
+      # Get messages from a chat using ng.msg API
+      def chat_messages(chat_id:, limit: 50)
+        encoded_id = URI.encode_www_form_component(chat_id)
+        get("/v1/users/ME/conversations/#{encoded_id}/messages",
+            params: { pageSize: limit, view: 'msnp24Equivalent|supportsMessageProperties' })
+      end
+
+      # Get a page of messages for sync, with pagination support.
+      # Returns the full response hash including _metadata for pagination.
+      #
+      # When backward_link is provided, follows it directly to get older messages.
+      # Otherwise builds a request with startTime for time-range filtering.
+      #
+      # The ng.msg API returns newest-first with _metadata.backwardLink for older pages.
+      def chat_messages_page(chat_id:, limit: 200, **pagination)
+        backward_link = pagination[:backward_link]
+        return get(backward_link, params: {}) if backward_link
+
+        encoded_id = URI.encode_www_form_component(chat_id)
+        params = messages_page_params(limit, pagination[:start_time])
+        get("/v1/users/ME/conversations/#{encoded_id}/messages", params: params)
+      end
+
+      # Get replies to a message
+      def replies(thread_id:, message_id:, limit: 50)
+        encoded_id = URI.encode_www_form_component(thread_id)
+        get("/v1/users/ME/conversations/#{encoded_id}/messages/#{message_id}/replies",
+            params: { pageSize: limit })
+      end
+
+      private
+
+      def messages_page_params(limit, start_time)
+        { pageSize: limit, view: 'msnp24Equivalent|supportsMessageProperties' }.tap do |params|
+          params[:startTime] = (start_time.to_f * 1000).to_i if start_time
+        end
+      end
+    end
+  end
+end

data/lib/teems/api/users.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'users_presence'
+require_relative 'users_mailbox'
+
+module Teems
+  module Api
+    # API wrapper for Microsoft Graph user endpoints
+    class Users < Client
+      include UsersPresence
+      include UsersMailbox
+
+      USER_SELECT = %w[
+        id displayName mail userPrincipalName jobTitle
+        department officeLocation businessPhones mobilePhone
+      ].join(',').freeze
+
+      def me
+        response = get('/v1.0/me', params: { '$select' => USER_SELECT })
+        Models::UserProfile.from_api(response)
+      end
+
+      def get_user(user_id)
+        encoded_id = URI.encode_www_form_component(user_id)
+        response = get("/v1.0/users/#{encoded_id}", params: { '$select' => USER_SELECT })
+        Models::UserProfile.from_api(response)
+      end
+
+      def search(query)
+        sanitized = query.gsub(/["\\]/, '')
+        headers = { 'ConsistencyLevel' => 'eventual' }
+        response = get('/v1.0/users', params: search_params(sanitized), headers: headers)
+        (response['value'] || []).map { |data| Models::UserProfile.from_api(data) }
+      end
+
+      def search_params(sanitized)
+        { '$search' => "\"displayName:#{sanitized}\" OR \"mail:#{sanitized}\"",
+          '$select' => USER_SELECT, '$count' => 'true', '$top' => 10 }
+      end
+
+      def manager(user_id)
+        encoded_id = URI.encode_www_form_component(user_id)
+        response = get("/v1.0/users/#{encoded_id}/manager", params: { '$select' => USER_SELECT })
+        Models::UserProfile.from_api(response)
+      end
+
+      def manager_me
+        response = get('/v1.0/me/manager', params: { '$select' => USER_SELECT })
+        Models::UserProfile.from_api(response)
+      end
+
+      def direct_reports(user_id)
+        encoded_id = URI.encode_www_form_component(user_id)
+        response = get("/v1.0/users/#{encoded_id}/directReports", params: { '$select' => USER_SELECT })
+        (response['value'] || []).map { |data| Models::UserProfile.from_api(data) }
+      end
+
+      def direct_reports_me
+        response = get('/v1.0/me/directReports', params: { '$select' => USER_SELECT })
+        (response['value'] || []).map { |data| Models::UserProfile.from_api(data) }
+      end
+
+      def presence(user_id)
+        encoded_id = URI.encode_www_form_component(user_id)
+        get("/v1.0/users/#{encoded_id}/presence")
+      end
+
+      def teams_presence(mri)
+        post_to(:presence, path: '/v1/presence/getpresence/', body: [{ mri: mri }])
+      end
+
+      def schedule(email, time_range:)
+        response = post('/v1.0/me/calendar/getSchedule', body: schedule_body(email, time_range))
+        response.dig('value', 0)
+      end
+
+      private
+
+      def schedule_body(email, time_range)
+        tz = time_range[:timezone]
+        { schedules: [email],
+          startTime: { dateTime: time_range[:start_time], timeZone: tz },
+          endTime: { dateTime: time_range[:end_time], timeZone: tz },
+          availabilityViewInterval: 15 }
+      end
+    end
+  end
+end

data/lib/teems/api/users_mailbox.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Teems
+  module Api
+    # Mailbox settings API methods for Users class (automatic replies / OOO)
+    module UsersMailbox
+      def auto_replies
+        get('/v1.0/me/mailboxSettings/automaticRepliesSetting')
+      end
+
+      def update_auto_replies(settings)
+        patch('/v1.0/me/mailboxSettings', body: { automaticRepliesSetting: settings })
+      end
+    end
+  end
+end

data/lib/teems/api/users_presence.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Teems
+  module Api
+    # Presence-related API methods for Users class
+    module UsersPresence
+      def my_presence
+        get('/v1.0/me/presence')
+      end
+
+      def set_presence(availability:, activity:, duration:)
+        post('/v1.0/me/presence/setPresence', body: {
+               sessionId: SecureRandom.uuid,
+               availability: availability,
+               activity: activity,
+               expirationDuration: duration
+             })
+      end
+
+      def set_status_message(message:, expiry: nil)
+        post('/v1.0/me/presence/setStatusMessage', body: build_status_message_body(message, expiry))
+      end
+
+      def clear_status_message
+        set_status_message(message: '')
+      end
+
+      def clear_presence
+        post('/v1.0/me/presence/clearPresence', body: { sessionId: SecureRandom.uuid })
+      end
+
+      private
+
+      def build_status_message_body(message, expiry)
+        body = { statusMessage: { message: { content: message, contentType: 'text' } } }
+        body[:statusMessage][:expiryDateTime] = { dateTime: expiry, timeZone: 'UTC' } if expiry
+        body
+      end
+    end
+  end
+end