@vibes.diy/api-svc 4.5.5 → 5.2.2

package/types.d.ts

@@ -2,7 +2,7 @@ import { SuperThis, FPApiToken, DeviceIdCAIf } from "@vibes.diy/identity";
 import { WSSendProvider } from "./svc-ws-send-provider.js";
 import { Logger, Result } from "@adviser/cement";
 import { LLMRequest } from "@vibes.diy/call-ai-v2";
-import { type AccessDescriptor, type UserContext, type EvtViewerGrantsChanged, type EvtRequestGrant, type EvtUserNotification, LLMHeaders, MsgBase, VibesAssetStorage, VibesFPApiParameters } from "@vibes.diy/api-types";
+import { type AccessDescriptor, type UserContext, type EvtViewerGrantsChanged, type EvtRequestGrant, type EvtSocialEdge, type EvtUserNotification, LLMHeaders, MsgBase, VibesAssetStorage, VibesFPApiParameters } from "@vibes.diy/api-types";
 import { DBFlavour, VibesApiTables, VibesSqlite } from "@vibes.diy/api-sql";
 import { type } from "arktype";
 import type { AssetGrantSigner } from "./asset-grant.js";
@@ -55,6 +55,13 @@ export interface VibesApiSQLCtx {
         docId: string;
         channel?: string;
     }, senderConnId: string): Promise<void>;
+    notifyDocChangedRemote?(evt: {
+        ownerHandle: string;
+        appSlug: string;
+        dbName: string;
+        docId: string;
+        channels: string[];
+    }): Promise<void>;
     registerDocSubscription?(subscriptionKey: string): Promise<void>;
     deregisterDocSubscription?(subscriptionKey: string): Promise<void>;
     notifyDocEphemeral?(evt: {
@@ -69,12 +76,24 @@ export interface VibesApiSQLCtx {
     notifyRequestGrantChanged?(evt: EvtRequestGrant, senderConnId: string): Promise<void>;
     registerRequestGrantSubscription?(subscriptionKey: string): Promise<void>;
     deregisterRequestGrantSubscription?(subscriptionKey: string): Promise<void>;
+    notifySocialEdgeChanged?(evt: EvtSocialEdge, senderConnId: string): Promise<void>;
+    registerSocialSubscription?(subscriptionKey: string): Promise<void>;
+    deregisterSocialSubscription?(subscriptionKey: string): Promise<void>;
     notifyViewerGrantsChanged?(evt: EvtViewerGrantsChanged, senderConnId: string): Promise<void>;
     registerViewerGrantsSubscription?(subscriptionKey: string): Promise<void>;
     deregisterViewerGrantsSubscription?(subscriptionKey: string): Promise<void>;
     notifyUser?(userId: string, evt: EvtUserNotification, senderConnId: string): Promise<void>;
     registerUserSubscription?(userId: string): Promise<void>;
     deregisterUserSubscription?(userId: string): Promise<void>;
+    registerAudienceReader?(handle: string): Promise<void>;
+    patchAudienceKeysRemote?(targetHandle: string, patch: {
+        op: "add" | "remove";
+        channels: string[];
+        appScope?: {
+            ownerHandle: string;
+            appSlug: string;
+        };
+    }): Promise<void>;
     registerPushToken?(userId: string, token: string, platform: "ios", appVersion: string): Promise<void>;
     deregisterPushToken?(userId: string, token: string): Promise<void>;
     invokeAccessFn?(params: {

package/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../jsr/types.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AA6G/B,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;IAChC,IAAI,EAAE,+BAA+B;IACrC,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,QAAQ;IACrB,MAAM,EAAE,QAAQ;CACjB,CAAC,CAAC;AAGH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,8BAA8B;IACpC,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,QAAQ;CACjB,CAAC,CAAC;AAGH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;IACnC,IAAI,EAAE,mCAAmC;IACzC,WAAW,EAAE,aAAa;IAC1B,OAAO,EAAE,cAAc;CACxB,CAAC,CAAC;AAGH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../jsr/types.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AA0J/B,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;IAChC,IAAI,EAAE,+BAA+B;IACrC,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,QAAQ;IACrB,MAAM,EAAE,QAAQ;CACjB,CAAC,CAAC;AAGH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,8BAA8B;IACpC,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,QAAQ;CACjB,CAAC,CAAC;AAGH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;IACnC,IAAI,EAAE,mCAAmC;IACzC,WAAW,EAAE,aAAa;IAC1B,OAAO,EAAE,cAAc;CACxB,CAAC,CAAC;AAGH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC"}

package/usage-report/README.md

@@ -7,6 +7,7 @@ Files:
 - `inspect-db.ts`: read-only database inspector for connection info, table listings, table samples, and ad hoc SQL.
 - `inspect-db-report.ts`: report generator that queries the database and produces the HTML report.
 - `inspect-db-report-template.ts`: HTML template/rendering module used by the report generator.
+- `vibe-usage.py`: cross-plane usage monitor for a deployed vibe (Postgres writers + Cloudflare visitors + Clerk sign-ups → one funnel). See `agents/vibe-usage-analytics.md`. Run: `python3 vibe-usage.py [HOURS]` (default 48); override `APP_SLUG` / `CF_PATH` env for other apps.
 
 Commands:
 

package/usage-report/billing-reconcile-util.d.ts

@@ -9,17 +9,19 @@ export interface AutumnUsageRow {
 export interface ReconciliationRow {
     readonly userId: string;
     readonly dbCents: number;
-    readonly autumnCents: number;
-    readonly driftCents: number;
+    readonly expectedCredits: number;
+    readonly autumnCredits: number;
+    readonly driftCredits: number;
 }
 export interface ReconciliationReport {
     readonly rows: readonly ReconciliationRow[];
     readonly totalDbCents: number;
-    readonly totalAutumnCents: number;
-    readonly totalDriftCents: number;
+    readonly totalExpectedCredits: number;
+    readonly totalAutumnCredits: number;
+    readonly totalDriftCredits: number;
     readonly driftPct: number;
 }
 export declare function mergeReconciliation(db: readonly DbCostRow[], autumn: readonly AutumnUsageRow[]): ReconciliationReport;
-export declare function usersOverThreshold(report: ReconciliationReport, cents: number): number;
+export declare function usersOverThreshold(report: ReconciliationReport, credits: number): number;
 export declare function usagePercentile(report: ReconciliationReport, p: number): number;
 export declare function renderReconciliationMarkdown(report: ReconciliationReport, thresholds: readonly number[]): string;

package/usage-report/billing-reconcile-util.js

@@ -1,23 +1,33 @@
+const DISPLAY_CREDITS_PER_CENT = 2;
 export function mergeReconciliation(db, autumn) {
     const ids = new Set([...db.map((r) => r.userId), ...autumn.map((r) => r.userId)]);
     const dbBy = new Map(db.map((r) => [r.userId, r.cents]));
     const autumnBy = new Map(autumn.map((r) => [r.userId, r.usage]));
     const rows = [...ids].sort().map((userId) => {
         const dbCents = dbBy.get(userId) ?? 0;
-        const autumnCents = autumnBy.get(userId) ?? 0;
-        return { userId, dbCents, autumnCents, driftCents: dbCents - autumnCents };
+        const expectedCredits = dbCents * DISPLAY_CREDITS_PER_CENT;
+        const autumnCredits = autumnBy.get(userId) ?? 0;
+        return { userId, dbCents, expectedCredits, autumnCredits, driftCredits: expectedCredits - autumnCredits };
     });
     const totalDbCents = rows.reduce((s, r) => s + r.dbCents, 0);
-    const totalAutumnCents = rows.reduce((s, r) => s + r.autumnCents, 0);
-    const totalDriftCents = totalDbCents - totalAutumnCents;
-    const driftPct = totalDbCents === 0 ? 0 : (Math.abs(totalDriftCents) / totalDbCents) * 100;
-    return { rows, totalDbCents, totalAutumnCents, totalDriftCents, driftPct };
+    const totalExpectedCredits = rows.reduce((s, r) => s + r.expectedCredits, 0);
+    const totalAutumnCredits = rows.reduce((s, r) => s + r.autumnCredits, 0);
+    const totalDriftCredits = totalExpectedCredits - totalAutumnCredits;
+    const driftPct = totalExpectedCredits === 0 ? 0 : (Math.abs(totalDriftCredits) / totalExpectedCredits) * 100;
+    return {
+        rows,
+        totalDbCents,
+        totalExpectedCredits,
+        totalAutumnCredits,
+        totalDriftCredits,
+        driftPct,
+    };
 }
-export function usersOverThreshold(report, cents) {
-    return report.rows.filter((r) => r.autumnCents > cents).length;
+export function usersOverThreshold(report, credits) {
+    return report.rows.filter((r) => r.autumnCredits > credits).length;
 }
 export function usagePercentile(report, p) {
-    const usages = report.rows.map((r) => r.autumnCents).sort((a, b) => a - b);
+    const usages = report.rows.map((r) => r.autumnCredits).sort((a, b) => a - b);
     if (usages.length === 0)
         return 0;
     const idx = Math.min(usages.length - 1, Math.max(0, Math.ceil((p / 100) * usages.length) - 1));
@@ -27,20 +37,25 @@ export function renderReconciliationMarkdown(report, thresholds) {
     const lines = [];
     lines.push("## Shadow-ledger reconciliation");
     lines.push("");
-    lines.push(`Total DB cents: ${report.totalDbCents}`);
-    lines.push(`Total Autumn cents: ${report.totalAutumnCents}`);
-    lines.push(`Total drift cents: ${report.totalDriftCents} (${report.driftPct.toFixed(2)}%)`);
+    lines.push(`Total DB cents (raw): ${report.totalDbCents}`);
+    lines.push(`Total expected credits (2x): ${report.totalExpectedCredits}`);
+    lines.push(`Total Autumn credits: ${report.totalAutumnCredits}`);
+    lines.push(`Total drift credits: ${report.totalDriftCredits} (${report.driftPct.toFixed(2)}%)`);
+    lines.push("");
+    lines.push("Carve-outs (see header): wall-crossing turns under-count in Autumn by the");
+    lines.push("clamped overshoot (verify via events.list values); plan changes reset the");
+    lines.push("aggregate — exclude users who changed plan inside the window.");
     lines.push("");
     for (const t of thresholds) {
-        lines.push(`Users over ${t} cents: ${usersOverThreshold(report, t)}`);
+        lines.push(`Users over ${t} credits: ${usersOverThreshold(report, t)}`);
     }
     lines.push("");
-    lines.push(`p50 / p90 / p99 usage cents: ${usagePercentile(report, 50)} / ${usagePercentile(report, 90)} / ${usagePercentile(report, 99)}`);
+    lines.push(`p50 / p90 / p99 usage credits: ${usagePercentile(report, 50)} / ${usagePercentile(report, 90)} / ${usagePercentile(report, 99)}`);
     lines.push("");
-    lines.push("| userId | dbCents | autumnCents | driftCents |");
-    lines.push("| --- | --- | --- | --- |");
+    lines.push("| userId | dbCents | expectedCredits | autumnCredits | driftCredits |");
+    lines.push("| --- | --- | --- | --- | --- |");
     for (const r of report.rows) {
-        lines.push(`| ${r.userId} | ${r.dbCents} | ${r.autumnCents} | ${r.driftCents} |`);
+        lines.push(`| ${r.userId} | ${r.dbCents} | ${r.expectedCredits} | ${r.autumnCredits} | ${r.driftCredits} |`);
     }
     return lines.join("\n");
 }

package/usage-report/billing-reconcile-util.js.map

@@ -1 +1 @@
-{"version":3,"file":"billing-reconcile-util.js","sourceRoot":"","sources":["../../jsr/usage-report/billing-reconcile-util.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"billing-reconcile-util.js","sourceRoot":"","sources":["../../jsr/usage-report/billing-reconcile-util.ts"],"names":[],"mappings":"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"}

package/usage-report/vibe-usage.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Cross-plane usage monitor for a deployed vibe.
+
+Pulls last-N-hours activity from all three data planes and prints one funnel:
+  - Postgres (AppDocuments): signed-in writers, doc types, new vs returning
+  - Cloudflare GraphQL:      page visits / distinct IPs (read-only visitors too)
+  - Clerk Backend API:       new sign-ups + platform baseline
+
+This is the scripted form of the runbook: agents/vibe-usage-analytics.md
+Read that for the gotchas (Clerk UA err-1010, CF 1d-window cap + sampling,
+cumulative-vs-rolling-window). Read-only throughout.
+
+Usage:
+  python3 vibe-usage.py [HOURS]                     # default 48
+  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.
+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
+# 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.
+OWNER = os.environ.get("OWNER", "og")                       # live app owner handle
+APP_SLUG = os.environ.get("APP_SLUG", "pickathon-picker")   # live app (owner: og)
+CF_PATH = os.environ.get("CF_PATH", "/vibe/og/pickathon-picker%")  # page shell path
+CF_ZONE = os.environ.get("CF_ZONE", "13f147047a38c9d54a576424347cb4be")  # vibes.diy
+# Resolve DB_DIR relative to this file so it works from any cwd / worktree.
+DB_DIR = os.path.dirname(os.path.abspath(__file__)) + "/.."
+REPO_ROOT = os.path.abspath(DB_DIR + "/../../..")
+
+now = datetime.now(timezone.utc)
+since = now - timedelta(hours=HOURS)
+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)
+
+CF_TOKEN = os.environ.get("CLOUDFLARE_API_TOKEN")
+CLERK_KEY = os.environ.get("CLERK_SECRET_KEY")
+
+
+def db(sql):
+    """Run a read-only query via db:inspect, return parsed rows."""
+    p = subprocess.run(
+        ["pnpm", "--dir", DB_DIR, "run", "db:inspect", "sql", sql],
+        capture_output=True, text=True, cwd=REPO_ROOT,
+    )
+    if "{" not in p.stdout:  # surface the real DB/tooling error, not a ValueError
+        raise SystemExit(f"db:inspect failed (exit {p.returncode}):\n"
+                         f"{(p.stderr or p.stdout).strip()}")
+    return json.loads(p.stdout[p.stdout.index("{"):]).get("rows", [])
+
+
+def http_json(url, data=None, headers=None):
+    headers = dict(headers or {})
+    # Clerk/CF firewall 403s (err 1010) the default python-urllib UA; curl UA passes.
+    headers.setdefault("User-Agent", "curl/8.0")
+    req = urllib.request.Request(url, data=data, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        return {"_error": f"{e.code} {e.read()[:200]!r}"}
+
+
+def cf_graphql(query):
+    return http_json(
+        "https://api.cloudflare.com/client/v4/graphql",
+        data=json.dumps({"query": query}).encode(),
+        headers={"Authorization": f"Bearer {CF_TOKEN}", "Content-Type": "application/json"},
+    )
+
+
+def clerk(path):
+    return http_json("https://api.clerk.com/v1" + path,
+                     headers={"Authorization": f"Bearer {CLERK_KEY}"})
+
+
+print(f"=== {APP_SLUG} — last {HOURS}h  ({since_iso} → {now_iso}) ===\n")
+
+# ---- 1. Postgres: signed-in activity -------------------------------------
+APP_FILTER = f"""\"userSlug\" = '{OWNER}' AND "appSlug" = '{APP_SLUG}'"""
+totals = db(f"""SELECT count(*) AS writes, count(DISTINCT "userId") AS writers,
+  count(DISTINCT "docId") AS docs, coalesce(sum(deleted),0) AS deletes
+  FROM "AppDocuments"
+  WHERE {APP_FILTER} AND created >= '{since_iso}'""")[0]
+print(f"DATA (signed-in users)  [{OWNER}/{APP_SLUG}]")
+print(f"  writes={totals['writes']}  writers={totals['writers']}  "
+      f"distinct-docs={totals['docs']}  deletes={totals['deletes']}")
+
+types = db(f"""SELECT coalesce(data->>'type','(none)') AS t, count(*) AS n,
+  count(DISTINCT "userId") AS u FROM "AppDocuments"
+  WHERE {APP_FILTER} AND created >= '{since_iso}'
+  GROUP BY 1 ORDER BY n DESC""")
+print("  by type: " + ", ".join(f"{r['t']}={r['n']}({r['u']}u)" for r in types))
+
+split = db(f"""WITH firsts AS (SELECT "userId", min(created) f FROM "AppDocuments"
+    WHERE {APP_FILTER} GROUP BY 1)
+  SELECT count(*) FILTER (WHERE f >= '{since_iso}') AS new,
+         count(*) FILTER (WHERE f <  '{since_iso}') AS returning
+  FROM firsts WHERE "userId" IN (
+    SELECT DISTINCT "userId" FROM "AppDocuments"
+    WHERE {APP_FILTER} AND created >= '{since_iso}')""")[0]
+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}")
+
+# ---- 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])))
+
+# 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)")