moco-ruby 1.1.0 → 1.3.0

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

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module MOCO
+  # Represents a MOCO API session for authentication.
+  #
+  # The `/session` endpoint exchanges email/password credentials for an
+  # API key, and can verify an existing key.
+  #
+  # == Creating an API key (POST /session):
+  #   result = MOCO::Session.create(
+  #     subdomain: "your-account",
+  #     email: "you@example.com",
+  #     password: "secret"
+  #   )
+  #   result["api_key"] # => "6f95f9a0..."
+  #   result["user_id"] # => 933590696
+  #
+  # == Verifying an existing key (GET /session):
+  #   identity = moco.session.verify
+  #   identity["id"]   # => 933590696
+  #   identity["uuid"] # => "7a60719d-..."
+  #
+  # == Note:
+  #   `create` does not require an existing Client - it uses a temporary
+  #   unauthenticated connection. `verify` uses the Client's configured
+  #   API key.
+  #
+  class Session
+    class << self
+      # Exchange email/password for an API key. Does not require a Client.
+      # Returns a Hash: { "api_key" => "...", "user_id" => ... }
+      def create(subdomain:, email:, password:)
+        conn = Faraday.new(url: "https://#{subdomain}.mocoapp.com/api/v1") do |f|
+          f.request :json
+          f.response :json
+        end
+        response = conn.post("session", { email:, password: })
+        raise MOCO::Error, "Authentication failed: #{response.status}" unless response.success?
+
+        response.body
+      end
+    end
+
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Verify the configured API key. Returns the identity Hash or raises on 401.
+    def verify
+      client.get("session")
+    end
+  end
+end