superthread 0.8.1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05edf5da03e7cda08cca6e16f9813bb8f464b7847f3717a669eeb69802a67208
-  data.tar.gz: bdb2593ece548e526dfd602ca061e40541d09a062b633919133bf5ab6cc672c7
+  metadata.gz: 764ae1eedbe67d7c951c99b3cf3269cbeb11d51ab8e905348a52a18124459877
+  data.tar.gz: 01e80e6cb854aeb2a58f0c864a18ef3c0fbe26a56bb43bc10c5058b8c3d96216
 SHA512:
-  metadata.gz: 7800b583a4a5b07062e460c1b053e593b3c344037d0a6dbf84e576097be4dfdb67594d61f021eaf46aa1bf9ec6b16b93ce5c9c31633331dfa5ef13b1742e82f6
-  data.tar.gz: 0d547f6b5c884715da432f8fdfa68593435f85c20cd06786c0f6594f33381ee661f30058c86912595124d3b113fd91978861146e578c3bf8513213d5cd33e269
+  metadata.gz: 58bbc5745f81aa529127ae86148ddc0e0d55334af6c73896633e5ed02ffd8762ff00ab7991fb3df3a0c7ca15ebc9f269e05c90e55a48ad282ce71992477332b1
+  data.tar.gz: ca562a028c48552b3ca6ba1d146dc0f02c9544ae91a33b0f252b8018b4a77abc315743f1c258e95e93d596a38eb3cc6f990d7a9b7b76be307429a1a266357f84

data/lib/superthread/cli/activity.rb

@@ -89,9 +89,9 @@ module Superthread
         }
 
         cards.each do |card|
-          created_ts = normalize_timestamp(card.time_created)
-          updated_ts = normalize_timestamp(card.time_updated)
-          completed_ts = normalize_timestamp(card.completed_date)
+          created_ts = TimeUtils.normalize_timestamp(card.time_created)
+          updated_ts = TimeUtils.normalize_timestamp(card.time_updated)
+          completed_ts = TimeUtils.normalize_timestamp(card.completed_date)
 
           # Check for completion (takes precedence)
           if completed_ts && completed_ts >= since_ts
@@ -113,14 +113,6 @@ module Superthread
         activity
       end
 
-      # Normalize timestamp to seconds (API sometimes returns milliseconds).
-      #
-      # @param ts [Integer, nil] Timestamp
-      # @return [Integer, nil] Normalized timestamp in seconds
-      def normalize_timestamp(ts)
-        Formatter.normalize_timestamp(ts)
-      end
-
       # Output activity as JSON.
       #
       # @param activity [Hash] the categorized activity data with :created, :updated, :completed keys

data/lib/superthread/cli/cards.rb

@@ -41,10 +41,11 @@ module Superthread
           end
 
           opts[:list_id] = resolve_list(options[:list]) if options[:list]
-          cards = client.cards.list(workspace_id, **opts)
+          cards = client.cards.list(workspace_id, **opts).to_a
 
           # Client-side date filtering (API doesn't support time-based filters)
-          cards = apply_date_filters(cards)
+          cards = filter_by_date(cards, field: :time_created, since: parse_date(options[:since])) if options[:since]
+          cards = filter_by_date(cards, field: :time_updated, since: parse_date(options[:updated_since])) if options[:updated_since]
 
           enrich_members(cards)
           output_list cards, columns: %i[id title priority list_title members],
@@ -107,10 +108,8 @@ module Superthread
       # @return [void]
       def get(card_id)
         handle_error do
-          begin
-            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."
+          card = with_not_found("Card not found: '#{card_id}'. Use 'suth cards list -b BOARD' to see available cards.") do
+            client.cards.find(workspace_id, card_id)
           end
 
           enrich_members(card)
@@ -205,6 +204,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,26 +215,47 @@ 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)
         handle_error do
           require_space_for_sprint!
+          not_found_msg = "Card not found: '#{card_id}'. Use 'suth cards list -b BOARD' to see available cards."
+
+          # Update content via dedicated PUT endpoint (separate from PATCH)
+          if options[:content]
+            with_not_found(not_found_msg) do
+              client.cards.update_content(workspace_id, card_id, content: options[:content])
+            end
+          end
+
+          # 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]
 
-          begin
+          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] || options[:epic])
+            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?
+              unless field_opts.empty?
+                with_not_found(not_found_msg) do
+                  client.cards.update(workspace_id, card_id, **field_opts)
+                end
+              end
 
               # 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)
+              card = with_not_found(not_found_msg) do
+                client.cards.update(workspace_id, card_id, **move_opts)
+              end
             else
               opts = symbolized_options(:title, :priority, :archived)
               opts[:epic_id] = options[:epic] if options[:epic]
@@ -250,10 +271,15 @@ module Superthread
                 opts[:list_id] = sprint_obj.lists.first&.id
               end
 
-              card = client.cards.update(workspace_id, card_id, **opts)
+              card = with_not_found(not_found_msg) do
+                client.cards.update(workspace_id, card_id, **opts)
+              end
             end
-          rescue Superthread::ForbiddenError, Superthread::NotFoundError
-            raise Thor::Error, "Card not found: '#{card_id}'. Use 'suth cards list -b BOARD' to see available cards."
+          end
+
+          # If only content was updated, fetch the card for output
+          card ||= with_not_found(not_found_msg) do
+            client.cards.find(workspace_id, card_id)
           end
           output_item card, labels: {id: "Card ID"}
         end
@@ -266,10 +292,8 @@ module Superthread
       # @return [void]
       def delete(card_ref)
         handle_error do
-          begin
-            card = client.cards.find(workspace_id, card_ref)
-          rescue Superthread::ForbiddenError, Superthread::NotFoundError
-            raise Thor::Error, "Card not found: '#{card_ref}'. Use 'suth cards list -b BOARD' to see available cards."
+          card = with_not_found("Card not found: '#{card_ref}'. Use 'suth cards list -b BOARD' to see available cards.") do
+            client.cards.find(workspace_id, card_ref)
           end
           confirming("Delete card '#{card.title}' (#{card.id})?") do
             client.cards.destroy(workspace_id, card.id)
@@ -290,14 +314,12 @@ module Superthread
       # @return [void]
       def duplicate(card_id)
         handle_error do
-          begin
-            opts = symbolized_options(:title)
-            opts[:project_id] = options[:project]
-            opts[:board_id] = board_id
-            opts[:list_id] = resolve_list(options[:list])
-            card = client.cards.duplicate(workspace_id, card_id, **opts)
-          rescue Superthread::ForbiddenError, Superthread::NotFoundError
-            raise Thor::Error, "Card not found: '#{card_id}'. Use 'suth cards list -b BOARD' to see available cards."
+          opts = symbolized_options(:title)
+          opts[:project_id] = options[:project]
+          opts[:board_id] = board_id
+          opts[:list_id] = resolve_list(options[:list])
+          card = with_not_found("Card not found: '#{card_id}'. Use 'suth cards list -b BOARD' to see available cards.") do
+            client.cards.duplicate(workspace_id, card_id, **opts)
           end
           output_item card, labels: {id: "Card ID"}
         end
@@ -321,10 +343,11 @@ module Superthread
           opts[:user_id] = resolve_user(user_ref)
           opts[:board_id] = board_id if options[:board]
           opts[:project_id] = options[:project] if options[:project]
-          cards = client.cards.assigned(workspace_id, **opts)
+          cards = client.cards.assigned(workspace_id, **opts).to_a
 
           # Client-side date filtering (API doesn't support time-based filters)
-          cards = apply_date_filters(cards)
+          cards = filter_by_date(cards, field: :time_created, since: parse_date(options[:since])) if options[:since]
+          cards = filter_by_date(cards, field: :time_updated, since: parse_date(options[:updated_since])) if options[:updated_since]
 
           enrich_members(cards)
           output_list cards, columns: %i[id title priority list_title members],
@@ -474,76 +497,73 @@ module Superthread
       # Resolve a list reference and include sprint context when needed.
       #
       # The API requires sprint_id and project_id alongside list_id when moving
-      # cards within a sprint. This method handles three scenarios:
-      # 1. --board or --sprint given: resolve list name with that context
-      # 2. Neither given: fetch the card to discover its sprint/board context
-      # 3. Card is on a board (no sprint): resolve normally
+      # cards within a sprint. Dispatches to one of three strategies based on
+      # whether explicit context (--board/--sprint) was provided.
       #
       # @param list_ref [String] the list ID or name to resolve
       # @param card_id [String] the card identifier to look up for context
       # @return [Hash] params hash with :list_id and optional :sprint_id, :project_id
       def resolve_list_with_context(list_ref, card_id)
-        result = {}
-
         if options[:board] || options[:sprint]
-          result[:list_id] = resolve_list(list_ref)
-          if options[:sprint]
-            result[:sprint_id] = sprint_id
-            result[:project_id] = space_id
-          end
+          resolve_list_with_explicit_context(list_ref)
         else
           existing = client.cards.find(workspace_id, card_id)
           if existing.sprint_id
-            sprint_obj = client.sprints.find(workspace_id, existing.sprint_id,
-              space_id: existing.project_id)
-            list = sprint_obj.lists&.find { |l| l.title&.downcase == list_ref.downcase }
-            unless list || looks_like_id?(list_ref)
-              available = sprint_obj.lists&.map(&:title)&.join(", ") || "none"
-              raise Thor::Error, "List '#{list_ref}' not found in sprint. Available: #{available}"
-            end
-            result[:list_id] = list ? list.id : list_ref
-            result[:sprint_id] = existing.sprint_id
-            result[:project_id] = existing.project_id
-          elsif looks_like_id?(list_ref)
-            result[:list_id] = list_ref
+            resolve_list_in_sprint_context(existing, list_ref)
           else
-            board = client.boards.find(workspace_id, existing.board_id)
-            list = board.lists&.find { |l| l.title&.downcase == list_ref.downcase }
-            unless list
-              available = board.lists&.map(&:title)&.join(", ") || "none"
-              raise Thor::Error, "List '#{list_ref}' not found on board. Available: #{available}"
-            end
-            result[:list_id] = list.id
+            resolve_list_on_board(existing, list_ref)
           end
         end
+      end
 
+      # Resolve list when --board or --sprint was explicitly provided.
+      #
+      # @param list_ref [String] the list ID or name
+      # @return [Hash] params hash with :list_id and optional :sprint_id, :project_id
+      def resolve_list_with_explicit_context(list_ref)
+        result = {list_id: resolve_list(list_ref)}
+        if options[:sprint]
+          result[:sprint_id] = sprint_id
+          result[:project_id] = space_id
+        end
         result
       end
 
-      # Apply date filters to a collection of cards.
-      # The API doesn't support time-based filtering, so we filter client-side.
+      # Resolve list for a card that lives in a sprint.
       #
-      # @param cards [Enumerable] the cards to apply --since and --updated_since filters to
-      # @return [Array] Filtered cards
-      def apply_date_filters(cards)
-        since_ts = parse_date(options[:since]) if options[:since]
-        updated_ts = parse_date(options[:updated_since]) if options[:updated_since]
-        return cards.to_a unless since_ts || updated_ts
-
-        cards.to_a.select do |card|
-          (since_ts.nil? || meets_date_threshold?(card.time_created, since_ts)) &&
-            (updated_ts.nil? || meets_date_threshold?(card.time_updated, updated_ts))
+      # @param existing [Card] the current card with sprint context
+      # @param list_ref [String] the list ID or name
+      # @return [Hash] params hash with :list_id, :sprint_id, :project_id
+      def resolve_list_in_sprint_context(existing, list_ref)
+        sprint_obj = client.sprints.find(workspace_id, existing.sprint_id,
+          space_id: existing.project_id)
+        list = sprint_obj.lists&.find { |l| l.title&.downcase == list_ref.downcase }
+        unless list || looks_like_id?(list_ref)
+          available = sprint_obj.lists&.map(&:title)&.join(", ") || "none"
+          raise Thor::Error, "List '#{list_ref}' not found in sprint. Available: #{available}"
         end
+        {
+          list_id: list ? list.id : list_ref,
+          sprint_id: existing.sprint_id,
+          project_id: existing.project_id
+        }
       end
 
-      # Check if a timestamp meets a minimum threshold after normalization.
+      # Resolve list for a card that lives on a board (no sprint).
       #
-      # @param timestamp [Object] the raw timestamp value from the model
-      # @param threshold [Integer] the minimum Unix timestamp
-      # @return [Boolean] true if the normalized timestamp meets or exceeds the threshold
-      def meets_date_threshold?(timestamp, threshold)
-        ts = Formatter.normalize_timestamp(timestamp)
-        ts && ts >= threshold
+      # @param existing [Card] the current card with board context
+      # @param list_ref [String] the list ID or name
+      # @return [Hash] params hash with :list_id
+      def resolve_list_on_board(existing, list_ref)
+        return {list_id: list_ref} if looks_like_id?(list_ref)
+
+        board = client.boards.find(workspace_id, existing.board_id)
+        list = board.lists&.find { |l| l.title&.downcase == list_ref.downcase }
+        unless list
+          available = board.lists&.map(&:title)&.join(", ") || "none"
+          raise Thor::Error, "List '#{list_ref}' not found on board. Available: #{available}"
+        end
+        {list_id: list.id}
       end
 
       # Output card relationships (parent, children, links) in human-readable format.

data/lib/superthread/cli/concerns/board_resolvable.rb

@@ -4,6 +4,7 @@ require "active_support/concern"
 
 module Superthread
   module Cli
+    # Shared behavior modules for CLI commands.
     module Concerns
       # Resolves board references (ID or name) to board IDs.
       #

data/lib/superthread/cli/concerns/date_parsable.rb

@@ -105,7 +105,7 @@ module Superthread
             ts = item.send(field)
             next false if ts.nil?
 
-            ts = Formatter.normalize_timestamp(ts)
+            ts = Superthread::TimeUtils.normalize_timestamp(ts)
             next false if ts.nil?
 
             (since.nil? || ts >= since) && (until_time.nil? || ts <= until_time)

data/lib/superthread/cli/formatter.rb

@@ -50,17 +50,9 @@ module Superthread
       }.freeze
 
       # Human-readable labels for priority levels.
+      # References the canonical constant from Models::Card.
       # @return [Hash{Integer => String}]
-      PRIORITY_LABELS = {
-        4 => "urgent",
-        3 => "high",
-        2 => "medium",
-        1 => "low"
-      }.freeze
-
-      # Threshold for detecting millisecond timestamps vs second timestamps.
-      # Timestamps above this value are assumed to be in milliseconds.
-      MAX_SECONDS_TIMESTAMP = 9_999_999_999
+      PRIORITY_LABELS = Superthread::Models::Card::PRIORITY_NAMES
 
       module_function
 
@@ -73,13 +65,12 @@ module Superthread
       end
 
       # Normalizes a timestamp to seconds (API sometimes returns milliseconds).
+      # Delegates to {Superthread::TimeUtils.normalize_timestamp}.
       #
       # @param ts [Integer, nil] timestamp in seconds or milliseconds
       # @return [Integer, nil] timestamp in seconds, or nil if nil/zero
       def normalize_timestamp(ts)
-        return nil if ts.nil? || ts == 0
-
-        (ts > MAX_SECONDS_TIMESTAMP) ? ts / 1000 : ts
+        Superthread::TimeUtils.normalize_timestamp(ts)
       end
 
       # Truncates a string to a maximum length with an ellipsis indicator.

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/models/card.rb

@@ -22,6 +22,15 @@ module Superthread
       include Concerns::Presentable
       include Concerns::Timestampable
 
+      # Human-readable labels for priority levels.
+      # @return [Hash{Integer => String}]
+      PRIORITY_NAMES = {
+        4 => "urgent",
+        3 => "high",
+        2 => "medium",
+        1 => "low"
+      }.freeze
+
       detail_fields :id, :title, :status, :priority, :list_title, :board_title, :time_created, :time_updated
       list_columns :id, :title, :status, :priority, :list_title
 
@@ -198,7 +207,7 @@ module Superthread
       #
       # @return [String, nil] priority label (urgent, high, medium, low)
       def priority_name
-        Cli::Formatter::PRIORITY_LABELS[priority]
+        PRIORITY_NAMES[priority]
       end
 
       # Returns the parent card as a CardRef, or nil if none.
@@ -233,28 +242,6 @@ module Superthread
       end
     end
 
-    # Represents a linked card with relationship type.
-    #
-    # Extends Card with linked_card_type attribute to indicate how this
-    # card relates to another (blocks, blocked_by, related, duplicates).
-    #
-    # @example
-    #   linked = card.linked_cards.first
-    #   linked.relationship  # => "blocks"
-    #   linked.title         # => "Other Card"
-    class LinkedCard < Card
-      # @!attribute [rw] linked_card_type
-      #   @return [String] relationship type (blocks, blocked_by, related, duplicates)
-      attribute :linked_card_type, Shale::Type::String
-
-      # Returns the relationship type between this card and the linked card.
-      #
-      # @return [String] relationship type (blocks, blocked_by, related, duplicates)
-      def relationship
-        linked_card_type
-      end
-    end
-
     # Lightweight reference to a card (id + title only).
     #
     # Used for parent/child relationships to avoid circular model references.
@@ -309,13 +296,6 @@ module Superthread
         super
         @relationship = data["linked_card_type"] || data[:linked_card_type]
       end
-
-      # Returns a human-readable string representation.
-      #
-      # @return [String] title with ID in parentheses
-      def to_s
-        "#{title} (#{id})"
-      end
     end
   end
 end

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
@@ -183,16 +197,6 @@ module Superthread
         MentionFormatter.new(@client, workspace_id).format(content)
       end
 
-      # Builds an API path prefixed with the workspace ID.
-      #
-      # @param workspace_id [String] the workspace identifier
-      # @param path [String] additional path segments to append
-      # @return [String] the full API path (e.g., "/ws-123/cards")
-      def workspace_path(workspace_id, path = "")
-        ws = safe_id("workspace_id", workspace_id)
-        "/#{ws}#{path}"
-      end
-
       # Returns a success response object for delete operations.
       #
       # @return [Superthread::Object] a response object with success: true

data/lib/superthread/resources/cards.rb

@@ -7,6 +7,9 @@ module Superthread
     # Provides methods for creating, updating, listing, and managing cards
     # including their members, checklists, tags, and relationships.
     class Cards < Base
+      # Safety cap on pagination requests to prevent runaway loops.
+      MAX_PAGES = 100
+
       # Creates a new card on a board or in a sprint.
       #
       # @param workspace_id [String] the workspace identifier
@@ -52,7 +55,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 +64,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
@@ -115,8 +135,7 @@ module Superthread
         ws = safe_id("workspace_id", workspace_id)
         body = {type: "card", card_filters: build_card_filters(filters)}
 
-        post_collection("/#{ws}/views/preview", body: body,
-          item_class: Models::Card, items_key: :cards)
+        paginated_card_list("/#{ws}/views/preview", body: body)
       end
 
       # Gets cards assigned to a user.
@@ -133,8 +152,7 @@ module Superthread
         ws = safe_id("workspace_id", workspace_id)
         body = {type: "card", card_filters: build_card_filters(filters, members: [user_id])}
 
-        post_collection("/#{ws}/views/preview", body: body,
-          item_class: Models::Card, items_key: :cards)
+        paginated_card_list("/#{ws}/views/preview", body: body)
       end
 
       # Links two cards with a relationship.
@@ -341,6 +359,34 @@ module Superthread
 
       private
 
+      # Fetches all pages from the views/preview endpoint.
+      #
+      # The API returns max 25 cards per page with a cursor for pagination.
+      # The cursor must be passed as a query parameter on subsequent requests.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash] the request body with type and card_filters
+      # @return [Superthread::Objects::Collection<Superthread::Models::Card>] all matching cards
+      def paginated_card_list(path, body:)
+        all_cards = []
+        cursor = nil
+        pages = 0
+
+        loop do
+          params = cursor ? {cursor: cursor} : nil
+          response = @client.request(method: :post, path: path, params: params, body: body)
+
+          all_cards.concat(response[:cards] || [])
+
+          cursor = response[:cursor]
+          pages += 1
+          break if cursor.nil? || cursor.empty?
+          break if pages >= MAX_PAGES
+        end
+
+        Objects::Collection.from_response(all_cards, item_class: Models::Card)
+      end
+
       # Builds the card_filters hash for the views/preview endpoint.
       #
       # @param filters [Hash{Symbol => Object}] filter options

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/resources/search.rb

@@ -28,7 +28,7 @@ module Superthread
       # @return [Superthread::Objects::Collection] the search results
       def query(workspace_id, query:, limit: nil, **params)
         ws = safe_id("workspace_id", workspace_id)
-        grouped = params.fetch(:grouped, false)
+        grouped = params.fetch(:grouped, false) || false
         all_results = []
         cursor = nil
         pages = 0

data/lib/superthread/time_utils.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Superthread
+  # Shared timestamp utilities used across layers.
+  module TimeUtils
+    # Threshold for detecting millisecond timestamps vs second timestamps.
+    # Timestamps above this value are assumed to be in milliseconds.
+    MAX_SECONDS_TIMESTAMP = 9_999_999_999
+
+    module_function
+
+    # Normalizes a timestamp to seconds (API sometimes returns milliseconds).
+    #
+    # @param ts [Integer, nil] timestamp in seconds or milliseconds
+    # @return [Integer, nil] timestamp in seconds, or nil if nil/zero
+    def normalize_timestamp(ts)
+      return nil if ts.nil? || ts == 0
+
+      (ts > MAX_SECONDS_TIMESTAMP) ? ts / 1000 : ts
+    end
+  end
+end

data/lib/superthread/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superthread
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.1
 platform: ruby
 authors:
 - Steve Clarke
@@ -160,7 +160,6 @@ files:
 - lib/superthread/cli/comments.rb
 - lib/superthread/cli/completion.rb
 - lib/superthread/cli/concerns/board_resolvable.rb
-- lib/superthread/cli/concerns/confirmable.rb
 - lib/superthread/cli/concerns/date_parsable.rb
 - lib/superthread/cli/concerns/list_resolvable.rb
 - lib/superthread/cli/concerns/space_resolvable.rb
@@ -225,6 +224,7 @@ files:
 - lib/superthread/resources/sprints.rb
 - lib/superthread/resources/tags.rb
 - lib/superthread/resources/users.rb
+- lib/superthread/time_utils.rb
 - lib/superthread/version.rb
 - lib/superthread/version_checker.rb
 homepage: https://github.com/steveclarke/superthread

data/lib/superthread/cli/concerns/confirmable.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/concern"
-
-module Superthread
-  module Cli
-    # Shared behavior modules for CLI commands.
-    module Concerns
-      # Provides confirmation prompts for destructive actions.
-      # Respects the --force flag to skip confirmation.
-      #
-      # @example
-      #   class Cards < Base
-      #     include Concerns::Confirmable
-      #
-      #     def delete(card_id)
-      #       handle_error do
-      #         confirming("Delete card #{card_id}?") do
-      #           client.cards.destroy(workspace_id, card_id)
-      #           Ui.success "Card #{card_id} deleted"
-      #         end
-      #       end
-      #     end
-      #   end
-      module Confirmable
-        extend ActiveSupport::Concern
-
-        # Execute a block with optional confirmation prompt.
-        #
-        # Skips confirmation if --force flag is set, otherwise prompts user.
-        #
-        # @param message [String] the confirmation question to display
-        # @yield the block to execute if user confirms
-        # @return [Object, nil] the block's return value, or nil if cancelled
-        def confirming(message)
-          if options[:force] || confirm_action(message)
-            yield
-          else
-            Ui.muted "Cancelled."
-          end
-        end
-
-        private
-
-        # Prompt user for yes/no confirmation via the UI.
-        #
-        # @param message [String] the confirmation question to display
-        # @return [Boolean] true if user confirms, false otherwise
-        def confirm_action(message)
-          Ui.confirm(message)
-        end
-      end
-    end
-  end
-end