slk 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6377478c56d25efc2b234bcd4ab2118bbe394520ff4f48aed0da0db5bb6c2cea
-  data.tar.gz: 869096e0ca163dc27042e199e5b2f4f44c81cbdc176ad00ed8546b59cdac7553
+  metadata.gz: daeb158ed43f78f1945fe8b66d24d9e9566096d560d7981d49827006f02e95c0
+  data.tar.gz: 30061321cb8d8e2476aa75897fe0830f557eb24f818360db74e9184a74eaaa72
 SHA512:
-  metadata.gz: c5ce6c57a9978ad2152a3267e9892274883a0980ee33f2648fe7ca14718f870ea3a0a7ecfa2420abffdea18b565c500bfda1524f2efc29bb73a35eaa9de56318
-  data.tar.gz: ffb2bd3791481c90223a9050760769868194e8044ffc0750704965180b5dfb750cdad1dd4a297f17e1688fc7e9e41c07a231f0b87d85e0af485a2c221e518f2b
+  metadata.gz: 7e69f27340cd5072b22e026eb8a429e1e3d5c9f91d8ae11d74f4c216fe7b133c322871e20d6566d9237db32dc7a9f769eaf142aaf43954cab0cdf36be37c965c
+  data.tar.gz: da29b5d82c8eb18e1e25c4ce65da977c309770946fc29b62f5de95a10394b9739eb4771fce9f4691ffe9a2d8ca5edeee1b10839e319fd9c4b64db30289ecdd64

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-30
+
+### Added
+
+- `slk thread subscribe <url>` follows a thread without posting in it, and `slk thread unsubscribe <url>` stops following it. The URL can point at the parent or any reply. Existing replies are marked read, so only new replies surface under Threads in `slk unread` and Slack's Threads view. `--json` reports the channel, thread, and last-read timestamps. Requires a session (`xoxc`) token; other token types get a hint instead of a bare API error.
+
+## [0.11.2] - 2026-09-24
+
+### Changed
+
+- `slk deactivations` now breaks the active-account total into full members, multi-channel guests, and single-channel guests, excluding bots and deactivated accounts. The summary labels the total as Slack accounts rather than company members, and `--json` adds the same breakdown while retaining `active_members`. An older roster cache is re-fetched so the new counts cannot appear as zeros.
+
 ## [0.11.1] - 2026-09-23
 
 ### Fixed

data/README.md

@@ -149,6 +149,16 @@ slk messages general -n 50      # Show 50 messages
 slk messages general --json     # Output as JSON
 ```
 
+### Threads
+
+```bash
+slk thread <url>                # View a thread
+slk thread subscribe <url>      # Follow a thread without replying
+slk thread unsubscribe <url>    # Stop following it
+```
+
+Subscribing treats existing replies as read, so only new replies show up under Threads in `slk unread` (and in Slack's own Threads view). Requires a session (`xoxc`) token.
+
 ### Activity
 
 ```bash
@@ -225,7 +235,8 @@ slk deactivations --json          # Machine-readable output
 ```
 
 ```
-acme: 16 deactivated since 30d (664 active members)
+acme: 16 deactivated since 30d (664 active accounts)
+  360 full members · 120 multi-channel guests · 184 single-channel guests
 
 2026-09-14  Dana Whitfield          Platform Support
 2026-09-11  Priya Raghunathan       UX Researcher
@@ -239,6 +250,12 @@ for that user. For a deactivated account that change is almost always the
 deactivation, but an admin editing a departed profile afterwards moves the date
 forward, so treat it as "last touched" rather than a payroll record.
 
+The active-account count excludes bots and deactivated accounts; full members and
+both types of Slack guests are shown separately. It is not an employee headcount.
+The same breakdown is available in `--json` as `active_full_members`,
+`active_multi_channel_guests`, and `active_single_channel_guests` (alongside the
+existing `active_members` total).
+
 The roster costs one API call per 1000 members, so the result is cached for six
 hours; `--refresh` re-fetches it.
 
@@ -248,7 +265,8 @@ hours; `--refresh` re-fetches it.
 "Start Date" profile field:
 
 ```
-acme: 3 deactivated since 30d (664 active members)
+acme: 3 deactivated since 30d (664 active accounts)
+  360 full members · 120 multi-channel guests · 184 single-channel guests
 
 2026-09-14  Dana Whitfield         1mo  Platform Support
 2026-09-11  Priya Raghunathan   2y 7mo  UX Researcher

data/lib/slk/api/threads.rb

@@ -28,6 +28,30 @@ module Slk
                        })
       end
 
+      # Subscribe to (follow) a thread so new replies land in the Threads view
+      # Requires a session (xoxc) token; this is an undocumented client endpoint.
+      # @param channel [String] Channel ID
+      # @param thread_ts [String] Thread parent timestamp
+      # @param last_read [String] Latest reply timestamp to treat as already read
+      def subscribe(channel:, thread_ts:, last_read:)
+        @api.post_form(@workspace, 'subscriptions.thread.add', subscription_params(channel, thread_ts, last_read))
+      end
+
+      # Unsubscribe from (unfollow) a thread
+      # @param channel [String] Channel ID
+      # @param thread_ts [String] Thread parent timestamp
+      # @param last_read [String] Latest reply timestamp to treat as already read
+      def unsubscribe(channel:, thread_ts:, last_read:)
+        @api.post_form(@workspace, 'subscriptions.thread.remove', subscription_params(channel, thread_ts, last_read))
+      end
+
+      # Check whether you are subscribed to a thread
+      # @param channel [String] Channel ID
+      # @param thread_ts [String] Thread parent timestamp
+      def get(channel:, thread_ts:)
+        @api.post_form(@workspace, 'subscriptions.thread.get', { channel: channel, thread_ts: thread_ts })
+      end
+
       # Get unread thread count
       # @return [Integer] Number of unread thread replies
       def unread_count
@@ -40,6 +64,12 @@ module Slk
       def unreads?
         unread_count.positive?
       end
+
+      private
+
+      def subscription_params(channel, thread_ts, last_read)
+        { channel: channel, thread_ts: thread_ts, last_read: last_read }
+      end
     end
   end
 end

data/lib/slk/commands/deactivations.rb

@@ -309,6 +309,7 @@ module Slk
       def render(workspace, report, records)
         formatter = Formatters::DeactivationFormatter.new(output: output, width: @options[:width])
         formatter.summary(summary_line(workspace, report, records))
+        render_account_breakdown(formatter, report)
         render_body(formatter, workspace, records)
         footer = footer(report, records)
         return if footer.empty?
@@ -340,7 +341,36 @@ module Slk
 
       def summary_line(workspace, report, records)
         "#{workspace.name}: #{records.size} #{scope_phrase} " \
-          "(#{report.active_count} active members)"
+          "(#{count_label(report.active_count, 'active account')})"
+      end
+
+      # Keep each guest type visible without overflowing a narrow terminal.
+      # rubocop:disable Metrics/MethodLength
+      def render_account_breakdown(formatter, report)
+        line = '  '
+        account_parts(report).each do |part|
+          combined = line == '  ' ? "#{line}#{part}" : "#{line} · #{part}"
+          if @options[:width] && combined.length > @options[:width] && line != '  '
+            formatter.note(line)
+            line = "  #{part}"
+          else
+            line = combined
+          end
+        end
+        formatter.note(line)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def account_parts(report)
+        [
+          count_label(report.full_member_count, 'full member'),
+          count_label(report.multi_channel_guest_count, 'multi-channel guest'),
+          count_label(report.single_channel_guest_count, 'single-channel guest')
+        ]
+      end
+
+      def count_label(count, singular)
+        "#{count} #{singular}#{'s' unless count == 1}"
       end
 
       def scope_phrase
@@ -390,7 +420,7 @@ module Slk
         {
           workspace: workspace.name,
           fetched_at: report.fetched_at,
-          active_members: report.active_count,
+          **active_counts_json(report),
           accounts_ever: report.human_count,
           total_deactivated: total_deactivated(report),
           includes_bots: @options[:bots] ? true : false,
@@ -399,6 +429,15 @@ module Slk
         }
       end
 
+      def active_counts_json(report)
+        {
+          active_members: report.active_count,
+          active_full_members: report.full_member_count,
+          active_multi_channel_guests: report.multi_channel_guest_count,
+          active_single_channel_guests: report.single_channel_guest_count
+        }
+      end
+
       # started_on and tenure_months appear only when they were asked for:
       # a null that means "not looked up" is indistinguishable from one that
       # means "nobody filled it in".

data/lib/slk/commands/debug.rb

@@ -7,6 +7,7 @@ module Slk
     # and field shapes before building higher-level features.
     #
     # Not registered in `slk help`.
+    # rubocop:disable Metrics/ClassLength
     class Debug < Base
       def execute
         result = validate_options
@@ -24,6 +25,7 @@ module Slk
         in ['profile'] then dump_profile(nil)
         in ['team'] then dump_team
         in ['schema'] then dump_schema
+        in ['thread', url] then dump_thread(url)
         else unknown_action
         end
       end
@@ -55,6 +57,40 @@ module Slk
         0
       end
 
+      # Raw shapes behind thread subscriptions: the parent message (does it
+      # carry `subscribed`/`last_read`?) and subscriptions.thread.get. Each call
+      # is captured separately so one failing does not hide the other.
+      def dump_thread(url)
+        resolved = resolve_thread(url)
+        ts = resolved.thread_ts || resolved.msg_ts
+        raise UsageError, 'URL must point to a specific message' unless ts
+
+        output.puts(JSON.pretty_generate(thread_calls(resolved.workspace.name, resolved.channel_id, ts)))
+        0
+      end
+
+      def resolve_thread(url)
+        Services::TargetResolver.new(runner: runner, cache_store: cache_store)
+                                .resolve(url, default_workspace: runner.workspace(@options[:workspace]))
+      end
+
+      def thread_calls(workspace_name, channel, thread_ts)
+        {
+          'conversations.replies' => capture do
+            runner.conversations_api(workspace_name).replies(channel: channel, timestamp: thread_ts, limit: 1)
+          end,
+          'subscriptions.thread.get' => capture do
+            runner.threads_api(workspace_name).get(channel: channel, thread_ts: thread_ts)
+          end
+        }
+      end
+
+      def capture
+        yield
+      rescue ApiError => e
+        { 'ok' => false, 'error' => e.message }
+      end
+
       def resolve_user_id(workspace, user_input)
         return self_user_id(workspace) if user_input.nil? || user_input == 'me'
         return user_input if user_input.match?(/\A[UW][A-Z0-9]+\z/)
@@ -82,7 +118,7 @@ module Slk
 
       def unknown_action
         error("Unknown debug action: #{positional_args.first.inspect}")
-        error('Valid actions: profile [user], team, schema')
+        error('Valid actions: profile [user], team, schema, thread <url>')
         1
       end
 
@@ -98,6 +134,7 @@ module Slk
             profile [user]   Dump users.profile.get + users.info + team.profile.get
             team             Dump team.info
             schema           Dump team.profile.get
+            thread <url>     Dump thread parent + subscriptions.thread.get
 
           USER
             (none) | me      Self
@@ -106,5 +143,6 @@ module Slk
         HELP
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/slk/commands/help.rb

@@ -11,6 +11,7 @@ module Slk
         ['presence', 'Get or set your presence (away/active)'],
         ['dnd', 'Manage Do Not Disturb'],
         ['messages', 'Read channel or DM messages'],
+        ['thread', 'View a thread, or subscribe to it without replying'],
         ['search', 'Search messages across channels'],
         ['sent', 'Show your sent messages across workspaces'],
         ['unread', 'View and clear unread messages'],

data/lib/slk/commands/thread.rb

@@ -4,13 +4,19 @@ require_relative 'messages'
 
 module Slk
   module Commands
-    # Views a message thread from a Slack URL
+    # Views a message thread from a Slack URL, or subscribes to / unsubscribes
+    # from it so new replies surface without posting in the thread
+    # rubocop:disable Metrics/ClassLength
     class Thread < Messages
+      SUBSCRIPTION_ACTIONS = %w[subscribe unsubscribe].freeze
+      # Session-only endpoint: bot/user OAuth tokens get one of these back.
+      TOKEN_ERRORS = %i[not_allowed_token_type unknown_method missing_scope].freeze
+
       def execute
         result = validate_options
         return result if result
 
-        resolve_and_display_thread
+        dispatch
       rescue ApiError => e
         error("Failed to fetch messages: #{e.message}")
         1
@@ -19,6 +25,13 @@ module Slk
         1
       end
 
+      def dispatch
+        action = positional_args.first
+        return change_subscription(action, positional_args[1]) if SUBSCRIPTION_ACTIONS.include?(action)
+
+        resolve_and_display_thread
+      end
+
       def resolve_and_display_thread
         target = positional_args.first
         return usage_error unless target
@@ -30,6 +43,16 @@ module Slk
         fetch_and_display_messages(resolved)
       end
 
+      def change_subscription(action, target)
+        return subscription_usage_error(action) unless target
+        return url_required_error unless Support::SlackUrlParser.new.parse(target)&.message?
+
+        resolved = target_resolver.resolve(target, default_workspace: target_workspaces.first)
+        report_subscription(action, resolved.workspace, apply_subscription(action, resolved))
+      rescue ApiError => e
+        subscription_error(action, e)
+      end
+
       def fetch_and_display_messages(resolved)
         ts = resolved.thread_ts || resolved.msg_ts
         return message_url_required_error unless ts
@@ -46,6 +69,12 @@ module Slk
 
       def usage_error
         error('Usage: slk thread <url>')
+        error('       slk thread subscribe|unsubscribe <url>')
+        1
+      end
+
+      def subscription_usage_error(action)
+        error("Usage: slk thread #{action} <url>")
         1
       end
 
@@ -60,9 +89,11 @@ module Slk
       end
 
       def help_text
-        help = Support::HelpFormatter.new('slk thread <url> [options]')
-        help.description('View a message thread from a Slack URL.')
+        help = Support::HelpFormatter.new('slk thread [subscribe|unsubscribe] <url> [options]')
+        help.description('View a message thread from a Slack URL, or subscribe to it without replying.')
+        help.note('Subscribing marks existing replies read; new replies show up in `slk unread`.')
         add_usage_section(help)
+        add_actions_section(help)
         add_options_section(help)
         add_examples_section(help)
         help.render
@@ -70,10 +101,56 @@ module Slk
 
       private
 
+      def apply_subscription(action, resolved)
+        thread_subscription(resolved.workspace).public_send(
+          action, channel_id: resolved.channel_id, timestamp: resolved.thread_ts || resolved.msg_ts
+        )
+      end
+
+      def thread_subscription(workspace)
+        Services::ThreadSubscription.new(
+          conversations_api: runner.conversations_api(workspace.name),
+          threads_api: runner.threads_api(workspace.name)
+        )
+      end
+
+      def report_subscription(action, workspace, result)
+        if @options[:json]
+          output_json(subscription_json(action, workspace, result))
+        else
+          verb = action == 'subscribe' ? 'Subscribed to' : 'Unsubscribed from'
+          success("#{verb} thread #{result.thread_ts} in #{channel_label(workspace, result.channel_id)}")
+        end
+        0
+      end
+
+      def subscription_json(action, workspace, result)
+        { subscribed: action == 'subscribe', workspace: workspace.name, channel_id: result.channel_id,
+          thread_ts: result.thread_ts, last_read: result.last_read }
+      end
+
+      def channel_label(workspace, channel_id)
+        name = cache_store.get_channel_name(workspace.name, channel_id)
+        name ? "##{name}" : channel_id
+      end
+
+      def subscription_error(action, err)
+        error("Failed to #{action} #{action == 'subscribe' ? 'to' : 'from'} thread: #{err.message}")
+        error('Thread subscriptions require a session (xoxc) token.') if TOKEN_ERRORS.include?(err.code)
+        1
+      end
+
       def add_usage_section(help)
         help.section('USAGE') { |s| s.item('<slack_url>', 'Slack message URL') }
       end
 
+      def add_actions_section(help)
+        help.section('ACTIONS') do |s|
+          s.action('subscribe <url>', 'Follow the thread (get notified of new replies)')
+          s.action('unsubscribe <url>', 'Stop following the thread')
+        end
+      end
+
       def add_options_section(help)
         help.section('OPTIONS') do |s|
           s.option('--no-emoji', 'Show :emoji: codes instead of unicode')
@@ -88,8 +165,11 @@ module Slk
       def add_examples_section(help)
         help.section('EXAMPLES') do |s|
           s.item('slk thread https://work.slack.com/archives/C123/p1234567890', 'View thread')
+          s.item('slk thread subscribe https://work.slack.com/archives/C123/p1234567890', 'Follow thread')
+          s.item('slk thread unsubscribe https://work.slack.com/archives/C123/p1234567890', 'Unfollow thread')
         end
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/slk/services/deactivation_scanner.rb

@@ -11,11 +11,17 @@ module Slk
     # (deactivated members plus headcounts, not the whole roster) is cached in
     # the workspace meta cache with a TTL.
     class DeactivationScanner
-      CACHE_KEY = 'deactivations_v1'
+      CACHE_KEY = 'deactivations_v2'
       DEFAULT_TTL = 21_600 # 6 hours
-      REQUIRED_KEYS = %w[fetched_at member_count human_count active_count records].freeze
-
-      Report = Data.define(:records, :member_count, :human_count, :active_count, :fetched_at) do
+      REQUIRED_KEYS = %w[
+        fetched_at member_count human_count active_count full_member_count
+        multi_channel_guest_count single_channel_guest_count records
+      ].freeze
+
+      Report = Data.define(
+        :records, :member_count, :human_count, :active_count, :full_member_count,
+        :multi_channel_guest_count, :single_channel_guest_count, :fetched_at
+      ) do
         def deactivated_count = records.size
 
         def bots = records.count(&:bot)
@@ -70,30 +76,55 @@ module Slk
 
       def counts(members)
         humans = members.reject { |m| Models::Deactivation.bot?(m) }
+        active = humans.reject { |m| m['deleted'] }
 
         {
           'member_count' => members.size,
           'human_count' => humans.size,
-          'active_count' => humans.count { |m| !m['deleted'] }
+          'active_count' => active.size
+        }.merge(guest_counts(active))
+      end
+
+      def guest_counts(active)
+        groups = active.group_by { |member| guest_type(member) }
+        {
+          'full_member_count' => groups.fetch(:full, []).size,
+          'multi_channel_guest_count' => groups.fetch(:multi, []).size,
+          'single_channel_guest_count' => groups.fetch(:single, []).size
         }
       end
 
+      def guest_type(member)
+        return :single if member['is_ultra_restricted']
+        return :multi if member['is_restricted']
+
+        :full
+      end
+
       def fetch_members
         @users_api.list_all do |total|
           @on_debug&.call("users.list: #{total} members fetched")
         end
       end
 
+      # Keep the cache fields explicit: a missing headcount must not become a
+      # plausible-looking zero without usable? first checking the cache shape.
+      # rubocop:disable Metrics/AbcSize
       def build_report(data)
         Report.new(
           records: sorted_records(data['records'] || []),
           member_count: data['member_count'].to_i,
           human_count: data['human_count'].to_i,
           active_count: data['active_count'].to_i,
+          full_member_count: data['full_member_count'].to_i,
+          multi_channel_guest_count: data['multi_channel_guest_count'].to_i,
+          single_channel_guest_count: data['single_channel_guest_count'].to_i,
           fetched_at: data['fetched_at']&.to_i
         )
       end
 
+      # rubocop:enable Metrics/AbcSize
+
       # Newest first; accounts with no usable timestamp sort to the bottom
       # rather than pretending to be from 1970.
       def sorted_records(raw)

data/lib/slk/services/thread_subscription.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Subscribes to or unsubscribes from a thread without posting in it.
+    #
+    # Slack wants the thread's parent timestamp plus a last-read marker. A
+    # permalink can point at any reply, so the parent is looked up first and
+    # its latest reply becomes the marker: what is already there counts as
+    # read, and only replies posted after subscribing show up as unread.
+    class ThreadSubscription
+      Result = Data.define(:channel_id, :thread_ts, :last_read)
+
+      def initialize(conversations_api:, threads_api:)
+        @conversations = conversations_api
+        @threads = threads_api
+      end
+
+      # @param channel_id [String] Channel ID
+      # @param timestamp [String] Timestamp of the parent or any reply
+      # @return [Result]
+      def subscribe(channel_id:, timestamp:)
+        change(:subscribe, channel_id, timestamp)
+      end
+
+      # @param channel_id [String] Channel ID
+      # @param timestamp [String] Timestamp of the parent or any reply
+      # @return [Result]
+      def unsubscribe(channel_id:, timestamp:)
+        change(:unsubscribe, channel_id, timestamp)
+      end
+
+      private
+
+      def change(action, channel_id, timestamp)
+        result = locate(channel_id, timestamp)
+        @threads.public_send(action, channel: channel_id, thread_ts: result.thread_ts, last_read: result.last_read)
+        result
+      end
+
+      def locate(channel_id, timestamp)
+        message = first_message(channel_id, timestamp)
+        thread_ts = message['thread_ts'] || message['ts'] || timestamp
+        # Pointed at a reply: only the parent carries latest_reply.
+        message = first_message(channel_id, thread_ts) if message['ts'] && message['ts'] != thread_ts
+
+        Result.new(channel_id: channel_id, thread_ts: thread_ts, last_read: message['latest_reply'] || thread_ts)
+      end
+
+      def first_message(channel_id, timestamp)
+        response = @conversations.replies(channel: channel_id, timestamp: timestamp, limit: 1)
+        message = (response['messages'] || []).first
+        raise ApiError.new('thread_not_found', code: :thread_not_found) unless message
+
+        message
+      end
+    end
+  end
+end

data/lib/slk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Slk
-  VERSION = '0.11.1'
+  VERSION = '0.12.0'
 end

data/lib/slk.rb

@@ -117,6 +117,7 @@ module Slk
     autoload :SentConversations, 'slk/services/sent_conversations'
     autoload :SentChanges, 'slk/services/sent_changes'
     autoload :SentChannelLabel, 'slk/services/sent_channel_label'
+    autoload :ThreadSubscription, 'slk/services/thread_subscription'
   end
 
   # Output formatters for messages, durations, and emoji

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slk
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Eric Boehs
@@ -127,6 +127,7 @@ files:
 - lib/slk/services/start_date_field.rb
 - lib/slk/services/start_date_lookup.rb
 - lib/slk/services/target_resolver.rb
+- lib/slk/services/thread_subscription.rb
 - lib/slk/services/token_loader.rb
 - lib/slk/services/token_saver.rb
 - lib/slk/services/token_store.rb