monday_ruby 1.1.0 → 1.2.0

data/docs/guides/authentication.md

@@ -0,0 +1,286 @@
+# Authentication
+
+Manage API tokens and authenticate your monday.com requests securely.
+
+## Overview
+
+monday_ruby uses API tokens for authentication. Every request to the monday.com API requires a valid token.
+
+## Token Types
+
+### Personal API Token
+
+For individual use and testing:
+
+1. Log in to monday.com
+2. Click your profile picture → **Administration**
+3. Go to **Connections** → **Personal API token**
+4. Copy your token
+
+::: 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>Token Permissions</span>
+Personal API tokens have the same permissions as your monday.com account. Use carefully in production.
+:::
+
+### App-Based Tokens
+
+For production integrations, create a monday.com app:
+
+1. Go to the monday.com Developers Center
+2. Create a new app
+3. Generate OAuth tokens for users
+
+See [monday.com's OAuth documentation](https://developer.monday.com/apps/docs/oauth) for details.
+
+## Secure Token Storage
+
+### Development: Environment Variables
+
+Use a `.env` file:
+
+```bash
+# .env
+MONDAY_TOKEN=your_token_here
+```
+
+Add to `.gitignore`:
+
+```bash
+# .gitignore
+.env
+```
+
+Load in your application:
+
+```ruby
+require "dotenv/load"
+
+Monday.configure do |config|
+  config.token = ENV["MONDAY_TOKEN"]
+end
+```
+
+### Production: Credential Management
+
+Use secure credential storage:
+
+**Rails Credentials:**
+
+```bash
+rails credentials:edit
+```
+
+Add:
+
+```yaml
+monday:
+  token: your_token_here
+```
+
+Load:
+
+```ruby
+Monday.configure do |config|
+  config.token = Rails.application.credentials.monday[:token]
+end
+```
+
+**Environment Variables:**
+
+Set on your hosting platform:
+
+```bash
+# Heroku
+heroku config:set MONDAY_TOKEN=your_token_here
+
+# AWS Lambda
+# Set in Lambda environment variables
+
+# Docker
+docker run -e MONDAY_TOKEN=your_token_here
+```
+
+## Configuration Methods
+
+### Global Configuration
+
+Set once, use everywhere:
+
+```ruby
+Monday.configure do |config|
+  config.token = ENV["MONDAY_TOKEN"]
+end
+
+# All clients use this token
+client = Monday::Client.new
+```
+
+### Per-Client Configuration
+
+Use different tokens for different clients:
+
+```ruby
+# Client 1 with token A
+client_a = Monday::Client.new(token: ENV["MONDAY_TOKEN_A"])
+
+# Client 2 with token B
+client_b = Monday::Client.new(token: ENV["MONDAY_TOKEN_B"])
+```
+
+### Dynamic Token Switching
+
+Change tokens at runtime:
+
+```ruby
+Monday.configure do |config|
+  config.token = user.monday_token
+end
+
+client = Monday::Client.new
+```
+
+## Verify Authentication
+
+Test if your token is valid:
+
+```ruby
+client = Monday::Client.new
+
+response = client.account.query(
+  select: ["id", "name"]
+)
+
+if response.success?
+  account = response.body.dig("data", "account")
+  puts "Authenticated as: #{account['name']}"
+else
+  puts "Authentication failed"
+end
+```
+
+## Handle Authentication Errors
+
+Catch authentication failures:
+
+```ruby
+begin
+  client = Monday::Client.new(token: "invalid_token")
+  response = client.boards
+
+  unless response.success?
+    puts "Request failed: #{response.code}"
+  end
+rescue Monday::AuthorizationError => e
+  puts "Invalid API token: #{e.message}"
+rescue Monday::Error => e
+  puts "API error: #{e.message}"
+end
+```
+
+## Token Rotation
+
+Rotate tokens regularly for security:
+
+```ruby
+# 1. Generate new token in monday.com
+# 2. Update environment variable
+# 3. Deploy with new token
+# 4. Revoke old token after verification
+
+Monday.configure do |config|
+  config.token = ENV["MONDAY_TOKEN_NEW"]
+end
+
+# Test new token
+client = Monday::Client.new
+response = client.boards
+
+if response.success?
+  puts "New token works. Safe to revoke old token."
+end
+```
+
+## Multi-Tenant Applications
+
+Handle multiple monday.com accounts:
+
+```ruby
+class MondayService
+  def initialize(user)
+    @client = Monday::Client.new(token: user.monday_token)
+  end
+
+  def fetch_boards
+    @client.boards
+  end
+end
+
+# Usage
+service = MondayService.new(current_user)
+response = service.fetch_boards
+```
+
+## Security Best Practices
+
+### Never Log Tokens
+
+Avoid logging sensitive data:
+
+```ruby
+# Bad
+logger.info "Token: #{ENV['MONDAY_TOKEN']}"
+
+# Good
+logger.info "Authenticating with monday.com"
+```
+
+### Use Read-Only Tokens
+
+For read-only operations, create tokens with limited scopes in your monday.com app settings.
+
+### Validate Tokens on Startup
+
+Check authentication before running:
+
+```ruby
+def validate_monday_token!
+  client = Monday::Client.new
+  response = client.account.query(select: ["id"])
+
+  raise "Invalid monday.com token" unless response.success?
+end
+
+validate_monday_token!
+```
+
+### Rotate Regularly
+
+Change tokens every 90 days or after team member changes.
+
+## Troubleshooting
+
+### "Invalid token" Error
+
+- Verify token is copied correctly (no extra spaces)
+- Check token hasn't been revoked
+- Ensure token has necessary permissions
+
+### "Unauthorized" Error
+
+- Token may lack permissions for the requested operation
+- Verify your monday.com account has access to the board/workspace
+
+### Token Not Loading
+
+```ruby
+# Debug environment variable loading
+puts "Token loaded: #{ENV['MONDAY_TOKEN'] ? 'Yes' : 'No'}"
+
+# Verify dotenv is loaded
+require "dotenv/load"
+```
+
+## Next Steps
+
+- [Make your first request →](/guides/first-request)
+- [Understand error handling →](/guides/advanced/errors)
+- [Learn about configuration →](/reference/configuration)

data/docs/guides/boards/create.md

@@ -0,0 +1,386 @@
+# Create a Board
+
+Create new boards programmatically in your monday.com account.
+
+## Basic Board Creation
+
+Create a board with just a name:
+
+```ruby
+require "monday_ruby"
+
+Monday.configure do |config|
+  config.token = ENV["MONDAY_TOKEN"]
+end
+
+client = Monday::Client.new
+
+response = client.board.create(
+  args: {
+    board_name: "My New Board",
+    board_kind: :public
+  }
+)
+
+if response.success?
+  board = response.body.dig("data", "create_board")
+  puts "✓ Created board: #{board['name']}"
+  puts "  ID: #{board['id']}"
+else
+  puts "✗ Failed to create board"
+end
+```
+
+**Output:**
+```
+✓ Created board: My New Board
+  ID: 1234567890
+```
+
+## Board Privacy Levels
+
+Specify who can access the board:
+
+### Public Board
+
+Visible to all workspace members:
+
+```ruby
+response = client.board.create(
+  args: {
+    board_name: "Team Announcements",
+    board_kind: :public
+  }
+)
+```
+
+### Private Board
+
+Only visible to board subscribers:
+
+```ruby
+response = client.board.create(
+  args: {
+    board_name: "Executive Planning",
+    board_kind: :private
+  }
+)
+```
+
+### Shareable Board
+
+Can be shared via link outside your workspace:
+
+```ruby
+response = client.board.create(
+  args: {
+    board_name: "Client Collaboration",
+    board_kind: :share
+  }
+)
+```
+
+## Add Description
+
+Include a board description:
+
+```ruby
+response = client.board.create(
+  args: {
+    board_name: "Q1 Marketing Campaign",
+    board_kind: :public,
+    description: "Track all marketing initiatives for Q1 2024"
+  }
+)
+
+if response.success?
+  board = response.body.dig("data", "create_board")
+  puts "Created: #{board['name']}"
+  puts "Description: #{board['description']}"
+end
+```
+
+## Create from Template
+
+Use an existing board as a template:
+
+```ruby
+template_id = 1234567890  # ID of the template board
+
+response = client.board.create(
+  args: {
+    board_name: "New Project from Template",
+    board_kind: :public,
+    template_id: template_id
+  }
+)
+
+if response.success?
+  board = response.body.dig("data", "create_board")
+  puts "✓ Created from template: #{board['name']}"
+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>Templates</span>
+Templates copy the board structure (columns, groups, automations) but not the items. Perfect for recurring project types.
+:::
+
+## Create in Workspace
+
+Add the board to a specific workspace:
+
+```ruby
+workspace_id = 9876543210
+
+response = client.board.create(
+  args: {
+    board_name: "Product Development",
+    board_kind: :public,
+    workspace_id: workspace_id
+  }
+)
+```
+
+## Create in Folder
+
+Organize boards by placing them in folders:
+
+```ruby
+folder_id = 5555555555
+
+response = client.board.create(
+  args: {
+    board_name: "Sprint Planning",
+    board_kind: :public,
+    folder_id: folder_id
+  }
+)
+```
+
+## Customize Response Fields
+
+Choose which fields to return:
+
+```ruby
+response = client.board.create(
+  args: {
+    board_name: "Custom Fields Board",
+    board_kind: :public
+  },
+  select: [
+    "id",
+    "name",
+    "description",
+    "state",
+    "board_folder_id",
+    "workspace_id"
+  ]
+)
+
+if response.success?
+  board = response.body.dig("data", "create_board")
+
+  puts "Board Details:"
+  puts "  ID: #{board['id']}"
+  puts "  Name: #{board['name']}"
+  puts "  State: #{board['state']}"
+  puts "  Workspace: #{board['workspace_id']}"
+  puts "  Folder: #{board['board_folder_id'] || 'None'}"
+end
+```
+
+## Get Board URL
+
+Retrieve the board's URL after creation:
+
+```ruby
+response = client.board.create(
+  args: {
+    board_name: "New Board",
+    board_kind: :public
+  },
+  select: ["id", "name", "url"]
+)
+
+if response.success?
+  board = response.body.dig("data", "create_board")
+  puts "✓ Board created!"
+  puts "  View at: #{board['url']}"
+end
+```
+
+## Create with Columns
+
+Query the created board to see default columns:
+
+```ruby
+response = client.board.create(
+  args: {
+    board_name: "Board with Columns",
+    board_kind: :public
+  },
+  select: [
+    "id",
+    "name",
+    {
+      columns: ["id", "title", "type"]
+    }
+  ]
+)
+
+if response.success?
+  board = response.body.dig("data", "create_board")
+
+  puts "Board: #{board['name']}"
+  puts "Default columns:"
+
+  board["columns"].each do |column|
+    puts "  • #{column['title']} (#{column['type']})"
+  end
+end
+```
+
+**Example output:**
+```
+Board: Board with Columns
+Default columns:
+  • Name (name)
+  • Person (people)
+  • Status (color)
+  • Date (date)
+```
+
+## Error Handling
+
+Handle common creation errors:
+
+```ruby
+def create_board_safe(client, name, kind)
+  response = client.board.create(
+    args: {
+      board_name: name,
+      board_kind: kind
+    }
+  )
+
+  if response.success?
+    board = response.body.dig("data", "create_board")
+    puts "✓ Created: #{board['name']} (ID: #{board['id']})"
+    board['id']
+  else
+    puts "✗ Failed to create board"
+    puts "  Status: #{response.status}"
+
+    if response.body["errors"]
+      response.body["errors"].each do |error|
+        puts "  Error: #{error['message']}"
+      end
+    end
+
+    nil
+  end
+rescue Monday::AuthorizationError
+  puts "✗ Invalid API token"
+  nil
+rescue Monday::Error => e
+  puts "✗ API error: #{e.message}"
+  nil
+end
+
+# Usage
+board_id = create_board_safe(client, "Safe Board", :public)
+```
+
+## Complete Example
+
+Create a fully configured board:
+
+```ruby
+require "monday_ruby"
+require "dotenv/load"
+
+Monday.configure do |config|
+  config.token = ENV["MONDAY_TOKEN"]
+end
+
+client = Monday::Client.new
+
+# Create board with all options
+response = client.board.create(
+  args: {
+    board_name: "Q1 2024 Projects",
+    board_kind: :public,
+    description: "All projects planned for Q1 2024",
+    workspace_id: 9876543210,  # Optional: your workspace ID
+    folder_id: 5555555555       # Optional: your folder ID
+  },
+  select: [
+    "id",
+    "name",
+    "description",
+    "url",
+    "state",
+    {
+      columns: ["id", "title", "type"]
+    }
+  ]
+)
+
+if response.success?
+  board = response.body.dig("data", "create_board")
+
+  puts "\n✓ Board Created Successfully\n"
+  puts "#{'=' * 50}"
+  puts "Name: #{board['name']}"
+  puts "ID: #{board['id']}"
+  puts "URL: #{board['url']}"
+  puts "Description: #{board['description']}"
+  puts "\nDefault Columns:"
+
+  board["columns"].each do |column|
+    puts "  • #{column['title']} (type: #{column['type']})"
+  end
+
+  puts "#{'=' * 50}"
+else
+  puts "\n✗ Failed to create board"
+  puts "Status code: #{response.status}"
+
+  if response.body["error_message"]
+    puts "Error: #{response.body['error_message']}"
+  end
+end
+```
+
+## Validate Board Name
+
+Check for valid board names before creating:
+
+```ruby
+def valid_board_name?(name)
+  return false if name.nil? || name.empty?
+  return false if name.length > 255
+
+  true
+end
+
+board_name = "My New Board"
+
+if valid_board_name?(board_name)
+  response = client.board.create(
+    args: {
+      board_name: board_name,
+      board_kind: :public
+    }
+  )
+else
+  puts "Invalid board name"
+end
+```
+
+## Next Steps
+
+- [Query boards](/guides/boards/query)
+- [Update board settings](/guides/boards/update)
+- [Add items to boards](/guides/items/create)
+- [Duplicate boards](/guides/boards/duplicate)