slk 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 663f35d4a747ac42d0fb9596caa7dd7b4809d7f3451b811b7fb7e8389c7a991c
-  data.tar.gz: 42e1ba0fda08b83c644b77212155ab2c68ac318d95f4966060624f5f0eb94827
+  metadata.gz: daeb158ed43f78f1945fe8b66d24d9e9566096d560d7981d49827006f02e95c0
+  data.tar.gz: 30061321cb8d8e2476aa75897fe0830f557eb24f818360db74e9184a74eaaa72
 SHA512:
-  metadata.gz: bd98ff12ddd5d0dfcf0ebc33e72852bfffed272c4136b74ed4b63b41ef38c0aab01b28826a02069738556781bec325a63b73eab66407f72c099de9186a6b56c2
-  data.tar.gz: 92a34fac64238598233edf4b8273d4597bb80deb07b316504649e21da575b4f56e75969a5178f2035c5fbaf5f0fa2ac70fe1eeb2e89d5baa3d6054285991a59a
+  metadata.gz: 7e69f27340cd5072b22e026eb8a429e1e3d5c9f91d8ae11d74f4c216fe7b133c322871e20d6566d9237db32dc7a9f769eaf142aaf43954cab0cdf36be37c965c
+  data.tar.gz: da29b5d82c8eb18e1e25c4ce65da977c309770946fc29b62f5de95a10394b9739eb4771fce9f4691ffe9a2d8ca5edeee1b10839e319fd9c4b64db30289ecdd64

data/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

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

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/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/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.2'
+  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.2
+  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