superthread 0.9.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e15ca652fe609604e401611f3359af9d094872c537a8fb817048631cf5a0cf1
-  data.tar.gz: a55736ee16a8ae5b232e0a8c72b3acc42dad25a1bef131b33e50a6dd6f3df950
+  metadata.gz: 19963c25ec59017aeaa48f22fd6bbc61ff354c82a404bc5705b3b38ae7d34952
+  data.tar.gz: e1f03e1cda195ae9b696cd31862044f66b8a08cd1aac29aca86ea21b88bdf6f7
 SHA512:
-  metadata.gz: e215412fbe73aaa60fb213fa028d78a3eb933f04023fe9889bc7cf20ad9fd969e5b88091929224883b49d06a20ff3db9581a34b7a7c8831e923d7ede8a72a08a
-  data.tar.gz: 1f322daa33b43c271173051cbac4b4d414eea4bfc52c90d6216baa74ba569596f8e812a078b4be7226a6e93d8e0ab0281a8f12d368ba4cde05332c79242393d8
+  metadata.gz: 122e2e4481e6da0544b311ca0c7009fb85de3f7133a514eee13d9d9be9154ebbe246515e42fcd634d0029e17de1c509688c7d63ab3f19663212476dfabf0174e
+  data.tar.gz: 0553d576f89d0cfc827c137a2f238fef23fb664a21a1cd413b1203eeb782e643a3c82bb86efd8ff93202186f5226a79dfad5158289820e9e6140a6baa1c41323

data/README.md

@@ -325,7 +325,7 @@ Common options have short forms:
 > - Most commands accept **names or IDs** for spaces, boards, lists, sprints, users, and tags
 > - Use `-s SPACE` to help when board or list names are unclear
 > - Use `--json` for scripted output: `suth cards assigned me --json`
-> - Use `me` as a shortcut: `suth cards assigned me`
+> - Use `me` in any user argument: `suth cards assigned me`, `suth cards assign CARD me`, `--owner me`
 > - Priority levels: 1=Urgent, 2=High, 3=Medium, 4=Low
 
 ### Mentions

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)
@@ -180,7 +179,7 @@ module Superthread
       option :priority, type: :numeric, desc: "Priority level (1=low, 4=urgent)"
       option :parent_card, type: :string, desc: "Parent card ID"
       option :epic, type: :string, desc: "Epic ID"
-      option :owner, type: :string, aliases: "-o", desc: "Owner (user ID, name, or email)"
+      option :owner, type: :string, aliases: "-o", desc: "Owner (user ID, name, email, or 'me')"
       # Create a new card on a board or sprint.
       #
       # @return [void]
@@ -224,54 +223,63 @@ module Superthread
       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."
 
-          begin
-            # Update content via dedicated PUT endpoint (separate from PATCH)
-            if options[:content]
+          # 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]
-
-            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
+          # 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]
+              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 = 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]
+              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)
+              card = with_not_found(not_found_msg) do
+                client.cards.update(workspace_id, card_id, **opts)
               end
             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."
+          # 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
@@ -284,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)
@@ -308,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
@@ -339,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],
@@ -492,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/concerns/user_resolvable.rb

@@ -21,6 +21,9 @@ module Superthread
         # @raise [Thor::Error] if name/email is provided but not found
         def resolve_user(ref)
           return ref if ref.nil?
+
+          return resolve_me if ref.downcase == "me"
+
           return ref if looks_like_id?(ref)
 
           user = find_user_by_name(ref)
@@ -29,6 +32,13 @@ module Superthread
           raise Thor::Error, "User not found: '#{ref}'. Use 'suth members list' to see available users."
         end
 
+        # Resolve 'me' to the current user's identifier (cached).
+        #
+        # @return [String] the current user's identifier
+        def resolve_me
+          @me_cache ||= client.users.me.user_identifier
+        end
+
         # Get cached workspace members list.
         #
         # @return [Array<Superthread::Models::User>] all workspace members

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/projects.rb

@@ -42,7 +42,7 @@ module Superthread
       option :content, type: :string, desc: "Project description"
       option :start_date, type: :numeric, desc: "Start date (Unix timestamp)"
       option :due_date, type: :numeric, desc: "Due date (Unix timestamp)"
-      option :owner, type: :string, aliases: "-o", desc: "Owner (user ID, name, or email)"
+      option :owner, type: :string, aliases: "-o", desc: "Owner (user ID, name, email, or 'me')"
       option :priority, type: :numeric, desc: "Priority level"
       # Creates a new project on a board list.
       #
@@ -60,7 +60,7 @@ module Superthread
       option :list, type: :string, aliases: "-l", desc: "Destination list (ID or name, requires --board)"
       option :board, type: :string, aliases: "-b", desc: "Board (helps resolve list name)"
       option :space, type: :string, aliases: "-s", desc: "Space (helps resolve board name)"
-      option :owner, type: :string, aliases: "-o", desc: "New owner (user ID, name, or email)"
+      option :owner, type: :string, aliases: "-o", desc: "New owner (user ID, name, email, or 'me')"
       option :start_date, type: :numeric, desc: "Start date"
       option :due_date, type: :numeric, desc: "Due date"
       option :priority, type: :numeric, desc: "Priority"

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

@@ -197,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
@@ -132,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.
@@ -150,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.
@@ -358,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/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.9.0"
+  VERSION = "0.9.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superthread
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.2
 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