umami-ruby 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8123faece9209e2ead6415c0e396a32853aa69ade5a11af2481c311a6e333e81
-  data.tar.gz: ad58c5c87d2e27e92e90b7210a7443e589e4879ab9f9f247648b8c43f6af4a99
+  metadata.gz: 24515824a954d2c9b334b0445ef3a64f2faf79bb9fd0ec26657b702f0e170951
+  data.tar.gz: 2eec535b5aa02bf528b05a7d767d843b5781d8d970d03d7070953fc604582904
 SHA512:
-  metadata.gz: 5cf0256f92097a0b2374205d727f1deb7f20d3dce31ade6783001023cd7512e76b3b4f65c41dc33166a340d4ae2e1dab60fef3f2043860fec9e3a98c1d1c7d3b
-  data.tar.gz: 6f9905fc18ac2200c003d620d5f0f2caac972436b43c9b2756fee76547b7a92ced1358662d5a25300c1d41c3a42a2e847c4bca58d5eed727d57fc90eca1de236
+  metadata.gz: 53784a10bf0025c49791ace32354800ac39bdb7e662234a7f81f78f50538234aec5c32fda101bd7d844bd3df5eaf8a94e6002d85037729db637b8ff818e2d55f
+  data.tar.gz: 84cb4db13dd978dfb0ac65982081fe3a1a23b8e0b3f755c7cfc0c920e53c32d16861630b5a17c43059882c43222ce62f4e6aed1ff1b599d4da2e92bd56e56375

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [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

data/README.md

@@ -440,12 +440,12 @@ 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::AuthenticationError => e
-  puts "Authentication failed: #{e.message}"
 rescue Umami::ConfigurationError => e
   puts "Configuration error: #{e.message}"
 rescue Umami::APIError => e
@@ -456,10 +456,10 @@ end
 **Error class hierarchy:**
 - `Umami::Error` - Base error class
   - `Umami::ConfigurationError` - Configuration issues
-  - `Umami::AuthenticationError` - Authentication failures
   - `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` - Client errors (4xx)
+    - `Umami::ClientError` - Other client errors (4xx)
     - `Umami::ServerError` - Server errors (5xx)
 
 ## Logging

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/umami-ruby",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/lib/umami/client.rb

@@ -72,6 +72,25 @@ module Umami
 
       data = JSON.parse(response.body)
       @access_token = data["token"]
+
+      # Umami answers a successful login with { "token": ..., "user": ... }
+      # (https://umami.is/docs/api/authentication#post-/api/auth/login).
+      # A 200 without a token would otherwise produce a client that fails
+      # every request with an opaque 401 — fail loudly at the source.
+      if @access_token.nil? || @access_token.empty?
+        raise Umami::AuthenticationError, "Authentication succeeded but the response carried no token"
+      end
+
+      # ⚠️ Load-bearing reset. The login POST above just memoized
+      # `@connection` — necessarily WITHOUT an Authorization header, since
+      # `@access_token` was still nil when the connection was built, and
+      # Faraday bakes headers into the connection at build time. Dropping
+      # the memo forces the next request to rebuild the connection, this
+      # time with the Bearer token (see #connection). Without this reset,
+      # every request after a username/password login fails with 401 —
+      # the exact bug shipped in <= 0.2.0 (why token-based auth was the
+      # only flow that worked against self-hosted instances).
+      @connection = nil
     rescue Faraday::Error, JSON::ParserError => e
       raise Umami::AuthenticationError, "Authentication failed: #{e.message}"
     end
@@ -1298,6 +1317,12 @@ module Umami
       handle_error(e)
     end
 
+    # Memoized so keep-alive and middleware setup are paid once, BUT the
+    # Authorization header is baked in at build time — Faraday connections
+    # don't re-read `@access_token` afterwards. Anything that changes the
+    # token MUST set `@connection = nil` so the next request rebuilds with
+    # the fresh header (see #authenticate, where forgetting exactly that
+    # was the <= 0.2.0 username/password bug).
     def connection
       @connection ||= Faraday.new(url: uri_base) do |faraday|
         faraday.request :json
@@ -1308,8 +1333,17 @@ module Umami
       end
     end
 
+    # Order matters: Faraday::UnauthorizedError (401) and ForbiddenError
+    # (403) are SUBCLASSES of Faraday::ClientError
+    # (https://lostisland.github.io/faraday/#/middleware/included/raising-errors),
+    # so they must be matched before the generic 4xx case or they'd
+    # surface as an undifferentiated ClientError. Raising
+    # AuthenticationError instead gives callers a re-authentication signal
+    # (e.g. an expired or revoked token on a long-lived client).
     def handle_error(error)
       case error
+      when Faraday::UnauthorizedError, Faraday::ForbiddenError
+        raise Umami::AuthenticationError, "Authentication failed: #{error.message}"
       when Faraday::ResourceNotFound
         raise Umami::NotFoundError, "Resource not found: #{error.message}"
       when Faraday::ClientError

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.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: umami-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-03 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -39,6 +39,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- context7.json
 - docs/Umami.html
 - docs/Umami/APIError.html
 - docs/Umami/AuthenticationError.html