superthread 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb38a8ab1c8ba081e66e8bda3bc4fabcb8aa9732e1e8cfc5ce1bdff0b14f94b2
-  data.tar.gz: e97e7bffe8dc9bfbd86b424a6762455d1d9979b07a60651b3997ad5feaedddf5
+  metadata.gz: 6e15ca652fe609604e401611f3359af9d094872c537a8fb817048631cf5a0cf1
+  data.tar.gz: a55736ee16a8ae5b232e0a8c72b3acc42dad25a1bef131b33e50a6dd6f3df950
 SHA512:
-  metadata.gz: b2c5dfabc604f08c7aae0eedb7a94fb8f702912c5ccc2730c9d388d6f404dbdff8aa9f3fa835288732612f84d7755e4a2a5283f1d266747b3e9727aa09fdbe5f
-  data.tar.gz: 847b4c2868387c94b08bbbffab9db1d80dac9b4991884941258eb801347996f11257cdc1079d192848ae5208936352da2b894f95a1288914403279395b50cf61
+  metadata.gz: e215412fbe73aaa60fb213fa028d78a3eb933f04023fe9889bc7cf20ad9fd969e5b88091929224883b49d06a20ff3db9581a34b7a7c8831e923d7ede8a72a08a
+  data.tar.gz: 1f322daa33b43c271173051cbac4b4d414eea4bfc52c90d6216baa74ba569596f8e812a078b4be7226a6e93d8e0ab0281a8f12d368ba4cde05332c79242393d8

data/lib/superthread/cli/cards.rb

@@ -173,7 +173,7 @@ module Superthread
       option :board, type: :string, aliases: "-b", desc: "Board (ID or name, required unless --sprint)"
       option :space, type: :string, aliases: "-s", desc: "Space (required for --sprint, helps resolve board name)"
       option :sprint, type: :string, desc: "Sprint (ID or name, required unless --board)"
-      option :content, type: :string, desc: "Card content (HTML)"
+      option :content, type: :string, desc: "Card content (HTML). Use {{@Name}} to mention users"
       option :project, type: :string, desc: "Project ID"
       option :start_date, type: :numeric, desc: "Start date (Unix timestamp)"
       option :due_date, type: :numeric, desc: "Due date (Unix timestamp)"
@@ -205,6 +205,7 @@ module Superthread
 
       desc "update CARD", "Update a card"
       option :title, type: :string, desc: "New title"
+      option :content, type: :string, desc: "Card content (HTML). Use {{@Name}} to mention users"
       option :list, type: :string, aliases: "-l", desc: "Destination list (ID or name)"
       option :board, type: :string, aliases: "-b", desc: "Board (helps resolve list name)"
       option :sprint, type: :string, desc: "Sprint to move card to (ID or name)"
@@ -215,6 +216,9 @@ module Superthread
       option :archived, type: :boolean, desc: "Archive/unarchive"
       # Update an existing card's properties.
       #
+      # Content is updated via a separate PUT endpoint since the standard
+      # PATCH endpoint does not support content changes.
+      #
       # @param card_id [String] the unique identifier of the card to update
       # @return [void]
       def update(card_id)
@@ -222,36 +226,50 @@ module Superthread
           require_space_for_sprint!
 
           begin
-            # WORKAROUND: API ignores title when combined with list_id,
-            # so we make separate requests when both are provided.
-            # TODO: Remove when API is fixed (https://superthread.com/api/known-issues)
-            if options[:list] && (options[:title] || options[:priority] || options[:archived] || options[:epic])
-              # First update non-move fields
-              field_opts = symbolized_options(:title, :priority, :archived)
-              field_opts[:epic_id] = options[:epic] if options[:epic]
-              client.cards.update(workspace_id, card_id, **field_opts) unless field_opts.empty?
-
-              # Then move the card (include sprint context)
-              move_opts = resolve_list_with_context(options[:list], card_id)
-              move_opts[:position] = options[:position] if options[:position]
-              card = client.cards.update(workspace_id, card_id, **move_opts)
-            else
-              opts = symbolized_options(:title, :priority, :archived)
-              opts[:epic_id] = options[:epic] if options[:epic]
-              opts[:position] = options[:position] if options[:position]
-
-              if options[:list]
-                opts.merge!(resolve_list_with_context(options[:list], card_id))
-              elsif options[:sprint]
-                # Moving to a sprint without --list — default to first list
-                opts[:sprint_id] = sprint_id
-                opts[:project_id] = space_id
-                sprint_obj = client.sprints.find(workspace_id, sprint_id, space_id: space_id)
-                opts[:list_id] = sprint_obj.lists.first&.id
-              end
+            # Update content via dedicated PUT endpoint (separate from PATCH)
+            if options[:content]
+              client.cards.update_content(workspace_id, card_id, content: options[:content])
+            end
 
-              card = client.cards.update(workspace_id, card_id, **opts)
+            # Update other fields via PATCH (skip if only content was provided)
+            has_patch_fields = options[:title] || options[:list] || options[:priority] ||
+              !options[:archived].nil? || options[:epic] || options[:position] || options[:sprint]
+
+            if has_patch_fields
+              # WORKAROUND: API ignores title when combined with list_id,
+              # so we make separate requests when both are provided.
+              # TODO: Remove when API is fixed (https://superthread.com/api/known-issues)
+              if options[:list] && (options[:title] || options[:priority] || !options[:archived].nil? || options[:epic])
+                # First update non-move fields
+                field_opts = symbolized_options(:title, :priority, :archived)
+                field_opts[:epic_id] = options[:epic] if options[:epic]
+                client.cards.update(workspace_id, card_id, **field_opts) unless field_opts.empty?
+
+                # Then move the card (include sprint context)
+                move_opts = resolve_list_with_context(options[:list], card_id)
+                move_opts[:position] = options[:position] if options[:position]
+                card = client.cards.update(workspace_id, card_id, **move_opts)
+              else
+                opts = symbolized_options(:title, :priority, :archived)
+                opts[:epic_id] = options[:epic] if options[:epic]
+                opts[:position] = options[:position] if options[:position]
+
+                if options[:list]
+                  opts.merge!(resolve_list_with_context(options[:list], card_id))
+                elsif options[:sprint]
+                  # Moving to a sprint without --list — default to first list
+                  opts[:sprint_id] = sprint_id
+                  opts[:project_id] = space_id
+                  sprint_obj = client.sprints.find(workspace_id, sprint_id, space_id: space_id)
+                  opts[:list_id] = sprint_obj.lists.first&.id
+                end
+
+                card = client.cards.update(workspace_id, card_id, **opts)
+              end
             end
+
+            # If only content was updated, fetch the card for output
+            card ||= client.cards.find(workspace_id, card_id)
           rescue Superthread::ForbiddenError, Superthread::NotFoundError
             raise Thor::Error, "Card not found: '#{card_id}'. Use 'suth cards list -b BOARD' to see available cards."
           end

data/lib/superthread/cli/checklists.rb

@@ -116,7 +116,7 @@ module Superthread
 
       desc "add-item CHECKLIST", "Add item to a checklist"
       option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
-      option :title, type: :string, required: true, desc: "Item title"
+      option :title, type: :string, required: true, desc: "Item title. Use {{@Name}} to mention users"
       option :checked, type: :boolean, default: false, desc: "Create as checked"
       # Add a new item to an existing checklist.
       #
@@ -139,7 +139,7 @@ module Superthread
       desc "update-item ITEM_ID", "Update a checklist item"
       option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
       option :checklist, type: :string, required: true, desc: "Parent checklist ID"
-      option :title, type: :string, desc: "New item title"
+      option :title, type: :string, desc: "New item title. Use {{@Name}} to mention users"
       option :checked, type: :boolean, desc: "Mark as checked/unchecked"
       # Update the title or checked state of a checklist item.
       #

data/lib/superthread/cli/pages.rb

@@ -55,19 +55,40 @@ module Superthread
 
       desc "update PAGE", "Update a page"
       option :title, type: :string, desc: "New title"
+      option :content, type: :string, desc: "Page content (HTML)"
       option :is_public, type: :boolean, desc: "Public visibility"
       option :parent_page, type: :string, desc: "Parent page ID"
       option :archived, type: :boolean, desc: "Archive/unarchive"
       # Updates an existing page's properties.
       #
+      # Content is updated via a separate PUT endpoint since the standard
+      # PATCH endpoint does not support content changes.
+      #
       # @param page_id [String] numeric ID or URL slug of the page to retrieve
       # @return [void]
       def update(page_id)
         handle_error do
-          opts = symbolized_options(:title, :is_public, :archived)
-          opts[:parent_page_id] = options[:parent_page] if options[:parent_page]
-          page = with_not_found("Page not found: '#{page_id}'. Use 'suth pages list' to see available pages.") do
-            client.pages.update(workspace_id, page_id, **opts)
+          # Update content via dedicated PUT endpoint (separate from PATCH)
+          if options[:content]
+            with_not_found("Page not found: '#{page_id}'. Use 'suth pages list' to see available pages.") do
+              client.pages.update_content(workspace_id, page_id, content: options[:content])
+            end
+          end
+
+          # Update other fields via PATCH (skip if only content was provided)
+          has_patch_fields = options[:title] || !options[:is_public].nil? || !options[:archived].nil? || options[:parent_page]
+
+          if has_patch_fields
+            opts = symbolized_options(:title, :is_public, :archived)
+            opts[:parent_page_id] = options[:parent_page] if options[:parent_page]
+            page = with_not_found("Page not found: '#{page_id}'. Use 'suth pages list' to see available pages.") do
+              client.pages.update(workspace_id, page_id, **opts)
+            end
+          end
+
+          # If only content was updated, fetch the page for output
+          page ||= with_not_found("Page not found: '#{page_id}'. Use 'suth pages list' to see available pages.") do
+            client.pages.find(workspace_id, page_id)
           end
           output_item page, labels: {id: "Page ID"}
         end

data/lib/superthread/mention_formatter.rb

@@ -32,6 +32,8 @@ module Superthread
     PLACEHOLDER_PATTERN = /___ESCAPED_MENTION_(.+?)___END___/
     # @return [Regexp] pattern matching raw HTML mention tags that should use {{@Name}} syntax
     HTML_MENTION_PATTERN = /<(?:user-mention|mention-user)\b/i
+    # @return [Regexp] pattern matching plain @Word that is not inside {{@...}} delimiters
+    PLAIN_MENTION_PATTERN = /(?<!\{\{)@(\w+)/
 
     # @param client [Superthread::Client] the API client for fetching members
     # @param workspace_id [String] the workspace to look up members in
@@ -46,6 +48,7 @@ module Superthread
     # @return [String, nil] content with mentions converted to HTML tags
     def format(content)
       warn_html_mentions(content) if content
+      warn_plain_mentions(content) if content
       return content if content.nil? || !content.include?("{{@")
 
       member_map = build_member_map
@@ -99,6 +102,36 @@ module Superthread
         "(e.g., '{{@Steve Clarke}} check this')."
     end
 
+    # Warns when content contains plain @Name mentions that match workspace members.
+    # This catches the common mistake of using @Name instead of {{@Name}}.
+    #
+    # @param content [String] text to check for plain @mentions
+    # @return [void]
+    def warn_plain_mentions(content)
+      return if content.include?("{{@")
+
+      names = content.scan(PLAIN_MENTION_PATTERN).flatten
+      return if names.empty?
+
+      member_map = build_member_map
+      return if member_map.nil?
+
+      # Also index by first name for multi-word display names
+      first_name_map = {}
+      member_map.each_value do |info|
+        first = info[:name].split.first&.downcase
+        first_name_map[first] = info[:name] if first
+      end
+
+      names.each do |name|
+        match = member_map[name.downcase]&.fetch(:name) || first_name_map[name.downcase]
+        if match
+          warn "Warning: Found @#{name} — did you mean {{@#{match}}}? " \
+            "Use {{@Name}} syntax to mention users and trigger notifications."
+        end
+      end
+    end
+
     # Fetches workspace members and builds a case-insensitive lookup map.
     #
     # @return [Hash{String => Hash}, nil] map of lowercase names to {id:, name:}, or nil on failure

data/lib/superthread/resources/base.rb

@@ -95,6 +95,20 @@ module Superthread
         )
       end
 
+      # Performs a PUT request and returns a typed object.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash{Symbol => Object}, nil] optional request body
+      # @param object_class [Class, nil] the model class to instantiate
+      # @param unwrap_key [Symbol, nil] key to extract from response before wrapping
+      # @return [Superthread::Object] the response wrapped in an object
+      def put_object(path, body: nil, object_class: nil, unwrap_key: nil)
+        @client.request_object(
+          method: :put, path: path, body: body,
+          object_class: object_class, unwrap_key: unwrap_key
+        )
+      end
+
       # Performs a DELETE request and returns a typed object.
       #
       # @param path [String] the API endpoint path

data/lib/superthread/resources/cards.rb

@@ -52,7 +52,7 @@ module Superthread
       # @option params [String] :epic_id the new epic identifier
       # @option params [Boolean] :archived whether the card is archived
       # @return [Superthread::Models::Card] the updated card
-      # @note Content cannot be updated via this API; it uses WebSocket collaboration.
+      # @note Content updates use a separate PUT endpoint; use {#update_content} instead.
       # @note parent_card_id is not supported on update; the API silently ignores it.
       def update(workspace_id, card_id, **params)
         ws = safe_id("workspace_id", workspace_id)
@@ -61,6 +61,23 @@ module Superthread
           object_class: Models::Card, unwrap_key: :card)
       end
 
+      # Updates a card's content (description) via the dedicated PUT endpoint.
+      #
+      # Card content cannot be updated through the standard PATCH endpoint
+      # because the web app uses WebSocket collaboration for real-time editing.
+      # This method uses the separate PUT endpoint for content updates.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param card_id [String] the card identifier
+      # @param content [String] the new content as HTML
+      # @return [Superthread::Object] a response object with success: true
+      def update_content(workspace_id, card_id, content:)
+        ws = safe_id("workspace_id", workspace_id)
+        card = safe_id("card_id", card_id)
+        content = format_mentions(workspace_id, content)
+        put_object("/#{ws}/cards/#{card}/content", body: {content: content, is_html: true})
+      end
+
       # Gets a specific card with full details.
       #
       # @param workspace_id [String] the workspace identifier

data/lib/superthread/resources/pages.rb

@@ -56,10 +56,10 @@ module Superthread
       # @param page_id [String] the page identifier
       # @param params [Hash{Symbol => Object}] the attributes to update
       # @option params [String] :title the new page title
-      # @option params [String] :content the new page content as HTML
       # @option params [Boolean] :archived whether the page is archived
       # @option params [String] :parent_page_id the new parent page identifier
       # @return [Superthread::Models::Page] the updated page
+      # @note Content updates use a separate PUT endpoint; use {#update_content} instead.
       def update(workspace_id, page_id, **params)
         ws = safe_id("workspace_id", workspace_id)
         page = safe_id("page_id", page_id)
@@ -67,6 +67,21 @@ module Superthread
           object_class: Models::Page, unwrap_key: :page)
       end
 
+      # Updates a page's content via the dedicated PUT endpoint.
+      #
+      # Page content cannot be updated through the standard PATCH endpoint.
+      # This method uses the separate PUT endpoint for content updates.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param page_id [String] the page identifier
+      # @param content [String] the new content as HTML
+      # @return [Superthread::Object] a response object with success: true
+      def update_content(workspace_id, page_id, content:)
+        ws = safe_id("workspace_id", workspace_id)
+        page = safe_id("page_id", page_id)
+        put_object("/#{ws}/pages/#{page}/content", body: {content: content, is_html: true})
+      end
+
       # Duplicates a page to a destination space.
       #
       # @param workspace_id [String] the workspace identifier

data/lib/superthread/version.rb

@@ -2,5 +2,5 @@
 
 module Superthread
   # Current version of the Superthread gem.
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superthread
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Steve Clarke