activeproject 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46d0e95fea9e696d7f35f2f8ad2cc32a82f9c068aaf834a9daa2650824650620
-  data.tar.gz: 709c98e0c3bab903db0447c7d53559c55e5c7c98cffc511a771c3b9f08cfa2fc
+  metadata.gz: 9fc9c393c3294c98f99863d698a7288077f6e71977e868c3a2ed0c2a5a5f7cbc
+  data.tar.gz: ff6f35f9cb6f58529be940efddb58d84f60490ee0bf02d1a6aba5f4e655dca51
 SHA512:
-  metadata.gz: 7fb8db4e4f952b10364e91727ebec93e6f0e65f6ebf7d5bd331dab77013bd3fc34d100f522a76d5f8d7014d947081a16fdee34535a6327cbabfe6bb74cbfc00b
-  data.tar.gz: 15231c9e5b94a103f21b643f219ffebf4747223f2662a410389ecbf142cc1f618c96384dd5314ba56d00afa6bdf4d0f81cfc0ba33bd580f2fa4999dae8a954eb
+  metadata.gz: 251021a9cbb4f3e0556092d7e8667b84324fcacbfee601683a3fadf3822b5a67b9a2c4b68744648d49a892c9690b99600879e16a5132d32ceac8d6177dc9cb60
+  data.tar.gz: 72a0056a416007bcc6abcfde009ec26674a37b6fe1864a01f7d9f01a13c8059adba6cf44208657e442170db5dc7fcdebfff6c0b7dee1d36b06f8dcfb8465ea28

data/README.md

@@ -10,9 +10,10 @@ Integrating with various project management platforms like Jira, Basecamp, and T
 
 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!`).
+*   **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.
 
 ## Supported Platforms
 
@@ -235,6 +236,56 @@ rescue => e
 end
 ```
 
+## Asynchronous I/O
+
+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)
+  boards  = %w[ACME DEV OPS]
+
+  tasks = boards.map do |key|
+    task.async { jira.list_issues(key, max_results: 100) }
+  end
+
+  issues = tasks.flat_map(&:wait)
+  puts "Fetched #{issues.size} issues in parallel."
+end
+```
+
+No threads, no Mutexes—just Ruby fibers.
+
+---
+
+## Rails auto-scheduler
+
+If your app runs on Rails, ActiveProject’s Railtie installs `Async::Scheduler` automatically **before Zeitwerk boots**.
+
+* Opt out per app:
+
+  ```ruby
+  # config/application.rb
+  config.active_project.use_async_scheduler = false
+  ```
+
+* …or per environment:
+
+  ```bash
+  AP_NO_ASYNC_SCHEDULER=1
+  ```
+
+If another gem (e.g. Falcon) already set a scheduler, ActiveProject detects it and does nothing.
+
+---
+
 ## 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

@@ -75,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.

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

@@ -4,6 +4,7 @@ module ActiveProject
   module Adapters
     module Basecamp
       module Connection
+        include ActiveProject::Adapters::HttpClient
         BASE_URL_TEMPLATE = "https://3.basecampapi.com/%<account_id>s/"
         # Initializes the Basecamp Adapter.
         # @param config [Configurations::BaseAdapterConfiguration] The configuration object for Basecamp.
@@ -14,11 +15,15 @@ module ActiveProject
           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]
+          account_id   = @config.options.fetch(:account_id)
+          access_token = @config.options.fetch(:access_token)
+
+          build_connection(
+            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"

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

@@ -6,11 +6,12 @@ module ActiveProject
       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.
+        # @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)
@@ -18,14 +19,16 @@ module ActiveProject
           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)
+            response = @connection.get(path, query)
             todos_data = begin
-              JSON.parse(response.body)
-            rescue StandardError
-              []
-            end
+                           JSON.parse(response.body)
+                         rescue StandardError
+                           []
+                         end
             break if todos_data.empty?
 
             todos_data.each do |todo_data|
@@ -37,6 +40,7 @@ module ActiveProject
             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
@@ -133,6 +137,21 @@ module ActiveProject
 
           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

data/lib/active_project/adapters/basecamp_adapter.rb

@@ -60,17 +60,8 @@ module ActiveProject
       # Initializes the Faraday connection object.
 
       # Helper method for making requests.
-      def make_request(method, path, body = nil, query_params = {})
-        full_path = path.start_with?("/") ? path[1..] : path
-
-        response = @connection.run_request(method, full_path, body, nil) do |req|
-          req.params.update(query_params) unless query_params.empty?
-        end
-        return nil if response.status == 204 # Handle No Content for POST/DELETE completion
-
-        JSON.parse(response.body) if response.body && !response.body.empty?
-      rescue Faraday::Error => e
-        handle_faraday_error(e)
+      def make_request(method, path, body = nil, query = {})
+        request(method, path, body: body, query: query)
       end
 
       # Handles Faraday errors.

data/lib/active_project/adapters/http_client.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module ActiveProject
+  module Adapters
+    module HttpClient
+      include Pagination
+      DEFAULT_HEADERS = {
+        "Content-Type" => "application/json",
+        "Accept"       => "application/json",
+        "User-Agent"   => -> { ActiveProject.user_agent }
+      }.freeze
+      RETRY_OPTS = { max: 5, interval: 0.5, backoff_factor: 2 }.freeze
+
+      def build_connection(base_url:, auth_middleware:, extra_headers: {})
+        @connection = Faraday.new(url: base_url) do |conn|
+          auth_middleware.call(conn)                 # <-- adapter-specific
+          conn.request  :retry, **RETRY_OPTS
+          conn.response :raise_error
+          default_adapter = ENV.fetch("AP_DEFAULT_ADAPTER", "net_http").to_sym
+          conn.adapter default_adapter
+          conn.headers.merge!(DEFAULT_HEADERS.transform_values { |v| v.respond_to?(:call) ? v.call : v })
+          conn.headers.merge!(extra_headers)
+          yield conn if block_given?                 # optional extra tweaks
+        end
+      end
+
+      def request(method, path, body: nil, query: nil, headers: {})
+        raise "HTTP connection not initialised" unless @connection
+
+        json_body = body.is_a?(String) ? body : (body ? JSON.generate(body) : nil)
+        response  = @connection.run_request(method, path, json_body, headers) do |req|
+          req.params.update(query) if query&.any?
+        end
+
+        return nil if response.status == 204 || response.body.to_s.empty?
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise translate_faraday_error(e)
+      rescue JSON::ParserError => e
+        raise ActiveProject::ApiError.new("Non-JSON response from #{path}",
+                                          original_error: e,
+                                          status_code: response&.status,
+                                          response_body: response&.body)
+      end
+
+      private
+
+      def translate_faraday_error(err)
+        status = err.response_status
+        body   = err.response_body.to_s
+        msg    = begin JSON.parse(body)["message"] rescue body end
+
+        case status
+        when 401, 403 then ActiveProject::AuthenticationError.new(msg)
+        when 404      then ActiveProject::NotFoundError.new(msg)
+        when 429      then ActiveProject::RateLimitError.new(msg)
+        when 400, 422 then ActiveProject::ValidationError.new(msg, status_code: status, response_body: body)
+        else
+          ActiveProject::ApiError.new("HTTP #{status || 'N/A'}: #{msg}",
+                                      original_error: err,
+                                      status_code: status,
+                                      response_body: body)
+        end
+      end
+    end
+  end
+end

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

@@ -1,45 +1,64 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module ActiveProject
   module Adapters
     module Jira
+      # Low-level HTTP concerns for JiraAdapter
       module Connection
-        # Initializes the Jira Adapter.
-        # @param config [Configurations::BaseAdapterConfiguration] The configuration object for Jira.
-        # @raise [ArgumentError] if required configuration options (:site_url, :username, :api_token) are missing.
+        include ActiveProject::Adapters::HttpClient
+
+        SERAPH_HEADER = "x-seraph-loginreason".freeze
+
+        # @param config [ActiveProject::Configurations::BaseAdapterConfiguration]
+        #   Must expose :site_url, :username, :api_token.
+        # @raise [ArgumentError] if required keys are missing.
         def initialize(config:)
           unless config.is_a?(ActiveProject::Configurations::BaseAdapterConfiguration)
             raise ArgumentError, "JiraAdapter requires a BaseAdapterConfiguration object"
           end
-
           @config = config
 
-          unless @config.options[:site_url] && !@config.options[:site_url].empty? &&
-                 @config.options[:username] && !@config.options[:username].empty? &&
-                 @config.options[:api_token] && !@config.options[:api_token].empty?
-            raise ArgumentError, "JiraAdapter configuration requires :site_url, :username, and :api_token"
-          end
+          # --- Build an absolute base URL ------------------------------------
+          raw_url  = @config.options.fetch(:site_url)
+          site_url = raw_url =~ %r{\Ahttps?://}i ? raw_url.dup : +"https://#{raw_url}"
+          site_url.chomp!("/")
+
+          username  = @config.options.fetch(:username)
+          api_token = @config.options.fetch(:api_token)
 
-          @connection = initialize_connection
+          build_connection(
+            base_url: site_url,
+            auth_middleware: ->(conn) do
+              # Faraday’s built-in basic-auth helper                               :contentReference[oaicite:0]{index=0}
+              conn.request :authorization, :basic, username, api_token
+            end
+          )
         end
 
-        private
-
-        # Initializes the Faraday connection object.
-        def initialize_connection
-          site_url = @config.options[:site_url].chomp("/")
-          username = @config.options[:username]
-          api_token = @config.options[:api_token]
-
-          Faraday.new(url: site_url) do |conn|
-            conn.request :authorization, :basic, username, api_token
-            conn.request :retry
-            # Important: Keep raise_error middleware *after* retry
-            # conn.response :raise_error # Defer raising error to handle_faraday_error
-            conn.headers["Content-Type"] = "application/json"
-            conn.headers["Accept"] = "application/json"
-            conn.headers["User-Agent"] = ActiveProject.user_agent
+        # --------------------------------------------------------------------
+        # Tiny wrapper around HttpClient#request that handles Jira quirks
+        # --------------------------------------------------------------------
+        #
+        # @param method [Symbol]  :get, :post, :put, :delete, …
+        # @param path   [String]  e.g. "/rest/api/3/issue/PROJ-1"
+        # @param body   [String, Hash, nil]
+        # @param query  [Hash,nil] additional query-string params
+        # @return [Hash, nil] parsed JSON response
+        #
+        # @raise [ActiveProject::AuthenticationError] if Jira signals
+        #   AUTHENTICATED_FAILED via X-Seraph-LoginReason header.
+        private def make_request(method, path, body = nil, query = nil)
+          data = request(method, path, body: body, query: query)
+
+          if @connection.headers[SERAPH_HEADER]&.include?("AUTHENTICATED_FAILED")
+            # Jira returns 200 + this header when credentials are wrong         :contentReference[oaicite:1]{index=1}
+            raise ActiveProject::AuthenticationError,
+                  "Jira authentication failed (#{SERAPH_HEADER}: AUTHENTICATED_FAILED)"
           end
+
+          data
         end
       end
     end

data/lib/active_project/adapters/jira/issues.rb

@@ -4,14 +4,17 @@ module ActiveProject
   module Adapters
     module Jira
       module Issues
+        DEFAULT_FIELDS = %w[summary description status assignee reporter created updated project issuetype duedate priority].freeze
+
         # Lists issues within a specific project, optionally filtered by JQL.
         # @param project_id_or_key [String, Integer] The ID or key of the project.
-        # @param options [Hash] Optional filtering/pagination options.
+        # @param options [Hash] Optional filtering/pagination options. Accepts :jql, :fields, :start_at, :max_results.
         # @return [Array<ActiveProject::Resources::Issue>]
         def list_issues(project_id_or_key, options = {})
           start_at = options.fetch(:start_at, 0)
           max_results = options.fetch(:max_results, 50)
           jql = options.fetch(:jql, "project = '#{project_id_or_key}' ORDER BY created DESC")
+          fields = options[:fields] || DEFAULT_FIELDS
 
           all_issues = []
           path = "/rest/api/3/search"
@@ -20,8 +23,7 @@ module ActiveProject
             jql: jql,
             startAt: start_at,
             maxResults: max_results,
-            fields: %w[summary description status assignee reporter created updated project
-                       issuetype duedate priority]
+            fields: fields
           }.to_json
 
           response_data = make_request(:post, path, payload)
@@ -36,11 +38,12 @@ module ActiveProject
 
         # Finds a specific issue by its ID or key using the V3 endpoint.
         # @param id_or_key [String, Integer] The ID or key of the issue.
-        # @param context [Hash] Optional context (ignored).
+        # @param context [Hash] Optional context. Accepts :fields for field selection.
         # @return [ActiveProject::Resources::Issue]
-        def find_issue(id_or_key, _context = {})
-          fields = "summary,description,status,assignee,reporter,created,updated,project,issuetype,duedate,priority"
-          path = "/rest/api/3/issue/#{id_or_key}?fields=#{fields}"
+        def find_issue(id_or_key, context = {})
+          fields = context[:fields] || DEFAULT_FIELDS
+          fields_param = fields.is_a?(Array) ? fields.join(",") : fields
+          path = "/rest/api/3/issue/#{id_or_key}?fields=#{fields_param}"
 
           issue_data = make_request(:get, path)
           map_issue_data(issue_data)
@@ -54,8 +57,8 @@ module ActiveProject
           path = "/rest/api/3/issue"
 
           unless attributes[:project].is_a?(Hash) && (attributes[:project][:id] || attributes[:project][:key]) &&
-                 attributes[:summary] && !attributes[:summary].empty? &&
-                 attributes[:issue_type] && (attributes[:issue_type][:id] || attributes[:issue_type][:name])
+            attributes[:summary] && !attributes[:summary].empty? &&
+            attributes[:issue_type] && (attributes[:issue_type][:id] || attributes[:issue_type][:name])
             raise ArgumentError,
                   "Missing required attributes for issue creation: :project (must be a Hash with id/key), :summary, :issue_type (with id/name)"
           end
@@ -83,6 +86,8 @@ module ActiveProject
 
           fields_payload[:priority] = attributes[:priority] if attributes.key?(:priority)
 
+          fields_payload[:parent] = attributes[:parent] if attributes.key?(:parent)
+
           payload = { fields: fields_payload }.to_json
           response_data = make_request(:post, path, payload)
 
@@ -92,9 +97,9 @@ module ActiveProject
         # Updates an existing issue in Jira using the V3 endpoint.
         # @param id_or_key [String, Integer] The ID or key of the issue to update.
         # @param attributes [Hash] Issue attributes to update (e.g., :summary, :description, :assignee_id, :due_on, :priority).
-        # @param context [Hash] Optional context (ignored).
+        # @param context [Hash] Optional context. Accepts :fields for field selection on return.
         # @return [ActiveProject::Resources::Issue]
-        def update_issue(id_or_key, attributes, _context = {})
+        def update_issue(id_or_key, attributes, context = {})
           path = "/rest/api/3/issue/#{id_or_key}"
 
           update_fields = {}
@@ -119,12 +124,25 @@ module ActiveProject
 
           update_fields[:priority] = attributes[:priority] if attributes.key?(:priority)
 
-          return find_issue(id_or_key) if update_fields.empty?
+          return find_issue(id_or_key, context) if update_fields.empty?
 
           payload = { fields: update_fields }.to_json
           make_request(:put, path, payload)
 
-          find_issue(id_or_key)
+          find_issue(id_or_key, context)
+        end
+
+        # Deletes an issue from Jira.
+        # @param id_or_key [String, Integer] The ID or key of the issue to delete.
+        # @param context [Hash] Optional context. Accepts :delete_subtasks to indicate whether subtasks should be deleted.
+        # @return [Boolean] True if successfully deleted.
+        def delete_issue(id_or_key, context = {})
+          delete_subtasks = context[:delete_subtasks] || false
+          path = "/rest/api/3/issue/#{id_or_key}"
+          query = { deleteSubtasks: delete_subtasks }
+
+          make_request(:delete, path, nil, query)
+          true
         end
       end
     end

data/lib/active_project/adapters/jira_adapter.rb

@@ -56,31 +56,6 @@ module ActiveProject
 
       # Initializes the Faraday connection object.
 
-      # Makes an HTTP request. Returns parsed JSON or raises appropriate error.
-      def make_request(method, path, body = nil)
-        response = @connection.run_request(method, path, body, nil)
-
-        # Check for AUTHENTICATED_FAILED header even on 200 OK
-        if response.status == 200 && response.headers["x-seraph-loginreason"]&.include?("AUTHENTICATED_FAILED")
-          raise AuthenticationError, "Jira authentication failed (X-Seraph-Loginreason: AUTHENTICATED_FAILED)"
-        end
-
-        # Check for other errors if not successful
-        handle_faraday_error(response) unless response.success?
-
-        # Return parsed body on success, or nil if body is empty/invalid
-        JSON.parse(response.body) if response.body && !response.body.empty?
-      rescue JSON::ParserError => e
-        # Raise specific error if JSON parsing fails on a successful response body
-        raise ApiError.new("Jira API returned non-JSON response: #{response&.body}", original_error: e)
-      rescue Faraday::Error => e
-        # Handle connection errors etc. that occur before the response object is available
-        status = e.response&.status
-        body = e.response&.body
-        raise ApiError.new("Jira API connection error (Status: #{status || 'N/A'}): #{e.message}", original_error: e,
-                                                                                                   status_code: status, response_body: body)
-      end
-
       # Handles Faraday errors based on the response object (for non-2xx responses).
       def handle_faraday_error(response)
         status = response.status

data/lib/active_project/adapters/pagination.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Adapters
+    module Pagination
+      # RFC 5988 Link header parsing. Returns { "next" => url, "prev" => url, … }
+      def parse_link_header(link_header)
+        return {} unless link_header
+
+        link_header.split(",").each_with_object({}) do |part, acc|
+          url, rel = part.split(";")
+          next unless rel && url
+
+          url = url[/\<([^>]+)\>/, 1]  # strip angle brackets
+          rel = rel[/rel=\"?([^\";]+)\"?/, 1]
+          acc[rel] = url if url && rel
+        end
+      end
+
+      # Synchronous enumerator – works with any Faraday adapter.
+      #
+      # @param path   [String] first request path or full URL
+      # @param method [Symbol] :get or :post
+      # @param body   [Hash,String,nil]
+      # @param query  [Hash]
+      def each_page(path, method: :get, body: nil, query: {})
+        next_path = path
+        loop do
+          data, link_header = perform_page_request(method, next_path, body, query)
+          yield data
+          next_path = parse_link_header(link_header)["next"]
+          break unless next_path
+          # After the first hop the URL is absolute; zero-out body/query for GETs
+          body = nil if method == :get
+          query = {}
+        end
+      end
+
+      # Fibre-friendly variant; launches a child task for every hop _after_ the
+      # first one, so JSON parsing in the current page overlaps the download of
+      # the next page (requires AP_DEFAULT_ADAPTER=async_http + Async scheduler).
+      def each_page_async(path, method: :get, body: nil, query: {}, &block)
+        require "async"       # soft-require so callers don’t need Async unless used
+        Async do |task|
+          current_path = path
+          while current_path
+            data, link = perform_page_request(method, current_path, body, query)
+            next_url = parse_link_header(link)["next"]
+            body = nil if method == :get # as above
+            query = {}
+            # Prefetch next page while the caller consumes this one
+            fut = next_url ? task.async { perform_page_request(method, next_url, body, query) } : nil
+            yield data
+            current_path, data, link = next_url, *fut&.wait
+          end
+        end
+      end
+
+      private
+
+      # One tiny helper so the logic is not duplicated.
+      def perform_page_request(method, path, body, query)
+        json = request(method, path, body: body, query: query)
+        [ json, @last_response.headers["Link"] ]
+      end
+    end
+  end
+end

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

@@ -4,33 +4,37 @@ module ActiveProject
   module Adapters
     module Trello
       module Connection
-        BASE_URL = "https://api.trello.com/1/"
-        # @raise [ArgumentError] if required configuration options (:api_key, :api_token) are missing.
-        def initialize(config:)
-          unless config.is_a?(ActiveProject::Configurations::TrelloConfiguration)
-            raise ArgumentError, "TrelloAdapter requires a TrelloConfiguration object"
-          end
+        include ActiveProject::Adapters::HttpClient
 
-          @config = config
-
-          unless @config.api_key && !@config.api_key.empty? && @config.api_token && !@config.api_token.empty?
-            raise ArgumentError, "TrelloAdapter configuration requires :api_key and :api_token"
-          end
+        BASE_URL = "https://api.trello.com/1/".freeze
 
-          @connection = initialize_connection
+        def initialize(config:)
+          @config = config
+          build_connection(
+            base_url: BASE_URL,
+            auth_middleware: ->(_c) { },           # Trello uses query-string auth
+            extra_headers: { "Accept" => "application/json" }
+          )
         end
 
-        private
-
-        # Initializes the Faraday connection object.
-        def initialize_connection
-          Faraday.new(url: BASE_URL) do |conn|
-            conn.request :retry
-            conn.headers["Accept"] = "application/json"
-            conn.response :raise_error
-            conn.headers["User-Agent"] = ActiveProject.user_agent
+        # ------------------------------------------------------------------
+        # Adapter-specific wrapper around HttpClient#request
+        # ------------------------------------------------------------------
+        def make_request(method, path, body = nil, query_params = {})
+          auth = { key: @config.api_key, token: @config.api_token }
+          request(method, path,
+                  body:  body,
+                  query: auth.merge(query_params))
+        rescue ActiveProject::ValidationError => e
+          # Trello signals “resource not found / malformed id” with 400 + "invalid id"
+          if e.status_code == 400 && e.message&.match?(/invalid id/i)
+            raise ActiveProject::NotFoundError, e.message
+          else
+            raise
           end
         end
+
+        private :make_request
       end
     end
   end

data/lib/active_project/adapters/trello/issues.rb

@@ -4,13 +4,17 @@ module ActiveProject
   module Adapters
     module Trello
       module Issues
+        DEFAULT_FIELDS = %w[id name desc closed idList idBoard due dueComplete idMembers].freeze
+
         # Lists Trello cards on a specific board.
         # @param board_id [String] The ID of the Trello board.
-        # @param options [Hash] Optional filtering options.
+        # @param options [Hash] Optional filtering options. Accepts :filter and :fields.
         # @return [Array<ActiveProject::Resources::Issue>]
         def list_issues(board_id, options = {})
           path = "boards/#{board_id}/cards"
-          query = { fields: "id,name,desc,closed,idList,idBoard,due,dueComplete,idMembers", list: true }
+
+          fields = options[:fields] ? Array(options[:fields]).join(",") : DEFAULT_FIELDS.join(",")
+          query = { fields: fields, list: true }
           query[:filter] = options[:filter] if options[:filter]
 
           cards_data = make_request(:get, path, nil, query)
@@ -21,11 +25,14 @@ module ActiveProject
 
         # Finds a specific Card by its ID.
         # @param card_id [String] The ID of the Trello Card.
-        # @param context [Hash] Optional context (ignored).
+        # @param context [Hash] Optional context. Accepts :fields for specific field selection.
         # @return [ActiveProject::Resources::Issue]
-        def find_issue(card_id, _context = {})
+        def find_issue(card_id, context = {})
           path = "cards/#{card_id}"
-          query = { fields: "id,name,desc,closed,idList,idBoard,due,dueComplete,idMembers", list: true }
+
+          fields = context[:fields] ? Array(context[:fields]).join(",") : DEFAULT_FIELDS.join(",")
+          query = { fields: fields, list: true }
+
           card_data = make_request(:get, path, nil, query)
           map_card_data(card_data, card_data["idBoard"])
         end
@@ -58,7 +65,7 @@ module ActiveProject
         # Updates an existing Card in Trello.
         # @param card_id [String] The ID of the Trello Card.
         # @param attributes [Hash] Attributes to update (e.g., :title, :description, :list_id, :closed, :due_on, :assignee_ids, :status).
-        # @param context [Hash] Optional context (ignored).
+        # @param context [Hash] Optional context. Accepts :fields for return data field selection.
         # @return [ActiveProject::Resources::Issue]
         def update_issue(card_id, attributes, context = {})
           update_attributes = attributes.dup
@@ -67,10 +74,10 @@ module ActiveProject
             target_status = update_attributes.delete(:status)
 
             board_id = update_attributes[:board_id] || begin
-              find_issue(card_id).project_id
-            rescue NotFoundError
-              raise NotFoundError, "Trello card with ID '#{card_id}' not found."
-            end
+                                                         find_issue(card_id).project_id
+                                                       rescue NotFoundError
+                                                         raise NotFoundError, "Trello card with ID '#{card_id}' not found."
+                                                       end
 
             unless board_id
               raise ApiError, "Could not determine board ID for card '#{card_id}' to perform status mapping."
@@ -111,6 +118,15 @@ module ActiveProject
           card_data = make_request(:put, path, nil, query_params.compact)
           map_card_data(card_data, card_data["idBoard"])
         end
+
+        # Deletes a Trello card.
+        # @param card_id [String] The ID of the Trello Card to delete.
+        # @return [Boolean] True if successfully deleted.
+        def delete_issue(card_id, **)
+          path = "cards/#{card_id}"
+          make_request(:delete, path)
+          true
+        end
       end
     end
   end

data/lib/active_project/adapters/trello_adapter.rb

@@ -70,33 +70,15 @@ module ActiveProject
 
       # Initializes the Faraday connection object.
 
-      # Helper method for making requests.
-      def make_request(method, path, body = nil, query_params = {})
-        # Use config object for credentials
-        auth_params = { key: @config.api_key, token: @config.api_token }
-        all_params = auth_params.merge(query_params)
-        json_body = body ? JSON.generate(body) : nil
-        headers = {}
-        headers["Content-Type"] = "application/json" if json_body
-
-        response = @connection.run_request(method, path, json_body, headers) do |req|
-          req.params.update(all_params)
-        end
-
-        return nil if response.status == 204 || response.body.empty?
-
-        JSON.parse(response.body)
-      rescue Faraday::Error => e
-        handle_faraday_error(e)
-      rescue JSON::ParserError => e
-        raise ApiError.new("Trello API returned non-JSON response: #{response&.body}", original_error: e)
-      end
-
       # Handles Faraday errors.
       def handle_faraday_error(error)
         status = error.response_status
         body = error.response_body
-        message = body || "Unknown Trello Error"
+        body = JSON.parse(body) if body.is_a?(String) && !body.empty? rescue body
+        if body.is_a?(Hash)
+          message = body["message"]
+        end
+        message ||= body || "Unknown Trello Error"
 
         case status
         when 401, 403

data/lib/active_project/async.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Async
+    require "async"
+    require "async/http/faraday"
+    def self.run(&block) = Async(&block)
+  end
+end

data/lib/active_project/railtie.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require "async"                       # async is now a hard dependency
+
+module ActiveProject
+  class Railtie < ::Rails::Railtie
+    config.active_project = ActiveSupport::OrderedOptions.new
+    # Host apps may override this in application.rb:
+    #   config.active_project.use_async_scheduler = false
+    config.active_project.use_async_scheduler = true
+
+    # ──────────────────────────────────────────────────────
+    # We run BEFORE Zeitwerk starts autoloading so that
+    # every thread inherits the scheduler.
+    # ──────────────────────────────────────────────────────
+    initializer "active_project.set_async_scheduler",
+                before: :initialize_dependency_mechanism do |app|
+      # 1. Allow opt-out
+      next unless app.config.active_project.use_async_scheduler
+      next if ENV["AP_NO_ASYNC_SCHEDULER"] == "1"
+
+      # 2. Don’t clobber a scheduler the host already set
+      next if Fiber.scheduler
+
+      # 3. Install Async’s cooperative scheduler
+      Fiber.set_scheduler ::Async::Scheduler.new
+
+      ActiveSupport::Notifications.instrument(
+        "active_project.async_scheduler_set",
+        scheduler: Fiber.scheduler.class.name
+      )
+    end
+  end
+end

data/lib/active_project/resource_factory.rb

@@ -31,6 +31,17 @@ module ActiveProject
       end
     end
 
+    # Fetches all resources in parallel, because patience is for people with no deadlines.
+    # Wraps `#all` calls in async tasks for each provided ID.
+    # @param args [Array] List of IDs to fetch resources for.
+    # @return [Async::Task<BaseResource>] Flattened array of results from async fetches.
+    def all_async(*args)
+      ActiveProject::Async.run do |task|
+        tasks = args.map { |id| task.async { all(id) } }
+        tasks.flat_map(&:wait)
+      end
+    end
+
     # Finds a specific resource by its ID.
     # Delegates to the appropriate adapter find method.
     # @param id [String, Integer] The ID or key of the resource.
@@ -98,6 +109,8 @@ module ActiveProject
 
     private
 
+    # Determines the list method name for the adapter based on the resource class.
+    # Throws a tantrum if it can't figure it out or if the adapter doesn't support it.
     def determine_list_method
       method_name = case @resource_class.name
       when "ActiveProject::Resources::Project" then :list_projects
@@ -112,6 +125,8 @@ module ActiveProject
       method_name
     end
 
+    # Figures out which magical method to call to find a resource, based on class name.
+    # Explodes if it can't figure it out or if the adapter is slacking off and didn't implement it.
     def determine_find_method
       method_name = case @resource_class.name
       when "ActiveProject::Resources::Project" then :find_project
@@ -126,6 +141,9 @@ module ActiveProject
       method_name
     end
 
+    # Builds the appropriate create method name for the adapter by assuming
+    # naming conventions are law and chaos isn't real.
+    # Raises if the adapter has no idea how to make the thing.
     def determine_create_method
       singular_name = @resource_class.name.split("::").last.downcase.to_sym
       method_name = :"create_#{singular_name}"

data/lib/active_project/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveProject
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/activeproject.rb

@@ -2,6 +2,7 @@ require "zeitwerk"
 require "concurrent"
 require_relative "active_project/errors"
 require_relative "active_project/version"
+require_relative "active_project/railtie" if defined?(Rails::Railtie)
 
 module ActiveProject
   class << self
@@ -110,4 +111,5 @@ loader.inflector.inflect("activeproject" => "ActiveProject")
 loader.do_not_eager_load("#{__dir__}/active_project/adapters")
 loader.ignore("#{__dir__}/active_project/errors.rb")
 loader.ignore("#{__dir__}/active_project/version.rb")
+loader.ignore("#{__dir__}/active_project/railtie.rb")
 loader.setup

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activeproject
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Abdelkader Boudih
 bindir: bin
 cert_chain: []
-date: 2025-04-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -57,6 +57,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: async-http-faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
@@ -91,6 +133,7 @@ files:
 - lib/active_project/adapters/basecamp/projects.rb
 - lib/active_project/adapters/basecamp/webhooks.rb
 - lib/active_project/adapters/basecamp_adapter.rb
+- lib/active_project/adapters/http_client.rb
 - lib/active_project/adapters/jira/comments.rb
 - lib/active_project/adapters/jira/connection.rb
 - lib/active_project/adapters/jira/issues.rb
@@ -98,6 +141,7 @@ files:
 - lib/active_project/adapters/jira/transitions.rb
 - lib/active_project/adapters/jira/webhooks.rb
 - lib/active_project/adapters/jira_adapter.rb
+- lib/active_project/adapters/pagination.rb
 - lib/active_project/adapters/trello/comments.rb
 - lib/active_project/adapters/trello/connection.rb
 - lib/active_project/adapters/trello/issues.rb
@@ -106,10 +150,12 @@ files:
 - lib/active_project/adapters/trello/webhooks.rb
 - lib/active_project/adapters/trello_adapter.rb
 - lib/active_project/association_proxy.rb
+- lib/active_project/async.rb
 - lib/active_project/configuration.rb
 - lib/active_project/configurations/base_adapter_configuration.rb
 - lib/active_project/configurations/trello_configuration.rb
 - lib/active_project/errors.rb
+- lib/active_project/railtie.rb
 - lib/active_project/resource_factory.rb
 - lib/active_project/resources/base_resource.rb
 - lib/active_project/resources/comment.rb
@@ -139,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.7
 specification_version: 4
 summary: A standardized Ruby interface for multiple project management APIs (Jira,
   Basecamp, Trello, etc.).