moco-ruby 1.0.0 → 1.2.0

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

data/lib/moco/entities/invoice_payment.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO invoice payment record
+  # (Rechnungen / Zahlungen) for tracking received payments
+  #
+  # == Required attributes for create:
+  #   date       - String, "YYYY-MM-DD" payment date
+  #   paid_total - Float, amount received
+  #
+  # == Optional attributes:
+  #   invoice_id     - Integer, invoice being paid (required unless description set)
+  #   currency       - String, payment currency (e.g., "EUR")
+  #   partially_paid - Boolean, mark as partial payment
+  #   description    - String, payment description (required if no invoice_id)
+  #
+  # == Read-only attributes:
+  #   id, invoice (Hash), paid_total_in_account_currency,
+  #   created_at, updated_at
+  #
+  # == Example:
+  #   moco.invoice_payments.create(
+  #     date: "2024-01-20",
+  #     invoice_id: 456,
+  #     paid_total: 5000.0,
+  #     currency: "EUR"
+  #   )
+  #
+  # == Bulk create:
+  #   moco.post("invoices/payments/bulk", {
+  #     bulk_data: [
+  #       { date: "2024-01-20", invoice_id: 123, paid_total: 1000 },
+  #       { date: "2024-01-21", invoice_id: 456, paid_total: 2000 }
+  #     ]
+  #   })
+  #
+  # == Filtering:
+  #   moco.invoice_payments.where(invoice_id: 123)
+  #   moco.invoice_payments.where(date_from: "2024-01-01", date_to: "2024-01-31")
+  #
+  class InvoicePayment < BaseEntity
+    # Associations
+    def invoice
+      association(:invoice)
+    end
+
+    def to_s
+      "Payment ##{id} (#{date})"
+    end
+  end
+end

data/lib/moco/entities/invoice_reminder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO invoice reminder (Mahnung / Zahlungserinnerung)
+  #
+  # == Required attributes for create:
+  #   invoice_id - Integer, overdue invoice ID
+  #
+  # == Optional attributes:
+  #   title    - String, reminder title (uses default if omitted)
+  #   text     - String, reminder message (uses default if omitted)
+  #   fee      - Float, late payment fee
+  #   date     - String, "YYYY-MM-DD" reminder date
+  #   due_date - String, "YYYY-MM-DD" new payment due date
+  #
+  # == Read-only attributes:
+  #   id, status ("created" or "sent"), file_url, invoice (Hash),
+  #   created_at, updated_at
+  #
+  # == Example:
+  #   moco.invoice_reminders.create(
+  #     invoice_id: 456,
+  #     title: "Payment Reminder",
+  #     text: "Please remit payment within 14 days.",
+  #     fee: 25.0,
+  #     date: "2024-02-01",
+  #     due_date: "2024-02-15"
+  #   )
+  #
+  # == Send by email:
+  #   moco.post("invoice_reminders/123/send_email", {
+  #     emails_to: "customer@example.com",
+  #     subject: "Payment Reminder",
+  #     text: "Please see attached reminder."
+  #   })
+  #
+  # == Filtering:
+  #   moco.invoice_reminders.where(invoice_id: 456)
+  #   moco.invoice_reminders.where(date_from: "2024-01-01", date_to: "2024-01-31")
+  #
+  class InvoiceReminder < BaseEntity
+    # Associations
+    def invoice
+      association(:invoice)
+    end
+
+    def to_s
+      "Reminder ##{id} (#{date})"
+    end
+  end
+end

data/lib/moco/entities/offer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO offer/quote
+  #
+  # == Required attributes for create:
+  #   recipient_address - String, full address (use \r\n for line breaks)
+  #   date              - String, "YYYY-MM-DD" offer date
+  #   due_date          - String, "YYYY-MM-DD" valid until date
+  #   title             - String, offer title (e.g., "Offer - Website Relaunch")
+  #   tax               - Float, tax rate percentage (e.g., 19.0)
+  #   items             - Array of Hashes, offer line items (see below)
+  #
+  # == Item types (for items array):
+  #   { type: "title", title: "Section Title" }
+  #   { type: "description", description: "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:
+  #   company_id  - Integer, customer company ID (set from project if project_id provided)
+  #   deal_id     - Integer, associated deal ID
+  #   project_id  - Integer, associated project ID
+  #   currency    - String, 3-letter code (required if no company/deal/project)
+  #   salutation  - String, greeting text
+  #   footer      - String, footer text
+  #   discount    - Float, discount percentage
+  #   contact_id  - Integer, customer contact ID
+  #   change_address - String, "offer" or "customer"
+  #   tags        - Array of Strings
+  #
+  # == Read-only attributes:
+  #   id, identifier, status, net_total, gross_total, created_at, updated_at
+  #
+  # == Example:
+  #   moco.offers.create(
+  #     deal_id: 123456,
+  #     recipient_address: "Acme Corp\r\n123 Main St",
+  #     date: "2024-01-15",
+  #     due_date: "2024-02-15",
+  #     title: "Offer - Website Relaunch",
+  #     tax: 19.0,
+  #     items: [
+  #       { type: "title", title: "Development Services" },
+  #       { type: "item", title: "Frontend Development", quantity: 40, unit: "h", unit_price: 150.0 },
+  #       { type: "item", title: "Backend Development", quantity: 60, unit: "h", unit_price: 150.0 }
+  #     ]
+  #   )
+  #
+  class Offer < BaseEntity
+    # Update the offer status
+    def update_status(status)
+      client.put("offers/#{id}/update_status", { status: })
+      self
+    end
+
+    # Get the offer as PDF
+    def pdf
+      client.get("offers/#{id}.pdf")
+    end
+
+    # Send the offer via email
+    def send_email(recipient:, subject:, text:, **options)
+      payload = {
+        recipient:,
+        subject:,
+        text:
+      }.merge(options)
+
+      client.post("offers/#{id}/send_email", payload)
+      self
+    end
+
+    # Assign offer to company, project, and/or deal
+    def assign(company_id: nil, project_id: nil, deal_id: nil)
+      payload = {}
+      payload[:company_id] = company_id if company_id
+      payload[:project_id] = project_id if project_id
+      payload[:deal_id] = deal_id if deal_id
+
+      client.put("offers/#{id}/assign", payload)
+      reload
+    end
+
+    # Get attachments for this offer
+    def attachments
+      client.get("offers/#{id}/attachments")
+    end
+
+    # Add an attachment to the offer
+    def add_attachment(file_data)
+      client.post("offers/#{id}/attachments", file_data)
+      self
+    end
+
+    # Delete an attachment from the offer
+    def delete_attachment(attachment_id)
+      client.delete("offers/#{id}/attachments/#{attachment_id}")
+      self
+    end
+
+    # Associations
+    def company
+      association(:customer, "Company")
+    end
+
+    def project
+      association(:project)
+    end
+
+    def deal
+      association(:deal)
+    end
+
+    def to_s
+      "#{identifier} - #{title}"
+    end
+  end
+end

data/lib/moco/entities/offer_approval.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO offer customer approval (Kundenfreigabe)
+  # Allows customers to review and sign offers online
+  #
+  # == Read-only attributes:
+  #   id, approval_url, offer_document_url, active,
+  #   customer_full_name, customer_email, signature_url,
+  #   signed_at, created_at, updated_at
+  #
+  # == Activation workflow:
+  #   1. Activate approval to generate shareable URL
+  #   2. Share offer_document_url with customer
+  #   3. Customer reviews and signs
+  #   4. Check signed_at to verify approval
+  #
+  # == Example:
+  #   # Activate customer approval
+  #   approval = moco.post("offers/123/customer_approval/activate")
+  #
+  #   # Get approval status
+  #   approval = moco.get("offers/123/customer_approval")
+  #
+  #   # Deactivate (revoke access)
+  #   moco.put("offers/123/customer_approval/deactivate")
+  #
+  # == Note:
+  #   Check signed_at to determine if the customer has signed.
+  #   Returns 404 if not yet activated.
+  #
+  class OfferApproval < BaseEntity
+    # Associations
+    def offer
+      association(:offer)
+    end
+
+    def to_s
+      "OfferApproval ##{id}"
+    end
+  end
+end

data/lib/moco/entities/payment_schedule.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO project payment schedule entry
+  # (Geplante Abrechnungen) for fixed-price project milestones
+  #
+  # == Required attributes for create:
+  #   net_total - Float, payment amount
+  #   date      - String, "YYYY-MM-DD" scheduled payment date
+  #
+  # == Optional attributes:
+  #   title       - String, milestone name (e.g., "First installment")
+  #   description - String, milestone details (HTML allowed)
+  #   checked     - Boolean, mark as completed
+  #
+  # == Read-only attributes:
+  #   id, project (Hash), billed, created_at, updated_at
+  #
+  # == Access methods:
+  #   # All payment schedules across projects
+  #   moco.payment_schedules.all
+  #
+  #   # Filter by project
+  #   moco.payment_schedules.where(project_id: 123)
+  #
+  # == Example:
+  #   moco.post("projects/123/payment_schedules", {
+  #     net_total: 5000.0,
+  #     date: "2024-03-15",
+  #     title: "Design Phase Complete"
+  #   })
+  #
+  # == Filtering:
+  #   moco.payment_schedules.where(from: "2024-01-01", to: "2024-12-31")
+  #   moco.payment_schedules.where(checked: false)  # unpaid only
+  #   moco.payment_schedules.where(company_id: 456)
+  #
+  class PaymentSchedule < BaseEntity
+    # Associations
+    def project
+      association(:project)
+    end
+
+    def to_s
+      "PaymentSchedule ##{id} (#{date})"
+    end
+  end
+end

data/lib/moco/entities/planning_entry.rb

@@ -1,8 +1,49 @@
 # frozen_string_literal: true
 
 module MOCO
-  # Represents a MOCO planning entry
-  # Provides methods for planning entry-specific associations
+  # Represents a MOCO planning entry (resource scheduling)
+  # For absences, use Schedule instead
+  #
+  # == Required attributes for create:
+  #   project_id OR deal_id - Integer, must provide exactly one
+  #   starts_on     - String, "YYYY-MM-DD" start date
+  #   ends_on       - String, "YYYY-MM-DD" end date
+  #   hours_per_day - Float/Integer, planned hours per day
+  #
+  # == Optional attributes:
+  #   user_id   - Integer, user ID (default: current user)
+  #   task_id   - Integer, task ID (only with project_id)
+  #   comment   - String, notes about the planning
+  #   symbol    - Integer, 1-10 for visual indicator:
+  #               1=home, 2=building, 3=car, 4=graduation cap, 5=cocktail,
+  #               6=bells, 7=baby carriage, 8=users, 9=moon, 10=info circle
+  #   tentative - Boolean, true if this is a blocker/tentative
+  #
+  # == Read-only attributes:
+  #   id, color, read_only, user (Hash), project (Hash), deal (Hash),
+  #   series_id, series_repeat, created_at, updated_at
+  #
+  # == Example:
+  #   # Plan user on project for a week
+  #   moco.planning_entries.create(
+  #     project_id: 123,
+  #     task_id: 456,
+  #     user_id: 789,
+  #     starts_on: "2024-01-15",
+  #     ends_on: "2024-01-19",
+  #     hours_per_day: 6,
+  #     comment: "Sprint planning"
+  #   )
+  #
+  #   # Plan user on deal (pre-sales)
+  #   moco.planning_entries.create(
+  #     deal_id: 123,
+  #     starts_on: "2024-01-22",
+  #     ends_on: "2024-01-22",
+  #     hours_per_day: 4,
+  #     tentative: true
+  #   )
+  #
   class PlanningEntry < BaseEntity
     # Associations
     def user