superthread 0.7.2

data/lib/superthread/models/space.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread space.
+    #
+    # Spaces are organizational containers within a workspace that group
+    # related projects, pages, and other content. They can have dedicated
+    # members with specific access.
+    #
+    # @example
+    #   space = client.spaces.find(workspace_id, space_id)
+    #   space.title       # => "Engineering"
+    #   space.members     # => [#<Superthread::Models::Member ...>]
+    #   space.archived?   # => false
+    class Space < Superthread::Model
+      include Concerns::Archivable
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :description, :time_created
+      list_columns :id, :title
+
+      # @!attribute [rw] id
+      #   @return [String] unique space identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] type
+      #   @return [String] space type
+      attribute :type, Shale::Type::String
+
+      # @!attribute [rw] team_id
+      #   @return [String] ID of the team/workspace this space belongs to
+      attribute :team_id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the space
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] description
+      #   @return [String] space description or purpose
+      attribute :description, Shale::Type::String
+
+      # @!attribute [rw] icon
+      #   @return [Object] emoji or icon data for the space
+      attribute :icon, Shale::Type::Value
+
+      # @!attribute [rw] user_id
+      #   @return [String] ID of the user who created the space
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the space was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the space was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] members
+      #   @return [Array<Member>] users with access to this space
+      attribute :members, Member, collection: true
+
+      # @!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/sprint.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread sprint.
+    #
+    # Sprints are time-boxed iterations used for agile planning. Cards
+    # can be assigned to sprints to organize work into release cycles.
+    #
+    # @example
+    #   sprint = client.sprints.find(workspace_id, sprint_id)
+    #   sprint.title       # => "Sprint 42"
+    #   sprint.start_time  # => 2024-01-15 00:00:00 UTC
+    class Sprint < Superthread::Model
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      detail_fields :id, :title, :start_date, :time_created, :time_updated
+      list_columns :id, :title, :status
+
+      # @!attribute [rw] id
+      #   @return [String] unique sprint identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] team_id
+      #   @return [String] ID of the team/workspace this sprint belongs to
+      attribute :team_id, Shale::Type::String
+
+      # @!attribute [rw] title
+      #   @return [String] display title of the sprint
+      attribute :title, Shale::Type::String
+
+      # @!attribute [rw] start_date
+      #   @return [Integer] Unix timestamp when the sprint starts
+      attribute :start_date, Shale::Type::Integer
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the sprint was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the sprint was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] lists
+      #   @return [Array<List>] columns/lists available in this sprint
+      attribute :lists, List, collection: true
+
+      timestamps :time_created, :time_updated
+      timestamps start_date: :start_time
+    end
+  end
+end

data/lib/superthread/models/tag.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread tag/label.
+    #
+    # Tags are colored labels that can be applied to cards for categorization
+    # and filtering. They track how many cards use each tag.
+    #
+    # @example
+    #   tag = card.tags.first
+    #   tag.name         # => "bug"
+    #   tag.color        # => "red"
+    #   tag.total_cards  # => 17
+    class Tag < Superthread::Model
+      include Concerns::Presentable
+
+      presents_as :name
+
+      detail_fields :id, :name, :color, :total_cards
+      list_columns :id, :name, :color
+
+      # @!attribute [rw] id
+      #   @return [String] unique tag identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] team_id
+      #   @return [String] ID of the team/workspace this tag belongs to
+      attribute :team_id, Shale::Type::String
+
+      # @!attribute [rw] project_id
+      #   @return [String] ID of the project this tag is scoped to, if any
+      attribute :project_id, Shale::Type::String
+
+      # @!attribute [rw] name
+      #   @return [String] display name of the tag
+      attribute :name, Shale::Type::String
+
+      # @!attribute [rw] slug
+      #   @return [String] URL-safe version of the tag name
+      attribute :slug, Shale::Type::String
+
+      # @!attribute [rw] color
+      #   @return [String] color code for visual styling
+      attribute :color, Shale::Type::String
+
+      # @!attribute [rw] total_cards
+      #   @return [Integer] number of cards using this tag
+      attribute :total_cards, Shale::Type::Integer
+    end
+  end
+end

data/lib/superthread/models/team.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread team/workspace.
+    #
+    # Teams are the top-level organizational unit in Superthread. All boards,
+    # projects, spaces, and users belong to a team. Users can be members of
+    # multiple teams.
+    #
+    # @example
+    #   user = client.users.me
+    #   user.teams.each do |team|
+    #     puts "#{team.team_name} (#{team.id})"
+    #   end
+    class Team < Superthread::Model
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      presents_as :team_name
+
+      # @!attribute [rw] id
+      #   @return [String] unique team identifier (workspace ID)
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] team_name
+      #   @return [String] display name of the team
+      attribute :team_name, Shale::Type::String
+
+      # @!attribute [rw] sub_domain
+      #   @return [String] subdomain for the team's Superthread URL
+      attribute :sub_domain, Shale::Type::String
+
+      # @!attribute [rw] role
+      #   @return [String] current user's role in this team
+      attribute :role, Shale::Type::String
+
+      # @!attribute [rw] status
+      #   @return [String] team status (e.g., "active")
+      attribute :status, Shale::Type::String
+
+      # @!attribute [rw] creator_user_id
+      #   @return [String] ID of the user who created the team
+      attribute :creator_user_id, Shale::Type::String
+
+      # @!attribute [rw] subscription_plan_id
+      #   @return [String] ID of the team's subscription plan
+      attribute :subscription_plan_id, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the team was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the team was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      timestamps :time_created
+
+      # Alias for team_name for consistency.
+      #
+      # @return [String] Team/workspace name
+      def name
+        team_name
+      end
+    end
+  end
+end

data/lib/superthread/models/user.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Models
+    # Represents a Superthread user.
+    #
+    # Users are people who can access Superthread workspaces. They have
+    # profiles with display names, emails, and avatars, and can be members
+    # of multiple teams.
+    #
+    # @example
+    #   user = client.users.me
+    #   user.display_name    # => "John Doe"
+    #   user.email           # => "john@example.com"
+    #   user.id              # => "u123"
+    class User < Superthread::Model
+      include Concerns::Presentable
+      include Concerns::Timestampable
+
+      presents_as :display_name
+
+      detail_fields :user_id, :display_name, :email, :role
+      list_columns :user_id, :display_name, :email
+
+      # @!attribute [rw] id
+      #   @return [String] unique user identifier
+      attribute :id, Shale::Type::String
+
+      # @!attribute [rw] user_id
+      #   @return [String] alternate user identifier (API returns both in different contexts)
+      attribute :user_id, Shale::Type::String
+
+      # @!attribute [rw] type
+      #   @return [String] user type
+      attribute :type, Shale::Type::String
+
+      # @!attribute [rw] display_name
+      #   @return [String] user's display name
+      attribute :display_name, Shale::Type::String
+
+      # @!attribute [rw] email
+      #   @return [String] user's email address
+      attribute :email, Shale::Type::String
+
+      # @!attribute [rw] avatar
+      #   @return [String] URL to the user's avatar image
+      attribute :avatar, Shale::Type::String
+
+      # @!attribute [rw] role
+      #   @return [String] user's role within the current context
+      attribute :role, Shale::Type::String
+
+      # @!attribute [rw] time_created
+      #   @return [Integer] Unix timestamp when the user account was created
+      attribute :time_created, Shale::Type::Integer
+
+      # @!attribute [rw] time_updated
+      #   @return [Integer] Unix timestamp when the user was last updated
+      attribute :time_updated, Shale::Type::Integer
+
+      # @!attribute [rw] teams
+      #   @return [Array<Team>] teams/workspaces this user belongs to
+      attribute :teams, Team, collection: true
+
+      timestamps :time_created, :time_updated
+
+      # Returns the user ID, checking both 'id' and 'user_id' fields
+      # (API returns different fields in different contexts)
+      #
+      # @return [String] User ID
+      def user_identifier
+        id || user_id
+      end
+    end
+  end
+end

data/lib/superthread/models.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Superthread
+  # Namespace for Shale-based API response models.
+  #
+  # These typed models are replacing the generic Superthread::Object
+  # classes, providing better type safety and validation.
+  #
+  # @see Superthread::Model Base class for all models
+  module Models
+  end
+end

data/lib/superthread/object.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Superthread
+  # Generic wrapper for API response objects (legacy pattern).
+  #
+  # Prefer {Superthread::Model} (Shale-based) for new resource types.
+  # This class is retained for backward compatibility with endpoints
+  # that haven't been migrated to typed models yet.
+  #
+  # Provides hash-like access, dot notation via method_missing, and conversion to Hash.
+  #
+  # Inspired by Stripe's StripeObject pattern - allows both:
+  #   card.title        # dot notation
+  #   card[:title]      # symbol key access
+  #   card["title"]     # string key access
+  #   card.to_h         # convert to plain hash
+  #
+  # @example
+  #   card = client.cards.find(workspace_id, card_id)
+  #   card.title              # => "My Card"
+  #   card[:title]            # => "My Card"
+  #   card.members.first.role # => "admin"
+  #   card.to_h               # => { id: "123", title: "My Card", ... }
+  class Object
+    include Enumerable
+
+    # @return [Hash] The raw data from the API response
+    attr_reader :data
+
+    # Creates a new object from a Hash or another SuperthreadObject.
+    #
+    # @param data [Hash, Superthread::Object] The data to wrap
+    def initialize(data = {})
+      @data = case data
+      when Hash
+        data.transform_keys(&:to_sym)
+      when Superthread::Object
+        data.data.dup
+      else
+        {}
+      end
+    end
+
+    # Factory method to construct the appropriate typed object from API response data.
+    # Uses the "type" field in the response to determine the class.
+    #
+    # @param data [Hash, Array, nil] The API response data
+    # @return [Superthread::Object, Array, nil] The constructed object(s)
+    def self.construct_from(data)
+      case data
+      when Array
+        data.map { |item| construct_from(item) }
+      when Hash
+        klass = object_class_for(data)
+        klass.new(data)
+      else
+        data
+      end
+    end
+
+    # Determines the appropriate class for the given data based on the "type" field.
+    #
+    # @param data [Hash] The data hash
+    # @return [Class] The class to use for construction
+    def self.object_class_for(data)
+      type = data[:type] || data["type"]
+      @object_types.fetch(type, Superthread::Object)
+    end
+
+    # Registry mapping API "type" values to Ruby classes.
+    #
+    # Subclasses register themselves here.
+    #
+    # @note This hash is intentionally mutable for dynamic registration.
+    @object_types = {}
+
+    class << self
+      attr_reader :object_types
+    end
+
+    # Registers a subclass for a given type name.
+    # Called automatically when OBJECT_NAME is defined on a subclass.
+    #
+    # @param type_name [String] The API type name
+    # @param klass [Class] The class to register
+    def self.register_type(type_name, klass)
+      @object_types[type_name] = klass
+    end
+
+    # Hook called when a subclass is defined.
+    #
+    # Automatically registers the subclass if it defines OBJECT_NAME.
+    #
+    # @param subclass [Class] the subclass being defined
+    # @return [void]
+    def self.inherited(subclass)
+      super
+      subclass.instance_eval do
+        def self.object_name
+          const_defined?(:OBJECT_NAME, false) ? const_get(:OBJECT_NAME) : nil
+        end
+      end
+    end
+
+    # Access a value by key (symbol or string).
+    #
+    # @param key [Symbol, String] The key to access
+    # @return [Object] The value, wrapped in a SuperthreadObject if it's a Hash
+    def [](key)
+      value = @data[key.to_sym]
+      wrap_value(value)
+    end
+
+    # Set a value by key.
+    #
+    # @param key [Symbol, String] The key to set
+    # @param value [Object] The value to set
+    def []=(key, value)
+      @data[key.to_sym] = value
+    end
+
+    # Iterate over key-value pairs.
+    #
+    # @param block [Proc] receives key-value pairs for each attribute
+    # @yieldparam key [Symbol] the attribute key
+    # @yieldparam value [Object] the attribute value (wrapped if Hash)
+    # @return [void]
+    def each(&block)
+      @data.each do |key, value|
+        block.call(key, wrap_value(value))
+      end
+    end
+
+    # Returns all keys.
+    #
+    # @return [Array<Symbol>] The keys
+    def keys
+      @data.keys
+    end
+
+    # Returns all values (wrapped).
+    #
+    # @return [Array] The values
+    def values
+      @data.values.map { |v| wrap_value(v) }
+    end
+
+    # Check if a key exists.
+    #
+    # @param key [Symbol, String] The key to check
+    # @return [Boolean] True if the key exists
+    def key?(key)
+      @data.key?(key.to_sym)
+    end
+    alias_method :has_key?, :key?
+
+    # Convert to a plain Hash (deep conversion).
+    #
+    # @return [Hash] A plain hash representation
+    def to_h
+      @data.transform_values do |value|
+        case value
+        when Superthread::Object
+          value.to_h
+        when Array
+          value.map { |v| v.respond_to?(:to_h) ? v.to_h : v }
+        when Hash
+          value.transform_values { |v| v.respond_to?(:to_h) ? v.to_h : v }
+        else
+          value
+        end
+      end
+    end
+    alias_method :to_hash, :to_h
+
+    # Convert to JSON string.
+    #
+    # @param args [Array] Arguments passed to JSON.generate
+    # @return [String] JSON representation
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Check equality based on data.
+    #
+    # @param other [Object] The object to compare
+    # @return [Boolean] True if equal
+    def ==(other)
+      case other
+      when Superthread::Object
+        @data == other.data
+      when Hash
+        @data == other.transform_keys(&:to_sym)
+      else
+        false
+      end
+    end
+    alias_method :eql?, :==
+
+    # Hash code for use in Hash keys.
+    #
+    # @return [Integer] Hash code
+    def hash
+      @data.hash
+    end
+
+    # String representation for debugging.
+    #
+    # @return [String] Debug representation
+    def inspect
+      "#<#{self.class.name} #{@data.inspect}>"
+    end
+
+    # Pretty string representation.
+    #
+    # @return [String] String representation
+    def to_s
+      inspect
+    end
+
+    # Check if the object has a given attribute.
+    # Supports predicate methods like `archived?`.
+    #
+    # @param method_name [Symbol] The method name
+    # @param include_private [Boolean] Whether to include private methods
+    # @return [Boolean] True if the method exists
+    def respond_to_missing?(method_name, include_private = false)
+      name = method_name.to_s
+      if name.end_with?("=")
+        true
+      elsif name.end_with?("?")
+        @data.key?(name.chomp("?").to_sym)
+      else
+        @data.key?(name.to_sym) || super
+      end
+    end
+
+    private
+
+    # Dynamic attribute access via method_missing.
+    #
+    # Supports:
+    #   - Getters: card.title
+    #   - Setters: card.title = "New Title"
+    #   - Predicates: card.archived?
+    #
+    # @param method_name [Symbol] the method being called
+    # @param args [Array] arguments passed to the method
+    # @return [Object] the attribute value or result of assignment
+    def method_missing(method_name, *args)
+      name = method_name.to_s
+
+      if name.end_with?("=")
+        # Setter: card.title = "New Title"
+        key = name.chomp("=").to_sym
+        @data[key] = args.first
+      elsif name.end_with?("?")
+        # Predicate: card.archived?
+        key = name.chomp("?").to_sym
+        !!@data[key]
+      elsif @data.key?(name.to_sym)
+        # Getter: card.title
+        wrap_value(@data[name.to_sym])
+      else
+        super
+      end
+    end
+
+    # Wraps values in SuperthreadObject instances for nested access.
+    # Arrays of Hashes become Arrays of SuperthreadObjects.
+    #
+    # @param value [Object] The value to wrap
+    # @return [Object] The wrapped value
+    def wrap_value(value)
+      case value
+      when Hash
+        Superthread::Object.construct_from(value)
+      when Array
+        value.map { |v| wrap_value(v) }
+      else
+        value
+      end
+    end
+  end
+end