umami-ruby 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24515824a954d2c9b334b0445ef3a64f2faf79bb9fd0ec26657b702f0e170951
-  data.tar.gz: 2eec535b5aa02bf528b05a7d767d843b5781d8d970d03d7070953fc604582904
+  metadata.gz: adc8943170e57c2126ffddff58f399b17ff3cb6f0736b293a75fd32c1f1fe6c7
+  data.tar.gz: 8a5477ecfeaca6b2cb2857c3b715fa4d32b01ad953b2dd640385d7344c526e0f
 SHA512:
-  metadata.gz: 53784a10bf0025c49791ace32354800ac39bdb7e662234a7f81f78f50538234aec5c32fda101bd7d844bd3df5eaf8a94e6002d85037729db637b8ff818e2d55f
-  data.tar.gz: 84cb4db13dd978dfb0ac65982081fe3a1a23b8e0b3f755c7cfc0c920e53c32d16861630b5a17c43059882c43222ce62f4e6aed1ff1b599d4da2e92bd56e56375
+  metadata.gz: ae319a33a3471d8688dfc36444eca87130c1c49fac89694f99377e91b5823454592164b18667cb06bc58fe43e2373040fa061772e79057ba02f76d9132bcd9e3
+  data.tar.gz: 87991d5621f16af9db3ae88e29a1b9b2d003c579418e1b92fca9054800aaea7f1ddacc7cc4c4922388dff0de8a0df9f0b8e6f429fbe81704604bd93351b3f5fc

data/CHANGELOG.md

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

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

data/lib/umami/client.rb

@@ -513,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.

data/lib/umami/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Umami
-  VERSION = "0.3.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.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday