activeproject 0.2.0 → 0.5.0

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Fizzy
+      module Projects
+        # Lists boards accessible by the configured credentials.
+        # Handles pagination automatically using the Link header.
+        # @return [Array<ActiveProject::Resources::Project>] An array of project resources.
+        def list_projects
+          all_boards = []
+          path = "boards.json"
+
+          loop do
+            response = @connection.get(path)
+            boards_data = parse_response(response)
+            break if boards_data.empty?
+
+            boards_data.each do |board_data|
+              all_boards << map_board_data(board_data)
+            end
+
+            next_url = parse_next_link(response.headers["Link"])
+            break unless next_url
+
+            path = extract_path_from_url(next_url)
+          end
+
+          all_boards
+        rescue Faraday::Error => e
+          handle_faraday_error(e)
+        end
+
+        # Finds a specific board by its ID.
+        # @param board_id [String] The ULID of the Fizzy board.
+        # @return [ActiveProject::Resources::Project] The project resource.
+        def find_project(board_id)
+          path = "boards/#{board_id}.json"
+          board_data = make_request(:get, path)
+          return nil unless board_data
+
+          map_board_data(board_data)
+        end
+
+        # Creates a new board in Fizzy.
+        # @param attributes [Hash] Board attributes. Required: :name. Optional: :all_access, :auto_postpone_period.
+        # @return [ActiveProject::Resources::Project] The created project resource.
+        def create_project(attributes)
+          unless attributes[:name] && !attributes[:name].empty?
+            raise ArgumentError, "Missing required attribute for Fizzy board creation: :name"
+          end
+
+          path = "boards.json"
+          payload = {
+            board: {
+              name: attributes[:name],
+              all_access: attributes.fetch(:all_access, true),
+              auto_postpone_period: attributes[:auto_postpone_period]
+            }.compact
+          }
+
+          # Fizzy returns 201 Created with Location header, need to fetch the board
+          response = @connection.post(path) do |req|
+            req.body = payload.to_json
+          end
+
+          # Extract board ID from Location header and fetch it
+          location = response.headers["Location"]
+          if location
+            board_id = location.match(%r{/boards/([^/.]+)})[1]
+            find_project(board_id)
+          else
+            # Fallback: parse response body if available
+            board_data = parse_response(response)
+            map_board_data(board_data)
+          end
+        rescue Faraday::Error => e
+          handle_faraday_error(e)
+        end
+
+        # Deletes a board in Fizzy.
+        # @param board_id [String] The ULID of the board to delete.
+        # @return [Boolean] true if deletion was successful (API returns 204).
+        def delete_project(board_id)
+          path = "boards/#{board_id}.json"
+          make_request(:delete, path)
+          true
+        end
+
+        private
+
+        def map_board_data(board_data)
+          Resources::Project.new(
+            self,
+            id: board_data["id"],
+            key: nil,
+            name: board_data["name"],
+            adapter_source: :fizzy,
+            raw_data: board_data
+          )
+        end
+      end
+    end
+  end
+end

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