moco-ruby 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 781b3fd8aed069892a3c387056616917556da295b17878e23e3ec3b8aa8dd8fb
-  data.tar.gz: 1a818a32e9910e7ab30fd978e4e39348dcb7e970717b60e3f2f2b7dd755c6fbb
+  metadata.gz: 94fd15c735a242e23f7a1e20dd49408d12dbfbb21f1665ca64bfd85ba3251cae
+  data.tar.gz: 710f5ce6be51b2c363c6d2b3df871d755e5b21e90e9ad53cbb535ac249b46b6f
 SHA512:
-  metadata.gz: aa1352b7183998b30397668eca16ca9eefbb99659f72fb60812eb14585f284789808defa0e8dfb147e6327a4d540bccf1e0531c3c3946f6753447bee347e3942
-  data.tar.gz: 367888eed8cb0a9bc91d2301a28e9f57ab1cc57f9226e5bd09a91fb71fe52c4220ff65bcb0e2fd7aae903fc12107be37f46e5df7ce27636451a1e7d3800e6807
+  metadata.gz: 272eede87d5a02636ca02354ea0ef592f0d21662378fb6817b68cc6fa73e66922b43623f6ac5da5c4c76ac3db9c6ebaee12a340fcc9920df93104303f96668fd
+  data.tar.gz: 12f55e014641e51ecf2f666c04bff0a5f330ae68b91cf63e70060b6f85e5fc759eed517854060190651581a7ffba5bfa8345fdd25b8e2e59a96193a32cdece9a

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.2
   SuggestExtensions: false
   NewCops: enable
 
@@ -15,12 +15,19 @@ Naming/MethodParameterName:
   AllowedNames:
   - a
   - b
+  - id
 
 Layout/LineLength:
   Max: 130
 
 Metrics/BlockLength:
-  Max: 40
+  Enabled: false
 
 Metrics/ClassLength:
-  Max: 130
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false

data/CHANGELOG.md

@@ -1,7 +1,101 @@
-# Changelog
+# # Changelog
 
 ## [Unreleased]
 
+## [1.0.0] - 2025-10-08
+
+### Fixed
+- Fixed Project `leader` and `co_leader` associations to return User objects instead of Hashes
+- Fixed Expense associations to use proper `association()` method for embedded objects
+- Fixed nested resource proxy caching issue - tasks and expenses now always return fresh data
+- Fixed `NestedCollectionProxy` path construction for expenses (was double-prefixing with "projects/")
+- Fixed `entity_path` warnings by converting instance methods to class methods in Holiday and WebHook classes
+- Fixed embedded entity conversion for leader, co_leader, and user associations in BaseEntity
+
+### Added
+- Added comprehensive test suite using test-unit framework:
+  - `test/test_comprehensive.rb` - 27 integration tests covering all CRUD operations
+  - `test/test_holidays_expenses.rb` - 9 tests for holidays and expenses (nested resources)
+  - `test/test_v2_api.rb` - 4 unit tests with mocked API responses
+  - `test/test_helper.rb` - Shared test configuration
+- Added `Project#expenses` method for nested expense access
+- Added proper entity type mappings for `:leader`, `:co_leader`, and `:user` in BaseEntity
+- Added dotenv gem as development dependency for test environment configuration
+
+### Changed
+- Moved all `require_relative` statements out of methods and into file-level requires
+- Improved load order in `lib/moco.rb` - core classes now load before entities
+- Updated `Expense` entity to use `association()` method for project and user relationships
+- Refactored nested resource access in Project class to return fresh proxies instead of cached ones
+- Enhanced `NestedCollectionProxy` to properly handle nested resource paths without double-prefixing
+
+### Removed
+- Removed manual test scripts (converted to proper test-unit tests)
+
+## [1.0.0.beta] - 2025-04-10
+
+### Fixed
+- Fixed activity synchronization to properly identify existing activities in target system
+- Added remote_id accessor to Activity class to prevent duplicate activity creation
+
+## [1.0.0.alpha] - 2025-04-10
+
+### Added
+- Added support for nested resources with `NestedCollectionProxy` class:
+  - Enables ActiveRecord-style operations on nested resources (e.g., `project.tasks.create`)
+  - Supports proper path construction for nested API endpoints
+  - Implements `destroy_all` method for bulk deletion of nested resources
+
+## [1.0.0.alpha-initial] - 2025-04-10
+
+### Added
+- Implemented ActiveRecord-style query interface (`where`, `find`, `find_by`, `first`, `all`, `each`) via `CollectionProxy`.
+- Added ActiveRecord-style persistence methods to `BaseEntity`:
+  - `save` - Persist changes to an entity
+  - `update` - Update attributes and save in one step
+  - `destroy` - Delete an entity
+  - `reload` - Refresh an entity from the API
+- Added `has_many` method to `BaseEntity` for handling one-to-many associations, complementing the existing `association` method for one-to-one associations.
+- Refactored entity association methods in `Project`, `User`, and `Company` classes to use the new `has_many` method.
+- Added comprehensive project lifecycle test that creates a project, adds tasks and activities, then cleans up.
+- Added support for nested resources with `NestedCollectionProxy` class:
+  - Enables ActiveRecord-style operations on nested resources (e.g., `project.tasks.create`)
+  - Supports proper path construction for nested API endpoints
+  - Implements `destroy_all` method for bulk deletion of nested resources
+- Complete redesign with Ruby-esque API
+- Chainable methods for fluent interface
+- Dynamic entity creation with Rails-style inflection
+- Comprehensive entity coverage for all MOCO API endpoints:
+  - Project
+  - Activity
+  - User
+  - Company
+  - Task
+  - Invoice
+  - Deal
+  - Expense
+  - WebHook
+  - Schedule
+  - Presence
+  - Holiday
+  - PlanningEntry
+- Entity association methods for related entities
+- Automatic entity creation from API responses
+- Struct-based fallback for unknown entity types
+- Generic association method for handling relationships between entities
+
+### Changed
+- Added ActiveSupport dependency for inflection methods
+- Reorganized code structure for better maintainability
+- Updated documentation with new API examples
+- `MOCO::Activity#to_s` now uses `Helpers.decimal_hours_to_civil` for improved time display.
+- Refined core components like `Client`, `CollectionProxy`, and `Connection`.
+- Updated various entity classes (`Activity`, `BaseEntity`, `Presence`, `Project`) with internal improvements.
+- Updated utility scripts (`mocurl.rb`, `sync_activity.rb`).
+
+### Removed
+- Legacy API (`lib/moco/api.rb`) as part of the transition to the new client.
+
 ## [0.1.2] - 2025-04-02
 
 ### Added
@@ -19,18 +113,23 @@
 ## [0.1.1] - 2024-02-27
 
 ### Added
-
 - Prepared for Gem release
 
 ### Changed
-
 - Changed target Ruby version to 2.6 (from 3.x)
 - Applied Rubocop configuration and fixed style errors
 
 ### Security
-
 - Bumped `uri` dependency to 0.13.0
 
 ## [0.1.0] - 2024-02-27
-
 - Initial release
+
+[Unreleased]: https://github.com/starsong-consulting/moco-ruby/compare/v1.0.0...HEAD
+[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
+[1.0.0.alpha-initial]: https://github.com/starsong-consulting/moco-ruby/compare/v0.1.2...v1.0.0.alpha-initial
+[0.1.2]: https://github.com/starsong-consulting/moco-ruby/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/starsong-consulting/moco-ruby/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/starsong-consulting/moco-ruby/releases/tag/v0.1.0

data/Gemfile

@@ -5,5 +5,7 @@ source "https://rubygems.org/"
 gemspec
 
 gem "rake", "~> 13.0"
-
 gem "rubocop", "~> 1.21"
+gem "test-unit", "~> 3.5"
+gem "webmock", "~> 3.18"
+gem "dotenv", "~> 2.8"

data/Gemfile.lock

@@ -1,57 +1,106 @@
 PATH
   remote: .
   specs:
-    moco-ruby (0.1.1)
+    moco-ruby (1.0.0)
+      activesupport (~> 7.0)
       faraday (~> 2.9.0)
       fuzzy_match (~> 2.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    faraday (2.9.0)
+    activesupport (7.2.2.1)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      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)
+    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)
+      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.0)
+    faraday-net_http (3.1.1)
       net-http
     fuzzy_match (2.1.0)
-    json (2.7.1)
-    language_server-protocol (3.17.0.3)
-    net-http (0.4.1)
+    hashdiff (1.1.2)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    json (2.10.2)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.25.5)
+    net-http (0.6.0)
       uri
-    parallel (1.24.0)
-    parser (3.3.0.5)
+    parallel (1.26.3)
+    parser (3.3.7.4)
       ast (~> 2.4.1)
       racc
-    racc (1.7.3)
+    power_assert (2.0.5)
+    prism (1.4.0)
+    public_suffix (6.0.1)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.1.0)
-    regexp_parser (2.9.0)
-    rexml (3.2.6)
-    rubocop (1.60.2)
+    rake (13.2.1)
+    regexp_parser (2.10.0)
+    rexml (3.4.1)
+    rubocop (1.75.2)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.30.0)
-      parser (>= 3.2.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.44.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
     ruby-progressbar (1.13.0)
-    unicode-display_width (2.5.0)
-    uri (0.13.0)
+    securerandom (0.4.1)
+    test-unit (3.6.8)
+      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)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
 
 DEPENDENCIES
+  dotenv (~> 2.8)
   moco-ruby!
   rake (~> 13.0)
   rubocop (~> 1.21)
+  test-unit (~> 3.5)
+  webmock (~> 3.18)
 
 BUNDLED WITH
    2.4.1

data/README.md

@@ -1,6 +1,8 @@
-# moco-ruby
+# MOCO Ruby Gem
 
-A Ruby Gem to interact with the [MOCO API](https://hundertzehn.github.io/mocoapp-api-docs/).
+[![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.
 
 ## Installation
 
@@ -14,88 +16,256 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-### MOCO::API
+### Initialization
+
+```ruby
+require 'moco'
+
+moco = MOCO::Client.new(
+  subdomain: "your-subdomain", # Your MOCO subdomain
+  api_key: "your-api-key"      # Your MOCO API key
+)
+```
+
+### Accessing Collections
+
+Collections are accessed dynamically using pluralized entity names (following Rails conventions):
+
+```ruby
+projects    = moco.projects
+activities  = moco.activities
+users       = moco.users
+# ... and so on for all supported entities
+```
+
+### Fetching Entities
+
+```ruby
+# Get all entities in a collection
+all_projects = moco.projects.all
+
+# Get entities matching specific criteria
+active_projects = moco.projects.where(active: true)
+recent_activities = moco.activities.where(date: ">=2024-01-01")
+
+# Get a specific entity by ID
+project = moco.projects.find(12345)
+user = moco.users.find(678)
+```
+
+### Creating Entities
 
 ```ruby
-moco = MOCO::API.new(subdomain, api_key)
-assigned_projects = moco.get_assigned_projects(active: 'true')
-assigned_projects.each do |project|
-  puts "Project \##{project.id} #{project.name} for customer #{project.customer.name}"
-  project.tasks.each do |task|
-    puts "- Task #{task.name} is #{task.billable ? 'billable' : 'not billable'}"
-  end
+# Create a new project
+new_project = moco.projects.create(
+  name: "New Website Project",
+  customer_id: 987,
+  billable: true
+)
+puts "Created project: #{new_project.name} (ID: #{new_project.id})"
+
+# Create a new time entry (activity)
+new_activity = moco.activities.create(
+  date: "2024-04-10",
+  project_id: new_project.id,
+  task_id: new_project.tasks.first.id, # Assumes project has tasks
+  hours: 3.5,
+  description: "Implemented feature X"
+)
+puts "Created activity: #{new_activity.description} on #{new_activity.date}"
+```
+
+### Updating Entities
+
+Modify attributes and call `save`:
+
+```ruby
+project = moco.projects.find(12345)
+project.name = "Updated Project Name"
+project.billable = false
+
+if project.save
+  puts "Project updated successfully."
+else
+  puts "Failed to update project: #{project.errors.full_messages.join(", ")}" # Assuming error handling exists
+end
+
+# You can also update directly via the collection
+moco.projects.update(12345, name: "Another Update", active: false)
+```
+
+### Deleting Entities
+
+```ruby
+# Delete by object
+activity = moco.activities.find(9876)
+if activity&.delete
+  puts "Activity deleted."
+end
+
+# Delete by ID via collection
+if moco.activities.delete(9876)
+  puts "Activity deleted."
 end
 ```
 
-### MOCO::Entities
+### Entity Associations
 
-The following entities are currently defined:
+Entities provide methods to access related entities easily:
 
-- Project (:id, :active, :name, :customer, :tasks)
-- Task (:id, :active, :name, :project_id, :billable)
-- Activity (:id, :active, :date, :description, :project, :task, :seconds, :hours, :billable, :billed, :user, :customer, :tag)
-- Customer (:id, :name)
-- User (:id, :firstname, :lastname)
+```ruby
+project = moco.projects.find(12345)
+
+# Get tasks associated with the project
+tasks = project.tasks # Returns a collection proxy for tasks
+puts "Tasks for project '#{project.name}': #{tasks.map(&:name).join(', ')}"
+
+# Get activities for the project
+project_activities = project.activities
+puts "Activities count: #{project_activities.size}"
 
-The entities implement comparison, hash and JSON conversion.
+# Get the customer (company) for the project
+customer = project.customer # Returns a MOCO::Company object
+puts "Customer: #{customer.name}"
 
-### MOCO::Sync
+# ---
 
-Intelligently matches and syncs data from one MOCO instance to another.
-Currently supports activities (time entries) only.
-See `sync_activity.rb` for a more detailed example.
+activity = moco.activities.find(9876)
+
+# Get the associated project, task, and user
+act_project = activity.project
+act_task = activity.task
+act_user = activity.user
+puts "Activity by #{act_user.firstname} on project '#{act_project.name}' (Task: #{act_task.name})"
+```
+
+### Nested Resources
+
+The gem supports ActiveRecord-style operations on nested resources:
 
 ```ruby
-source_api = MOCO::API.new(source_instance, source_api_key)
-target_api = MOCO::API.new(target_instance, target_api_key)
-
-syncer = MOCO::Sync.new(
-  source_api,
-  target_api,
-  project_match_threshold: options[:match_project_threshold],
-  task_match_threshold: options[:match_task_threshold],
-  filters: {
-    source: options.slice(:from, :to, :project_id, :company_id, :term),
-    target: options.slice(:from, :to)
-  },
-  dry_run: options[:dry_run]
+project = moco.projects.find(12345)
+
+# Create a new task for the project
+new_task = project.tasks.create(
+  name: "New Feature Development",
+  billable: true,
+  active: true,
+  budget: 40,
+  hourly_rate: 120
 )
+puts "Created task: #{new_task.name} (ID: #{new_task.id})"
+
+# Delete all tasks for a project
+project.tasks.destroy_all
+
+# Query tasks with conditions
+billable_tasks = project.tasks.where(billable: true).all
+puts "Billable tasks: #{billable_tasks.map(&:name).join(', ')}"
+
+# Find a specific task
+dev_task = project.tasks.find_by(name: "Development")
 ```
 
+### 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`).
+
 ## Utilities
 
-Utilities can use `config.yml` to fetch instance data and other configuration. For format, see `config.yml.sample`.
+These command-line utilities provide helpful shortcuts. They can use credentials and configuration from a `config.yml` file (see `config.yml.sample`) in the current directory or accept parameters.
 
-### mocurl
+### `mocurl`
 
-Run an API request against a MOCO instance and return the result nicely formatted.
-Use config.yml or specify api key with `-a`.
+A wrapper around `curl` to easily make authenticated requests to your MOCO instance API. Useful for testing or exploring endpoints.
 
 ```
 Usage: mocurl.rb [options] url
        mocurl.rb [options] subdomain path
-    -X, --method METHOD              Set HTTP method to use
-    -d, --data DATA                  Data to send to server, JSON format
-    -a, --api-key API_KEY            Manually specify MOCO API key
-    -n, --no-format                  Disable JSON pretty-printing
+    -X, --method METHOD              Set HTTP method to use (GET, POST, PUT, DELETE)
+    -d, --data DATA                  Data to send to server (JSON format) for POST/PUT
+    -a, --api-key API_KEY            Manually specify MOCO API key (overrides config.yml)
+    -n, --no-format                  Disable JSON pretty-printing of the response
     -v, --verbose                    Show additional request and response information
     -h, --help                       Show this message
 ```
+**Example:** `mocurl.rb your-subdomain projects/12345`
+
+### `sync_activity`
 
-### sync_activity
+Syncs activity data (time entries) between two MOCO instances (source and target). It uses fuzzy matching to map projects and tasks between the instances.
 
-Sync activity data (time entries) from one instance to another, fuzzy matching projects and tasks.
-It is highly recommended to use filter options (`--from`, `--to`) and to use `--dry-run` first to check the matching performance.
+**Important:**
+*   Always use `--dry-run` first to verify the matching and intended actions.
+*   Use date filters (`--from`, `--to`) to limit the scope.
 
 ```
-Usage: sync_activity.rb [options] source target
-    -f, --from DATE                  Start date (YYYY-MM-DD)
-    -t, --to DATE                    End date (YYYY-MM-DD)
-    -p, --project PROJECT_ID         Project ID to filter by
-    -c, --company COMPANY_ID         Company ID to filter by
-    -g, --term TERM                  Term to filter for
-    -n, --dry-run                    Match only, but do not edit data
+Usage: sync_activity.rb [options] source_subdomain target_subdomain
+    -f, --from DATE                  Start date for sync (YYYY-MM-DD)
+    -t, --to DATE                    End date for sync (YYYY-MM-DD)
+    -p, --project PROJECT_ID         Source Project ID to filter by (optional)
+    -c, --company COMPANY_ID         Source Company ID to filter by (optional)
+    -g, --term TERM                  Term to filter source activities by (optional)
+    -n, --dry-run                    Perform matching and show planned actions, but do not modify target instance
         --match-project-threshold VALUE
-                                     Project matching threshold (0.0 - 1.0), default 0.8
-        --match-task-threshold VALUE Task matching threshold (0.0 - 1.0), default 0.45
+                                     Fuzzy match threshold for projects (0.0 - 1.0), default 0.8
+        --match-task-threshold VALUE Fuzzy match threshold for tasks (0.0 - 1.0), default 0.45
+    -h, --help                       Show this message
 ```
+**Example:** `sync_activity.rb --from 2024-04-01 --to 2024-04-10 --dry-run source-instance target-instance`
+
+## Development
+
+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):
+
+```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)
+
+# Or run individually
+ruby test/test_v2_api.rb
+```
+
+For integration tests, create a `.env` file with your test instance credentials:
+```
+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.
+
+### Installation
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update the version number in `version.rb`, update the `CHANGELOG.md`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/starsong-consulting/moco-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).