superthread 0.7.2

data/lib/superthread/models/checklist_item.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a checklist item.
+    #
+    # Individual todo items within a checklist that can be marked as complete.
+    #
+    # @example
+    #   item = checklist.items.first
+    #   item.title     # => "Write specs"
+    #   item.checked?  # => true
+    class ChecklistItem < Superthread::Model
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :checked, :checklist_id
+      list_columns :id, :title, :checked
+
+      # @!attribute [rw] id
+      #   @return [String] unique checklist item identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the item
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] content
+      #   @return [String] optional description or notes
+      attribute :content, Shale::Type::String
+
+      # @!attribute [rw] checklist_id
+      #   @return [String] ID of the parent checklist
+      attribute :checklist_id, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the item
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] checked
+      #   @return [Boolean] whether this item is checked/completed
+      attribute :checked, Shale::Type::Boolean
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the item was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the item was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      timestamps :time_created, :time_updated
+
+      # Check if the item is checked.
+      #
+      # @return [Boolean] True if checked
+      def checked?
+        !!checked
+      end
+
+      # Alias for checked?.
+      #
+      # @return [Boolean] True if complete
+      def complete?
+        checked?
+      end
+    end
+  end
+end

data/lib/superthread/models/comment.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread comment.
+    #
+    # Comments are discussion items attached to cards. They support threaded
+    # replies through the parent_id and replies attributes.
+    #
+    # @example
+    #   comment = client.comments.find(workspace_id, comment_id)
+    #   comment.content      # => "This looks great!"
+    #   comment.user_id      # => "u123"
+    #   comment.replies      # => [#<Superthread::Models::Comment ...>]
+    #   comment.reply?       # => false
+    class Comment < Superthread::Model
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      presents_as(:content) { content.to_s.then { |c| (c.length > 50) ? "#{c[0..47]}..." : c } }
+
+      detail_fields :id, :content, :user_id, :time_created
+      list_columns :id, :content, :user_id
+
+      # @!attribute [rw] id
+      #   @return [String] unique comment identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] type
+      #   @return [String] comment type
+      attribute :type, Shale::Type::String
+
+      # @!attribute [rw] content
+      #   @return [String] HTML content of the comment
+      attribute :content, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who posted the comment
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] card_id
+      #   @return [String] ID of the card this comment is on
+      attribute :card_id, Shale::Type::String
+
+      # @!attribute [rw] parent_id
+      #   @return [String, nil] ID of the parent comment if this is a reply
+      attribute :parent_id, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the comment was posted
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the comment was last edited
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] replies
+      #   @return [Array<Comment>] threaded replies to this comment
+      attribute :replies, Comment, collection: true
+
+      timestamps :time_created, :time_updated
+
+      # Check if this is a reply to another comment.
+      #
+      # @return [Boolean] True if this is a reply
+      def reply?
+        !!parent_id
+      end
+    end
+  end
+end

data/lib/superthread/models/concerns/archivable.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Models
+    # Shared behavior modules for Superthread models.
+    module Concerns
+      # Provides archived status checking for models with an `archived` attribute.
+      #
+      # @example
+      #   class Board < Superthread::Model
+      #     include Concerns::Archivable
+      #
+      #     attribute :archived, Shale::Type::Value
+      #   end
+      #
+      #   board.archived?  # => true/false
+      module Archivable
+        extend ActiveSupport::Concern
+
+        # Check if the resource is archived.
+        # The archived attribute can be a boolean or a hash with metadata.
+        #
+        # @return [Boolean] True if archived
+        def archived?
+          !!archived
+        end
+      end
+    end
+  end
+end

data/lib/superthread/models/concerns/presentable.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Models
+    module Concerns
+      # Provides string representation via a configurable attribute.
+      # Default uses :title, but can be customized.
+      #
+      # @example Default (uses title)
+      #   class Board < Superthread::Model
+      #     include Concerns::Presentable
+      #
+      #     attribute :title, Shale::Type::String
+      #   end
+      #
+      #   board.to_s  # => "My Board"
+      #
+      # @example Custom attribute
+      #   class User < Superthread::Model
+      #     include Concerns::Presentable
+      #     presents_as :display_name
+      #
+      #     attribute :display_name, Shale::Type::String
+      #   end
+      #
+      #   user.to_s  # => "John Doe"
+      #
+      # @example With block for custom formatting
+      #   class Checklist < Superthread::Model
+      #     include Concerns::Presentable
+      #     presents_as(:title) { "#{title} (#{completed_count}/#{total_count})" }
+      #   end
+      #
+      #   checklist.to_s  # => "Requirements (2/3)"
+      module Presentable
+        extend ActiveSupport::Concern
+
+        included do
+          @presentation_attribute = :title
+          @presentation_block = nil
+        end
+
+        class_methods do
+          # Configure which attribute to use for string representation.
+          #
+          # When called with just an attribute, that attribute's value becomes
+          # the string representation. When called with a block, the block is
+          # evaluated in the instance context to produce the string.
+          #
+          # @param attribute [Symbol] attribute name to use for to_s output
+          # @yield optional block evaluated in instance context for custom formatting
+          # @yieldreturn [String] the formatted string representation
+          # @return [void]
+          def presents_as(attribute, &block)
+            @presentation_attribute = attribute
+            @presentation_block = block
+          end
+
+          # Returns the configured presentation attribute.
+          #
+          # @return [Symbol] attribute name used for string representation
+          def presentation_attribute
+            @presentation_attribute || :title
+          end
+
+          # Returns the configured presentation block, if any.
+          #
+          # @return [Proc, nil] custom formatting block or nil if using attribute directly
+          def presentation_block
+            @presentation_block
+          end
+
+          # Configure the default fields shown in CLI detail view.
+          #
+          # @param fields [Array<Symbol>] field names for detail output
+          # @return [Array<Symbol>] the configured detail fields
+          def detail_fields(*fields)
+            if fields.empty?
+              @detail_fields || []
+            else
+              @detail_fields = fields.flatten
+            end
+          end
+
+          # Configure the default columns shown in CLI list view.
+          #
+          # @param columns [Array<Symbol>] column names for list output
+          # @return [Array<Symbol>] the configured list columns
+          def list_columns(*columns)
+            if columns.empty?
+              @list_columns || []
+            else
+              @list_columns = columns.flatten
+            end
+          end
+        end
+
+        # Returns the string representation using the configured attribute or block.
+        #
+        # @return [String] formatted string for display
+        def to_s
+          if self.class.presentation_block
+            instance_eval(&self.class.presentation_block).to_s
+          else
+            send(self.class.presentation_attribute).to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superthread/models/concerns/timestampable.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Models
+    module Concerns
+      # Provides a DSL for defining timestamp accessor methods.
+      #
+      # Converts Unix timestamps (integers) to Ruby Time objects automatically.
+      # Supports both auto-generated method names and explicit mappings.
+      #
+      # @example
+      #   class Card < Superthread::Model
+      #     include Concerns::Timestampable
+      #
+      #     attribute :time_created, Shale::Type::Integer
+      #     attribute :time_updated, Shale::Type::Integer
+      #     attribute :start_date, Shale::Type::Integer
+      #
+      #     timestamps :time_created, :time_updated
+      #     timestamps start_date: :start_time, due_date: :due_time
+      #   end
+      #
+      #   card.created_at  # => Time object
+      #   card.start_time  # => Time object
+      module Timestampable
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Define timestamp accessor methods.
+          #
+          # With symbols, creates standard accessor names:
+          # - time_created -> created_at
+          # - time_updated -> updated_at
+          # - start_date -> start_time
+          #
+          # With hash, creates custom accessor names (e.g., start_date: :start_time).
+          #
+          # @param fields [Array<Symbol>] attribute names to create accessors for
+          # @param mappings [Hash{Symbol => Symbol}] explicit attribute to method name mappings
+          # @return [void]
+          def timestamps(*fields, **mappings)
+            # Handle simple field names with auto-generated method names
+            fields.each do |field|
+              method_name = derive_method_name(field)
+              define_timestamp_method(field, method_name)
+            end
+
+            # Handle explicit field => method mappings
+            mappings.each do |field, method_name|
+              define_timestamp_method(field, method_name)
+            end
+          end
+
+          private
+
+          # Derives a conventional method name from a timestamp field name.
+          #
+          # @param field [Symbol] the attribute name
+          # @return [Symbol] the derived method name
+          def derive_method_name(field)
+            name = field.to_s
+            if name.start_with?("time_")
+              # time_created -> created_at, time_updated -> updated_at
+              name.sub(/^time_/, "").concat("_at").to_sym
+            elsif name.end_with?("_date")
+              # start_date -> start_time, due_date -> due_time
+              name.sub(/_date$/, "_time").to_sym
+            else
+              # fallback: field_at
+              :"#{name}_at"
+            end
+          end
+
+          # Defines an instance method that converts a Unix timestamp to Time.
+          #
+          # @param field [Symbol] the source attribute name
+          # @param method_name [Symbol] the accessor method name to define
+          # @return [void]
+          def define_timestamp_method(field, method_name)
+            define_method(method_name) do
+              ts = send(field)
+              (ts && ts != 0) ? Time.at(ts) : nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superthread/models/list.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a list (column) on a board.
+    #
+    # Lists are vertical columns on a Kanban board that contain cards.
+    # They have a position for ordering and an optional color for visual distinction.
+    #
+    # @example
+    #   list = board.lists.first
+    #   list.title      # => "To Do"
+    #   list.color      # => "blue"
+    #   list.position   # => 0
+    #   list.archived?  # => false
+    class List < Superthread::Model
+      include Concerns::Archivable
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :color, :position, :board_id
+      list_columns :id, :title, :color
+
+      # @!attribute [rw] id
+      #   @return [String] unique list identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] type
+      #   @return [String] list type
+      attribute :type, Shale::Type::String
+
+      # @!attribute [rw] board_id
+      #   @return [String] ID of the board this list belongs to
+      attribute :board_id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the list
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] color
+      #   @return [String] color code for visual styling
+      attribute :color, Shale::Type::String
+
+      # @!attribute [rw] position
+      #   @return [Integer] zero-based position for ordering lists on the board
+      attribute :position, Shale::Type::Integer
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the list
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the list was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the list was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] archived
+      #   @return [Hash{String => Object}, nil] archive metadata with user_id and time_archived
+      attribute :archived, Shale::Type::Value
+
+      timestamps :time_created, :time_updated
+    end
+  end
+end

data/lib/superthread/models/member.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a card member assignment.
+    #
+    # Members link users to cards with a specific role (e.g., assignee).
+    # They track when the assignment was made.
+    #
+    # @example
+    #   member = card.members.first
+    #   member.user_id      # => "user-123"
+    #   member.role         # => "assignee"
+    #   member.assigned_at  # => 2024-01-15 10:30:00 -0800
+    class Member < Superthread::Model
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      presents_as(:display_name) { display_name || user_id }
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the assigned user
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] display_name
+      #   @return [String, nil] display name of the assigned user (enriched client-side)
+      attribute :display_name, Shale::Type::String
+
+      # @!attribute [rw] role
+      #   @return [String] assignment role (e.g., "assignee")
+      attribute :role, Shale::Type::String
+
+      # @!attribute [rw] assigned_date
+      #   @return [Integer] Unix timestamp when the user was assigned
+      attribute :assigned_date, Shale::Type::Integer
+
+      timestamps assigned_date: :assigned_at
+    end
+  end
+end

data/lib/superthread/models/note.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread note.
+    #
+    # Notes are standalone documents within a workspace, used for
+    # meeting notes, documentation, or other text content.
+    #
+    # @example
+    #   note = client.notes.find(workspace_id, note_id)
+    #   note.title       # => "Meeting Notes"
+    #   note.content     # => "<p>Discussed...</p>"
+    class Note < Superthread::Model
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :time_created
+      list_columns :id, :title
+
+      # @!attribute [rw] id
+      #   @return [String] unique note identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] type
+      #   @return [String] note type
+      attribute :type, Shale::Type::String
+
+      # @!attribute [rw] team_id
+      #   @return [String] ID of the team/workspace this note belongs to
+      attribute :team_id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the note
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] content
+      #   @return [String] HTML content of the note
+      attribute :content, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the note
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the note was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the note was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      timestamps :time_created, :time_updated
+    end
+  end
+end

data/lib/superthread/models/page.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread page (document).
+    #
+    # Pages are wiki-style documents that live within spaces. They support
+    # rich text content, icons, and can be archived.
+    #
+    # @example
+    #   page = client.pages.find(workspace_id, page_id)
+    #   page.title       # => "Project Overview"
+    #   page.content     # => "<p>This project...</p>"
+    #   page.archived?   # => false
+    class Page < Superthread::Model
+      include Concerns::Archivable
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :space_id, :time_created, :time_updated
+      list_columns :id, :title
+
+      # @!attribute [rw] id
+      #   @return [String] unique page identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] type
+      #   @return [String] page type
+      attribute :type, Shale::Type::String
+
+      # @!attribute [rw] team_id
+      #   @return [String] ID of the team/workspace this page belongs to
+      attribute :team_id, Shale::Type::String
+
+      # @!attribute [rw] space_id
+      #   @return [String] ID of the space this page belongs to
+      attribute :space_id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the page
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] content
+      #   @return [String] HTML content of the page
+      attribute :content, Shale::Type::String
+
+      # @!attribute [rw] icon
+      #   @return [String] emoji or icon identifier for the page
+      attribute :icon, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the page
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the page was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the page was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] archived
+      #   @return [Hash{String => Object}, nil] archive metadata with user_id and time_archived
+      attribute :archived, Shale::Type::Value
+
+      timestamps :time_created, :time_updated
+    end
+  end
+end

data/lib/superthread/models/project.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread project (epic/roadmap item).
+    #
+    # Projects are high-level work items that group related cards together.
+    # They have their own timeline with start and due dates.
+    #
+    # @example
+    #   project = client.projects.find(workspace_id, project_id)
+    #   project.title       # => "Q4 Planning"
+    #   project.status      # => "active"
+    #   project.archived?   # => false
+    class Project < Superthread::Model
+      include Concerns::Archivable
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :status, :start_date, :due_date
+      list_columns :id, :title, :status
+
+      # @!attribute [rw] id
+      #   @return [String] unique project identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] type
+      #   @return [String] project type
+      attribute :type, Shale::Type::String
+
+      # @!attribute [rw] team_id
+      #   @return [String] ID of the team/workspace this project belongs to
+      attribute :team_id, Shale::Type::String
+
+      # @!attribute [rw] space_id
+      #   @return [String] ID of the space this project belongs to
+      attribute :space_id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the project
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] description
+      #   @return [String] project description or summary
+      attribute :description, Shale::Type::String
+
+      # @!attribute [rw] status
+      #   @return [String] project status (e.g., "active", "completed")
+      attribute :status, Shale::Type::String
+
+      # @!attribute [rw] icon
+      #   @return [String] emoji or icon identifier for the project
+      attribute :icon, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the project
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] start_date
+      #   @return [Integer] Unix timestamp when the project starts
+      attribute :start_date, Shale::Type::Integer
+
+      # @!attribute [rw] due_date
+      #   @return [Integer] Unix timestamp when the project is due
+      attribute :due_date, Shale::Type::Integer
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the project was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the project was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] archived
+      #   @return [Hash{String => Object}, nil] archive metadata with user_id and time_archived
+      attribute :archived, Shale::Type::Value
+
+      timestamps :time_created, :time_updated
+      timestamps start_date: :start_time, due_date: :due_time
+    end
+  end
+end