moco-ruby 1.1.0 → 1.3.0

data/lib/moco/entities/invoice_attachment.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents an attachment on a MOCO invoice
+  #
+  # == Required attributes for create:
+  #   attachment - Hash with the following keys:
+  #     filename - String, file name including extension (e.g., "appendix.pdf")
+  #     base64   - String, base64-encoded file content
+  #
+  # == Read-only attributes:
+  #   id, title, created_at, updated_at
+  #
+  # == Usage:
+  #   invoice = moco.invoices.find(123)
+  #   invoice.attachments.all
+  #   invoice.attachments.create(
+  #     attachment: {
+  #       filename: "appendix.pdf",
+  #       base64: Base64.strict_encode64(File.read("appendix.pdf"))
+  #     }
+  #   )
+  #   invoice.attachments.find(42).destroy
+  #
+  # == Note:
+  #   The API only supports list (GET), create (POST), and delete (DELETE).
+  #   Update is not available - delete and re-upload to replace.
+  #
+  class InvoiceAttachment < BaseEntity
+    def to_s
+      title.to_s
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO letter paper (letterhead template used on invoices/offers PDFs)
+  # Read-only listing of letterheads configured in the MOCO account.
+  #
+  # == Read-only attributes:
+  #   id, name, active, template, file, created_at, updated_at
+  #
+  # == Usage:
+  #   moco.letter_papers.all
+  #
+  # == Note:
+  #   The API only exposes a list endpoint (GET /letter_papers).
+  #   Use a letter paper's `id` as `letter_paper_id` when fetching
+  #   invoice/offer PDFs (e.g. GET /invoices/{id}.pdf?letter_paper_id=...).
+  #
+  class LetterPaper < BaseEntity
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/offer.rb

@@ -0,0 +1,111 @@
+# 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
+
+    # Fetches attachments for this offer as a NestedCollectionProxy.
+    # Supports .all, .find(id), .create(attachment: { filename:, base64: }), and .destroy.
+    def attachments
+      MOCO::NestedCollectionProxy.new(client, self, :attachments, "OfferAttachment")
+    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/offer_attachment.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents an attachment on a MOCO offer
+  #
+  # == Required attributes for create:
+  #   attachment - Hash with the following keys:
+  #     filename - String, file name including extension (e.g., "appendix.pdf")
+  #     base64   - String, base64-encoded file content
+  #
+  # == Read-only attributes:
+  #   id, title, created_at, updated_at
+  #
+  # == Usage:
+  #   offer = moco.offers.find(123)
+  #   offer.attachments.all
+  #   offer.attachments.create(
+  #     attachment: {
+  #       filename: "appendix.pdf",
+  #       base64: Base64.strict_encode64(File.read("appendix.pdf"))
+  #     }
+  #   )
+  #   offer.attachments.find(42).destroy
+  #
+  # == Note:
+  #   The API only supports list (GET), create (POST), and delete (DELETE).
+  #   Update is not available - delete and re-upload to replace.
+  #
+  class OfferAttachment < BaseEntity
+    def to_s
+      title.to_s
+    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

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
@@ -30,19 +82,42 @@ module MOCO
       MOCO::NestedCollectionProxy.new(client, self, :expenses, "Expense")
     end
 
-    # Fetches tasks associated with this project.
+    # Fetches tasks associated with this project via the API.
+    # Returns a NestedCollectionProxy for lazy loading and CRUD operations.
     def tasks
-      # If tasks are already embedded in the attributes (e.g., from projects.assigned),
-      # return them directly instead of making a new API call
-      embedded_tasks = attributes[:tasks]
-      if embedded_tasks.is_a?(Array) && embedded_tasks.all? { |t| t.is_a?(MOCO::Task) }
-        return embedded_tasks
+      MOCO::NestedCollectionProxy.new(client, self, :tasks, "Task")
+    end
+
+    # Returns embedded tasks from the projects/assigned response, or nil.
+    # These have fewer fields than the full API response but avoid an
+    # extra API call, useful for limited-permission accounts.
+    def embedded_tasks
+      embedded = attributes[:tasks]
+      if embedded.is_a?(Array) && embedded.all? { |t| t.is_a?(MOCO::Task) }
+        embedded
+      else
+        []
       end
+    end
 
-      # Otherwise, create a proxy for fetching tasks via API
-      # 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")
+    # 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