📊 umami-ruby – Ruby client for the Umami Analytics API

gem 'umami-ruby'

Umami.configure do |config|
  config.access_token = "your_api_key"
  # No need to specify uri_base - automatically uses https://api.umami.is
end

# 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

# Example with custom timeout
Umami.configure do |config|
  config.access_token = "your_api_key"
  config.request_timeout = 60  # 60 seconds
end

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")

# Verify token
token_info = client.verify_token

# 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")

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")

# 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
})

# 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
})

# 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

# 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")

# 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")

begin
  client.website("non-existent-id")
rescue Umami::NotFoundError => e
  puts "Website not found: #{e.message}"
rescue Umami::ClientError => e
  puts "Client error: #{e.message}"
rescue Umami::ServerError => e
  puts "Server error: #{e.message}"
rescue Umami::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue Umami::ConfigurationError => e
  puts "Configuration error: #{e.message}"
rescue Umami::APIError => e
  puts "API error: #{e.message}"
end

# Set log level
Umami.logger.level = Logger::DEBUG

# Use a custom logger
Umami.logger = Rails.logger