Skip to content

gerodp/hermes-productivity-skills / analytics/umami-report

umami-report

Verified

Per-site visitor & pageview reports from a private (self-hosted) Umami instance.

FileKindSize
SKILL.mdskill md4.9 KB
scripts/test_umami_report.pyexecutablescript13.6 KB
scripts/umami_report.pyexecutablescript16.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())
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall