moco-ruby 0.1.2 → 1.0.0

data/lib/moco/entities/base_entity.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require "active_support/inflector" # Ensure ActiveSupport::Inflector is available
+
+module MOCO
+  # Base class for all MOCO API entities
+  class BaseEntity
+    attr_reader :client, :attributes
+
+    # Initializes an entity instance from raw API response data (Hash).
+    # Recursively processes nested hashes and arrays, converting known
+    # entity structures into corresponding MOCO::Entity instances.
+    def initialize(client, response_data)
+      @client = client
+
+      # Ensure response_data is a Hash before proceeding
+      unless response_data.is_a?(Hash)
+        raise ArgumentError, "BaseEntity must be initialized with a Hash, got: #{response_data.class}"
+      end
+
+      # Process the top-level hash: transform keys and process nested values.
+      @attributes = response_data.transform_keys(&:to_sym)
+                                 .each_with_object({}) do |(k, v), acc|
+                                   # Use process_value only for the *values* within the hash
+                                   acc[k] = process_value(v, k)
+                                 end
+
+      # Define attribute methods based on the processed attributes hash
+      define_attribute_methods
+    end
+
+    # Provides a basic string representation (can be overridden by subclasses).
+    def to_s
+      "#{self.class.name.split("::").last} ##{id}"
+    end
+
+    # Returns the entity's ID.
+    def id
+      attributes[:id] || attributes["id"]
+    end
+
+    # Compares two entities based on class and ID.
+    def ==(other)
+      self.class == other.class && !id.nil? && id == other.id
+    end
+
+    # Converts the entity to a Hash, recursively converting nested entities.
+    def to_h
+      attributes.transform_values do |value|
+        case value
+        when BaseEntity then value.to_h
+        when Array then value.map { |item| item.is_a?(BaseEntity) ? item.to_h : item }
+        else value
+        end
+      end
+    end
+
+    # Converts the entity to a JSON string.
+    def to_json(*options)
+      to_h.to_json(*options)
+    end
+
+    # Provides a string representation of the entity.
+    def inspect
+      "#<#{self.class.name}:#{object_id} @attributes=#{@attributes.inspect}>"
+    end
+
+    # Saves changes to the entity back to the API.
+    # Returns self on success for method chaining.
+    def save
+      return self if id.nil? # Can't save without an ID
+
+      # Determine the collection name from the class name
+      collection_name = ActiveSupport::Inflector.tableize(self.class.name.split("::").last).to_sym
+
+      # Check if the client responds to the collection method
+      if client.respond_to?(collection_name)
+        # Use the collection proxy to update the entity
+        updated_data = client.send(collection_name).update(id, attributes)
+
+        # Update local attributes with the response data
+        @attributes = updated_data.attributes if updated_data
+      else
+        warn "Warning: Client does not respond to collection '#{collection_name}' for saving entity."
+      end
+
+      self # Return self for method chaining
+    end
+
+    # Updates attributes and saves the entity in one step.
+    # Returns self on success for method chaining.
+    def update(new_attributes)
+      # Update attributes
+      new_attributes.each do |key, value|
+        send("#{key}=", value) if respond_to?("#{key}=")
+      end
+
+      # Save changes
+      save
+    end
+
+    # Deletes the entity from the API.
+    # Returns true on success, false on failure.
+    def destroy
+      return false if id.nil? # Can't destroy without an ID
+
+      # Determine the collection name from the class name
+      collection_name = ActiveSupport::Inflector.tableize(self.class.name.split("::").last).to_sym
+
+      # Check if the client responds to the collection method
+      if client.respond_to?(collection_name)
+        # Use the collection proxy to delete the entity
+        client.send(collection_name).delete(id)
+        true
+      else
+        warn "Warning: Client does not respond to collection '#{collection_name}' for destroying entity."
+        false
+      end
+    end
+
+    # Reloads the entity from the API.
+    # Returns self on success for method chaining.
+    def reload
+      return self if id.nil? # Can't reload without an ID
+
+      # Determine the collection name from the class name
+      collection_name = ActiveSupport::Inflector.tableize(self.class.name.split("::").last).to_sym
+
+      # Check if the client responds to the collection method
+      if client.respond_to?(collection_name)
+        # Use the collection proxy to find the entity
+        reloaded = client.send(collection_name).find(id)
+
+        # Update attributes with the reloaded data
+        @attributes = reloaded.attributes if reloaded
+      else
+        warn "Warning: Client does not respond to collection '#{collection_name}' for reloading entity."
+      end
+
+      self # Return self for method chaining
+    end
+
+    # Helper method to fetch associated objects based on data in attributes.
+    # Uses memoization to avoid repeated API calls.
+    # association_name: Symbol representing the association (e.g., :project, :customer).
+    # target_class_name_override: String specifying the target class if it differs
+    #                             from the classified association name (e.g., "Company" for :customer).
+    def association(association_name, target_class_name_override = nil)
+      # Initialize cache if it doesn't exist
+      @_association_cache ||= {}
+      # Return cached object if available
+      return @_association_cache[association_name] if @_association_cache.key?(association_name)
+
+      association_data = attributes[association_name]
+
+      # If data is already a BaseEntity object (processed during initialization), use it directly.
+      return @_association_cache[association_name] = association_data if association_data.is_a?(MOCO::BaseEntity)
+
+      # If data is a hash containing an ID, fetch the object.
+      if association_data.is_a?(Hash) && association_data[:id]
+        assoc_id = association_data[:id]
+        target_class_name = target_class_name_override || ActiveSupport::Inflector.classify(association_name.to_s)
+        collection_name = ActiveSupport::Inflector.tableize(target_class_name).to_sym # e.g., "Project" -> :projects
+
+        # Check if the client responds to the collection method (e.g., client.projects)
+        if client.respond_to?(collection_name)
+          # Fetch the object using the appropriate collection proxy
+          fetched_object = client.send(collection_name).find(assoc_id)
+          return @_association_cache[association_name] = fetched_object
+        else
+          warn "Warning: Client does not respond to collection '#{collection_name}' for association '#{association_name}'."
+          return @_association_cache[association_name] = nil
+        end
+      end
+
+      # If data is not an object or a hash with an ID, return nil.
+      @_association_cache[association_name] = nil
+    end
+
+    # Helper method to fetch associated collections based on a foreign key.
+    # Uses memoization to avoid repeated API calls.
+    # association_name: Symbol representing the association (e.g., :tasks, :activities).
+    # foreign_key: Symbol representing the foreign key to use (e.g., :project_id).
+    # target_class_name_override: String specifying the target class if it differs
+    #                             from the classified association name (e.g., "Task" for :tasks).
+    # nested: Boolean indicating if this is a nested resource (e.g., project.tasks)
+    def has_many(association_name, foreign_key = nil, target_class_name_override = nil, nested = false)
+      # Initialize cache if it doesn't exist
+      @_association_cache ||= {}
+      # Return cached collection if available
+      return @_association_cache[association_name] if @_association_cache.key?(association_name)
+
+      # If the association data is already in attributes and is an array of entities
+      # AND this is NOT a nested resource, use it directly
+      # For nested resources, we always create a proxy to ensure CRUD operations work
+      association_data = attributes[association_name]
+      if !nested && association_data.is_a?(Array) && association_data.all? { |item| item.is_a?(MOCO::BaseEntity) }
+        return @_association_cache[association_name] = association_data
+      end
+
+      # Otherwise, fetch the collection from the API
+      target_class_name = target_class_name_override || ActiveSupport::Inflector.classify(association_name.to_s)
+      collection_name = ActiveSupport::Inflector.tableize(target_class_name).to_sym # e.g., "Task" -> :tasks
+
+      # Determine the foreign key to use
+      fk = foreign_key || :"#{ActiveSupport::Inflector.underscore(self.class.name.split("::").last)}_id"
+
+      # Check if this is a nested resource
+      if nested
+        # For nested resources, create a NestedCollectionProxy
+        @_association_cache[association_name] = MOCO::NestedCollectionProxy.new(
+          client,
+          self,
+          collection_name,
+          target_class_name
+        )
+      elsif client.respond_to?(collection_name)
+        # For regular resources, use the standard collection proxy with a filter
+        @_association_cache[association_name] = client.send(collection_name).where(fk => id)
+      else
+        warn "Warning: Client does not respond to collection '#{collection_name}' for association '#{association_name}'."
+        @_association_cache[association_name] = []
+      end
+    end
+
+    private
+
+    # Defines getter and setter methods for each key in the @attributes hash.
+    def define_attribute_methods
+      attributes.each_key do |key|
+        # Skip if the key is nil or a method with this name already exists.
+        next if key.nil? || respond_to?(key)
+
+        define_singleton_method(key) { attributes[key] }
+        define_singleton_method("#{key}=") { |v| attributes[key] = process_value(v, key) } # Process assigned value too
+      end
+    end
+
+    # Recursively processes a value from the API response.
+    # - Hashes representing known entities are converted to Entity instances.
+    # - Other Hashes have their values processed recursively.
+    # - Arrays have their items processed recursively.
+    # - Primitives are returned as is.
+    # key_hint: The key under which this value was found in its parent Hash.
+    def process_value(value, key_hint = nil)
+      case value
+      when Hash
+        # Check if this hash represents a known MOCO entity class
+        klass = entity_class_for(value, key_hint)
+        if klass
+          # If yes, create an instance of that class (recursive initialize)
+          klass.new(client, value)
+        else
+          # If no, treat as a generic hash: process its values recursively
+          value.transform_keys(&:to_sym)
+               .each_with_object({}) do |(k, v), acc|
+                 # Pass the key 'k' as a hint for nested processing
+                 acc[k] = process_value(v, k)
+               end
+        end
+      when Array
+        # Recursively process each item in the array.
+        # Pass a singularized key_hint if available (e.g., :tasks -> :task)
+        singular_hint = key_hint ? ActiveSupport::Inflector.singularize(key_hint.to_s).to_sym : nil
+        value.map { |item| process_value(item, singular_hint) }
+      else
+        # Return primitive values (String, Integer, Boolean, nil, etc.) as is
+        value
+      end
+    end
+
+    # Determines the specific MOCO::Entity class for a given hash, if possible.
+    # Returns the class constant or nil if no specific entity type is identified.
+    # data: The hash to analyze.
+    # key_hint: The key under which this hash was found in its parent.
+    def entity_class_for(data, key_hint = nil)
+      # data is always a Hash when called from process_value
+      type_name = data[:type] || data["type"]
+
+      # Infer type from the key_hint if :type attribute is missing
+      if type_name.nil? && key_hint
+        # Special cases: map certain keys to specific entity classes
+        type_name = case key_hint
+                    when :customer
+                      "Company"
+                    when :leader, :co_leader, :user
+                      "User"
+                    else
+                      # General case: singularize the key hint (e.g., :tasks -> "task")
+                      ActiveSupport::Inflector.singularize(key_hint.to_s)
+                    end
+      end
+
+      # If no type name could be determined, it's not a known entity structure
+      return nil unless type_name
+
+      # Convert type name (e.g., "project", "user", "company", "Task") to class name
+      # If type_name is already classified (like "Company" from the special case),
+      # classify won't hurt it.
+      class_name = ActiveSupport::Inflector.classify(type_name)
+
+      # Check if the class exists within the MOCO module and is a BaseEntity subclass
+      if MOCO.const_defined?(class_name, false)
+        klass = MOCO.const_get(class_name)
+        return klass if klass.is_a?(Class) && klass <= MOCO::BaseEntity
+      end
+
+      # Fallback: No matching entity class found
+      nil
+    end
+  end
+end

data/lib/moco/entities/company.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO company (customer)
+  # Provides methods for company-specific associations
+  class Company < BaseEntity
+    # Associations
+    def projects
+      has_many(:projects)
+    end
+
+    def invoices
+      has_many(:invoices)
+    end
+
+    def deals
+      has_many(:deals)
+    end
+
+    def contacts
+      has_many(:contacts)
+    end
+
+    def to_s
+      name
+    end
+  end
+end

data/lib/moco/entities/deal.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO deal
+  # Provides methods for deal-specific associations
+  class Deal < BaseEntity
+    # Associations
+    def company
+      association(:company) || association(:customer, "Company")
+    end
+
+    def user
+      association(:user)
+    end
+
+    def category
+      association(:category, "DealCategory")
+    end
+
+    def to_s
+      "#{name} (#{company&.name})"
+    end
+  end
+end

data/lib/moco/entities/expense.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO expense
+  # Provides methods for expense-specific operations and associations
+  class Expense < BaseEntity
+    # Override entity_path to use the global expenses endpoint
+    # Note: Expenses can also be accessed via projects/{id}/expenses
+    def self.entity_path
+      "projects/expenses"
+    end
+
+    # Class methods for bulk operations
+    def self.disregard(client, expense_ids:)
+      client.post("projects/expenses/disregard", { expense_ids: })
+    end
+
+    def self.bulk_create(client, project_id, expenses)
+      client.post("projects/#{project_id}/expenses/bulk", { expenses: })
+    end
+
+    # Associations
+    def project
+      # Use the association method which handles embedded objects
+      association(:project, "Project")
+    end
+
+    def user
+      # Use the association method which handles embedded objects
+      association(:user, "User")
+    end
+
+    def to_s
+      "#{date} - #{title} (#{amount})"
+    end
+  end
+end

data/lib/moco/entities/holiday.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO holiday entry
+  # Provides methods for holiday-specific associations
+  class Holiday < BaseEntity
+    # Override entity_path to match API path
+    def self.entity_path
+      "users/holidays"
+    end
+
+    # Associations
+    def user
+      @user ||= client.users.find(user_id) if user_id
+    end
+
+    def creator
+      @creator ||= client.users.find(creator_id) if creator_id
+    end
+
+    def to_s
+      "#{year} - #{title} - #{days} days (#{hours} hours) - #{user&.full_name}"
+    end
+  end
+end

data/lib/moco/entities/invoice.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO invoice
+  # Provides methods for invoice-specific operations and associations
+  class Invoice < BaseEntity
+    # Instance methods for invoice-specific operations
+    def update_status(status)
+      client.put("invoices/#{id}/update_status", { status: })
+      self
+    end
+
+    def pdf
+      client.get("invoices/#{id}.pdf")
+    end
+
+    def timesheet
+      client.get("invoices/#{id}/timesheet")
+    end
+
+    def timesheet_pdf
+      client.get("invoices/#{id}/timesheet.pdf")
+    end
+
+    def expenses
+      client.get("invoices/#{id}/expenses")
+    end
+
+    def send_email(recipient:, subject:, text:, **options)
+      payload = {
+        recipient:,
+        subject:,
+        text:
+      }.merge(options)
+
+      client.post("invoices/#{id}/send_email", payload)
+      self
+    end
+
+    # Associations
+    def company
+      association(:customer, "Company")
+    end
+
+    def project
+      association(:project)
+    end
+
+    def to_s
+      "#{identifier} - #{title} (#{date})"
+    end
+  end
+end

data/lib/moco/entities/planning_entry.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO planning entry
+  # Provides methods for planning entry-specific associations
+  class PlanningEntry < BaseEntity
+    # Associations
+    def user
+      @user ||= client.users.find(user_id) if user_id
+    end
+
+    def project
+      @project ||= client.projects.find(project_id) if project_id
+    end
+
+    def deal
+      @deal ||= client.deals.find(deal_id) if deal_id
+    end
+
+    def to_s
+      period = starts_on == ends_on ? starts_on : "#{starts_on} to #{ends_on}"
+      resource = project || deal
+      "#{period} - #{hours_per_day}h/day - #{user&.full_name} - #{resource&.name}"
+    end
+  end
+end

data/lib/moco/entities/presence.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO presence entry
+  # Provides methods for presence-specific operations and associations
+  class Presence < BaseEntity
+    # Define the specific API path for this entity as a class method
+    def self.entity_path
+      "users/presences"
+    end
+
+    # Class methods for special operations
+    def self.touch(client, is_home_office: false, override: nil)
+      payload = {}
+      payload[:is_home_office] = is_home_office if is_home_office
+      payload[:override] = override if override
+
+      client.post("users/presences/touch", payload)
+    end
+
+    # Associations
+    def user
+      @user ||= client.users.find(user_id) if user_id
+    end
+
+    def to_s
+      "#{date} - #{from} to #{to} - #{user&.full_name}"
+    end
+  end
+end

data/lib/moco/entities/project.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MOCO
+  class Project < BaseEntity
+    def customer
+      # Use the association method to fetch the customer
+      association(:customer, "Company")
+    end
+
+    def leader
+      # Use the association method to fetch the leader
+      association(:leader, "User")
+    end
+
+    def co_leader
+      # Use the association method to fetch the co_leader
+      association(:co_leader, "User")
+    end
+
+    # Fetches activities associated with this project.
+    def activities
+      # Use the has_many method to fetch activities
+      has_many(:activities)
+    end
+
+    # Fetches expenses associated with this project.
+    def expenses
+      # Don't cache the proxy - create a fresh one each time
+      # This ensures we get fresh data when expenses are created/updated/deleted
+      MOCO::NestedCollectionProxy.new(client, self, :expenses, "Expense")
+    end
+
+    # Fetches tasks associated with this project.
+    def tasks
+      # Don't cache the proxy - create a fresh one each time
+      # This ensures we get fresh data when tasks are created/updated/deleted
+      MOCO::NestedCollectionProxy.new(client, self, :tasks, "Task")
+    end
+
+    def to_s
+      "Project #{identifier} \"#{name}\" (#{id})"
+    end
+
+    def active?
+      status == "active"
+    end
+  end
+end

data/lib/moco/entities/schedule.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO schedule entry
+  # Provides methods for schedule-specific associations
+  class Schedule < BaseEntity
+    # Associations
+    def user
+      @user ||= client.users.find(user_id) if user_id
+    end
+
+    def assignment
+      return nil unless assignment_id
+
+      @assignment ||= if assignment_type == "Absence"
+                        client.absences.find(assignment_id)
+                      else
+                        client.projects.find(assignment_id)
+                      end
+    end
+
+    def to_s
+      "#{date} - #{user&.full_name} - #{assignment&.name}"
+    end
+  end
+end

data/lib/moco/entities/task.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO task
+  # Provides methods for task-specific associations
+  class Task < BaseEntity
+    # Associations
+    def project
+      @project ||= client.projects.find(project_id) if project_id
+    end
+
+    def activities
+      client.activities.where(task_id: id)
+    end
+
+    def to_s
+      name
+    end
+  end
+end

data/lib/moco/entities/user.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO user
+  # Provides methods for user-specific operations and associations
+  class User < BaseEntity
+    # Instance methods for user-specific operations
+    def performance_report
+      client.get("users/#{id}/performance_report")
+    end
+
+    # Associations
+    def activities
+      has_many(:activities)
+    end
+
+    def presences
+      has_many(:presences)
+    end
+
+    def holidays
+      has_many(:holidays)
+    end
+
+    def full_name
+      "#{firstname} #{lastname}"
+    end
+
+    def to_s
+      full_name
+    end
+  end
+end