activeproject 0.0.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f3323a59c15ce296050ec1c7b231416d2cac1aa6f78fe133c8d7d2fd3ebb639
-  data.tar.gz: 0f60e5b29d28e3adca3ce7e26df63929ed3c0d4b898887213823cd284efa365a
+  metadata.gz: 46d0e95fea9e696d7f35f2f8ad2cc32a82f9c068aaf834a9daa2650824650620
+  data.tar.gz: 709c98e0c3bab903db0447c7d53559c55e5c7c98cffc511a771c3b9f08cfa2fc
 SHA512:
-  metadata.gz: 756f9f83b0f443ceb6d426514d79c7c7cca5c8f6b410ab6fbad9469426354735d706d0b00be102a1f36ec4dcb4a7ee04d8b110c6aaaeda3ac8ccce2b61695623
-  data.tar.gz: 5397faf8bae3c5fe4ab86a98360de55c92237270806ac3372cdf7cff08742fa857ccff9f4a139998116ce366cd321df5afab6d81368a78970822de853d43c68c
+  metadata.gz: 7fb8db4e4f952b10364e91727ebec93e6f0e65f6ebf7d5bd331dab77013bd3fc34d100f522a76d5f8d7014d947081a16fdee34535a6327cbabfe6bb74cbfc00b
+  data.tar.gz: 15231c9e5b94a103f21b643f219ffebf4747223f2662a410389ecbf142cc1f618c96384dd5314ba56d00afa6bdf4d0f81cfc0ba33bd580f2fa4999dae8a954eb

data/README.md

@@ -18,7 +18,7 @@ The ActiveProject gem aims to solve this by providing a unified, opinionated int
 
 The initial focus is on integrating with platforms primarily via their **REST APIs**:
 
-*   **Jira (Cloud & Server):** REST API (v2/v3)
+*   **Jira (Cloud & Server):** REST API (v3)
 *   **Basecamp (v3+):** REST API
 *   **Trello:** REST API
 
@@ -69,29 +69,49 @@ $ gem install activeproject
 
 ### Configuration
 
-Configure the adapters in an initializer (e.g., `config/initializers/active_project.rb`):
+Configure multiple adapters, optionally with named instances (default is `:primary`):
 
 ```ruby
 ActiveProject.configure do |config|
-  # Configure Jira Adapter
+  # Primary Jira instance (default name :primary)
   config.add_adapter(:jira,
     site_url: ENV.fetch('JIRA_SITE_URL'),
-    username: ENV.fetch('JIRA_USERNAME'), # Your Jira email
+    username: ENV.fetch('JIRA_USERNAME'),
     api_token: ENV.fetch('JIRA_API_TOKEN')
   )
 
+  # Secondary Jira instance
+  config.add_adapter(:jira, :secondary,
+    site_url: ENV.fetch('JIRA_SECOND_SITE_URL'),
+    username: ENV.fetch('JIRA_SECOND_USERNAME'),
+    api_token: ENV.fetch('JIRA_SECOND_API_TOKEN')
+  )
 
-  # Configure Basecamp Adapter
+  # Basecamp primary instance
   config.add_adapter(:basecamp,
     account_id: ENV.fetch('BASECAMP_ACCOUNT_ID'),
     access_token: ENV.fetch('BASECAMP_ACCESS_TOKEN')
   )
 
-  # Configure other adapters later (e.g., :trello, :basecamp)
-  # config.add_adapter(:trello, key: '...', token: '...')
+  # Trello primary instance
+  config.add_adapter(:trello,
+    key: ENV.fetch('TRELLO_KEY'),
+    token: ENV.fetch('TRELLO_TOKEN')
+  )
 end
 ```
 
+### Accessing adapters
+
+Fetch a specific adapter instance:
+
+```ruby
+jira_primary = ActiveProject.adapter(:jira) # defaults to :primary
+jira_secondary = ActiveProject.adapter(:jira, :secondary)
+basecamp = ActiveProject.adapter(:basecamp) # defaults to :primary
+trello = ActiveProject.adapter(:trello) # defaults to :primary
+```
+
 ### Basic Usage (Jira Example)
 
 ```ruby
@@ -215,80 +235,6 @@ rescue => e
 end
 ```
 
-
-
-### Webhook Handling
-
-The gem provides helpers for parsing webhook payloads and verifying signatures (where applicable), but you need to implement your own webhook receiver endpoint (e.g., a Rails controller action).
-
-```ruby
-# Example Rails Controller Action
-class WebhooksController < ApplicationController
-  # Disable CSRF protection for webhook endpoints
-  skip_before_action :verify_authenticity_token
-
-  def jira_webhook
-    adapter = ActiveProject.adapter(:jira)
-    request_body = request.body.read
-
-    # Verification (if applicable and implemented for your Jira setup)
-    # signature = request.headers['X-Jira-Signature'] # Example header
-    # unless adapter.verify_webhook_signature(request_body, signature)
-    #   render plain: 'Invalid signature', status: :unauthorized
-    #   return
-    # end
-
-    # Parse the event
-    event = adapter.parse_webhook(request_body, request.headers)
-
-    if event
-      puts "Received Jira Event: #{event.event_type} for #{event.object_kind} #{event.object_key || event.object_id}"
-      # Process the event (e.g., queue a background job)
-      # handle_event(event)
-    else
-      puts "Received unhandled or unparseable Jira webhook"
-    end
-
-    head :ok # Respond to Jira quickly
-  end
-
-  def trello_webhook
-    adapter = ActiveProject.adapter(:trello)
-    request_body = request.body.read
-    signature = request.headers['X-Trello-Webhook'] # Trello signature header
-    callback_url = request.original_url # The URL Trello sent the webhook to
-    trello_api_secret = ENV.fetch('TRELLO_API_SECRET') # You need your secret
-
-    # Verification (Manual comparison using the helper)
-    expected_signature = ActiveProject::Adapters::TrelloAdapter.compute_webhook_signature(
-      callback_url,
-      request_body,
-      trello_api_secret
-    )
-
-    unless ActiveSupport::SecurityUtils.secure_compare(signature, expected_signature)
-      render plain: 'Invalid Trello signature', status: :unauthorized
-      return
-    end
-
-    # Parse the event
-    event = adapter.parse_webhook(request_body)
-
-    if event
-      puts "Received Trello Event: #{event.event_type} for #{event.object_kind} #{event.object_id}"
-      # Process the event
-    else
-      puts "Received unhandled or unparseable Trello webhook"
-    end
-
-    head :ok
-  end
-
-  # Add similar actions for other adapters like Basecamp
-
-end
-```
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -297,7 +243,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/activeproject.
+Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/active_project.
 
 ## License
 

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.
@@ -88,11 +85,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 +104,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.
@@ -122,13 +118,6 @@ module ActiveProject
       def connected?
         raise NotImplementedError, "#{self.class.name} must implement #connected?"
       end
-
-
-      # Placeholder comments for data structures (to be defined elsewhere)
-      # Example:
-      # Project = Struct.new(:id, :key, :name, :adapter_source, keyword_init: true)
-      # Issue = Struct.new(:id, :key, :title, :description, :status, :assignee, :project_id, :adapter_source, keyword_init: true)
-      # Comment = Struct.new(:id, :body, :author, :created_at, :issue_id, :adapter_source, keyword_init: true)
     end
   end
 end

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,139 @@
+# 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.
+        # @return [Array<ActiveProject::Resources::Issue>] An array of issue resources.
+        def list_issues(project_id, options = {})
+          all_todos = []
+          todolist_id = options[:todolist_id]
+
+          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"
+
+          loop do
+            response = @connection.get(path)
+            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{^/}, "")
+          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
+      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