activeproject 0.0.0

data/lib/active_project/configuration.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  # Handles configuration for the ActiveProject gem, including adapter settings.
+  class Configuration
+    attr_reader :adapter_configs
+    attr_accessor :user_agent
+
+    # Maps adapter names (symbols) to their specific configuration classes.
+    # Add other adapters here when they need specific config classes.
+    ADAPTER_CONFIG_CLASSES = {
+      trello: Configurations::TrelloConfiguration
+      # :jira => Configurations::JiraConfiguration,
+      # :basecamp => Configurations::BasecampConfiguration,
+    }.freeze
+
+    def initialize
+      @adapter_configs = {}
+    end
+      @user_agent = "ActiveProject Gem (github.com/seuros/activeproject)"
+
+    # Adds or updates the configuration for a specific adapter.
+    # If a block is given and a specific configuration class exists for the adapter,
+    # an instance of that class is yielded to the block. Otherwise, a basic
+    # configuration object is created from the options hash.
+    #
+    # @param name [Symbol] The name of the adapter (e.g., :jira, :trello).
+    # @param options [Hash] Configuration options for the adapter (e.g., site, api_key, token).
+    # @yield [BaseAdapterConfiguration] Yields an adapter-specific configuration object if a block is given.
+    def add_adapter(name, options = {}, &block)
+      unless name.is_a?(Symbol)
+        raise ArgumentError, "Adapter name must be a Symbol (e.g., :jira)"
+      end
+
+      config_class = ADAPTER_CONFIG_CLASSES[name]
+
+      # Use specific config class if block is given and class exists
+      if block && config_class
+        adapter_config_obj = config_class.new(options)
+        yield adapter_config_obj # Allow block to modify the specific config object
+        @adapter_configs[name] = adapter_config_obj.freeze
+      # Use specific config class if no block but class exists (handles options like status_mappings passed directly)
+      elsif config_class
+         adapter_config_obj = config_class.new(options)
+         @adapter_configs[name] = adapter_config_obj.freeze
+      # Fallback to base config class if no specific class or no block
+      else
+        @adapter_configs[name] = Configurations::BaseAdapterConfiguration.new(options).freeze
+      end
+    end
+
+    # Retrieves the configuration object for a specific adapter.
+    # @param name [Symbol] The name of the adapter.
+    # @return [BaseAdapterConfiguration, nil] The configuration object or nil if not found.
+    def adapter_config(name)
+      @adapter_configs[name]
+    end
+  end
+end

data/lib/active_project/configurations/base_adapter_configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Configurations
+    # Base class for adapter configurations, holding common options.
+    class BaseAdapterConfiguration
+      attr_reader :options
+
+      def initialize(options = {})
+        @options = options.dup # Duplicate to allow modification before freezing
+      end
+
+      # Allow accessing options via method calls
+      def method_missing(method_name, *arguments, &block)
+        if options.key?(method_name) && arguments.empty? && !block
+          options[method_name]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        options.key?(method_name) || super
+      end
+
+      def freeze
+        @options.freeze
+        super
+      end
+    end
+  end
+end

data/lib/active_project/configurations/trello_configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Configurations
+    # Holds Trello-specific configuration options.
+    class TrelloConfiguration < BaseAdapterConfiguration
+      # @!attribute [rw] status_mappings
+      #   @return [Hash] Mappings from Board IDs to List ID/Name to Status Symbol.
+      #   @example
+      #     {
+      #       'board_id_1' => { 'list_id_open' => :open, 'list_id_closed' => :closed },
+      #       'board_id_2' => { 'Done List Name' => :closed } # Example using names (less reliable)
+      #     }
+      attr_accessor :status_mappings
+
+      def initialize(options = {})
+        super
+        @status_mappings = options.delete(:status_mappings) || {}
+      end
+
+      def freeze
+        # Ensure nested hashes are also frozen
+        @status_mappings.each do |board_id, mappings|
+          mappings.freeze
+        end
+        @status_mappings.freeze
+        super
+      end
+    end
+  end
+end

data/lib/active_project/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  # Base class for all ActiveProject errors
+  class Error < StandardError; end
+
+  # Raised when authentication with the external API fails
+  class AuthenticationError < Error; end
+
+  # Raised when a requested resource is not found
+  class NotFoundError < Error; end
+
+  # Raised when the external API rate limit is exceeded
+  class RateLimitError < Error; end
+
+  # Raised for general API errors (e.g., 5xx status codes)
+  class ApiError < Error
+    attr_reader :original_error, :status_code, :response_body
+
+    def initialize(message = nil, original_error: nil, status_code: nil, response_body: nil)
+      super(message)
+      @original_error = original_error
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  # Raised for validation errors (e.g., 400/422 status codes with field details)
+  class ValidationError < ApiError
+    attr_reader :errors
+
+    def initialize(message = nil, errors: {}, original_error: nil, status_code: nil, response_body: nil)
+      super(message, original_error: original_error, status_code: status_code, response_body: response_body)
+      @errors = errors # Expects a hash like { field: ['message1', 'message2'] }
+    end
+  end
+
+  # Raised when an adapter method is not implemented
+  class NotImplementedError < Error; end
+end

data/lib/active_project/resource_factory.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  # Factory class for creating and finding resource objects (Project, Issue, etc.)
+  # associated with a specific adapter.
+  class ResourceFactory
+    # @param adapter [Adapters::Base] The adapter instance.
+    # @param resource_class [Class] The resource class (e.g., Resources::Project).
+    def initialize(adapter:, resource_class:)
+      @adapter = adapter
+      @resource_class = resource_class
+    end
+
+    # Fetches all resources of the associated type.
+    # Delegates to the appropriate adapter list method.
+    # @param args [Array] Arguments to pass to the adapter's list method (e.g., project_id for issues).
+    # @return [Array<BaseResource>] An array of resource objects.
+    def all(*args)
+      list_method = determine_list_method
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      primary_arg = args.first
+
+      # Call adapter method with appropriate arguments
+      if primary_arg
+        @adapter.send(list_method, primary_arg, options)
+      else
+        # Handle case where list method might not take options (like list_projects)
+        if @adapter.method(list_method).arity == 0
+           @adapter.send(list_method)
+        else
+           @adapter.send(list_method, options)
+        end
+      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.
+    # @param context [Hash] Optional context needed by some find methods (e.g., :project_id for Basecamp issues).
+    # @return [BaseResource, nil] The found resource object or nil.
+    def find(id, context = {})
+      find_method = determine_find_method
+
+      # Pass context only if provided and the find method accepts it
+      if !context.empty?
+        @adapter.send(find_method, id, context)
+      else
+        @adapter.send(find_method, id)
+      end
+    rescue ActiveProject::NotFoundError
+      nil # Return nil if the resource is not found by the adapter
+    end
+
+    # Fetches the first resource of the associated type.
+    # @param args [Array] Arguments to pass to the adapter's list method.
+    # @return [BaseResource, nil] The first resource object found or nil.
+    def first(*args)
+      all(*args).first
+    end
+
+    # Filters resources based on given conditions (client-side).
+    # @param conditions [Hash] Conditions to filter by.
+    # @param list_args [Array] Arguments for the underlying #all call.
+    # @return [Array<BaseResource>] Matching resources.
+    def where(conditions, *list_args)
+      resources = all(*list_args)
+      resources.select do |resource|
+        conditions.all? do |key, value|
+          resource.respond_to?(key) && resource.send(key) == value
+        end
+      end
+    end
+
+    # Builds a new, unsaved resource instance.
+    # @param attributes [Hash] Attributes for the new resource.
+    # @return [BaseResource] A new instance of the resource class.
+    def build(attributes = {})
+      merged_attrs = attributes.merge(
+        adapter_source: @adapter.class.name.split("::").last.sub("Adapter", "").downcase.to_sym,
+        raw_data: attributes
+      )
+      @resource_class.new(@adapter, merged_attrs)
+    end
+
+    # Builds and saves a new resource instance.
+    # @param attributes [Hash] Attributes for the new resource.
+    # @return [BaseResource] The created resource object.
+    # @raise [NotImplementedError] Currently raises because #save is not implemented.
+    def create(attributes = {})
+      # Determine the correct adapter create method based on resource type
+      create_method = determine_create_method
+      # Note: Assumes create methods on adapters take attributes hash directly
+      # Context like project_id needs to be part of the attributes hash if required by adapter
+      @adapter.send(create_method, attributes)
+      # A full implementation would likely involve build then save:
+      # resource = build(attributes)
+      # resource.save
+      # resource
+    end
+
+    private
+
+    def determine_list_method
+      method_name = case @resource_class.name
+      when "ActiveProject::Resources::Project" then :list_projects
+      when "ActiveProject::Resources::Issue" then :list_issues
+      else raise "Cannot determine list method for #{@resource_class.name}"
+      end
+      raise NotImplementedError, "#{@adapter.class.name} does not implement ##{method_name}" unless @adapter.respond_to?(method_name)
+      method_name
+    end
+
+    def determine_find_method
+      method_name = case @resource_class.name
+      when "ActiveProject::Resources::Project" then :find_project
+      when "ActiveProject::Resources::Issue" then :find_issue
+      else raise "Cannot determine find method for #{@resource_class.name}"
+      end
+      raise NotImplementedError, "#{@adapter.class.name} does not implement ##{method_name}" unless @adapter.respond_to?(method_name)
+      method_name
+    end
+
+    def determine_create_method
+      singular_name = @resource_class.name.split("::").last.downcase.to_sym
+      method_name = :"create_#{singular_name}"
+      raise NotImplementedError, "#{@adapter.class.name} does not implement ##{method_name}" unless @adapter.respond_to?(method_name)
+      method_name
+    end
+  end
+end

data/lib/active_project/resources/base_resource.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Resources
+    # Base class for resource objects (Project, Issue, etc.)
+    # Provides common initialization and attribute access via method_missing.
+    class BaseResource
+      attr_reader :adapter, :raw_data, :attributes
+
+      # @param adapter [Adapters::Base] The adapter instance that fetched/created this resource.
+      # @param attributes [Hash] A hash of attributes for the resource.
+      def initialize(adapter, attributes = {})
+        @adapter = adapter
+        # Store raw_data if provided, otherwise duplicate the input attributes
+        @raw_data = attributes.key?(:raw_data) ? attributes[:raw_data] : attributes.dup
+        # Store attributes for method_missing access, remove raw_data key if it exists
+        @attributes = attributes.dup
+        @attributes.delete(:raw_data)
+      end
+
+      # Basic inspection using defined members if available, otherwise attributes.
+      def inspect
+        members_to_show = self.class.members.empty? ? @attributes.keys : self.class.members
+        attrs_str = members_to_show.map { |m| "#{m}=#{send(m).inspect}" }.join(", ")
+        "#<#{self.class.name} #{attrs_str}>"
+      end
+
+      # Method missing for accessing attributes stored in @attributes hash.
+      def method_missing(method_name, *arguments, &block)
+        if @attributes.key?(method_name)
+          # Return attribute value if no arguments are given (getter)
+          arguments.empty? ? @attributes[method_name] : super
+        else
+          super
+        end
+      end
+
+      # Ensure respond_to? works correctly with method_missing.
+      def respond_to_missing?(method_name, include_private = false)
+        @attributes.key?(method_name) || super
+      end
+
+      # Class method to define expected members (mainly for introspection/documentation).
+      def self.members
+        @members ||= []
+      end
+
+      # Defines expected members for the resource class.
+      def self.def_members(*args)
+        @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}"
+      end
+
+      def delete
+        raise NotImplementedError, "#delete not yet implemented for #{self.class.name}"
+      end
+    end
+  end
+end

data/lib/active_project/resources/comment.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "base_resource"
+
+module ActiveProject
+  module Resources
+    # Represents a Comment on an Issue
+    class Comment < BaseResource
+      def_members :id, :body, :author, :created_at, :updated_at, :issue_id,
+                  :adapter_source
+      # raw_data and adapter are inherited from BaseResource
+
+      # Add comment-specific methods here later (e.g., save, update, delete)
+    end
+  end
+end

data/lib/active_project/resources/issue.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Resources
+    # Represents an Issue (e.g., Jira Issue, Trello Card, Basecamp Todo)
+    class Issue < BaseResource
+      def_members :id, :key, :title, :description, :status, :assignees,
+                  :reporter, :project_id, :created_at, :updated_at, :due_on,
+                  :priority, :adapter_source
+      # raw_data and adapter are inherited from BaseResource
+
+
+      # Saves the issue (creates if new, updates if existing).
+      # Placeholder - Full implementation requires attribute tracking and adapter delegation.
+      # @return [Boolean] true if save was successful, false otherwise.
+      def save
+        raise NotImplementedError, "#save not yet implemented for #{self.class.name}"
+      end
+
+      # Updates the issue with the given attributes and saves it.
+      # Placeholder - Full implementation requires attribute tracking and adapter delegation.
+      # @param attributes [Hash] Attributes to update.
+      # @return [Boolean] true if update was successful, false otherwise.
+      def update(attributes)
+        # Basic implementation could be:
+        # attributes.each { |k, v| instance_variable_set("@#{k}", v) if respond_to?(k) } # Need setters or direct ivar access
+        # save
+        raise NotImplementedError, "#update not yet implemented for #{self.class.name}"
+      end
+
+
+      # Returns an association proxy for accessing comments on this issue.
+      # @return [AssociationProxy<Resources::Comment>]
+      def comments
+        AssociationProxy.new(owner: self, adapter: @adapter, association_name: :comments)
+      end
+
+      # Add issue-specific methods here later (e.g., comments association, save, update)
+    end
+  end
+end

data/lib/active_project/resources/project.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  module Resources
+    # Represents a Project (e.g., Jira Project, Trello Board, Basecamp Project)
+    class Project < BaseResource
+      def_members :id, :key, :name, :adapter_source
+      # raw_data and adapter are inherited from BaseResource
+
+
+      # Returns an association proxy for accessing issues within this project.
+      # @return [AssociationProxy<Resources::Issue>]
+      def issues
+        AssociationProxy.new(owner: self, adapter: @adapter, association_name: :issues)
+      end
+
+      # Add project-specific methods here later (e.g., issues association)
+    end
+  end
+end

data/lib/active_project/resources/user.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base_resource"
+
+module ActiveProject
+  module Resources
+    # Represents a User
+    class User < BaseResource
+      def_members :id, :name, :email, :adapter_source
+      # raw_data and adapter are inherited from BaseResource
+    end
+  end
+end

data/lib/active_project/version.rb

@@ -0,0 +1,3 @@
+module ActiveProject
+  VERSION = "0.0.0"
+end

data/lib/active_project/webhook_event.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveProject
+  # Represents a standardized event parsed from a webhook payload.
+  # Using Struct for simplicity for now. Could be a full class inheriting BaseResource if needed.
+  WebhookEvent = Struct.new(
+    :event_type,        # Symbol representing the event (e.g., :issue_created, :comment_added)
+    :object_kind,       # Symbol representing the type of object involved (e.g., :issue, :comment)
+    :event_object_id,   # String or Integer ID of the primary object (renamed from object_id)
+    :object_key,        # String key/slug of the primary object (if applicable, e.g., Jira issue key)
+    :project_id,        # String or Integer ID of the associated project/board/bucket
+    :actor,             # User resource or Hash representing the user who triggered the event
+    :timestamp,         # Time object representing when the event occurred
+    :adapter_source,    # Symbol identifying the source adapter (e.g., :jira, :trello, :basecamp)
+    :changes,           # Hash detailing specific changes (if applicable, e.g., for updates)
+    :object_data,       # Optional: Hash containing more detailed data about the object
+    :raw_data,          # The original, parsed webhook payload hash
+    keyword_init: true
+  )
+end

data/lib/activeproject.rb

@@ -0,0 +1,61 @@
+require "zeitwerk"
+require_relative "active_project/errors"
+require_relative "active_project/version"
+
+module ActiveProject
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+
+    # Returns the configured User-Agent string, including the gem version.
+    # @return [String] The User-Agent string.
+    def user_agent
+      base_agent = configuration.user_agent || "ActiveProject Gem (github.com/seuros/activeproject)"
+      "#{base_agent} v#{ActiveProject::VERSION}"
+    end
+
+    # Returns a memoized instance of the requested adapter.
+    # @param adapter_name [Symbol] The name of the adapter (e.g., :jira, :trello).
+    # @return [Adapters::Base] An instance of the requested adapter.
+    # @raise [ArgumentError] if the adapter configuration is missing or invalid.
+    # @raise [LoadError] if the adapter class cannot be found.
+    def adapter(adapter_name)
+      @adapters ||= {}
+      @adapters[adapter_name] ||= begin
+        config = configuration.adapter_config(adapter_name)
+
+        unless config.is_a?(ActiveProject::Configurations::BaseAdapterConfiguration)
+          raise ArgumentError, "Configuration for adapter ':#{adapter_name}' not found or invalid. Use ActiveProject.configure."
+        end
+
+        # Use string-based constant lookup with the full namespace path
+        adapter_class_name = "ActiveProject::Adapters::#{adapter_name.to_s.capitalize}Adapter"
+
+        # Ensure the adapter class is loaded
+        require "active_project/adapters/#{adapter_name}_adapter"
+
+        # Get the constant with the full path
+        adapter_class = Object.const_get(adapter_class_name)
+
+        adapter_class.new(config: config)
+      rescue LoadError, NameError => e
+        raise LoadError, "Could not find adapter class #{adapter_class_name}: #{e.message}"
+      end
+    end
+  end
+end
+
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+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.setup

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: activeproject
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 2025-04-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: 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: faraday-retry
+  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
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides a unified API client for interacting with various project management
+  platforms like Jira, Basecamp, and Trello. Aims to normalize core models (projects,
+  tasks, comments) and workflows for easier integration in Rails applications.
+email:
+- terminale@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/active_project/adapters/base.rb
+- lib/active_project/adapters/basecamp_adapter.rb
+- lib/active_project/adapters/jira_adapter.rb
+- lib/active_project/adapters/trello_adapter.rb
+- lib/active_project/association_proxy.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/resource_factory.rb
+- lib/active_project/resources/base_resource.rb
+- lib/active_project/resources/comment.rb
+- lib/active_project/resources/issue.rb
+- lib/active_project/resources/project.rb
+- lib/active_project/resources/user.rb
+- lib/active_project/version.rb
+- lib/active_project/webhook_event.rb
+- lib/activeproject.rb
+homepage: https://github.com/seuros/activeproject
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/seuros/activeproject
+  source_code_uri: https://github.com/seuros/activeproject
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A standardized Ruby interface for multiple project management APIs (Jira,
+  Basecamp, Trello, etc.).
+test_files: []