activeproject 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b69a05303fa485956e8bdf7e56984aa5690df8f4bb7b9119253d760f0940916
-  data.tar.gz: 45dab21a69a42325b067f01510f47e16f9b8c9ebb312b11793e1b0c447f563a6
+  metadata.gz: 9960da80d5e32d0cdfa4fce3ffe824ebf3c36a8710d0a7782dbac3ec7001b863
+  data.tar.gz: 1ca92b2e165afbe314b70d970cb42817e5987ae3bfaa5a7d0ba58987999afe45
 SHA512:
-  metadata.gz: fcd6726cf79cfa6819ecfe3de62d5502d94317bfbb824a4f5e4c3579b836fa65a06ee408ff69f601d1e9ba47b7d3d45848e326e48608b413a7431b87e208dbff
-  data.tar.gz: 23191e09bd239c8fc21552c64520de969e70875fbedcb514449dbe1fe4f157cc204b150eb45a9b71ddb0af0edf0774fc4934ba1deb9cafe5202ca64b1245d7e2
+  metadata.gz: 46a0f331e8f7e956d643e6070d21dc20abe3825308c0761067df3773b3a20fcea7b94aa9c07f333c0fc794443945419436486b3daec49e4a19b5e473b05b4c6c
+  data.tar.gz: d78685242c2ea12a5a522a74e64b8f438d613dd2bb2977c14aca0ed7ba918ef953719f17b23b8cf6400723ea23886f7a63df898a9b804214eab4db635c8fb794

data/Rakefile

@@ -1,3 +1,5 @@
-require "bundler/setup"
+# frozen_string_literal: true
 
-require "bundler/gem_tasks"
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'

data/lib/active_project/adapters/base.rb

@@ -18,7 +18,6 @@ module ActiveProject
         raise NotImplementedError, "#{self.class.name} must implement #find_project"
       end
 
-
       # Creates a new project.
       # @param attributes [Hash] Project attributes (platform-specific).
       # @return [ActiveProject::Project] The created project object.
@@ -35,7 +34,6 @@ module ActiveProject
         raise NotImplementedError, "#{self.class.name} does not support #create_list or must implement #create_list"
       end
 
-
       # Deletes a project. Use with caution.
       # @param project_id [String, Integer] The ID or key of the project to delete.
       # @return [Boolean] true if deletion was successful (or accepted), false otherwise.
@@ -44,7 +42,6 @@ module ActiveProject
         raise NotImplementedError, "#{self.class.name} does not support #delete_project or must implement it"
       end
 
-
       # Lists issues within a specific project.
       # @param project_id [String, Integer] The ID or key of the project.
       # @param options [Hash] Optional filtering/pagination options.
@@ -78,6 +75,12 @@ module ActiveProject
         raise NotImplementedError, "#{self.class.name} must implement #update_issue"
       end
 
+      # Base implementation of delete_issue that raises NotImplementedError
+      # This will be included in the base adapter class and overridden by specific adapters
+      def delete_issue(id, context = {})
+        raise NotImplementedError, "The #{self.class.name} adapter does not implement delete_issue"
+      end
+
       # Adds a comment to an issue.
       # @param issue_id [String, Integer] The ID or key of the issue.
       # @param comment_body [String] The text of the comment.
@@ -88,11 +91,11 @@ module ActiveProject
       end
 
       # Verifies the signature of an incoming webhook request, if supported by the platform.
-      # @param request_body [String] The raw request body.
-      # @param signature_header [String] The value of the platform-specific signature header (e.g., 'X-Trello-Webhook').
+      # @param _request_body [String] The raw request body.
+      # @param _signature_header [String] The value of the platform-specific signature header (e.g., 'X-Trello-Webhook').
       # @return [Boolean] true if the signature is valid or verification is not supported/needed, false otherwise.
       # @raise [NotImplementedError] if verification is applicable but not implemented by a subclass.
-      def verify_webhook_signature(request_body, signature_header)
+      def verify_webhook_signature(_request_body, _signature_header)
         # Default implementation assumes no verification needed or supported.
         # Adapters supporting verification should override this.
         true
@@ -107,7 +110,6 @@ module ActiveProject
         raise NotImplementedError, "#{self.class.name} must implement #parse_webhook"
       end
 
-
       # Retrieves details for the currently authenticated user.
       # @return [ActiveProject::Resources::User] The user object.
       # @raise [ActiveProject::AuthenticationError] if authentication fails.

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Basecamp
+      module Comments
+        # Adds a comment to a To-do in Basecamp.
+        # @param todo_id [String, Integer] The ID of the Basecamp To-do.
+        # @param comment_body [String] The comment text (HTML).
+        # @param context [Hash] Required context: { project_id: '...' }.
+        # @return [ActiveProject::Resources::Comment] The created comment resource.
+        def add_comment(todo_id, comment_body, context = {})
+          project_id = context[:project_id]
+          unless project_id
+            raise ArgumentError,
+                  "Missing required context: :project_id must be provided for BasecampAdapter#add_comment"
+          end
+
+          path = "buckets/#{project_id}/recordings/#{todo_id}/comments.json"
+          payload = { content: comment_body }.to_json
+          comment_data = make_request(:post, path, payload)
+          map_comment_data(comment_data, todo_id.to_i)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Basecamp
+      module Connection
+        BASE_URL_TEMPLATE = "https://3.basecampapi.com/%<account_id>s/"
+        # Initializes the Basecamp Adapter.
+        # @param config [Configurations::BaseAdapterConfiguration] The configuration object for Basecamp.
+        # @raise [ArgumentError] if required configuration options (:account_id, :access_token) are missing.
+        def initialize(config:)
+          # For now, Basecamp uses the base config. If specific Basecamp options are added,
+          # create BasecampConfiguration and check for that type.
+          unless config.is_a?(ActiveProject::Configurations::BaseAdapterConfiguration)
+            raise ArgumentError, "BasecampAdapter requires a BaseAdapterConfiguration object"
+          end
+
+          @config = config
+
+          account_id = @config.options[:account_id].to_s # Ensure it's a string
+          access_token = @config.options[:access_token]
+
+          unless account_id && !account_id.empty? && access_token && !access_token.empty?
+            raise ArgumentError, "BasecampAdapter configuration requires :account_id and :access_token"
+          end
+
+          @base_url = format(BASE_URL_TEMPLATE, account_id: account_id)
+          @connection = initialize_connection
+        end
+
+        private
+
+        # Initializes the Faraday connection object.
+        def initialize_connection
+          access_token = @config.options[:access_token]
+
+          Faraday.new(url: @base_url) do |conn|
+            conn.request :authorization, :bearer, access_token
+            conn.request :retry
+            conn.response :raise_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/basecamp/issues.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Basecamp
+      module Issues
+        # Lists To-dos within a specific project.
+        # @param project_id [String, Integer] The ID of the Basecamp project.
+        # @param options [Hash] Optional options. Accepts :todolist_id and :page_size.
+        # @return [Array<ActiveProject::Resources::Issue>] An array of issue resources.
+        def list_issues(project_id, options = {})
+          all_todos = []
+          todolist_id = options[:todolist_id]
+          page_size = options[:page_size] || 50
+
+          unless todolist_id
+            todolist_id = find_first_todolist_id(project_id)
+            return [] unless todolist_id
+          end
+
+          path = "buckets/#{project_id}/todolists/#{todolist_id}/todos.json"
+          query = {}
+          query[:per_page] = page_size if page_size
+
+          loop do
+            response = @connection.get(path, query)
+            todos_data = begin
+                           JSON.parse(response.body)
+                         rescue StandardError
+                           []
+                         end
+            break if todos_data.empty?
+
+            todos_data.each do |todo_data|
+              all_todos << map_todo_data(todo_data, project_id)
+            end
+
+            link_header = response.headers["Link"]
+            next_url = parse_next_link(link_header)
+            break unless next_url
+
+            path = next_url.sub(@base_url, "").sub(%r{^/}, "")
+            query = {} # Clear query as pagination is in the URL now
+          end
+
+          all_todos
+        rescue Faraday::Error => e
+          handle_faraday_error(e)
+        end
+
+        # Finds a specific To-do by its ID.
+        # @param todo_id [String, Integer] The ID of the Basecamp To-do.
+        # @param context [Hash] Required context: { project_id: '...' }.
+        # @return [ActiveProject::Resources::Issue] The issue resource.
+        def find_issue(todo_id, context = {})
+          project_id = context[:project_id]
+          unless project_id
+            raise ArgumentError, "Missing required context: :project_id must be provided for BasecampAdapter#find_issue"
+          end
+
+          path = "buckets/#{project_id}/todos/#{todo_id}.json"
+          todo_data = make_request(:get, path)
+          map_todo_data(todo_data, project_id)
+        end
+
+        # Creates a new To-do in Basecamp.
+        # @param project_id [String, Integer] The ID of the Basecamp project.
+        # @param attributes [Hash] To-do attributes. Required: :todolist_id, :title. Optional: :description, :due_on, :assignee_ids.
+        # @return [ActiveProject::Resources::Issue] The created issue resource.
+        def create_issue(project_id, attributes)
+          todolist_id = attributes[:todolist_id]
+          title = attributes[:title]
+
+          unless todolist_id && title && !title.empty?
+            raise ArgumentError, "Missing required attributes for Basecamp to-do creation: :todolist_id, :title"
+          end
+
+          path = "buckets/#{project_id}/todolists/#{todolist_id}/todos.json"
+
+          payload = {
+            content: title,
+            description: attributes[:description],
+            due_on: attributes[:due_on].respond_to?(:strftime) ? attributes[:due_on].strftime("%Y-%m-%d") : attributes[:due_on],
+            assignee_ids: attributes[:assignee_ids]
+          }.compact
+
+          todo_data = make_request(:post, path, payload.to_json)
+          map_todo_data(todo_data, project_id)
+        end
+
+        # Updates an existing To-do in Basecamp.
+        # Handles updates to standard fields via PUT and status changes via POST/DELETE completion endpoints.
+        # @param todo_id [String, Integer] The ID of the Basecamp To-do.
+        # @param attributes [Hash] Attributes to update (e.g., :title, :description, :status, :assignee_ids, :due_on).
+        # @param context [Hash] Required context: { project_id: '...' }.
+        # @return [ActiveProject::Resources::Issue] The updated issue resource (fetched after updates).
+        def update_issue(todo_id, attributes, context = {})
+          project_id = context[:project_id]
+          unless project_id
+            raise ArgumentError,
+                  "Missing required context: :project_id must be provided for BasecampAdapter#update_issue"
+          end
+
+          put_payload = {}
+          put_payload[:content] = attributes[:title] if attributes.key?(:title)
+          put_payload[:description] = attributes[:description] if attributes.key?(:description)
+          if attributes.key?(:due_on)
+            due_on_val = attributes[:due_on]
+            put_payload[:due_on] = due_on_val.respond_to?(:strftime) ? due_on_val.strftime("%Y-%m-%d") : due_on_val
+          end
+          put_payload[:assignee_ids] = attributes[:assignee_ids] if attributes.key?(:assignee_ids)
+
+          status_change_required = attributes.key?(:status)
+          target_status = attributes[:status] if status_change_required
+
+          unless !put_payload.empty? || status_change_required
+            raise ArgumentError, "No attributes provided to update for BasecampAdapter#update_issue"
+          end
+
+          unless put_payload.empty?
+            put_path = "buckets/#{project_id}/todos/#{todo_id}.json"
+            make_request(:put, put_path, put_payload.compact.to_json)
+          end
+
+          if status_change_required
+            completion_path = "buckets/#{project_id}/todos/#{todo_id}/completion.json"
+            begin
+              if target_status == :closed
+                make_request(:post, completion_path)
+              elsif target_status == :open
+                make_request(:delete, completion_path)
+              end
+            rescue NotFoundError
+              raise unless target_status == :open
+            end
+          end
+
+          find_issue(todo_id, context)
+        end
+
+        # Deletes a To-do in Basecamp.
+        # @param todo_id [String, Integer] The ID of the Basecamp To-do to delete.
+        # @param context [Hash] Required context: { project_id: '...' }.
+        # @return [Boolean] True if successfully deleted.
+        def delete_issue(todo_id, context = {})
+          project_id = context[:project_id]
+          unless project_id
+            raise ArgumentError, "Missing required context: :project_id must be provided for BasecampAdapter#delete_issue"
+          end
+
+          path = "buckets/#{project_id}/todos/#{todo_id}.json"
+          make_request(:delete, path)
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Basecamp
+      module Lists
+        # Creates a new Todolist within a project.
+        # @param project_id [String, Integer] The ID of the Basecamp project (bucket).
+        # @param attributes [Hash] Todolist attributes. Required: :name. Optional: :description.
+        # @return [Hash] The raw data hash of the created todolist.
+        def create_list(project_id, attributes)
+          unless attributes[:name] && !attributes[:name].empty?
+            raise ArgumentError, "Missing required attribute for Basecamp todolist creation: :name"
+          end
+
+          project_data = make_request(:get, "projects/#{project_id}.json")
+          todoset_dock_entry = project_data&.dig("dock")&.find { |d| d["name"] == "todoset" }
+          todoset_url = todoset_dock_entry&.dig("url")
+          raise ApiError, "Could not find todoset URL for project #{project_id}" unless todoset_url
+
+          todoset_id = todoset_url.match(%r{todosets/(\d+)\.json$})&.captures&.first
+          raise ApiError, "Could not extract todoset ID from URL: #{todoset_url}" unless todoset_id
+
+          path = "buckets/#{project_id}/todosets/#{todoset_id}/todolists.json"
+          payload = {
+            name: attributes[:name],
+            description: attributes[:description]
+          }.compact
+
+          make_request(:post, path, payload.to_json)
+        end
+
+        # Finds the ID of the first todolist in a project.
+        # @param project_id [String, Integer]
+        # @return [String, nil]
+        def find_first_todolist_id(project_id)
+          project_data = make_request(:get, "projects/#{project_id}.json")
+          todoset_dock_entry = project_data&.dig("dock")&.find { |d| d["name"] == "todoset" }
+          todoset_url = todoset_dock_entry&.dig("url")
+          return nil unless todoset_url
+
+          todoset_id = todoset_url.match(%r{todosets/(\d+)\.json$})&.captures&.first
+          return nil unless todoset_id
+
+          todolists_url_path = "buckets/#{project_id}/todosets/#{todoset_id}/todolists.json"
+          todolists_data = make_request(:get, todolists_url_path)
+          todolists_data&.first&.dig("id")
+        rescue NotFoundError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Basecamp
+      module Projects
+        # Lists projects 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_projects = []
+          path = "projects.json"
+
+          loop do
+            response = @connection.get(path)
+            projects_data = begin
+              JSON.parse(response.body)
+            rescue StandardError
+              []
+            end
+            break if projects_data.empty?
+
+            projects_data.each do |project_data|
+              all_projects << Resources::Project.new(self,
+                                                     id: project_data["id"],
+                                                     key: nil,
+                                                     name: project_data["name"],
+                                                     adapter_source: :basecamp,
+                                                     raw_data: project_data)
+            end
+
+            link_header = response.headers["Link"]
+            next_url = parse_next_link(link_header)
+            break unless next_url
+
+            path = next_url.sub(@base_url, "").sub(%r{^/}, "")
+          end
+
+          all_projects
+        rescue Faraday::Error => e
+          handle_faraday_error(e)
+        end
+
+        # Finds a specific project by its ID.
+        # @param project_id [String, Integer] The ID of the Basecamp project.
+        # @return [ActiveProject::Resources::Project] The project resource.
+        def find_project(project_id)
+          path = "projects/#{project_id}.json"
+          project_data = make_request(:get, path)
+          return nil unless project_data
+
+          raise NotFoundError, "Basecamp project ID #{project_id} is trashed." if project_data["status"] == "trashed"
+
+          Resources::Project.new(self,
+                                 id: project_data["id"],
+                                 key: nil,
+                                 name: project_data["name"],
+                                 adapter_source: :basecamp,
+                                 raw_data: project_data)
+        end
+
+        # Creates a new project in Basecamp.
+        # @param attributes [Hash] Project attributes. Required: :name. Optional: :description.
+        # @return [ActiveProject::Resources::Project] The created project resource.
+        def create_project(attributes)
+          unless attributes[:name] && !attributes[:name].empty?
+            raise ArgumentError, "Missing required attribute for Basecamp project creation: :name"
+          end
+
+          path = "projects.json"
+          payload = {
+            name: attributes[:name],
+            description: attributes[:description]
+          }.compact
+
+          project_data = make_request(:post, path, payload.to_json)
+
+          Resources::Project.new(self,
+                                 id: project_data["id"],
+                                 key: nil,
+                                 name: project_data["name"],
+                                 adapter_source: :basecamp,
+                                 raw_data: project_data)
+        end
+
+        # Recovers a trashed project in Basecamp.
+        # @param project_id [String, Integer] The ID of the project to recover.
+        # @return [Boolean] true if recovery was successful (API returns 204).
+        def untrash_project(project_id)
+          path = "projects/#{project_id}.json"
+          make_request(:put, path, { "status": "active" }.to_json)
+          true
+        end
+
+        # Archives (trashes) a project in Basecamp.
+        # Note: Basecamp API doesn't offer permanent deletion via this endpoint.
+        # @param project_id [String, Integer] The ID of the project to trash.
+        # @return [Boolean] true if trashing 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)
+          path = "projects/#{project_id}.json"
+          make_request(:delete, path)
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Basecamp
+      module Webhooks
+        # Parses an incoming Basecamp 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)
+
+          kind = payload["kind"]
+          recording = payload["recording"]
+          creator = payload["creator"]
+          timestamp = begin
+            Time.parse(payload["created_at"])
+          rescue StandardError
+            nil
+          end
+          return nil unless recording && kind
+
+          event_type = nil
+          object_kind = nil
+          event_object_id = recording["id"]
+          object_key = nil
+          project_id = recording.dig("bucket", "id")
+          changes = nil
+          object_data = nil
+
+          case kind
+          when /todo_created$/
+            event_type = :issue_created
+            object_kind = :issue
+          when /todo_assignment_changed$/, /todo_completion_changed$/, /todo_content_updated$/, /todo_description_changed$/, /todo_due_on_changed$/
+            event_type = :issue_updated
+            object_kind = :issue
+          when /comment_created$/
+            event_type = :comment_added
+            object_kind = :comment
+          when /comment_content_changed$/
+            event_type = :comment_updated
+            object_kind = :comment
+          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(creator),
+            timestamp: timestamp,
+            adapter_source: :basecamp,
+            changes: changes,
+            object_data: object_data,
+            raw_data: payload
+          )
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end