activeproject 0.2.0 → 0.5.0

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

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module GithubRepo
+      module Webhooks
+        # Validates incoming webhook signature using X-Hub-Signature-256 header
+        # @param request_body [String] The raw request body
+        # @param signature_header [String] The value of the X-Hub-Signature-256 header
+        # @return [Boolean] True if signature is valid or verification is not needed
+        def verify_webhook_signature(request_body, signature_header)
+          webhook_secret = @config.options[:webhook_secret]
+
+          # No webhook secret configured = no verification needed
+          return true if webhook_secret.nil? || webhook_secret.empty?
+
+          # Signature header is required when a secret is configured
+          return false unless signature_header
+
+          # GitHub uses 'sha256=' prefix for their signatures
+          algorithm, signature = signature_header.split("=", 2)
+          return false unless algorithm == "sha256" && signature
+
+          # Calculate expected signature
+          expected_signature = OpenSSL::HMAC.hexdigest(
+            OpenSSL::Digest.new("sha256"),
+            webhook_secret,
+            request_body
+          )
+
+          # Perform a secure comparison
+          secure_compare(signature, expected_signature)
+        end
+
+        # Constant-time comparison to prevent timing attacks
+        # @param a [String] First string to compare
+        # @param b [String] Second string to compare
+        # @return [Boolean] True if strings are equal
+        def secure_compare(a, b)
+          return false if a.bytesize != b.bytesize
+          l = a.unpack("C*")
+
+          res = 0
+          b.each_byte { |byte| res |= byte ^ l.shift }
+          res == 0
+        end
+
+        # Parses an incoming webhook payload into a standardized WebhookEvent struct
+        # @param request_body [String] The raw request body
+        # @param headers [Hash] Hash of request headers
+        # @return [ActiveProject::WebhookEvent, nil] The parsed event or nil if not relevant
+        def parse_webhook(request_body, headers = {})
+          data = JSON.parse(request_body)
+          event_type = headers["X-GitHub-Event"]
+
+          case event_type
+          when "issues"
+            parse_issue_event(data)
+          when "issue_comment"
+            parse_comment_event(data)
+          when "pull_request"
+            parse_pull_request_event(data)
+          else
+            nil # Unsupported event type
+          end
+        rescue JSON::ParserError
+          nil # Return nil for invalid JSON
+        end
+
+        private
+
+        # Parses an issue event into a WebhookEvent
+        # @param data [Hash] Parsed webhook payload
+        # @return [WebhookEvent, nil] The standardized event
+        def parse_issue_event(data)
+          return nil unless data["issue"]
+
+          action = data["action"]
+          issue_data = data["issue"]
+          repository = data["repository"]
+
+          # Map GitHub action to our event type
+          event_type = case action
+          when "opened" then :issue_created
+          when "edited" then :issue_updated
+          when "closed" then :issue_closed
+          when "reopened" then :issue_reopened
+          when "assigned", "unassigned" then :issue_assigned
+          when "labeled", "unlabeled" then :issue_labeled
+          else :issue_updated # Default for other actions
+          end
+
+          # Map the issue data
+          issue = map_webhook_issue(issue_data)
+
+          # Get project (repository) info
+          project_id = repository ? repository["full_name"] : nil
+
+          WebhookEvent.new(
+            source: webhook_type,
+            type: event_type,
+            resource_type: :issue,
+            resource_id: issue_data["number"].to_s,
+            project_id: project_id,
+            data: {
+              issue: issue,
+              action: action
+            }
+          )
+        end
+
+        # Parses a comment event into a WebhookEvent
+        # @param data [Hash] Parsed webhook payload
+        # @return [WebhookEvent, nil] The standardized event
+        def parse_comment_event(data)
+          return nil unless data["comment"] && data["issue"]
+
+          action = data["action"]
+          comment_data = data["comment"]
+          issue_data = data["issue"]
+          repository = data["repository"]
+
+          # Only handle supported actions
+          return nil unless [ "created", "edited", "deleted" ].include?(action)
+
+          # Map GitHub action to our event type
+          event_type = case action
+          when "created" then :comment_created
+          when "edited" then :comment_updated
+          when "deleted" then :comment_deleted
+          else nil
+          end
+
+          return nil unless event_type
+
+          # Get project (repository) info
+          project_id = repository ? repository["full_name"] : nil
+
+          # Create a webhook event with comment and issue data
+          WebhookEvent.new(
+            source: webhook_type,
+            type: event_type,
+            resource_type: :comment,
+            resource_id: comment_data["id"].to_s,
+            project_id: project_id,
+            data: {
+              # Map the comment data to a Comment resource
+              comment: map_webhook_comment(comment_data, issue_data["number"].to_s),
+              # Map the issue data to an Issue resource
+              issue: map_webhook_issue(issue_data),
+              action: action
+            }
+          )
+        end
+
+        # Parses a pull request event into a WebhookEvent
+        # GitHub PRs are mapped to issues for compatibility
+        # @param data [Hash] Parsed webhook payload
+        # @return [WebhookEvent, nil] The standardized event
+        def parse_pull_request_event(data)
+          return nil unless data["pull_request"]
+
+          action = data["action"]
+          pull_request_data = data["pull_request"]
+          repository = data["repository"]
+
+          # Map GitHub action to our event type (treating PRs as a type of issue)
+          event_type = case action
+          when "opened" then :issue_created
+          when "edited" then :issue_updated
+          when "closed"
+                         pull_request_data["merged"] ? :issue_merged : :issue_closed
+          when "reopened" then :issue_reopened
+          else :issue_updated # Default for other actions
+          end
+
+          # Get project (repository) info
+          project_id = repository ? repository["full_name"] : nil
+
+          # Create a synthetic issue from the PR
+          # We map PRs to issues for the ActiveProject model
+          pr_issue = map_webhook_pull_request_to_issue(pull_request_data)
+
+          WebhookEvent.new(
+            source: webhook_type,
+            type: event_type,
+            resource_type: :issue, # Map PRs to issues for consistency
+            resource_id: pull_request_data["number"].to_s,
+            project_id: project_id,
+            data: {
+              issue: pr_issue,
+              action: action,
+              is_pull_request: true
+            }
+          )
+        end
+
+        # Map webhook issue data to an Issue resource
+        # @param issue_data [Hash] Issue data from GitHub webhook
+        # @return [ActiveProject::Resources::Issue] Mapped issue resource
+        def map_webhook_issue(issue_data)
+          return nil unless issue_data
+
+          # Map state to status
+          state = issue_data["state"]
+          status = @config.status_mappings[state] || (state == "open" ? :open : :closed)
+
+          # Map assignees
+          assignees = []
+          if issue_data["assignees"] && !issue_data["assignees"].empty?
+            assignees = issue_data["assignees"].map do |assignee|
+              Resources::User.new(
+                self,
+                id: assignee["id"].to_s,
+                name: assignee["login"],
+                adapter_source: :github,
+                raw_data: assignee
+              )
+            end
+          end
+
+          # Map reporter (creator)
+          reporter = nil
+          if issue_data["user"]
+            reporter = Resources::User.new(
+              self,
+              id: issue_data["user"]["id"].to_s,
+              name: issue_data["user"]["login"],
+              adapter_source: :github,
+              raw_data: issue_data["user"]
+            )
+          end
+
+          # Determine project ID (repository name)
+          project_id = issue_data["repository_url"]
+          if project_id
+            parts = project_id.split("/")
+            project_id = "#{parts[-2]}/#{parts[-1]}" if parts.size >= 2
+          else
+            project_id = "#{@config.options[:owner]}/#{@config.options[:repo]}"
+          end
+
+          Resources::Issue.new(
+            self,
+            id: issue_data["id"].to_s,
+            key: issue_data["number"].to_s,
+            title: issue_data["title"],
+            description: issue_data["body"],
+            status: status,
+            assignees: assignees,
+            reporter: reporter,
+            project_id: project_id,
+            created_at: issue_data["created_at"] ? Time.parse(issue_data["created_at"]) : nil,
+            updated_at: issue_data["updated_at"] ? Time.parse(issue_data["updated_at"]) : nil,
+            due_on: nil, # GitHub issues don't have due dates
+            priority: nil, # GitHub issues don't have priorities
+            adapter_source: :github,
+            raw_data: issue_data
+          )
+        end
+
+        # Map webhook comment data to a Comment resource
+        # @param comment_data [Hash] Comment data from GitHub webhook
+        # @param issue_id [String] The issue ID/number this comment belongs to
+        # @return [ActiveProject::Resources::Comment] Mapped comment resource
+        def map_webhook_comment(comment_data, issue_id)
+          return nil unless comment_data
+
+          # Map author
+          author = nil
+          if comment_data["user"]
+            author = Resources::User.new(
+              self,
+              id: comment_data["user"]["id"].to_s,
+              name: comment_data["user"]["login"],
+              adapter_source: :github,
+              raw_data: comment_data["user"]
+            )
+          end
+
+          Resources::Comment.new(
+            self,
+            id: comment_data["id"].to_s,
+            body: comment_data["body"],
+            author: author,
+            created_at: comment_data["created_at"] ? Time.parse(comment_data["created_at"]) : nil,
+            updated_at: comment_data["updated_at"] ? Time.parse(comment_data["updated_at"]) : nil,
+            issue_id: issue_id,
+            adapter_source: :github,
+            raw_data: comment_data
+          )
+        end
+
+        # Maps a pull request to an issue for compatibility
+        # @param pull_request_data [Hash] Pull request data from webhook
+        # @return [ActiveProject::Resources::Issue] Issue representation of the PR
+        def map_webhook_pull_request_to_issue(pull_request_data)
+          return nil unless pull_request_data
+
+          # Get state from PR data
+          state = pull_request_data["state"]
+          status = @config.status_mappings[state] || (state == "open" ? :open : :closed)
+
+          # Extract assignees if present
+          assignees = []
+          if pull_request_data["assignees"]
+            assignees = pull_request_data["assignees"].map do |assignee|
+              Resources::User.new(
+                self,
+                id: assignee["id"].to_s,
+                name: assignee["login"],
+                adapter_source: :github,
+                raw_data: assignee
+              )
+            end
+          end
+
+          # Extract reporter (user who created the PR)
+          reporter = nil
+          if pull_request_data["user"]
+            reporter = Resources::User.new(
+              self,
+              id: pull_request_data["user"]["id"].to_s,
+              name: pull_request_data["user"]["login"],
+              adapter_source: :github,
+              raw_data: pull_request_data["user"]
+            )
+          end
+
+          # Determine project ID
+          project_id = pull_request_data.dig("base", "repo", "full_name") ||
+                      "#{@config.options[:owner]}/#{@config.options[:repo]}"
+
+          # Create an issue resource from the PR data
+          Resources::Issue.new(
+            self,
+            id: pull_request_data["id"].to_s,
+            key: pull_request_data["number"].to_s,
+            title: pull_request_data["title"],
+            description: pull_request_data["body"],
+            status: status,
+            assignees: assignees,
+            reporter: reporter,
+            project_id: project_id,
+            created_at: pull_request_data["created_at"] ? Time.parse(pull_request_data["created_at"]) : nil,
+            updated_at: pull_request_data["updated_at"] ? Time.parse(pull_request_data["updated_at"]) : nil,
+            adapter_source: :github,
+            raw_data: pull_request_data
+          )
+        end
+      end
+    end
+  end
+end

data/lib/active_project/adapters/github_repo_adapter.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "time"
+
+module ActiveProject
+  module Adapters
+    # Adapter for interacting with the GitHub REST API.
+    # Implements the interface defined in ActiveProject::Adapters::Base.
+    # API Docs: https://docs.github.com/en/rest
+    class GithubRepoAdapter < Base
+      attr_reader :config
+
+      include GithubRepo::Connection
+      include GithubRepo::Projects
+      include GithubRepo::Issues
+      include GithubRepo::Webhooks
+
+      # Retrieves details for the currently authenticated user.
+      # @return [ActiveProject::Resources::User] The user object.
+      # @raise [ActiveProject::AuthenticationError] if authentication fails.
+      # @raise [ActiveProject::ApiError] for other API-related errors.
+      def get_current_user
+        user_data = make_request(:get, "user")
+        map_user_data(user_data)
+      end
+
+      # Checks if the adapter can successfully authenticate and connect to the service.
+      # Calls #get_current_user internally and catches authentication errors.
+      # @return [Boolean] true if connection is successful, false otherwise.
+      def connected?
+        get_current_user
+        true
+      rescue ActiveProject::AuthenticationError
+        false
+      end
+
+      # Returns a factory for Project resources.
+      # In GitHub's context, this is for interacting with repositories.
+      # @return [ResourceFactory<Resources::Project>]
+      def projects
+        ResourceFactory.new(adapter: self, resource_class: Resources::Project)
+      end
+
+      # Returns a factory for Issue resources.
+      # @return [ResourceFactory<Resources::Issue>]
+      def issues
+        ResourceFactory.new(adapter: self, resource_class: Resources::Issue)
+      end
+
+      protected
+
+      private
+
+      # Helper method for making requests to the GitHub API.
+      # @param method [Symbol] HTTP method (:get, :post, :patch, :delete, etc.)
+      # @param path [String] API endpoint path
+      # @param body [Hash, nil] Request body (for POST/PATCH requests)
+      # @param query [Hash, nil] Query parameters
+      # @return [Hash, Array, nil] Parsed JSON response or nil if response is empty
+      # @raise [ActiveProject::ApiError] for various API errors
+      def make_request(method, path, body = nil, query = nil)
+        json_body = body ? JSON.generate(body) : nil
+
+        response = @connection.run_request(method, path, json_body, nil) do |req|
+          req.params = query if query
+        end
+
+        return nil if response.status == 204 || response.body.empty?
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        handle_faraday_error(e)
+      rescue JSON::ParserError => e
+        raise ApiError.new("GitHub API returned non-JSON response: #{response&.body}", original_error: e)
+      end
+
+      # Handles Faraday errors and converts them to appropriate ActiveProject error types.
+      # @param error [Faraday::Error] The Faraday error to handle
+      # @raise [ActiveProject::AuthenticationError] for 401/403 errors
+      # @raise [ActiveProject::NotFoundError] for 404 errors
+      # @raise [ActiveProject::ValidationError] for 422 errors
+      # @raise [ActiveProject::RateLimitError] for 429 errors
+      # @raise [ActiveProject::ApiError] for other errors
+      def handle_faraday_error(error)
+        status = error.response_status
+        body = error.response_body
+
+        begin
+          parsed_body = JSON.parse(body)
+          message = parsed_body["message"]
+        rescue
+          message = body || "Unknown GitHub Error"
+        end
+
+        case status
+        when 401, 403
+          raise AuthenticationError, "GitHub authentication failed (Status: #{status}): #{message}"
+        when 404
+          raise NotFoundError, "GitHub resource not found (Status: 404): #{message}"
+        when 422
+          raise ValidationError.new("GitHub validation failed (Status: 422): #{message}",
+                                   status_code: status,
+                                   response_body: body)
+        when 429
+          raise RateLimitError, "GitHub rate limit exceeded (Status: 429): #{message}"
+        else
+          raise ApiError.new("GitHub API error (Status: #{status || 'N/A'}): #{message}",
+                            original_error: error,
+                            status_code: status,
+                            response_body: body)
+        end
+      end
+
+      # Maps raw GitHub user data hash to a User resource.
+      # @param user_data [Hash, nil] Raw user data from GitHub API
+      # @return [Resources::User, nil] The mapped user object or nil if user_data is nil
+      def map_user_data(user_data)
+        return nil unless user_data && user_data["id"]
+
+        Resources::User.new(
+          self,
+          id: user_data["id"].to_s,
+          name: user_data["login"],
+          email: user_data["email"],
+          adapter_source: :github,
+          raw_data: user_data
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Jira
+      module AttributeNormalizer
+        # Normalise Issue attributes before they hit Jira’s REST API
+        def normalize_issue_attrs(attrs)
+          attrs = attrs.dup
+          attrs[:summary] = attrs.delete(:title) if attrs.key?(:title)
+          attrs
+        end
+      end
+    end
+  end
+end

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

@@ -22,6 +22,47 @@ module ActiveProject
           comment_data = make_request(:post, path, payload)
           map_comment_data(comment_data, issue_id_or_key)
         end
+
+        # Updates a comment on an issue in Jira using the V3 endpoint.
+        # @param comment_id [String, Integer] The ID of the comment.
+        # @param body [String] The new comment text.
+        # @param context [Hash] Required context: { issue_id: '...' }.
+        # @return [ActiveProject::Resources::Comment] The updated comment resource.
+        def update_comment(comment_id, body, context = {})
+          issue_id_or_key = context[:issue_id]
+          unless issue_id_or_key
+            raise ArgumentError,
+                  "Missing required context: :issue_id must be provided for JiraAdapter#update_comment"
+          end
+
+          path = "/rest/api/3/issue/#{issue_id_or_key}/comment/#{comment_id}"
+
+          payload = {
+            body: {
+              type: "doc", version: 1,
+              content: [ { type: "paragraph", content: [ { type: "text", text: body } ] } ]
+            }
+          }.to_json
+
+          comment_data = make_request(:put, path, payload)
+          map_comment_data(comment_data, issue_id_or_key)
+        end
+
+        # Deletes a comment from an issue in Jira.
+        # @param comment_id [String, Integer] The ID of the comment to delete.
+        # @param context [Hash] Required context: { issue_id: '...' }.
+        # @return [Boolean] True if successfully deleted.
+        def delete_comment(comment_id, context = {})
+          issue_id_or_key = context[:issue_id]
+          unless issue_id_or_key
+            raise ArgumentError,
+                  "Missing required context: :issue_id must be provided for JiraAdapter#delete_comment"
+          end
+
+          path = "/rest/api/3/issue/#{issue_id_or_key}/comment/#{comment_id}"
+          make_request(:delete, path)
+          true
+        end
       end
     end
   end

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

@@ -1,45 +1,64 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module ActiveProject
   module Adapters
     module Jira
+      # Low-level HTTP concerns for JiraAdapter
       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.
+        include Connections::Rest
+
+        SERAPH_HEADER = "x-seraph-loginreason"
+
+        # @param config [ActiveProject::Configurations::BaseAdapterConfiguration]
+        #   Must expose :site_url, :username, :api_token.
+        # @raise [ArgumentError] if required keys are missing.
         def initialize(config:)
           unless config.is_a?(ActiveProject::Configurations::BaseAdapterConfiguration)
             raise ArgumentError, "JiraAdapter requires a BaseAdapterConfiguration object"
           end
 
-          @config = config
+          super(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
+          # --- Build an absolute base URL ------------------------------------
+          raw_url = @config.options.fetch(:site_url)
+          site_url = raw_url =~ %r{\Ahttps?://}i ? raw_url.dup : +"https://#{raw_url}"
+          site_url.chomp!("/")
+
+          username = @config.options.fetch(:username)
+          api_token = @config.options.fetch(:api_token)
 
-          @connection = initialize_connection
+          init_rest(
+            base_url: site_url,
+            auth_middleware: lambda do |conn|
+              # Faraday’s built-in basic-auth helper                               :contentReference[oaicite:0]{index=0}
+              conn.request :authorization, :basic, username, api_token
+            end
+          )
         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
+        # --------------------------------------------------------------------
+        # Tiny wrapper around HttpClient#request that handles Jira quirks
+        # --------------------------------------------------------------------
+        #
+        # @param method [Symbol]  :get, :post, :put, :delete, …
+        # @param path   [String]  e.g. "/rest/api/3/issue/PROJ-1"
+        # @param body   [String, Hash, nil]
+        # @param query  [Hash,nil] additional query-string params
+        # @return [Hash, nil] parsed JSON response
+        #
+        # @raise [ActiveProject::AuthenticationError] if Jira signals
+        #   AUTHENTICATED_FAILED via X-Seraph-LoginReason header.
+        def make_request(method, path, body = nil, query = nil, headers = {})
+          res = request_rest(method, path, body, query, headers)
+          if last_response&.headers&.[](SERAPH_HEADER)&.include?("AUTHENTICATED_FAILED")
+            raise ActiveProject::AuthenticationError, "Jira authentication failed"
           end
+
+          res
         end
       end
     end