activeproject 0.0.0 → 0.1.1

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Jira
+      module Connection
+        # Initializes the Jira Adapter.
+        # @param config [Configurations::BaseAdapterConfiguration] The configuration object for Jira.
+        # @raise [ArgumentError] if required configuration options (:site_url, :username, :api_token) are missing.
+        def initialize(config:)
+          unless config.is_a?(ActiveProject::Configurations::BaseAdapterConfiguration)
+            raise ArgumentError, "JiraAdapter requires a BaseAdapterConfiguration object"
+          end
+
+          @config = config
+
+          unless @config.options[:site_url] && !@config.options[:site_url].empty? &&
+                 @config.options[:username] && !@config.options[:username].empty? &&
+                 @config.options[:api_token] && !@config.options[:api_token].empty?
+            raise ArgumentError, "JiraAdapter configuration requires :site_url, :username, and :api_token"
+          end
+
+          @connection = initialize_connection
+        end
+
+        private
+
+        # Initializes the Faraday connection object.
+        def initialize_connection
+          site_url = @config.options[:site_url].chomp("/")
+          username = @config.options[:username]
+          api_token = @config.options[:api_token]
+
+          Faraday.new(url: site_url) do |conn|
+            conn.request :authorization, :basic, username, api_token
+            conn.request :retry
+            # Important: Keep raise_error middleware *after* retry
+            # conn.response :raise_error # Defer raising error to handle_faraday_error
+            conn.headers["Content-Type"] = "application/json"
+            conn.headers["Accept"] = "application/json"
+            conn.headers["User-Agent"] = ActiveProject.user_agent
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Jira
+      module Issues
+        # Lists issues within a specific project, optionally filtered by JQL.
+        # @param project_id_or_key [String, Integer] The ID or key of the project.
+        # @param options [Hash] Optional filtering/pagination options.
+        # @return [Array<ActiveProject::Resources::Issue>]
+        def list_issues(project_id_or_key, options = {})
+          start_at = options.fetch(:start_at, 0)
+          max_results = options.fetch(:max_results, 50)
+          jql = options.fetch(:jql, "project = '#{project_id_or_key}' ORDER BY created DESC")
+
+          all_issues = []
+          path = "/rest/api/3/search"
+
+          payload = {
+            jql: jql,
+            startAt: start_at,
+            maxResults: max_results,
+            fields: %w[summary description status assignee reporter created updated project
+                       issuetype duedate priority]
+          }.to_json
+
+          response_data = make_request(:post, path, payload)
+
+          issues_data = response_data["issues"] || []
+          issues_data.each do |issue_data|
+            all_issues << map_issue_data(issue_data)
+          end
+
+          all_issues
+        end
+
+        # Finds a specific issue by its ID or key using the V3 endpoint.
+        # @param id_or_key [String, Integer] The ID or key of the issue.
+        # @param context [Hash] Optional context (ignored).
+        # @return [ActiveProject::Resources::Issue]
+        def find_issue(id_or_key, _context = {})
+          fields = "summary,description,status,assignee,reporter,created,updated,project,issuetype,duedate,priority"
+          path = "/rest/api/3/issue/#{id_or_key}?fields=#{fields}"
+
+          issue_data = make_request(:get, path)
+          map_issue_data(issue_data)
+        end
+
+        # Creates a new issue in Jira using the V3 endpoint.
+        # @param _project_id_or_key [String, Integer] Ignored (project info is in attributes).
+        # @param attributes [Hash] Issue attributes. Required: :project, :summary, :issue_type. Optional: :description, :assignee_id, :due_on, :priority.
+        # @return [ActiveProject::Resources::Issue]
+        def create_issue(_project_id_or_key, attributes)
+          path = "/rest/api/3/issue"
+
+          unless attributes[:project].is_a?(Hash) && (attributes[:project][:id] || attributes[:project][:key]) &&
+                 attributes[:summary] && !attributes[:summary].empty? &&
+                 attributes[:issue_type] && (attributes[:issue_type][:id] || attributes[:issue_type][:name])
+            raise ArgumentError,
+                  "Missing required attributes for issue creation: :project (must be a Hash with id/key), :summary, :issue_type (with id/name)"
+          end
+
+          fields_payload = {
+            project: attributes[:project],
+            summary: attributes[:summary],
+            issuetype: attributes[:issue_type]
+          }
+
+          if attributes.key?(:description)
+            fields_payload[:description] = if attributes[:description].is_a?(String)
+                                             { type: "doc", version: 1, content: [ { type: "paragraph", content: [ { type: "text", text: attributes[:description] } ] } ] }
+            elsif attributes[:description].is_a?(Hash)
+                                             attributes[:description]
+            end
+          end
+
+          fields_payload[:assignee] = { accountId: attributes[:assignee_id] } if attributes.key?(:assignee_id)
+
+          if attributes.key?(:due_on)
+            fields_payload[:duedate] =
+              attributes[:due_on].respond_to?(:strftime) ? attributes[:due_on].strftime("%Y-%m-%d") : attributes[:due_on]
+          end
+
+          fields_payload[:priority] = attributes[:priority] if attributes.key?(:priority)
+
+          payload = { fields: fields_payload }.to_json
+          response_data = make_request(:post, path, payload)
+
+          find_issue(response_data["key"])
+        end
+
+        # Updates an existing issue in Jira using the V3 endpoint.
+        # @param id_or_key [String, Integer] The ID or key of the issue to update.
+        # @param attributes [Hash] Issue attributes to update (e.g., :summary, :description, :assignee_id, :due_on, :priority).
+        # @param context [Hash] Optional context (ignored).
+        # @return [ActiveProject::Resources::Issue]
+        def update_issue(id_or_key, attributes, _context = {})
+          path = "/rest/api/3/issue/#{id_or_key}"
+
+          update_fields = {}
+          update_fields[:summary] = attributes[:summary] if attributes.key?(:summary)
+
+          if attributes.key?(:description)
+            update_fields[:description] = if attributes[:description].is_a?(String)
+                                            { type: "doc", version: 1, content: [ { type: "paragraph", content: [ { type: "text", text: attributes[:description] } ] } ] }
+            elsif attributes[:description].is_a?(Hash)
+                                            attributes[:description]
+            end
+          end
+
+          if attributes.key?(:assignee_id)
+            update_fields[:assignee] = attributes[:assignee_id] ? { accountId: attributes[:assignee_id] } : nil
+          end
+
+          if attributes.key?(:due_on)
+            update_fields[:duedate] =
+              attributes[:due_on].respond_to?(:strftime) ? attributes[:due_on].strftime("%Y-%m-%d") : attributes[:due_on]
+          end
+
+          update_fields[:priority] = attributes[:priority] if attributes.key?(:priority)
+
+          return find_issue(id_or_key) if update_fields.empty?
+
+          payload = { fields: update_fields }.to_json
+          make_request(:put, path, payload)
+
+          find_issue(id_or_key)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Jira
+      module Projects
+        # Lists projects accessible by the configured credentials using the V3 endpoint.
+        # Handles pagination automatically.
+        # @return [Array<ActiveProject::Resources::Project>] An array of project resources.
+        def list_projects
+          start_at = 0
+          max_results = 50
+          all_projects = []
+
+          loop do
+            path = "/rest/api/3/project/search?startAt=#{start_at}&maxResults=#{max_results}"
+            response_data = make_request(:get, path)
+
+            projects_data = response_data["values"] || []
+            break if projects_data.empty?
+
+            projects_data.each do |project_data|
+              all_projects << Resources::Project.new(self,
+                                                     id: project_data["id"],
+                                                     key: project_data["key"],
+                                                     name: project_data["name"],
+                                                     adapter_source: :jira,
+                                                     raw_data: project_data)
+            end
+
+            is_last = response_data["isLast"]
+            break if is_last || projects_data.size < max_results
+
+            start_at += projects_data.size
+          end
+
+          all_projects
+        end
+
+        # Finds a specific project by its ID or key.
+        # @param id_or_key [String, Integer] The ID or key of the project.
+        # @return [ActiveProject::Resources::Project]
+        def find_project(id_or_key)
+          path = "/rest/api/3/project/#{id_or_key}"
+          project_data = make_request(:get, path)
+
+          Resources::Project.new(self,
+                                 id: project_data["id"].to_i,
+                                 key: project_data["key"],
+                                 name: project_data["name"],
+                                 adapter_source: :jira,
+                                 raw_data: project_data)
+        end
+
+        # Creates a new project in Jira.
+        # @param attributes [Hash] Project attributes. Required: :key, :name, :project_type_key, :lead_account_id. Optional: :description, :assignee_type.
+        # @return [ActiveProject::Resources::Project]
+        def create_project(attributes)
+          required_keys = %i[key name project_type_key lead_account_id]
+          missing_keys = required_keys.reject { |k| attributes.key?(k) && !attributes[k].to_s.empty? }
+          unless missing_keys.empty?
+            raise ArgumentError, "Missing required attributes for Jira project creation: #{missing_keys.join(', ')}"
+          end
+
+          path = "/rest/api/3/project"
+          payload = {
+            key: attributes[:key],
+            name: attributes[:name],
+            projectTypeKey: attributes[:project_type_key],
+            leadAccountId: attributes[:lead_account_id],
+            description: attributes[:description],
+            assigneeType: attributes[:assignee_type]
+          }.compact
+
+          project_data = make_request(:post, path, payload.to_json)
+
+          Resources::Project.new(self,
+                                 id: project_data["id"]&.to_i,
+                                 key: project_data["key"],
+                                 name: project_data["name"],
+                                 adapter_source: :jira,
+                                 raw_data: project_data)
+        end
+
+        # Deletes a project in Jira.
+        # WARNING: This is a permanent deletion and requires admin permissions.
+        # @param project_id_or_key [String, Integer] The ID or key of the project to delete.
+        # @return [Boolean] true if deletion was successful (API returns 204).
+        # @raise [NotFoundError] if the project is not found.
+        # @raise [AuthenticationError] if credentials lack permission.
+        # @raise [ApiError] for other errors.
+        def delete_project(project_id_or_key)
+          path = "/rest/api/3/project/#{project_id_or_key}"
+          make_request(:delete, path)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/active_project/adapters/jira/transitions.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Jira
+      module Transitions
+        # Transitions a Jira issue to a new status by finding and executing the appropriate workflow transition.
+        # @param issue_id_or_key [String, Integer] The ID or key of the issue.
+        # @param target_status_name_or_id [String, Integer] The name or ID of the target status.
+        # @param options [Hash] Optional parameters for the transition (e.g., :resolution, :comment).
+        #   - :resolution [Hash] e.g., `{ name: 'Done' }`
+        #   - :comment [String] Comment body to add during transition.
+        # @return [Boolean] true if successful.
+        # @raise [NotFoundError] if the issue or target transition is not found.
+        # @raise [ApiError] for other API errors.
+        def transition_issue(issue_id_or_key, target_status_name_or_id, options = {})
+          transitions_path = "/rest/api/3/issue/#{issue_id_or_key}/transitions"
+          begin
+            response_data = make_request(:get, transitions_path)
+          rescue NotFoundError
+            raise NotFoundError, "Jira issue '#{issue_id_or_key}' not found."
+          end
+          available_transitions = response_data["transitions"] || []
+
+          target_transition = available_transitions.find do |t|
+            t["id"] == target_status_name_or_id.to_s ||
+              t.dig("to", "name")&.casecmp?(target_status_name_or_id.to_s) ||
+              t.dig("to", "id") == target_status_name_or_id.to_s
+          end
+
+          unless target_transition
+            available_names = available_transitions.map { |t| t.dig("to", "name") }.compact.join(", ")
+            raise NotFoundError,
+                  "Target transition '#{target_status_name_or_id}' not found or not available for issue '#{issue_id_or_key}'. Available transitions: [#{available_names}]"
+          end
+
+          payload = {
+            transition: { id: target_transition["id"] }
+          }
+
+          if options[:resolution]
+            payload[:fields] ||= {}
+            payload[:fields][:resolution] = options[:resolution]
+          end
+
+          if options[:comment] && !options[:comment].empty?
+            payload[:update] ||= {}
+            payload[:update][:comment] ||= []
+            payload[:update][:comment] << {
+              add: {
+                body: {
+                  type: "doc", version: 1,
+                  content: [ { type: "paragraph", content: [ { type: "text", text: options[:comment] } ] } ]
+                }
+              }
+            }
+          end
+
+          make_request(:post, transitions_path, payload.to_json)
+          true
+        rescue Faraday::Error => e
+          handle_faraday_error(e)
+          raise ApiError.new("Failed to transition Jira issue '#{issue_id_or_key}'", original_error: e)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Jira
+      module Webhooks
+        # Parses an incoming Jira webhook payload.
+        # @param request_body [String] The raw JSON request body.
+        # @param headers [Hash] Request headers.
+        # @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)
+
+          event_name = payload["webhookEvent"]
+          timestamp = payload["timestamp"] ? Time.at(payload["timestamp"] / 1000) : nil
+
+          actor_data = if event_name.start_with?("comment_")
+                         payload.dig("comment", "author")
+          else
+                         payload["user"]
+          end
+
+          issue_data = payload["issue"]
+          comment_data = payload["comment"]
+          changelog = payload["changelog"]
+
+          event_type = nil
+          object_kind = nil
+          event_object_id = nil
+          object_key = nil
+          project_id = nil
+          changes = nil
+          object_data = nil
+
+          case event_name
+          when "jira:issue_created"
+            event_type = :issue_created
+            object_kind = :issue
+            event_object_id = issue_data["id"]
+            object_key = issue_data["key"]
+            project_id = issue_data.dig("fields", "project", "id")&.to_i
+          when "jira:issue_updated"
+            event_type = :issue_updated
+            object_kind = :issue
+            event_object_id = issue_data["id"]
+            object_key = issue_data["key"]
+            project_id = issue_data.dig("fields", "project", "id")&.to_i
+            changes = parse_changelog(changelog)
+          when "comment_created"
+            event_type = :comment_added
+            object_kind = :comment
+            event_object_id = comment_data["id"]
+            object_key = nil
+            project_id = issue_data.dig("fields", "project", "id")&.to_i
+          when "comment_updated"
+            event_type = :comment_updated
+            object_kind = :comment
+            event_object_id = comment_data["id"]
+            object_key = nil
+            project_id = issue_data.dig("fields", "project", "id")&.to_i
+          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: project_id,
+            actor: map_user_data(actor_data),
+            timestamp: timestamp,
+            adapter_source: :jira,
+            changes: changes,
+            object_data: object_data,
+            raw_data: payload
+          )
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end