activeproject 0.2.0 → 0.5.0

data/lib/active_project/configurations/github_configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Configurations
+    class GithubConfiguration < BaseAdapterConfiguration
+      # expected options:
+      # :access_token – PAT or GitHub App installation token
+      # :owner        – user/org login the adapter should default to (optional for github_project)
+      # :repo         – repository name (required for github_repo adapter)
+      # optional:
+      # :status_mappings – Maps GitHub project status names to normalized symbols
+      #   Example: { "Todo" => :open, "In Progress" => :in_progress, "Blocked" => :blocked, "Done" => :closed }
+      #   Supports: :open, :in_progress, :blocked, :on_hold, :closed
+      # :webhook_secret – For webhook signature verification
+
+      attr_accessor :status_mappings
+
+      def initialize(options = {})
+        # Set up default status mappings before calling super
+        @status_mappings = options.delete(:status_mappings) || {
+          "open" => :open,
+          "closed" => :closed
+        }
+        super
+      end
+
+      def freeze
+        # Ensure nested hashes are also frozen
+        @status_mappings.freeze
+        super
+      end
+
+      protected
+
+      def validate_configuration!
+        require_options(:access_token)
+        validate_option_type(:access_token, String)
+        validate_option_type(:owner, String, allow_nil: true)
+        validate_option_type(:repo, String, allow_nil: true)
+        validate_option_type(:webhook_secret, String, allow_nil: true)
+        validate_option_type(:status_mappings, Hash, allow_nil: true)
+
+        # Skip format validation in test environment with dummy values
+        return if test_environment_with_dummy_values?
+
+        # Validate access_token format (GitHub tokens start with specific prefixes)
+        token = options[:access_token]
+        unless token.match?(/^(gh[pousr]_|github_pat_)/i) || token.length >= 20
+          raise ArgumentError,
+                "GitHub access token appears to be invalid. Expected a GitHub PAT " \
+                "(starting with 'ghp_', 'gho_', 'ghu_', 'ghs_', 'ghr_', or 'github_pat_') " \
+                "or a token at least 20 characters long."
+        end
+      end
+    end
+  end
+end

data/lib/active_project/configurations/jira_configuration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Configurations
+    class JiraConfiguration < BaseAdapterConfiguration
+      # expected options:
+      # :site_url   – Jira instance URL (e.g., "https://company.atlassian.net")
+      # :username   – Jira username/email
+      # :api_token  – Jira API token (not password)
+      # optional:
+      # :timeout    – Request timeout in seconds (default: 30)
+      # :verify_ssl – Whether to verify SSL certificates (default: true)
+
+      protected
+
+      def validate_configuration!
+        super # Call parent validation for retry options
+        require_options(:site_url, :username, :api_token)
+        validate_option_type(:site_url, String)
+        validate_option_type(:username, String)
+        validate_option_type(:api_token, String)
+        validate_option_type(:timeout, Integer, allow_nil: true)
+        validate_option_type(:verify_ssl, [ TrueClass, FalseClass ], allow_nil: true)
+
+        # Skip format validation in test environment with dummy values
+        return if test_environment_with_dummy_values?
+
+        # Validate site_url format
+        site_url = options[:site_url]
+        unless site_url.match?(/^https?:\/\/.+/)
+          raise ArgumentError,
+                "Jira site_url must be a valid URL starting with http:// or https://, " \
+                "got: #{site_url.inspect}"
+        end
+
+        # Validate username format (email or username)
+        username = options[:username]
+        unless username.include?("@") || username.match?(/^[a-zA-Z0-9._-]+$/)
+          raise ArgumentError,
+                "Jira username should be an email address or valid username, " \
+                "got: #{username.inspect}"
+        end
+
+        # Validate API token format (should be base64-ish)
+        api_token = options[:api_token]
+        if api_token.length < 10
+          raise ArgumentError,
+                "Jira API token appears to be too short. Expected an API token from " \
+                "Atlassian Account Settings, got token of length #{api_token.length}"
+        end
+      end
+    end
+  end
+end

data/lib/active_project/configurations/trello_configuration.rb

@@ -6,10 +6,16 @@ module ActiveProject
     class TrelloConfiguration < BaseAdapterConfiguration
       # @!attribute [rw] status_mappings
       #   @return [Hash] Mappings from Board IDs to List ID/Name to Status Symbol.
+      #   Supports expanded status vocabulary: :open, :in_progress, :blocked, :on_hold, :closed
       #   @example
       #     {
-      #       'board_id_1' => { 'list_id_open' => :open, 'list_id_closed' => :closed },
-      #       'board_id_2' => { 'Done List Name' => :closed } # Example using names (less reliable)
+      #       'board_id_1' => {
+      #         'list_id_backlog' => :open,
+      #         'list_id_progress' => :in_progress,
+      #         'list_id_blocked' => :blocked,
+      #         'list_id_done' => :closed
+      #       },
+      #       'board_id_2' => { 'Done List Name' => :closed } # Using names (less reliable)
       #     }
       attr_accessor :status_mappings
 
@@ -18,6 +24,22 @@ module ActiveProject
         @status_mappings = options.delete(:status_mappings) || {}
       end
 
+      protected
+
+      def validate_configuration!
+        require_options(:key, :token)
+        validate_option_type(:key, String)
+        validate_option_type(:token, String)
+        validate_option_type(:status_mappings, Hash, allow_nil: true) if options[:status_mappings]
+
+        # Skip format validation in test environment with dummy values
+        nil if test_environment_with_dummy_values?
+
+        # Additional validation for actual tokens could go here
+      end
+
+      public
+
       def freeze
         # Ensure nested hashes are also frozen
         @status_mappings.each_value(&:freeze)

data/lib/active_project/connections/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Connections
+    # Shared helpers used by both REST and GraphQL modules,
+    # because every cult needs a doctrine of "Don't Repeat Yourself."
+    module Base
+      # ------------------------------------------------------------------
+      # RFC 5988 Link header parsing
+      # ------------------------------------------------------------------
+      #
+      # Parses your classic overengineered pagination headers.
+      #
+      #   <https://api.example.com/…?page=2>; rel="next",
+      #   <https://api.example.com/…?page=5>; rel="last"
+      #
+      # REST’s way of pretending it’s not just guessing how many pages there are.
+      #
+      # @param header [String, nil]
+      # @return [Hash{String => String}] map of rel => absolute URL
+      def parse_link_header(header)
+        return {} unless header # Always a good first step: check if we’ve been given absolutely nothing.
+
+        header.split(",").each_with_object({}) do |part, acc|
+          url, rel = part.split(";", 2)
+          next unless url && rel
+
+          url = url[/<([^>]+)>/, 1] # Pull the sacred URL from its <> temple.
+          rel = rel[/rel="?([^";]+)"?/, 1] # Decode the rel tag, likely “next,” “prev,” or “you tried.”
+          acc[rel] = url if url && rel
+        end
+      end
+    end
+  end
+end

data/lib/active_project/connections/graph_ql.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Connections
+    # Supposedly "reusable" GraphQL connection logic.
+    # Because clearly REST wasn't performative enough, and now we need a whole query language
+    # to fetch a user's email address.
+    module GraphQl
+      include Base
+      include Pagination # Because apparently, every five-item list deserves its own saga.
+
+      # Initializes the GraphQL connection. Requires an endpoint, a token,
+      # an optional auth header, and—if it still doesn't work—maybe a goat sacrifice.
+      # Bonus points if you time it around Eid al-Adha or Yom Kippur.
+      # Nothing says "API design" like invoking Abrahamic tension.
+      def init_graphql(endpoint:, token:, auth_header: "Authorization", extra_headers: {})
+        default_headers = {
+          "Content-Type" => "application/json"
+        }
+
+        build_connection(
+          base_url: endpoint,
+          auth_middleware: ->(c) { c.headers[auth_header] = "Bearer #{token}" },
+          extra_headers: default_headers.merge(extra_headers)
+        )
+      end
+
+      # Executes a GraphQL POST request. Because normal HTTP verbs had too much dignity.
+      #
+      # @return [Hash] The "data" part, which is always buried under a mountain of abstract misery.
+      def request_gql(query:, variables: {})
+        payload = { query: query, variables: variables }.to_json
+        res = request(:post, "", body: payload)
+        raise_graphql_errors!(res) # Make sure to decode the latest prophecy from the Error Oracle.
+        res["data"]
+      end
+
+      private
+
+      # Handle GraphQL errors with configurable behavior for partial success.
+      # GitHub sometimes returns "partial success" (data + errors) when we query
+      # both `user` and `organization` for the same login.
+      #
+      # @param result [Hash] The GraphQL response containing "data" and/or "errors"
+      # @raise [ActiveProject::AuthenticationError] for auth-related errors
+      # @raise [ActiveProject::NotFoundError] for not-found errors
+      # @raise [ActiveProject::ValidationError] for other GraphQL errors
+      def raise_graphql_errors!(result)
+        errs = result["errors"]
+        return unless errs&.any?          # no errors → nothing to do
+
+        data = result["data"]
+
+        has_useful_data =
+          case data
+          when Hash  then data.values.compact.any?
+          when Array then data.compact.any?
+          else            !data.nil?
+          end
+
+        # Log partial errors for debugging even when we have useful data
+        if has_useful_data && defined?(ActiveProject.logger) && ActiveProject.logger
+          partial_msg = errs.map { |e| e["message"] }.join("; ")
+          ActiveProject.logger.warn("[ActiveProject::GraphQL] Partial errors ignored: #{partial_msg}")
+        end
+
+        return if has_useful_data         # partial success – continue with data
+
+        # ─── No useful data. Treat as fatal. Map message to our error hierarchy. ──
+        msg = errs.map { |e| e["message"] }.join("; ")
+
+        case msg
+        when /unauth/i
+          raise ActiveProject::AuthenticationError, msg
+        when /not\s+found|unknown id|resolve to a User/i
+          raise ActiveProject::NotFoundError, msg
+        else
+          raise ActiveProject::ValidationError.new(msg, errors: errs)
+        end
+      end
+    end
+  end
+end

data/lib/active_project/connections/http_client.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "async/http/faraday"
+require "json"
+
+module ActiveProject
+  module Connections
+    module HttpClient
+      include Base
+      attr_reader :connection, :last_response
+
+      DEFAULT_HEADERS = {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => -> { ActiveProject.user_agent }
+      }.freeze
+
+      # Default retry configuration - can be overridden in adapter configs
+      DEFAULT_RETRY_OPTS = {
+        max: 3,                           # Maximum number of retries
+        interval: 0.5,                    # Initial delay between retries (seconds)
+        backoff_factor: 2,                # Exponential backoff multiplier
+        retry_statuses: [ 429, 500, 502, 503, 504 ], # HTTP status codes to retry
+        exceptions: [
+          Faraday::TimeoutError,
+          Faraday::ConnectionFailed,
+          Faraday::SSLError
+        ]
+      }.freeze
+
+      def build_connection(base_url:, auth_middleware:, extra_headers: {}, retry_options: {})
+        @base_url = base_url
+
+        # Merge custom retry options with defaults
+        final_retry_opts = DEFAULT_RETRY_OPTS.merge(retry_options)
+
+        @connection = Faraday.new(url: base_url) do |conn|
+          auth_middleware.call(conn)                 # Let the adapter sprinkle its secret sauce here.
+          conn.request  :retry, **final_retry_opts   # Intelligent retry with configurable options
+          conn.response :raise_error                 # Yes, we want the failure loud and flaming.
+          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)         # Add your weird little header tweaks here.
+          yield conn if block_given?                 # Optional: make it worse with your own block.
+        end
+      end
+
+      # Sends the HTTP request like a brave little toaster.
+      def request(method, path, body: nil, query: nil, headers: {})
+        raise "HTTP connection not initialised" unless connection # You forgot to plug it in. Classic.
+
+        json_body = if body.is_a?(String)
+                      body
+        else
+                      (body ? JSON.generate(body) : nil)
+        end
+        response  = connection.run_request(method, path, json_body, headers) do |req|
+          req.params.update(query) if query&.any?
+        end
+
+        @last_response = response
+
+        return nil if response.status == 204 || response.body.to_s.empty?
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise translate_http_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
+    end
+  end
+end

data/lib/active_project/connections/pagination.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Connections
+    # Relay + Link-header pagination helpers usable for REST and GraphQL
+    module Pagination
+      include HttpClient
+      # Generic RFC-5988 “Link” header paginator (GitHub/Jira/Trello style)
+      #
+      # @yieldparam page [Object] parsed JSON for each HTTP page
+      def each_page(path, method: :get, body: nil, query: {}, headers: {})
+        next_url = path
+        loop do
+          page = request(method, next_url, body: body, query: query, headers: headers)
+          yield page
+          link_header = @last_response&.headers&.[]("Link")
+          next_url = parse_link_header(link_header)["next"]
+          break unless next_url
+
+          # After first request we follow absolute URLs; zero out body/query for GETs
+          body = nil if method == :get
+          query = {}
+        end
+      end
+
+      # Relay-style paginator (pageInfo{ hasNextPage, endCursor })
+      #
+      # @param connection_path [Array<String>] path inside JSON to the connection node
+      # @yieldparam node [Object] each edge.node yielded
+      def each_edge(query:, connection_path:, variables: {}, after_key: "after")
+        cursor = nil
+        loop do
+          vars = variables.merge(after_key => cursor)
+          data = yield(vars) # caller executes GraphQL request, returns data hash
+          conn = data.dig(*connection_path)
+          conn["edges"].each { |edge| yield edge["node"] }
+          break unless conn["pageInfo"]["hasNextPage"]
+
+          cursor = conn["pageInfo"]["endCursor"]
+        end
+      end
+    end
+  end
+end

data/lib/active_project/connections/rest.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Connections
+    # Reusable REST connection logic for normal, boring APIs like Jira, Basecamp, and Trello.
+    # You know, ones that don’t require a decoder ring and a theological debate to use.
+    module Rest
+      include Base
+      include Pagination
+
+      # Must be called from the concrete adapter's initialize.
+      #
+      # @yieldparam conn [Faraday::Connection] A lovely, dependable object where you slap on your auth.
+      # Unlike GraphQL, this one doesn’t need you to bend the knee or cite the Book of Steve Job.
+      def init_rest(base_url:, auth_middleware:, extra_headers: {}, retry_options: {})
+        build_connection(
+          base_url: base_url,
+          auth_middleware: auth_middleware,
+          extra_headers: extra_headers,
+          retry_options: retry_options
+        )
+      end
+
+      # Wrapper around HttpClient#request.
+      # Adapters may override this if their APIs have... *quirks* (read: sins).
+      def request_rest(method, path, body = nil, query = nil, headers = {})
+        request(method, path, body: body, query: query, headers: headers)
+      rescue Faraday::Error => e
+        raise map_faraday_error(e) # Wrap Faraday errors in our custom trauma response.
+      end
+    end
+  end
+end

data/lib/active_project/error_mapper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module ErrorMapper
+    extend ActiveSupport::Concern
+
+    included do
+      # one hash per subclass, inherited & copy-on-write
+      class_attribute :error_map, instance_accessor: false, default: {}
+    end
+
+    class_methods do
+      # rescue_status 401..403, with: AuthenticationError
+      def rescue_status(*codes, with:)
+        new_map = error_map.dup
+        codes.flat_map { |c| c.is_a?(Range) ? c.to_a : c }
+             .each { |status| new_map[status] = with }
+        self.error_map = new_map.freeze
+      end
+    end
+
+    private
+
+    def translate_http_error(err)
+      status  = err.response_status
+      message = begin
+        JSON.parse(err.response_body.to_s)["message"]
+      rescue StandardError
+        err.response_body
+      end
+
+      exc = self.class.error_map[status] ||
+            ActiveProject::ApiError
+
+      raise exc, message, err.backtrace
+    end
+  end
+end

data/lib/active_project/errors.rb

@@ -13,6 +13,19 @@ module ActiveProject
   # Raised when the external API rate limit is exceeded
   class RateLimitError < Error; end
 
+  # Raised for configuration errors (e.g., missing required settings, invalid mappings)
+  class ConfigurationError < Error; end
+
+  # Raised for connection errors (e.g., network failures, timeouts)
+  class ConnectionError < Error
+    attr_reader :original_error
+
+    def initialize(message = nil, original_error: nil)
+      super(message)
+      @original_error = original_error
+    end
+  end
+
   # Raised for general API errors (e.g., 5xx status codes)
   class ApiError < Error
     attr_reader :original_error, :status_code, :response_body

data/lib/active_project/railtie.rb

@@ -0,0 +1,33 @@
+# 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/resources/base_resource.rb

@@ -46,23 +46,22 @@ module ActiveProject
       end
 
       # Defines expected members for the resource class.
-      def self.def_members(*args)
+      def self.def_members(*names)
         @members ||= []
-        @members.concat(args.map(&:to_sym))
-        # No explicit attr_reader needed when using method_missing
-      end
-
-      # Placeholder methods for ORM-like behavior
-      def save
-        raise NotImplementedError, "#save not yet implemented for #{self.class.name}"
-      end
-
-      def update(attributes)
-        raise NotImplementedError, "#update not yet implemented for #{self.class.name}"
+        names.each do |name|
+          sym = name.to_sym
+          @members << sym
+          define_method(sym) { @attributes[sym] } # reader
+          define_method("#{sym}=") do |val| # writer
+            @attributes[sym] = val
+          end
+        end
       end
 
-      def delete
-        raise NotImplementedError, "#delete not yet implemented for #{self.class.name}"
+      def to_h
+        self.class.members.each_with_object({}) do |name, hash|
+          hash[name] = public_send(name)
+        end
       end
     end
   end

data/lib/active_project/resources/comment.rb

@@ -3,9 +3,53 @@
 module ActiveProject
   module Resources
     # Represents a Comment on an Issue
-    class Comment < BaseResource
+    class Comment < PersistableResource
       def_members :id, :body, :author, :created_at, :updated_at, :issue_id,
-                  :adapter_source
+                  :project_id, :adapter_source
+
+      # For new comments (no id) call add_comment; otherwise update.
+      def save
+        fresh = if id.nil?
+                  @adapter.add_comment(issue_id, body, adapter_context)
+        else
+                  @adapter.update_comment(id, body, adapter_context)
+        end
+        copy_from(fresh)
+        true
+      end
+
+      # Shorthand that mutates +body+ and persists.
+      def update(attrs = {})
+        self.body = attrs[:body] if attrs[:body]
+        save
+      end
+
+      # Remove comment remotely and freeze this instance.
+      def delete
+        raise "id missing – not persisted" if id.nil?
+
+        @adapter.delete_comment(id, adapter_context)
+        freeze
+        true
+      end
+
+      alias destroy delete
+
+      private
+
+      # Build adapter-specific context for comment operations
+      def adapter_context
+        case @adapter
+        when ActiveProject::Adapters::BasecampAdapter
+          { project_id: project_id }
+        when ActiveProject::Adapters::JiraAdapter
+          { issue_id: issue_id }
+        when ActiveProject::Adapters::TrelloAdapter
+          { card_id: issue_id }
+        else
+          {}
+        end
+      end
     end
   end
 end