@decantr/telemetry 3.4.0 → 3.8.0

package/README.md

@@ -1,139 +1,45 @@
 # @decantr/telemetry
 
-Privacy-preserving telemetry contracts, clients, and analytics sinks for Decantr.
+Optional telemetry contracts, privacy filters, clients, and sinks for Decantr.
 
-This package is the first layer of Decantr's usage intelligence system. It defines the event names and payload shapes that the CLI, API, MCP server, registry app, and content pipeline can emit without coupling those surfaces to a single analytics vendor.
+Decantr 3.8 keeps this package for compatibility and future/private deployments. The active hosted product no longer includes registry portal analytics, PostHog dashboards, Supabase rollups, billing funnels, public telemetry ingest, or admin telemetry pages.
 
 ## Product Stance
 
 Decantr telemetry measures Decantr usage, not customer application data.
 
-Allowed signals include command names, registry sources, registry content IDs, package versions, workflow modes, success/failure, duration, audit scores, Project Health status/score/counts, aggregate counts, marketing route labels, campaign tags, and referrer domains. Do not send prompts, source code, generated files, health reports, finding evidence, raw file paths, environment variables, secrets, API keys, email addresses, IP addresses, raw referrer URLs, click IDs, or user agents.
+Allowed signals include command names, package versions, workflow modes, success/failure, duration, Project Health status/counts, content types, aggregate counts, and optional campaign labels. Do not send prompts, source code, generated files, health reports, finding evidence, raw file paths, environment variables, secrets, API keys, email addresses, IP addresses, raw referrer URLs, click IDs, or user agents.
 
-## MVP Events
+## Runtime Posture
 
-- `cli.command.completed`
-- `registry.item.resolved`
-- `registry.sync.completed`
-- `execution_pack.compiled`
-- `execution_pack.selected`
-- `audit.completed`
-- `critique.completed`
-- `decantr.analyze.completed`
-- `decantr.init.completed`
-- `decantr.new.completed`
-- `decantr.refresh.completed`
-- `decantr.check.completed`
-- `decantr.health.healthy`
-- `health.report.generated`
-- `health.finding.prompt_requested`
-- `health.ci.failed`
-- `studio.started`
-- `studio.health_refreshed`
-- `content.validation.completed`
-- `content.publish.completed`
-- `user.signup.completed`
-- `org.created`
-- `api_key.created`
-- `billing.plan_clicked`
-- `billing.checkout_blocked`
-- `private_registry.gate_viewed`
-- `private_registry.intent_clicked`
-- `private_registry.content_listed`
-- `marketing_web.page_viewed`
-- `marketing_web.cta_clicked`
-- `marketing_web.outbound_clicked`
-- `marketing_web.command_clicked`
-- `registry_web.page_viewed`
-- `registry_web.search_performed`
-- `registry_web.content_opened`
-- `registry_web.signup_clicked`
-- `registry_web.api_key_page_viewed`
-- `registry_web.billing_viewed`
-- `registry_web.organization_viewed`
-- `registry_web.identity_linked`
-- `telemetry.identity_linked`
+- CLI telemetry is disabled by default.
+- MCP does not emit Decantr telemetry.
+- The Fly API is content/reference only.
+- Legacy event names may still contain `registry.*` for Decantr 3.x compatibility.
 
-Private Registry remains manually provisioned and Enterprise-gated while the paywall is off. The telemetry surface records readiness and permitted usage only: gated views, intent clicks, and aggregate content-list counts. It does not collect private package slugs or customer source material.
-
-`DECANTR_TELEMETRY_EVENT_CATALOG` is the canonical source/event matrix. Public ingest should call `isTelemetryEventAllowedForSource(name, source)` and accept both `DECANTR_TELEMETRY_ACCEPTED_SCHEMA_VERSIONS` during rollout, while new emitters use schema `0.3.0`.
-
-## Actor Attribution
-
-Every event can carry `context.actorType` so Decantr can distinguish founder/internal usage from real customer adoption without relying on remembered PostHog person ids.
-
-- `anonymous`: unauthenticated registry/API browsing or resolution with only an anonymous id.
-- `customer`: authenticated hosted usage, org/project usage, or opted-in CLI install/project usage.
-- `internal`: Decantr team, QA, and synthetic traffic identified by server-side identity flags or opaque id allowlists.
-- `official_pipeline`: Decantr-owned content validation/publish automation.
-- `service`: backend service events that are not attributable to a user, org, install, project, or anonymous visitor.
-
-If omitted, sinks call `resolveTelemetryActorType(context)`. The hosted API normalizes public ingest events with server-authoritative attribution from Supabase identity flags, `telemetry_identity_aliases`, and fallback overrides through `DECANTR_INTERNAL_USER_IDS`, `DECANTR_INTERNAL_ORG_IDS`, `DECANTR_INTERNAL_INSTALL_IDS`, `DECANTR_INTERNAL_PROJECT_IDS`, and `DECANTR_INTERNAL_ANONYMOUS_IDS`.
-
-The registry admin portal exposes `/admin/telemetry` for managing `anonymous`, `install`, and `project` aliases without writing SQL. Aliases can be linked by user email/id or organization slug/id. Opted-in CLI users can review the shareable event/field explanation with `decantr telemetry explain`, then self-link opaque install/project ids with `decantr telemetry link --enable --org <slug>`, which calls the audited API alias flow and emits `telemetry.identity_linked`. Mutations clear the hosted API actor-resolution cache. `/admin/telemetry/usage` adds the protected PostHog query view for active identities, source/actor mix, paid-acquisition signals, failure signals, period-over-period trends, product signal buckets, operating alerts, stored rollup history, snapshot freshness, identity coverage, and unaliased identity candidates, with one-click candidate classification through the same audited alias flow. `/admin/reports` and individual organization admin pages read durable Supabase rollups written by the service-token protected snapshot runner, giving Decantr an owned business-intelligence history while PostHog remains the raw event explorer.
-
-The shared client redacts sensitive keys before any sink receives an event. This includes prompts, source code, file paths, repository names, raw route names, package slugs, emails, tokens, cookies, URLs, user agents, and authorization fields, while preserving aggregate product fields such as command, duration, success, counts, workflow mode, and signal bucket metadata.
-
-## Security And Permissions
-
-This package defines telemetry contracts, redaction, clients, and optional sinks. It does not auto-start collection. Events are emitted only when a caller constructs a client and calls `capture`. The Decantr CLI remains opt-in for telemetry; use `decantr telemetry explain` for the shareable review view. See [security permissions](https://decantr.ai/reference/security-permissions.md).
-
-## Campaign Attribution
-
-The marketing site and registry can attach campaign attribution fields to web events: UTM source/medium/campaign/content/term/id, first and last touch variants, landing path, referrer domain, click-id provider, and whether a supported click id was present. Raw ad click ids such as `twclid`, `gclid`, `gbraid`, `wbraid`, `fbclid`, `msclkid`, `ttclid`, and `li_fat_id` are not included in Decantr telemetry.
-
-`decantr.ai` and `registry.decantr.ai` share one opaque first-party anonymous cookie when the browser allows it, so PostHog funnels can connect marketing CTAs to registry exploration and signup intent without collecting personal identifiers.
-
-## PostHog
+## Example
 
 ```ts
-import { createPostHogTelemetrySink, createTelemetryClient } from '@decantr/telemetry';
+import { createTelemetryClient } from '@decantr/telemetry';
 
 const telemetry = createTelemetryClient({
   context: {
-    source: 'api',
-    environment: 'production',
-    serviceName: 'decantr-api',
-    decantrVersion: '1.7.26',
+    source: 'cli',
+    environment: 'development',
+    serviceName: 'decantr-cli',
   },
-  sink: createPostHogTelemetrySink({
-    apiKey: process.env.POSTHOG_PROJECT_TOKEN!,
-    host: process.env.POSTHOG_HOST,
-  }),
 });
 
 await telemetry.capture({
-  name: 'registry.item.resolved',
-  context: {
-    source: 'api',
-    projectId: 'project_opaque_id',
-    orgId: 'org_opaque_id',
-    registrySource: 'official',
-  },
+  name: 'cli.command.completed',
   properties: {
-    contentType: 'pattern',
-    itemId: 'hero-split',
-    namespace: '@official',
+    command: 'content',
     success: true,
+    durationMs: 42,
   },
 });
 ```
 
-The PostHog sink uses opaque Decantr IDs as `distinct_id`, maps `orgId` and `projectId` to PostHog groups, and defaults `$process_person_profile` to `false`.
-
-## Future First-Party Dashboard
-
-The generic fetch sink is intended for a later Decantr-owned ingestion endpoint:
-
-```ts
-import { createFetchTelemetrySink, createTelemetryClient } from '@decantr/telemetry';
-
-const telemetry = createTelemetryClient({
-  sink: createFetchTelemetrySink({
-    endpoint: 'https://api.decantr.ai/v1/telemetry/events',
-    headers: () => ({ Authorization: `Bearer ${process.env.DECANTR_TELEMETRY_TOKEN}` }),
-  }),
-});
-```
+Constructing a client is explicit; the package does not auto-start collection.
 
-That endpoint can write raw events and daily rollups into Supabase or an analytics warehouse while PostHog remains the fast product analytics layer.
+See [security permissions](https://decantr.ai/reference/security-permissions.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/telemetry",
-  "version": "3.4.0",
+  "version": "3.8.0",
   "description": "Privacy-preserving telemetry contracts, clients, and analytics sinks for Decantr",
   "keywords": [
     "decantr",