activeproject 0.3.0 → 0.5.0

data/lib/active_project/adapters/fizzy_adapter.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "time"
+
+module ActiveProject
+  module Adapters
+    # Adapter for interacting with the Fizzy API.
+    # Fizzy is a Kanban-style project tracking tool by 37signals.
+    # Implements the interface defined in ActiveProject::Adapters::Base.
+    # API Docs: https://github.com/basecamp/fizzy (see docs/API.md)
+    class FizzyAdapter < Base
+      attr_reader :config, :base_url
+
+      include Fizzy::Connection
+      include Fizzy::Projects
+      include Fizzy::Issues
+      include Fizzy::Comments
+      include Fizzy::Columns
+
+      # --- Resource Factories ---
+
+      # Returns a factory for Project resources (Boards).
+      # @return [ResourceFactory<Resources::Project>]
+      def projects
+        ResourceFactory.new(adapter: self, resource_class: Resources::Project)
+      end
+
+      # Returns a factory for Issue resources (Cards).
+      # @return [ResourceFactory<Resources::Issue>]
+      def issues
+        ResourceFactory.new(adapter: self, resource_class: Resources::Issue)
+      end
+
+      # --- Implementation of Base methods ---
+
+      # Retrieves details for the currently authenticated user.
+      # Uses /my/identity endpoint which returns accounts and user info.
+      # @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
+        # Fizzy's /my/identity is at the root, not under account_slug
+        # We need to make a request to the base URL without the account_slug
+        base_without_slug = @base_url.sub(%r{/\d+/$}, "/")
+        response = @connection.get("#{base_without_slug}my/identity")
+        identity_data = parse_response(response)
+
+        # Get the first account's user data
+        first_account = identity_data["accounts"]&.first
+        return nil unless first_account
+
+        user_data = first_account["user"]
+        map_user_data(user_data)
+      rescue Faraday::Error => e
+        handle_faraday_error(e)
+      end
+
+      # Checks if the adapter can successfully authenticate and connect to the service.
+      # @return [Boolean] true if connection is successful, false otherwise.
+      def connected?
+        get_current_user
+        true
+      rescue ActiveProject::AuthenticationError
+        false
+      end
+
+      private
+
+      # Helper method for making requests.
+      def make_request(method, path, body = nil, query = {})
+        request(method, path, body: body, query: query)
+      end
+
+      # Parses JSON response body.
+      def parse_response(response)
+        return {} if response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        {}
+      end
+
+      # Extracts relative path from full URL.
+      def extract_path_from_url(url)
+        url.sub(@base_url, "").sub(%r{^/}, "")
+      end
+
+      # Parses the 'next' link URL from the Link header.
+      def parse_next_link(link_header)
+        return nil unless link_header
+
+        links = link_header.split(",").map(&:strip)
+        next_link = links.find { |link| link.end_with?('rel="next"') }
+        return nil unless next_link
+
+        match = next_link.match(/<([^>]+)>/)
+        match ? match[1] : nil
+      end
+
+      # Handles Faraday errors.
+      def handle_faraday_error(error)
+        status = error.response_status
+        body = error.response_body
+
+        parsed_body = begin
+          JSON.parse(body)
+        rescue StandardError
+          { "error" => body }
+        end
+        message = parsed_body["error"] || parsed_body["message"] || "Unknown Fizzy Error"
+
+        case status
+        when 401, 403
+          raise AuthenticationError, "Fizzy authentication/authorization failed (Status: #{status}): #{message}"
+        when 404
+          raise NotFoundError, "Fizzy resource not found (Status: 404): #{message}"
+        when 429
+          retry_after = error.response_headers&.dig("Retry-After")
+          msg = "Fizzy rate limit exceeded (Status: 429)"
+          msg += ". Retry after #{retry_after} seconds." if retry_after
+          raise RateLimitError, msg
+        when 400, 422
+          raise ValidationError.new("Fizzy validation failed (Status: #{status}): #{message}",
+                                    status_code: status, response_body: body)
+        else
+          raise ApiError.new("Fizzy API error (Status: #{status || 'N/A'}): #{message}",
+                             original_error: error, status_code: status, response_body: body)
+        end
+      end
+
+      # Maps raw Fizzy User data hash to a User resource.
+      # @param user_data [Hash, nil] Raw user data from Fizzy API.
+      # @return [Resources::User, nil]
+      def map_user_data(user_data)
+        return nil unless user_data && user_data["id"]
+
+        Resources::User.new(
+          self,
+          id: user_data["id"],
+          name: user_data["name"],
+          email: user_data["email_address"],
+          adapter_source: :fizzy,
+          raw_data: user_data
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module GithubProject
+      module Comments
+        #
+        # Add a comment to the underlying Issue or PR of a ProjectV2Item.
+        # For draft items (no linked content) this raises NotImplementedError,
+        # because GitHub does not expose a comment thread for drafts.
+        #
+        # @param item_id [String] ProjectV2Item node-ID
+        # @param body    [String] Markdown text
+        # @param ctx     [Hash]   MUST include :content_node_id for speed,
+        #                         otherwise we’ll query.
+        #
+        def add_comment(item_id, body, ctx = {})
+          content_id =
+            ctx[:content_node_id] ||
+            begin
+              q = <<~GQL
+                query($id:ID!){
+                  node(id:$id){
+                    ... on ProjectV2Item{ content{ __typename ... on Issue{id} ... on PullRequest{id} } }
+                  }
+                }
+              GQL
+              request_gql(query: q, variables: { id: item_id })
+                .dig("node", "content", "id")
+            end
+
+          raise NotImplementedError, "Draft cards cannot receive comments" unless content_id
+
+          mutation = <<~GQL
+            mutation($subject:ID!, $body:String!){
+              addComment(input:{subjectId:$subject, body:$body}){ commentEdge{ node{ id body author{login}
+                createdAt updatedAt } } }
+            }
+          GQL
+          comment_node = request_gql(query: mutation,
+                                     variables: { subject: content_id, body: body })
+                         .dig("addComment", "commentEdge", "node")
+
+          map_comment(comment_node, item_id)
+        end
+        alias create_comment add_comment
+
+        def update_comment(comment_id, body)
+          mutation = <<~GQL
+            mutation($id:ID!, $body:String!){
+              updateIssueComment(input:{id:$id, body:$body}){
+                issueComment { id body updatedAt }
+              }
+            }
+          GQL
+          node = request_gql(query: mutation,
+                             variables: { id: comment_id, body: body })
+                 .dig("updateIssueComment", "issueComment")
+
+          map_comment(node, node["id"])
+        end
+
+        def delete_comment(comment_id)
+          mutation = <<~GQL
+            mutation($id:ID!){
+              deleteIssueComment(input:{id:$id}){ clientMutationId }
+            }
+          GQL
+          request_gql(query: mutation, variables: { id: comment_id })
+          true
+        end
+
+        private
+
+        def map_comment(node, item_id)
+          Resources::Comment.new(
+            self,
+            id: node["id"],
+            body: node["body"],
+            author: map_user(node["author"]),
+            created_at: Time.parse(node["createdAt"]),
+            updated_at: Time.parse(node["updatedAt"]),
+            issue_id: item_id,
+            adapter_source: :github,
+            raw_data: node
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module GithubProject
+      module Connection
+        include Connections::GraphQl
+
+        ENDPOINT = "https://api.github.com/graphql"
+
+        def initialize(config:)
+          super(config: config)
+          token = @config.options.fetch(:access_token)
+
+          init_graphql(
+            endpoint: ENDPOINT,
+            token: token,
+            extra_headers: {
+              "X-Github-Next-Global-ID" => "1"
+            }
+          )
+
+          # monkey-patch method for this instance only
+          class << self
+            prepend InstanceGraphqlPatcher
+          end
+        end
+
+        module InstanceGraphqlPatcher
+          def request_gql(query:, variables: {})
+            payload = { query: query, variables: variables }.to_json
+            res = request(:post, "", body: payload)
+            handle_deprecation_warnings!(res)
+            raise_graphql_errors!(res)
+            res["data"]
+          end
+
+          def handle_deprecation_warnings!(res)
+            warnings = res.dig("extensions", "warnings") || []
+            warnings.each do |w|
+              next unless w["type"] == "DEPRECATION"
+
+              legacy = w.dig("data", "legacy_global_id")
+              updated = w.dig("data", "next_global_id")
+              next unless legacy && updated
+
+              (@_deprecation_map ||= {})[legacy] = updated
+            end
+          end
+
+          def upgraded_id(legacy_id)
+            @_deprecation_map&.fetch(legacy_id, legacy_id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_project/adapters/github_project/helpers.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module GithubProject
+      module Helpers
+        #
+        # Cursor-based pagination wrapper for GraphQL connections.
+        #
+        # @param query [String]   the GraphQL query with $after variable
+        # @param variables [Hash] initial variables (without :after)
+        # @param connection_path [Array<String>] JSON path to the connection hash
+        # @yield [vars] yields the variables hash for each page so caller can execute the request
+        # @return [Array<Hash>] all nodes from every page
+        #
+        def fetch_all_pages(query, variables:, connection_path:, &request_block)
+          # turn the (possibly-nil) block into something callable
+          request_fn =
+            request_block ||
+            ->(v) { request_gql(query: query, variables: v) }
+
+          after = nil
+          nodes = []
+
+          loop do
+            data = request_fn.call(variables.merge(after: after))
+            conn = data.dig(*connection_path)
+            nodes.concat(conn["nodes"])
+            break unless conn["pageInfo"]["hasNextPage"]
+
+            after = conn["pageInfo"]["endCursor"]
+          end
+
+          nodes
+        end
+
+        #
+        # Resolve a user/org login → GraphQL node-ID (memoised).
+        #
+        def owner_node_id(login)
+          @owner_id_cache ||= {}
+          return @owner_id_cache[login] if @owner_id_cache.key?(login)
+
+          q = <<~GQL
+            query($login:String!){
+              organization(login:$login){ id }
+              user(login:$login){ id }
+            }
+          GQL
+
+          data = request_gql(query: q, variables: { login: login })
+          id = data.dig("organization", "id") || data.dig("user", "id")
+          raise ActiveProject::NotFoundError, "GitHub owner “#{login}” not found" unless id
+
+          id = upgraded_id(id) if respond_to?(:upgraded_id)
+
+          @owner_id_cache[login] = id
+        end
+
+        #
+        # Convert a compact user hash returned by GraphQL into Resources::User.
+        #
+        def map_user(u)
+          return nil unless u
+
+          Resources::User.new(
+            self,
+            id: u["id"] || u["login"],
+            name: u["login"],
+            email: u["email"],
+            adapter_source: :github,
+            raw_data: u
+          )
+        end
+
+        def project_field_ids(project_id)
+          @field_cache ||= {}
+          @field_cache[project_id] ||= begin
+            q = <<~GQL
+              query($id:ID!){
+                node(id:$id){
+                  ... on ProjectV2{
+                    fields(first:50){
+                      nodes{
+                        ... on ProjectV2FieldCommon{ id name }
+                      }
+                    }
+                  }
+                }
+              }
+            GQL
+            nodes = request_gql(query: q, variables: { id: project_id })
+                    .dig("node", "fields", "nodes")
+            nodes.to_h { |f| [ f["name"], f["id"] ] }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module GithubProject
+      #
+      # Project-item CRUD operations for GitHub Projects v2.
+      #
+      # This module exists because GitHub decided that "issues," "drafts," and "project items"
+      # are three different species, and we have to *unify the galaxy.*
+      #
+      module Issues
+        include Helpers
+        # Like everything on GitHub: decent default, weird edge cases. Why not 25 like a normal person?
+        DEFAULT_ITEM_PAGE_SIZE = 50
+
+        #
+        # Lists *every* issue or draft in a GitHub Project.
+        # Handles pagination the GitHub way: manually, painfully, endlessly.
+        #
+        # options[:page_size] → control how much data you want per jump into hyperspace.
+        #
+        def list_issues(project_id, options = {})
+          page_size = options.fetch(:page_size, DEFAULT_ITEM_PAGE_SIZE)
+          query = <<~GQL
+            query($id:ID!, $first:Int!, $after:String){
+              node(id:$id){
+                ... on ProjectV2{
+                  items(first:$first, after:$after){
+                    nodes{
+                      id type content{__typename ... on Issue{ id number title body state
+                        assignees(first:10){nodes{login id}}
+                        reporter:author{login} } }
+                      createdAt updatedAt
+                    }
+                    pageInfo{hasNextPage endCursor}
+                  }
+                }
+              }
+            }
+          GQL
+
+          nodes = fetch_all_pages(
+            query,
+            variables: { id: project_id, first: page_size },
+            connection_path: %w[node items]
+          ) { |vars| request_gql(query: query, variables: vars) }
+
+          nodes.map { |n| map_item_to_issue(n, project_id) }
+        end
+
+        #
+        # Fetch a single issue or draft item by its mysterious GraphQL node ID.
+        # If it's missing, you get a 404 so you can take a day off.
+        #
+        def find_issue(item_id, _ctx = {})
+          query = <<~GQL
+            query($id:ID!){
+              node(id:$id){
+                ... on ProjectV2Item{
+                  id
+                  type
+                  fieldValues(first:20){
+                    nodes{
+                      ... on ProjectV2ItemFieldTextValue{
+                        text
+                        field { ... on ProjectV2FieldCommon { name } }
+                      }
+                    }
+                  }
+                  content{
+                    __typename
+                    ... on Issue{
+                      id number title body state
+                      assignees(first:10){nodes{login id}}
+                      reporter:author{login}
+                    }
+                  }
+                  createdAt
+                  updatedAt
+                  project { id }
+                }
+              }
+            }
+          GQL
+          node = request_gql(query: query, variables: { id: item_id })["node"]
+          raise NotFoundError, "Project item #{item_id} not found" unless node
+
+          map_item_to_issue(node, node.dig("project", "id"))
+        end
+
+        #
+        # Create a new issue in the project.
+        #
+        # Choose your destiny:
+        #   - Pass :content_id → links an existing GitHub Issue or PR into the project.
+
+        def create_issue(project_id, attrs)
+          content_id = attrs[:content_id] or
+            raise ArgumentError, "DraftIssues not supported—pass :content_id of a real Issue or PR"
+
+          mutation = <<~GQL
+            mutation($project:ID!, $content:ID!) {
+              addProjectV2ItemById(input:{projectId:$project, contentId:$content}) {
+                item { id }
+              }
+            }
+          GQL
+
+          data = request_gql(
+            query: mutation,
+            variables: { project: project_id, content: content_id }
+          ).dig("addProjectV2ItemById", "item")
+
+          find_issue(data["id"])
+        end
+
+        #
+        # Update fields on an existing ProjectV2Item.
+        #
+        # You can adjust:
+        #   - Title (text field)
+        #   - Status (single-select nightmare field)
+        #
+        # NOTE: Requires you to preload field mappings, because GitHub’s GraphQL API
+        # refuses to help unless you memorize all their withcrafts.
+        #
+        def update_issue_original(project_id, item_id, attrs = {})
+          field_ids = project_field_ids(project_id)
+
+          # -- Update Title (basic) --
+          if attrs[:title]
+            mutation = <<~GQL
+              mutation($proj:ID!, $item:ID!, $field:ID!, $title:String!) {
+                updateProjectV2ItemFieldValue(input:{
+                  projectId:$proj, itemId:$item,
+                  fieldId:$field, value:{text:$title}
+                }) { projectV2Item { id } }
+              }
+            GQL
+            request_gql(query: mutation,
+                        variables: {
+                          proj: project_id,
+                          item: item_id,
+                          field: field_ids.fetch("Title"),
+                          title: attrs[:title]
+                        })
+          end
+
+          # -- Update Status (dark side difficulty) --
+          if attrs[:status]
+            status_field_id = field_ids.fetch("Status")
+            option_id = status_option_id(project_id, attrs[:status])
+            mutation = <<~GQL
+              mutation($proj:ID!, $item:ID!, $field:ID!, $opt:String!) {
+                updateProjectV2ItemFieldValue(input:{
+                  projectId:$proj, itemId:$item,
+                  fieldId:$field, value:{singleSelectOptionId:$opt}
+                }) { projectV2Item { id } }
+              }
+            GQL
+            request_gql(query: mutation,
+                        variables: { proj: project_id, item: item_id,
+                                     field: status_field_id, opt: option_id })
+          end
+
+          find_issue(item_id)
+        end
+
+        #
+        # Delete a ProjectV2Item from a project.
+        # No soft delete, no grace period — just *execute Order 66*.
+        #
+        def delete_issue_original(project_id, item_id)
+          mutation = <<~GQL
+            mutation($proj:ID!, $item:ID!){
+              deleteProjectV2Item(input:{projectId:$proj, itemId:$item}){deletedItemId}
+            }
+          GQL
+          request_gql(query: mutation,
+                      variables: { proj: project_id, item: item_id })
+          true
+        end
+
+        #
+        # Check if a status symbol like :in_progress is known for a project.
+        # Avoids exploding like fukushima reactor if you try to set a status that doesn't exist.
+        #
+        def status_known?(project_id, sym)
+          (@status_cache && @status_cache[project_id] || {}).key?(sym)
+        end
+
+        private
+
+        #
+        # Turn a GraphQL project item node into a clean, beautiful Resources::Issue object.
+        #
+        # Because the only thing worse than undocumented fields is undocumented *types.*
+        #
+        def map_item_to_issue(node, project_id)
+          content = node["content"] || {}
+          typename = content["__typename"]
+          title =
+            if typename == "Issue"
+              content["title"]
+            else
+              # Draft card – try to pull “Title” field value
+              fv = node.dig("fieldValues", "nodes")
+                       &.find { |n| n.dig("field", "name") == "Title" }
+              "(draft) #{fv&.dig('text')}"
+            end
+          description = typename == "Issue" ? content["body"] : nil
+          status = :open
+          status = :closed if typename == "Issue" && content["state"] == "CLOSED"
+
+          assignees = if content["assignees"] && content["assignees"]["nodes"]
+                        content["assignees"]["nodes"].map { |u| map_user(u) }
+          else
+                        []
+          end
+
+          reporter = map_user(content["reporter"]) if content["reporter"]
+
+          Resources::Issue.new(
+            self,
+            id: node["id"],
+            key: typename == "Issue" ? content["number"] : nil,
+            title: title,
+            description: description,
+            status: status,
+            assignees: assignees,
+            reporter: reporter,
+            project_id: project_id,
+            created_at: Time.parse(node["createdAt"]),
+            updated_at: Time.parse(node["updatedAt"]),
+            due_on: nil,
+            priority: nil,
+            adapter_source: :github,
+            raw_data: node
+          )
+        end
+
+        #
+        # Look up the option ID for a given status symbol, or raise a tantrum.
+        #
+        def status_option_id(project_id, symbol)
+          @status_cache ||= Concurrent::Map.new
+          cache = (@status_cache[project_id] ||= load_status_options(project_id))
+
+          return cache[symbol] if cache.key?(symbol)
+
+          available = cache.keys.map(&:inspect).join(", ")
+          raise ArgumentError,
+                "No status #{symbol.inspect} in project; valid symbols are: #{available}"
+        end
+
+        #
+        # Load all valid status options for a project’s "Status" field.
+        # Only way to win is not to play.
+        #
+        def load_status_options(project_id)
+          q = <<~GQL
+            query($id:ID!){
+              node(id:$id){
+                ... on ProjectV2{
+                  field(name:"Status"){
+                    ... on ProjectV2SingleSelectField{
+                      options{ id name }
+                    }
+                  }
+                }
+              }
+            }
+          GQL
+
+          opts = request_gql(query: q, variables: { id: project_id })
+                 .dig("node", "field", "options")
+
+          opts.to_h do |o|
+            key = o["name"].downcase.tr(" ", "_").to_sym
+            [ key, o["id"] ]
+          end
+        end
+      end
+    end
+  end
+end