@decantr/telemetry

Privacy-preserving telemetry contracts, clients, and analytics 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.

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, aggregate counts, marketing route labels, campaign tags, and referrer domains. Do not send prompts, source code, generated files, raw file paths, environment variables, secrets, API keys, email addresses, IP addresses, raw referrer URLs, click IDs, or user agents.

MVP Events

• cli.command.completed
• registry.item.resolved
• registry.sync.completed
• execution_pack.compiled
• execution_pack.selected
• audit.completed
• critique.completed
• content.validation.completed
• content.publish.completed
• user.signup.completed
• org.created
• api_key.created
• 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

Private registries do not need a separate telemetry surface yet. Use registry.item.resolved with registrySource: "private" and visibility: "private" when that product line lands.

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. Mutations are audit logged and 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, 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.

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

import { createPostHogTelemetrySink, createTelemetryClient } from '@decantr/telemetry';

const telemetry = createTelemetryClient({
  context: {
    source: 'api',
    environment: 'production',
    serviceName: 'decantr-api',
    decantrVersion: '1.7.26',
  },
  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',
  },
  properties: {
    contentType: 'pattern',
    itemId: 'hero-split',
    namespace: '@official',
    success: true,
  },
});

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:

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}` }),
  }),
});

That endpoint can write raw events and daily rollups into Supabase or an analytics warehouse while PostHog remains the fast product analytics layer.