@vibes.diy/api-svc 12.2.11 → 12.3.0

package/usage-report/vibe-usage.py

@@ -15,12 +15,19 @@ Usage:
   OWNER=owner APP_SLUG=my-app CF_PATH='/vibe/owner/my-app%' python3 vibe-usage.py 168
 
 Requires env (present in cloud sessions): CLOUDFLARE_API_TOKEN, CLERK_SECRET_KEY.
+Both are ENFORCED — a missing key exits 2 rather than zeroing a leg of the
+funnel. Check with usage-report/check-env.sh --tool vibe-usage; opt out of a
+leg deliberately with --skip-visitors / --skip-signups.
 Postgres goes through the repo's db:inspect (prod, read-only).
 """
 import json, os, subprocess, sys, urllib.request, urllib.error
 from datetime import datetime, timedelta, timezone
 
-HOURS = int(sys.argv[1]) if len(sys.argv) > 1 else 48
+_FLAGS = {a for a in sys.argv[1:] if a.startswith("--")}
+_POSITIONAL = [a for a in sys.argv[1:] if not a.startswith("--")]
+HOURS = int(_POSITIONAL[0]) if _POSITIONAL else 48
+SKIP_VISITORS = "--skip-visitors" in _FLAGS
+SKIP_SIGNUPS = "--skip-signups" in _FLAGS
 # App identity in Postgres is keyed by (userSlug, appSlug) — filtering on appSlug
 # alone would aggregate dev/remix/test twins under other handles. OWNER scopes it
 # to the one owner whose /vibe/<owner>/<slug> path the CF_PATH also targets.
@@ -38,9 +45,46 @@ since_iso = since.strftime("%Y-%m-%dT%H:%M:%SZ")
 now_iso = now.strftime("%Y-%m-%dT%H:%M:%SZ")
 since_ms = int(since.timestamp() * 1000)
 
+def load_dev_vars():
+    """Mirror loadDevVars() in usage-report-util.ts: api/svc/.dev.vars is a
+    supported source for these keys, so the TS tools, check-env.sh and this
+    script must all agree on what 'set' means. First occurrence wins, quotes
+    are stripped, and a real environment variable always takes precedence."""
+    for path in (os.path.join(DB_DIR, ".dev.vars"), ".dev.vars"):
+        if not os.path.exists(path):
+            continue
+        with open(path, encoding="utf8") as fh:
+            for raw in fh:
+                line = raw.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key, value = key.strip(), value.strip()
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+                    value = value[1:-1]
+                os.environ.setdefault(key, value)
+
+
+load_dev_vars()
 CF_TOKEN = os.environ.get("CLOUDFLARE_API_TOKEN")
 CLERK_KEY = os.environ.get("CLERK_SECRET_KEY")
 
+# A missing key must not silently zero a leg of the funnel. Without CF_TOKEN the
+# requests go out as "Bearer None", the HTTPError is swallowed, the counters stay
+# at their zero initialisers, and the last line reads "FUNNEL: ~0 visits" — a
+# plausible number about a dead app rather than a visible failure. Fail closed;
+# --skip-visitors / --skip-signups opt out explicitly and stamp the funnel.
+_missing = []
+if not CF_TOKEN and not SKIP_VISITORS:
+    _missing.append("CLOUDFLARE_API_TOKEN  (visitor traffic; without it the funnel would read ~0 visits)")
+if not CLERK_KEY and not SKIP_SIGNUPS:
+    _missing.append("CLERK_SECRET_KEY      (sign-ups; without it the funnel would read 0 sign-ups)")
+if _missing:
+    print("refusing to run — missing credentials:\n  " + "\n  ".join(_missing), file=sys.stderr)
+    print("\ncheck your env:  usage-report/check-env.sh --tool vibe-usage"
+          "\nor accept a partial funnel with --skip-visitors / --skip-signups", file=sys.stderr)
+    sys.exit(2)
+
 
 def db(sql):
     """Run a read-only query via db:inspect, return parsed rows."""
@@ -109,63 +153,83 @@ print(f"  writers new-to-app={split['new']}  returning={split['returning']}")
 # ---- 2. Cloudflare: read-only visitors (day-sliced; zone caps at 1d) ------
 print("\nTRAFFIC (all visitors, incl. non-signed-in; sampled + IP counts overlap days)")
 tot_ip = tot_visits = tot_req = 0
-slice_start = since
-while slice_start < now:
-    slice_end = min(slice_start + timedelta(hours=24), now)
-    q = f'''query {{ viewer {{ zones(filter: {{zoneTag: "{CF_ZONE}"}}) {{
-      httpRequestsAdaptiveGroups(limit: 5000, filter: {{
-        datetime_geq: "{slice_start.strftime('%Y-%m-%dT%H:%M:%SZ')}",
-        datetime_leq: "{slice_end.strftime('%Y-%m-%dT%H:%M:%SZ')}",
-        clientRequestPath_like: "{CF_PATH}"}}) {{
-        dimensions {{ clientIP }} sum {{ visits }} count }} }} }} }}'''
-    res = cf_graphql(q)
-    if res.get("errors") or res.get("_error"):
-        print(f"  [{slice_start:%m-%d %H:%M}] cf error: {res.get('errors') or res.get('_error')}")
-    else:
-        rows = res["data"]["viewer"]["zones"][0]["httpRequestsAdaptiveGroups"]
-        ips = len(rows); v = sum(r["sum"]["visits"] for r in rows); c = sum(r["count"] for r in rows)
-        tot_ip += ips; tot_visits += v; tot_req += c
-        print(f"  [{slice_start:%m-%d %H:%M}→{slice_end:%H:%M}]  IPs={ips}  visits={v}  requests={c}")
-    slice_start = slice_end
-print(f"  TOTAL: IPs={tot_ip} (summed per-slice — cross-day overlap, not exact uniques)"
-      f"  visits={tot_visits}  requests={tot_req}")
+cf_failed = False
+if SKIP_VISITORS:
+    print("  SKIPPED (--skip-visitors) — Cloudflare was never queried. The zeros below mean")
+    print("  'not measured', not 'no traffic'.")
+else:
+    slice_start = since
+    while slice_start < now:
+        slice_end = min(slice_start + timedelta(hours=24), now)
+        q = f'''query {{ viewer {{ zones(filter: {{zoneTag: "{CF_ZONE}"}}) {{
+          httpRequestsAdaptiveGroups(limit: 5000, filter: {{
+            datetime_geq: "{slice_start.strftime('%Y-%m-%dT%H:%M:%SZ')}",
+            datetime_leq: "{slice_end.strftime('%Y-%m-%dT%H:%M:%SZ')}",
+            clientRequestPath_like: "{CF_PATH}"}}) {{
+            dimensions {{ clientIP }} sum {{ visits }} count }} }} }} }}'''
+        res = cf_graphql(q)
+        if res.get("errors") or res.get("_error"):
+            cf_failed = True
+            print(f"  [{slice_start:%m-%d %H:%M}] cf error: {res.get('errors') or res.get('_error')}")
+        else:
+            rows = res["data"]["viewer"]["zones"][0]["httpRequestsAdaptiveGroups"]
+            ips = len(rows); v = sum(r["sum"]["visits"] for r in rows); c = sum(r["count"] for r in rows)
+            tot_ip += ips; tot_visits += v; tot_req += c
+            print(f"  [{slice_start:%m-%d %H:%M}→{slice_end:%H:%M}]  IPs={ips}  visits={v}  requests={c}")
+        slice_start = slice_end
+    print(f"  TOTAL: IPs={tot_ip} (summed per-slice — cross-day overlap, not exact uniques)"
+          f"  visits={tot_visits}  requests={tot_req}")
+    # A slice that errored contributes 0, so a partly-failed run must not present
+    # its total as a measurement.
+    if cf_failed:
+        print("  ⚠ at least one slice errored — the total above is a FLOOR, not a count.")
 
 # ---- 3. Clerk: sign-ups + baseline ---------------------------------------
 print("\nSIGN-UPS (Clerk, platform-wide)")
-total = clerk("/users/count").get("total_count", "?")
-active = clerk(f"/users/count?last_active_at_since={since_ms}").get("total_count", "?")
-# Page back until we pass the baseline window's start, else the newest 200 would
-# silently cap `new`/`prior` during exactly the spike/long-window runs this targets.
-base_start = since_ms - 14 * 86400000
-users, offset, capped = [], 0, False
-while True:
-    page = clerk(f"/users?order_by=-created_at&limit=500&offset={offset}")
-    if not isinstance(page, list) or not page:
-        break
-    users += page
-    if page[-1]["created_at"] < base_start:   # covered the whole window+baseline
-        break
-    offset += 500
-    if offset >= 5000:                        # 10k-account safety stop
-        capped = True
-        break
-new = [u for u in users if u["created_at"] >= since_ms]
-prior = [u for u in users if base_start <= u["created_at"] < since_ms]
-base_per = len(prior) / (14 / (HOURS / 24))
-print(f"  total accounts(cumulative)={total}  active-in-window={active}")
-cap_note = "  ⚠ paging capped at 10k — new/baseline may undercount" if capped else ""
-print(f"  new sign-ups={len(new)}  (prior baseline ≈{base_per:.1f} per {HOURS}h){cap_note}")
-doms = {}
-for u in new:
-    d = (u["email_addresses"][0]["email_address"].split("@")[-1]
-         if u.get("email_addresses") else "?")
-    doms[d] = doms.get(d, 0) + 1
-if doms:
-    print("  domains: " + ", ".join(f"{k}={v}" for k, v in sorted(doms.items(), key=lambda x: -x[1])))
+if SKIP_SIGNUPS:
+    print("  SKIPPED (--skip-signups) — Clerk was never queried; sign-ups are UNKNOWN, not 0.")
+    new = []
+else:
+    total = clerk("/users/count").get("total_count", "?")
+    active = clerk(f"/users/count?last_active_at_since={since_ms}").get("total_count", "?")
+    # Page back until we pass the baseline window's start, else the newest 200 would
+    # silently cap `new`/`prior` during exactly the spike/long-window runs this targets.
+    base_start = since_ms - 14 * 86400000
+    users, offset, capped = [], 0, False
+    while True:
+        page = clerk(f"/users?order_by=-created_at&limit=500&offset={offset}")
+        if not isinstance(page, list) or not page:
+            break
+        users += page
+        if page[-1]["created_at"] < base_start:   # covered the whole window+baseline
+            break
+        offset += 500
+        if offset >= 5000:                        # 10k-account safety stop
+            capped = True
+            break
+    new = [u for u in users if u["created_at"] >= since_ms]
+    prior = [u for u in users if base_start <= u["created_at"] < since_ms]
+    base_per = len(prior) / (14 / (HOURS / 24))
+    print(f"  total accounts(cumulative)={total}  active-in-window={active}")
+    cap_note = "  ⚠ paging capped at 10k — new/baseline may undercount" if capped else ""
+    print(f"  new sign-ups={len(new)}  (prior baseline ≈{base_per:.1f} per {HOURS}h){cap_note}")
+    doms = {}
+    for u in new:
+        d = (u["email_addresses"][0]["email_address"].split("@")[-1]
+             if u.get("email_addresses") else "?")
+        doms[d] = doms.get(d, 0) + 1
+    if doms:
+        print("  domains: " + ", ".join(f"{k}={v}" for k, v in sorted(doms.items(), key=lambda x: -x[1])))
 
 # funnel cross-ref: which new Clerk accounts wrote in the app
 writers = {r["userId"] for r in db(f'''SELECT DISTINCT "userId" FROM "AppDocuments"
   WHERE {APP_FILTER} AND created >= '{since_iso}' ''')}
 new_ids = {u["id"] for u in new}
-print(f"\nFUNNEL: ~{tot_visits} visits → {len(new)} sign-ups → "
-      f"{len(writers)} active writers ({len(writers & new_ids)} of them brand-new accounts)")
+visits_txt = "UNKNOWN" if SKIP_VISITORS else (f"~{tot_visits}+" if cf_failed else f"~{tot_visits}")
+signups_txt = "UNKNOWN" if SKIP_SIGNUPS else str(len(new))
+# The cross-reference is derived from `new`, so skipping Clerk makes it
+# unmeasured too — printing "0 of them brand-new" would be the same
+# plausible-negative this whole change exists to remove.
+new_txt = "UNKNOWN" if SKIP_SIGNUPS else str(len(writers & new_ids))
+print(f"\nFUNNEL: {visits_txt} visits → {signups_txt} sign-ups → "
+      f"{len(writers)} active writers ({new_txt} of them brand-new accounts)")