superthread 0.7.2

data/lib/superthread/model.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "shale"
+
+module Superthread
+  # Base class for all Shale-based API response models.
+  # Provides a consistent interface compatible with existing code patterns.
+  #
+  # @example Defining a model
+  #   class Card < Superthread::Model
+  #     attribute :id, Shale::Type::String
+  #     attribute :title, Shale::Type::String
+  #     attribute :priority, Shale::Type::Integer
+  #     attribute :members, Member, collection: true
+  #
+  #     def priority_name
+  #       { 1 => 'urgent', 2 => 'high', 3 => 'medium', 4 => 'low' }[priority]
+  #     end
+  #   end
+  #
+  # @example Using a model
+  #   card = Card.from_hash(json_data)
+  #   card.title          # => "My Card"
+  #   card.priority       # => 1
+  #   card.priority_name  # => "urgent"
+  #   card.to_h           # => { id: "123", title: "My Card", ... }
+  class Model < Shale::Mapper
+    class << self
+      # Check if this is a Shale-based model.
+      # Used by the client to determine deserialization method.
+      #
+      # @return [Boolean] Always true for Model subclasses
+      def shale_model?
+        true
+      end
+
+      # Check if a given class is a Shale-based model.
+      #
+      # @param klass [Class] the class to check
+      # @return [Boolean] true if the class responds to shale_model? and returns true
+      def shale_class?(klass)
+        klass.respond_to?(:shale_model?) && klass.shale_model?
+      end
+
+      # Construct a model from a hash (API response).
+      # This is the primary factory method used by the client.
+      #
+      # @param data [Hash] The hash data from the API
+      # @return [Model] The constructed model instance
+      def from_response(data)
+        return nil if data.nil?
+
+        # Shale's from_hash expects string keys, so we deep-transform
+        from_hash(deep_stringify_keys(data))
+      end
+
+      private
+
+      # Recursively stringify hash keys for Shale compatibility.
+      #
+      # @param obj [Object] Object to process
+      # @return [Object] Object with stringified keys
+      def deep_stringify_keys(obj)
+        case obj
+        when Hash
+          obj.transform_keys(&:to_s).transform_values { |v| deep_stringify_keys(v) }
+        when Array
+          obj.map { |v| deep_stringify_keys(v) }
+        else
+          obj
+        end
+      end
+
+      public
+
+      # Construct a collection of models from an array of hashes.
+      #
+      # @param items [Array<Hash>] Array of hash data
+      # @return [Array<Model>] Array of model instances
+      def from_response_array(items)
+        return [] if items.nil?
+
+        items.map { |item| from_response(item) }
+      end
+    end
+
+    # Convert to a hash with symbol keys.
+    # Provides compatibility with existing code expecting symbol keys.
+    # Uses Shale's to_hash internally, then symbolizes keys.
+    #
+    # @return [Hash] Hash representation with symbol keys
+    def to_h
+      deep_symbolize_keys(to_hash)
+    end
+
+    private
+
+    # Recursively symbolize hash keys.
+    #
+    # @param obj [Object] Object to process
+    # @return [Object] Object with symbolized keys
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.transform_keys(&:to_sym).transform_values { |v| deep_symbolize_keys(v) }
+      when Array
+        obj.map { |v| deep_symbolize_keys(v) }
+      else
+        obj
+      end
+    end
+
+    public
+
+    # Access attribute by key (symbol or string).
+    # Provides hash-like access for compatibility.
+    #
+    # @param key [Symbol, String] The attribute name
+    # @return [Object] The attribute value
+    def [](key)
+      send(key.to_sym)
+    rescue NoMethodError
+      nil
+    end
+
+    # Check if a key/attribute exists.
+    #
+    # @param key [Symbol, String] The attribute name
+    # @return [Boolean] True if the attribute is defined
+    def key?(key)
+      respond_to?(key.to_sym)
+    end
+    alias_method :has_key?, :key?
+
+    # String representation for debugging.
+    #
+    # @return [String] Debug representation
+    def inspect
+      attrs = self.class.attributes.keys.map do |attr|
+        value = send(attr)
+        "#{attr}: #{value.inspect}"
+      end.join(", ")
+      "#<#{self.class.name} #{attrs}>"
+    end
+
+    # Comparison by attribute values.
+    #
+    # @param other [Object] Object to compare
+    # @return [Boolean] True if equal
+    def ==(other)
+      return false unless other.is_a?(self.class)
+
+      self.class.attributes.keys.all? do |attr|
+        send(attr) == other.send(attr)
+      end
+    end
+    alias_method :eql?, :==
+
+    # Hash code based on attributes.
+    #
+    # @return [Integer] Hash code
+    def hash
+      to_h.hash
+    end
+
+    protected
+
+    # Converts Unix timestamp (seconds) to Time.
+    #
+    # Use in helper methods for timestamp fields.
+    #
+    # @param ts [Integer, nil] Unix timestamp in seconds
+    # @return [Time, nil] Time object or nil
+    def timestamp_to_time(ts)
+      ts && ts != 0 && Time.at(ts)
+    end
+  end
+end

data/lib/superthread/models/board.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread board.
+    #
+    # Boards are containers for lists (columns) that organize cards in a
+    # Kanban-style workflow. Each board belongs to a team/workspace.
+    #
+    # @example
+    #   board = client.boards.find(workspace_id, board_id)
+    #   board.title              # => "Sprint Backlog"
+    #   board.lists              # => [#<Superthread::Models::List ...>]
+    #   board.lists.first.title  # => "To Do"
+    #   board.archived?          # => false
+    class Board < Superthread::Model
+      include Concerns::Archivable
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :time_created, :time_updated
+      list_columns :id, :title
+
+      # @!attribute [rw] id
+      #   @return [String] unique board identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] team_id
+      #   @return [String] ID of the team/workspace this board belongs to
+      attribute :team_id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the board
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the board
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the board was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the board was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] lists
+      #   @return [Array<List>] columns/lists contained in this board
+      attribute :lists, List, collection: true
+
+      # @!attribute [rw] archived
+      #   @return [Hash{String => Object}, nil] archive metadata with user_id and time_archived, or nil if not archived
+      attribute :archived, Shale::Type::Value
+
+      timestamps :time_created, :time_updated
+    end
+  end
+end

data/lib/superthread/models/card.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread card (task/issue).
+    #
+    # Cards are the primary work items in Superthread, containing title,
+    # description, assignees, checklists, and other metadata. They live
+    # on boards within lists and can be linked to sprints and projects.
+    #
+    # @example
+    #   card = client.cards.find(workspace_id, card_id)
+    #   card.title          # => "Implement feature X"
+    #   card.status         # => "started"
+    #   card.priority       # => 4
+    #   card.priority_name  # => "urgent"
+    #   card.members        # => [#<Superthread::Models::Member ...>]
+    #   card.archived?      # => false
+    #   card.created_at     # => 2024-01-15 10:30:00 -0800
+    class Card < Superthread::Model
+      include Concerns::Archivable
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :status, :priority, :list_title, :board_title, :time_created, :time_updated
+      list_columns :id, :title, :status, :priority, :list_title
+
+      # @!attribute [rw] id
+      #   @return [String] unique card identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] type
+      #   @return [String] card type (e.g., "card", "epic")
+      attribute :type, Shale::Type::String
+
+      # @!attribute [rw] team_id
+      #   @return [String] ID of the team/workspace this card belongs to
+      attribute :team_id, Shale::Type::String
+
+      # @!attribute [rw] project_id
+      #   @return [String] ID of the project this card belongs to
+      attribute :project_id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the card
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] content
+      #   @return [String] HTML content/description of the card
+      attribute :content, Shale::Type::String
+
+      # @!attribute [rw] schema
+      #   @return [Object] JSON schema for custom fields, can be complex
+      attribute :schema, Shale::Type::Value
+
+      # @!attribute [rw] status
+      #   @return [String] workflow status (e.g., "open", "started", "closed")
+      attribute :status, Shale::Type::String
+
+      # @!attribute [rw] priority
+      #   @return [Integer] priority level (4=urgent, 3=high, 2=medium, 1=low)
+      attribute :priority, Shale::Type::Integer
+
+      # @!attribute [rw] estimate
+      #   @return [Float] story point or time estimate
+      attribute :estimate, Shale::Type::Float
+
+      # @!attribute [rw] board_id
+      #   @return [String] ID of the board this card is on
+      attribute :board_id, Shale::Type::String
+
+      # @!attribute [rw] board_title
+      #   @return [String] title of the board this card is on
+      attribute :board_title, Shale::Type::String
+
+      # @!attribute [rw] list_id
+      #   @return [String] ID of the list/column this card is in
+      attribute :list_id, Shale::Type::String
+
+      # @!attribute [rw] list_title
+      #   @return [String] title of the list/column this card is in
+      attribute :list_title, Shale::Type::String
+
+      # @!attribute [rw] list_color
+      #   @return [String] color of the list/column this card is in
+      attribute :list_color, Shale::Type::String
+
+      # @!attribute [rw] sprint_id
+      #   @return [String] ID of the sprint this card is assigned to
+      attribute :sprint_id, Shale::Type::String
+
+      # @!attribute [rw] owner_id
+      #   @return [String] ID of the card owner
+      attribute :owner_id, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the card
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] user_id_updated
+      #   @return [String] ID of the user who last updated the card
+      attribute :user_id_updated, Shale::Type::String
+
+      # @!attribute [rw] start_date
+      #   @return [Integer] Unix timestamp when work started
+      attribute :start_date, Shale::Type::Integer
+
+      # @!attribute [rw] due_date
+      #   @return [Integer] Unix timestamp when the card is due
+      attribute :due_date, Shale::Type::Integer
+
+      # @!attribute [rw] completed_date
+      #   @return [Integer] Unix timestamp when the card was completed
+      attribute :completed_date, Shale::Type::Integer
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the card was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the card was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] total_comments
+      #   @return [Integer] number of comments on this card
+      attribute :total_comments, Shale::Type::Integer
+
+      # @!attribute [rw] total_files
+      #   @return [Integer] number of files attached to this card
+      attribute :total_files, Shale::Type::Integer
+
+      # @!attribute [rw] is_watching
+      #   @return [Boolean] whether the current user is watching this card
+      attribute :is_watching, Shale::Type::Boolean
+
+      # @!attribute [rw] is_bookmarked
+      #   @return [Boolean] whether the current user has bookmarked this card
+      attribute :is_bookmarked, Shale::Type::Boolean
+
+      # @!attribute [rw] archived_list
+      #   @return [Boolean] whether the card's list is archived
+      attribute :archived_list, Shale::Type::Boolean
+
+      # @!attribute [rw] archived_board
+      #   @return [Boolean] whether the card's board is archived
+      attribute :archived_board, Shale::Type::Boolean
+
+      # @!attribute [rw] members
+      #   @return [Array<Member>] users assigned to this card
+      attribute :members, Member, collection: true
+
+      # @!attribute [rw] tags
+      #   @return [Array<Tag>] labels/tags applied to this card
+      attribute :tags, Tag, collection: true
+
+      # @!attribute [rw] checklists
+      #   @return [Array<Checklist>] checklists attached to this card
+      attribute :checklists, Checklist, collection: true
+
+      # @!attribute [rw] archived
+      #   @return [Hash{String => Object}, nil] archive metadata with user_id and time_archived
+      attribute :archived, Shale::Type::Value
+
+      # @!attribute [rw] parent_card
+      #   @return [Hash{String => Object}, nil] raw parent card data, use {#parent} for CardRef
+      attribute :parent_card, Shale::Type::Value
+
+      # @!attribute [rw] child_cards
+      #   @return [Array<Hash>, nil] raw child card data, use {#children} for CardRef array
+      attribute :child_cards, Shale::Type::Value
+
+      # @!attribute [rw] linked_cards
+      #   @return [Array<Hash>, nil] raw linked card data, use {#links} for LinkedCardRef array
+      attribute :linked_cards, Shale::Type::Value
+
+      # @!attribute [rw] epic
+      #   @return [Hash{String => Object}, nil] epic this card belongs to
+      attribute :epic, Shale::Type::Value
+
+      timestamps :time_created, :time_updated
+      timestamps start_date: :start_time, due_date: :due_time, completed_date: :completed_time
+
+      # Check if the card is being watched.
+      #
+      # @return [Boolean] True if watching
+      def watching?
+        !!is_watching
+      end
+
+      # Check if the card is bookmarked.
+      #
+      # @return [Boolean] True if bookmarked
+      def bookmarked?
+        !!is_bookmarked
+      end
+
+      # Human-readable priority name.
+      #
+      # @return [String, nil] priority label (urgent, high, medium, low)
+      def priority_name
+        Cli::Formatter::PRIORITY_LABELS[priority]
+      end
+
+      # Returns the parent card as a CardRef, or nil if none.
+      #
+      # @return [CardRef, nil] lightweight reference to the parent card
+      def parent
+        return nil if parent_card.nil? || parent_card.empty?
+        CardRef.new(parent_card)
+      end
+
+      # Returns child cards as an array of CardRef objects.
+      #
+      # @return [Array<CardRef>] lightweight references to child cards
+      def children
+        return [] if child_cards.nil? || !child_cards.is_a?(Array)
+        child_cards.map { |c| CardRef.new(c) }
+      end
+
+      # Returns linked cards as an array of LinkedCardRef objects.
+      #
+      # @return [Array<LinkedCardRef>] lightweight references to linked cards with relationship types
+      def links
+        return [] if linked_cards.nil? || !linked_cards.is_a?(Array)
+        linked_cards.map { |c| LinkedCardRef.new(c) }
+      end
+
+      # Returns linked cards grouped by relationship type.
+      #
+      # @return [Hash{String => Array<LinkedCardRef>}] links organized by relationship type
+      def links_by_type
+        links.group_by(&:relationship)
+      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.
+    # Provides just enough information to identify and display a card.
+    #
+    # @example
+    #   ref = card.parent
+    #   ref.id     # => "abc123"
+    #   ref.title  # => "Parent Task"
+    #   ref.to_s   # => "Parent Task (abc123)"
+    class CardRef
+      # @return [String] unique card identifier
+      attr_reader :id
+
+      # @return [String] display title of the card
+      attr_reader :title
+
+      # Creates a new card reference from API response data.
+      #
+      # @param data [Hash{String => Object}, Hash{Symbol => Object}] raw card data from API
+      def initialize(data)
+        # API returns card_id for child/linked cards, id for parent
+        @id = data["card_id"] || data[:card_id] || data["id"] || data[:id]
+        @title = data["title"] || data[:title]
+      end
+
+      # Returns a human-readable string representation.
+      #
+      # @return [String] title with ID in parentheses
+      def to_s
+        "#{title} (#{id})"
+      end
+    end
+
+    # Lightweight reference to a linked card with relationship type.
+    #
+    # Extends CardRef to include the relationship type indicating how
+    # this card relates to another card.
+    #
+    # @example
+    #   ref = card.links.first
+    #   ref.relationship  # => "blocks"
+    #   ref.to_s          # => "Task Name (abc123)"
+    class LinkedCardRef < CardRef
+      # @return [String] relationship type (blocks, blocked_by, related, duplicates)
+      attr_reader :relationship
+
+      # Creates a new linked card reference from API response data.
+      #
+      # @param data [Hash{String => Object}, Hash{Symbol => Object}] raw linked card data from API
+      def initialize(data)
+        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/models/checklist.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a checklist on a card.
+    #
+    # Checklists contain a collection of items that can be checked off.
+    # They track progress and provide completion statistics.
+    #
+    # @example
+    #   checklist = card.checklists.first
+    #   checklist.title                    # => "Requirements"
+    #   checklist.items.count              # => 3
+    #   checklist.items.first.title        # => "Write specs"
+    #   checklist.items.first.checked?     # => true
+    #   checklist.progress                 # => 66.7
+    class Checklist < Superthread::Model
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      presents_as(:title) { "#{title} (#{completed_count}/#{total_count})" }
+
+      detail_fields :id, :title, :card_id, :time_created
+      list_columns :id, :title
+
+      # @!attribute [rw] id
+      #   @return [String] unique checklist identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the checklist
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] content
+      #   @return [String] optional description or notes
+      attribute :content, Shale::Type::String
+
+      # @!attribute [rw] card_id
+      #   @return [String] ID of the card this checklist belongs to
+      attribute :card_id, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the checklist
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the checklist was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the checklist was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] items
+      #   @return [Array<ChecklistItem>] items in this checklist
+      attribute :items, ChecklistItem, collection: true
+
+      timestamps :time_created, :time_updated
+
+      # Count of completed items.
+      #
+      # @return [Integer] Number of checked items
+      def completed_count
+        (items || []).count(&:checked?)
+      end
+
+      # Total number of items.
+      #
+      # @return [Integer] Total items
+      def total_count
+        (items || []).count
+      end
+
+      # Progress as a percentage.
+      #
+      # @return [Float] Percentage complete (0.0 - 100.0)
+      def progress
+        return 0.0 if total_count.zero?
+
+        (completed_count.to_f / total_count * 100).round(1)
+      end
+
+      # Check if all items are complete.
+      #
+      # @return [Boolean] True if all items checked
+      def complete?
+        total_count.positive? && completed_count == total_count
+      end
+    end
+  end
+end