moco-ruby 1.0.0 → 1.2.0

data/lib/moco/client.rb

@@ -37,6 +37,16 @@ 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
+
+    # 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 +54,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

data/lib/moco/entities/comment.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO comment/note (Notizen)
+  # Comments can be attached to various entities
+  #
+  # == Required attributes for create:
+  #   commentable_id   - Integer, ID of the entity to attach comment to
+  #   commentable_type - String, entity type:
+  #                      "Project", "Contact", "Company", "Deal", "User", "Unit",
+  #                      "Invoice", "Offer", "Expense", "Receipt", "Purchase",
+  #                      "DeliveryNote", "OfferConfirmation", "InvoiceReminder",
+  #                      "InvoiceDeletion", "InvoiceBookkeepingExport",
+  #                      "RecurringExpense", "ReceiptRefundRequest",
+  #                      "PurchaseBookkeepingExport", "PurchaseDraft"
+  #   text             - String, comment text (plain text or HTML)
+  #
+  # == Optional attributes:
+  #   attachment_filename - String, filename for attachment
+  #   attachment_content  - String, base64-encoded file content
+  #   created_at          - String, timestamp for data migration
+  #
+  # == Read-only attributes:
+  #   id, manual, user (Hash - creator), created_at, updated_at
+  #
+  # == Allowed HTML tags in text:
+  #   div, strong, em, u, pre, ul, ol, li, br
+  #
+  # == Example:
+  #   # Add comment to a project
+  #   moco.comments.create(
+  #     commentable_id: 123,
+  #     commentable_type: "Project",
+  #     text: "<div>Project kickoff on <strong>Jan 15</strong></div>"
+  #   )
+  #
+  # == Filtering:
+  #   moco.comments.where(commentable_type: "Project", commentable_id: 123)
+  #   moco.comments.where(user_id: 456)
+  #   moco.comments.where(manual: true)  # user-created only
+  #
+  class Comment < BaseEntity
+    # Bulk create comments
+    # @param client [MOCO::Client] the client instance
+    # @param comments [Array<Hash>] array of comment attributes
+    # @return [Array<Comment>] created comments
+    def self.bulk_create(client, comments)
+      response = client.post("comments/bulk", { bulk: comments })
+      response.map { |data| new(client, data) }
+    end
+
+    # Associations
+    def user
+      association(:user)
+    end
+
+    def to_s
+      text.to_s.truncate(50)
+    end
+  end
+end

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