activeproject 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fc9c393c3294c98f99863d698a7288077f6e71977e868c3a2ed0c2a5a5f7cbc
-  data.tar.gz: ff6f35f9cb6f58529be940efddb58d84f60490ee0bf02d1a6aba5f4e655dca51
+  metadata.gz: b9726d3cbaf8990833d420df514aeb0e7f283bc443756406f1600e95e73a3f79
+  data.tar.gz: f641d36b536206152d300ccc7f054a6ebe0768737eb2a6d658c45a044edd5938
 SHA512:
-  metadata.gz: 251021a9cbb4f3e0556092d7e8667b84324fcacbfee601683a3fadf3822b5a67b9a2c4b68744648d49a892c9690b99600879e16a5132d32ceac8d6177dc9cb60
-  data.tar.gz: 72a0056a416007bcc6abcfde009ec26674a37b6fe1864a01f7d9f01a13c8059adba6cf44208657e442170db5dc7fcdebfff6c0b7dee1d36b06f8dcfb8465ea28
+  metadata.gz: b86037bbf5ba508e1c7544bdd8aa5787db7a7b340c211029dcb7b4348a45b313b13a8d8e16e90ef083c86a291c332465efafe4e9079a4f8015ff3a4c14850786
+  data.tar.gz: 4dd7f59b51e515dae0a57299841573343983160a030adc62c146b9ad8858be262c249cb6b8f2a58e81c8241559a943263bf0b15dc5f31c1b35a86c8604eb6d5e

data/README.md

@@ -1,50 +1,68 @@
 # ActiveProject Gem
 
-A standardized Ruby interface for multiple project management APIs (Jira, Basecamp, Trello, etc.).
+A standardized Ruby interface for multiple project-management APIs
+(Jira, Basecamp, Trello, GitHub Projects, …).
 
 ## Problem
 
-Integrating with various project management platforms like Jira, Basecamp, and Trello often requires writing separate, complex clients for each API. Developers face challenges in handling different authentication methods, error formats, data structures, and workflow concepts across these platforms.
+Every platform—Jira, Basecamp, Trello, GitHub—ships its **own** authentication flow, error vocabulary, data model, and workflow quirks.
+Teams end up maintaining a grab-bag of fragile, bespoke clients.
 
 ## Solution
 
-The ActiveProject gem aims to solve this by providing a unified, opinionated interface built on the **Adapter pattern**. It abstracts away the complexities of individual APIs, offering:
+ActiveProject wraps those APIs behind a single, opinionated interface:
 
-*   **Normalized Data Models:** Common Ruby objects for core concepts like `Project`, `Issue` (Issue/Task/Card/To-do), `Comment`, and `User`.
-*   **Standardized Operations:** Consistent methods for creating, reading, updating, and transitioning issues (e.g., `issue.close!`, `issue.reopen!`).
-*   **Unified Error Handling:** A common set of exceptions (`AuthenticationError`, `NotFoundError`, `RateLimitError`, etc.) regardless of the underlying platform.
-*   **Co-operative Concurrency:** Optional fiber-based I/O (powered by the [`async`](https://github.com/socketry/async) ecosystem) for bulk operations without threads.
+| Feature | What you get |
+|---------|--------------|
+| **Normalized models** | `Project`, `Issue` (Task/Card/To-do), `Comment`, `User`—same Ruby objects everywhere. |
+| **Standard CRUD** | `issue.close!`, `issue.reopen!`, `project.list_issues`, etc. |
+| **Unified errors** | `AuthenticationError`, `NotFoundError`, `RateLimitError`, … regardless of the backend. |
+| **Co-operative concurrency** | Fiber-based I/O (via [`async`](https://github.com/socketry/async)) for painless parallel fan-out. |
 
-## Supported Platforms
 
-The initial focus is on integrating with platforms primarily via their **REST APIs**:
+## Supported Platforms (initial wave)
 
-*   **Jira (Cloud & Server):** REST API (v3)
-*   **Basecamp (v3+):** REST API
-*   **Trello:** REST API
+| Platform                  | API        | Notes                        |
+|---------------------------|------------|------------------------------|
+| **Jira** (Cloud & Server) | REST v3    | Full issue & project support |
+| **Basecamp**              | REST v3+   | Maps To-dos ↔ Issues         |
+| **Trello**                | REST       | Cards ↔ Issues               |
+| **GitHub Projects V2**    | GraphQL v4 |                              |
+| **GitHub**                | REST v3    | Issues and repositories      |
 
-Future integrations might include platforms like Asana (REST), Monday.com (GraphQL), and Linear (GraphQL). For GraphQL-based APIs, the adapter will encapsulate the query logic, maintaining a consistent interface for the gem user.
+_Planned next_: Asana, Monday.com, Linear, etc.
 
 ## Core Concepts
 
-*   **Project:** Represents a Jira Project, Basecamp Project, or Trello Board.
-*   **Task:** A unified representation of a Jira Issue, Basecamp To-do, or Trello Card. Includes normalized fields like `title`, `description`, `assignees`, `status`, and `priority`.
-*   **Status Normalization:** Maps platform-specific statuses (Jira statuses, Basecamp completion, Trello lists) to a common set like `:open`, `:in_progress`, `:closed`.
-*   **Priority Normalization:** Maps priorities (where available, like in Jira) to a standard scale (e.g., `:low`, `:medium`, `:high`).
+* **Project** – Jira Project, Basecamp Project, Trello Board, GitHub ProjectV2, or GitHub Repository.
+* **Issue** – Unified wrapper around Jira Issue, Basecamp To-do, Trello Card, GitHub Issue/PR.
+  *GitHub DraftIssues intentionally omitted for now.*
+* **Status** – Normalized to `:open`, `:in_progress`, `:blocked`, `:on_hold`, `:closed`.
+* **Priority** – Normalized to `:low`, `:medium`, `:high` (where supported).
+
+---
 
 ## Architecture
 
-The gem uses an **Adapter pattern**, with specific adapters (`Adapters::JiraAdapter`, `Adapters::BasecampAdapter`, etc.) implementing a common interface. This allows for easy extension to new platforms.
+```
+
+ActiveProject
+└── Adapters
+  ├── JiraAdapter
+  ├── BasecampAdapter
+  ├── TrelloAdapter
+  ├── GithubProjectAdapter
+  └── GithubAdapter
+
+````
+Add a new platform by subclassing and conforming to the common contract.
+---
 
 ## Planned Features
 
-*   CRUD operations for Projects and Tasks.
-*   Unified status transitions.
-*   Comment management.
-*   Standardized error handling and reporting.
-*   Webhook support for real-time updates from platforms.
-*   Configuration management for API credentials.
-*   Utilization of **Mermaid diagrams** to visualize workflows and integration logic within documentation.
+* Webhook helpers for real-time updates
+* Centralised credential/config store
+* Mermaid diagrams for docs & SDK flow-charts
 
 ## Installation
 
@@ -74,31 +92,29 @@ Configure multiple adapters, optionally with named instances (default is `:prima
 
 ```ruby
 ActiveProject.configure do |config|
-  # Primary Jira instance (default name :primary)
-  config.add_adapter(:jira,
-    site_url: ENV.fetch('JIRA_SITE_URL'),
-    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')
-  )
-
-  # Basecamp primary instance
-  config.add_adapter(:basecamp,
-    account_id: ENV.fetch('BASECAMP_ACCOUNT_ID'),
-    access_token: ENV.fetch('BASECAMP_ACCESS_TOKEN')
-  )
-
-  # Trello primary instance
-  config.add_adapter(:trello,
-    key: ENV.fetch('TRELLO_KEY'),
-    token: ENV.fetch('TRELLO_TOKEN')
-  )
+  config.add_adapter :jira,
+    site_url:  ENV["JIRA_SITE_URL"],
+    username:  ENV["JIRA_USERNAME"],
+    api_token: ENV["JIRA_API_TOKEN"]
+
+  config.add_adapter :basecamp,
+    account_id:   ENV["BASECAMP_ACCOUNT_ID"],
+    access_token: ENV["BASECAMP_ACCESS_TOKEN"]
+
+  config.add_adapter :trello,
+    key:   ENV["TRELLO_KEY"],
+    token: ENV["TRELLO_TOKEN"]
+
+  # GitHub Projects – real Issues/PRs only
+  config.add_adapter :github_project,
+    access_token: ENV["GITHUB_TOKEN"]
+
+  # GitHub primary instance
+  config.add_adapter :github,
+    owner: ENV["GITHUB_OWNER"],
+    repo: ENV["GITHUB_REPO"],
+    access_token: ENV["GITHUB_ACCESS_TOKEN"],
+    webhook_secret: ENV["GITHUB_WEBHOOK_SECRET"]
 end
 ```
 
@@ -111,6 +127,8 @@ 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
+github = ActiveProject.adapter(:github) # defaults to :primary
+github_project = ActiveProject.adapter(:github_project) # defaults to :primary
 ```
 
 ### Basic Usage (Jira Example)
@@ -175,8 +193,7 @@ end
 
 ```ruby
 # Get the configured Basecamp adapter instance
-basecamp_config = ActiveProject.configuration.adapter_config(:basecamp)
-basecamp_adapter = ActiveProject::Adapters::BasecampAdapter.new(**basecamp_config)
+basecamp_adapter = ActiveProject.adapter(:basecamp)
 
 begin
   # List projects
@@ -238,15 +255,13 @@ end
 
 ## Asynchronous I/O
 
-ActiveProject ships with `async-http` under the hood.  
+ActiveProject ships with `async-http` under the hood.
 Enable the non-blocking adapter by setting an ENV var **before** your process boots:
 
 ```bash
 AP_DEFAULT_ADAPTER=async_http
 ```
 
-### Parallel fan-out example
-
 ```ruby
 ActiveProject::Async.run do |task|
   jira    = ActiveProject.adapter(:jira)
@@ -286,6 +301,137 @@ If another gem (e.g. Falcon) already set a scheduler, ActiveProject detects it a
 
 ---
 
+### Basic Usage (GitHub Example)
+
+```ruby
+# Get the configured GitHub adapter instance
+github_adapter = ActiveProject.adapter(:github)
+
+begin
+  # With GitHub adapter, a repository is treated as a project.
+  # The adapter is configured for a specific repository.
+
+  # List projects (will return the configured repository)
+  projects = github_adapter.list_projects
+  puts "Found #{projects.count} GitHub repository."
+  repo = projects.first
+
+  if repo
+    puts "Working with repository: #{repo.key} (#{repo.name})"
+
+    # List issues in the repository
+    issues = github_adapter.list_issues(repo.key)
+    puts "- Found #{issues.count} issues."
+
+    # Find a specific issue (replace '1' with a valid issue number)
+    # issue_number = 1
+    # issue = github_adapter.find_issue(issue_number.to_s)
+    # puts "- Found issue: ##{issue.key} - #{issue.title}"
+
+    # Create a new issue
+    puts "Creating a new issue..."
+    new_issue_attributes = {
+      title: "New issue from ActiveProject Gem #{Time.now}",
+      description: "This issue was created via the ActiveProject gem.",
+      assignees: [{ name: "username" }]  # Optional: Provide GitHub usernames for assignees
+    }
+    created_issue = github_adapter.create_issue(repo.key, new_issue_attributes)
+    puts "- Created issue: ##{created_issue.key} - #{created_issue.title}"
+
+    # Update the issue
+    puts "Updating issue ##{created_issue.key}..."
+    updated_issue = github_adapter.update_issue(created_issue.key, { title: "[Updated] #{created_issue.title}" })
+    puts "- Updated title: #{updated_issue.title}"
+
+    # Add a comment
+    puts "Adding comment to issue ##{updated_issue.key}..."
+    comment = github_adapter.add_comment(updated_issue.key, "This is a comment added via the ActiveProject gem.")
+    puts "- Comment added with ID: #{comment.id}"
+
+    # Close the issue
+    puts "Closing issue ##{updated_issue.key}..."
+    closed_issue = github_adapter.update_issue(updated_issue.key, { state: "closed" })
+    puts "- Issue closed, status: #{closed_issue.status}"
+  end
+
+rescue ActiveProject::AuthenticationError => e
+  puts "Error: GitHub Authentication Failed - #{e.message}"
+rescue ActiveProject::NotFoundError => e
+  puts "Error: Resource Not Found - #{e.message}"
+rescue ActiveProject::ValidationError => e
+  puts "Error: Validation Failed - #{e.message}"
+rescue ActiveProject::RateLimitError => e
+  puts "Error: GitHub Rate Limit Exceeded - #{e.message}"
+rescue ActiveProject::ApiError => e
+  puts "Error: GitHub API Error (#{e.status_code}) - #{e.message}"
+rescue => e
+  puts "An unexpected error occurred: #{e.message}"
+end
+```
+
+### Webhook Support (GitHub Example)
+
+The GitHub adapter includes support for processing GitHub webhooks, which allows you to receive real-time events when issues are created, updated, commented on, etc.
+
+```ruby
+# Configure the adapter with a webhook secret (same secret used in GitHub webhook settings)
+ActiveProject.configure do |config|
+  config.add_adapter(:github,
+    owner: ENV.fetch('GITHUB_OWNER'),
+    repo: ENV.fetch('GITHUB_REPO'),
+    access_token: ENV.fetch('GITHUB_ACCESS_TOKEN'),
+    webhook_secret: ENV.fetch('GITHUB_WEBHOOK_SECRET', nil)
+  )
+end
+
+# In your webhook endpoint (e.g., in a Rails controller)
+def github_webhook
+  adapter = ActiveProject.adapter(:github)
+
+  # Get the raw request body and signature header
+  request_body = request.raw_post
+  signature = request.headers['X-Hub-Signature-256']
+
+  # Verify the webhook signature (if webhook_secret is configured)
+  if adapter.verify_webhook_signature(request_body, signature)
+    # Parse the webhook payload into a standardized WebhookEvent
+    event_headers = {
+      'X-GitHub-Event' => request.headers['X-GitHub-Event'],
+      'X-GitHub-Delivery' => request.headers['X-GitHub-Delivery']
+    }
+
+    webhook_event = adapter.parse_webhook(request_body, event_headers)
+
+    if webhook_event
+      # Process different event types
+      case webhook_event.type
+      when :issue_created
+        issue = webhook_event.data[:issue]
+        puts "New issue created: ##{issue.key} - #{issue.title}"
+
+      when :issue_updated, :issue_closed, :issue_reopened
+        issue = webhook_event.data[:issue]
+        puts "Issue ##{issue.key} was #{webhook_event.type.to_s.sub('issue_', '')}"
+
+      when :comment_created
+        comment = webhook_event.data[:comment]
+        issue = webhook_event.data[:issue]
+        puts "New comment on issue ##{issue.key}: #{comment.body.truncate(50)}"
+      end
+
+      # The webhook was successfully processed
+      head :ok
+    else
+      # The webhook payload couldn't be parsed
+      head :unprocessable_entity
+    end
+  else
+    # The webhook signature verification failed
+    head :forbidden
+  end
+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.

data/lib/active_project/adapters/base.rb

@@ -1,10 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "../status_mapper"
+
 module ActiveProject
   module Adapters
     # Base abstract class defining the interface for all adapters.
     # Concrete adapters should inherit from this class and implement its abstract methods.
     class Base
+      include ErrorMapper
+
+      # ─────────────────── Central HTTP-status → exception map ────────────
+      rescue_status 401..403, with: ActiveProject::AuthenticationError
+      rescue_status 404, with: ActiveProject::NotFoundError
+      rescue_status 429, with: ActiveProject::RateLimitError
+      rescue_status 400, 422, with: ActiveProject::ValidationError
+
+      attr_reader :config
+
+      def initialize(config:)
+        @config = config
+        @status_mapper = StatusMapper.from_config(adapter_type, config)
+      end
+
       # Lists projects accessible by the configured credentials.
       # @return [Array<ActiveProject::Project>]
       def list_projects
@@ -52,8 +69,13 @@ module ActiveProject
 
       # Finds a specific issue by its ID or key.
       # @param id [String, Integer] The ID or key of the issue.
-      # @param context [Hash] Optional context hash (e.g., { project_id: '...' } for Basecamp).
+      # @param context [Hash] Optional context hash. Platform-specific requirements:
+      #   - Basecamp: REQUIRES { project_id: '...' }
+      #   - Jira: Optional { fields: '...' }
+      #   - Trello: Optional { fields: '...' }
+      #   - GitHub: Ignored
       # @return [ActiveProject::Issue, nil] The issue object or nil if not found.
+      # @raise [ArgumentError] if required context is missing (platform-specific).
       def find_issue(id, context = {})
         raise NotImplementedError, "#{self.class.name} must implement #find_issue"
       end
@@ -69,14 +91,30 @@ module ActiveProject
       # Updates an existing issue.
       # @param id [String, Integer] The ID or key of the issue to update.
       # @param attributes [Hash] Issue attributes to update.
-      # @param context [Hash] Optional context hash (e.g., { project_id: '...' } for Basecamp).
+      # @param context [Hash] Optional context hash. Platform-specific requirements:
+      #   - Basecamp: REQUIRES { project_id: '...' }
+      #   - Jira: Optional { fields: '...' }
+      #   - Trello: Optional { fields: '...' }
+      #   - GitHub: Uses different signature: update_issue(project_id, item_id, attrs)
       # @return [ActiveProject::Issue] The updated issue object.
+      # @raise [ArgumentError] if required context is missing (platform-specific).
+      # @note GitHub adapter overrides this with update_issue(project_id, item_id, attrs)
+      #   due to GraphQL API requirements for project-specific field operations.
       def update_issue(id, attributes, context = {})
         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
+      # Deletes an issue from a project.
+      # @param id [String, Integer] The ID or key of the issue to delete.
+      # @param context [Hash] Optional context hash. Platform-specific requirements:
+      #   - Basecamp: REQUIRES { project_id: '...' }
+      #   - Jira: Optional { delete_subtasks: true/false }
+      #   - Trello: Ignored
+      #   - GitHub: Uses different signature: delete_issue(project_id, item_id)
+      # @return [Boolean] true if deletion was successful.
+      # @raise [ArgumentError] if required context is missing (platform-specific).
+      # @note GitHub adapter overrides this with delete_issue(project_id, item_id)
+      #   due to GraphQL API requirements.
       def delete_issue(id, context = {})
         raise NotImplementedError, "The #{self.class.name} adapter does not implement delete_issue"
       end
@@ -84,21 +122,79 @@ module ActiveProject
       # 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.
-      # @param context [Hash] Optional context hash (e.g., { project_id: '...' } for Basecamp).
+      # @param context [Hash] Optional context hash. Platform-specific requirements:
+      #   - Basecamp: REQUIRES { project_id: '...' }
+      #   - Jira: Ignored
+      #   - Trello: Ignored
+      #   - GitHub: Optional { content_node_id: '...' } for optimization
       # @return [ActiveProject::Comment] The created comment object.
+      # @raise [ArgumentError] if required context is missing (platform-specific).
       def add_comment(issue_id, comment_body, context = {})
         raise NotImplementedError, "#{self.class.name} must implement #add_comment"
       end
 
+      # Updates an existing comment.
+      # @param comment_id [String, Integer] The ID of the comment to update.
+      # @param body [String] The new comment body text.
+      # @param context [Hash] Optional context hash. Platform-specific requirements:
+      #   - Basecamp: REQUIRES { project_id: '...' }
+      #   - Jira: REQUIRES { issue_id: '...' }
+      #   - Trello: Ignored
+      #   - GitHub: Ignored
+      # @return [ActiveProject::Comment] The updated comment object.
+      # @raise [NotImplementedError] if the adapter does not support comment updates.
+      def update_comment(comment_id, body, context = {})
+        raise NotImplementedError, "#{self.class.name} does not support #update_comment"
+      end
+
+      # Deletes a comment.
+      # @param comment_id [String, Integer] The ID of the comment to delete.
+      # @param context [Hash] Optional context hash. Platform-specific requirements:
+      #   - Basecamp: REQUIRES { project_id: '...' }
+      #   - Jira: REQUIRES { issue_id: '...' }
+      #   - Trello: Ignored
+      #   - GitHub: Ignored
+      # @return [Boolean] true if deletion was successful.
+      # @raise [NotImplementedError] if the adapter does not support comment deletion.
+      def delete_comment(comment_id, context = {})
+        raise NotImplementedError, "#{self.class.name} does not support #delete_comment"
+      end
+
+      # Checks if the adapter supports webhook processing.
+      # @return [Boolean] true if the adapter can process webhooks
+      def supports_webhooks?
+        respond_to?(:parse_webhook, true) &&
+          !method(:parse_webhook).source_location.nil? &&
+          method(:parse_webhook).source_location[0] != __FILE__
+      end
+
+      # Returns the webhook type identifier for this adapter class.
+      # This distinguishes between different adapter types for the same platform.
+      # @return [Symbol] The webhook type (e.g., :github_repo, :github_project, :jira, :basecamp)
+      def self.webhook_type
+        # Default implementation extracts from class name
+        # GithubRepoAdapter -> :github_repo, BasecampAdapter -> :basecamp
+        class_name = name.split("::").last
+        class_name.gsub(/Adapter$/, "").gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+      end
+
+      # Instance method that delegates to class method
+      # @return [Symbol] The webhook type
+      def webhook_type
+        self.class.webhook_type
+      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').
-      # @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)
-        # Default implementation assumes no verification needed or supported.
-        # Adapters supporting verification should override this.
-        true
+      # @param request_body [String] The raw request body.
+      # @param signature_header [String] The value of the platform-specific signature header.
+      # @param webhook_secret [String] Optional webhook secret for verification.
+      # @return [Boolean] true if the signature is valid or verification is not supported, false otherwise.
+      # @note Override this method in adapter subclasses to implement platform-specific verification.
+      def verify_webhook_signature(request_body, signature_header, webhook_secret: nil)
+        # Default implementation assumes no verification needed.
+        # Adapters supporting verification should override this method.
+        return true unless supports_webhooks? # Allow non-webhook flows by default
+        false # Adapters must override this method to implement verification
       end
 
       # Parses an incoming webhook payload into a standardized WebhookEvent struct.
@@ -107,7 +203,9 @@ module ActiveProject
       # @return [ActiveProject::WebhookEvent, nil] The parsed event object or nil if the payload is irrelevant/unparseable.
       # @raise [NotImplementedError] if webhook parsing is not implemented for the adapter.
       def parse_webhook(request_body, headers = {})
-        raise NotImplementedError, "#{self.class.name} must implement #parse_webhook"
+        raise NotImplementedError,
+              "#{self.class.name} does not support webhook parsing. " \
+              "Webhook support is optional. Check #supports_webhooks? before calling this method."
       end
 
       # Retrieves details for the currently authenticated user.
@@ -124,6 +222,48 @@ module ActiveProject
       def connected?
         raise NotImplementedError, "#{self.class.name} must implement #connected?"
       end
+
+      # Adapters that do **not** support a custom “status” field can simply rely
+      # on this default implementation.  Adapters that _do_ care (e.g. the
+      # GitHub project adapter which knows its single-select options) already
+      # override it.
+      #
+      # @return [Boolean] _true_ if the symbol is safe to pass through.
+      def status_known?(project_id, status_sym)
+        @status_mapper.status_known?(status_sym, project_id: project_id)
+      end
+
+      # Returns all valid statuses for the given project context.
+      # @param project_id [String, Integer] The project context
+      # @return [Array<Symbol>] Array of valid status symbols
+      def valid_statuses(project_id = nil)
+        @status_mapper.valid_statuses(project_id: project_id)
+      end
+
+      # Normalizes a platform-specific status to a standard symbol.
+      # @param platform_status [String, Symbol] Platform-specific status
+      # @param project_id [String, Integer] Optional project context
+      # @return [Symbol] Normalized status symbol
+      def normalize_status(platform_status, project_id: nil)
+        @status_mapper.normalize_status(platform_status, project_id: project_id)
+      end
+
+      # Converts a normalized status back to platform-specific format.
+      # @param normalized_status [Symbol] Normalized status symbol
+      # @param project_id [String, Integer] Optional project context
+      # @return [String, Symbol] Platform-specific status
+      def denormalize_status(normalized_status, project_id: nil)
+        @status_mapper.denormalize_status(normalized_status, project_id: project_id)
+      end
+
+      protected
+
+      # Returns the adapter type symbol for status mapping.
+      # Override in subclasses if the adapter type differs from class name pattern.
+      # @return [Symbol] The adapter type
+      def adapter_type
+        self.class.name.split("::").last.gsub("Adapter", "").downcase.to_sym
+      end
     end
   end
 end

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

@@ -21,6 +21,40 @@ module ActiveProject
           comment_data = make_request(:post, path, payload)
           map_comment_data(comment_data, todo_id.to_i)
         end
+
+        # Updates a comment on a To-do in Basecamp.
+        # @param comment_id [String, Integer] The ID of the comment.
+        # @param body [String] The new comment text (HTML).
+        # @param context [Hash] Required context: { project_id: '...' }.
+        # @return [ActiveProject::Resources::Comment] The updated comment resource.
+        def update_comment(comment_id, body, context = {})
+          project_id = context[:project_id]
+          unless project_id
+            raise ArgumentError,
+                  "Missing required context: :project_id must be provided for BasecampAdapter#update_comment"
+          end
+
+          path = "buckets/#{project_id}/comments/#{comment_id}.json"
+          payload = { content: body }.to_json
+          comment_data = make_request(:put, path, payload)
+          map_comment_data(comment_data, comment_data["parent"]&.dig("id"))
+        end
+
+        # Deletes a comment from a To-do in Basecamp.
+        # @param comment_id [String, Integer] The ID of the comment to delete.
+        # @param context [Hash] Required context: { project_id: '...' }.
+        # @return [Boolean] True if successfully deleted.
+        def delete_comment(comment_id, context = {})
+          project_id = context[:project_id]
+          unless project_id
+            raise ArgumentError,
+                  "Missing required context: :project_id must be provided for BasecampAdapter#delete_comment"
+          end
+
+          path = "buckets/#{project_id}/recordings/#{comment_id}/status/trashed.json"
+          make_request(:put, path)
+          true
+        end
       end
     end
   end

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

@@ -4,7 +4,7 @@ module ActiveProject
   module Adapters
     module Basecamp
       module Connection
-        include ActiveProject::Adapters::HttpClient
+        include Connections::Rest
         BASE_URL_TEMPLATE = "https://3.basecampapi.com/%<account_id>s/"
         # Initializes the Basecamp Adapter.
         # @param config [Configurations::BaseAdapterConfiguration] The configuration object for Basecamp.
@@ -15,38 +15,20 @@ module ActiveProject
           unless config.is_a?(ActiveProject::Configurations::BaseAdapterConfiguration)
             raise ArgumentError, "BasecampAdapter requires a BaseAdapterConfiguration object"
           end
-          @config = config
+
+          super(config: config)
 
           account_id   = @config.options.fetch(:account_id)
           access_token = @config.options.fetch(:access_token)
 
-          build_connection(
+          init_rest(
             base_url: format(BASE_URL_TEMPLATE, account_id: account_id),
             auth_middleware: ->(conn) { conn.request :authorization, :bearer, 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
+          return if account_id && !account_id.empty? && access_token && !access_token.empty?
 
-        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
+          raise ArgumentError, "BasecampAdapter configuration requires :account_id and :access_token"
         end
       end
     end