moco-ruby 1.0.0 → 1.2.0

data/lib/moco/entities/reports/finance.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MOCO
+  module Reports
+    # Represents a MOCO finance report (read-only)
+    class Finance < BaseEntity
+      def self.entity_path
+        "report/finance"
+      end
+
+      def to_s
+        "FinanceReport"
+      end
+    end
+  end
+end

data/lib/moco/entities/reports/utilization.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MOCO
+  module Reports
+    # Represents a MOCO utilization report (read-only)
+    class Utilization < BaseEntity
+      def self.entity_path
+        "report/utilization"
+      end
+
+      def to_s
+        "UtilizationReport"
+      end
+    end
+  end
+end

data/lib/moco/entities/schedule.rb

@@ -1,8 +1,45 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO schedule entry
-  # Provides methods for schedule-specific associations
+  # Represents a MOCO schedule entry (absence/time-off)
+  # Note: For project planning, use PlanningEntry instead
+  #
+  # == Required attributes for create:
+  #   date         - String, "YYYY-MM-DD" date of absence
+  #   absence_code - Integer, type of absence:
+  #                  1 = unplannable absence
+  #                  2 = public holiday
+  #                  3 = sick day
+  #                  4 = holiday/vacation
+  #                  5 = other absence
+  #
+  # == Optional attributes:
+  #   user_id - Integer, user ID (default: current user)
+  #   am      - Boolean, morning absence (default: true)
+  #   pm      - Boolean, afternoon absence (default: true)
+  #   comment - String, comment/note
+  #   symbol  - Integer, 1-6 for half day visualization
+  #
+  # == Read-only attributes:
+  #   id, assignment (Hash), user (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   # Full day vacation
+  #   moco.schedules.create(
+  #     date: "2024-01-15",
+  #     absence_code: 4,
+  #     user_id: 123,
+  #     comment: "Annual leave"
+  #   )
+  #
+  #   # Half day sick (morning only)
+  #   moco.schedules.create(
+  #     date: "2024-01-16",
+  #     absence_code: 3,
+  #     am: true,
+  #     pm: false
+  #   )
+  #
   class Schedule < BaseEntity
     # Associations
     def user

data/lib/moco/entities/tag.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO tag/label
+  #
+  # == Required attributes for create:
+  #   name    - String, tag name (e.g., "Important")
+  #   context - String, entity type this tag applies to:
+  #             "Project", "Contact", "Company", "Deal", "Offer",
+  #             "Invoice", "Purchase", "User"
+  #
+  # == Read-only attributes:
+  #   id, created_at, updated_at
+  #
+  # == Example:
+  #   moco.tags.create(
+  #     name: "Priority",
+  #     context: "Project"
+  #   )
+  #
+  # == Note:
+  #   To apply tags to entities, use the `tags` attribute when
+  #   creating/updating the entity: { tags: ["Tag1", "Tag2"] }
+  #
+  class Tag < BaseEntity
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/tagging.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO tagging (association between a tag and an entity)
+  # This is a read-only entity representing tag assignments.
+  #
+  # == Read-only attributes:
+  #   id, entity_id, entity_type, tag (Hash), created_at, updated_at
+  #
+  # == Note:
+  #   To apply tags to entities, use the `tags` attribute when
+  #   creating/updating the entity directly:
+  #   moco.projects.update(123, tags: ["Priority", "Important"])
+  #
+  #   See also: Tag entity for managing available tags.
+  #
+  class Tagging < BaseEntity
+    # Associations
+    def tag
+      association(:tag)
+    end
+
+    def to_s
+      "Tagging ##{id}"
+    end
+  end
+end

data/lib/moco/entities/task.rb

@@ -1,8 +1,31 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO task
-  # Provides methods for task-specific associations
+  # Represents a MOCO task (project service/activity type)
+  # Tasks are nested under projects: project.tasks.create(...)
+  #
+  # == Required attributes for create:
+  #   name - String, task name (e.g., "Development", "Design / UX")
+  #
+  # == Optional attributes:
+  #   billable    - Boolean, whether time on this task is billable
+  #   active      - Boolean, whether task is active
+  #   budget      - Float/Integer, budget in hours or currency
+  #   hourly_rate - Float/Integer, rate for this task (used if project billing_variant is "task")
+  #   description - String, task description
+  #
+  # == Read-only attributes (returned by API):
+  #   id, created_at, updated_at
+  #
+  # == Example:
+  #   project = moco.projects.find(123)
+  #   project.tasks.create(
+  #     name: "Development",
+  #     billable: true,
+  #     hourly_rate: 150,
+  #     budget: 100
+  #   )
+  #
   class Task < BaseEntity
     # Associations
     def project

data/lib/moco/entities/task_template.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO task template (Standardleistungen)
+  # Pre-defined task types for projects
+  #
+  # == Required attributes for create:
+  #   name - String, task name (e.g., "Development", "Design")
+  #
+  # == Optional attributes:
+  #   description         - String, task description
+  #   revenue_category_id - Integer, revenue category for invoicing
+  #   billable            - Boolean, whether tasks are billable by default
+  #   project_default     - Boolean, auto-add to new projects
+  #   index               - Integer, display order (e.g., 10, 20, 30)
+  #
+  # == Read-only attributes:
+  #   id, revenue_category (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   moco.task_templates.create(
+  #     name: "Backend Development",
+  #     description: "Server-side programming",
+  #     billable: true,
+  #     project_default: true,
+  #     index: 10
+  #   )
+  #
+  class TaskTemplate < BaseEntity
+    def self.entity_path
+      "account/task_templates"
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/unit.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO unit/team (Teams)
+  #
+  # == Required attributes for create:
+  #   name - String, team name (e.g., "Development Team")
+  #
+  # == Read-only attributes:
+  #   id, users (Array of user hashes), created_at, updated_at
+  #
+  # == Example:
+  #   # Create a new team
+  #   moco.units.create(name: "Marketing Team")
+  #
+  #   # Get users in a team
+  #   team = moco.units.find(123)
+  #   team.users  # => Array of User objects
+  #
+  # == Note:
+  #   To assign users to a team, update the user with unit_id:
+  #   moco.users.update(user_id, unit_id: team.id)
+  #
+  #   Deleting a unit is only possible if no users are assigned to it.
+  #
+  class Unit < BaseEntity
+    # Get users belonging to this unit
+    def users
+      has_many(:users, :unit_id)
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/user.rb

@@ -1,8 +1,44 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO user
-  # Provides methods for user-specific operations and associations
+  # Represents a MOCO user (staff member)
+  #
+  # == Required attributes for create:
+  #   firstname - String, first name
+  #   lastname  - String, last name
+  #   email     - String, email address (used for login)
+  #   unit_id   - Integer, team/unit ID
+  #
+  # == Optional attributes:
+  #   password     - String, initial password (if not set, user gets welcome email)
+  #   role_id      - Integer, permission role ID
+  #   active       - Boolean, whether user is active
+  #   external     - Boolean, true for contractors/external staff
+  #   language     - String, one of: "de", "de-AT", "de-CH", "en", "it", "fr"
+  #   mobile_phone - String, mobile phone number
+  #   work_phone   - String, work phone number
+  #   home_address - String, home address (use \n for line breaks)
+  #   bday         - String, birthday "YYYY-MM-DD"
+  #   iban         - String, bank account IBAN
+  #   tags         - Array of Strings, e.g., ["Developer", "Remote"]
+  #   custom_properties - Hash, e.g., {"Start Date": "2024-01-01"}
+  #   info         - String, additional notes
+  #   welcome_email - Boolean, send welcome email (default: true if no password)
+  #   avatar       - Hash, { filename: "photo.jpg", base64: "..." }
+  #
+  # == Read-only attributes:
+  #   id, avatar_url, unit (Hash), role (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   moco.users.create(
+  #     firstname: "John",
+  #     lastname: "Doe",
+  #     email: "john.doe@company.com",
+  #     unit_id: 123,
+  #     language: "en",
+  #     tags: ["Developer"]
+  #   )
+  #
   class User < BaseEntity
     # Instance methods for user-specific operations
     def performance_report
@@ -22,6 +58,18 @@ module MOCO
       has_many(:holidays)
     end
 
+    def employments
+      has_many(:employments)
+    end
+
+    def work_time_adjustments
+      has_many(:work_time_adjustments)
+    end
+
+    def unit
+      association(:unit)
+    end
+
     def full_name
       "#{firstname} #{lastname}"
     end

data/lib/moco/entities/user_role.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO user permission role
+  # Read-only list of available permission roles
+  #
+  # == Read-only attributes:
+  #   id, name, created_at, updated_at
+  #
+  # == Common roles:
+  #   - Admin
+  #   - Manager
+  #   - Coworker
+  #   - etc.
+  #
+  # == Note:
+  #   Permission roles are configured in MOCO's admin interface.
+  #   Use role_id when creating/updating users to assign a role.
+  #
+  class UserRole < BaseEntity
+    def self.entity_path
+      "users/roles"
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/vat_code_purchase.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO purchase VAT code (Steuerschlüssel Einkauf)
+  # Read-only VAT rates for purchases/receipts
+  #
+  # == Read-only attributes:
+  #   id, code, tax, reverse_charge, intra_eu, active
+  #
+  # == Filtering:
+  #   moco.vat_code_purchases.where(active: true)
+  #   moco.vat_code_purchases.where(reverse_charge: true)
+  #   moco.vat_code_purchases.where(intra_eu: true)
+  #   moco.vat_code_purchases.where(ids: "123,456")
+  #
+  # == Note:
+  #   VAT codes are configured in MOCO's admin interface.
+  #   Use vat_code_id when creating purchases/receipts.
+  #
+  class VatCodePurchase < BaseEntity
+    def self.entity_path
+      "vat_code_purchases"
+    end
+
+    def to_s
+      "#{code} - #{name}"
+    end
+  end
+end

data/lib/moco/entities/vat_code_sale.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO sales VAT code (Steuerschlüssel Verkauf)
+  # Read-only VAT rates for invoices/offers
+  #
+  # == Read-only attributes:
+  #   id, code, tax, reverse_charge, intra_eu, active,
+  #   print_gross_total, notice_tax_exemption, credit_account
+  #
+  # == Filtering:
+  #   moco.vat_code_sales.where(active: true)
+  #   moco.vat_code_sales.where(reverse_charge: true)
+  #   moco.vat_code_sales.where(intra_eu: true)  # EU intra-community
+  #
+  # == Note:
+  #   VAT codes are configured in MOCO's admin interface.
+  #   Use vat_code_id when creating invoices/offers.
+  #
+  class VatCodeSale < BaseEntity
+    def self.entity_path
+      "vat_code_sales"
+    end
+
+    def to_s
+      "#{code} - #{name}"
+    end
+  end
+end

data/lib/moco/entities/web_hook.rb

@@ -1,8 +1,38 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO webhook
-  # Provides methods for webhook-specific operations
+  # Represents a MOCO webhook for event notifications
+  #
+  # == Required attributes for create:
+  #   target - String, entity type to watch:
+  #            "Activity", "Company", "Contact", "Project",
+  #            "Invoice", "Offer", "Deal", "Expense"
+  #   event  - String, event type: "create", "update", "delete"
+  #   hook   - String, URL to receive webhook payloads (e.g., "https://example.org/callback")
+  #
+  # == Read-only attributes:
+  #   id, disabled, disabled_at, created_at, updated_at
+  #
+  # == Instance methods:
+  #   enable   - Enable the webhook
+  #   disable  - Disable the webhook
+  #
+  # == Example:
+  #   # Create webhook for new activities
+  #   moco.web_hooks.create(
+  #     target: "Activity",
+  #     event: "create",
+  #     hook: "https://example.org/moco-activity-webhook"
+  #   )
+  #
+  #   # Disable a webhook
+  #   webhook = moco.web_hooks.find(123)
+  #   webhook.disable
+  #
+  # == Note:
+  #   Only the `hook` URL can be updated after creation.
+  #   To change target/event, delete and recreate the webhook.
+  #
   class WebHook < BaseEntity
     # Override entity_path to match API path
     def self.entity_path

data/lib/moco/entities/work_time_adjustment.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO user work time adjustment record
+  # (Korrekturen Zeiterfassung) for overtime/undertime corrections
+  #
+  # == Required attributes for create:
+  #   user_id     - Integer, user to adjust
+  #   date        - String, "YYYY-MM-DD" effective date
+  #   description - String, reason for adjustment
+  #   hours       - Float, hours to add (positive) or subtract (negative)
+  #
+  # == Read-only attributes:
+  #   id, user (Hash), creator (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   # Add overtime from previous year
+  #   moco.work_time_adjustments.create(
+  #     user_id: 123,
+  #     date: "2024-01-01",
+  #     description: "Overtime carryover from 2023",
+  #     hours: 42.0
+  #   )
+  #
+  #   # Correct time balance
+  #   moco.work_time_adjustments.create(
+  #     user_id: 123,
+  #     date: "2024-06-15",
+  #     description: "Correction for unpaid leave",
+  #     hours: -16.0
+  #   )
+  #
+  # == Filtering:
+  #   moco.work_time_adjustments.where(user_id: 123)
+  #   moco.work_time_adjustments.where(from: "2024-01-01", to: "2024-12-31")
+  #
+  class WorkTimeAdjustment < BaseEntity
+    def self.entity_path
+      "users/work_time_adjustments"
+    end
+
+    # Associations
+    def user
+      association(:user)
+    end
+
+    def to_s
+      "WorkTimeAdjustment ##{id} (#{date})"
+    end
+  end
+end

data/lib/moco/sync.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "set"
 require "fuzzy_match"
 require_relative "client"
 
@@ -17,12 +18,15 @@ module MOCO
       @filters = args.fetch(:filters, {})
       @dry_run = args.fetch(:dry_run, false)
       @debug = args.fetch(:debug, false)
+      @default_task_name = args.fetch(:default_task_name, nil)
 
       @project_mapping = {}
       @task_mapping = {}
+      @default_task_cache = {} # Cache default tasks per project
 
       fetch_assigned_projects
       build_initial_mappings
+      create_missing_tasks_for_activities
     end
 
     # rubocop:todo Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -420,6 +424,110 @@ module MOCO
       end
     end
 
+    def create_missing_tasks_for_activities
+      # Fetch source activities to see which tasks are actually used
+      source_activity_filters = @filters.fetch(:source, {})
+      source_activities = @source.activities.where(source_activity_filters).all
+
+      # Collect unique task IDs that are used in activities and need syncing
+      tasks_needed = Set.new
+      source_activities.each do |activity|
+        # Only consider activities for mapped projects
+        next unless @project_mapping[activity.project&.id]
+        # Check if task is already mapped
+        next if activity.task.nil?
+        next if @task_mapping[activity.task.id]
+
+        tasks_needed.add(activity.task.id)
+      end
+
+      return if tasks_needed.empty?
+
+      debug_log "Found #{tasks_needed.size} unmapped tasks used in activities"
+
+      # Track tasks that couldn't be created due to permission errors
+      @failed_task_creations ||= []
+      @mapped_to_default ||= []
+
+      # Create missing tasks in target projects
+      tasks_needed.each do |task_id|
+        # Find the source task from source activities
+        source_activity = source_activities.find { |a| a.task&.id == task_id }
+        next unless source_activity
+
+        source_task = source_activity.task
+        source_project_id = source_activity.project.id
+        target_project = @project_mapping[source_project_id]
+
+        # If default task name is provided, try to map to it instead of creating
+        if @default_task_name
+          default_task = find_default_task(target_project)
+          if default_task
+            @task_mapping[source_task.id] = default_task
+            debug_log "  Mapped task '#{source_task.name}' -> default task '#{default_task.name}' (#{default_task.id})"
+            @mapped_to_default << {
+              task_name: source_task.name,
+              project_name: target_project.name,
+              default_task_name: default_task.name
+            }
+            next
+          else
+            warn "  WARNING: Default task '#{@default_task_name}' not found in target project '#{target_project.name}'"
+            warn "           Will attempt to create task '#{source_task.name}' instead"
+          end
+        end
+
+        debug_log "  Creating missing task '#{source_task.name}' in target project #{target_project.id} (#{target_project.name})"
+
+        unless @dry_run
+          begin
+            # Create the task in the target project
+            # Tasks used in activities must be active
+            # Use NestedCollectionProxy to create the task
+            task_proxy = MOCO::NestedCollectionProxy.new(@target, target_project, :tasks, "Task")
+            new_task = task_proxy.create(
+              name: source_task.name,
+              billable: source_task.billable,
+              active: true
+            )
+
+            # Add to mapping
+            @task_mapping[source_task.id] = new_task
+            debug_log "    Created task #{new_task.id} - #{new_task.name}"
+          rescue StandardError => e
+            # Check if this is a permission error
+            if e.message =~ /403|Forbidden|401|Unauthorized|not authorized|permission/i
+              warn "  WARNING: Cannot create task '#{source_task.name}' in target project - insufficient permissions"
+              warn "           Activities using this task will be skipped during sync"
+              @failed_task_creations << {
+                task_name: source_task.name,
+                project_name: target_project.name,
+                project_id: target_project.id
+              }
+            else
+              # Re-raise other errors
+              raise
+            end
+          end
+        else
+          debug_log "    (Dry run - would create task '#{source_task.name}')"
+        end
+      end
+    end
+
+    def find_default_task(target_project)
+      # Return cached result if available
+      return @default_task_cache[target_project.id] if @default_task_cache.key?(target_project.id)
+
+      # Search for the default task in the target project
+      default_task = target_project.tasks.find { |task| task.name == @default_task_name }
+
+      # Cache the result (even if nil)
+      @default_task_cache[target_project.id] = default_task
+
+      default_task
+    end
+
     def match_project(target_project)
       # Create array of search objects manually since we can't call map on EntityCollection
       searchable_projects = []
@@ -436,19 +544,17 @@ module MOCO
     end
 
     def match_task(target_task, source_project)
-      # Get tasks from the source project
+      # Get tasks from the source project (embedded in projects.assigned response)
       tasks = source_project.tasks
 
-      # Create array of search objects manually since we can't rely on Enumerable methods
+      # Only proceed if we have tasks to match against
+      return nil if tasks.empty?
 
-      # Manually iterate through tasks
+      # Create array of search objects for fuzzy matching
       searchable_tasks = tasks.map do |task|
         { original: task, name: task.name }
       end
 
-      # Only proceed if we have tasks to match against
-      return nil if searchable_tasks.empty?
-
       matcher = FuzzyMatch.new(searchable_tasks, read: :name)
       match = matcher.find(target_task.name, threshold: @task_match_threshold)
       match[:original] if match

data/lib/moco/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MOCO
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/moco-ruby.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# This file exists so that `gem 'moco-ruby'` auto-requires correctly.
+# Bundler converts gem names with hyphens to require paths with slashes,
+# so 'moco-ruby' looks for 'moco/ruby'. This shim redirects to the real entry point.
+require_relative "moco"