moco-ruby 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e60f0a59b12881fc99571967ff77dd1ae8c55ff8f3d45cd467bed9e6bf85c5d
-  data.tar.gz: a2070fba649482eb59f4ab96367cc5d8f12b5bfb0f6923bc7e7f6d2c69135566
+  metadata.gz: a32219e92cf0b5cc11f885486ec9a0afce63d39d2a2de95f3d5225b5521020e5
+  data.tar.gz: fa20563a9ff63d9b412540b99beecdab249ee7dca31608d23a47a82926062f27
 SHA512:
-  metadata.gz: 867202c4431ae5a1d86fe9a8b18451c4cff6465d2119f5e9738d8a1b3018c6b81c726c00860762cf97ad233632df61bc38588ee0cf2d468f9516e36d65d3ed9f
-  data.tar.gz: 5a7cebee47463f888880ae2f9c0fa672e294adb2a0a1abcf3f098cfe241ac35eb84091607c035d36658cf5eb386880f3fc7f2db2abd0c5de8668c9ae72622333
+  metadata.gz: 63995cff5c2e36f43619a43e04208460d8aa3a899f06a8b4e0acc673655af550ac40f472519096a8da21d73d850705a4d4a10d788287eb6cac1a461d614c4139
+  data.tar.gz: 7be74a0104d6bfffd3d3bb93f6658db539ec1727e108795f69a63c1b38447d0876eb21187c0557936fa0b70d7457a4150bccd9eed3ba04e8df6f3d32c59179ef

data/.rubocop.yml

@@ -16,6 +16,7 @@ Naming/MethodParameterName:
   - a
   - b
   - id
+  - to
 
 Layout/LineLength:
   Max: 130

data/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-05-23
+
+### Added
+- New entities to cover remaining MOCO API v1 resources: `LetterPaper`
+  (read-only letterhead listing), `InvoiceAttachment`, `OfferAttachment`,
+  and `Session` (API key exchange/verification).
+- `MOCO::Session.create(subdomain:, email:, password:)` exchanges credentials
+  for an API key without requiring an existing `Client`.
+- `moco.session.verify` confirms the configured API key and returns the user
+  identity.
+
+### Changed
+- `Invoice#attachments` and `Offer#attachments` now return a
+  `NestedCollectionProxy` of typed `InvoiceAttachment` / `OfferAttachment`
+  entities, replacing the previous raw `add_attachment` / `delete_attachment`
+  helpers. Use `invoice.attachments.create(attachment: { filename:, base64: })`
+  and `invoice.attachments.find(id).destroy` instead.
+- Documentation URLs updated from `hundertzehn.github.io/mocoapp-api-docs`
+  (legacy) to `docs.mocoapp.com/api/docs/v1` (current OpenAPI reference).
+
+## [1.2.0] - 2026-01-14
+
+### Added
+- Complete MOCO API coverage with 48+ entity types
+- New entities: Offer, Contact, Tagging, DealCategory, CatalogService, CustomProperty,
+  ExpenseTemplate, FixedCost, HourlyRate, InternalHourlyRate, TaskTemplate, UserRole,
+  VatCodeSale, VatCodePurchase, Profile, WorkTimeAdjustment, ProjectContract,
+  PaymentSchedule, RecurringExpense, InvoicePayment, InvoiceReminder, OfferApproval,
+  PurchaseCategory, PurchaseDraft, ProjectGroup, InvoiceBookkeepingExport,
+  PurchaseBookkeepingExport, PurchaseBudget, PurchasePayment
+- Inline attribute documentation for all entity classes
+- Reports API support via `moco.reports.absences`, `.cashflow`, `.finance`, `.utilization`
+- Integration tests for all entity types
+- GitHub Actions CI for tests and auto-release
+- Ruby 4.0 support
+
+### Fixed
+- Debug output now correctly shows request body for POST/PUT/PATCH requests
+
+## [1.1.0] - 2025-11-15
+
+### Added
+- Support for limited-permission accounts with auto-create missing tasks
+- `--default-task` flag for limited-permission accounts
+- `copy_project` tool for copying projects between MOCO instances
+
+### Fixed
+- Enable auto-require for Bundler
+- Loosen dependency constraints for Rails 8 compatibility
+
+### Security
+- Update rexml to 3.4.4 to fix CVE-2025-58767
+
 ## [1.0.0] - 2025-10-08
 
 ### Fixed
@@ -125,7 +178,9 @@
 ## [0.1.0] - 2024-02-27
 - Initial release
 
-[Unreleased]: https://github.com/starsong-consulting/moco-ruby/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/starsong-consulting/moco-ruby/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/starsong-consulting/moco-ruby/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/starsong-consulting/moco-ruby/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/starsong-consulting/moco-ruby/compare/v1.0.0.beta...v1.0.0
 [1.0.0.beta]: https://github.com/starsong-consulting/moco-ruby/compare/v1.0.0.alpha...v1.0.0.beta
 [1.0.0.alpha]: https://github.com/starsong-consulting/moco-ruby/compare/v1.0.0.alpha-initial...v1.0.0.alpha

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    moco-ruby (1.0.0)
+    moco-ruby (1.3.0)
       activesupport (>= 7.0)
       faraday (>= 2.0)
       fuzzy_match (~> 2.1.0)
@@ -9,59 +9,63 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.2.2.1)
+    activesupport (8.1.3)
       base64
-      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+      uri (>= 0.13.1)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
-    base64 (0.2.0)
-    benchmark (0.4.0)
-    bigdecimal (3.1.9)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.0)
-    crack (1.0.0)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    crack (1.0.1)
       bigdecimal
       rexml
     dotenv (2.8.1)
-    drb (2.2.1)
-    faraday (2.9.2)
-      faraday-net_http (>= 2.0, < 3.2)
-    faraday-net_http (3.1.1)
-      net-http
+    drb (2.2.3)
+    faraday (2.14.2)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.3)
+      net-http (~> 0.5)
     fuzzy_match (2.1.0)
-    hashdiff (1.1.2)
-    i18n (1.14.7)
+    hashdiff (1.2.1)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.10.2)
-    language_server-protocol (3.17.0.4)
+    json (2.19.5)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.25.5)
-    net-http (0.6.0)
-      uri
-    parallel (1.26.3)
-    parser (3.3.7.4)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    parallel (1.27.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
-    power_assert (2.0.5)
-    prism (1.4.0)
-    public_suffix (6.0.1)
+    power_assert (3.0.1)
+    prism (1.9.0)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.10.0)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
     rexml (3.4.4)
-    rubocop (1.75.2)
+    rubocop (1.82.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -69,23 +73,23 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.0)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    test-unit (3.6.8)
+    test-unit (3.7.7)
       power_assert
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
-    uri (1.0.3)
-    webmock (3.25.1)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
@@ -93,6 +97,7 @@ GEM
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
+  x86_64-linux
 
 DEPENDENCIES
   dotenv (~> 2.8)

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/moco-ruby.svg)](https://badge.fury.io/rb/moco-ruby)
 
-A Ruby Gem to interact with the [MOCO API](https://hundertzehn.github.io/mocoapp-api-docs/). This gem provides a modern, Ruby-esque interface (`MOCO::Client`) for interacting with the MOCO API.
+A Ruby Gem to interact with the [MOCO API](https://docs.mocoapp.com/api/docs/v1). This gem provides a modern, Ruby-esque interface (`MOCO::Client`) for interacting with the MOCO API.
 
 ## Installation
 
@@ -167,25 +167,98 @@ puts "Billable tasks: #{billable_tasks.map(&:name).join(', ')}"
 dev_task = project.tasks.find_by(name: "Development")
 ```
 
+### Profile
+
+Access the current user's profile:
+
+```ruby
+profile = moco.profile
+puts "Logged in as: #{profile.firstname} #{profile.lastname}"
+```
+
+### Sessions
+
+Exchange email/password for an API key, or verify an existing key:
+
+```ruby
+# Exchange credentials for an API key (no Client needed)
+session = MOCO::Session.create(
+  subdomain: "your-subdomain",
+  email: "you@example.com",
+  password: "secret"
+)
+api_key = session["api_key"]
+
+# Verify the configured API key for an existing client
+identity = moco.session.verify
+puts "Authenticated as user #{identity['id']} (#{identity['uuid']})"
+```
+
+### Invoice / Offer Attachments
+
+Attachments are nested under the parent document and use base64-encoded uploads:
+
+```ruby
+require "base64"
+
+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
+
+# Offer attachments work the same way:
+moco.offers.find(123).attachments.create(
+  attachment: { filename: "quote-details.pdf", base64: ... }
+)
+```
+
+### Reports
+
+Access read-only report endpoints:
+
+```ruby
+# Absences report
+absences = moco.reports.absences(year: 2024)
+
+# Utilization report (requires date range)
+utilization = moco.reports.utilization(from: "2024-01-01", to: "2024-12-31")
+
+# Financial reports
+cashflow = moco.reports.cashflow(from: "2024-01-01", to: "2024-03-31")
+finance = moco.reports.finance(from: "2024-01-01", to: "2024-03-31")
+```
+
 ### Supported Entities
 
 The gem supports all MOCO API entities with a Ruby-esque interface:
 
-- `Project`
-- `Activity`
-- `User`
-- `Company`
-- `Task`
-- `Invoice`
-- `Deal`
-- `Expense`
-- `WebHook`
-- `Schedule`
-- `Presence`
-- `Holiday`
-- `PlanningEntry`
-
-Access them via the moco using their plural, snake_case names (e.g., `moco.planning_entries`).
+**Core:**
+`Project`, `Activity`, `User`, `Company`, `Task`, `Invoice`, `Deal`, `Expense`, `WebHook`, `Schedule`, `Presence`, `Holiday`, `PlanningEntry`
+
+**Business:**
+`Contact`, `Offer`, `Purchase`, `Receipt`, `Comment`, `Tag`, `Tagging`, `DealCategory`, `ProjectGroup`, `Unit`
+
+**Account Settings:**
+`CatalogService`, `CustomProperty`, `ExpenseTemplate`, `FixedCost`, `HourlyRate`, `InternalHourlyRate`, `TaskTemplate`, `UserRole`
+
+**Financial:**
+`VatCodeSale`, `VatCodePurchase`, `PurchaseCategory`, `PurchaseDraft`, `PurchaseBudget`, `PurchasePayment`
+
+**Bookkeeping:**
+`InvoiceBookkeepingExport`, `PurchaseBookkeepingExport`
+
+**Nested Resources:**
+`Employment`, `WorkTimeAdjustment`, `ProjectContract`, `PaymentSchedule`, `RecurringExpense`, `InvoicePayment`, `InvoiceReminder`, `OfferApproval`, `InvoiceAttachment`, `OfferAttachment`
+
+**Misc:**
+`LetterPaper` (read-only), `Session` (for API key exchange/verification)
+
+Access them via the client using their plural, snake_case names (e.g., `moco.planning_entries`, `moco.vat_code_sales`, `moco.letter_papers`). Attachments are accessed via the parent: `invoice.attachments`, `offer.attachments`.
 
 ## Utilities
 
@@ -246,16 +319,16 @@ After checking out the repo, run `bin/setup` to install dependencies.
 
 ### Running Tests
 
-The gem includes a comprehensive test suite with both unit tests (mocked) and integration tests (live API):
+The gem includes unit tests (mocked) and integration tests (live API):
 
 ```bash
-# Run all tests
-ruby test/test_v2_api.rb              # Unit tests (mocked, fast)
-ruby test/test_comprehensive.rb       # Integration tests (requires .env)
-ruby test/test_holidays_expenses.rb   # Holidays & Expenses tests (requires .env)
+# Unit tests (mocked, fast)
+bundle exec ruby -Ilib -Itest test/test_v2_api.rb
+bundle exec ruby -Ilib -Itest test/test_new_entities.rb
 
-# Or run individually
-ruby test/test_v2_api.rb
+# Integration tests (requires .env credentials)
+bundle exec ruby -Ilib -Itest test/test_integration.rb
+bundle exec ruby -Ilib -Itest test/test_comprehensive.rb
 ```
 
 For integration tests, create a `.env` file with your test instance credentials:
@@ -264,7 +337,7 @@ MOCO_API_TEST_SUBDOMAIN=your-test-subdomain
 MOCO_API_TEST_API_KEY=your-test-api-key
 ```
 
-**Note:** The MOCO API has rate limits (120 requests per 2 minutes on standard plans). Integration tests make real API calls.
+**Note:** The MOCO API has rate limits. The gem automatically retries rate-limited requests with exponential backoff.
 
 ### Installation
 
@@ -278,4 +351,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/starso
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).

data/lib/moco/client.rb

@@ -37,6 +37,23 @@ module MOCO
       name.to_s == ActiveSupport::Inflector.pluralize(name.to_s)
     end
 
+    # Get the current user's profile (singleton resource)
+    def profile
+      Profile.new(self, get("profile"))
+    end
+
+    # Session helper for verifying the configured API key.
+    # Use MOCO::Session.create(subdomain:, email:, password:) to exchange
+    # credentials for an API key without a Client.
+    def session
+      @session ||= Session.new(self)
+    end
+
+    # Reports namespace for read-only report endpoints
+    def reports
+      @reports ||= ReportsProxy.new(self)
+    end
+
     # Delegate HTTP methods to connection
     %i[get post put patch delete].each do |method|
       define_method(method) do |path, params = {}|
@@ -44,4 +61,52 @@ module MOCO
       end
     end
   end
+
+  # Proxy for accessing report endpoints
+  class ReportsProxy
+    def initialize(client)
+      @client = client
+    end
+
+    # Get absences report
+    # @param year [Integer] optional year filter
+    # @param active [Boolean] optional active status filter
+    def absences(year: nil, active: nil)
+      params = {}
+      params[:year] = year if year
+      params[:active] = active unless active.nil?
+      @client.get("report/absences", params)
+    end
+
+    # Get cashflow report
+    # @param from [String] start date (YYYY-MM-DD)
+    # @param to [String] end date (YYYY-MM-DD)
+    # @param term [String] optional search term
+    def cashflow(from: nil, to: nil, term: nil)
+      params = {}
+      params[:from] = from if from
+      params[:to] = to if to
+      params[:term] = term if term
+      @client.get("report/cashflow", params)
+    end
+
+    # Get finance report
+    # @param from [String] start date (YYYY-MM-DD)
+    # @param to [String] end date (YYYY-MM-DD)
+    # @param term [String] optional search term
+    def finance(from: nil, to: nil, term: nil)
+      params = {}
+      params[:from] = from if from
+      params[:to] = to if to
+      params[:term] = term if term
+      @client.get("report/finance", params)
+    end
+
+    # Get utilization report
+    # @param from [String] start date (YYYY-MM-DD) - required
+    # @param to [String] end date (YYYY-MM-DD) - required
+    def utilization(from:, to:)
+      @client.get("report/utilization", { from:, to: })
+    end
+  end
 end

data/lib/moco/connection.rb

@@ -22,34 +22,57 @@ module MOCO
       end
     end
 
+    # Maximum retries for rate-limited requests
+    MAX_RETRIES = 3
+    # Base delay between retries (seconds)
+    RETRY_DELAY = 1.0
+
     # Define methods for HTTP verbs (get, post, put, patch, delete)
     # These methods send the request and return the raw parsed JSON response body.
     %w[get post put patch delete].each do |http_method|
       define_method(http_method) do |path, params = {}|
-        # Log URL if debug is enabled
-        if @debug
-          full_url = @conn.build_url(path, params).to_s
-          warn "[DEBUG] Fetching URL: #{http_method.upcase} #{full_url}"
-        end
-        response = @conn.send(http_method, path, params)
+        retries = 0
 
-        # Raise an error for non-successful responses
-        unless response.success?
-          # Attempt to parse error details from the body, otherwise use status/reason
-          error_details = response.body.is_a?(Hash) ? response.body["message"] : response.body
-          # Explicitly pass nil for original_error, and response for the third argument
-          # raise MOCO::Error.new("MOCO API Error: #{response.status} #{response.reason_phrase}. Details: #{error_details}",
-          #                       nil, response)
-          # Use RuntimeError for now
-          raise "MOCO API Error: #{response.status} #{response.reason_phrase}. Details: #{error_details}"
-        end
+        loop do
+          begin
+            # Log request if debug is enabled
+            if @debug
+              if %w[post put patch].include?(http_method)
+                # For body methods, show the JSON that will be sent
+                warn "[DEBUG] #{http_method.upcase} #{@conn.url_prefix}/#{path}"
+                warn "[DEBUG] Body: #{params.to_json}" unless params.empty?
+              else
+                # For query methods, show the full URL with params
+                full_url = @conn.build_url(path, params).to_s
+                warn "[DEBUG] #{http_method.upcase} #{full_url}"
+              end
+            end
+
+            response = @conn.send(http_method, path, params)
 
-        response.body
-      rescue Faraday::Error => e
-        # Wrap Faraday errors - pass e as the second argument (original_error)
-        # raise MOCO::Error.new("Faraday Connection Error: #{e.message}", e)
-        # Use RuntimeError for now
-        raise "Faraday Connection Error: #{e.message}"
+            # Handle rate limiting with automatic retry
+            if response.status == 429 && retries < MAX_RETRIES
+              retries += 1
+              # Get Retry-After header or use exponential backoff
+              retry_after = response.headers["Retry-After"]&.to_f || (RETRY_DELAY * (2**retries))
+              warn "[RATE LIMITED] Waiting #{retry_after}s before retry #{retries}/#{MAX_RETRIES}..." if @debug
+              sleep(retry_after)
+              next
+            end
+
+            # Raise an error for non-successful responses
+            unless response.success?
+              # Attempt to parse error details from the body, otherwise use status/reason
+              error_details = response.body.is_a?(Hash) ? response.body["message"] : response.body
+              raise "MOCO API Error: #{response.status} #{response.reason_phrase}. Details: #{error_details}"
+            end
+
+            return response.body
+          rescue Faraday::Error => e
+            # Wrap Faraday errors
+            raise "Faraday Connection Error: #{e.message}"
+          end
+        end
       end
     end
 

data/lib/moco/entities/activity.rb

@@ -2,7 +2,37 @@
 
 module MOCO
   # Represents a MOCO activity (time entry)
-  # Provides methods for activity-specific operations and associations
+  #
+  # == Required attributes for create:
+  #   date        - String, "YYYY-MM-DD" format (e.g., "2024-01-15")
+  #   project_id  - Integer, ID of the project
+  #   task_id     - Integer, ID of the task within the project
+  #
+  # == Optional attributes:
+  #   seconds     - Integer, duration in seconds (3600 = 1 hour)
+  #   hours       - Float, duration in hours (alternative to seconds)
+  #   description - String, description of the work done
+  #   billable    - Boolean, whether the activity is billable (default: true or project setting)
+  #   tag         - String, any tag (e.g., "RMT-123")
+  #   remote_service - String, external service name. Allowed: "trello", "jira", "asana",
+  #                    "basecamp", "wunderlist", "basecamp2", "basecamp3", "toggl", "mite",
+  #                    "github", "youtrack"
+  #   remote_id   - String, ID in the external service (e.g., "PRJ-2342")
+  #   remote_url  - String, URL to the external ticket/issue
+  #
+  # == Read-only attributes (returned by API):
+  #   id, billed, invoice_id, project (Hash), task (Hash), customer (Hash),
+  #   user (Hash), hourly_rate, timer_started_at, created_at, updated_at
+  #
+  # == Example:
+  #   moco.activities.create(
+  #     date: "2024-01-15",
+  #     project_id: 123456,
+  #     task_id: 234567,
+  #     seconds: 3600,
+  #     description: "Implemented feature X"
+  #   )
+  #
   class Activity < BaseEntity
     # Instance methods for activity-specific operations
     def start_timer

data/lib/moco/entities/catalog_service.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO catalog service (Leistungskatalog)
+  # Pre-defined service templates for offers/invoices
+  #
+  # == Required attributes for create:
+  #   title - String, catalog entry name
+  #
+  # == Optional attributes:
+  #   items - Array of item hashes, service line items
+  #
+  # == Item types:
+  #   { type: "title", title: "Section" }
+  #   { type: "description", description: "Details..." }
+  #   { type: "item", title: "Service", quantity: 10, unit: "h", unit_price: 150.0, net_total: 1500.0 }
+  #   { type: "item", title: "Fixed Fee", net_total: 500.0 }  # lump sum (quantity=0)
+  #   { type: "subtotal", part: true }  # subtotal for section
+  #   { type: "separator" }
+  #   { type: "page-break" }
+  #
+  # == Item attributes:
+  #   title       - String, item title
+  #   description - String, item description
+  #   quantity    - Float, number of units (0 for lump sum)
+  #   unit        - String, unit type (e.g., "h", "pieces")
+  #   unit_price  - Float, price per unit
+  #   net_total   - Float, total price for this item
+  #   unit_cost   - Float, internal cost per unit
+  #   optional    - Boolean, mark as optional
+  #   additional  - Boolean, mark as additional service
+  #
+  # == Read-only attributes:
+  #   id, items (Array), created_at, updated_at
+  #
+  # == Example:
+  #   moco.catalog_services.create(
+  #     title: "Web Development Package",
+  #     items: [
+  #       { type: "item", title: "Setup", net_total: 1200.0 },
+  #       { type: "item", title: "Development", quantity: 40, unit: "h", unit_price: 150.0, net_total: 6000.0 }
+  #     ]
+  #   )
+  #
+  class CatalogService < BaseEntity
+    def self.entity_path
+      "account/catalog_services"
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
+end