monday_ruby 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fca12fa6b3f49d85bea9353e7621904cbe773f69fc9b4b18afc641a7c25318a0
-  data.tar.gz: 738fa89ae3732c0bf6afe22c314d7dcc42bae2990bfc313e640ce8aee7183755
+  metadata.gz: 65df3dcbdada1d02fb3573b444015cb6b566d6b77cc1d63d103d6b5e7803f65b
+  data.tar.gz: 319fd612684e644dc0235c0010ece6890214f844d5b48f3f9238319ff77e70c5
 SHA512:
-  metadata.gz: 843ba4a79d3a53b75b8ddfc8eb545d442600fe3b5b90df4f01ced08dd1516c8e9aab4755180b094d7c8fa94a2c330497dbee0b86ecc04071101deb0e236d2d6c
-  data.tar.gz: e6a6b8a7c1b912aee79a55f3da44372cf4d35eed207c7e061f131e6385ed9c48475c87c5722162dbdbf259058eaf13f7acf0e990a765dbc3b33299662120d8ef
+  metadata.gz: bc4f34d8de144d95b4fe9cc78ea9801614389c4be7aaf72ba29186d6447d14200c95a3814ed5d8a3106045142b81f10b38fe7045ca8fcb5549153acf59b63c95
+  data.tar.gz: e5c15771ea6c5ec86e2b12508860c1927d67017b223b40c51b921ee28912a691aaa2750f39ef08ec6d9efec091a5d3fdaf07393e920e8b907b34659d72372a4a

data/.env

@@ -1 +1 @@
-token="eyJhbGciOiJIUzI1NiJ9.eyJ0aWQiOjU3ODczMzkyMiwiYWFpIjoxMSwidWlkIjo5NDg5NDgxMywiaWFkIjoiMjAyNS0xMC0yN1QwMToyMToxMy44NDFaIiwicGVyIjoibWU6d3JpdGUiLCJhY3RpZCI6MzIxODc3OTQsInJnbiI6InVzZTEifQ.SgPS-m2FEMHjitKC0SYTYsiQ8vAHZ7ynjDmMwQInneE"
+token="[REPLACE_TOKEN]"

data/.rubocop.yml

@@ -27,6 +27,7 @@ Metrics/BlockLength:
 
 Metrics/MethodLength:
   Exclude:
+    - "lib/monday/configuration.rb"
     - "lib/monday/util.rb"
 
 Metrics/ParameterLists:
@@ -37,4 +38,4 @@ RSpec/NestedGroups:
   Max: 5
 
 RSpec/MultipleMemoizedHelpers:
-  Max: 10
+  Max: 11

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 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

data/CONTRIBUTING.md

@@ -77,6 +77,110 @@ Run RuboCop to ensure code style compliance:
 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,240 +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
 
-client = Monday::Client.new(token: "<AUTH_TOKEN>")
+# Query boards
+response = client.board.query(args: { limit: 5 })
+
+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
 
-Monday.configure do |config|
-  config.token = "<AUTH_TOKEN>"
-  config.version = "2023-07"
-end
-```
+### Configuration
 
-You can also configure request timeouts (new in v1.1.0):
+**Global configuration** (recommended):
 
 ```ruby
-require "monday_ruby"
-
 Monday.configure do |config|
-  config.token = "<AUTH_TOKEN>"
-  config.open_timeout = 10  # seconds (default: 10)
-  config.read_timeout = 30  # seconds (default: 30)
+  config.token = ENV["MONDAY_TOKEN"]
+  config.version = "2024-01"  # API version (optional)
 end
 
-# Or configure per client
-client = Monday::Client.new(
-  token: "<AUTH_TOKEN>",
-  open_timeout: 15,
-  read_timeout: 45
-)
+client = Monday::Client.new
 ```
 
-### Accessing a response object
-
-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
-
-puts response.success?
-puts response.body
+client = Monday::Client.new(
+  token: ENV["MONDAY_TOKEN"],
+  version: "2024-01"
+)
 ```
 
-### Use cases
-
-Here are some common use cases for the API client.
-
-#### Fetching all the boards
-
-Initialize the client with the auth token and call the `boards` method.
+**Configure timeouts**:
 
 ```ruby
-client = Monday::Client.new(token: <AUTH_TOKEN>)
-
-response = client.boards # => <Monday::Response ...>
-
-# To check if the request was successful
-response.success? # => true
-
-# To get the boards from the response
-response.body.dig("data", "boards") # => [...]
+Monday.configure do |config|
+  config.token = ENV["MONDAY_TOKEN"]
+  config.open_timeout = 10  # seconds (default: 10)
+  config.read_timeout = 30  # seconds (default: 30)
+end
 ```
 
-#### Creating a new board
-
-Initialize the client with the auth token and call the `create_board` method.
+### Working with Boards
 
 ```ruby
-client = Monday::Client.new(token: <AUTH_TOKEN>)
-
-args = {
-  board_name: "Test board",
-  board_kind: "public",
-  description: "Test board description"
-}
+# Query boards
+response = client.board.query(
+  args: { ids: [1234567890] },
+  select: ["id", "name", "description"]
+)
 
-# => <Monday::Response ...>
-response = client.create_board(args: args)
+boards = response.body.dig("data", "boards")
 
-# To check if the request was successful
-response.success? # => true
+# Create a board
+response = client.board.create(
+  args: {
+    board_name: "Project Tasks",
+    board_kind: "public",
+    description: "Track project deliverables"
+  }
+)
 
-# To get the created board from the response
-response.body.dig("data", "create_board") # => { ... }
+board = response.body.dig("data", "create_board")
 ```
 
-#### Creating a new item on board
-
-Initialize the client with the auth token and call the `create_item` method.
+### Working with Items
 
 ```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"]
+# 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" }
     }
   }
-}
-
-# => <Monday::Response ...>
-response = client.create_item(args: args)
+)
 
-# 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 created item from the response
-response.body.dig("data", "create_item") # => { ... }
+items = response.body.dig("data", "items")
 ```
 
-#### Fetching items with pagination (New in v1.1.0)
+### Pagination
 
-The library now supports efficient cursor-based pagination for retrieving large numbers of items. This is the recommended approach for working with boards, groups, or items that contain many records.
+Handle large datasets efficiently with cursor-based pagination:
 
 ```ruby
-client = Monday::Client.new(token: <AUTH_TOKEN>)
-
-# Fetch first page of items from a board (up to 500 items per page)
+# Fetch first page
 response = client.board.items_page(
-  board_ids: <BOARD_ID>,
+  board_ids: 1234567890,
   limit: 100
 )
 
-# Extract items and cursor from response
 items = response.body.dig("data", "boards", 0, "items_page", "items")
 cursor = response.body.dig("data", "boards", 0, "items_page", "cursor")
 
-# Fetch next page using cursor
+# Fetch next page
 if cursor
   next_response = client.board.items_page(
-    board_ids: <BOARD_ID>,
+    board_ids: 1234567890,
     limit: 100,
     cursor: cursor
   )
 end
-
-# You can also filter items using query_params
-response = client.board.items_page(
-  board_ids: <BOARD_ID>,
-  limit: 50,
-  query_params: {
-    rules: [{ column_id: "status", compare_value: [1] }],
-    operator: :and
-  }
-)
 ```
 
-Pagination is also available for groups and items:
+See the [Pagination Guide](https://sanifhimani.github.io/monday_ruby/guides/advanced/pagination) for more details.
 
-```ruby
-# Fetch paginated items from a group
-response = client.group.items_page(
-  board_ids: <BOARD_ID>,
-  group_ids: "group_id",
-  limit: 100
-)
+### Error Handling
 
-# Fetch paginated items with custom query
-response = client.item.items_page(
-  limit: 100,
-  query_params: {
-    rules: [{ column_id: "status", compare_value: [5] }]
-  }
-)
+The library provides typed exceptions for different error scenarios:
+
+```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
 ```
 
+See the [Error Handling Guide](https://sanifhimani.github.io/monday_ruby/guides/advanced/errors) for best practices.
+
+## Available Resources
+
+The client provides access to all monday.com resources:
+
+- **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`
+
+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