moco-ruby 0.1.2 → 1.0.0

data/examples/v2_api_example.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "moco"
+require "yaml"
+
+# Load configuration from config.yml
+config = YAML.load_file(File.join(File.dirname(__FILE__), "..", "config.yml"))
+instance = config["instances"].first
+
+# Initialize client
+moco = MOCO::Client.new(
+  subdomain: instance["subdomain"],
+  api_key: instance["api_key"]
+)
+
+puts "Connected to MOCO instance: #{instance["subdomain"]}"
+
+# Get all active projects
+puts "\nActive Projects:"
+projects = moco.projects.where(active: "true")
+projects.each do |project|
+  puts "- #{project.id}: #{project.name} (#{project.customer&.name})"
+end
+
+# Get a specific project
+if projects.any?
+  project = projects.first
+  puts "\nProject Details for #{project.name}:"
+  puts "  Customer: #{project.customer&.name}"
+
+  # Get tasks for the project
+  puts "  Tasks:"
+  project.tasks.each do |task|
+    puts "  - #{task.name} (#{task.billable ? "Billable" : "Non-billable"})"
+  end
+
+  # Get recent activities for the project
+  puts "\nRecent Activities for #{project.name}:"
+  activities = project.activities
+  activities.each do |activity|
+    puts "  - #{activity.date}: #{activity.hours}h - #{activity.description} (#{activity.user&.full_name})"
+  end
+
+  # Demonstrate chaining (commented out to avoid modifying data)
+  # project.archive.assign_to_group(123).unarchive
+end
+
+# Get users
+puts "\nUsers:"
+users = moco.users.all
+users.each do |user|
+  puts "- #{user.id}: #{user.full_name}"
+end
+
+# Dynamic access to any collection
+puts "\nDemonstrating dynamic collection access:"
+collections = %w[companies deals invoices expenses schedules presences holidays planning_entries]
+collections.each do |collection|
+  if moco.respond_to?(collection)
+    count = begin
+      moco.send(collection).count
+    rescue StandardError
+      0
+    end
+    puts "- #{collection}: #{count} items"
+  else
+    puts "- #{collection}: not available"
+  end
+end
+
+puts "\nExample completed successfully!"

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:, debug: false)
+      @connection = Connection.new(self, subdomain, api_key, debug: debug)
+      @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,200 @@
+# 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
+
+    # Modifies the base path to fetch assigned resources. Returns self.
+    def assigned
+      # Ensure this is only called once or handle idempotency if needed
+      @base_path += "/assigned"
+      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.
+
+      # Filter out nil values before sending to avoid empty params like ?from&to=
+      query_params.compact!
+
+      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,68 @@
+# 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, :debug
+
+    def initialize(client, subdomain, api_key, debug: false)
+      @client = client
+      @subdomain = subdomain
+      @api_key = api_key
+      @debug = debug
+      @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 = {}|
+        # Log URL if debug is enabled
+        if @debug
+          full_url = @conn.build_url(path, params).to_s
+          warn "[DEBUG] Fetching URL: #{http_method.upcase} #{full_url}"
+        end
+        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,101 @@
+# 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
+
+    # Access the remote_id attribute
+    def remote_id
+      attributes[:remote_id]
+    end
+
+    def to_s
+      "#{attributes[:date]} - #{attributes[:hours]}h - #{project&.name} - #{task&.name} - #{attributes[:description]}"
+    end
+  end
+end