moco-ruby 0.1.1 → 1.0.0.alpha

data/lib/moco/client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Main client class for interacting with the MOCO API
+  # Provides dynamic access to all API endpoints through method_missing
+  class Client
+    attr_reader :connection
+
+    def initialize(subdomain:, api_key:)
+      @connection = Connection.new(self, subdomain, api_key)
+      @collections = {}
+    end
+
+    # Dynamically handle entity collection access (e.g., client.projects)
+    def method_missing(name, *args, &)
+      # Check if the method name corresponds to a known plural entity type
+      if collection_name?(name)
+        # Return a CollectionProxy directly for chainable queries
+        # Cache it so subsequent calls return the same proxy instance
+        @collections[name] ||= CollectionProxy.new(
+          self,
+          name.to_s, # Pass the plural name (e.g., "projects") as the path hint
+          ActiveSupport::Inflector.classify(name.to_s) # Get class name (e.g., "Project")
+        )
+      else
+        # Delegate to superclass for non-collection methods
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      collection_name?(name) || super
+    end
+
+    # Check if the method name looks like a collection name (plural)
+    def collection_name?(name)
+      name.to_s == ActiveSupport::Inflector.pluralize(name.to_s)
+    end
+
+    # Delegate HTTP methods to connection
+    %i[get post put patch delete].each do |method|
+      define_method(method) do |path, params = {}|
+        connection.send(method, path, params)
+      end
+    end
+  end
+end

data/lib/moco/collection_proxy.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Provides ActiveRecord-style query interface for MOCO entities
+  class CollectionProxy
+    include Enumerable
+    attr_reader :client, :entity_class_name, :filters, :limit_value
+
+    def initialize(client, path_or_entity_name, entity_class_name)
+      @client = client
+      @entity_class_name = entity_class_name
+      @entity_class = load_entity_class # Load and store the class
+      @base_path = determine_base_path(path_or_entity_name)
+      @filters = {} # Store query filters
+      @limit_value = nil # Store limit for methods like first/find_by
+      @loaded = false # Flag to track if data has been fetched
+      @records = [] # Cache for fetched records
+    end
+
+    def load_entity_class
+      # Ensure ActiveSupport::Inflector is available if not already loaded globally
+      require "active_support/inflector" unless defined?(ActiveSupport::Inflector)
+
+      entity_file_name = ActiveSupport::Inflector.underscore(entity_class_name)
+      entity_file_path = "entities/#{entity_file_name}" # Path relative to lib/moco/
+      begin
+        # Use require_relative from the current file's directory
+        require_relative entity_file_path
+        MOCO.const_get(entity_class_name)
+      rescue LoadError
+        warn "Warning: Could not load entity file at #{entity_file_path}. Using BaseEntity."
+        MOCO::BaseEntity # Fallback
+      rescue NameError
+        warn "Warning: Could not find entity class #{entity_class_name}. Using BaseEntity."
+        MOCO::BaseEntity # Fallback
+      end
+    end
+
+    # Removed method_missing and respond_to_missing? as they are not
+    # currently used for building nested paths in this implementation.
+
+    # --- Chainable Methods ---
+
+    # Adds filters to the query. Returns self for chaining.
+    def where(conditions = {})
+      # TODO: Implement proper merging/handling of existing filters if called multiple times
+      @filters.merge!(conditions)
+      self # Return self to allow chaining like client.projects.where(active: true).where(...)
+    end
+
+    # Sets a limit on the number of records to fetch. Returns self.
+    def limit(value)
+      @limit_value = value
+      self
+    end
+
+    # --- Methods Triggering API Call ---
+
+    # Fetches all records matching the current filters.
+    # Caches the result.
+    def all
+      load_records unless loaded?
+      @records
+    end
+
+    # Fetches a specific record by ID. Does not use current filters or limit.
+    def find(id)
+      # Ensure entity_class is loaded and valid before calling new
+      klass = entity_class
+      return nil unless klass && klass <= MOCO::BaseEntity
+
+      # Directly fetch by ID, bypassing stored filters/limit
+      response = client.get("#{@base_path}/#{id}")
+      # wrap_response now returns an array even for single results
+      result_array = wrap_response(response)
+      # Return the single entity or nil if not found (or if response was not a hash)
+      result_array.first
+    end
+
+    # NOTE: The duplicated 'where' method definition below is removed.
+    # The correct 'where' method is defined earlier in the class.
+
+    # Fetches the first record matching the current filters.
+    def first
+      limit(1).load_records unless loaded? && @limit_value == 1
+      @records.first
+    end
+
+    # Finds the first record matching the given attributes.
+    def find_by(conditions)
+      where(conditions).first
+    end
+
+    # Executes the query and yields each record.
+    def each(&)
+      load_records unless loaded?
+      @records.each(&)
+    end
+
+    # --- Persistence Methods (Pass-through) ---
+    # These don't typically belong on the relation/proxy but are kept for now.
+    # Consider moving them or ensuring they operate correctly in this context.
+
+    def create(attributes)
+      klass = entity_class
+      return nil unless klass && klass <= MOCO::BaseEntity
+
+      klass.new(client, client.post(@base_path, attributes))
+    end
+
+    def update(id, attributes)
+      klass = entity_class
+      return nil unless klass && klass <= MOCO::BaseEntity
+
+      klass.new(client, client.put("#{@base_path}/#{id}", attributes))
+    end
+
+    def delete(id)
+      client.delete("#{@base_path}/#{id}")
+    end
+
+    # --- Internal Methods ---
+
+    # Executes the API request based on current filters and limit.
+    # Populates @records and sets @loaded flag.
+    # Needs to be public for methods like first, each, find_by to call it.
+    def load_records
+      query_params = @filters.dup
+      query_params[:limit] = @limit_value if @limit_value
+      # MOCO API might use 'per_page' instead of 'limit' for pagination control
+      # Adjust if necessary based on API docs. Assuming 'limit' works for now.
+
+      response = client.get(@base_path, query_params)
+      @records = wrap_response(response) # wrap_response should return an Array here
+      @loaded = true
+      @records # Return the loaded records
+    end
+
+    protected
+
+    # Flag indicating if records have been loaded from the API.
+    def loaded?
+      @loaded
+    end
+
+    # Returns the loaded entity class constant.
+    attr_reader :entity_class
+
+    # Determines the base API path for the entity.
+    # Uses entity_path method if defined, otherwise uses the pluralized name.
+    def determine_base_path(path_or_entity_name)
+      klass = entity_class
+      # Check if the class itself responds to entity_path (class method)
+      return klass.entity_path if klass.respond_to?(:entity_path)
+
+      # Check if instances respond to entity_path (instance method)
+      # Need a dummy instance if the class is valid
+      if klass && klass <= MOCO::BaseEntity && klass.instance_methods.include?(:entity_path)
+        # We can't reliably call instance methods here without data.
+        # This indicates entity_path should likely be a class method.
+        # Falling back to default path generation.
+        warn "Warning: entity_path is defined as an instance method on #{klass.name}. It should ideally be a class method. Falling back to default path."
+      end
+
+      # Fallback: Use the pluralized/tableized version of the entity name or the provided path.
+      ActiveSupport::Inflector.tableize(path_or_entity_name.to_s)
+    end
+
+    private
+
+    # Wraps the raw API response (Hash or Array of Hashes) into entity objects.
+    def wrap_response(response_body)
+      klass = entity_class
+      # Ensure we have a valid class derived from BaseEntity
+      return [] unless klass && klass <= MOCO::BaseEntity # Return empty array if class invalid
+
+      if response_body.is_a?(Array)
+        # Convert array of hashes to array of entity objects
+        response_body.map { |item_hash| klass.new(client, item_hash) if item_hash.is_a?(Hash) }.compact
+      elsif response_body.is_a?(Hash)
+        # Wrap single hash response in an array for consistency internally
+        [klass.new(client, response_body)]
+      else
+        # Handle unexpected response types (like the String error we saw)
+        warn "Warning: Unexpected API response type received in wrap_response: #{response_body.class}. Expected Hash or Array."
+        response_body # Return the unexpected body as is
+      end
+    end
+  end
+end

data/lib/moco/connection.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module MOCO
+  # Handles HTTP communication with the MOCO API
+  # Responsible for building API requests and converting responses to entity objects
+  class Connection
+    attr_reader :client, :subdomain, :api_key
+
+    def initialize(client, subdomain, api_key)
+      @client = client
+      @subdomain = subdomain
+      @api_key = api_key
+      @conn = Faraday.new do |f|
+        f.request :json
+        f.response :json
+        f.request :authorization, "Token", "token=#{@api_key}"
+        f.url_prefix = "https://#{@subdomain}.mocoapp.com/api/v1"
+      end
+    end
+
+    # Define methods for HTTP verbs (get, post, put, patch, delete)
+    # These methods send the request and return the raw parsed JSON response body.
+    %w[get post put patch delete].each do |http_method|
+      define_method(http_method) do |path, params = {}|
+        response = @conn.send(http_method, path, params)
+
+        # Raise an error for non-successful responses
+        unless response.success?
+          # Attempt to parse error details from the body, otherwise use status/reason
+          error_details = response.body.is_a?(Hash) ? response.body["message"] : response.body
+          # Explicitly pass nil for original_error, and response for the third argument
+          # raise MOCO::Error.new("MOCO API Error: #{response.status} #{response.reason_phrase}. Details: #{error_details}",
+          #                       nil, response)
+          # Use RuntimeError for now
+          raise "MOCO API Error: #{response.status} #{response.reason_phrase}. Details: #{error_details}"
+        end
+
+        response.body
+      rescue Faraday::Error => e
+        # Wrap Faraday errors - pass e as the second argument (original_error)
+        # raise MOCO::Error.new("Faraday Connection Error: #{e.message}", e)
+        # Use RuntimeError for now
+        raise "Faraday Connection Error: #{e.message}"
+      end
+    end
+
+    # Define a custom error class for MOCO API errors
+    # Temporarily commented out
+    # class Error < StandardError
+    #   attr_reader :original_error, :response
+    #
+    #   def initialize(message, original_error = nil, response = nil)
+    #     super(message)
+    #     @original_error = original_error
+    #     @response = response
+    #   end
+    # end
+  end
+end

data/lib/moco/entities/activity.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO activity (time entry)
+  # Provides methods for activity-specific operations and associations
+  class Activity < BaseEntity
+    # Instance methods for activity-specific operations
+    def start_timer
+      client.patch("activities/#{id}/start_timer")
+      self
+    end
+
+    def stop_timer
+      client.patch("activities/#{id}/stop_timer")
+      self
+    end
+
+    # Class methods for bulk operations
+    def self.disregard(client, reason:, activity_ids:, company_id:, project_id: nil)
+      payload = {
+        reason:,
+        activity_ids:,
+        company_id:
+      }
+      payload[:project_id] = project_id if project_id
+      client.post("activities/disregard", payload)
+    end
+
+    def self.bulk_create(client, activities)
+      api_entities = activities.map do |activity|
+        activity.to_h.except(:id, :project, :user, :customer).tap do |h|
+          h[:project_id] = activity.project.id if activity.project
+          h[:task_id] = activity.task.id if activity.task
+        end
+      end
+      client.post("activities/bulk", { activities: api_entities })
+    end
+
+    # Associations
+    # Fetches the associated Project object.
+    def project
+      # Check if the project attribute is a hash (contains ID) or already an object
+      project_data = attributes[:project]
+      return @project if defined?(@project) # Return memoized object if already fetched
+
+      @project = if project_data.is_a?(Hash) && project_data[:id]
+                   client.projects.find(project_data[:id])
+                 elsif project_data.is_a?(MOCO::Project) # If it was already processed into an object
+                   project_data
+                 else
+                   nil # No project associated or data missing
+                 end
+    end
+
+    # Fetches the associated Task object.
+    def task
+      task_data = attributes[:task]
+      return @task if defined?(@task)
+
+      @task = if task_data.is_a?(Hash) && task_data[:id]
+                client.tasks.find(task_data[:id])
+              elsif task_data.is_a?(MOCO::Task)
+                task_data
+              end
+    end
+
+    # Fetches the associated User object.
+    def user
+      user_data = attributes[:user]
+      return @user if defined?(@user)
+
+      @user = if user_data.is_a?(Hash) && user_data[:id]
+                client.users.find(user_data[:id])
+              elsif user_data.is_a?(MOCO::User)
+                user_data
+              end
+    end
+
+    # Fetches the associated Customer (Company) object.
+    def customer
+      customer_data = attributes[:customer]
+      return @customer if defined?(@customer)
+
+      @customer = if customer_data.is_a?(Hash) && customer_data[:id]
+                    # Customer association points to the 'companies' collection
+                    client.companies.find(customer_data[:id])
+                  elsif customer_data.is_a?(MOCO::Company)
+                    customer_data
+                  end
+    end
+
+    def to_s
+      "#{date} - #{hours}h - #{project&.name} - #{task&.name} - #{description}"
+    end
+  end
+end

data/lib/moco/entities/base_entity.rb

@@ -0,0 +1,303 @@
+# 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
+
+    # 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, use it directly
+      association_data = attributes[association_name]
+      if 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
+        require_relative "../nested_collection_proxy"
+        @_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 case: map :customer key to Company class
+        type_name = if key_hint == :customer
+                      "Company"
+                    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