feat(telemetry): capture installs from published packages

feat(telemetry): capture installs from published packages

Author: blove

apps/website/public/AGENTS.md

@@ -1,4 +1,4 @@
-# Angular Agent Framework v0.0.28
+# Angular Agent Framework v0.0.29
 
 Agent UI primitives and LangGraph streaming adapters for Angular.
 

apps/website/public/CLAUDE.md

@@ -1,4 +1,4 @@
-# Angular Agent Framework v0.0.28
+# Angular Agent Framework v0.0.29
 
 Agent UI primitives and LangGraph streaming adapters for Angular.
 

apps/website/src/app/api/ingest/route.ts

@@ -0,0 +1,79 @@
+import { PostHog } from 'posthog-node';
+import { NextRequest, NextResponse } from 'next/server';
+import { normalizePostHogHost, toSafeAnalyticsString } from '../../../lib/analytics/properties';
+
+const PUBLIC_INGEST_KEY = 'phc_public_cacheplane_telemetry';
+
+interface TelemetryIngestPayload {
+  key?: unknown;
+  distinctId?: unknown;
+  event?: unknown;
+  properties?: unknown;
+}
+
+function getPostHogClient(): PostHog | null {
+  const token = toSafeAnalyticsString(process.env.NEXT_PUBLIC_POSTHOG_TOKEN, 500);
+  if (!token) return null;
+  return new PostHog(token, {
+    host: normalizePostHogHost(process.env.NEXT_PUBLIC_POSTHOG_HOST),
+    flushAt: 1,
+    flushInterval: 0,
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readPayload(value: unknown): {
+  distinctId: string;
+  event: string;
+  properties: Record<string, unknown>;
+} | null {
+  if (!isRecord(value)) return null;
+  const payload = value as TelemetryIngestPayload;
+  if (payload.key !== PUBLIC_INGEST_KEY) return null;
+
+  const distinctId = toSafeAnalyticsString(payload.distinctId, 200);
+  const event = toSafeAnalyticsString(payload.event, 100);
+  if (!distinctId || !event?.startsWith('ngaf:')) return null;
+
+  return {
+    distinctId,
+    event,
+    properties: isRecord(payload.properties) ? payload.properties : {},
+  };
+}
+
+export async function POST(req: NextRequest) {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 });
+  }
+
+  const payload = readPayload(body);
+  if (!payload) return NextResponse.json({ error: 'Invalid telemetry payload' }, { status: 400 });
+
+  const posthog = getPostHogClient();
+  if (!posthog) return NextResponse.json({ error: 'Telemetry ingest is not configured' }, { status: 503 });
+
+  try {
+    posthog.capture({
+      distinctId: payload.distinctId,
+      event: payload.event,
+      properties: {
+        ...payload.properties,
+        $ip: null,
+        $process_person_profile: false,
+      },
+    });
+    await posthog.shutdown();
+    return NextResponse.json({ ok: true }, { status: 202 });
+  } catch (err) {
+    console.error('[telemetry-ingest] capture failed:', err);
+    await posthog.shutdown().catch(() => undefined);
+    return NextResponse.json({ error: 'Telemetry ingest failed' }, { status: 502 });
+  }
+}

apps/website/src/components/landing/FinalCTA.tsx

@@ -24,7 +24,7 @@ export function FinalCTA({
   subtext = 'Install the framework, read the docs, and have a streaming chat in your app this afternoon.',
   primary = DEFAULT_PRIMARY,
   secondary = DEFAULT_SECONDARY,
-  caption = 'MIT · No signup required · No telemetry',
+  caption = 'MIT · No signup required · App telemetry off by default',
 }: FinalCTAProps = {}) {
   return (
     <Section surface="tinted" ariaLabelledBy="final-cta-heading">

apps/website/src/components/landing/Promises.tsx

@@ -18,8 +18,8 @@ const PROMISES = [
     body: 'Self-host LangGraph + your Angular app. Run it all in your VPC.',
   },
   {
-    title: 'No telemetry',
-    body: 'We don’t collect anything from your app. Not at install, not at runtime.',
+    title: 'No app telemetry',
+    body: 'We don’t collect prompts, completions, tool data, or app runtime content by default. Package installs send a minimal opt-out ping.',
   },
   {
     title: 'No model lock-in',

docs/RELEASE.md

@@ -15,7 +15,7 @@ npx nx release patch
 
 This runs Nx Release in interactive mode, which:
 
-1. Builds all seven publishable projects (preVersionCommand).
+1. Builds all seven publishable projects and patches install telemetry into the publishable package manifests (preVersionCommand).
 2. Bumps every package.json version (e.g., `0.0.1` → `0.0.2`).
 3. Generates `CHANGELOG.md` from commits since the last tag.
 4. Creates a git commit `chore(release): publish v0.0.2`.
@@ -50,8 +50,9 @@ npx nx release publish --groups=publishable
 The very first publish ships the version currently on disk (`0.0.1`) — no version bump. `--first-release` skips the "previous tag exists" check and the "package already on registry" check.
 
 ```bash
-# 1. Build everything
+# 1. Build everything and patch install telemetry into publishable manifests
 npx nx run-many -t build --projects=chat,langgraph,ag-ui,render,a2ui,licensing,telemetry
+node libs/telemetry/scripts/apply-install-telemetry.mjs dist/libs/chat dist/libs/langgraph dist/libs/ag-ui dist/libs/render dist/libs/a2ui dist/libs/licensing
 
 # 2. Generate the initial CHANGELOG, commit, and tag v0.0.1
 npx nx release changelog 0.0.1 --first-release

docs/gtm/messaging.md

@@ -10,13 +10,13 @@
 
 **H1:** Ship production agent UIs in Angular.
 
-**Subhead:** Signal-native chat, threads, interrupts, tool progress, and generative UI for LangGraph, AG-UI, and A2UI. MIT-licensed, self-hostable, opt-in telemetry, no React rewrite.
+**Subhead:** Signal-native chat, threads, interrupts, tool progress, and generative UI for LangGraph, AG-UI, and A2UI. MIT-licensed, self-hostable, app telemetry off by default, no React rewrite.
 
 **Primary CTA:** `Install @ngaf/chat` (copy-to-clipboard, fires `marketing:cta_click` with `cta_id=hero_install`, `track=developer`).
 
 **Secondary CTA:** `Talk to our engineers` (routes to `/contact?source=home_hero&track=enterprise`, fires `marketing:cta_click` with `cta_id=hero_talk_to_engineers`, `track=enterprise`).
 
-**Proof row:** `MIT · Angular-native Signals · LangGraph + AG-UI · A2UI-compatible · Self-hostable · Opt-in telemetry`
+**Proof row:** `MIT · Angular-native Signals · LangGraph + AG-UI · A2UI-compatible · Self-hostable · App telemetry off by default`
 
 **Subline under proof row:** *Not another backend agent runtime. Keep LangGraph, Genkit, Mastra, CrewAI, or your own service. Cacheplane solves the Angular UI layer.*
 
@@ -27,12 +27,12 @@ Repeat across the site, comparison pages, and content.
 1. **Angular-native, not React-translated.** Signals, DI, OnPush, standalone components, Angular testing patterns, design-system ownership.
 2. **Complete agent UI, not just stream plumbing.** Messages, status, errors, tool progress, interrupts, branching/history, thread persistence, reload, fallbacks, tests.
 3. **Generative UI that respects the enterprise design system.** Approved components from your design system; no arbitrary code shipping.
-4. **Enterprise OSS posture.** MIT, no end-user telemetry, no required cloud, self-hosting, optional paid support/SLA.
+4. **Enterprise OSS posture.** MIT, no app/runtime content telemetry by default, no required cloud, self-hosting, optional paid support/SLA.
 5. **Production patterns, not demo candy.** Real auth, real backends, observability, error boundaries, fallback strategies, CI/CD, load/chaos patterns, runbooks.
 
 ## Risk-cleanup copy changes (Spec 2)
 
-- "No telemetry" → "**Opt-in telemetry**" with link to `libs/telemetry/README.md`.
+- "No telemetry" → "**App telemetry off by default**" with link to `libs/telemetry/README.md` for the minimal opt-out package install ping.
 - "All Angular versions" (pricing) → **real compatibility matrix** with supported/experimental/planned/unsupported.
 - "A2UI v1" → **"A2UI v0.9-compatible"** until v1 is verified.
 - "Angular Agent Framework" → **"Agent UI for Angular"** (category sweep, with care for substring overlap per existing memory note).

docs/gtm/taxonomy.md

@@ -64,9 +64,8 @@ The standard PostHog `$pageview` event is used as-is across all three surfaces.
 
 | Event                                | When                                       | Surface         | Default      |
 |--------------------------------------|--------------------------------------------|-----------------|--------------|
-| `ngaf:postinstall`                   | `npm install` of an `@ngaf/*` package      | Node (script)   | **Opt-out**  |
+| `ngaf:postinstall`                   | Dependency/global install of a published `@ngaf/*` package | Node (script)   | **Opt-out**  |
 | `ngaf:runtime_instance_created`      | Server adapter init                         | Node            | **Opt-out**  |
-| `ngaf:runtime_request_created`       | Server adapter handles a request            | Node            | **Opt-out**  |
 | `ngaf:stream_started`                | Stream begins                              | Node            | **Opt-out**  |
 | `ngaf:stream_ended`                  | Stream ends normally                       | Node            | **Opt-out**  |
 | `ngaf:stream_errored`                | Stream errors                              | Node            | **Opt-out**  |

gtm.md

@@ -92,7 +92,7 @@ Operational progress lives in agent runs and PostHog. The repo holds durable str
 ## 8. Non-goals (current phase)
 
 - We do not compete as a general agent UI framework. We claim the Angular final mile.
-- We do not ship telemetry from `@ngaf/*` browser packages by default. Opt-in only. Node-side telemetry honors `DO_NOT_TRACK` and `NGAF_TELEMETRY_DISABLED`; see [libs/telemetry/README.md](libs/telemetry/README.md) for the full contract.
+- We do not ship telemetry from `@ngaf/*` browser packages by default. Opt-in only. Node-side package telemetry is minimal and honors `DO_NOT_TRACK`, `npm_config_do_not_track`, and `NGAF_TELEMETRY_DISABLED`; see [libs/telemetry/README.md](libs/telemetry/README.md) for the full contract.
 - We do not run paid acquisition until Phase 2 organic baselines exist.
 - We do not pursue stars as a vanity metric.
 - We do not run A/B positioning experiments in Phase 1. Ship one hero, measure, iterate.

libs/ag-ui/project.json

@@ -4,15 +4,6 @@
   "sourceRoot": "libs/ag-ui/src",
   "prefix": "lib",
   "projectType": "library",
-  "release": {
-    "version": {
-      "manifestRootsToUpdate": [
-        "{projectRoot}"
-      ],
-      "currentVersionResolver": "git-tag",
-      "fallbackCurrentVersionResolver": "disk"
-    }
-  },
   "tags": [],
   "targets": {
     "build": {