activeproject 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f3323a59c15ce296050ec1c7b231416d2cac1aa6f78fe133c8d7d2fd3ebb639
+  data.tar.gz: 0f60e5b29d28e3adca3ce7e26df63929ed3c0d4b898887213823cd284efa365a
+SHA512:
+  metadata.gz: 756f9f83b0f443ceb6d426514d79c7c7cca5c8f6b410ab6fbad9469426354735d706d0b00be102a1f36ec4dcb4a7ee04d8b110c6aaaeda3ac8ccce2b61695623
+  data.tar.gz: 5397faf8bae3c5fe4ab86a98360de55c92237270806ac3372cdf7cff08742fa857ccff9f4a139998116ce366cd321df5afab6d81368a78970822de853d43c68c

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,304 @@
+# ActiveProject Gem
+
+A standardized Ruby interface for multiple project management APIs (Jira, Basecamp, Trello, etc.).
+
+## 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.
+
+## 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:
+
+*   **Normalized Data Models:** Common Ruby objects for core concepts like `Project`, `Task` (Issue/Card/To-do), `Comment`, and `User`.
+*   **Standardized Operations:** Consistent methods for creating, reading, updating, and transitioning tasks (e.g., `task.close!`, `task.reopen!`).
+*   **Unified Error Handling:** A common set of exceptions (`AuthenticationError`, `NotFoundError`, `RateLimitError`, etc.) regardless of the underlying platform.
+
+## Supported Platforms
+
+The initial focus is on integrating with platforms primarily via their **REST APIs**:
+
+*   **Jira (Cloud & Server):** REST API (v2/v3)
+*   **Basecamp (v3+):** REST API
+*   **Trello:** REST API
+
+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.
+
+## 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`).
+
+## 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.
+
+## 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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activeproject'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install activeproject
+```
+
+## Usage
+
+### Configuration
+
+Configure the adapters in an initializer (e.g., `config/initializers/active_project.rb`):
+
+```ruby
+ActiveProject.configure do |config|
+  # Configure Jira Adapter
+  config.add_adapter(:jira,
+    site_url: ENV.fetch('JIRA_SITE_URL'),
+    username: ENV.fetch('JIRA_USERNAME'), # Your Jira email
+    api_token: ENV.fetch('JIRA_API_TOKEN')
+  )
+
+
+  # Configure Basecamp Adapter
+  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: '...')
+end
+```
+
+### Basic Usage (Jira Example)
+
+```ruby
+# Get the configured Jira adapter instance
+jira_adapter = ActiveProject.adapter(:jira)
+
+begin
+  # List projects
+  projects = jira_adapter.list_projects
+  puts "Found #{projects.count} projects."
+  first_project = projects.first
+
+  if first_project
+    puts "Listing issues for project: #{first_project.key}"
+    # List issues in the first project
+    issues = jira_adapter.list_issues(first_project.key, max_results: 5)
+    puts "- Found #{issues.count} issues (showing max 5)."
+
+    # Find a specific issue (replace 'PROJ-1' with a valid key)
+    # issue_key_to_find = 'PROJ-1'
+    # issue = jira_adapter.find_issue(issue_key_to_find)
+    # puts "- Found issue: #{issue.key} - #{issue.title}"
+
+    # Create a new issue
+    puts "Creating a new issue..."
+    new_issue_attributes = {
+      project: { key: first_project.key },
+      summary: "New task from ActiveProject Gem #{Time.now}",
+      issue_type: { name: 'Task' }, # Ensure 'Task' is a valid issue type name
+      description: "This issue was created via the ActiveProject gem."
+    }
+    created_issue = jira_adapter.create_issue(first_project.key, new_issue_attributes)
+    puts "- Created issue: #{created_issue.key} - #{created_issue.title}"
+
+    # Update the issue
+    puts "Updating issue #{created_issue.key}..."
+    updated_issue = jira_adapter.update_issue(created_issue.key, { summary: "[Updated] #{created_issue.title}" })
+    puts "- Updated summary: #{updated_issue.title}"
+
+    # Add a comment
+    puts "Adding comment to issue #{updated_issue.key}..."
+    comment = jira_adapter.add_comment(updated_issue.key, "This is a comment added via the ActiveProject gem.")
+    puts "- Comment added with ID: #{comment.id}"
+  end
+
+rescue ActiveProject::AuthenticationError => e
+  puts "Error: Jira 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} (Details: #{e.errors})"
+rescue ActiveProject::ApiError => e
+  puts "Error: Jira API Error (#{e.status_code}) - #{e.message}"
+rescue => e
+  puts "An unexpected error occurred: #{e.message}"
+end
+```
+
+### Basic Usage (Basecamp Example)
+
+```ruby
+# Get the configured Basecamp adapter instance
+basecamp_config = ActiveProject.configuration.adapter_config(:basecamp)
+basecamp_adapter = ActiveProject::Adapters::BasecampAdapter.new(**basecamp_config)
+
+begin
+  # List projects
+  projects = basecamp_adapter.list_projects
+  puts "Found #{projects.count} Basecamp projects."
+  first_project = projects.first
+
+  if first_project
+    puts "Listing issues (To-dos) for project: #{first_project.name} (ID: #{first_project.id})"
+    # List issues (To-dos) in the first project
+    # Note: This lists across all to-do lists in the project
+    issues = basecamp_adapter.list_issues(first_project.id)
+    puts "- Found #{issues.count} To-dos."
+
+    # Create a new issue (To-do)
+    # IMPORTANT: You need a valid todolist_id for the target project.
+    # You might need another API call to find a todolist_id first.
+    # todolist_id_for_test = 1234567 # Replace with a real ID
+    # puts "Creating a new To-do..."
+    # new_issue_attributes = {
+    #   todolist_id: todolist_id_for_test,
+    #   title: "New BC To-do from ActiveProject Gem #{Time.now}",
+    #   description: "<em>HTML description</em> for the to-do."
+    # }
+    # created_issue = basecamp_adapter.create_issue(first_project.id, new_issue_attributes)
+    # puts "- Created To-do: #{created_issue.id} - #{created_issue.title}"
+
+    # --- Operations requiring project_id context (Currently raise NotImplementedError) ---
+    # puts "Finding, updating, and commenting require project_id context and are currently not directly usable via the base interface."
+    #
+    # # Find a specific issue (To-do) - Requires project_id context
+    # # todo_id_to_find = created_issue.id
+    # # issue = basecamp_adapter.find_issue(todo_id_to_find) # Raises NotImplementedError
+    #
+    # # Update the issue (To-do) - Requires project_id context
+    # # updated_issue = basecamp_adapter.update_issue(created_issue.id, { title: "[Updated] #{created_issue.title}" }) # Raises NotImplementedError
+    #
+    # # Add a comment - Requires project_id context
+    # # comment = basecamp_adapter.add_comment(created_issue.id, "This is an <b>HTML</b> comment.") # Raises NotImplementedError
+
+  end
+
+rescue ActiveProject::AuthenticationError => e
+  puts "Error: Basecamp Authentication Failed - #{e.message}"
+rescue ActiveProject::NotFoundError => e
+  puts "Error: Basecamp Resource Not Found - #{e.message}"
+rescue ActiveProject::ValidationError => e
+  puts "Error: Basecamp Validation Failed - #{e.message}"
+rescue ActiveProject::RateLimitError => e
+  puts "Error: Basecamp Rate Limit Exceeded - #{e.message}"
+rescue ActiveProject::ApiError => e
+  puts "Error: Basecamp API Error (#{e.status_code}) - #{e.message}"
+rescue NotImplementedError => e
+  puts "Error: Method requires project_id context which is not yet implemented: #{e.message}"
+rescue => e
+  puts "An unexpected error occurred: #{e.message}"
+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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `lib/active_project/version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [RubyGems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/activeproject.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/active_project/adapters/base.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+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
+      # Lists projects accessible by the configured credentials.
+      # @return [Array<ActiveProject::Project>]
+      def list_projects
+        raise NotImplementedError, "#{self.class.name} must implement #list_projects"
+      end
+
+      # Finds a specific project by its ID or key.
+      # @param id [String, Integer] The ID or key of the project.
+      # @return [ActiveProject::Project, nil] The project object or nil if not found.
+      def find_project(id)
+        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.
+      def create_project(attributes)
+        raise NotImplementedError, "#{self.class.name} must implement #create_project"
+      end
+
+      # Creates a new list/container within a project (e.g., Trello List, Basecamp Todolist).
+      # Not applicable to all platforms (e.g., Jira statuses are managed differently).
+      # @param project_id [String, Integer] The ID or key of the parent project.
+      # @param attributes [Hash] List attributes (platform-specific, e.g., :name).
+      # @return [Hash] A hash representing the created list (platform-specific structure).
+      def create_list(project_id, attributes)
+        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.
+      # @raise [NotImplementedError] if deletion is not supported or implemented.
+      def delete_project(project_id)
+        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.
+      # @return [Array<ActiveProject::Issue>]
+      def list_issues(project_id, options = {})
+        raise NotImplementedError, "#{self.class.name} must implement #list_issues"
+      end
+
+      # 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).
+      # @return [ActiveProject::Issue, nil] The issue object or nil if not found.
+      def find_issue(id, context = {})
+        raise NotImplementedError, "#{self.class.name} must implement #find_issue"
+      end
+
+      # Creates a new issue.
+      # @param project_id [String, Integer] The ID or key of the project to create the issue in.
+      # @param attributes [Hash] Issue attributes (e.g., title, description).
+      # @return [ActiveProject::Issue] The created issue object.
+      def create_issue(project_id, attributes)
+        raise NotImplementedError, "#{self.class.name} must implement #create_issue"
+      end
+
+      # 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).
+      # @return [ActiveProject::Issue] The updated issue object.
+      def update_issue(id, attributes, context = {})
+        raise NotImplementedError, "#{self.class.name} must implement #update_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.
+      # @param context [Hash] Optional context hash (e.g., { project_id: '...' } for Basecamp).
+      # @return [ActiveProject::Comment] The created comment object.
+      def add_comment(issue_id, comment_body, context = {})
+        raise NotImplementedError, "#{self.class.name} must implement #add_comment"
+      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
+      end
+
+      # Parses an incoming webhook payload into a standardized WebhookEvent struct.
+      # @param request_body [String] The raw request body.
+      # @param headers [Hash] Optional hash of request headers (may be needed for event type detection).
+      # @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"
+      end
+
+
+      # Retrieves details for the currently authenticated user.
+      # @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
+        raise NotImplementedError, "#{self.class.name} must implement #get_current_user"
+      end
+
+      # Checks if the adapter can successfully authenticate and connect to the service.
+      # Typically calls #get_current_user internally and catches authentication errors.
+      # @return [Boolean] true if connection is successful, false otherwise.
+      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