gerodp/hermes-productivity-skills / analytics/umami-report
umami-report
VerifiedPer-site visitor & pageview reports from a private (self-hosted) Umami instance.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
| scripts/test_umami_report.pyexecutable | script | 13.6 KB |
| scripts/umami_report.pyexecutable | script | 16.7 KB |
scripts/umami_report.py
View on GitHub#!/usr/bin/env python3
"""umami-report — per-site visitor & pageview reports from a private Umami instance.
Credentials are read from environment variables (Hermes injects these from
~/.hermes/.env into the sandbox — never paste them into chat):
UMAMI_URL e.g. https://analytics.example.com
UMAMI_USERNAME Umami login username
UMAMI_PASSWORD Umami login password
Subcommands:
check Verify config + that login works (prints no secrets).
report Per-site visit report (default when no subcommand is given).
Python standard library only — no third-party dependencies, so runs fast and
deterministically in the Hermes terminal sandbox.
"""
from __future__ import annotations
import argparse
import json
import os
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
from concurrent.futures import ThreadPoolExecutor
from datetime import datetime, timezone
DAY_MS = 86_400_000
ENV_VARS = ("UMAMI_URL", "UMAMI_USERNAME", "UMAMI_PASSWORD")
STAT_KEYS = ("pageviews", "visitors", "visits", "bounces", "totaltime")
HTTP_TIMEOUT = 30
MAX_WORKERS = 8
class UmamiError(Exception):
"""User-facing error — message is safe to print (never contains secrets)."""
# --------------------------------------------------------------------------- #
# Pure helpers (unit-tested, no network)
# --------------------------------------------------------------------------- #
# NOTE: intentional variant of the shared window vocabulary — this one works in
# UTC epoch-ms (Umami's API is UTC), so it is deliberately excluded from the
# repo-level sync check in test_shared_window_vocab.py. Don't "align" it.
def compute_range(now_ms, *, days=None, since=None, start=None, end=None):
"""Return (start_ms, end_ms) for the requested window.
Precedence: explicit start/end > since > days. Defaults to the last 7 days.
Dates are interpreted in UTC for deterministic, timezone-independent output.
"""
if start or end:
if not (start and end):
raise UmamiError("--start and --end must be given together")
s = _date_to_ms(start)
e = _date_to_ms(end) + DAY_MS - 1 # inclusive end-of-day
if e < s:
raise UmamiError("--end is before --start")
return s, e
if since:
if since == "today":
return _start_of_day_ms(now_ms), now_ms
spans = {"7d": 7, "30d": 30}
if since not in spans:
raise UmamiError(f"unknown --since value: {since}")
return now_ms - spans[since] * DAY_MS, now_ms
n = 7 if days is None else days
if n < 0:
raise UmamiError("--days must be >= 0")
if n == 0:
return _start_of_day_ms(now_ms), now_ms
return now_ms - n * DAY_MS, now_ms
def _date_to_ms(date_str):
try:
dt = datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=timezone.utc)
except ValueError:
raise UmamiError(f"invalid date (use YYYY-MM-DD): {date_str}")
return int(dt.timestamp() * 1000)
def _start_of_day_ms(now_ms):
dt = datetime.fromtimestamp(now_ms / 1000, tz=timezone.utc)
sod = dt.replace(hour=0, minute=0, second=0, microsecond=0)
return int(sod.timestamp() * 1000)
def yesterday_range(now_ms):
"""(start_ms, end_ms) covering all of yesterday (UTC, inclusive end-of-day)."""
start_today = _start_of_day_ms(now_ms)
return start_today - DAY_MS, start_today - 1
def fmt_date(ms):
return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).strftime("%Y-%m-%d")
def parse_stats(payload):
"""Normalize a /stats response into (current, previous) flat int dicts.
Handles both Umami response shapes:
* newer: {"visitors": 10, ..., "comparison": {"visitors": 8, ...}}
* older: {"visitors": {"value": 10, "prev": 8}, ...}
"""
comparison = payload.get("comparison") or {}
current, previous = {}, {}
for k in STAT_KEYS:
raw = payload.get(k, 0)
if isinstance(raw, dict): # older {value, prev} shape
current[k] = _to_int(raw.get("value"))
previous[k] = _to_int(raw.get("prev"))
else:
current[k] = _to_int(raw)
previous[k] = _to_int(comparison.get(k))
return current, previous
def normalize_websites(payload):
"""Extract [{id, name, domain}, ...] from a /websites response (any shape)."""
if isinstance(payload, dict):
data = payload.get("data")
if data is None:
data = payload.get("websites", [])
else:
data = payload
sites = []
for w in data:
# team-website rows sometimes wrap the site under "website"
if isinstance(w.get("website"), dict):
w = {**w, **w["website"]}
wid = w.get("id") or w.get("websiteId")
if not wid:
continue
sites.append({
"id": wid,
"name": w.get("name") or w.get("domain") or str(wid),
"domain": w.get("domain") or "",
})
return sites
def normalize_teams(payload):
"""Extract team ids from a /users/:id/teams response (any shape)."""
if isinstance(payload, dict):
data = payload.get("data") or payload.get("teams") or []
else:
data = payload
ids = []
for t in data:
if isinstance(t.get("team"), dict):
t = {**t, **t["team"]}
tid = t.get("id") or t.get("teamId")
if tid:
ids.append(tid)
return ids
def merge_websites(*site_lists):
"""Merge several website lists, de-duplicating by id, preserving order."""
seen, merged = set(), []
for sites in site_lists:
for s in sites:
if s["id"] not in seen:
seen.add(s["id"])
merged.append(s)
return merged
def _to_int(v):
try:
return int(v or 0)
except (TypeError, ValueError):
return 0
def bounce_pct(bounces, visits):
return round(100.0 * bounces / visits, 1) if visits else 0.0
def avg_duration(totaltime, visits):
"""Average visit duration in **seconds** (totaltime is total seconds)."""
return round(totaltime / visits) if visits else 0
def fmt_num(n):
"""Plain integer with thousands separators."""
return f"{n:,}"
def format_delta(current, previous):
"""'1234 ▲12.5%' / '12 ▼3.0%' / '0 —' / '5 ▲new' — period-over-period."""
if previous == 0:
return f"{current:,} —" if current == 0 else f"{current:,} ▲new"
pct = 100.0 * (current - previous) / previous
arrow = "▲" if pct > 0 else "▼" if pct < 0 else "—"
return f"{current:,} {arrow}{abs(pct):.1f}%"
def build_rows(sites_stats):
"""sites_stats: list of (site, current, previous, yesterday_visitors).
Returns display rows sorted by pageviews descending.
"""
rows = []
for site, cur, prev, yest_visitors in sites_stats:
rows.append({
"id": site.get("id"),
"name": site["name"],
"domain": site["domain"],
"yesterday": yest_visitors,
"visitors": cur["visitors"], "visitors_prev": prev["visitors"],
"visits": cur["visits"], "visits_prev": prev["visits"],
"pageviews": cur["pageviews"], "pageviews_prev": prev["pageviews"],
"bounces": cur["bounces"],
"bounce": bounce_pct(cur["bounces"], cur["visits"]),
"totaltime": cur["totaltime"],
"avg_duration": avg_duration(cur["totaltime"], cur["visits"]),
"avg_duration_prev": avg_duration(prev["totaltime"], prev["visits"]),
})
rows.sort(key=lambda r: (r["pageviews"], r["visitors"]), reverse=True)
return rows
def render_table(rows, start_ms, end_ms):
headers = ["Site", "Yesterday", "Visitors", "Visits", "Pageviews", "Bounce%"]
body = []
for r in rows:
body.append([
r["name"],
fmt_num(r["yesterday"]),
format_delta(r["visitors"], r["visitors_prev"]),
fmt_num(r["visits"]),
fmt_num(r["pageviews"]),
f'{r["bounce"]:.1f}',
])
if rows:
tv = sum(r["visitors"] for r in rows)
ts = sum(r["visits"] for r in rows)
tp = sum(r["pageviews"] for r in rows)
tb = sum(r["bounces"] for r in rows)
body.append([
"TOTAL",
fmt_num(sum(r["yesterday"] for r in rows)),
format_delta(tv, sum(r["visitors_prev"] for r in rows)),
fmt_num(ts),
fmt_num(tp),
f"{bounce_pct(tb, ts):.1f}",
])
widths = [len(h) for h in headers]
for row in body:
for i, cell in enumerate(row):
widths[i] = max(widths[i], len(cell))
def line(cells):
out = [cells[0].ljust(widths[0])]
out += [cells[i].rjust(widths[i]) for i in range(1, len(cells))]
return " ".join(out)
title = (f"Umami visits {fmt_date(start_ms)} → {fmt_date(end_ms)}"
" (Visitors Δ vs previous period; Yesterday = visitors yesterday)")
sep = "-" * (sum(widths) + 2 * (len(widths) - 1))
lines = [title, "", line(headers), sep]
for row in body[: len(rows)]:
lines.append(line(row))
if rows:
lines.append(sep)
lines.append(line(body[-1])) # TOTAL
else:
lines.append("(no websites found)")
return "\n".join(lines)
def render_json(rows, start_ms, end_ms):
return json.dumps({
"range": {
"startAt": start_ms, "endAt": end_ms,
"start": fmt_date(start_ms), "end": fmt_date(end_ms),
},
"sites": [{
"site_id": r.get("id"),
"name": r["name"], "domain": r["domain"],
"yesterday_visitors": r["yesterday"],
"visitors": r["visitors"], "visitors_prev": r["visitors_prev"],
"visits": r["visits"], "visits_prev": r["visits_prev"],
"pageviews": r["pageviews"], "pageviews_prev": r["pageviews_prev"],
"bounces": r["bounces"], "bounce_pct": r["bounce"],
"avg_duration": r["avg_duration"], "avg_duration_prev": r["avg_duration_prev"],
} for r in rows],
}, indent=2, sort_keys=True)
# --------------------------------------------------------------------------- #
# Config + HTTP (network)
# --------------------------------------------------------------------------- #
def get_config(env=None):
env = os.environ if env is None else env
missing = [v for v in ENV_VARS if not env.get(v)]
if missing:
raise UmamiError(
"missing environment variable(s): " + ", ".join(missing)
+ " — set them in ~/.hermes/.env (see SKILL.md). "
"Do not paste secrets into chat."
)
base = env["UMAMI_URL"].rstrip("/")
if not base.startswith(("http://", "https://")):
raise UmamiError("UMAMI_URL must start with http:// or https://")
if base.startswith("http://") and not _is_localhost(base):
raise UmamiError(
"UMAMI_URL uses http:// — the login would send the password in "
"cleartext. Use https:// (http is allowed only for localhost)."
)
return base, env["UMAMI_USERNAME"], env["UMAMI_PASSWORD"]
def _is_localhost(base):
host = urllib.parse.urlsplit(base).hostname or ""
return host == "localhost" or host == "::1" or host.startswith("127.")
def _request(url, *, method="GET", token=None, data=None, timeout=HTTP_TIMEOUT):
headers = {"Accept": "application/json"}
body = None
if data is not None:
body = json.dumps(data).encode()
headers["Content-Type"] = "application/json"
if token:
headers["Authorization"] = f"Bearer {token}"
req = urllib.request.Request(url, data=body, headers=headers, method=method)
try:
with urllib.request.urlopen(req, timeout=timeout) as resp: # TLS verified by default
return json.loads(resp.read().decode())
except urllib.error.HTTPError as e:
raise UmamiError(f"HTTP {e.code} ({e.reason}) from {_safe_url(url)}")
except urllib.error.URLError as e:
raise UmamiError(f"network error reaching {_safe_url(url)}: {e.reason}")
except json.JSONDecodeError:
raise UmamiError(f"non-JSON response from {_safe_url(url)}")
def _safe_url(url):
return url.split("?", 1)[0]
def login(base, username, password):
payload = _request(f"{base}/api/auth/login", method="POST",
data={"username": username, "password": password})
token = payload.get("token")
if not token:
raise UmamiError("login failed: no token returned (check credentials)")
return token, (payload.get("user") or {}).get("id")
def _get_optional(url, token):
"""GET that returns [] instead of raising on 4xx (endpoint may not exist)."""
try:
return _request(url, token=token)
except UmamiError:
return {"data": []}
def list_websites(base, token, user_id=None):
"""All websites the account can see: owned + every team it belongs to."""
owned = normalize_websites(
_request(f"{base}/api/websites?page=1&pageSize=200", token=token))
if not user_id:
return owned
team_sites = []
teams = normalize_teams(
_get_optional(f"{base}/api/users/{user_id}/teams?page=1&pageSize=200", token))
for tid in teams:
team_sites += normalize_websites(
_get_optional(f"{base}/api/teams/{tid}/websites?page=1&pageSize=200", token))
return merge_websites(owned, team_sites)
def fetch_stats(base, token, website_id, start_ms, end_ms):
url = f"{base}/api/websites/{website_id}/stats?startAt={start_ms}&endAt={end_ms}"
return parse_stats(_request(url, token=token))
def gather(base, token, sites, start_ms, end_ms, yest_start, yest_end):
def work(site):
cur, prev = fetch_stats(base, token, site["id"], start_ms, end_ms)
yest, _ = fetch_stats(base, token, site["id"], yest_start, yest_end)
return site, cur, prev, yest["visitors"]
workers = min(MAX_WORKERS, max(1, len(sites)))
with ThreadPoolExecutor(max_workers=workers) as ex:
return list(ex.map(work, sites))
# --------------------------------------------------------------------------- #
# Subcommands
# --------------------------------------------------------------------------- #
def do_check():
base, user, pw = get_config()
token, user_id = login(base, user, pw)
sites = list_websites(base, token, user_id)
print(f"OK — authenticated to {base}; {len(sites)} website(s) visible.")
if not sites:
print("note: this account has access to 0 websites — share a website "
"with it (or add it to a team) in Umami.", file=sys.stderr)
return 0
def do_report(args):
base, user, pw = get_config()
now_ms = int(time.time() * 1000)
start_ms, end_ms = compute_range(
now_ms,
days=getattr(args, "days", None),
since=getattr(args, "since", None),
start=getattr(args, "start", None),
end=getattr(args, "end", None),
)
token, user_id = login(base, user, pw)
sites = list_websites(base, token, user_id)
site_filter = getattr(args, "site", None)
if site_filter:
sf = site_filter.lower()
sites = [s for s in sites
if sf in s["name"].lower() or sf in s["domain"].lower()]
if not sites:
raise UmamiError(f"no website matches --site {site_filter!r}")
yest_start, yest_end = yesterday_range(now_ms)
rows = build_rows(gather(base, token, sites, start_ms, end_ms, yest_start, yest_end))
if getattr(args, "json", False):
print(render_json(rows, start_ms, end_ms))
else:
print(render_table(rows, start_ms, end_ms))
return 0
def build_parser():
p = argparse.ArgumentParser(prog="umami_report",
description="Per-site visit reports from a private Umami instance.")
sub = p.add_subparsers(dest="cmd")
sub.add_parser("check", help="verify config + login (no report)")
rep = sub.add_parser("report", help="per-site visit report (default)")
window = rep.add_mutually_exclusive_group()
window.add_argument("--days", type=int, help="last N days (default 7)")
window.add_argument("--since", choices=["today", "7d", "30d"],
help="preset window")
rep.add_argument("--start", help="explicit start date YYYY-MM-DD (with --end)")
rep.add_argument("--end", help="explicit end date YYYY-MM-DD (with --start)")
rep.add_argument("--site", help="filter to sites matching this name/domain")
rep.add_argument("--json", action="store_true", help="machine-readable output")
return p
def main(argv=None):
args = build_parser().parse_args(argv)
try:
if args.cmd == "check":
return do_check()
return do_report(args) # report is the default
except UmamiError as e:
print(f"error: {e}", file=sys.stderr)
return 1
except KeyboardInterrupt:
return 130
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |