monday_ruby 1.0.0 → 1.2.0

data/docs/explanation/migration/v1.md

@@ -0,0 +1,808 @@
+# Migration Guide: Upgrading to v1.0.0
+
+This guide will help you migrate from monday_ruby v0.x to v1.x. The v1.0.0 release introduces a major architectural change that improves code organization, maintainability, and developer experience.
+
+## Overview of Changes
+
+Version 1.0.0 introduces a **client-resource architecture** that replaces the previous flat API design. This change provides better code organization, more consistent naming conventions, and improved maintainability for future features.
+
+### What Changed
+
+- **Architecture**: Moved from a flat API with mixed-in modules to a modular resource class system
+- **Method Access**: Resources are now accessed through dedicated resource objects instead of directly on the client
+- **Method Names**: Resource methods are now more consistent and predictable
+- **Code Organization**: Each resource is encapsulated in its own class with clear responsibilities
+
+### Why These Changes Were Made
+
+The v0.x architecture had several limitations:
+
+1. **Poor Separation of Concerns**: All resource methods were mixed into the client class, making it bloated
+2. **Namespace Pollution**: Every resource method was directly accessible on the client, leading to potential naming conflicts
+3. **Inconsistent Naming**: Method names like `create_board`, `update_item` were inconsistent with `account` (no verb)
+4. **Difficult to Extend**: Adding new resources required modifying multiple files and careful management of method names
+5. **Testing Challenges**: Testing individual resources was difficult due to tight coupling
+
+The new architecture solves these problems by:
+
+- Encapsulating each resource in its own class
+- Providing consistent method naming across all resources
+- Enabling easier testing and maintenance
+- Following Ruby best practices and modern API design patterns
+- Setting a foundation for future features like pagination, filtering, and more
+
+## Breaking Changes
+
+### 1. Resource Access Pattern
+
+The most significant change is how you access resources. All resource methods now require accessing the resource object first.
+
+#### Before (v0.x)
+
+```ruby
+client = Monday::Client.new(token: "your_token")
+
+# Resources accessed directly on client
+response = client.account
+response = client.boards
+response = client.items
+```
+
+#### After (v1.x)
+
+```ruby
+client = Monday::Client.new(token: "your_token")
+
+# Resources accessed through resource objects
+response = client.account.query
+response = client.board.query
+response = client.item.query
+```
+
+### 2. Method Name Changes
+
+All resource methods have been renamed to be more consistent and predictable.
+
+#### Account Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.account` | `client.account.query` |
+
+#### Board Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.boards` | `client.board.query` |
+| `client.create_board` | `client.board.create` |
+| `client.update_board` | `client.board.update` |
+| `client.duplicate_board` | `client.board.duplicate` |
+| `client.archive_board` | `client.board.archive` |
+| `client.delete_board` | `client.board.delete` |
+| `client.delete_board_subscribers` | `client.board.delete_subscribers` |
+
+#### Item Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.items` | `client.item.query` |
+| `client.create_item` | `client.item.create` |
+| `client.duplicate_item` | `client.item.duplicate` |
+| `client.clear_item_updates` | `client.item.clear_updates` |
+| `client.move_item_to_group` | `client.item.move_to_group` |
+| `client.archive_item` | `client.item.archive` |
+| `client.delete_item` | `client.item.delete` |
+
+#### Group Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.groups` | `client.group.query` |
+| `client.create_group` | `client.group.create` |
+| `client.update_group` | `client.group.update` |
+| `client.duplicate_group` | `client.group.duplicate` |
+| `client.archive_group` | `client.group.archive` |
+| `client.delete_group` | `client.group.delete` |
+
+#### Column Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.columns` | `client.column.query` |
+| `client.create_column` | `client.column.create` |
+| `client.change_column_metadata` | `client.column.change_metadata` |
+| `client.change_column_title` | `client.column.change_title` |
+| `client.change_column_value` | `client.column.change_value` |
+| `client.change_multiple_column_values` | `client.column.change_multiple_values` |
+| `client.delete_column` | `client.column.delete` |
+
+#### Workspace Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.workspaces` | `client.workspace.query` |
+| `client.create_workspace` | `client.workspace.create` |
+| `client.update_workspace` | `client.workspace.update` |
+| `client.delete_workspace` | `client.workspace.delete` |
+
+#### Update Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.create_update` | `client.update.create` |
+| `client.like_update` | `client.update.like` |
+| `client.delete_update` | `client.update.delete` |
+
+#### Subitem Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.subitems` | `client.subitem.query` |
+| `client.create_subitem` | `client.subitem.create` |
+
+#### Board View Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.board_views` | `client.board_view.query` |
+
+#### Activity Log Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.activity_logs` | `client.activity_log.query` |
+
+#### Folder Resource
+
+| v0.x | v1.x |
+|------|------|
+| `client.folders` | `client.folder.query` |
+| `client.create_folder` | `client.folder.create` |
+| `client.update_folder` | `client.folder.update` |
+| `client.delete_folder` | `client.folder.delete` |
+
+## Migration Steps
+
+### Step 1: Update Your Gemfile
+
+```ruby
+# Gemfile
+gem 'monday_ruby', '~> 1.0'
+```
+
+Run `bundle update monday_ruby` to install the latest version.
+
+### Step 2: Update Resource Access Patterns
+
+Find all instances where you're calling client methods and update them to the new resource pattern.
+
+**Search Pattern**: Look for `client.` followed by resource method names like `boards`, `create_board`, `items`, etc.
+
+**Example Migration**:
+
+```ruby
+# Before (v0.x)
+client = Monday::Client.new(token: token)
+boards = client.boards(args: {ids: [123, 456]})
+new_board = client.create_board(args: {board_name: "My Board"})
+
+# After (v1.x)
+client = Monday::Client.new(token: token)
+boards = client.board.query(args: {ids: [123, 456]})
+new_board = client.board.create(args: {board_name: "My Board"})
+```
+
+### Step 3: Update Method Names
+
+Change all method calls to remove the resource prefix and use the resource object instead.
+
+```ruby
+# Before (v0.x)
+client.create_item(args: {board_id: 123, item_name: "Task"})
+client.update_board(args: {board_id: 456, board_name: "Updated"})
+client.delete_group(group_id: 789)
+
+# After (v1.x)
+client.item.create(args: {board_id: 123, item_name: "Task"})
+client.board.update(args: {board_id: 456, board_name: "Updated"})
+client.group.delete(group_id: 789)
+```
+
+### Step 4: Test Thoroughly
+
+After making changes:
+
+1. Run your test suite to ensure all API calls work correctly
+2. Test error handling to ensure exceptions are still caught properly
+3. Verify that response objects work as expected (they haven't changed)
+
+## Common Migration Scenarios
+
+### Scenario 1: Fetching and Creating Boards
+
+```ruby
+# Before (v0.x)
+client = Monday::Client.new(token: token)
+
+# Get all boards
+boards = client.boards
+boards.body.dig("data", "boards")
+
+# Create a new board
+new_board = client.create_board(
+  args: {
+    board_name: "Project Tracker",
+    board_kind: "public"
+  }
+)
+```
+
+```ruby
+# After (v1.x)
+client = Monday::Client.new(token: token)
+
+# Get all boards
+boards = client.board.query
+boards.body.dig("data", "boards")
+
+# Create a new board
+new_board = client.board.create(
+  args: {
+    board_name: "Project Tracker",
+    board_kind: "public"
+  }
+)
+```
+
+### Scenario 2: Working with Items
+
+```ruby
+# Before (v0.x)
+# Get items from a board
+items = client.items(args: {ids: [123, 456]})
+
+# Create a new item
+new_item = client.create_item(
+  args: {
+    board_id: 789,
+    item_name: "New Task",
+    column_values: {
+      status: {label: "Working on it"}
+    }
+  }
+)
+
+# Move item to a different group
+client.move_item_to_group(item_id: 123, group_id: "topics")
+```
+
+```ruby
+# After (v1.x)
+# Get items from a board
+items = client.item.query(args: {ids: [123, 456]})
+
+# Create a new item
+new_item = client.item.create(
+  args: {
+    board_id: 789,
+    item_name: "New Task",
+    column_values: {
+      status: {label: "Working on it"}
+    }
+  }
+)
+
+# Move item to a different group
+client.item.move_to_group(item_id: 123, group_id: "topics")
+```
+
+### Scenario 3: Column Value Updates
+
+```ruby
+# Before (v0.x)
+client.change_column_value(
+  board_id: 123,
+  item_id: 456,
+  column_id: "status",
+  value: {label: "Done"}
+)
+
+client.change_multiple_column_values(
+  board_id: 123,
+  item_id: 456,
+  column_values: {
+    status: {label: "Done"},
+    person: {personsAndTeams: [{id: 789, kind: "person"}]}
+  }
+)
+```
+
+```ruby
+# After (v1.x)
+client.column.change_value(
+  board_id: 123,
+  item_id: 456,
+  column_id: "status",
+  value: {label: "Done"}
+)
+
+client.column.change_multiple_values(
+  board_id: 123,
+  item_id: 456,
+  column_values: {
+    status: {label: "Done"},
+    person: {personsAndTeams: [{id: 789, kind: "person"}]}
+  }
+)
+```
+
+### Scenario 4: Workspace Management
+
+```ruby
+# Before (v0.x)
+workspaces = client.workspaces
+new_workspace = client.create_workspace(args: {name: "Engineering"})
+client.update_workspace(workspace_id: 123, args: {name: "Product"})
+client.delete_workspace(workspace_id: 456)
+```
+
+```ruby
+# After (v1.x)
+workspaces = client.workspace.query
+new_workspace = client.workspace.create(args: {name: "Engineering"})
+client.workspace.update(workspace_id: 123, args: {name: "Product"})
+client.workspace.delete(workspace_id: 456)
+```
+
+## What Stayed the Same
+
+Several aspects of the library remain unchanged to minimize disruption:
+
+### 1. Configuration
+
+Configuration works exactly the same way in both versions:
+
+```ruby
+# Global configuration (unchanged)
+Monday.configure do |config|
+  config.token = "your_token"
+  config.version = "2023-07"
+end
+
+# Client-specific configuration (unchanged)
+client = Monday::Client.new(token: "your_token", version: "2023-07")
+```
+
+### 2. Response Objects
+
+Response objects have the same interface:
+
+```ruby
+response = client.board.query
+
+response.success?  # Same as before
+response.body      # Same as before
+response.status    # Same as before
+```
+
+### 3. Error Handling
+
+Error handling remains identical:
+
+```ruby
+begin
+  client.board.create(args: {board_name: "Test"})
+rescue Monday::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue Monday::Error => e
+  puts "API error: #{e.message}"
+end
+```
+
+### 4. Method Arguments
+
+The `args` and `select` parameters work the same way:
+
+```ruby
+# Still uses args and select parameters
+client.board.query(
+  args: {ids: [123, 456]},
+  select: ["id", "name", "description"]
+)
+```
+
+## Common Migration Pitfalls
+
+### Pitfall 1: Forgetting the Resource Object
+
+**Problem**: Calling methods directly on the client
+
+```ruby
+# This will fail in v1.x
+client.boards  # NoMethodError: undefined method `boards'
+```
+
+**Solution**: Access through the resource object
+
+```ruby
+# Correct approach
+client.board.query
+```
+
+### Pitfall 2: Using Old Method Names
+
+**Problem**: Using the full method name with resource prefix
+
+```ruby
+# This will fail in v1.x
+client.board.create_board  # NoMethodError
+```
+
+**Solution**: Use the simplified method name
+
+```ruby
+# Correct approach
+client.board.create
+```
+
+### Pitfall 3: Inconsistent Resource Names
+
+**Problem**: Using plural resource names
+
+```ruby
+# This will fail in v1.x
+client.boards.query  # NoMethodError: undefined method `boards'
+```
+
+**Solution**: All resources are singular
+
+```ruby
+# Correct approach
+client.board.query
+client.item.query
+client.group.query
+```
+
+### Pitfall 4: Assuming Response Format Changed
+
+**Problem**: Trying to access response differently
+
+```ruby
+# This still works the same way
+response = client.board.query
+boards = response.body.dig("data", "boards")  # Unchanged
+```
+
+**Solution**: Response objects work exactly the same as before
+
+## New Features in v1.x
+
+### v1.0.0 Features
+
+#### Enum Support
+
+Version 1.0.0 adds support for GraphQL enums, allowing you to use enum values in your queries:
+
+```ruby
+# Use enums in your queries
+client.board.create(
+  args: {
+    board_name: "My Board",
+    board_kind: :public  # Can use symbols for enums
+  }
+)
+```
+
+#### Better Code Organization
+
+The new architecture makes it easier to:
+
+- Understand which methods belong to which resource
+- Add new resources without affecting existing code
+- Test individual resources in isolation
+- Navigate the codebase
+
+### v1.1.0 Features
+
+If you're migrating directly to v1.1.0, you also get these new features:
+
+#### Cursor-Based Pagination
+
+Efficiently retrieve large numbers of items using cursor-based pagination:
+
+```ruby
+# Fetch items with pagination (up to 500 items per page)
+response = client.board.items_page(
+  board_ids: 123,
+  limit: 100
+)
+
+items = response.body.dig("data", "boards", 0, "items_page", "items")
+cursor = response.body.dig("data", "boards", 0, "items_page", "cursor")
+
+# Fetch next page
+if cursor
+  next_response = client.board.items_page(
+    board_ids: 123,
+    limit: 100,
+    cursor: cursor
+  )
+end
+```
+
+#### Configurable Timeouts
+
+Configure connection and read timeouts for API requests:
+
+```ruby
+Monday.configure do |config|
+  config.token = "your_token"
+  config.open_timeout = 10  # seconds (default: 10)
+  config.read_timeout = 30  # seconds (default: 30)
+end
+
+# Or per client
+client = Monday::Client.new(
+  token: "your_token",
+  open_timeout: 15,
+  read_timeout: 45
+)
+```
+
+#### Deprecation Warning System
+
+The library now includes a deprecation warning system to help you stay informed about upcoming changes:
+
+```ruby
+# If you use a deprecated method, you'll see a warning:
+client.board.delete_subscribers(...)
+# [DEPRECATION] `delete_subscribers` is deprecated and will be removed in v2.0.0.
+# Use `client.user.delete_from_board` instead.
+```
+
+## Benefits of Upgrading
+
+### 1. Future-Proof Code
+
+The v1.x architecture is designed to support new monday.com API features with minimal breaking changes. Features like pagination, filtering, and webhooks integrate naturally into the resource pattern.
+
+### 2. Better Developer Experience
+
+- **Auto-completion**: IDEs can better suggest methods when they're organized by resource
+- **Documentation**: Each resource class has clear documentation of its methods
+- **Consistency**: Predictable naming makes it easier to guess the correct method name
+
+### 3. Improved Maintainability
+
+- **Isolated Resources**: Changes to one resource don't affect others
+- **Easier Testing**: Resources can be tested independently
+- **Clear Responsibilities**: Each class has a single, well-defined purpose
+
+### 4. Ruby Best Practices
+
+The new architecture follows Ruby community standards and patterns, making the library more familiar to Ruby developers.
+
+## Timeline and Support
+
+### Version Support Policy
+
+- **v0.x**: No longer actively maintained (security fixes only)
+- **v1.x**: Current stable version, receives new features and bug fixes
+- **v2.x**: Planned for future, will include removal of deprecated methods
+
+### Migration Timeframe
+
+We recommend upgrading to v1.x as soon as possible:
+
+- **Immediate**: Update applications under active development
+- **Within 3 months**: Update production applications
+- **Within 6 months**: Update all applications (before v2.0.0 deprecations)
+
+### Deprecation Timeline
+
+Methods deprecated in v1.1.0 will be removed in v2.0.0:
+
+- `client.board.delete_subscribers` - Use `client.user.delete_from_board` instead
+- `client.column.column_values` - Use `client.item.query` with `column_values` select instead
+
+## Getting Help
+
+### Resources
+
+- **Documentation**: Check the [Wiki](https://github.com/sanifhimani/monday_ruby/wiki) for detailed API documentation
+- **Changelog**: See [CHANGELOG.md](https://github.com/sanifhimani/monday_ruby/blob/main/CHANGELOG.md) for all changes
+- **Examples**: Browse the [examples directory](https://github.com/sanifhimani/monday_ruby/tree/main/examples) (if available)
+
+### Support Channels
+
+- **Issues**: Report bugs or ask questions on [GitHub Issues](https://github.com/sanifhimani/monday_ruby/issues)
+- **Discussions**: Join conversations on [GitHub Discussions](https://github.com/sanifhimani/monday_ruby/discussions)
+- **Contributing**: See [CONTRIBUTING.md](https://github.com/sanifhimani/monday_ruby/blob/main/CONTRIBUTING.md) for contribution guidelines
+
+### Common Questions
+
+**Q: Do I need to change my error handling?**
+A: No, error handling remains exactly the same.
+
+**Q: Will my existing response parsing code work?**
+A: Yes, response objects have the same interface.
+
+**Q: Can I upgrade incrementally?**
+A: No, the v1.0.0 changes are comprehensive. We recommend upgrading all client calls at once.
+
+**Q: How long will v0.x be supported?**
+A: v0.x will receive security fixes only. We recommend migrating to v1.x as soon as possible.
+
+**Q: Are there any performance differences?**
+A: The architectural changes have minimal performance impact. Response times are virtually identical.
+
+**Q: What if I find a bug during migration?**
+A: Please report it on [GitHub Issues](https://github.com/sanifhimani/monday_ruby/issues). We'll prioritize migration-related bugs.
+
+## Automated Migration Tools
+
+While we don't provide an automated migration script, you can use these search-and-replace patterns to help with the migration:
+
+### Using Regex Find and Replace
+
+**Pattern 1**: Board methods
+```
+Find:    client\.boards\(
+Replace: client.board.query(
+
+Find:    client\.create_board\(
+Replace: client.board.create(
+
+Find:    client\.update_board\(
+Replace: client.board.update(
+
+Find:    client\.delete_board\(
+Replace: client.board.delete(
+
+Find:    client\.archive_board\(
+Replace: client.board.archive(
+
+Find:    client\.duplicate_board\(
+Replace: client.board.duplicate(
+```
+
+**Pattern 2**: Item methods
+```
+Find:    client\.items\(
+Replace: client.item.query(
+
+Find:    client\.create_item\(
+Replace: client.item.create(
+
+Find:    client\.move_item_to_group\(
+Replace: client.item.move_to_group(
+
+Find:    client\.clear_item_updates\(
+Replace: client.item.clear_updates(
+```
+
+**Pattern 3**: Other resources
+```
+Find:    client\.account\(
+Replace: client.account.query(
+
+Find:    client\.workspaces\(
+Replace: client.workspace.query(
+
+Find:    client\.create_workspace\(
+Replace: client.workspace.create(
+```
+
+**Important**: Always review changes manually and test thoroughly after using automated find-and-replace.
+
+## Example: Complete Before and After
+
+Here's a complete example showing a typical workflow in both versions:
+
+### Before (v0.x)
+
+```ruby
+require 'monday_ruby'
+
+# Initialize client
+client = Monday::Client.new(token: ENV['MONDAY_TOKEN'])
+
+# Get account info
+account = client.account
+puts "Account: #{account.body.dig('data', 'users', 0, 'account', 'name')}"
+
+# Get all boards
+boards = client.boards(args: {limit: 10})
+board_id = boards.body.dig('data', 'boards', 0, 'id')
+
+# Create a new item
+new_item = client.create_item(
+  args: {
+    board_id: board_id,
+    item_name: "New Task",
+    column_values: {
+      status: {label: "Working on it"},
+      date: {date: "2024-12-31"}
+    }
+  }
+)
+
+item_id = new_item.body.dig('data', 'create_item', 'id')
+
+# Update a column value
+client.change_column_value(
+  board_id: board_id,
+  item_id: item_id,
+  column_id: "status",
+  value: {label: "Done"}
+)
+
+# Create an update
+client.create_update(
+  item_id: item_id,
+  args: {body: "Task completed successfully!"}
+)
+
+# Archive the item
+client.archive_item(item_id: item_id)
+```
+
+### After (v1.x)
+
+```ruby
+require 'monday_ruby'
+
+# Initialize client (unchanged)
+client = Monday::Client.new(token: ENV['MONDAY_TOKEN'])
+
+# Get account info
+account = client.account.query
+puts "Account: #{account.body.dig('data', 'users', 0, 'account', 'name')}"
+
+# Get all boards
+boards = client.board.query(args: {limit: 10})
+board_id = boards.body.dig('data', 'boards', 0, 'id')
+
+# Create a new item
+new_item = client.item.create(
+  args: {
+    board_id: board_id,
+    item_name: "New Task",
+    column_values: {
+      status: {label: "Working on it"},
+      date: {date: "2024-12-31"}
+    }
+  }
+)
+
+item_id = new_item.body.dig('data', 'create_item', 'id')
+
+# Update a column value
+client.column.change_value(
+  board_id: board_id,
+  item_id: item_id,
+  column_id: "status",
+  value: {label: "Done"}
+)
+
+# Create an update
+client.update.create(
+  item_id: item_id,
+  args: {body: "Task completed successfully!"}
+)
+
+# Archive the item
+client.item.archive(item_id: item_id)
+```
+
+## Conclusion
+
+The migration from v0.x to v1.x requires updating how you access resources and method names, but the benefits far outweigh the effort. The new architecture provides:
+
+- Better code organization
+- More consistent API design
+- Easier maintenance and testing
+- Foundation for future features
+- Improved developer experience
+
+Take your time with the migration, test thoroughly, and don't hesitate to reach out for help if you encounter issues. Welcome to monday_ruby v1.x!