monday_ruby 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8164389fc7acb67d40bee3bf79a9768e1256833268e5ef8002c6d9392a5b75
-  data.tar.gz: 29165f3538b8658267944fd2ea91f2bbdf11c916c7967e17cfe55e27397959c3
+  metadata.gz: 65df3dcbdada1d02fb3573b444015cb6b566d6b77cc1d63d103d6b5e7803f65b
+  data.tar.gz: 319fd612684e644dc0235c0010ece6890214f844d5b48f3f9238319ff77e70c5
 SHA512:
-  metadata.gz: f21b44ba54e5c14513cd7f39b6709126fe1a5e54a00468da76fc2275230d9a01e7cf4844ae5035bf8777dacd8153ee7571a8a53a3491b6bf4366b47ea324d6ce
-  data.tar.gz: bbaee28c405107767469f7a9386c7d2b991b4e877ccc3b476a360837ca25bb776aee2d05579ef4aa641b74b747cafe2fb73dc72836dd6b8264f61d4982b36729
+  metadata.gz: bc4f34d8de144d95b4fe9cc78ea9801614389c4be7aaf72ba29186d6447d14200c95a3814ed5d8a3106045142b81f10b38fe7045ca8fcb5549153acf59b63c95
+  data.tar.gz: e5c15771ea6c5ec86e2b12508860c1927d67017b223b40c51b921ee28912a691aaa2750f39ef08ec6d9efec091a5d3fdaf07393e920e8b907b34659d72372a4a

data/.env

@@ -1 +1 @@
-token="eyJhbGciOiJIUzI1NiJ9.eyJ0aWQiOjM4MTE3NTY1MywiYWFpIjoxMSwidWlkIjo2MzEzMDMxMiwiaWFkIjoiMjAyNC0wNy0wN1QxMzo0OTo0Mi4wMzJaIiwicGVyIjoibWU6d3JpdGUiLCJhY3RpZCI6MjQzMDgwODMsInJnbiI6InVzZTEifQ.AKgwPueXJkzm9d0I9y4DzSKBwJ3Vi3t8IsOc2hpyDtk"
+token="[REPLACE_TOKEN]"

data/.rspec

@@ -1,3 +1,2 @@
---format documentation
 --color
 --require spec_helper

data/.rubocop.yml

@@ -1,6 +1,14 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
 AllCops:
   TargetRubyVersion: 2.7
   NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "spec/support/**/*.rb"
+    - "vendor/**/*"
 
 Style/StringLiterals:
   Enabled: true
@@ -19,4 +27,15 @@ Metrics/BlockLength:
 
 Metrics/MethodLength:
   Exclude:
+    - "lib/monday/configuration.rb"
     - "lib/monday/util.rb"
+
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/monday/resources/group.rb"
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 11

data/.simplecov

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
+SimpleCov.add_filter "/spec/support/"
 SimpleCov.minimum_coverage 97

data/CHANGELOG.md

@@ -1,3 +1,52 @@
+## v1.2.0 (November 18, 2025)
+
+#### Added
+
+- Added support for adding Files (Assets) to a File column.
+- Added support for adding Files (Assets) to an Update (Comments).
+- Added helper method for clearing a Files column.
+
+#### Changed
+
+- Updated gemspec dependency to use multipart-post (~> 2.4.0)
+- Updated rubocop RSpec/MultipleMemoizedHelpers from 10 to 11.
+- Updated Utils to allow GraphQL variables in queries.
+
+## v1.1.0 (October 27, 2025)
+
+### Added
+
+- **Cursor-based pagination for items**:
+  - Added `items_page` method to `Board` resource for paginated item retrieval
+  - Added `items_page` method to `Group` resource for paginated group items
+  - Added `items_page` method to `Item` resource for paginated item queries
+  - Support for cursor-based pagination with customizable limits (up to 500 items per page)
+  - Support for filtered queries using `query_params` with rules and operators
+
+- **Deprecation warning system**:
+  - Added `Deprecation` module for issuing deprecation warnings
+  - Marked `delete_subscribers` method for deprecation in v2.0.0
+  - Provides clear migration paths for deprecated methods
+
+- **Configurable request timeouts**:
+  - Added `open_timeout` configuration option (default: 10 seconds)
+  - Added `read_timeout` configuration option (default: 30 seconds)
+  - Configurable at both global and client instance levels
+
+- **Documentation improvements**:
+  - Added CONTRIBUTING.md with development guidelines
+  - Added VCR testing guide in pull request template
+
+### Changed
+
+- Updated Ruby version support matrix in CI (added Ruby 3.3 and 3.4)
+- Updated base64 gem dependency to ~> 0.3.0
+- Improved RuboCop configuration and fixed linting issues
+
+### Fixed
+
+- CI workflow improvements and linting configurations
+
 ## v1.0.0 (July 30, 2024)
 
 ### Changed

data/CONTRIBUTING.md

@@ -16,6 +16,171 @@ Please follow these steps to have your contribution considered:
 2. Follow the [commit guidelines](#commit-message-guidelines).
 3. After you submit your pull request, verify that all the status checks are passing.
 
+## Testing Guidelines
+
+This project uses [VCR](https://github.com/vcr/vcr) to record HTTP interactions for tests. This means you **do not need a Monday.com API token** to run most tests or contribute to the project.
+
+### Running Tests
+
+To run the test suite:
+
+```bash
+bundle exec rake spec
+```
+
+All tests will use pre-recorded VCR cassettes stored in `spec/fixtures/vcr_cassettes/`.
+
+### Working with VCR Cassettes
+
+**For most contributions, you won't need to modify VCR cassettes.** The existing cassettes cover the current API functionality.
+
+#### When You Need to Record New Cassettes
+
+You only need to record new VCR cassettes when:
+- Adding support for a **new API endpoint** that doesn't have existing test coverage
+- Modifying an existing API call that changes the request/response structure
+
+To record new cassettes:
+
+1. Set your Monday.com API token as an environment variable:
+   ```bash
+   export MONDAY_TOKEN="your_token_here"
+   ```
+
+2. Delete the old cassette file (if updating an existing test):
+   ```bash
+   rm spec/fixtures/vcr_cassettes/your_cassette_name.yml
+   ```
+
+3. Run the specific test to generate a new cassette:
+   ```bash
+   bundle exec rspec spec/path/to/your_spec.rb
+   ```
+
+4. **Important:** Before committing, verify the cassette doesn't contain sensitive data:
+   - VCR automatically filters the `Authorization` header
+   - Check for any other sensitive information in the cassette file
+   - Cassettes are committed to the repository
+
+#### Testing New Features Without API Access
+
+If you're adding a new feature but don't have API access to record cassettes:
+1. Write your implementation and tests
+2. Create a pull request noting that cassettes need to be recorded
+3. A maintainer with API access will record the cassettes for you
+
+### Code Quality
+
+Run RuboCop to ensure code style compliance:
+
+```bash
+bundle exec rake rubocop
+```
+
+## Documentation
+
+The project uses [VitePress](https://vitepress.dev/) to generate documentation from Markdown files. The documentation site is hosted at [https://sanifhimani.github.io/monday_ruby/](https://sanifhimani.github.io/monday_ruby/).
+
+### When to Update Documentation
+
+Update documentation when you:
+- Add a new resource or method to the public API
+- Change the behavior of existing methods
+- Add new features or configuration options
+- Fix bugs that affect documented behavior
+
+### Documentation Structure
+
+Documentation follows the [Diataxis framework](https://diataxis.fr):
+
+- **Tutorial** (`docs/tutorial/`) - Learning-oriented, gets users started
+- **How-to Guides** (`docs/guides/`) - Task-oriented, solves specific problems
+- **Reference** (`docs/reference/`) - Information-oriented, describes the API
+- **Explanation** (`docs/explanation/`) - Understanding-oriented, explains concepts
+
+### Adding/Updating Documentation
+
+Documentation files are located in the `docs/` directory:
+
+```
+docs/
+├── .vitepress/
+│   └── config.mjs          # Navigation and site configuration
+├── guides/                 # How-to guides
+│   ├── boards/
+│   ├── items/
+│   ├── columns/
+│   └── advanced/
+├── reference/              # API reference
+│   ├── resources/
+│   └── client.md
+├── explanation/            # Conceptual documentation
+└── tutorial/               # Getting started tutorial
+```
+
+#### Steps to Update Documentation:
+
+1. **Find or create the appropriate file** based on what you're documenting
+2. **Follow the existing format** - look at similar documentation files for examples
+3. **Test your code examples** - all examples should be runnable and accurate
+4. **Update navigation** if adding new pages - edit `docs/.vitepress/config.mjs`
+5. **Build locally** to preview changes:
+
+```bash
+cd docs
+npm install  # First time only
+npm run dev  # Start local dev server
+```
+
+Visit `http://localhost:5173/monday_ruby/` to preview your changes.
+
+6. **Check for broken links** before submitting:
+
+```bash
+cd docs
+npm run build  # Build will fail if there are dead links
+```
+
+#### Documentation Guidelines:
+
+- **Code examples must be accurate** - verify against VCR test fixtures or real API
+- **Include practical examples** - show real-world usage, not just syntax
+- **Be consistent** - follow the style and tone of existing documentation
+- **No emojis** - maintain professional tone in documentation
+- **Link related pages** - help users discover relevant documentation
+- **Keep examples self-contained** - users should be able to copy-paste and run
+
+#### Example Documentation Pattern:
+
+```markdown
+# Resource Name
+
+Brief description of what this resource does.
+
+## Methods
+
+### method_name
+
+Description of what the method does.
+
+\`\`\`ruby
+# Example code that actually works
+client = Monday::Client.new(token: ENV["MONDAY_TOKEN"])
+response = client.resource.method_name(args: {})
+\`\`\`
+
+**Parameters:**
+- List parameters and their types
+
+**Returns:** Description of return value
+
+**See:** Link to monday.com API docs
+```
+
+### Deploying Documentation
+
+Documentation is automatically deployed via GitHub Actions when changes are merged to the `main` branch. You don't need to manually deploy.
+
 ## Commit message guidelines
 
 * Use present tense ("Add feature" not "Added feature")

data/README.md

@@ -1,165 +1,244 @@
-# Monday API Library for Ruby
+# monday_ruby
 
 ![Build Status](https://github.com/sanifhimani/monday_ruby/actions/workflows/ci.yml/badge.svg)
 [![Gem Version](https://badge.fury.io/rb/monday_ruby.svg)](https://badge.fury.io/rb/monday_ruby)
 [![Coverage Status](https://coveralls.io/repos/github/sanifhimani/monday_ruby/badge.svg?branch=main)](https://coveralls.io/github/sanifhimani/monday_ruby?branch=main)
 
-This library provides convenient access to the monday.com API from the application written in Ruby.
+A Ruby client library for the [monday.com GraphQL API](https://developer.monday.com/api-reference). Build integrations with boards, items, columns, and more using idiomatic Ruby.
 
-The library provides:
+## Features
 
-1. A pre-defined set of methods to easily interact with the API resources.
-2. Easy configuration path for fast setup and use.
-3. Easy error handling.
+- **Resource-based API** - Clean, intuitive interface (`client.board.query`, `client.item.create`)
+- **Flexible configuration** - Global or per-client setup
+- **Comprehensive error handling** - Typed exceptions for different error scenarios
+- **Cursor-based pagination** - Efficiently handle large datasets
+- **Fully tested** - 100% test coverage with VCR-recorded fixtures
 
-**Check out the [Wiki](https://github.com/sanifhimani/monday_ruby/wiki) for detailed documentation on how to use the library.**
+## Documentation
 
-## Installation
+**[Complete Documentation →](https://sanifhimani.github.io/monday_ruby/)**
 
-```bash
-gem install monday_ruby
-```
+- [Getting Started Tutorial](https://sanifhimani.github.io/monday_ruby/tutorial/first-integration)
+- [How-to Guides](https://sanifhimani.github.io/monday_ruby/guides/installation)
+- [API Reference](https://sanifhimani.github.io/monday_ruby/reference/client)
+- [Best Practices](https://sanifhimani.github.io/monday_ruby/explanation/best-practices/errors)
 
-## Usage
+## Installation
 
-***Complete list of resources along with examples are provided in the [Wiki](https://github.com/sanifhimani/monday_ruby/wiki).***
+Add to your Gemfile:
 
-The library needs to be configured with your account's authentication token which is available on the Admin tab on monday.com. Elaborate documentation can be found [here](https://developer.monday.com/api-reference/docs/authentication).
+```ruby
+gem "monday_ruby"
+```
 
-### Configuration
+Or install directly:
 
-Once you have the authentication token, you can either globally configure the library or you can configure a specific client.
+```bash
+gem install monday_ruby
+```
 
-#### Global config
+## Quick Start
 
 ```ruby
 require "monday_ruby"
 
+# Configure with your API token
 Monday.configure do |config|
-  config.token = "<AUTH_TOKEN>"
+  config.token = ENV["MONDAY_TOKEN"]
 end
-```
 
-#### Client specific config
-```ruby
-require "monday_ruby"
+# Create a client
+client = Monday::Client.new
+
+# Query boards
+response = client.board.query(args: { limit: 5 })
 
-client = Monday::Client.new(token: "<AUTH_TOKEN>")
+if response.success?
+  boards = response.body.dig("data", "boards")
+  boards.each { |board| puts board["name"] }
+end
 ```
 
-The version configuration field allows you to optionally pass in the version of the API you want to use. By default, the latest stable version is used.
+Get your API token from your [monday.com Admin settings](https://support.monday.com/hc/en-us/articles/360005144659-Does-monday-com-have-an-API).
 
-```ruby
-require "monday_ruby"
+## Usage
 
+### Configuration
+
+**Global configuration** (recommended):
+
+```ruby
 Monday.configure do |config|
-  config.token = "<AUTH_TOKEN>"
-  config.version = "2023-07"
+  config.token = ENV["MONDAY_TOKEN"]
+  config.version = "2024-01"  # API version (optional)
 end
-```
 
-### Accessing a response object
+client = Monday::Client.new
+```
 
-Get access to response objects by initializing a client and using the appropriate action you want to perform:
+**Per-client configuration**:
 
 ```ruby
-client = Monday::Client.new(token: "<AUTH_TOKEN>")
-response = client.boards
+client = Monday::Client.new(
+  token: ENV["MONDAY_TOKEN"],
+  version: "2024-01"
+)
+```
 
-puts response.success?
-puts response.body
+**Configure timeouts**:
+
+```ruby
+Monday.configure do |config|
+  config.token = ENV["MONDAY_TOKEN"]
+  config.open_timeout = 10  # seconds (default: 10)
+  config.read_timeout = 30  # seconds (default: 30)
+end
 ```
 
-### Use cases
+### Working with Boards
 
-Here are some common use cases for the API client.
+```ruby
+# Query boards
+response = client.board.query(
+  args: { ids: [1234567890] },
+  select: ["id", "name", "description"]
+)
+
+boards = response.body.dig("data", "boards")
+
+# Create a board
+response = client.board.create(
+  args: {
+    board_name: "Project Tasks",
+    board_kind: "public",
+    description: "Track project deliverables"
+  }
+)
 
-#### Fetching all the boards
+board = response.body.dig("data", "create_board")
+```
 
-Initialize the client with the auth token and call the `boards` method.
+### Working with Items
 
 ```ruby
-client = Monday::Client.new(token: <AUTH_TOKEN>)
-
-response = client.boards # => <Monday::Response ...>
+# Create an item
+response = client.item.create(
+  args: {
+    board_id: 1234567890,
+    item_name: "Implement authentication",
+    column_values: {
+      status: { label: "Working on it" },
+      date4: { date: "2024-12-31" }
+    }
+  }
+)
 
-# To check if the request was successful
-response.success? # => true
+# Query items
+response = client.item.query(
+  args: { ids: [987654321] },
+  select: ["id", "name", { column_values: ["id", "text"] }]
+)
 
-# To get the boards from the response
-response.dig("data", "boards") # => [...]
+items = response.body.dig("data", "items")
 ```
 
-#### Creating a new board
+### Pagination
 
-Initialize the client with the auth token and call the `create_board` method.
+Handle large datasets efficiently with cursor-based pagination:
 
 ```ruby
-client = Monday::Client.new(token: <AUTH_TOKEN>)
+# Fetch first page
+response = client.board.items_page(
+  board_ids: 1234567890,
+  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: 1234567890,
+    limit: 100,
+    cursor: cursor
+  )
+end
+```
 
-args = {
-  board_name: "Test board",
-  board_kind: "public",
-  description: "Test board description"
-}
+See the [Pagination Guide](https://sanifhimani.github.io/monday_ruby/guides/advanced/pagination) for more details.
 
-# => <Monday::Response ...>
-response = client.create_board(args: args)
+### Error Handling
 
-# To check if the request was successful
-response.success? # => true
+The library provides typed exceptions for different error scenarios:
 
-# To get the created board from the response
-response.dig("data", "create_board") # => { ... }
+```ruby
+begin
+  response = client.board.query(args: { ids: [123] })
+rescue Monday::AuthorizationError => e
+  puts "Invalid API token: #{e.message}"
+rescue Monday::InvalidRequestError => e
+  puts "Invalid request: #{e.message}"
+rescue Monday::RateLimitError => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue Monday::Error => e
+  puts "API error: #{e.message}"
+end
 ```
 
-#### Creating a new item on board
+See the [Error Handling Guide](https://sanifhimani.github.io/monday_ruby/guides/advanced/errors) for best practices.
 
-Initialize the client with the auth token and call the `create_item` method.
+## Available Resources
 
-```ruby
-client = Monday::Client.new(token: <AUTH_TOKEN>)
-
-args = {
-  board_id: <BOARD_ID>,
-  item_name: "New item",
-  column_values: {
-    status: {
-      label: "Working on it"
-    },
-    keywords: {
-      labels: ["Tech team", "DevOps team"]
-    }
-  }
-}
+The client provides access to all monday.com resources:
 
-# => <Monday::Response ...>
-response = client.create_item(args: args)
+- **Boards** - `client.board`
+- **Items** - `client.item`
+- **Columns** - `client.column`
+- **Files** - `client.file`
+- **Groups** - `client.group`
+- **Updates** - `client.update`
+- **Subitems** - `client.subitem`
+- **Workspaces** - `client.workspace`
+- **Folders** - `client.folder`
+- **Account** - `client.account`
+- **Activity Logs** - `client.activity_log`
+- **Board Views** - `client.board_view`
 
-# To check if the request was successful
-response.success? # => true
-
-# To get the created item from the response
-response.dig("data", "create_item") # => { ... }
-```
+For complete API documentation, see the [API Reference](https://sanifhimani.github.io/monday_ruby/reference/client).
 
 ## Development
 
-Run all tests:
+### Running Tests
 
 ```bash
 bundle exec rake spec
 ```
 
-Run linter:
+Tests use [VCR](https://github.com/vcr/vcr) to record HTTP interactions, so you don't need a monday.com API token to run them.
+
+### Linting
 
 ```bash
 bundle exec rake rubocop
 ```
 
+### All Checks
+
+```bash
+bundle exec rake  # Runs both tests and linter
+```
+
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/sanifhimani/monday_ruby). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sanifhimani/monday_ruby/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/sanifhimani/monday_ruby).
+
+Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
+- Development setup and testing
+- Documentation guidelines
+- Code style and commit conventions
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License