superthread 0.7.2

data/lib/superthread/objects/collection.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Superthread
+  # Container classes for API response wrappers.
+  module Objects
+    # Represents a collection of objects returned from list endpoints.
+    # Wraps arrays with additional metadata and convenience methods.
+    #
+    # @example
+    #   cards = client.cards.assigned(workspace_id, user_id: user_id)
+    #   cards.each { |card| puts card.title }
+    #   cards.count        # => 5
+    #   cards.empty?       # => false
+    #   cards.to_a         # => [#<Superthread::Models::Card ...>, ...]
+    class Collection
+      include Enumerable
+
+      # @return [Array<Superthread::Object, Superthread::Model>] the items in the collection
+      attr_reader :items
+
+      # @return [Hash{Symbol => Object}] raw response data
+      attr_reader :data
+
+      # Creates a new collection from API response data.
+      #
+      # @param data [Hash{Symbol => Object}] the raw API response
+      # @param key [Symbol, String, nil] the key containing the items array (auto-detected if nil)
+      # @param item_class [Class, nil] the class to use for items (auto-detected if nil)
+      def initialize(data, key: nil, item_class: nil)
+        @data = data.is_a?(Hash) ? data.transform_keys(&:to_sym) : {}
+        @item_class = item_class
+
+        # Extract items from the response
+        items_data = extract_items(key)
+        @items = items_data.map { |item| wrap_item(item) }
+      end
+
+      # Constructs a collection from an API response.
+      #
+      # @param data [Hash{Symbol => Object}, Array<Hash>] the API response
+      # @param key [Symbol, String, nil] the key containing items (auto-detected if nil)
+      # @param item_class [Class, nil] the class for items (auto-detected if nil)
+      # @return [Superthread::Objects::Collection] the constructed collection
+      def self.from_response(data, key: nil, item_class: nil)
+        # If the response is already an array, wrap it
+        if data.is_a?(Array)
+          new({items: data}, key: :items, item_class: item_class)
+        else
+          new(data, key: key, item_class: item_class)
+        end
+      end
+
+      # Iterates over items in the collection.
+      #
+      # @param block [Proc] receives each item in the collection
+      # @yieldparam item [Superthread::Object, Superthread::Model] an item
+      # @return [Enumerator] if no block given
+      def each(&block)
+        @items.each(&block)
+      end
+
+      # Returns the number of items in the collection.
+      #
+      # @return [Integer] item count
+      def count
+        @items.count
+      end
+      alias_method :size, :count
+      alias_method :length, :count
+
+      # Checks if the collection is empty.
+      #
+      # @return [Boolean] true if no items
+      def empty?
+        @items.empty?
+      end
+
+      # Returns the first item.
+      #
+      # @return [Superthread::Object, Superthread::Model, nil] first item or nil if empty
+      def first
+        @items.first
+      end
+
+      # Returns the last item.
+      #
+      # @return [Superthread::Object, Superthread::Model, nil] last item or nil if empty
+      def last
+        @items.last
+      end
+
+      # Accesses an item by index.
+      #
+      # @param index [Integer] the zero-based index
+      # @return [Superthread::Object, Superthread::Model, nil] item at index or nil if out of bounds
+      def [](index)
+        @items[index]
+      end
+
+      # Converts the collection to an array.
+      #
+      # @return [Array<Superthread::Object, Superthread::Model>] copy of items array
+      def to_a
+        @items.dup
+      end
+      alias_method :to_ary, :to_a
+
+      # Converts the collection to an array of hashes.
+      #
+      # @return [Array<Hash{Symbol => Object}>] array of hash representations
+      def to_h
+        @items.map(&:to_h)
+      end
+
+      # Returns raw response metadata (everything except items).
+      #
+      # @return [Hash{Symbol => Object}] metadata from the API response
+      def metadata
+        @data.except(*items_keys)
+      end
+
+      private
+
+      # Common keys that contain item arrays in API responses.
+      ITEMS_KEYS = %i[items cards boards lists users projects spaces sprints
+        pages notes comments tags members results data].freeze
+
+      # Returns the list of common item keys.
+      #
+      # @return [Array<Symbol>] keys that typically contain item arrays
+      def items_keys
+        ITEMS_KEYS
+      end
+
+      # Extracts items array from the response data.
+      #
+      # @param key [Symbol, String, nil] the key to extract, or nil to auto-detect
+      # @return [Array<Hash>] the extracted items array
+      def extract_items(key)
+        if key
+          @data[key.to_sym] || []
+        else
+          # Auto-detect items key
+          ITEMS_KEYS.each do |k|
+            return @data[k] if @data[k].is_a?(Array)
+          end
+          # If nothing found, check if the response itself has a single array value
+          @data.values.find { |v| v.is_a?(Array) } || []
+        end
+      end
+
+      # Wraps a hash item in the appropriate object class.
+      #
+      # @param item [Hash, Object] the item to wrap
+      # @return [Superthread::Object, Superthread::Model] the wrapped item
+      def wrap_item(item)
+        return item unless item.is_a?(Hash)
+
+        if @item_class
+          if shale_model?(@item_class)
+            @item_class.from_response(item)
+          else
+            @item_class.new(item)
+          end
+        else
+          Superthread::Object.construct_from(item)
+        end
+      end
+
+      # Checks if a class is a Shale model.
+      #
+      # @param klass [Class] the class to check
+      # @return [Boolean] true if the class is a Shale model
+      def shale_model?(klass)
+        Superthread::Model.shale_class?(klass)
+      end
+    end
+  end
+end

data/lib/superthread/resources/base.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Superthread
+  # API resource classes for interacting with Superthread endpoints.
+  module Resources
+    # Base class for all API resources.
+    #
+    # Provides HTTP helpers, ID validation, and response handling shared
+    # by all resource classes. Subclasses should use the protected HTTP
+    # methods to interact with the Superthread API.
+    class Base
+      # Initializes a new resource instance.
+      #
+      # @param client [Superthread::Client] the API client for making requests
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      # Performs a GET request and returns raw response data.
+      #
+      # @param path [String] the API endpoint path
+      # @param params [Hash{Symbol => Object}, nil] optional query parameters
+      # @return [Hash{Symbol => Object}] the parsed response body
+      def http_get(path, params: nil)
+        @client.request(method: :get, path: path, params: params)
+      end
+
+      # Performs a POST request and returns raw response data.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash{Symbol => Object}, nil] optional request body
+      # @return [Hash{Symbol => Object}] the parsed response body
+      def http_post(path, body: nil)
+        @client.request(method: :post, path: path, body: body)
+      end
+
+      # Performs a PATCH request and returns raw response data.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash{Symbol => Object}, nil] optional request body
+      # @return [Hash{Symbol => Object}] the parsed response body
+      def http_patch(path, body: nil)
+        @client.request(method: :patch, path: path, body: body)
+      end
+
+      # Performs a DELETE request and returns raw response data.
+      #
+      # @param path [String] the API endpoint path
+      # @return [Hash{Symbol => Object}] the parsed response body
+      def http_delete(path)
+        @client.request(method: :delete, path: path)
+      end
+
+      # Performs a GET request and returns a typed object.
+      #
+      # @param path [String] the API endpoint path
+      # @param params [Hash{Symbol => Object}, nil] optional query parameters
+      # @param object_class [Class, nil] the model class to instantiate
+      # @param unwrap_key [Symbol, nil] key to extract from response before wrapping
+      # @return [Superthread::Object] the response wrapped in an object
+      def get_object(path, params: nil, object_class: nil, unwrap_key: nil)
+        @client.request_object(
+          method: :get, path: path, params: params,
+          object_class: object_class, unwrap_key: unwrap_key
+        )
+      end
+
+      # Performs a POST request and returns a typed object.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash{Symbol => Object}, nil] optional request body
+      # @param object_class [Class, nil] the model class to instantiate
+      # @param unwrap_key [Symbol, nil] key to extract from response before wrapping
+      # @return [Superthread::Object] the response wrapped in an object
+      def post_object(path, body: nil, object_class: nil, unwrap_key: nil)
+        @client.request_object(
+          method: :post, path: path, body: body,
+          object_class: object_class, unwrap_key: unwrap_key
+        )
+      end
+
+      # Performs a PATCH request and returns a typed object.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash{Symbol => Object}, nil] optional request body
+      # @param object_class [Class, nil] the model class to instantiate
+      # @param unwrap_key [Symbol, nil] key to extract from response before wrapping
+      # @return [Superthread::Object] the response wrapped in an object
+      def patch_object(path, body: nil, object_class: nil, unwrap_key: nil)
+        @client.request_object(
+          method: :patch, path: path, body: body,
+          object_class: object_class, unwrap_key: unwrap_key
+        )
+      end
+
+      # Performs a DELETE request and returns a typed object.
+      #
+      # @param path [String] the API endpoint path
+      # @param object_class [Class, nil] the model class to instantiate
+      # @param unwrap_key [Symbol, nil] key to extract from response before wrapping
+      # @return [Superthread::Object] the response wrapped in an object
+      def delete_object(path, object_class: nil, unwrap_key: nil)
+        @client.request_object(
+          method: :delete, path: path,
+          object_class: object_class, unwrap_key: unwrap_key
+        )
+      end
+
+      # Performs a GET request and returns a collection of objects.
+      #
+      # @param path [String] the API endpoint path
+      # @param params [Hash{Symbol => Object}, nil] optional query parameters
+      # @param item_class [Class, nil] the model class for collection items
+      # @param items_key [Symbol, nil] key containing the array in response
+      # @return [Superthread::Objects::Collection] the collection of items
+      def get_collection(path, params: nil, item_class: nil, items_key: nil)
+        @client.request_collection(
+          method: :get, path: path, params: params,
+          item_class: item_class, items_key: items_key
+        )
+      end
+
+      # Performs a POST request and returns a collection of objects.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash{Symbol => Object}, nil] optional request body
+      # @param item_class [Class, nil] the model class for collection items
+      # @param items_key [Symbol, nil] key containing the array in response
+      # @return [Superthread::Objects::Collection] the collection of items
+      def post_collection(path, body: nil, item_class: nil, items_key: nil)
+        @client.request_collection(
+          method: :post, path: path, body: body,
+          item_class: item_class, items_key: items_key
+        )
+      end
+
+      # Validates and sanitizes an ID to prevent path traversal attacks.
+      #
+      # Only allows alphanumeric characters, hyphens, and underscores.
+      #
+      # @param name [String] descriptive name for error messages (e.g., "workspace_id")
+      # @param value [String] the ID value to validate
+      # @return [String] the sanitized ID
+      # @raise [Superthread::PathValidationError] if the value is nil, empty, or contains invalid characters
+      # @example
+      #   safe_id("workspace_id", "ws-123_abc") # => "ws-123_abc"
+      #   safe_id("card_id", "../evil")         # raises PathValidationError
+      def safe_id(name, value)
+        raise Superthread::PathValidationError, "#{name} must be a non-empty string" if value.nil? || value.to_s.empty?
+
+        cleaned = value.to_s.strip.gsub(/[^a-zA-Z0-9_-]/, "")
+
+        if cleaned.empty?
+          raise Superthread::PathValidationError,
+            "#{name} must contain only letters, numbers, hyphen, or underscore"
+        end
+
+        cleaned
+      end
+
+      # Filters nil values from a params hash.
+      #
+      # Accepts arbitrary keyword arguments and returns only non-nil values.
+      # Used internally to clean up API request parameters.
+      #
+      # @param args [Hash{Symbol => Object}] arbitrary key-value pairs to filter
+      # @option args [Object] :any any key-value pair (nil values will be removed)
+      # @return [Hash{Symbol => Object}] hash with nil values removed
+      def compact_params(**args)
+        args.compact
+      end
+
+      # Formats {{@mentions}} in content to HTML user-mention tags.
+      #
+      # @param workspace_id [String] the workspace identifier for member lookup
+      # @param content [String, nil] text that may contain {{@Name}} patterns
+      # @return [String, nil] content with mentions converted to HTML tags
+      def format_mentions(workspace_id, content)
+        return content if content.nil?
+
+        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
+      def success_response
+        Superthread::Object.new(success: true)
+      end
+    end
+  end
+end

data/lib/superthread/resources/boards.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Resources
+    # API resource for board operations.
+    #
+    # Provides methods for creating, listing, updating, and deleting boards
+    # and their lists (columns) via the Superthread API.
+    class Boards < Base
+      # Creates a new board in a space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier (maps to project_id in API)
+      # @param title [String] the board title
+      # @param params [Hash{Symbol => Object}] optional board parameters
+      # @option params [String] :content the board description content
+      # @option params [String] :icon the board icon identifier
+      # @option params [String] :color the board color hex code
+      # @option params [String] :layout the board layout type
+      # @return [Superthread::Models::Board] the created board
+      def create(workspace_id, space_id:, title:, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        body = compact_params(title: title, project_id: space_id, **params)
+        post_object("/#{ws}/boards", body: body,
+          object_class: Models::Board, unwrap_key: :board)
+      end
+
+      # Lists all boards in a space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier to filter by
+      # @param bookmarked [Boolean, nil] when true, returns only bookmarked boards
+      # @param archived [Boolean, nil] when true, includes archived boards
+      # @return [Superthread::Objects::Collection<Superthread::Models::Board>] the boards in the space
+      def list(workspace_id, space_id:, bookmarked: nil, archived: nil)
+        ws = safe_id("workspace_id", workspace_id)
+        params = compact_params(project_id: space_id, bookmarked: bookmarked, archived: archived)
+        get_collection("/#{ws}/boards", params: params,
+          item_class: Models::Board, items_key: :boards)
+      end
+
+      # Gets a specific board with its lists and cards.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param board_id [String] the board identifier
+      # @return [Superthread::Models::Board] the board with nested lists and cards
+      def find(workspace_id, board_id)
+        ws = safe_id("workspace_id", workspace_id)
+        board = safe_id("board_id", board_id)
+        get_object("/#{ws}/boards/#{board}",
+          object_class: Models::Board, unwrap_key: :board)
+      end
+
+      # Updates a board's attributes.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param board_id [String] the board identifier
+      # @param params [Hash{Symbol => Object}] the attributes to update
+      # @option params [String] :title the new board title
+      # @option params [String] :content the new board description
+      # @option params [String] :icon the new board icon identifier
+      # @option params [String] :color the new board color hex code
+      # @option params [Boolean] :archived whether the board is archived
+      # @return [Superthread::Models::Board] the updated board
+      def update(workspace_id, board_id, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        board = safe_id("board_id", board_id)
+        patch_object("/#{ws}/boards/#{board}", body: compact_params(**params),
+          object_class: Models::Board, unwrap_key: :board)
+      end
+
+      # Duplicates a board to a destination space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param board_id [String] the board identifier to duplicate
+      # @param space_id [String] the destination space identifier
+      # @param title [String, nil] the title for the duplicated board (defaults to original)
+      # @param copy_cards [Boolean, nil] when true, copies all cards to the new board
+      # @param create_missing_tags [Boolean, nil] when true, creates tags that do not exist in target space
+      # @return [Superthread::Models::Board] the duplicated board
+      def duplicate(workspace_id, board_id, space_id:, title: nil, copy_cards: nil, create_missing_tags: nil)
+        ws = safe_id("workspace_id", workspace_id)
+        board = safe_id("board_id", board_id)
+        body = compact_params(project_id: space_id, title: title, copy_cards: copy_cards, create_missing_tags: create_missing_tags)
+        post_object("/#{ws}/boards/#{board}/copy", body: body,
+          object_class: Models::Board, unwrap_key: :board)
+      end
+
+      # Deletes a board permanently.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param board_id [String] the board identifier to delete
+      # @return [Superthread::Object] a response object with success: true
+      def destroy(workspace_id, board_id)
+        ws = safe_id("workspace_id", workspace_id)
+        board = safe_id("board_id", board_id)
+        http_delete("/#{ws}/boards/#{board}")
+        success_response
+      end
+
+      # Creates a list (column) on a board.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param board_id [String] the board identifier to add the list to
+      # @param title [String] the list title
+      # @param params [Hash{Symbol => Object}] optional list parameters
+      # @option params [String] :content the list description content
+      # @option params [String] :icon the list icon identifier
+      # @option params [String] :color the list color hex code
+      # @option params [String] :behavior the list behavior type (e.g., "done")
+      # @return [Superthread::Models::List] the created list
+      def create_list(workspace_id, board_id:, title:, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        body = compact_params(board_id: board_id, title: title, **params)
+        post_object("/#{ws}/lists", body: body,
+          object_class: Models::List, unwrap_key: :list)
+      end
+
+      # Updates a list's attributes.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param list_id [String] the list identifier
+      # @param params [Hash{Symbol => Object}] the attributes to update
+      # @option params [String] :title the new list title
+      # @option params [String] :content the new list description
+      # @option params [String] :icon the new list icon identifier
+      # @option params [String] :color the new list color hex code
+      # @option params [String] :behavior the new list behavior type
+      # @return [Superthread::Models::List] the updated list
+      def update_list(workspace_id, list_id, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        list = safe_id("list_id", list_id)
+        patch_object("/#{ws}/lists/#{list}", body: compact_params(**params),
+          object_class: Models::List, unwrap_key: :list)
+      end
+
+      # Deletes a list permanently.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param list_id [String] the list identifier to delete
+      # @return [Superthread::Object] a response object with success: true
+      def delete_list(workspace_id, list_id)
+        ws = safe_id("workspace_id", workspace_id)
+        list = safe_id("list_id", list_id)
+        http_delete("/#{ws}/lists/#{list}")
+        success_response
+      end
+    end
+  end
+end