moco-ruby 1.1.0 → 1.2.0

data/lib/moco/entities/purchase.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO purchase/expense (Ausgaben)
+  #
+  # == Required attributes for create:
+  #   date           - String, "YYYY-MM-DD" format
+  #   currency       - String, valid currency code (e.g., "EUR", "CHF", "USD")
+  #   payment_method - String, one of:
+  #                    "bank_transfer", "direct_debit", "credit_card",
+  #                    "paypal", "cash", "bank_transfer_swiss_qr_esr"
+  #   items          - Array of item hashes (at least one required):
+  #                    { title: "Item", total: 100.0, tax: 7.7, tax_included: true }
+  #
+  # == Optional attributes:
+  #   title              - String, purchase title (auto-generated from items if omitted)
+  #   due_date           - String, "YYYY-MM-DD" payment due date
+  #   service_period_from - String, "YYYY-MM-DD" service period start
+  #   service_period_to   - String, "YYYY-MM-DD" service period end
+  #   status             - String, "pending" (Inbox) or "archived" (Archive)
+  #   company_id         - Integer, supplier company ID
+  #   user_id            - Integer, responsible user ID
+  #   receipt_identifier - String, supplier's invoice number
+  #   info               - String, free text notes
+  #   iban               - String, bank account for payment
+  #   reference          - String, payment reference
+  #   custom_property_values - Hash, custom field values
+  #   tags               - Array of Strings, labels
+  #   file               - Hash, { filename: "doc.pdf", base64: "..." }
+  #
+  # == Item attributes:
+  #   title        - String, item description
+  #   total        - Float, item total amount
+  #   tax          - Float, tax percentage (e.g., 7.7)
+  #   tax_included - Boolean, whether total includes tax
+  #   category_id  - Integer, purchase category ID
+  #
+  # == Read-only attributes:
+  #   id, identifier, net_total, gross_total, payments (Array),
+  #   approval_status, file_url, company (Hash), user (Hash),
+  #   created_at, updated_at
+  #
+  # == Example:
+  #   moco.purchases.create(
+  #     date: "2024-01-15",
+  #     currency: "EUR",
+  #     payment_method: "bank_transfer",
+  #     company_id: 456,
+  #     items: [
+  #       { title: "Office supplies", total: 119.0, tax: 19.0, tax_included: true }
+  #     ],
+  #     tags: ["Office"]
+  #   )
+  #
+  class Purchase < BaseEntity
+    # Assign purchase to a project expense
+    def assign_to_project(project_id:, project_expense_id: nil)
+      payload = { project_id: }
+      payload[:project_expense_id] = project_expense_id if project_expense_id
+
+      client.post("purchases/#{id}/assign_to_project", payload)
+      reload
+    end
+
+    # Update purchase status (pending/archived)
+    def update_status(status)
+      client.patch("purchases/#{id}/update_status", { status: })
+      reload
+    end
+
+    # Store/upload a document for this purchase
+    def store_document(file_data)
+      client.patch("purchases/#{id}/store_document", file_data)
+      self
+    end
+
+    # Associations
+    def company
+      association(:company)
+    end
+
+    def user
+      association(:user)
+    end
+
+    def to_s
+      "#{title} (#{date})"
+    end
+  end
+end

data/lib/moco/entities/purchase_bookkeeping_export.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO purchase bookkeeping export
+  # (Ausgaben / Buchhaltungsexporte)
+  # Exports purchase data for accounting systems
+  #
+  # == Read-only attributes:
+  #   id, from, to, file_url, user (Hash),
+  #   created_at, updated_at
+  #
+  # == Filtering:
+  #   moco.purchase_bookkeeping_exports.all
+  #   moco.purchase_bookkeeping_exports.where(from: "2024-01-01", to: "2024-01-31")
+  #
+  # == Note:
+  #   Bookkeeping exports are generated via MOCO's finance interface.
+  #   This endpoint provides read-only access to export records.
+  #
+  class PurchaseBookkeepingExport < BaseEntity
+    # Custom path since it's nested under purchases
+    def self.entity_path
+      "purchases/bookkeeping_exports"
+    end
+
+    def user
+      association(:user, "User")
+    end
+
+    def to_s
+      "PurchaseBookkeepingExport #{id} (#{from} - #{to})"
+    end
+  end
+end

data/lib/moco/entities/purchase_budget.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO purchase budget (Ausgaben – Budgets)
+  # Read-only budget tracking for expense categories
+  #
+  # == Read-only attributes:
+  #   id, title, year, target, exhausted, remaining,
+  #   created_at, updated_at
+  #
+  # == Helper methods:
+  #   remaining_percentage   - Percentage of budget remaining
+  #   exhausted_percentage   - Percentage of budget used
+  #
+  # == Example:
+  #   budgets = moco.purchase_budgets.all
+  #   budgets.each do |budget|
+  #     puts "#{budget.title}: #{budget.remaining_percentage}% remaining"
+  #   end
+  #
+  # == Note:
+  #   Purchase budgets are configured in MOCO's admin interface.
+  #   This endpoint provides read-only access for tracking.
+  #
+  class PurchaseBudget < BaseEntity
+    # Custom path since it's nested under purchases
+    def self.entity_path
+      "purchases/budgets"
+    end
+
+    def to_s
+      "PurchaseBudget #{id}: #{title} (#{year})"
+    end
+
+    def remaining_percentage
+      return 0 if target.to_f.zero?
+
+      (remaining.to_f / target.to_f * 100).round(1)
+    end
+
+    def exhausted_percentage
+      return 0 if target.to_f.zero?
+
+      (exhaused.to_f / target.to_f * 100).round(1)
+    end
+  end
+end

data/lib/moco/entities/purchase_category.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO purchase category (Ausgaben – Kategorien)
+  # Read-only expense categories for organizing purchases
+  #
+  # == Read-only attributes:
+  #   id, name, credit_account, active, created_at, updated_at
+  #
+  # == Example:
+  #   # List all categories
+  #   moco.purchase_categories.all
+  #
+  #   # Use category when creating purchase
+  #   moco.purchases.create(
+  #     # ... other fields ...
+  #     items: [{
+  #       title: "Travel",
+  #       total: 250.0,
+  #       tax: 7.7,
+  #       category_id: 123  # from purchase_categories
+  #     }]
+  #   )
+  #
+  # == Note:
+  #   Purchase categories are configured in MOCO's admin interface.
+  #   This endpoint provides read-only access.
+  #
+  class PurchaseCategory < BaseEntity
+    def self.entity_path
+      "purchases/categories"
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/purchase_draft.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO purchase draft
+  # Auto-created draft purchases from document scanning
+  #
+  # == Read-only attributes:
+  #   id, title, date, company (Hash), file_url,
+  #   items (Array), created_at, updated_at
+  #
+  # == Note:
+  #   Purchase drafts are created automatically when documents
+  #   are uploaded/scanned in MOCO's inbox.
+  #   Convert to actual purchases via the MOCO interface.
+  #
+  class PurchaseDraft < BaseEntity
+    def self.entity_path
+      "purchases/drafts"
+    end
+
+    def to_s
+      "Draft ##{id}"
+    end
+  end
+end

data/lib/moco/entities/purchase_payment.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO purchase payment record (Ausgaben / Zahlungen)
+  # For tracking payments made for purchases
+  #
+  # == Required attributes for create:
+  #   date  - String, "YYYY-MM-DD" payment date
+  #   total - Float, payment amount
+  #
+  # == Optional attributes:
+  #   purchase_id - Integer, purchase being paid (required unless description set)
+  #   description - String, payment description (required if no purchase_id)
+  #
+  # == Read-only attributes:
+  #   id, purchase (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   moco.purchase_payments.create(
+  #     date: "2024-01-20",
+  #     purchase_id: 456,
+  #     total: 1500.0
+  #   )
+  #
+  # == Bulk create:
+  #   moco.post("purchases/payments/bulk", {
+  #     bulk_data: [
+  #       { date: "2024-01-20", purchase_id: 123, total: 500 },
+  #       { date: "2024-01-21", description: "Salaries", total: 10000 }
+  #     ]
+  #   })
+  #
+  # == Filtering:
+  #   moco.purchase_payments.where(purchase_id: 456)
+  #   moco.purchase_payments.where(date_from: "2024-01-01", date_to: "2024-01-31")
+  #
+  class PurchasePayment < BaseEntity
+    # Custom path since it's nested under purchases
+    def self.entity_path
+      "purchases/payments"
+    end
+
+    def purchase
+      association(:purchase, "Purchase")
+    end
+
+    def to_s
+      "PurchasePayment #{id}: #{total} on #{date}"
+    end
+  end
+end

data/lib/moco/entities/receipt.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO receipt/expense claim (Spesen)
+  #
+  # == Required attributes for create:
+  #   date     - String, "YYYY-MM-DD" format
+  #   title    - String, receipt description (e.g., "Team lunch")
+  #   currency - String, valid currency code (e.g., "EUR", "CHF")
+  #   items    - Array of item hashes (at least one required):
+  #              { vat_code_id: 186, gross_total: 99.90 }
+  #
+  # == Optional attributes:
+  #   project_id - Integer, project to associate with
+  #   info       - String, additional notes
+  #   billable   - Boolean, whether expense is billable to customer
+  #   attachment - Hash, { filename: "receipt.pdf", base64: "..." }
+  #
+  # == Item attributes:
+  #   vat_code_id          - Integer, VAT code ID (required)
+  #   gross_total          - Float, total amount including tax (required)
+  #   purchase_category_id - Integer, expense category
+  #
+  # == Read-only attributes:
+  #   id, pending, user (Hash), project (Hash), refund_request (Hash),
+  #   attachment_url, created_at, updated_at
+  #
+  # == Example:
+  #   moco.receipts.create(
+  #     date: "2024-01-15",
+  #     title: "Client lunch",
+  #     currency: "EUR",
+  #     project_id: 123,
+  #     billable: true,
+  #     items: [
+  #       { vat_code_id: 186, gross_total: 85.50 }
+  #     ]
+  #   )
+  #
+  # == Filtering:
+  #   moco.receipts.where(from: "2024-01-01", to: "2024-01-31")
+  #   moco.receipts.where(project_id: 123)
+  #   moco.receipts.where(user_id: 456)
+  #
+  class Receipt < BaseEntity
+    # Associations
+    def user
+      association(:user)
+    end
+
+    def to_s
+      "#{title} (#{date})"
+    end
+  end
+end

data/lib/moco/entities/recurring_expense.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO project recurring expense
+  # (Wiederkehrende Zusatzleistungen) for ongoing services like hosting
+  #
+  # == Required attributes for create:
+  #   start_date - String, "YYYY-MM-DD" when recurring starts
+  #   period     - String, recurrence interval:
+  #                "weekly", "biweekly", "monthly", "quarterly",
+  #                "biannual", "annual"
+  #   title      - String, expense name (e.g., "Monthly Hosting")
+  #   quantity   - Float, number of units per period
+  #   unit       - String, unit type (e.g., "Server", "License")
+  #   unit_price - Float, price per unit
+  #   unit_cost  - Float, internal cost per unit
+  #
+  # == Optional attributes:
+  #   finish_date              - String, "YYYY-MM-DD" when to stop (null = unlimited)
+  #   description              - String, detailed description
+  #   billable                 - Boolean, whether to invoice (default: true)
+  #   budget_relevant          - Boolean, count toward budget (default: false)
+  #   service_period_direction - String, "none", "forward", "backward"
+  #   custom_properties        - Hash, custom field values
+  #
+  # == Read-only attributes:
+  #   id, price, cost, currency, recur_next_date, project (Hash),
+  #   revenue_category (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   moco.post("projects/123/recurring_expenses", {
+  #     start_date: "2024-01-01",
+  #     period: "monthly",
+  #     title: "Web Hosting",
+  #     quantity: 1,
+  #     unit: "Server",
+  #     unit_price: 99.0,
+  #     unit_cost: 50.0,
+  #     billable: true
+  #   })
+  #
+  # == Note:
+  #   start_date and period cannot be modified after creation.
+  #
+  class RecurringExpense < BaseEntity
+    # Associations
+    def project
+      association(:project)
+    end
+
+    def to_s
+      "RecurringExpense ##{id} - #{title}"
+    end
+  end
+end

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

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

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

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

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