moco-ruby 1.0.0 → 1.2.0

data/lib/moco/entities/presence.rb

@@ -1,8 +1,40 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO presence entry
-  # Provides methods for presence-specific operations and associations
+  # Represents a MOCO presence entry (work time tracking)
+  #
+  # == Required attributes for create:
+  #   date - String, "YYYY-MM-DD" date
+  #   from - String, "HH:MM" start time (e.g., "08:00")
+  #
+  # == Optional attributes:
+  #   to            - String, "HH:MM" end time (e.g., "17:00"), can be blank for open entry
+  #   is_home_office - Boolean, whether working from home (default: false)
+  #
+  # == Read-only attributes:
+  #   id, user (Hash), created_at, updated_at
+  #
+  # == Class methods:
+  #   Presence.touch(client) - Clock in/out (creates or closes presence)
+  #
+  # == Example:
+  #   # Log work time
+  #   moco.presences.create(
+  #     date: "2024-01-15",
+  #     from: "09:00",
+  #     to: "17:30"
+  #   )
+  #
+  #   # Start work (open-ended)
+  #   moco.presences.create(
+  #     date: "2024-01-16",
+  #     from: "08:30",
+  #     is_home_office: true
+  #   )
+  #
+  #   # Clock in/out via touch
+  #   MOCO::Presence.touch(moco)
+  #
   class Presence < BaseEntity
     # Define the specific API path for this entity as a class method
     def self.entity_path

data/lib/moco/entities/profile.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents the current API user's profile
+  # Read-only singleton endpoint for the authenticated user
+  #
+  # == Read-only attributes:
+  #   id, firstname, lastname, email, unit (Hash),
+  #   created_at, updated_at
+  #
+  # == Usage:
+  #   profile = moco.profile.get
+  #   puts "Logged in as: #{profile.firstname} #{profile.lastname}"
+  #
+  # == Note:
+  #   This returns information about the user who owns the API key.
+  #   For other user information, use moco.users.
+  #
+  class Profile < BaseEntity
+    def to_s
+      "#{firstname} #{lastname}"
+    end
+  end
+end

data/lib/moco/entities/project.rb

@@ -1,6 +1,58 @@
 # frozen_string_literal: true
 
 module MOCO
+  # Represents a MOCO project
+  #
+  # == Required attributes for create:
+  #   name        - String, project name (e.g., "Website Relaunch")
+  #   currency    - String, 3-letter currency code (e.g., "EUR", "USD", "CHF")
+  #   start_date  - String, "YYYY-MM-DD" format (required, must be 1st of month if retainer)
+  #   finish_date - String, "YYYY-MM-DD" format (required, must be last of month if retainer)
+  #   fixed_price - Boolean, true for fixed-price projects
+  #   retainer    - Boolean, true for retainer/recurring projects
+  #   leader_id   - Integer, user ID of the project leader
+  #   customer_id - Integer, company ID of the customer
+  #   identifier  - String, project identifier (e.g., "P-123") - only required if manual numbering
+  #
+  # == Optional attributes:
+  #   co_leader_id    - Integer, user ID of co-leader
+  #   deal_id         - Integer, associated deal ID
+  #   project_group_id - Integer, project group ID
+  #   contact_id      - Integer, primary contact ID
+  #   secondary_contact_id - Integer, secondary contact ID
+  #   billing_contact_id - Integer, billing contact ID
+  #   billing_address - String, billing address (multiline with \n)
+  #   billing_email_to - String, email for invoices
+  #   billing_email_cc - String, CC email for invoices
+  #   billing_notes   - String, notes for billing
+  #   billing_variant - String, "project", "task", or "user" (default: "project")
+  #   setting_include_time_report - Boolean, include time report with invoices
+  #   hourly_rate     - Float/Integer, hourly rate (meaning depends on billing_variant)
+  #   budget          - Float/Integer, total budget
+  #   budget_monthly  - Float/Integer, monthly budget (required if retainer: true)
+  #   budget_expenses - Float/Integer, expenses budget
+  #   tags            - Array of Strings, e.g., ["Print", "Digital"]
+  #   custom_properties - Hash, e.g., {"PO-Number": "123-ABC"}
+  #   info            - String, additional info
+  #
+  # == Read-only attributes (returned by API):
+  #   id, active, color, customer (Hash), leader (Hash), co_leader (Hash),
+  #   deal (Hash), tasks (Array), contracts (Array), project_group (Hash),
+  #   created_at, updated_at
+  #
+  # == Example:
+  #   moco.projects.create(
+  #     name: "Website Relaunch",
+  #     currency: "EUR",
+  #     start_date: "2024-01-01",
+  #     finish_date: "2024-12-31",
+  #     fixed_price: false,
+  #     retainer: false,
+  #     leader_id: 123456,
+  #     customer_id: 789012,
+  #     budget: 50000
+  #   )
+  #
   class Project < BaseEntity
     def customer
       # Use the association method to fetch the customer
@@ -31,12 +83,34 @@ module MOCO
     end
 
     # Fetches tasks associated with this project.
+    # Always returns a NestedCollectionProxy for consistent interface.
+    # Data is fetched lazily when accessed (e.g., .all, .first, .each).
+    # Note: Embedded tasks from projects.assigned are available via attributes[:tasks]
+    # but may have incomplete fields compared to the dedicated endpoint.
     def tasks
-      # Don't cache the proxy - create a fresh one each time
-      # This ensures we get fresh data when tasks are created/updated/deleted
       MOCO::NestedCollectionProxy.new(client, self, :tasks, "Task")
     end
 
+    # Fetches contracts associated with this project.
+    def contracts
+      MOCO::NestedCollectionProxy.new(client, self, :contracts, "ProjectContract")
+    end
+
+    # Fetches payment schedules associated with this project.
+    def payment_schedules
+      MOCO::NestedCollectionProxy.new(client, self, :payment_schedules, "PaymentSchedule")
+    end
+
+    # Fetches recurring expenses associated with this project.
+    def recurring_expenses
+      MOCO::NestedCollectionProxy.new(client, self, :recurring_expenses, "RecurringExpense")
+    end
+
+    # Get the project group
+    def project_group
+      association(:project_group)
+    end
+
     def to_s
       "Project #{identifier} \"#{name}\" (#{id})"
     end

data/lib/moco/entities/project_contract.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO project contract/staff assignment
+  # (Projekte / Personal) - assigning users to projects
+  #
+  # == Required attributes for create:
+  #   user_id - Integer, user to assign to project
+  #
+  # == Optional attributes:
+  #   billable    - Boolean, whether user's time is billable
+  #   active      - Boolean, whether assignment is active
+  #   budget      - Float, hours budget for this user on project
+  #   hourly_rate - Float, billing rate for this user on project
+  #
+  # == Read-only attributes:
+  #   id, firstname, lastname, created_at, updated_at
+  #
+  # == Access via project:
+  #   project = moco.projects.find(123)
+  #   project.contracts  # via nested API
+  #
+  # == Example:
+  #   # Assign user to project with budget
+  #   moco.post("projects/123/contracts", {
+  #     user_id: 456,
+  #     budget: 100,
+  #     hourly_rate: 150.0,
+  #     billable: true
+  #   })
+  #
+  # == Note:
+  #   Cannot delete assignment if user has tracked hours.
+  #   user_id cannot be changed after creation.
+  #
+  class ProjectContract < BaseEntity
+    # Associations
+    def project
+      association(:project)
+    end
+
+    def user
+      association(:user)
+    end
+
+    def to_s
+      "Contract ##{id}"
+    end
+  end
+end

data/lib/moco/entities/project_group.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO project group for organizing projects
+  #
+  # == Required attributes for create:
+  #   name - String, group name
+  #
+  # == Read-only attributes:
+  #   id, created_at, updated_at
+  #
+  # == Example:
+  #   # Create a project group
+  #   moco.project_groups.create(name: "Website Projects")
+  #
+  #   # Get projects in a group
+  #   group = moco.project_groups.find(123)
+  #   group.projects  # => Array of Project objects
+  #
+  # == Note:
+  #   To assign a project to a group, set project_group_id when
+  #   creating/updating the project.
+  #
+  class ProjectGroup < BaseEntity
+    def self.entity_path
+      "projects/groups"
+    end
+
+    # Get projects in this group
+    def projects
+      has_many(:projects, :project_group_id)
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end

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