monday_ruby 1.2.0 → 1.2.1

data/docs/guides/first-request.md

@@ -1,285 +0,0 @@
-# Make Your First Request
-
-Query boards from your monday.com account using the Ruby client.
-
-## Prerequisites
-
-- [Installed and configured](/guides/installation) monday_ruby
-- [Set up authentication](/guides/authentication) with your API token
-
-## Basic Query
-
-The simplest request fetches all boards you have access to:
-
-```ruby
-require "monday_ruby"
-
-Monday.configure do |config|
-  config.token = ENV["MONDAY_TOKEN"]
-end
-
-client = Monday::Client.new
-response = client.board.query
-```
-
-This returns all boards with their ID, name, and description.
-
-## Check Response Status
-
-Always verify the request succeeded:
-
-```ruby
-client = Monday::Client.new
-response = client.board.query
-
-if response.success?
-  puts "Request succeeded!"
-  puts "Status code: #{response.status}"
-else
-  puts "Request failed: #{response.status}"
-end
-```
-
-The `success?` method returns `true` for 2xx status codes and when there are no API errors.
-
-## Access Response Data
-
-Extract data from the response body:
-
-```ruby
-response = client.board.query
-
-if response.success?
-  boards = response.body["data"]["boards"]
-
-  puts "Found #{boards.length} boards:\n"
-
-  boards.each do |board|
-    puts "  • #{board['name']} (ID: #{board['id']})"
-  end
-end
-```
-
-**Example output:**
-```
-Found 3 boards:
-  • Marketing Campaigns (ID: 1234567890)
-  • Product Roadmap (ID: 2345678901)
-  • Team Tasks (ID: 3456789012)
-```
-
-## Using dig for Safe Access
-
-Use `dig` to safely navigate nested hashes:
-
-```ruby
-response = client.board.query
-
-boards = response.body.dig("data", "boards")
-
-if boards
-  first_board = boards.first
-  board_name = first_board.dig("name")
-
-  puts "First board: #{board_name}"
-else
-  puts "No boards found"
-end
-```
-
-This prevents `NoMethodError` if keys don't exist.
-
-## Filter Results
-
-Query specific boards by ID:
-
-```ruby
-response = client.board.query(
-  args: { ids: [1234567890, 2345678901] }
-)
-
-if response.success?
-  boards = response.body.dig("data", "boards")
-  puts "Retrieved #{boards.length} specific boards"
-end
-```
-
-## Customize Fields
-
-Select only the fields you need:
-
-```ruby
-response = client.board.query(
-  select: ["id", "name"]  # Skip description
-)
-
-if response.success?
-  boards = response.body.dig("data", "boards")
-
-  boards.each do |board|
-    # Only id and name are present
-    puts "#{board['id']}: #{board['name']}"
-  end
-end
-```
-
-::: tip <span style="display: inline-flex; align-items: center; gap: 6px;"><svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle><line x1="12" y1="16" x2="12" y2="12"></line><line x1="12" y1="8" x2="12.01" y2="8"></line></svg>Performance Tip</span>
-Only request fields you need. Smaller responses are faster and use less bandwidth.
-:::
-
-## Query Nested Data
-
-Fetch boards with their items:
-
-```ruby
-response = client.board.query(
-  args: { ids: [1234567890] },
-  select: [
-    "id",
-    "name",
-    {
-      items: ["id", "name"]
-    }
-  ]
-)
-
-if response.success?
-  board = response.body.dig("data", "boards", 0)
-
-  puts "Board: #{board['name']}"
-  puts "Items:"
-
-  board["items"].each do |item|
-    puts "  • #{item['name']}"
-  end
-end
-```
-
-**Example output:**
-```
-Board: Marketing Campaigns
-Items:
-  • Q1 Campaign Plan
-  • Social Media Strategy
-  • Email Newsletter Design
-```
-
-## Response Structure
-
-All responses follow this structure:
-
-```ruby
-{
-  "data" => {
-    "boards" => [
-      {
-        "id" => "1234567890",
-        "name" => "Board Name",
-        "description" => "Board description"
-      }
-    ]
-  }
-}
-```
-
-The root `data` key contains the query results. Resource arrays (like `boards`) are always arrays, even for single items.
-
-## Handle Errors
-
-Check for specific error conditions:
-
-```ruby
-response = client.board.query
-
-if response.success?
-  boards = response.body.dig("data", "boards")
-  puts "Success! Found #{boards.length} boards"
-else
-  puts "Request failed with status: #{response.status}"
-
-  # Check for API errors
-  if response.body["errors"]
-    puts "API Errors:"
-    response.body["errors"].each do |error|
-      puts "  • #{error['message']}"
-    end
-  end
-end
-```
-
-## Common Response Codes
-
-| Code | Meaning | Action |
-|------|---------|--------|
-| 200 | Success | Process the data |
-| 401 | Unauthorized | Check your API token |
-| 429 | Rate limited | Wait and retry |
-| 500 | Server error | Retry with backoff |
-
-::: warning <span style="display: inline-flex; align-items: center; gap: 6px;"><svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"></path><line x1="12" y1="9" x2="12" y2="13"></line><line x1="12" y1="17" x2="12.01" y2="17"></line></svg>200 Doesn't Always Mean Success</span>
-monday.com returns status 200 even for some errors. Always check `response.success?` which also validates the response body for error fields.
-:::
-
-## Complete Example
-
-Put it all together:
-
-```ruby
-require "monday_ruby"
-require "dotenv/load"
-
-Monday.configure do |config|
-  config.token = ENV["MONDAY_TOKEN"]
-end
-
-client = Monday::Client.new
-
-# Query boards with items
-response = client.board.query(
-  args: { limit: 5 },
-  select: [
-    "id",
-    "name",
-    "description",
-    {
-      items: ["id", "name"]
-    }
-  ]
-)
-
-if response.success?
-  boards = response.body.dig("data", "boards")
-
-  puts "\n📋 Your Boards\n#{'=' * 50}\n"
-
-  boards.each do |board|
-    puts "\n#{board['name']}"
-    puts "  ID: #{board['id']}"
-    puts "  Items: #{board['items']&.length || 0}"
-
-    if board['description'] && !board['description'].empty?
-      puts "  Description: #{board['description']}"
-    end
-  end
-
-  puts "\n#{'=' * 50}"
-  puts "Total: #{boards.length} boards"
-else
-  puts "❌ Request failed"
-  puts "Status: #{response.status}"
-
-  if response.body["errors"]
-    puts "\nErrors:"
-    response.body["errors"].each do |error|
-      puts "  • #{error['message']}"
-    end
-  end
-end
-```
-
-## Next Steps
-
-- [Create a board](/guides/boards/create)
-- [Query boards with advanced filters](/guides/boards/query)
-- [Work with items](/guides/items/create)
-- [Handle errors properly](/guides/advanced/errors)