activeproject 0.1.0 → 0.2.0

data/lib/active_project/adapters/trello/connection.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Trello
+      module Connection
+        BASE_URL = "https://api.trello.com/1/"
+        # @raise [ArgumentError] if required configuration options (:api_key, :api_token) are missing.
+        def initialize(config:)
+          unless config.is_a?(ActiveProject::Configurations::TrelloConfiguration)
+            raise ArgumentError, "TrelloAdapter requires a TrelloConfiguration object"
+          end
+
+          @config = config
+
+          unless @config.api_key && !@config.api_key.empty? && @config.api_token && !@config.api_token.empty?
+            raise ArgumentError, "TrelloAdapter configuration requires :api_key and :api_token"
+          end
+
+          @connection = initialize_connection
+        end
+
+        private
+
+        # Initializes the Faraday connection object.
+        def initialize_connection
+          Faraday.new(url: BASE_URL) do |conn|
+            conn.request :retry
+            conn.headers["Accept"] = "application/json"
+            conn.response :raise_error
+            conn.headers["User-Agent"] = ActiveProject.user_agent
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_project/adapters/trello/issues.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Trello
+      module Issues
+        DEFAULT_FIELDS = %w[id name desc closed idList idBoard due dueComplete idMembers].freeze
+
+        # Lists Trello cards on a specific board.
+        # @param board_id [String] The ID of the Trello board.
+        # @param options [Hash] Optional filtering options. Accepts :filter and :fields.
+        # @return [Array<ActiveProject::Resources::Issue>]
+        def list_issues(board_id, options = {})
+          path = "boards/#{board_id}/cards"
+
+          fields = options[:fields] ? Array(options[:fields]).join(",") : DEFAULT_FIELDS.join(",")
+          query = { fields: fields, list: true }
+          query[:filter] = options[:filter] if options[:filter]
+
+          cards_data = make_request(:get, path, nil, query)
+          return [] unless cards_data.is_a?(Array)
+
+          cards_data.map { |card_data| map_card_data(card_data, board_id) }
+        end
+
+        # Finds a specific Card by its ID.
+        # @param card_id [String] The ID of the Trello Card.
+        # @param context [Hash] Optional context. Accepts :fields for specific field selection.
+        # @return [ActiveProject::Resources::Issue]
+        def find_issue(card_id, context = {})
+          path = "cards/#{card_id}"
+
+          fields = context[:fields] ? Array(context[:fields]).join(",") : DEFAULT_FIELDS.join(",")
+          query = { fields: fields, list: true }
+
+          card_data = make_request(:get, path, nil, query)
+          map_card_data(card_data, card_data["idBoard"])
+        end
+
+        # Creates a new Card in Trello.
+        # @param _board_id [String] Ignored (context).
+        # @param attributes [Hash] Card attributes. Required: :list_id, :title. Optional: :description, :assignee_ids, :due_on.
+        # @return [ActiveProject::Resources::Issue]
+        def create_issue(_board_id, attributes)
+          list_id = attributes[:list_id]
+          title = attributes[:title]
+
+          unless list_id && title && !title.empty?
+            raise ArgumentError, "Missing required attributes for Trello card creation: :list_id, :title"
+          end
+
+          path = "cards"
+          query_params = {
+            idList: list_id,
+            name: title,
+            desc: attributes[:description],
+            idMembers: attributes[:assignee_ids]&.join(","),
+            due: attributes[:due_on]&.iso8601
+          }.compact
+
+          card_data = make_request(:post, path, nil, query_params)
+          map_card_data(card_data, card_data["idBoard"])
+        end
+
+        # Updates an existing Card in Trello.
+        # @param card_id [String] The ID of the Trello Card.
+        # @param attributes [Hash] Attributes to update (e.g., :title, :description, :list_id, :closed, :due_on, :assignee_ids, :status).
+        # @param context [Hash] Optional context. Accepts :fields for return data field selection.
+        # @return [ActiveProject::Resources::Issue]
+        def update_issue(card_id, attributes, context = {})
+          update_attributes = attributes.dup
+
+          if update_attributes.key?(:status)
+            target_status = update_attributes.delete(:status)
+
+            board_id = update_attributes[:board_id] || begin
+                                                         find_issue(card_id).project_id
+                                                       rescue NotFoundError
+                                                         raise NotFoundError, "Trello card with ID '#{card_id}' not found."
+                                                       end
+
+            unless board_id
+              raise ApiError, "Could not determine board ID for card '#{card_id}' to perform status mapping."
+            end
+
+            board_mappings = @config.status_mappings[board_id]
+            unless board_mappings
+              raise ConfigurationError,
+                    "Trello status mapping not configured for board ID '#{board_id}'. Cannot map status ':#{target_status}'."
+            end
+
+            target_list_id = board_mappings.key(target_status)
+
+            unless target_list_id
+              raise ConfigurationError,
+                    "Target status ':#{target_status}' not found in configured Trello status mappings for board ID '#{board_id}'."
+            end
+
+            update_attributes[:list_id] = target_list_id
+          end
+
+          path = "cards/#{card_id}"
+
+          query_params = {}
+          query_params[:name] = update_attributes[:title] if update_attributes.key?(:title)
+          query_params[:desc] = update_attributes[:description] if update_attributes.key?(:description)
+          query_params[:closed] = update_attributes[:closed] if update_attributes.key?(:closed)
+          query_params[:idList] = update_attributes[:list_id] if update_attributes.key?(:list_id)
+          query_params[:due] = update_attributes[:due_on]&.iso8601 if update_attributes.key?(:due_on)
+          query_params[:dueComplete] = update_attributes[:dueComplete] if update_attributes.key?(:dueComplete)
+          if update_attributes.key?(:assignee_ids)
+            query_params[:idMembers] =
+              update_attributes[:assignee_ids]&.join(",")
+          end
+
+          return find_issue(card_id, context) if query_params.empty?
+
+          card_data = make_request(:put, path, nil, query_params.compact)
+          map_card_data(card_data, card_data["idBoard"])
+        end
+
+        # Deletes a Trello card.
+        # @param card_id [String] The ID of the Trello Card to delete.
+        # @return [Boolean] True if successfully deleted.
+        def delete_issue(card_id, **)
+          path = "cards/#{card_id}"
+          make_request(:delete, path)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/active_project/adapters/trello/lists.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Trello
+      module Lists
+        # Creates a new list on a Trello board.
+        # @param board_id [String] The ID of the board.
+        # @param attributes [Hash] List attributes. Required: :name. Optional: :pos.
+        # @return [Hash] The raw data hash of the created list.
+        def create_list(board_id, attributes)
+          unless attributes[:name] && !attributes[:name].empty?
+            raise ArgumentError, "Missing required attribute for Trello list creation: :name"
+          end
+
+          path = "boards/#{board_id}/lists"
+          query_params = {
+            name: attributes[:name],
+            pos: attributes[:pos]
+          }.compact
+
+          make_request(:post, path, nil, query_params)
+        end
+      end
+    end
+  end
+end

data/lib/active_project/adapters/trello/projects.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Trello
+      module Projects
+        # Lists Trello boards accessible by the configured token.
+        # @return [Array<ActiveProject::Resources::Project>] An array of project resources.
+        def list_projects
+          path = "members/me/boards"
+          query = { fields: "id,name,desc" }
+          boards_data = make_request(:get, path, nil, query)
+
+          return [] unless boards_data.is_a?(Array)
+
+          boards_data.map do |board_data|
+            Resources::Project.new(self,
+                                   id: board_data["id"],
+                                   key: nil,
+                                   name: board_data["name"],
+                                   adapter_source: :trello,
+                                   raw_data: board_data)
+          end
+        end
+
+        # Finds a specific Trello Board by its ID.
+        # @param board_id [String] The ID of the Trello Board.
+        # @return [ActiveProject::Resources::Project]
+        def find_project(board_id)
+          path = "boards/#{board_id}"
+          query = { fields: "id,name,desc" }
+          board_data = make_request(:get, path, nil, query)
+
+          Resources::Project.new(self,
+                                 id: board_data["id"],
+                                 key: nil,
+                                 name: board_data["name"],
+                                 adapter_source: :trello,
+                                 raw_data: board_data)
+        end
+
+        # Creates a new board in Trello.
+        # @param attributes [Hash] Board attributes. Required: :name. Optional: :description, :default_lists.
+        # @return [ActiveProject::Resources::Project]
+        def create_project(attributes)
+          unless attributes[:name] && !attributes[:name].empty?
+            raise ArgumentError, "Missing required attribute for Trello board creation: :name"
+          end
+
+          path = "boards/"
+          query_params = {
+            name: attributes[:name],
+            desc: attributes[:description],
+            defaultLists: attributes.fetch(:default_lists, true)
+          }.compact
+
+          board_data = make_request(:post, path, nil, query_params)
+
+          Resources::Project.new(self,
+                                 id: board_data["id"],
+                                 key: nil,
+                                 name: board_data["name"],
+                                 adapter_source: :trello,
+                                 raw_data: board_data)
+        end
+
+        # Deletes a board in Trello.
+        # WARNING: This is a permanent deletion.
+        # @param board_id [String] The ID of the board to delete.
+        # @return [Boolean] true if deletion was successful (API returns 200).
+        # @raise [NotFoundError] if the board is not found.
+        # @raise [AuthenticationError] if credentials lack permission.
+        # @raise [ApiError] for other errors.
+        def delete_project(board_id)
+          path = "/boards/#{board_id}"
+          make_request(:delete, path)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/active_project/adapters/trello/webhooks.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Trello
+      module Webhooks
+        # Parses an incoming Trello webhook payload.
+        # @param request_body [String] The raw JSON request body.
+        # @param headers [Hash] Request headers (unused).
+        # @return [ActiveProject::WebhookEvent, nil] Parsed event or nil if unhandled.
+        def parse_webhook(request_body, _headers = {})
+          payload = begin
+            JSON.parse(request_body)
+          rescue StandardError
+            nil
+          end
+          return nil unless payload.is_a?(Hash) && payload["action"].is_a?(Hash)
+
+          action = payload["action"]
+          action_type = action["type"]
+          actor_data = action["memberCreator"]
+          timestamp = begin
+            Time.parse(action["date"])
+          rescue StandardError
+            nil
+          end
+          board_id = action.dig("data", "board", "id")
+          card_data = action.dig("data", "card")
+          action.dig("data", "text")
+          old_data = action.dig("data", "old")
+
+          event_type = nil
+          object_kind = nil
+          event_object_id = nil
+          object_key = nil
+          changes = nil
+          object_data = nil
+
+          case action_type
+          when "createCard"
+            event_type = :issue_created
+            object_kind = :issue
+            event_object_id = card_data["id"]
+            object_key = card_data["idShort"]
+          when "updateCard"
+            event_type = :issue_updated
+            object_kind = :issue
+            event_object_id = card_data["id"]
+            object_key = card_data["idShort"]
+            if old_data.is_a?(Hash)
+              changes = {}
+              old_data.each do |field, old_value|
+                new_value = card_data[field]
+                changes[field.to_sym] = [ old_value, new_value ]
+              end
+            end
+          when "commentCard"
+            event_type = :comment_added
+            object_kind = :comment
+            event_object_id = action["id"]
+            object_key = nil
+          when "addMemberToCard", "removeMemberFromCard"
+            event_type = :issue_updated
+            object_kind = :issue
+            event_object_id = card_data["id"]
+            object_key = card_data["idShort"]
+            changes = { assignees: true }
+          else
+            return nil
+          end
+
+          WebhookEvent.new(
+            event_type: event_type,
+            object_kind: object_kind,
+            event_object_id: event_object_id,
+            object_key: object_key,
+            project_id: board_id,
+            actor: map_user_data(actor_data),
+            timestamp: timestamp,
+            adapter_source: :trello,
+            changes: changes,
+            object_data: object_data,
+            raw_data: payload
+          )
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end