moco-ruby 1.1.0 → 1.2.0

data/lib/moco/entities/company.rb

@@ -1,8 +1,63 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO company (customer)
-  # Provides methods for company-specific associations
+  # Represents a MOCO company (customer, supplier, or organization)
+  #
+  # == Required attributes for create:
+  #   name     - String, company name (e.g., "Acme Corp")
+  #   type     - String, one of: "customer", "supplier", "organization"
+  #   currency - String, 3-letter code (e.g., "EUR") - required for customers only
+  #
+  # == Optional attributes (all types):
+  #   identifier   - String, company identifier (e.g., "K-123") - required if manual numbering
+  #   country_code - String, ISO Alpha-2 code in uppercase (e.g., "DE", "CH", "US")
+  #   vat_identifier - String, EU VAT ID (e.g., "DE123456789")
+  #   website      - String, company website URL
+  #   phone        - String, phone number
+  #   fax          - String, fax number
+  #   email        - String, main email address
+  #   billing_email_cc - String, CC for billing emails
+  #   billing_notes - String, notes for billing
+  #   address      - String, full address (use \n for line breaks)
+  #   info         - String, additional information
+  #   tags         - Array of Strings, e.g., ["Network", "Print"]
+  #   custom_properties - Hash, e.g., {"UID": "123-ABC"}
+  #   user_id      - Integer, responsible person (user ID)
+  #   footer       - String, HTML footer for invoices
+  #   alternative_correspondence_language - Boolean, use alternative language
+  #
+  # == Customer-specific attributes:
+  #   customer_tax - Float, tax rate for customer (e.g., 19.0)
+  #   default_invoice_due_days - Integer, payment terms (e.g., 30)
+  #   debit_number - Integer, for bookkeeping (e.g., 10000)
+  #
+  # == Supplier-specific attributes:
+  #   bank_owner   - String, bank account holder name
+  #   iban         - String, bank account IBAN
+  #   bank_bic     - String, bank BIC/SWIFT code
+  #   supplier_tax - Float, tax rate for supplier
+  #   credit_number - Integer, for bookkeeping (e.g., 70000)
+  #
+  # == Read-only attributes (returned by API):
+  #   id, intern, projects (Array), user (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   # Create a customer
+  #   moco.companies.create(
+  #     name: "Acme Corp",
+  #     type: "customer",
+  #     currency: "EUR",
+  #     country_code: "DE",
+  #     email: "info@acme.com"
+  #   )
+  #
+  #   # Create a supplier
+  #   moco.companies.create(
+  #     name: "Office Supplies Inc",
+  #     type: "supplier",
+  #     iban: "DE89370400440532013000"
+  #   )
+  #
   class Company < BaseEntity
     # Associations
     def projects

data/lib/moco/entities/contact.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO contact (person/Ansprechpartner)
+  # Contacts are people associated with companies
+  #
+  # == Required attributes for create:
+  #   lastname - String, last name (e.g., "Muster")
+  #   gender   - String, one of: "F" (female), "M" (male), "U" (unknown/diverse)
+  #
+  # == Optional attributes:
+  #   firstname    - String, first name
+  #   company_id   - Integer, associated company ID
+  #   user_id      - Integer, responsible user ID (default: current user)
+  #   title        - String, title (e.g., "Dr.", "Prof.")
+  #   job_position - String, job title (e.g., "Account Manager")
+  #   mobile_phone - String, mobile phone number
+  #   work_phone   - String, work phone number
+  #   work_fax     - String, work fax number
+  #   work_email   - String, work email address
+  #   work_address - String, work address (use \n for line breaks)
+  #   home_email   - String, personal email
+  #   home_address - String, home address
+  #   birthday     - String, "YYYY-MM-DD" format (e.g., "1990-05-22")
+  #   info         - String, additional notes
+  #   tags         - Array of Strings, e.g., ["VIP", "Newsletter"]
+  #
+  # == Read-only attributes (returned by API):
+  #   id, avatar_url, company (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   moco.contacts.create(
+  #     firstname: "John",
+  #     lastname: "Doe",
+  #     gender: "M",
+  #     company_id: 123456,
+  #     work_email: "john.doe@example.com",
+  #     job_position: "CTO"
+  #   )
+  #
+  class Contact < BaseEntity
+    # Override entity_path to match API path
+    def self.entity_path
+      "contacts/people"
+    end
+
+    # Associations
+    def company
+      association(:company)
+    end
+
+    def to_s
+      "#{firstname} #{lastname}"
+    end
+  end
+end

data/lib/moco/entities/custom_property.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO custom property/field definition (Eigene Felder)
+  #
+  # == Required attributes for create:
+  #   name   - String, field name (e.g., "Purchase Order Number")
+  #   kind   - String, field type:
+  #            "String", "Textarea", "Link", "Boolean",
+  #            "Select", "MultiSelect", "Date"
+  #   entity - String, entity type this field applies to:
+  #            "Project", "Customer", "Deal", etc.
+  #
+  # == Optional attributes:
+  #   placeholder          - String, placeholder text for input
+  #   placeholder_alt      - String, placeholder in alternative language
+  #   print_on_invoice     - Boolean, show on invoices
+  #   print_on_offer       - Boolean, show on offers
+  #   print_on_timesheet   - Boolean, show on timesheets
+  #   notification_enabled - Boolean, send notification for Date fields
+  #   api_only             - Boolean, hide from UI (API access only)
+  #   defaults             - Array, options for Select/MultiSelect types
+  #
+  # == Read-only attributes:
+  #   id, name_alt, created_at, updated_at
+  #
+  # == Example:
+  #   # Create a dropdown field
+  #   moco.custom_properties.create(
+  #     name: "Project Type",
+  #     kind: "Select",
+  #     entity: "Project",
+  #     defaults: ["Website", "Mobile App", "API Integration"],
+  #     print_on_invoice: true
+  #   )
+  #
+  # == Note:
+  #   `kind` and `entity` cannot be changed after creation.
+  #
+  class CustomProperty < BaseEntity
+    def self.entity_path
+      "account/custom_properties"
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/deal.rb

@@ -1,8 +1,44 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO deal
-  # Provides methods for deal-specific associations
+  # Represents a MOCO deal/lead
+  #
+  # == Required attributes for create:
+  #   name             - String, deal name (e.g., "Website Relaunch")
+  #   currency         - String, 3-letter code (e.g., "EUR", "USD")
+  #   money            - Float/Integer, deal value (e.g., 25000)
+  #   reminder_date    - String, "YYYY-MM-DD" format for follow-up
+  #   user_id          - Integer, responsible user ID
+  #   deal_category_id - Integer, deal category/stage ID
+  #
+  # == Optional attributes:
+  #   company_id   - Integer, associated company ID
+  #   person_id    - Integer, associated contact ID
+  #   info         - String, additional information
+  #   status       - String, one of: "potential", "pending", "won", "lost", "dropped"
+  #                  (default: "pending")
+  #   closed_on    - String, "YYYY-MM-DD" when deal was closed
+  #   service_period_from - String, "YYYY-MM-DD" (must be 1st of month)
+  #   service_period_to   - String, "YYYY-MM-DD" (must be last of month)
+  #   tags         - Array of Strings, e.g., ["Important", "Q1"]
+  #   custom_properties - Hash, e.g., {"Source": "Website"}
+  #
+  # == Read-only attributes (returned by API):
+  #   id, user (Hash), company (Hash), person (Hash), category (Hash),
+  #   created_at, updated_at
+  #
+  # == Example:
+  #   moco.deals.create(
+  #     name: "New Website Project",
+  #     currency: "EUR",
+  #     money: 50000,
+  #     reminder_date: "2024-02-01",
+  #     user_id: 123,
+  #     deal_category_id: 456,
+  #     company_id: 789,
+  #     status: "pending"
+  #   )
+  #
   class Deal < BaseEntity
     # Associations
     def company

data/lib/moco/entities/deal_category.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO deal category/stage (Akquise-Stufen)
+  #
+  # == Required attributes for create:
+  #   name        - String, category name (e.g., "Contact", "Qualified", "Proposal")
+  #   probability - Integer, win probability percentage (0-100)
+  #
+  # == Read-only attributes:
+  #   id, created_at, updated_at
+  #
+  # == Example:
+  #   moco.deal_categories.create(
+  #     name: "Qualified Lead",
+  #     probability: 25
+  #   )
+  #
+  # == Note:
+  #   Categories cannot be deleted if deals are using them.
+  #
+  class DealCategory < BaseEntity
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/employment.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO user employment/work schedule record
+  # Access via: moco.employments.where(user_id: 123) or user.employments
+  #
+  # == Required attributes for create:
+  #   user_id - Integer, the user this employment belongs to
+  #   pattern - Hash, weekly work schedule:
+  #             { "am": [0, 4, 4, 4, 4], "pm": [0, 4, 4, 4, 4] }
+  #             Arrays represent Mon-Fri morning/afternoon hours
+  #
+  # == Optional attributes:
+  #   from - String, "YYYY-MM-DD" when employment starts (default: today)
+  #   to   - String, "YYYY-MM-DD" when employment ends (null = ongoing)
+  #
+  # == Read-only attributes:
+  #   id, weekly_target_hours, user (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   # Create full-time employment (8h/day Mon-Fri)
+  #   moco.employments.create(
+  #     user_id: 123,
+  #     pattern: {
+  #       am: [4, 4, 4, 4, 4],
+  #       pm: [4, 4, 4, 4, 4]
+  #     },
+  #     from: "2024-01-01"
+  #   )
+  #
+  #   # Create part-time (4h/day Tue-Thu)
+  #   moco.employments.create(
+  #     user_id: 123,
+  #     pattern: {
+  #       am: [0, 4, 4, 4, 0],
+  #       pm: [0, 0, 0, 0, 0]
+  #     },
+  #     from: "2024-01-01"
+  #   )
+  #
+  class Employment < BaseEntity
+    def self.entity_path
+      "users/employments"
+    end
+
+    # Associations
+    def user
+      association(:user)
+    end
+
+    def to_s
+      "Employment ##{id} (#{from} - #{self.to || 'present'})"
+    end
+  end
+end

data/lib/moco/entities/expense.rb

@@ -1,8 +1,43 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO expense
-  # Provides methods for expense-specific operations and associations
+  # Represents a MOCO project expense (additional service)
+  # Expenses are typically accessed via project: project.expenses.create(...)
+  #
+  # == Required attributes for create:
+  #   date       - String, "YYYY-MM-DD" expense date
+  #   title      - String, expense title (e.g., "Hosting XS")
+  #   quantity   - Float/Integer, quantity (e.g., 3)
+  #   unit       - String, unit label (e.g., "months", "pieces", "hours")
+  #   unit_price - Float, price per unit charged to customer
+  #   unit_cost  - Float, cost per unit (your cost)
+  #
+  # == Optional attributes:
+  #   description     - String, detailed description
+  #   billable        - Boolean, whether expense is billable (default: true)
+  #   budget_relevant - Boolean, whether counts toward budget (default: false)
+  #   service_period_from - String, "YYYY-MM-DD" service period start
+  #   service_period_to   - String, "YYYY-MM-DD" service period end
+  #   user_id         - Integer, responsible user ID (default: current user)
+  #   custom_properties - Hash, e.g., {"Type": "Infrastructure"}
+  #   file            - Hash, { filename: "receipt.pdf", base64: "..." }
+  #
+  # == Read-only attributes:
+  #   id, price, cost, currency, billed, invoice_id, project (Hash),
+  #   company (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   project = moco.projects.find(123)
+  #   project.expenses.create(
+  #     date: "2024-01-15",
+  #     title: "Cloud Hosting",
+  #     quantity: 1,
+  #     unit: "month",
+  #     unit_price: 99.0,
+  #     unit_cost: 49.0,
+  #     billable: true
+  #   )
+  #
   class Expense < BaseEntity
     # Override entity_path to use the global expenses endpoint
     # Note: Expenses can also be accessed via projects/{id}/expenses

data/lib/moco/entities/expense_template.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO expense template (Zusatzleistungs-Katalog)
+  # Pre-defined templates for project additional services
+  #
+  # == Required attributes for create:
+  #   title      - String, template name (e.g., "Hosting L")
+  #   unit       - String, unit type (e.g., "month", "hours", "pieces")
+  #   unit_price - Float, price per unit
+  #   currency   - String, currency code (e.g., "EUR")
+  #
+  # == Optional attributes:
+  #   description - String, detailed description
+  #   unit_cost   - Float, internal cost per unit
+  #
+  # == Read-only attributes:
+  #   id, revenue_category (Hash), created_at, updated_at
+  #
+  # == Example:
+  #   moco.expense_templates.create(
+  #     title: "Monthly Hosting",
+  #     description: "Web hosting with monitoring and backup",
+  #     unit: "month",
+  #     unit_price: 50.0,
+  #     unit_cost: 30.0,
+  #     currency: "EUR"
+  #   )
+  #
+  class ExpenseTemplate < BaseEntity
+    def self.entity_path
+      "account/expense_templates"
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/fixed_cost.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO fixed cost entry (Fixkosten)
+  # Read-only access to company fixed costs for reporting
+  #
+  # == Read-only attributes:
+  #   id, title, description, costs (Array of monthly amounts),
+  #   created_at, updated_at
+  #
+  # == Costs array format:
+  #   [{ year: 2024, month: 1, amount: 50000.0 }, ...]
+  #
+  # == Filtering:
+  #   moco.fixed_costs.where(year: 2024)
+  #
+  # == Note:
+  #   Fixed costs are configured in MOCO's admin interface.
+  #   This endpoint provides read-only access for reporting.
+  #
+  class FixedCost < BaseEntity
+    def self.entity_path
+      "account/fixed_costs"
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/holiday.rb

@@ -1,8 +1,39 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO holiday entry
-  # Provides methods for holiday-specific associations
+  # Represents a MOCO user holiday/vacation entitlement record
+  # German: "Urlaubsanspruch"
+  #
+  # == Required attributes for create:
+  #   user_id - Integer, the user this holiday entitlement belongs to
+  #   year    - Integer, the year (e.g., 2024)
+  #   title   - String, description (e.g., "Urlaubsanspruch 80%")
+  #   days    - Integer/Float, number of vacation days entitled
+  #
+  # == Optional attributes:
+  #   creator_id - Integer, user who created this record
+  #
+  # == Read-only attributes:
+  #   id, hours (auto-calculated from days), user (Hash), creator (Hash),
+  #   created_at, updated_at
+  #
+  # == Example:
+  #   # Create holiday entitlement for a user
+  #   moco.holidays.create(
+  #     user_id: 123,
+  #     year: 2024,
+  #     title: "Annual vacation entitlement",
+  #     days: 25
+  #   )
+  #
+  # == Filtering:
+  #   moco.holidays.where(year: 2024)
+  #   moco.holidays.where(user_id: 123)
+  #
+  # == Note:
+  #   Holiday days are converted to hours using the user's daily hours setting.
+  #   10 days at 8h/day = 80 hours, 10 days at 5h/day = 50 hours.
+  #
   class Holiday < BaseEntity
     # Override entity_path to match API path
     def self.entity_path

data/lib/moco/entities/hourly_rate.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents MOCO hourly rates (Stundensätze)
+  # Read-only access to billing rates by task and user
+  #
+  # == Read-only structure:
+  #   defaults_rates - Array of default rates per currency
+  #   tasks          - Array of tasks with their rates per currency
+  #   users          - Array of users with their rates per currency
+  #
+  # == Rate format:
+  #   { currency: "EUR", hourly_rate: 150.0 }
+  #
+  # == Filtering:
+  #   moco.hourly_rates.where(company_id: 123)  # customer-specific rates
+  #   moco.hourly_rates.where(include_archived_users: true)
+  #
+  # == Note:
+  #   Hourly rates are configured in MOCO's admin interface.
+  #   This endpoint provides read-only access.
+  #   Without company_id, returns global default rates.
+  #
+  class HourlyRate < BaseEntity
+    def self.entity_path
+      "account/hourly_rates"
+    end
+
+    def to_s
+      "#{name} - #{rate}"
+    end
+  end
+end

data/lib/moco/entities/internal_hourly_rate.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents MOCO internal hourly rates (Interne Stundensätze)
+  # Internal cost rates per user for profitability calculations
+  #
+  # == Read-only structure (per user):
+  #   id, full_name, rates (Array by year)
+  #
+  # == Rate format:
+  #   { year: 2024, rate: 120.0 }
+  #
+  # == Filtering:
+  #   moco.internal_hourly_rates.where(years: "2024")
+  #   moco.internal_hourly_rates.where(years: "2023,2024")
+  #   moco.internal_hourly_rates.where(unit_id: 123)
+  #   moco.internal_hourly_rates.where(include_archived: true)
+  #
+  # == Updating rates:
+  #   Use PATCH with year and rates array:
+  #   { year: 2024, rates: [{ user_id: 123, rate: 140.0 }] }
+  #
+  class InternalHourlyRate < BaseEntity
+    def self.entity_path
+      "account/internal_hourly_rates"
+    end
+
+    def to_s
+      "#{name} - #{rate}"
+    end
+  end
+end

data/lib/moco/entities/invoice.rb

@@ -2,7 +2,60 @@
 
 module MOCO
   # Represents a MOCO invoice
-  # Provides methods for invoice-specific operations and associations
+  #
+  # == Required attributes for create:
+  #   customer_id       - Integer, customer company ID
+  #   recipient_address - String, full address (use \n for line breaks)
+  #   date              - String, "YYYY-MM-DD" invoice date
+  #   due_date          - String, "YYYY-MM-DD" payment due date
+  #   title             - String, invoice title (e.g., "Invoice")
+  #   tax               - Float, tax rate percentage (e.g., 19.0)
+  #   currency          - String, 3-letter code (e.g., "EUR")
+  #   items             - Array of Hashes, invoice line items (see below)
+  #
+  # == Item types (for items array):
+  #   { type: "title", title: "Section Title" }
+  #   { type: "description", description: "Some description text" }
+  #   { type: "item", title: "Service", quantity: 10, unit: "h", unit_price: 150.0 }
+  #   { type: "item", title: "Fixed Fee", net_total: 500.0 }  # lump sum
+  #   { type: "subtotal" }
+  #   { type: "separator" }
+  #   { type: "page-break" }
+  #
+  # == Optional attributes:
+  #   project_id        - Integer, associated project ID
+  #   status            - String, "created" or "draft" (default: "created")
+  #   service_period_from - String, "YYYY-MM-DD"
+  #   service_period_to   - String, "YYYY-MM-DD"
+  #   change_address    - String, "invoice", "project", or "customer"
+  #   salutation        - String, greeting text (HTML allowed)
+  #   footer            - String, footer text (HTML allowed)
+  #   discount          - Float, discount percentage
+  #   cash_discount     - Float, early payment discount percentage
+  #   cash_discount_days - Integer, days for early payment discount
+  #   tags              - Array of Strings
+  #   custom_properties - Hash
+  #
+  # == Read-only attributes:
+  #   id, identifier, status, net_total, gross_total, payments, reminders,
+  #   created_at, updated_at
+  #
+  # == Example:
+  #   moco.invoices.create(
+  #     customer_id: 123456,
+  #     recipient_address: "Acme Corp\n123 Main St\n12345 City",
+  #     date: "2024-01-15",
+  #     due_date: "2024-02-15",
+  #     title: "Invoice",
+  #     tax: 19.0,
+  #     currency: "EUR",
+  #     items: [
+  #       { type: "title", title: "Services January 2024" },
+  #       { type: "item", title: "Development", quantity: 40, unit: "h", unit_price: 150.0 },
+  #       { type: "item", title: "Project Management", quantity: 8, unit: "h", unit_price: 120.0 }
+  #     ]
+  #   )
+  #
   class Invoice < BaseEntity
     # Instance methods for invoice-specific operations
     def update_status(status)
@@ -37,6 +90,33 @@ module MOCO
       self
     end
 
+    # Get attachments for this invoice
+    def attachments
+      client.get("invoices/#{id}/attachments")
+    end
+
+    # Add an attachment to the invoice
+    def add_attachment(file_data)
+      client.post("invoices/#{id}/attachments", file_data)
+      self
+    end
+
+    # Delete an attachment from the invoice
+    def delete_attachment(attachment_id)
+      client.delete("invoices/#{id}/attachments/#{attachment_id}")
+      self
+    end
+
+    # Fetches payments for this invoice
+    def payments
+      MOCO::NestedCollectionProxy.new(client, self, :payments, "InvoicePayment")
+    end
+
+    # Fetches reminders for this invoice
+    def reminders
+      MOCO::NestedCollectionProxy.new(client, self, :reminders, "InvoiceReminder")
+    end
+
     # Associations
     def company
       association(:customer, "Company")

data/lib/moco/entities/invoice_bookkeeping_export.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO invoice bookkeeping export (Buchhaltungsexporte)
+  # Exports invoice data for accounting systems
+  #
+  # == Read-only attributes:
+  #   id, from, to, file_url, user (Hash),
+  #   created_at, updated_at
+  #
+  # == Filtering:
+  #   moco.invoice_bookkeeping_exports.all
+  #   moco.invoice_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 InvoiceBookkeepingExport < BaseEntity
+    # Custom path since it's nested under invoices
+    def self.entity_path
+      "invoices/bookkeeping_exports"
+    end
+
+    def user
+      association(:user, "User")
+    end
+
+    def to_s
+      "InvoiceBookkeepingExport #{id} (#{from} - #{to})"
+    end
+  end
+end