moco-ruby 1.1.0 → 1.3.0

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/entities.rb

@@ -44,7 +44,7 @@ module MOCO
     end
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/projects.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/projects.html
   # @deprecated Use MOCO::Project from entities/project.rb instead
   class Project < BaseEntity
     attr_accessor :id, :active, :name, :customer, :tasks
@@ -54,7 +54,7 @@ module MOCO
     end
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/project_tasks.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/project_tasks.html
   # @deprecated Use MOCO::Task from entities/task.rb instead
   class Task < BaseEntity
     attr_accessor :id, :active, :name, :project_id, :billable
@@ -64,7 +64,7 @@ module MOCO
     end
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/activities.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/activities.html
   # @deprecated Use MOCO::Activity from entities/activity.rb instead
   class Activity < BaseEntity
     attr_accessor :id, :active, :date, :description, :project, :task, :seconds, :hours, :billable, :billed, :user,
@@ -79,13 +79,13 @@ module MOCO
     end
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/companies.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/companies.html
   # @deprecated Use MOCO::Company from entities/company.rb instead
   class Customer < BaseEntity
     attr_accessor :id, :name
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/users.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/users.html
   # @deprecated Use MOCO::User from entities/user.rb instead
   class User < BaseEntity
     attr_accessor :id, :firstname, :lastname

data/lib/moco/sync.rb

@@ -364,7 +364,7 @@ module MOCO
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
 
     def fetch_assigned_projects
-      # Use .projects.assigned for the source, standard .projects for the target
+      # Use .projects.assigned for both source and target to get embedded tasks
       source_filters = @filters.fetch(:source, {}).merge(active: "true")
       # Get the proxy, then fetch all results into the instance variable
       @source_projects = @source.projects.assigned.where(source_filters).all
@@ -372,19 +372,19 @@ module MOCO
       @source_projects.each do |project|
         debug_log "  Source Project: #{project.id} - #{project.name} (#{project.identifier})"
         debug_log "    Tasks:"
-        project.tasks.each do |task|
+        project.embedded_tasks.each do |task|
           debug_log "      Task: #{task.id} - #{task.name}"
         end
       end
 
       target_filters = @filters.fetch(:target, {}).merge(active: "true")
       # Get the proxy, then fetch all results into the instance variable
-      @target_projects = @target.projects.where(target_filters).all
+      @target_projects = @target.projects.assigned.where(target_filters).all
       debug_log "Found #{@target_projects.size} target projects:"
       @target_projects.each do |project|
         debug_log "  Target Project: #{project.id} - #{project.name} (#{project.identifier})"
         debug_log "    Tasks:"
-        project.tasks.each do |task|
+        project.embedded_tasks.each do |task|
           debug_log "      Task: #{task.id} - #{task.name}"
         end
       end
@@ -401,7 +401,7 @@ module MOCO
         @project_mapping[source_project.id] = target_project
         debug_log "Mapped source project #{source_project.id} (#{source_project.name}) to target project #{target_project.id} (#{target_project.name})"
 
-        target_project.tasks.each do |target_task|
+        target_project.embedded_tasks.each do |target_task|
           source_task = match_task(target_task, source_project)
           if source_task
             @task_mapping[source_task.id] = target_task
@@ -520,7 +520,7 @@ module MOCO
       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 }
+      default_task = target_project.embedded_tasks.find { |task| task.name == @default_task_name }
 
       # Cache the result (even if nil)
       @default_task_cache[target_project.id] = default_task
@@ -545,7 +545,7 @@ module MOCO
 
     def match_task(target_task, source_project)
       # Get tasks from the source project (embedded in projects.assigned response)
-      tasks = source_project.tasks
+      tasks = source_project.embedded_tasks
 
       # Only proceed if we have tasks to match against
       return nil if tasks.empty?

data/lib/moco/version.rb

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

data/lib/moco.rb

@@ -11,8 +11,10 @@ require_relative "moco/connection"
 require_relative "moco/collection_proxy"
 require_relative "moco/nested_collection_proxy"
 
-# New API (v2)
+# Entities
 require_relative "moco/entities/base_entity"
+
+# Core entities (original)
 require_relative "moco/entities/project"
 require_relative "moco/entities/activity"
 require_relative "moco/entities/user"
@@ -26,6 +28,58 @@ require_relative "moco/entities/schedule"
 require_relative "moco/entities/presence"
 require_relative "moco/entities/holiday"
 require_relative "moco/entities/planning_entry"
+
+# New standalone entities
+require_relative "moco/entities/contact"
+require_relative "moco/entities/offer"
+require_relative "moco/entities/purchase"
+require_relative "moco/entities/receipt"
+require_relative "moco/entities/unit"
+require_relative "moco/entities/comment"
+require_relative "moco/entities/tag"
+require_relative "moco/entities/tagging"
+require_relative "moco/entities/deal_category"
+require_relative "moco/entities/project_group"
+require_relative "moco/entities/profile"
+
+# Account-level entities
+require_relative "moco/entities/catalog_service"
+require_relative "moco/entities/custom_property"
+require_relative "moco/entities/expense_template"
+require_relative "moco/entities/fixed_cost"
+require_relative "moco/entities/hourly_rate"
+require_relative "moco/entities/internal_hourly_rate"
+require_relative "moco/entities/task_template"
+require_relative "moco/entities/user_role"
+require_relative "moco/entities/vat_code_sale"
+require_relative "moco/entities/vat_code_purchase"
+
+# Nested/sub-resource entities
+require_relative "moco/entities/employment"
+require_relative "moco/entities/work_time_adjustment"
+require_relative "moco/entities/project_contract"
+require_relative "moco/entities/payment_schedule"
+require_relative "moco/entities/recurring_expense"
+require_relative "moco/entities/invoice_payment"
+require_relative "moco/entities/invoice_reminder"
+require_relative "moco/entities/invoice_bookkeeping_export"
+require_relative "moco/entities/invoice_attachment"
+require_relative "moco/entities/offer_approval"
+require_relative "moco/entities/offer_attachment"
+require_relative "moco/entities/letter_paper"
+require_relative "moco/entities/session"
+require_relative "moco/entities/purchase_category"
+require_relative "moco/entities/purchase_draft"
+require_relative "moco/entities/purchase_payment"
+require_relative "moco/entities/purchase_budget"
+require_relative "moco/entities/purchase_bookkeeping_export"
+
+# Reports
+require_relative "moco/entities/reports/absences"
+require_relative "moco/entities/reports/cashflow"
+require_relative "moco/entities/reports/finance"
+require_relative "moco/entities/reports/utilization"
+
 require_relative "moco/client"
 require_relative "moco/entity_collection"
 

data/moco.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/moco/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "moco-ruby"
+  spec.version = MOCO::VERSION
+  spec.authors = ["Teal Bauer"]
+  spec.email = ["rubygems@teal.is"]
+
+  spec.summary = "A Ruby Gem to interact with the MOCO API."
+  spec.description = "A modern, Ruby-esque interface for the MOCO API (mocoapp.com). " \
+                     "Provides an ActiveRecord-style interface for projects, activities, users, companies, and more."
+  spec.homepage = "https://github.com/starsong-consulting/moco-ruby"
+  spec.required_ruby_version = ">= 3.2.0"
+  spec.license = "Apache-2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/starsong-consulting/moco-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/starsong-consulting/moco-ruby/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 7.0"
+  spec.add_dependency "faraday", ">= 2.0"
+  spec.add_dependency "fuzzy_match", "~> 2.1.0"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/sync_activity.rb

@@ -94,7 +94,7 @@ syncer = MOCO::Sync.new(
 syncer.source_projects.each do |project|
   if syncer.project_mapping[project.id]
     puts "✅ Project #{project} --> #{syncer.project_mapping[project.id]}"
-    project.tasks.each do |task|
+    project.embedded_tasks.each do |task|
       if syncer.task_mapping[task.id]
         puts "  ✅ Task #{task} --> #{syncer.task_mapping[task.id]}"
       else