umami-ruby 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6864cffba61396afd181c29d69bf8f3676c4836b70acc06d309fb7d95c1e1e02
-  data.tar.gz: 619f861f73eb0388813d6252cc5869f3c53246e799d90d912d9cde8e8118cb97
+  metadata.gz: 24515824a954d2c9b334b0445ef3a64f2faf79bb9fd0ec26657b702f0e170951
+  data.tar.gz: 2eec535b5aa02bf528b05a7d767d843b5781d8d970d03d7070953fc604582904
 SHA512:
-  metadata.gz: 809be5c3afeacf57451b33218c9e7f4cf49045148ac41b1efd0970ddcf597dff99a7adf12c9f3ddb4beb47209d94e55da211857b3d7fd9901fbead106b454a1d
-  data.tar.gz: 3abcca6c471a3353b8a7ca257f3583d6ede3cc5477b16f2d1abf546dd26b9a81a3720947cfbee0277e9ce7a7eb00005d084816d681ef0dbe6a1f4b53dd93e23a
+  metadata.gz: 53784a10bf0025c49791ace32354800ac39bdb7e662234a7f81f78f50538234aec5c32fda101bd7d844bd3df5eaf8a94e6002d85037729db637b8ff818e2d55f
+  data.tar.gz: 84cb4db13dd978dfb0ac65982081fe3a1a23b8e0b3f755c7cfc0c920e53c32d16861630b5a17c43059882c43222ce62f4e6aed1ff1b599d4da2e92bd56e56375

data/.env.test

@@ -0,0 +1,9 @@
+# Test environment configuration (safe to commit)
+# Real credentials should go in .env.test.local (gitignored)
+
+UMAMI_ACCESS_TOKEN=test_token_placeholder
+UMAMI_URI_BASE=https://api.umami.is
+
+# Test website IDs (using placeholder UUIDs)
+UMAMI_TEST_WEBSITE_ID=00000000-0000-0000-0000-000000000001
+UMAMI_TEST_WEBSITE_ID_ALT=00000000-0000-0000-0000-000000000002

data/.simplecov

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Track coverage for the lib directory (gem source code)
+  add_filter "/test/"
+
+  # Track Ruby files in lib directory
+  track_files "lib/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Set minimum coverage threshold to prevent coverage regression
+  # Current coverage: Line ~73%, Branch ~73%
+  minimum_coverage line: 70, branch: 65
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  puts "Branch Coverage: #{SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || 'N/A'}%"
+  puts "=" * 60
+end

data/CHANGELOG.md

@@ -1,4 +1,97 @@
-## [Unreleased]
+## [0.3.0] - 2026-07-24
+
+### Fixed
+
+- **Username/password authentication against self-hosted instances actually works now.** Since the connection memoization was introduced, `authenticate` built (and memoized) the Faraday connection in order to POST `/api/auth/login` — before `@access_token` existed. Faraday bakes headers in at connection build time, so every request after a successful login went out without an `Authorization` header and failed with 401. The token-based flow was unaffected, which is how this survived: docs and tests exercised logins, never "login **then** call an endpoint". `authenticate` now drops the memoized connection after storing the token so the next request rebuilds it with the Bearer header, and the new `test/integration/authentication_flow_test.rb` pins the full lifecycle (login → authorized request → connection reuse without re-login).
+- `authenticate` raises `Umami::AuthenticationError` when the login response is a 200 without a `token` field, instead of leaving a client that 401s on every call with no hint why.
+
+### Changed
+
+- HTTP 401 and 403 responses now raise `Umami::AuthenticationError` instead of the undifferentiated `Umami::ClientError`, giving long-lived clients a re-authentication signal (expired/revoked token, insufficient permissions). To keep existing `rescue Umami::APIError` handlers working — they used to catch these as `ClientError` — `AuthenticationError` is now a subclass of `Umami::APIError` (previously it subclassed `Umami::Error` directly). Code matching `Umami::ClientError` specifically for 401/403 must switch to `Umami::AuthenticationError`.
+
+## [0.2.0] - 2026-02-02
+
+### Added
+
+**New Endpoint Categories:**
+- **Me endpoints**: `me`, `my_teams`, `my_websites` - Get current user info and resources
+- **Admin endpoints**: `admin_users`, `admin_websites`, `admin_teams` - Admin-only endpoints for self-hosted
+- **Sessions endpoints** (8 new methods):
+  - `website_sessions` - Get sessions within a time range
+  - `website_sessions_stats` - Get summarized session statistics
+  - `website_sessions_weekly` - Get session counts by hour of weekday
+  - `website_session` - Get individual session details
+  - `website_session_activity` - Get session activity
+  - `website_session_properties` - Get session properties
+  - `website_session_data_properties` - Get session data property counts
+  - `website_session_data_values` - Get session data value counts
+- **Realtime endpoint**: `realtime` - Get live stats for last 30 minutes
+- **Links endpoints**: `links`, `link`, `update_link`, `delete_link`
+- **Pixels endpoints**: `pixels`, `pixel`, `update_pixel`, `delete_pixel`
+- **Reports endpoints** (13 new methods):
+  - CRUD: `reports`, `create_report`, `report`, `update_report`, `delete_report`
+  - Specialized: `report_attribution`, `report_breakdown`, `report_funnel`, `report_goals`, `report_journey`, `report_retention`, `report_revenue`, `report_utm`
+- **Website stats endpoints**:
+  - `website_events_series` - Get events series with time bucketing
+  - `website_metrics_expanded` - Get detailed metrics with engagement data
+- **Events endpoints**:
+  - `website_events_list` - Get paginated event details
+  - `website_event_data` - Get data for individual event
+  - `website_event_data_events` - Get event data names and counts
+  - `website_event_data_fields` - Get event data fields
+  - `website_event_data_properties` - Get event properties
+  - `website_event_data_values` - Get event data values
+  - `website_event_data_stats` - Get aggregated event stats
+
+**Configuration:**
+- `request_timeout=` setter - users can now customize timeout via `Umami.configure` block
+- New `UMAMI_CLOUD_SEND_URL` constant for the Cloud send endpoint URL
+- Optional `user_agent:` parameter to `send_event` method for custom User-Agent strings
+
+**Documentation:**
+- Configuration Options table in README with all available options and defaults
+- Report Types reference table in README
+
+**Test Suite:**
+- Comprehensive Minitest test suite with 152 tests
+- VCR cassettes for all read API endpoints (33 cassettes)
+- CI workflow for Ruby 3.3, 3.4, 4.0
+- ~72% line and branch coverage
+
+### Changed
+
+- Updated `website_metrics` documentation with all current metric types
+- Updated user role documentation to include `view-only` option
+- Updated team role documentation with `team-manager`, `team-member`, `team-view-only` roles
+- Updated `send_event` documentation with `tag` and `id` parameters
+- Improved filter parameter documentation across all endpoints
+- Added optional `id` parameter to `create_user` for UUID control
+- Report endpoints use `startDate`/`endDate` (ISO 8601) instead of `startAt`/`endAt` (timestamps)
+- Added `window` parameter to `report_funnel` for days between steps
+- Added `timezone` parameter (required) to `report_retention`
+- Updated `unit` parameter to include `minute` option
+- Made `timezone` required for `website_sessions_weekly`
+- Made `startAt`/`endAt` required for `website_session_activity`
+
+### Fixed
+
+- **Critical**: Fixed `send_event` to use correct Umami Cloud URL (`https://cloud.umami.is/api/send`)
+- **Critical**: Added mandatory `User-Agent` header to `send_event` requests (fixes [#2](https://github.com/rameerez/umami-ruby/issues/2))
+- Fixed `send_event` to not send unnecessary `Authorization` header
+- Fixed event data endpoint paths from `/api/event-data/...` to `/api/websites/:websiteId/event-data/...`
+- Fixed `verify_token` to use POST method instead of GET
+- Fixed `website_event_data_stats` return type documentation
+
+### Deprecated
+
+- `event_data_events` - Use `website_event_data_events` instead
+- `event_data_fields` - Use `website_event_data_fields` instead
+- `event_data_stats` - Use `website_event_data_stats` instead
+- `users` - Use `admin_users` instead
+
+## [0.1.3] - 2025-02-19
+
+- Bug fixes and improvements
 
 ## [0.1.0] - 2024-07-22
 

data/CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`umami-ruby` is a Ruby wrapper for the Umami Analytics API. It works with both Umami Cloud and self-hosted instances.
+
+## Key Files
+
+- `lib/umami/client.rb` - Main API client with all endpoint methods
+- `lib/umami/configuration.rb` - Configuration management
+- `lib/umami/errors.rb` - Custom error classes
+- `test/` - Minitest test suite with VCR cassettes
+
+## Development Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rake test
+
+# Run tests with coverage
+bundle exec rake test  # SimpleCov runs automatically
+
+# Generate documentation
+yard doc
+yard server
+```
+
+## Testing Guidelines
+
+- All tests use VCR cassettes for HTTP interactions
+- Cassettes are in `test/cassettes/`
+- Use `VCR_RECORD_MODE=new_episodes bundle exec rake test` to record new cassettes
+- Anonymize all sensitive data in cassettes before committing
+
+## Code Style
+
+- Follow standard Ruby conventions
+- Use YARD documentation for all public methods
+- Keep methods focused and single-purpose
+- Error handling uses custom error classes inheriting from `Umami::Error`

data/README.md

@@ -1,8 +1,11 @@
-# Umami Ruby
+# 📊 `umami-ruby` – Ruby client for the Umami Analytics API
 
-[![Gem Version](https://badge.fury.io/rb/umami-ruby.svg)](https://badge.fury.io/rb/umami-ruby)
+[![Gem Version](https://badge.fury.io/rb/umami-ruby.svg)](https://badge.fury.io/rb/umami-ruby) [![Build Status](https://github.com/rameerez/umami-ruby/workflows/Tests/badge.svg)](https://github.com/rameerez/umami-ruby/actions)
 
-A Ruby wrapper for the Umami analytics API.
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=umami-ruby)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=umami-ruby)!
+
+`umami-ruby` is a comprehensive Ruby wrapper for the [Umami Analytics API](https://umami.is/docs/api). Works with both Umami Cloud and self-hosted instances.
 
 ## Installation
 
@@ -33,79 +36,447 @@ yard doc
 yard server
 ```
 
-## Usage
-
-### Configuration
+## Configuration
 
 You can put this config in a handy location within your Rails project, like `config/initializers/umami.rb`
 
-#### For self-hosted Umami instances:
+### For Umami Cloud
 
 ```ruby
-# With username and password
 Umami.configure do |config|
-  config.uri_base = "https://your-umami-instance.com"
-  config.credentials = {
-    username: "your_username",
-    password: "your_password"
-  }
+  config.access_token = "your_api_key"
+  # No need to specify uri_base - automatically uses https://api.umami.is
 end
+```
+
+### For Self-Hosted Umami Instances
 
-# Or with an access token
+```ruby
+# With an access token
 Umami.configure do |config|
   config.uri_base = "https://your-umami-instance.com"
   config.access_token = "your_access_token"
 end
+
+# Or with username and password
+Umami.configure do |config|
+  config.uri_base = "https://your-umami-instance.com"
+  config.credentials = {
+    username: "your_username",
+    password: "your_password"
+  }
+end
 ```
 
-#### For Umami Cloud:
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `access_token` | API key for Umami Cloud or access token for self-hosted | `nil` |
+| `uri_base` | Base URL for self-hosted instances | Auto-detected |
+| `credentials` | Hash with `:username` and `:password` for self-hosted | `nil` |
+| `request_timeout` | Request timeout in seconds | `120` |
 
 ```ruby
+# Example with custom timeout
 Umami.configure do |config|
   config.access_token = "your_api_key"
-  # No need to specify uri_base for Umami Cloud
+  config.request_timeout = 60  # 60 seconds
 end
 ```
 
-### Using the Client
+## Usage
 
-After configuration, you can use the client to interact with the Umami API:
+### Basic Usage
 
 ```ruby
 client = Umami::Client.new
 
+# Get current user info
+me = client.me
+
 # Get all websites
 websites = client.websites
 
 # Get a specific website
 website = client.website("website_id")
 
-# Get website stats
-stats = client.website_stats("website_id", { startAt: 1656679719687, endAt: 1656766119687 })
-
 # Verify token
 token_info = client.verify_token
 ```
 
+### Website Statistics
+
+```ruby
+# Get website stats for a time range (timestamps in milliseconds)
+stats = client.website_stats("website_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687
+})
+
+# Get active visitors (last 5 minutes)
+active = client.website_active_visitors("website_id")
+
+# Get pageviews with time grouping
+pageviews = client.website_pageviews("website_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687,
+  unit: "day",
+  timezone: "America/Los_Angeles"
+})
+
+# Get metrics by type
+metrics = client.website_metrics("website_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687,
+  type: "browser"  # or: path, referrer, os, device, country, etc.
+})
+
+# Get realtime stats (last 30 minutes)
+realtime = client.realtime("website_id")
+```
+
+### Sending Events
+
+Send custom events to Umami for tracking. This is useful for server-side event tracking.
+
+```ruby
+client = Umami::Client.new
+
+# Send a basic event
+client.send_event({
+  website: "your-website-id",
+  url: "/checkout",
+  hostname: "example.com",
+  name: "purchase_completed"
+})
+
+# Send an event with custom data
+client.send_event({
+  website: "your-website-id",
+  url: "/checkout",
+  hostname: "example.com",
+  name: "purchase_completed",
+  language: "en-US",
+  screen: "1920x1080",
+  title: "Checkout - Example Store",
+  data: {
+    order_id: "12345",
+    total: 99.99,
+    currency: "USD"
+  }
+})
+
+# Send with a custom User-Agent (optional)
+client.send_event(payload, user_agent: "MyApp/1.0")
+```
+
+**Important notes about `send_event`:**
+- No authentication token is sent (not required by the API)
+- A `User-Agent` header is automatically included (required by Umami)
+- For Umami Cloud, requests go to `https://cloud.umami.is/api/send` (different from other API calls)
+- For self-hosted, requests go to your configured `uri_base`
+
+### Sessions
+
+```ruby
+# Get sessions within a time range
+sessions = client.website_sessions("website_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687,
+  page: 1,
+  pageSize: 20
+})
+
+# Get session statistics
+stats = client.website_sessions_stats("website_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687
+})
+
+# Get individual session details
+session = client.website_session("website_id", "session_id")
+
+# Get session activity
+activity = client.website_session_activity("website_id", "session_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687
+})
+```
+
+### Events Data
+
+```ruby
+# Get paginated event list with search
+events = client.website_events_list("website_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687,
+  search: "click",
+  page: 1,
+  pageSize: 20
+})
+
+# Get event data aggregations
+event_data = client.website_event_data_events("website_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687
+})
+
+# Get event statistics
+stats = client.website_event_data_stats("website_id", {
+  startAt: 1656679719687,
+  endAt: 1656766119687
+})
+```
+
+### Reports
+
+```ruby
+# List reports (optionally filter by website and/or type)
+all_reports = client.reports
+website_reports = client.reports(websiteId: "website_id")
+funnel_reports = client.reports(websiteId: "website_id", type: "funnel")
+
+# Create a report
+report = client.create_report({
+  websiteId: "website_id",
+  type: "funnel",
+  name: "Checkout Funnel",
+  parameters: {
+    startDate: "2024-01-01T00:00:00Z",
+    endDate: "2024-01-31T23:59:59Z"
+  }
+})
+
+# Run specialized reports
+funnel = client.report_funnel({
+  websiteId: "website_id",
+  startDate: "2024-01-01T00:00:00Z",
+  endDate: "2024-01-31T23:59:59Z",
+  steps: [
+    { type: "path", value: "/" },
+    { type: "path", value: "/checkout" },
+    { type: "path", value: "/thank-you" }
+  ],
+  window: 7
+})
+
+retention = client.report_retention({
+  websiteId: "website_id",
+  startDate: "2024-01-01T00:00:00Z",
+  endDate: "2024-01-31T23:59:59Z",
+  timezone: "America/Los_Angeles"
+})
+
+# Available report types: attribution, breakdown, funnel, goal, journey, retention, revenue, utm
+```
+
+**Report types:**
+| Type | Description |
+|------|-------------|
+| `attribution` | Marketing channel attribution analysis |
+| `breakdown` | Multi-dimensional data segmentation |
+| `funnel` | Conversion funnel tracking |
+| `goal` | Goal performance metrics |
+| `journey` | User navigation path analysis |
+| `retention` | Return visitor analysis |
+| `revenue` | Revenue tracking and analysis |
+| `utm` | UTM campaign parameter breakdown |
+
+### User & Team Management
+
+```ruby
+# Get current user info
+me = client.me
+my_teams = client.my_teams(page: 1, pageSize: 10)
+my_websites = client.my_websites(includeTeams: true)
+
+# Team management
+teams = client.teams
+team = client.team("team_id")
+client.create_team("My Team")
+client.add_team_user("team_id", "user_id", "team-member")
+
+# User management (admin only, self-hosted)
+users = client.admin_users
+client.create_user("username", "password", "user")
+```
+
+### Website Management
+
+```ruby
+# Create a website
+website = client.create_website({
+  name: "My Website",
+  domain: "example.com",
+  teamId: "optional-team-id"
+})
+
+# Update a website
+client.update_website("website_id", {
+  name: "Updated Name",
+  shareId: "public-share-id"
+})
+
+# Reset website data
+client.reset_website("website_id")
+
+# Delete a website
+client.delete_website("website_id")
+```
+
+## Available Methods
+
+### Authentication
+- `verify_token` - Verify the current authentication token
+
+### Me (Current User)
+- `me` - Get current user information
+- `my_teams(params)` - Get user's teams (supports pagination)
+- `my_websites(params)` - Get user's websites
+
+### Admin (Self-hosted only)
+- `admin_users(params)` - List all users
+- `admin_websites(params)` - List all websites
+- `admin_teams(params)` - List all teams
+
+### Users
+- `create_user(username, password, role, id:)` - Create a user
+- `user(user_id)` - Get user by ID
+- `update_user(user_id, params)` - Update user
+- `delete_user(user_id)` - Delete user
+- `user_websites(user_id, params)` - Get user's websites
+- `user_teams(user_id, params)` - Get user's teams
+
+### Teams
+- `teams(params)` - List all teams
+- `create_team(name)` - Create a team
+- `join_team(access_code)` - Join a team
+- `team(team_id)` - Get team by ID
+- `update_team(team_id, params)` - Update team
+- `delete_team(team_id)` - Delete team
+- `team_users(team_id, params)` - List team members
+- `add_team_user(team_id, user_id, role)` - Add user to team
+- `team_user(team_id, user_id)` - Get team member
+- `update_team_user(team_id, user_id, role)` - Update member role
+- `delete_team_user(team_id, user_id)` - Remove user from team
+- `team_websites(team_id, params)` - List team websites
+
+### Websites
+- `websites(params)` - List all websites
+- `create_website(params)` - Create a website
+- `website(website_id)` - Get website by ID
+- `update_website(website_id, params)` - Update website
+- `delete_website(website_id)` - Delete website
+- `reset_website(website_id)` - Reset website data
+
+### Website Statistics
+- `website_stats(website_id, params)` - Get statistics
+- `website_active_visitors(website_id)` - Get active visitors
+- `website_pageviews(website_id, params)` - Get pageviews
+- `website_events(website_id, params)` - Get events (time-series)
+- `website_events_series(website_id, params)` - Get events series
+- `website_metrics(website_id, params)` - Get metrics
+- `website_metrics_expanded(website_id, params)` - Get expanded metrics
+
+### Sessions
+- `website_sessions(website_id, params)` - List sessions
+- `website_sessions_stats(website_id, params)` - Get session stats
+- `website_sessions_weekly(website_id, params)` - Get weekly breakdown
+- `website_session(website_id, session_id)` - Get session details
+- `website_session_activity(website_id, session_id, params)` - Get activity
+- `website_session_properties(website_id, session_id)` - Get properties
+- `website_session_data_properties(website_id, params)` - Get data properties
+- `website_session_data_values(website_id, params)` - Get data values
+
+### Events
+- `website_events_list(website_id, params)` - List events (paginated)
+- `website_event_data(website_id, event_id)` - Get event data
+- `website_event_data_events(website_id, params)` - Get event aggregations
+- `website_event_data_fields(website_id, params)` - Get event fields
+- `website_event_data_properties(website_id, params)` - Get event properties
+- `website_event_data_values(website_id, params)` - Get event values
+- `website_event_data_stats(website_id, params)` - Get event statistics
+
+### Realtime
+- `realtime(website_id)` - Get realtime stats (last 30 minutes)
+
+### Links
+- `links(params)` - List all links
+- `link(link_id)` - Get link by ID
+- `update_link(link_id, params)` - Update link
+- `delete_link(link_id)` - Delete link
+
+### Pixels
+- `pixels(params)` - List all pixels
+- `pixel(pixel_id)` - Get pixel by ID
+- `update_pixel(pixel_id, params)` - Update pixel
+- `delete_pixel(pixel_id)` - Delete pixel
+
+### Reports
+- `reports(params)` - List all reports (filter by `websiteId`, `type`)
+- `create_report(params)` - Create a report
+- `report(report_id)` - Get report by ID
+- `update_report(report_id, params)` - Update report
+- `delete_report(report_id)` - Delete report
+- `report_attribution(params)` - Run attribution report
+- `report_breakdown(params)` - Run breakdown report
+- `report_funnel(params)` - Run funnel report
+- `report_goals(params)` - Run goals report
+- `report_journey(params)` - Run journey report
+- `report_retention(params)` - Run retention report
+- `report_revenue(params)` - Run revenue report
+- `report_utm(params)` - Run UTM report
+
+### Sending Events
+- `send_event(payload, user_agent:)` - Send tracking event
+
 ## Error Handling
 
 The gem defines several custom error classes:
 
-- `Umami::ConfigurationError`: Raised for configuration-related issues.
-- `Umami::AuthenticationError`: Raised for authentication-related issues.
-- `Umami::APIError`: Raised for API request failures.
+```ruby
+begin
+  client.website("non-existent-id")
+rescue Umami::NotFoundError => e
+  puts "Website not found: #{e.message}"
+rescue Umami::AuthenticationError => e
+  puts "Authentication failed: #{e.message}" # rejected login, expired/revoked token (401), forbidden (403)
+rescue Umami::ClientError => e
+  puts "Client error: #{e.message}"
+rescue Umami::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Umami::ConfigurationError => e
+  puts "Configuration error: #{e.message}"
+rescue Umami::APIError => e
+  puts "API error: #{e.message}"
+end
+```
+
+**Error class hierarchy:**
+- `Umami::Error` - Base error class
+  - `Umami::ConfigurationError` - Configuration issues
+  - `Umami::APIError` - API request failures
+    - `Umami::AuthenticationError` - Authentication failures: rejected logins, and HTTP 401/403 API responses (since 0.3.0 — an expired token on a long-lived client surfaces here so you can re-authenticate)
+    - `Umami::NotFoundError` - Resource not found (404)
+    - `Umami::ClientError` - Other client errors (4xx)
+    - `Umami::ServerError` - Server errors (5xx)
 
 ## Logging
 
 The gem uses a logger that can be configured:
 
 ```ruby
+# Set log level
 Umami.logger.level = Logger::DEBUG
+
+# Use a custom logger
+Umami.logger = Rails.logger
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.