fizzy-api-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3e7d416cc4e5989199b27614c9ea651a86510ffc823efd22837a995b643dd965
+  data.tar.gz: 5abf84d0a65f218974ace1361f5ed8d7ca79fb4512c90f260b86a55307881824
+SHA512:
+  metadata.gz: 9382ce0f1278a8547d1fe2d9fd13f637cbe7d793ff9df02db8ed45eeec184d52c3752cb62cf4a227ae1d2aeb155159328aa83b2f6722485cf12c122f581acaa9
+  data.tar.gz: 974bf8afa1f54d417b906178b4640b8165fabd4ad1f978c97f98fed376263a56f2a04eddf2ceb94f2f0db15c5255d5babf160c8f962847f5f17a92403e1c4fc8

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-21
+
+### Added
+
+- Initial release of the Fizzy API Client gem
+- Full CRUD support for all Fizzy resources:
+  - Identity (account info)
+  - Boards (create, read, update, delete)
+  - Cards (full lifecycle including close, reopen, postpone, triage, watch, gild)
+  - Columns (with named color support: blue, gray, tan, yellow, lime, aqua, violet, purple, pink)
+  - Comments (threaded discussions)
+  - Steps (checklist items with complete/incomplete)
+  - Reactions (emoji reactions)
+  - Tags (with toggle support)
+  - Users (including avatar upload and deactivation)
+  - Notifications (read/unread management)
+  - Direct Uploads (ActiveStorage integration)
+- Named colors for columns (`:blue`, `:lime`, `:pink`, etc.) - no need to use CSS variables
+- Golden ticket support (`gild_card`/`ungild_card`)
+- Background image upload for cards
+- Flexible configuration system:
+  - Global configuration via `FizzyApiClient.configure`
+  - Client-specific configuration
+  - Environment variable support (FIZZY_API_TOKEN, FIZZY_ACCOUNT, FIZZY_BASE_URL)
+- Pagination support:
+  - Manual page navigation with `page:` parameter
+  - Automatic pagination with `auto_paginate: true`
+- Error handling with specific error classes:
+  - AuthenticationError (401)
+  - ForbiddenError (403)
+  - NotFoundError (404)
+  - ValidationError (422)
+  - ServerError (500+)
+- Comprehensive demo script that tests all features
+- Self-hosted instance support via `base_url` configuration
+- Account slug normalization (strips leading `/` from identity API slugs)
+- Multipart/form-data support for file uploads
+- Optional logger integration for debugging

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Fizzy Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,469 @@
+# Fizzy API Client
+
+A Ruby gem providing a clean, idiomatic interface to the [Fizzy](https://fizzy.do) API. Fizzy is a task management app from [37signals](https://37signals.com).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fizzy-api-client'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install fizzy-api-client
+```
+
+## Quick Start
+
+```ruby
+require 'fizzy_api_client'
+
+# Configure globally
+FizzyApiClient.configure do |config|
+  config.api_token = 'your-api-token'
+  config.account_slug = 'your-account'
+end
+
+# Or use environment variables:
+# FIZZY_API_TOKEN, FIZZY_ACCOUNT, FIZZY_BASE_URL
+
+client = FizzyApiClient::Client.new
+
+# Get identity
+identity = client.identity
+
+# List boards
+boards = client.boards
+
+# Create a card (note: uses 'title' field, not 'name')
+card = client.create_card(board_id: 'board_1', title: 'New Task')
+
+# Add a step (note: uses 'content' field)
+step = client.create_step(card['number'], content: 'First step')
+```
+
+## Rails Integration
+
+### Configuration with Credentials
+
+Store your API credentials securely using Rails credentials:
+
+```bash
+$ rails credentials:edit
+```
+
+```yaml
+# config/credentials.yml.enc
+fizzy:
+  api_token: your-api-token
+  account_slug: your-account
+```
+
+### Initializer
+
+Create an initializer to configure the client:
+
+```ruby
+# config/initializers/fizzy.rb
+FizzyApiClient.configure do |config|
+  config.api_token = Rails.application.credentials.dig(:fizzy, :api_token)
+  config.account_slug = Rails.application.credentials.dig(:fizzy, :account_slug)
+  config.logger = Rails.logger if Rails.env.development?
+end
+```
+
+### Controller Example
+
+```ruby
+# app/controllers/tasks_controller.rb
+class TasksController < ApplicationController
+  def index
+    @boards = fizzy_client.boards
+  end
+
+  def create
+    card = fizzy_client.create_card(
+      board_id: params[:board_id],
+      title: params[:title],
+      description: params[:description]
+    )
+
+    redirect_to tasks_path, notice: "Task ##{card['number']} created"
+  rescue FizzyApiClient::ApiError => e
+    redirect_to tasks_path, alert: "Failed to create task: #{e.message}"
+  end
+
+  def complete
+    fizzy_client.close_card(params[:card_number])
+    redirect_to tasks_path, notice: "Task completed"
+  end
+
+  private
+
+  def fizzy_client
+    @fizzy_client ||= FizzyApiClient::Client.new
+  end
+end
+```
+
+### Background Job Example
+
+```ruby
+# app/jobs/sync_fizzy_cards_job.rb
+class SyncFizzyCardsJob < ApplicationJob
+  queue_as :default
+
+  def perform(board_id)
+    client = FizzyApiClient::Client.new
+    cards = client.cards(board_ids: [board_id], auto_paginate: true)
+
+    cards.each do |card_data|
+      Task.find_or_initialize_by(fizzy_number: card_data['number']).update!(
+        title: card_data['title'],
+        status: card_data['closed_at'].present? ? 'completed' : 'open',
+        synced_at: Time.current
+      )
+    end
+  end
+end
+```
+
+### Per-Environment Configuration
+
+```ruby
+# config/initializers/fizzy.rb
+FizzyApiClient.configure do |config|
+  config.api_token = Rails.application.credentials.dig(:fizzy, :api_token)
+  config.account_slug = Rails.application.credentials.dig(:fizzy, :account_slug)
+
+  # Use different base URL for staging/development
+  if Rails.env.staging?
+    config.base_url = 'https://staging.fizzy.do'
+  end
+
+  # Enable logging in development
+  config.logger = Rails.logger if Rails.env.development?
+
+  # Shorter timeouts in test environment
+  if Rails.env.test?
+    config.timeout = 5
+    config.open_timeout = 2
+  end
+end
+```
+
+## Configuration
+
+### Global Configuration
+
+```ruby
+FizzyApiClient.configure do |config|
+  config.api_token = 'your-api-token'
+  config.account_slug = 'your-account'
+  config.base_url = 'https://app.fizzy.do'  # default
+  config.timeout = 30                        # seconds
+  config.open_timeout = 10                   # seconds
+  config.logger = Logger.new($stdout)        # optional
+end
+```
+
+### Client Configuration
+
+```ruby
+client = FizzyApiClient::Client.new(
+  api_token: 'your-api-token',
+  account_slug: 'your-account'
+)
+```
+
+### Environment Variables
+
+- `FIZZY_API_TOKEN` - Personal Access Token
+- `FIZZY_ACCOUNT` - Default account slug
+- `FIZZY_BASE_URL` - API base URL (for self-hosted instances)
+
+### Account Slug Normalization
+
+The identity API returns account slugs with a leading slash (e.g., `/897362094`). This gem automatically normalizes slugs by stripping the leading slash.
+
+## Resources
+
+### Identity
+```ruby
+client.identity
+```
+
+### Boards
+```ruby
+# List and retrieve
+client.boards
+client.boards(page: 2)
+client.boards(auto_paginate: true)
+client.board('board_id')
+
+# Create
+client.create_board(name: 'New Board')
+client.create_board(
+  name: 'Team Board',
+  all_access: false,
+  auto_postpone_period: 7,
+  public_description: '<p>Description</p>'
+)
+
+# Update
+client.update_board('board_id', name: 'Updated Name')
+client.update_board('board_id', user_ids: ['user_1', 'user_2'])  # when all_access: false
+
+# Delete
+client.delete_board('board_id')
+```
+
+### Cards
+Cards use `title` field (not `name`).
+
+```ruby
+# List with filters
+client.cards
+client.cards(board_ids: ['board_1', 'board_2'])
+client.cards(tag_ids: ['tag_1'], assignee_ids: ['user_1'])
+client.cards(terms: ['bug', 'fix'])
+client.cards(auto_paginate: true)
+
+# Retrieve
+client.card(42)
+
+# Create
+client.create_card(board_id: 'board_1', title: 'New Card')
+client.create_card(
+  board_id: 'board_1',
+  title: 'Full Card',
+  description: 'Details here',
+  status: 'published',
+  tag_ids: ['tag_1', 'tag_2']
+)
+
+# Create with image
+client.create_card(
+  board_id: 'board_1',
+  title: 'Card with Image',
+  image: '/path/to/image.png'  # or File object
+)
+
+# Update
+client.update_card(42, title: 'Updated Title')
+client.update_card(42, image: '/path/to/new_image.png')
+
+# Delete
+client.delete_card(42)
+
+# State changes
+client.close_card(42)
+client.reopen_card(42)
+client.postpone_card(42)  # or client.not_now_card(42)
+
+# Triage (move to column)
+client.triage_card(42, column_id: 'col_1')
+client.untriage_card(42)
+
+# Assignments and tags
+client.toggle_assignment(42, assignee_id: 'user_1')
+client.toggle_tag(42, tag_title: 'urgent')
+
+# Watch/unwatch
+client.watch_card(42)
+client.unwatch_card(42)
+
+# Golden ticket (highlight/pin a card)
+client.gild_card(42)
+client.ungild_card(42)
+```
+
+### Columns
+```ruby
+# List and retrieve
+client.columns('board_id')
+client.column('board_id', 'column_id')
+
+# Create with named color (recommended)
+client.create_column(board_id: 'board_1', name: 'In Progress')
+client.create_column(board_id: 'board_1', name: 'Review', color: :lime)
+client.create_column(board_id: 'board_1', name: 'Urgent', color: :pink)
+
+# Update with named color
+client.update_column('board_id', 'column_id', name: 'Done')
+client.update_column('board_id', 'column_id', color: :purple)
+
+# Available colors: :blue (default), :gray, :tan, :yellow, :lime, :aqua, :violet, :purple, :pink
+# CSS variable tokens are also supported: 'var(--color-card-3)'
+
+# Delete
+client.delete_column('board_id', 'column_id')
+```
+
+### Comments
+```ruby
+# List and retrieve
+client.comments(42)
+client.comment(42, 'comment_id')
+
+# Create
+client.create_comment(42, body: 'This is a comment')
+client.create_comment(42, body: 'Backdated comment', created_at: '2025-01-01T00:00:00Z')
+
+# Update
+client.update_comment(42, 'comment_id', body: 'Updated comment')
+
+# Delete
+client.delete_comment(42, 'comment_id')
+```
+
+### Steps
+Steps use `content` field (not `name`).
+
+```ruby
+# Retrieve
+client.step(42, 'step_id')
+
+# Create
+client.create_step(42, content: 'Do this first')
+client.create_step(42, content: 'Already done', completed: true)
+
+# Update
+client.update_step(42, 'step_id', content: 'Updated step')
+client.update_step(42, 'step_id', completed: true)
+
+# Convenience methods
+client.complete_step(42, 'step_id')
+client.incomplete_step(42, 'step_id')
+
+# Delete
+client.delete_step(42, 'step_id')
+```
+
+### Reactions
+Reactions use `content` field (not `emoji`).
+
+```ruby
+# List reactions on a comment
+client.reactions(42, 'comment_id')
+
+# Add reaction
+client.add_reaction(42, 'comment_id', content: ':+1:')
+
+# Remove reaction
+client.remove_reaction(42, 'comment_id', 'reaction_id')
+```
+
+### Tags
+Tags return `title` field (not `name`).
+
+```ruby
+client.tags
+client.tags(page: 2)
+client.tags(auto_paginate: true)
+```
+
+### Users
+```ruby
+# List and retrieve
+client.users
+client.users(auto_paginate: true)
+client.user('user_id')
+
+# Update
+client.update_user('user_id', name: 'New Name')
+
+# Update with avatar
+client.update_user('user_id', avatar: '/path/to/avatar.png')
+client.update_user('user_id', name: 'New Name', avatar: File.open('avatar.png'))
+
+# Deactivate
+client.deactivate_user('user_id')
+```
+
+### Notifications
+```ruby
+# List
+client.notifications
+client.notifications(auto_paginate: true)
+
+# Mark as read/unread
+client.mark_notification_read('notification_id')
+client.mark_notification_unread('notification_id')
+
+# Mark all as read
+client.mark_all_notifications_read
+```
+
+### Direct Uploads (File Attachments)
+For uploading files via ActiveStorage:
+
+```ruby
+# Simple file upload (handles all steps automatically)
+signed_id = client.upload_file('/path/to/document.pdf')
+signed_id = client.upload_file(file_io, filename: 'report.pdf', content_type: 'application/pdf')
+
+# Manual direct upload (for advanced use cases)
+upload = client.create_direct_upload(
+  filename: 'document.pdf',
+  byte_size: 1024,
+  checksum: Base64.strict_encode64(Digest::MD5.digest(content)),
+  content_type: 'application/pdf'
+)
+# Then PUT to upload['direct_upload']['url'] with the file content
+# Use upload['signed_id'] to reference the uploaded file
+```
+
+## Pagination
+
+```ruby
+# First page only (default)
+boards = client.boards
+
+# Specific page
+boards = client.boards(page: 2)
+
+# All pages (automatically follows pagination)
+boards = client.boards(auto_paginate: true)
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.board('invalid')
+rescue FizzyApiClient::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue FizzyApiClient::AuthenticationError => e
+  puts "Auth failed: #{e.message}"
+rescue FizzyApiClient::ForbiddenError => e
+  puts "Access denied: #{e.message}"
+rescue FizzyApiClient::ValidationError => e
+  puts "Invalid data: #{e.message}"
+rescue FizzyApiClient::ServerError => e
+  puts "Server error: #{e.message}"
+rescue FizzyApiClient::ApiError => e
+  puts "API error #{e.status}: #{e.message}"
+rescue FizzyApiClient::ConnectionError => e
+  puts "Connection failed: #{e.message}"
+rescue FizzyApiClient::TimeoutError => e
+  puts "Request timed out: #{e.message}"
+end
+```
+
+## Demo Script
+
+A comprehensive demo script is included that tests every feature of the gem. See [examples/README.md](examples/README.md) for usage instructions.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/examples/README.md

@@ -0,0 +1,102 @@
+# Demo Script
+
+A comprehensive demo script that tests every feature of the fizzy-api-client gem against a live Fizzy instance.
+
+## Running the Demo
+
+```bash
+# Basic usage
+FIZZY_API_TOKEN=your-token FIZZY_ACCOUNT=your-account ruby examples/demo.rb
+
+# For self-hosted Fizzy instances
+FIZZY_BASE_URL=https://fizzy.mycompany.com FIZZY_API_TOKEN=your-token ruby examples/demo.rb
+
+# With verbose output (shows full API responses)
+VERBOSE=1 FIZZY_API_TOKEN=your-token FIZZY_ACCOUNT=your-account ruby examples/demo.rb
+
+# Skip destructive operations (user updates, deactivation)
+SKIP_DESTRUCTIVE=1 FIZZY_API_TOKEN=your-token FIZZY_ACCOUNT=your-account ruby examples/demo.rb
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FIZZY_API_TOKEN` | Yes | Your Fizzy API token |
+| `FIZZY_ACCOUNT` | No | Account slug (auto-detected if not set) |
+| `FIZZY_BASE_URL` | No | API base URL for self-hosted instances |
+| `VERBOSE` | No | Set to `1` to show full API responses |
+| `SKIP_DESTRUCTIVE` | No | Set to `1` to skip operations that modify existing user data (update_user, deactivate_user) |
+
+## What the Demo Tests
+
+The demo runs through all gem features:
+
+1. **Identity** - Authentication and account discovery
+2. **Boards** - List, get, create, update, delete
+3. **Columns** - List, get, create with named colors, update, delete
+4. **Cards** - Full CRUD, state changes (close/reopen/postpone), triage, watch, tags, assignments, background image upload, golden tickets
+5. **Steps** - Create, get, update, complete/incomplete, delete
+6. **Comments** - Full CRUD operations
+7. **Reactions** - Add, list, remove
+8. **Tags** - List with pagination
+9. **Users** - List, get single user
+10. **Notifications** - List, mark read/unread, mark all read
+11. **Direct Uploads** - File upload via ActiveStorage
+12. **Pagination** - Auto-pagination for all list endpoints
+13. **Error Handling** - Validates proper error responses
+14. **Cleanup** - Removes all test data created during the demo
+
+## Test Data
+
+The demo creates temporary test data and cleans up after itself:
+
+- Creates a test board
+- Creates test columns with various colors
+- Creates test cards (including one with `sydney.jpg` as background image)
+- Creates test steps, comments, and reactions
+- Tests golden ticket (gild/ungild) functionality
+- Deletes all created resources at the end
+
+## Test Image
+
+The `sydney.jpg` file is included for testing background image uploads on cards.
+
+## Expected Output
+
+A successful run looks like:
+
+```
+============================================================
+Fizzy API Client - Comprehensive Demo
+============================================================
+Version: 0.1.0
+Base URL: https://app.fizzy.do
+Skip destructive: false
+============================================================
+
+1. IDENTITY
+-----------
+  ✓ Get identity
+    Accounts: /123456
+
+2. BOARDS
+---------
+  ✓ List boards
+  ✓ Get single board
+  ✓ Create board
+  ...
+
+============================================================
+DEMO SUMMARY
+============================================================
+  Passed:  70
+  Failed:  0
+  Skipped: 4
+============================================================
+All tests passed!
+```
+
+Skipped tests are expected for:
+- Toggle assignment (when identity doesn't include current user)
+- Update user, avatar, deactivate (skipped to protect real data)