@vibes.diy/api-svc 5.0.1 → 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/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)")