umami-ruby 0.1.3 → 0.3.0

data/lib/umami/configuration.rb

@@ -1,9 +1,51 @@
 module Umami
+  # Configuration class for the Umami client.
+  #
+  # @example Configure for Umami Cloud
+  #   Umami.configure do |config|
+  #     config.access_token = "your_api_key"
+  #   end
+  #
+  # @example Configure for self-hosted with access token
+  #   Umami.configure do |config|
+  #     config.uri_base = "https://your-umami-instance.com"
+  #     config.access_token = "your_access_token"
+  #   end
+  #
+  # @example Configure for self-hosted with credentials
+  #   Umami.configure do |config|
+  #     config.uri_base = "https://your-umami-instance.com"
+  #     config.credentials = { username: "user", password: "pass" }
+  #   end
+  #
+  # @example Configure with custom timeout
+  #   Umami.configure do |config|
+  #     config.access_token = "your_api_key"
+  #     config.request_timeout = 60  # 60 seconds instead of default 120
+  #   end
   class Configuration
+    # Base URL for Umami Cloud API (used for most API calls)
+    # @return [String]
     UMAMI_CLOUD_URL = "https://api.umami.is".freeze
 
+    # Base URL for Umami Cloud send endpoint (used only for send_event)
+    # @note The send endpoint uses a different base URL than other API calls
+    # @return [String]
+    UMAMI_CLOUD_SEND_URL = "https://cloud.umami.is".freeze
+
+    # @!attribute [rw] uri_base
+    #   @return [String, nil] Base URL for the Umami API
+    # @!attribute [rw] request_timeout
+    #   @return [Integer] Request timeout in seconds (default: 120)
+    # @!attribute [rw] access_token
+    #   @return [String, nil] Access token for API authentication
+    # @!attribute [r] username
+    #   @return [String, nil] Username for self-hosted authentication (set via credentials=)
+    # @!attribute [r] password
+    #   @return [String, nil] Password for self-hosted authentication (set via credentials=)
     attr_reader :uri_base, :request_timeout, :access_token, :username, :password
 
+    # Initialize a new Configuration with default values
     def initialize
       @uri_base = nil
       @request_timeout = 120
@@ -13,11 +55,16 @@ module Umami
       @dirty = false
     end
 
+    # Set the base URI for the Umami API
+    # @param url [String] The base URL (trailing slash will be removed)
     def uri_base=(url)
       @uri_base = url&.chomp('/')
       @dirty = true
     end
 
+    # Set the access token for API authentication
+    # @note Setting an access token clears any username/password credentials
+    # @param token [String] The access token
     def access_token=(token)
       @access_token = token
       @username = nil
@@ -25,6 +72,10 @@ module Umami
       @dirty = true
     end
 
+    # Set username/password credentials for self-hosted authentication
+    # @note Setting credentials clears any access token
+    # @param creds [Hash] Credentials hash with :username and :password keys
+    # @raise [Umami::ConfigurationError] if username or password is missing
     def credentials=(creds)
       raise Umami::ConfigurationError, "Both username and password are required" unless creds[:username] && creds[:password]
 
@@ -34,10 +85,21 @@ module Umami
       @dirty = true
     end
 
+    # Set the request timeout in seconds
+    # @param timeout [Integer] Timeout in seconds
+    def request_timeout=(timeout)
+      @request_timeout = timeout
+      @dirty = true
+    end
+
+    # Check if configured for Umami Cloud
+    # @return [Boolean] true if using Umami Cloud (access token without custom URI)
     def cloud?
       @access_token && @uri_base.nil?
     end
 
+    # Validate the configuration and apply defaults
+    # @raise [Umami::ConfigurationError] if configuration is invalid
     def validate!
       return unless @dirty
 

data/lib/umami/errors.rb

@@ -5,12 +5,19 @@ module Umami
   # Error raised when there's a configuration issue
   class ConfigurationError < Error; end
 
-  # Error raised when authentication fails
-  class AuthenticationError < Error; end
-
   # Base error class for API-related errors
   class APIError < Error; end
 
+  # Error raised when authentication fails — a rejected login, a login
+  # response without a token, or an API request answered 401/403 (an
+  # expired or revoked token on a long-lived client, insufficient
+  # permissions). Deliberately a subclass of APIError since 0.2.1:
+  # before that, HTTP 401/403 surfaced as ClientError, so callers who
+  # `rescue Umami::APIError` were already catching them — subclassing
+  # APIError keeps those rescues working while giving auth failures
+  # their own class to match on.
+  class AuthenticationError < APIError; end
+
   # Error raised when a resource is not found
   class NotFoundError < APIError; end
 

data/lib/umami/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Umami
-  VERSION = "0.1.3"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: umami-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-25 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,62 +23,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: redcarpet
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: A simple and efficient Ruby gem to interact with the Umami analytics
   API
 email:
@@ -88,11 +31,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".env.test"
+- ".simplecov"
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- context7.json
 - docs/Umami.html
 - docs/Umami/APIError.html
 - docs/Umami/AuthenticationError.html
@@ -136,7 +83,6 @@ metadata:
   source_code_uri: https://github.com/rameerez/umami-ruby
   changelog_uri: https://github.com/rameerez/umami-ruby/blob/main/CHANGELOG.md
   documentation_uri: https://rameerez.github.io/umami-ruby/
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -151,8 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Ruby wrapper for the Umami API
 test_files: []