umami-ruby 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8123faece9209e2ead6415c0e396a32853aa69ade5a11af2481c311a6e333e81
-  data.tar.gz: ad58c5c87d2e27e92e90b7210a7443e589e4879ab9f9f247648b8c43f6af4a99
+  metadata.gz: adc8943170e57c2126ffddff58f399b17ff3cb6f0736b293a75fd32c1f1fe6c7
+  data.tar.gz: 8a5477ecfeaca6b2cb2857c3b715fa4d32b01ad953b2dd640385d7344c526e0f
 SHA512:
-  metadata.gz: 5cf0256f92097a0b2374205d727f1deb7f20d3dce31ade6783001023cd7512e76b3b4f65c41dc33166a340d4ae2e1dab60fef3f2043860fec9e3a98c1d1c7d3b
-  data.tar.gz: 6f9905fc18ac2200c003d620d5f0f2caac972436b43c9b2756fee76547b7a92ced1358662d5a25300c1d41c3a42a2e847c4bca58d5eed727d57fc90eca1de236
+  metadata.gz: ae319a33a3471d8688dfc36444eca87130c1c49fac89694f99377e91b5823454592164b18667cb06bc58fe43e2373040fa061772e79057ba02f76d9132bcd9e3
+  data.tar.gz: 87991d5621f16af9db3ae88e29a1b9b2d003c579418e1b92fca9054800aaea7f1ddacc7cc4c4922388dff0de8a0df9f0b8e6f429fbe81704604bd93351b3f5fc

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [0.4.0] - 2026-11-06
+
+### Added
+
+- `website_pageviews_over_range`: pageviews and sessions over a range of any length, keeping the unit you asked for. Umami silently answers `unit: "day"` in months once a range spans more than 7 calendar months (and `unit: "hour"` in days past 30 days), so a year of daily points came back as twelve monthly ones. The new method splits the range into requests short enough for the unit (90 days for `day`, 30 for `hour`) and joins the results.
+
+### Documentation
+
+- README: "Two traps in the Umami API". List endpoints return 20 items unless you pass `pageSize`, and long ranges come back in coarser units than requested. The basic-usage example now passes `pageSize`.
+
+## [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

@@ -95,8 +95,8 @@ client = Umami::Client.new
 # Get current user info
 me = client.me
 
-# Get all websites
-websites = client.websites
+# Get your websites (first page only: Umami pages lists at 20, see below)
+websites = client.websites(pageSize: 200)
 
 # Get a specific website
 website = client.website("website_id")
@@ -125,6 +125,14 @@ pageviews = client.website_pageviews("website_id", {
   timezone: "America/Los_Angeles"
 })
 
+# Pageviews over a range of any length, keeping daily points (see below)
+year = client.website_pageviews_over_range("website_id", {
+  startAt: Time.utc(2025, 11, 1).to_i * 1000,
+  endAt: Time.utc(2026, 11, 1).to_i * 1000 - 1,
+  unit: "day",
+  timezone: "UTC"
+})
+
 # Get metrics by type
 metrics = client.website_metrics("website_id", {
   startAt: 1656679719687,
@@ -325,6 +333,34 @@ client.reset_website("website_id")
 client.delete_website("website_id")
 ```
 
+### Two traps in the Umami API
+
+Both fail silently: you get a normal-looking answer with data missing.
+
+**Lists stop at 20 items.** Every list endpoint (`websites`, `my_websites`,
+`team_websites`, `admin_websites`, users, teams, reports, ...) returns one page
+of 20 unless you ask for more. With 32 sites, `client.websites` returns 20, and
+the other 12 look like they don't exist. Pass `pageSize`, and compare the
+response's `count` with the items you got:
+
+```ruby
+response = client.websites(pageSize: 200)
+response["data"].size == response["count"] # otherwise, fetch the next page
+```
+
+**Long ranges come back in coarser units than you asked for.** If a range is
+too long for the requested `unit`, the server switches to a coarser one and
+says nothing. On Umami 3.x, `unit: "day"` turns into monthly points once the
+range spans more than 7 calendar months, and `unit: "hour"` turns into daily
+points past 30 days (`getMinimumUnit` in Umami's `src/lib/date.ts`). A year of
+`unit: "day"` from `website_pageviews` is twelve monthly points, and code that
+reads them as days puts a month's total on one day.
+
+`website_pageviews_over_range` takes the same params as `website_pageviews`,
+splits a long range into requests short enough for the unit (90 days for
+`day`, 30 for `hour`), and joins the results. Start `startAt` at midnight in
+the `timezone` you pass, so no day is split across two requests.
+
 ## Available Methods
 
 ### Authentication
@@ -374,6 +410,7 @@ client.delete_website("website_id")
 - `website_stats(website_id, params)` - Get statistics
 - `website_active_visitors(website_id)` - Get active visitors
 - `website_pageviews(website_id, params)` - Get pageviews
+- `website_pageviews_over_range(website_id, params)` - Get pageviews over a range of any length, keeping the requested unit
 - `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
@@ -440,12 +477,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 +493,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
@@ -494,6 +513,59 @@ module Umami
       get("/api/websites/#{website_id}/pageviews", params)
     end
 
+    # Longest range, in days, that one pageviews request can cover and still
+    # get the unit it asked for. Umami silently picks a coarser unit when the
+    # range is too long for the one requested: 3.x answers `unit: "day"` in
+    # months once the range spans more than 7 calendar months, and
+    # `unit: "hour"` in days past 30 days (src/lib/date.ts, getMinimumUnit).
+    # These limits leave room for older servers too.
+    PAGEVIEWS_DAYS_PER_REQUEST = { "hour" => 30, "day" => 90 }.freeze
+
+    # Get pageviews and sessions over a range of any length, keeping the unit
+    # you asked for
+    #
+    # Takes the same params as {#website_pageviews}. A range longer than one
+    # request can hold for that unit (see PAGEVIEWS_DAYS_PER_REQUEST) is split
+    # into consecutive requests, and their series are joined. Without this,
+    # a year of `unit: "day"` comes back as twelve monthly points, with no
+    # error.
+    #
+    # Start `startAt` at midnight (or on the hour) in the `timezone` you pass,
+    # so no bucket is split across two requests. If one is, its counts are
+    # added together, which can count a visitor twice in "sessions".
+    #
+    # @param website_id [String] The website's ID
+    # @param params [Hash] Same as {#website_pageviews}; :startAt, :endAt and :unit are required
+    # @return [Hash] "pageviews" and "sessions" arrays of { "x" => bucket, "y" => count }, in order
+    # @example A year of daily visitors
+    #   client.website_pageviews_over_range(website_id,
+    #     startAt: Time.utc(2025, 11, 1).to_i * 1000,
+    #     endAt: Time.utc(2026, 11, 1).to_i * 1000 - 1,
+    #     unit: "day", timezone: "UTC")
+    def website_pageviews_over_range(website_id, params = {})
+      params = params.transform_keys(&:to_sym)
+      days = PAGEVIEWS_DAYS_PER_REQUEST[params[:unit].to_s]
+      return website_pageviews(website_id, params) unless days
+
+      start_at, end_at = Integer(params.fetch(:startAt)), Integer(params.fetch(:endAt))
+      step = days * 24 * 60 * 60 * 1000
+      series = Hash.new { |hash, key| hash[key] = {} }
+
+      start_at.step(end_at, step) do |from|
+        response = website_pageviews(website_id, params.merge(startAt: from, endAt: [from + step - 1, end_at].min))
+
+        %w[pageviews sessions].each do |key|
+          Array(response[key]).each do |point|
+            series[key][point["x"]] = series[key].fetch(point["x"], 0) + point["y"].to_i
+          end
+        end
+      end
+
+      %w[pageviews sessions].to_h do |key|
+        [key, series[key].map { |x, y| { "x" => x, "y" => y } }]
+      end
+    end
+
     # Get website events within a time range
     #
     # This method returns event data with optional time-series grouping.
@@ -1298,6 +1370,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 +1386,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.4.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.4.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-03 00:00:00.000000000 Z
+date: 2026-11-06 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