@decantr/telemetry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decantr AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @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, and aggregate counts. Do not send prompts, source code, generated files, raw file paths, environment variables, secrets, API keys, email addresses, IP addresses, 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`
+
+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.
+
+## PostHog
+
+```ts
+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:
+
+```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}` }),
+  }),
+});
+```
+
+That endpoint can write raw events and daily rollups into Supabase or an analytics warehouse while PostHog remains the fast product analytics layer.

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+import { DecantrTelemetryEvent, TelemetryContext } from './events.js';
+import { TelemetryRedactionOptions } from './privacy.js';
+
+interface TelemetrySink {
+    capture(event: DecantrTelemetryEvent): Promise<void> | void;
+    flush?(): Promise<void> | void;
+}
+interface TelemetryClient {
+    capture(event: DecantrTelemetryEvent): Promise<void>;
+    flush(): Promise<void>;
+}
+interface TelemetryClientOptions {
+    context?: Partial<TelemetryContext>;
+    enabled?: boolean;
+    onError?: (error: unknown, event: DecantrTelemetryEvent) => void;
+    redaction?: TelemetryRedactionOptions;
+    sink?: TelemetrySink;
+}
+interface FetchTelemetrySinkOptions {
+    endpoint: string;
+    fetch?: typeof fetch;
+    headers?: HeadersInit | (() => HeadersInit);
+    timeoutMs?: number;
+}
+declare function createNoopTelemetrySink(): TelemetrySink;
+declare function createTelemetryClient(options?: TelemetryClientOptions): TelemetryClient;
+declare function createFetchTelemetrySink(options: FetchTelemetrySinkOptions): TelemetrySink;
+
+export { type FetchTelemetrySinkOptions, type TelemetryClient, type TelemetryClientOptions, type TelemetrySink, createFetchTelemetrySink, createNoopTelemetrySink, createTelemetryClient };

package/dist/client.js

@@ -0,0 +1,166 @@
+// src/events.ts
+var DECANTR_TELEMETRY_SCHEMA_VERSION = "0.1.0";
+
+// src/privacy.ts
+var REDACTED_VALUE = "[redacted]";
+var DEFAULT_MAX_STRING_LENGTH = 240;
+var DEFAULT_MAX_ARRAY_LENGTH = 25;
+var DEFAULT_MAX_OBJECT_KEYS = 80;
+var DEFAULT_MAX_DEPTH = 4;
+var SENSITIVE_KEY_PATTERNS = [
+  /^api[_-]?key$/i,
+  /^authorization$/i,
+  /^code$/i,
+  /^content$/i,
+  /^contents$/i,
+  /^cookie$/i,
+  /^cwd$/i,
+  /^email$/i,
+  /^env$/i,
+  /^file[_-]?contents$/i,
+  /^file[_-]?path$/i,
+  /^home$/i,
+  /^ip[_-]?address$/i,
+  /^password$/i,
+  /^path$/i,
+  /^prompt$/i,
+  /^raw[_-]?prompt$/i,
+  /^secret$/i,
+  /^source$/i,
+  /^source[_-]?code$/i,
+  /^token$/i,
+  /^url$/i,
+  /^user[_-]?agent$/i
+];
+function isSensitiveTelemetryKey(key, patterns = SENSITIVE_KEY_PATTERNS) {
+  return patterns.some((pattern) => pattern.test(key));
+}
+function sanitizeTelemetryValue(value, options = {}, depth = 0) {
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  if (depth > maxDepth) {
+    return options.redactedValue ?? REDACTED_VALUE;
+  }
+  if (typeof value === "string") {
+    const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
+    return value.length > maxStringLength ? `${value.slice(0, maxStringLength)}...` : value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || value === null) {
+    return value;
+  }
+  if (value === void 0) {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    const maxArrayLength = options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH;
+    return value.slice(0, maxArrayLength).map((entry) => sanitizeTelemetryValue(entry, options, depth + 1));
+  }
+  const redactedValue = options.redactedValue ?? REDACTED_VALUE;
+  const sensitiveKeyPatterns = options.sensitiveKeyPatterns ?? SENSITIVE_KEY_PATTERNS;
+  const maxObjectKeys = options.maxObjectKeys ?? DEFAULT_MAX_OBJECT_KEYS;
+  const entries = Object.entries(value).slice(0, maxObjectKeys);
+  const sanitized = {};
+  for (const [key, entryValue] of entries) {
+    sanitized[key] = isSensitiveTelemetryKey(key, sensitiveKeyPatterns) ? redactedValue : sanitizeTelemetryValue(entryValue, options, depth + 1);
+  }
+  return sanitized;
+}
+function sanitizeTelemetryEvent(event, options = {}) {
+  return {
+    ...event,
+    properties: sanitizeTelemetryValue(
+      event.properties,
+      options
+    )
+  };
+}
+
+// src/client.ts
+function createNoopTelemetrySink() {
+  return {
+    capture() {
+      return void 0;
+    }
+  };
+}
+function createTelemetryClient(options = {}) {
+  const enabled = options.enabled ?? true;
+  const sink = options.sink ?? createNoopTelemetrySink();
+  const pending = /* @__PURE__ */ new Set();
+  async function capture(event) {
+    if (!enabled) return;
+    const enriched = sanitizeTelemetryEvent(
+      {
+        ...event,
+        context: {
+          ...options.context,
+          ...event.context
+        },
+        timestamp: normalizeTimestamp(event.timestamp)
+      },
+      options.redaction
+    );
+    const promise = Promise.resolve().then(() => sink.capture(enriched)).catch((error) => {
+      options.onError?.(error, enriched);
+    }).then(() => void 0);
+    pending.add(promise);
+    promise.finally(() => pending.delete(promise));
+    await promise;
+  }
+  async function flush() {
+    await Promise.allSettled([...pending]);
+    await sink.flush?.();
+  }
+  return { capture, flush };
+}
+function createFetchTelemetrySink(options) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  return {
+    async capture(event) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+      try {
+        const response = await fetchImpl(options.endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...normalizeHeaders(
+              typeof options.headers === "function" ? options.headers() : options.headers
+            )
+          },
+          body: JSON.stringify({
+            schemaVersion: DECANTR_TELEMETRY_SCHEMA_VERSION,
+            event
+          }),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`Telemetry endpoint returned HTTP ${response.status}.`);
+        }
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
+function normalizeTimestamp(timestamp) {
+  if (timestamp instanceof Date) {
+    return timestamp.toISOString();
+  }
+  return timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
+}
+function normalizeHeaders(headers) {
+  if (!headers) return {};
+  if (headers instanceof Headers) {
+    return Object.fromEntries(headers.entries());
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return headers;
+}
+export {
+  createFetchTelemetrySink,
+  createNoopTelemetrySink,
+  createTelemetryClient
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/events.ts","../src/privacy.ts","../src/client.ts"],"sourcesContent":["export const DECANTR_TELEMETRY_SCHEMA_VERSION = '0.1.0';\n\nexport type TelemetrySource = 'api' | 'cli' | 'content-ci' | 'mcp' | 'registry-web';\nexport type TelemetryEnvironment = 'development' | 'preview' | 'production' | 'test';\nexport type RegistrySource = 'cache' | 'custom' | 'none' | 'official' | 'private';\nexport type WorkflowMode =\n  | 'brownfield-attach'\n  | 'greenfield-contract-only'\n  | 'greenfield-scaffold'\n  | 'hybrid-compose';\nexport type AdoptionMode = 'contract-only' | 'decantr-css' | 'style-bridge';\nexport type ProjectScope = 'single-app' | 'workspace-app';\nexport type TelemetryContentType = 'archetype' | 'blueprint' | 'pattern' | 'shell' | 'theme';\nexport type TelemetryVisibility = 'private' | 'public' | 'team';\nexport type TelemetryAnalysisScope = 'hosted' | 'local';\n\nexport const DECANTR_TELEMETRY_EVENT_NAMES = [\n  'api_key.created',\n  'audit.completed',\n  'cli.command.completed',\n  'content.publish.completed',\n  'content.validation.completed',\n  'critique.completed',\n  'execution_pack.compiled',\n  'execution_pack.selected',\n  'org.created',\n  'registry.item.resolved',\n  'registry.sync.completed',\n  'user.signup.completed',\n] as const;\n\nexport type DecantrTelemetryEventName = (typeof DECANTR_TELEMETRY_EVENT_NAMES)[number];\n\nexport type TelemetryPropertyValue =\n  | TelemetryPropertyValue[]\n  | boolean\n  | null\n  | number\n  | string\n  | undefined\n  | { [key: string]: TelemetryPropertyValue };\n\nexport type TelemetryProperties = Record<string, TelemetryPropertyValue>;\n\nexport interface TelemetryContext {\n  source: TelemetrySource;\n  environment?: TelemetryEnvironment;\n  serviceName?: string;\n  serviceVersion?: string;\n  decantrVersion?: string;\n  registrySource?: RegistrySource;\n  anonymousId?: string;\n  installId?: string;\n  projectId?: string;\n  sessionId?: string;\n  userId?: string;\n  orgId?: string;\n}\n\nexport interface TelemetryEventBase<\n  Name extends DecantrTelemetryEventName = DecantrTelemetryEventName,\n  Properties extends TelemetryProperties = TelemetryProperties,\n> {\n  name: Name;\n  context: TelemetryContext;\n  properties: Properties;\n  timestamp?: Date | string;\n}\n\nexport interface CliCommandCompletedProperties extends TelemetryProperties {\n  command: string;\n  success: boolean;\n  durationMs: number;\n  adoptionMode?: AdoptionMode;\n  errorCode?: string;\n  offline?: boolean;\n  projectScope?: ProjectScope;\n  registrySource?: RegistrySource;\n  targetFramework?: string;\n  workflowMode?: WorkflowMode;\n}\n\nexport interface RegistryItemResolvedProperties extends TelemetryProperties {\n  contentType: TelemetryContentType;\n  success: boolean;\n  cacheHit?: boolean;\n  durationMs?: number;\n  errorCode?: string;\n  itemId?: string;\n  namespace?: string;\n  registrySource?: RegistrySource;\n  version?: string;\n  visibility?: TelemetryVisibility;\n}\n\nexport interface RegistrySyncCompletedProperties extends TelemetryProperties {\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  registrySource?: RegistrySource;\n  totalItems?: number;\n}\n\nexport interface ExecutionPackCompiledProperties extends TelemetryProperties {\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  pageCount?: number;\n  patternCount?: number;\n  sectionCount?: number;\n  targetFramework?: string;\n}\n\nexport interface ExecutionPackSelectedProperties extends TelemetryProperties {\n  packType: 'mutation' | 'page' | 'review' | 'scaffold' | 'section';\n  success: boolean;\n  durationMs?: number;\n  errorCode?: string;\n  id?: string;\n}\n\nexport interface AuditCompletedProperties extends TelemetryProperties {\n  scope: TelemetryAnalysisScope;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorCount?: number;\n  pageCount?: number;\n  runtimePassed?: boolean;\n  score?: number;\n  warnCount?: number;\n}\n\nexport interface CritiqueCompletedProperties extends TelemetryProperties {\n  scope: TelemetryAnalysisScope;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorCount?: number;\n  infoCount?: number;\n  overall?: number;\n  warnCount?: number;\n}\n\nexport interface ContentValidationCompletedProperties extends TelemetryProperties {\n  valid: boolean;\n  contentType?: TelemetryContentType;\n  durationMs?: number;\n  errorCount?: number;\n  itemCount?: number;\n  warningCount?: number;\n}\n\nexport interface ContentPublishCompletedProperties extends TelemetryProperties {\n  contentType: TelemetryContentType;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  namespace?: string;\n  visibility?: TelemetryVisibility;\n}\n\nexport interface ProductEventProperties extends TelemetryProperties {\n  success?: boolean;\n  channel?: string;\n  entrypoint?: string;\n  plan?: string;\n}\n\nexport type DecantrTelemetryEvent =\n  | TelemetryEventBase<'api_key.created', ProductEventProperties>\n  | TelemetryEventBase<'audit.completed', AuditCompletedProperties>\n  | TelemetryEventBase<'cli.command.completed', CliCommandCompletedProperties>\n  | TelemetryEventBase<'content.publish.completed', ContentPublishCompletedProperties>\n  | TelemetryEventBase<'content.validation.completed', ContentValidationCompletedProperties>\n  | TelemetryEventBase<'critique.completed', CritiqueCompletedProperties>\n  | TelemetryEventBase<'execution_pack.compiled', ExecutionPackCompiledProperties>\n  | TelemetryEventBase<'execution_pack.selected', ExecutionPackSelectedProperties>\n  | TelemetryEventBase<'org.created', ProductEventProperties>\n  | TelemetryEventBase<'registry.item.resolved', RegistryItemResolvedProperties>\n  | TelemetryEventBase<'registry.sync.completed', RegistrySyncCompletedProperties>\n  | TelemetryEventBase<'user.signup.completed', ProductEventProperties>;\n\nexport function isDecantrTelemetryEventName(value: string): value is DecantrTelemetryEventName {\n  return (DECANTR_TELEMETRY_EVENT_NAMES as readonly string[]).includes(value);\n}\n","import type { DecantrTelemetryEvent, TelemetryPropertyValue } from './events.js';\n\nexport const REDACTED_VALUE = '[redacted]';\n\nconst DEFAULT_MAX_STRING_LENGTH = 240;\nconst DEFAULT_MAX_ARRAY_LENGTH = 25;\nconst DEFAULT_MAX_OBJECT_KEYS = 80;\nconst DEFAULT_MAX_DEPTH = 4;\n\nconst SENSITIVE_KEY_PATTERNS = [\n  /^api[_-]?key$/i,\n  /^authorization$/i,\n  /^code$/i,\n  /^content$/i,\n  /^contents$/i,\n  /^cookie$/i,\n  /^cwd$/i,\n  /^email$/i,\n  /^env$/i,\n  /^file[_-]?contents$/i,\n  /^file[_-]?path$/i,\n  /^home$/i,\n  /^ip[_-]?address$/i,\n  /^password$/i,\n  /^path$/i,\n  /^prompt$/i,\n  /^raw[_-]?prompt$/i,\n  /^secret$/i,\n  /^source$/i,\n  /^source[_-]?code$/i,\n  /^token$/i,\n  /^url$/i,\n  /^user[_-]?agent$/i,\n];\n\nexport interface TelemetryRedactionOptions {\n  maxArrayLength?: number;\n  maxDepth?: number;\n  maxObjectKeys?: number;\n  maxStringLength?: number;\n  redactedValue?: string;\n  sensitiveKeyPatterns?: RegExp[];\n}\n\nexport function isSensitiveTelemetryKey(key: string, patterns = SENSITIVE_KEY_PATTERNS): boolean {\n  return patterns.some((pattern) => pattern.test(key));\n}\n\nexport function sanitizeTelemetryValue(\n  value: TelemetryPropertyValue,\n  options: TelemetryRedactionOptions = {},\n  depth = 0,\n): TelemetryPropertyValue {\n  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;\n  if (depth > maxDepth) {\n    return options.redactedValue ?? REDACTED_VALUE;\n  }\n\n  if (typeof value === 'string') {\n    const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;\n    return value.length > maxStringLength ? `${value.slice(0, maxStringLength)}...` : value;\n  }\n\n  if (typeof value === 'number' || typeof value === 'boolean' || value === null) {\n    return value;\n  }\n\n  if (value === undefined) {\n    return null;\n  }\n\n  if (Array.isArray(value)) {\n    const maxArrayLength = options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH;\n    return value\n      .slice(0, maxArrayLength)\n      .map((entry) => sanitizeTelemetryValue(entry, options, depth + 1));\n  }\n\n  const redactedValue = options.redactedValue ?? REDACTED_VALUE;\n  const sensitiveKeyPatterns = options.sensitiveKeyPatterns ?? SENSITIVE_KEY_PATTERNS;\n  const maxObjectKeys = options.maxObjectKeys ?? DEFAULT_MAX_OBJECT_KEYS;\n  const entries = Object.entries(value).slice(0, maxObjectKeys);\n  const sanitized: Record<string, TelemetryPropertyValue> = {};\n\n  for (const [key, entryValue] of entries) {\n    sanitized[key] = isSensitiveTelemetryKey(key, sensitiveKeyPatterns)\n      ? redactedValue\n      : sanitizeTelemetryValue(entryValue, options, depth + 1);\n  }\n\n  return sanitized;\n}\n\nexport function sanitizeTelemetryEvent(\n  event: DecantrTelemetryEvent,\n  options: TelemetryRedactionOptions = {},\n): DecantrTelemetryEvent {\n  return {\n    ...event,\n    properties: sanitizeTelemetryValue(\n      event.properties,\n      options,\n    ) as DecantrTelemetryEvent['properties'],\n  } as DecantrTelemetryEvent;\n}\n","import {\n  DECANTR_TELEMETRY_SCHEMA_VERSION,\n  type DecantrTelemetryEvent,\n  type TelemetryContext,\n} from './events.js';\nimport { sanitizeTelemetryEvent, type TelemetryRedactionOptions } from './privacy.js';\n\nexport interface TelemetrySink {\n  capture(event: DecantrTelemetryEvent): Promise<void> | void;\n  flush?(): Promise<void> | void;\n}\n\nexport interface TelemetryClient {\n  capture(event: DecantrTelemetryEvent): Promise<void>;\n  flush(): Promise<void>;\n}\n\nexport interface TelemetryClientOptions {\n  context?: Partial<TelemetryContext>;\n  enabled?: boolean;\n  onError?: (error: unknown, event: DecantrTelemetryEvent) => void;\n  redaction?: TelemetryRedactionOptions;\n  sink?: TelemetrySink;\n}\n\nexport interface FetchTelemetrySinkOptions {\n  endpoint: string;\n  fetch?: typeof fetch;\n  headers?: HeadersInit | (() => HeadersInit);\n  timeoutMs?: number;\n}\n\nexport function createNoopTelemetrySink(): TelemetrySink {\n  return {\n    capture() {\n      return undefined;\n    },\n  };\n}\n\nexport function createTelemetryClient(options: TelemetryClientOptions = {}): TelemetryClient {\n  const enabled = options.enabled ?? true;\n  const sink = options.sink ?? createNoopTelemetrySink();\n  const pending = new Set<Promise<void>>();\n\n  async function capture(event: DecantrTelemetryEvent): Promise<void> {\n    if (!enabled) return;\n\n    const enriched = sanitizeTelemetryEvent(\n      {\n        ...event,\n        context: {\n          ...options.context,\n          ...event.context,\n        },\n        timestamp: normalizeTimestamp(event.timestamp),\n      } as DecantrTelemetryEvent,\n      options.redaction,\n    );\n\n    const promise = Promise.resolve()\n      .then(() => sink.capture(enriched))\n      .catch((error) => {\n        options.onError?.(error, enriched);\n      })\n      .then(() => undefined);\n\n    pending.add(promise);\n    promise.finally(() => pending.delete(promise));\n    await promise;\n  }\n\n  async function flush(): Promise<void> {\n    await Promise.allSettled([...pending]);\n    await sink.flush?.();\n  }\n\n  return { capture, flush };\n}\n\nexport function createFetchTelemetrySink(options: FetchTelemetrySinkOptions): TelemetrySink {\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n\n  return {\n    async capture(event) {\n      const controller = new AbortController();\n      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3000);\n\n      try {\n        const response = await fetchImpl(options.endpoint, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            ...normalizeHeaders(\n              typeof options.headers === 'function' ? options.headers() : options.headers,\n            ),\n          },\n          body: JSON.stringify({\n            schemaVersion: DECANTR_TELEMETRY_SCHEMA_VERSION,\n            event,\n          }),\n          signal: controller.signal,\n        });\n\n        if (!response.ok) {\n          throw new Error(`Telemetry endpoint returned HTTP ${response.status}.`);\n        }\n      } finally {\n        clearTimeout(timeout);\n      }\n    },\n  };\n}\n\nfunction normalizeTimestamp(timestamp: Date | string | undefined): string {\n  if (timestamp instanceof Date) {\n    return timestamp.toISOString();\n  }\n  return timestamp ?? new Date().toISOString();\n}\n\nfunction normalizeHeaders(headers: HeadersInit | undefined): Record<string, string> {\n  if (!headers) return {};\n\n  if (headers instanceof Headers) {\n    return Object.fromEntries(headers.entries());\n  }\n\n  if (Array.isArray(headers)) {\n    return Object.fromEntries(headers);\n  }\n\n  return headers as Record<string, string>;\n}\n"],"mappings":"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","names":[]}

package/dist/events.d.ts

@@ -0,0 +1,130 @@
+declare const DECANTR_TELEMETRY_SCHEMA_VERSION = "0.1.0";
+type TelemetrySource = 'api' | 'cli' | 'content-ci' | 'mcp' | 'registry-web';
+type TelemetryEnvironment = 'development' | 'preview' | 'production' | 'test';
+type RegistrySource = 'cache' | 'custom' | 'none' | 'official' | 'private';
+type WorkflowMode = 'brownfield-attach' | 'greenfield-contract-only' | 'greenfield-scaffold' | 'hybrid-compose';
+type AdoptionMode = 'contract-only' | 'decantr-css' | 'style-bridge';
+type ProjectScope = 'single-app' | 'workspace-app';
+type TelemetryContentType = 'archetype' | 'blueprint' | 'pattern' | 'shell' | 'theme';
+type TelemetryVisibility = 'private' | 'public' | 'team';
+type TelemetryAnalysisScope = 'hosted' | 'local';
+declare const DECANTR_TELEMETRY_EVENT_NAMES: readonly ["api_key.created", "audit.completed", "cli.command.completed", "content.publish.completed", "content.validation.completed", "critique.completed", "execution_pack.compiled", "execution_pack.selected", "org.created", "registry.item.resolved", "registry.sync.completed", "user.signup.completed"];
+type DecantrTelemetryEventName = (typeof DECANTR_TELEMETRY_EVENT_NAMES)[number];
+type TelemetryPropertyValue = TelemetryPropertyValue[] | boolean | null | number | string | undefined | {
+    [key: string]: TelemetryPropertyValue;
+};
+type TelemetryProperties = Record<string, TelemetryPropertyValue>;
+interface TelemetryContext {
+    source: TelemetrySource;
+    environment?: TelemetryEnvironment;
+    serviceName?: string;
+    serviceVersion?: string;
+    decantrVersion?: string;
+    registrySource?: RegistrySource;
+    anonymousId?: string;
+    installId?: string;
+    projectId?: string;
+    sessionId?: string;
+    userId?: string;
+    orgId?: string;
+}
+interface TelemetryEventBase<Name extends DecantrTelemetryEventName = DecantrTelemetryEventName, Properties extends TelemetryProperties = TelemetryProperties> {
+    name: Name;
+    context: TelemetryContext;
+    properties: Properties;
+    timestamp?: Date | string;
+}
+interface CliCommandCompletedProperties extends TelemetryProperties {
+    command: string;
+    success: boolean;
+    durationMs: number;
+    adoptionMode?: AdoptionMode;
+    errorCode?: string;
+    offline?: boolean;
+    projectScope?: ProjectScope;
+    registrySource?: RegistrySource;
+    targetFramework?: string;
+    workflowMode?: WorkflowMode;
+}
+interface RegistryItemResolvedProperties extends TelemetryProperties {
+    contentType: TelemetryContentType;
+    success: boolean;
+    cacheHit?: boolean;
+    durationMs?: number;
+    errorCode?: string;
+    itemId?: string;
+    namespace?: string;
+    registrySource?: RegistrySource;
+    version?: string;
+    visibility?: TelemetryVisibility;
+}
+interface RegistrySyncCompletedProperties extends TelemetryProperties {
+    success: boolean;
+    durationMs: number;
+    errorCode?: string;
+    registrySource?: RegistrySource;
+    totalItems?: number;
+}
+interface ExecutionPackCompiledProperties extends TelemetryProperties {
+    success: boolean;
+    durationMs: number;
+    errorCode?: string;
+    pageCount?: number;
+    patternCount?: number;
+    sectionCount?: number;
+    targetFramework?: string;
+}
+interface ExecutionPackSelectedProperties extends TelemetryProperties {
+    packType: 'mutation' | 'page' | 'review' | 'scaffold' | 'section';
+    success: boolean;
+    durationMs?: number;
+    errorCode?: string;
+    id?: string;
+}
+interface AuditCompletedProperties extends TelemetryProperties {
+    scope: TelemetryAnalysisScope;
+    success: boolean;
+    durationMs: number;
+    errorCode?: string;
+    errorCount?: number;
+    pageCount?: number;
+    runtimePassed?: boolean;
+    score?: number;
+    warnCount?: number;
+}
+interface CritiqueCompletedProperties extends TelemetryProperties {
+    scope: TelemetryAnalysisScope;
+    success: boolean;
+    durationMs: number;
+    errorCode?: string;
+    errorCount?: number;
+    infoCount?: number;
+    overall?: number;
+    warnCount?: number;
+}
+interface ContentValidationCompletedProperties extends TelemetryProperties {
+    valid: boolean;
+    contentType?: TelemetryContentType;
+    durationMs?: number;
+    errorCount?: number;
+    itemCount?: number;
+    warningCount?: number;
+}
+interface ContentPublishCompletedProperties extends TelemetryProperties {
+    contentType: TelemetryContentType;
+    success: boolean;
+    durationMs: number;
+    errorCode?: string;
+    namespace?: string;
+    visibility?: TelemetryVisibility;
+}
+interface ProductEventProperties extends TelemetryProperties {
+    success?: boolean;
+    channel?: string;
+    entrypoint?: string;
+    plan?: string;
+}
+type DecantrTelemetryEvent = TelemetryEventBase<'api_key.created', ProductEventProperties> | TelemetryEventBase<'audit.completed', AuditCompletedProperties> | TelemetryEventBase<'cli.command.completed', CliCommandCompletedProperties> | TelemetryEventBase<'content.publish.completed', ContentPublishCompletedProperties> | TelemetryEventBase<'content.validation.completed', ContentValidationCompletedProperties> | TelemetryEventBase<'critique.completed', CritiqueCompletedProperties> | TelemetryEventBase<'execution_pack.compiled', ExecutionPackCompiledProperties> | TelemetryEventBase<'execution_pack.selected', ExecutionPackSelectedProperties> | TelemetryEventBase<'org.created', ProductEventProperties> | TelemetryEventBase<'registry.item.resolved', RegistryItemResolvedProperties> | TelemetryEventBase<'registry.sync.completed', RegistrySyncCompletedProperties> | TelemetryEventBase<'user.signup.completed', ProductEventProperties>;
+declare function isDecantrTelemetryEventName(value: string): value is DecantrTelemetryEventName;
+
+export { type AdoptionMode, type AuditCompletedProperties, type CliCommandCompletedProperties, type ContentPublishCompletedProperties, type ContentValidationCompletedProperties, type CritiqueCompletedProperties, DECANTR_TELEMETRY_EVENT_NAMES, DECANTR_TELEMETRY_SCHEMA_VERSION, type DecantrTelemetryEvent, type DecantrTelemetryEventName, type ExecutionPackCompiledProperties, type ExecutionPackSelectedProperties, type ProductEventProperties, type ProjectScope, type RegistryItemResolvedProperties, type RegistrySource, type RegistrySyncCompletedProperties, type TelemetryAnalysisScope, type TelemetryContentType, type TelemetryContext, type TelemetryEnvironment, type TelemetryEventBase, type TelemetryProperties, type TelemetryPropertyValue, type TelemetrySource, type TelemetryVisibility, type WorkflowMode, isDecantrTelemetryEventName };

package/dist/events.js

@@ -0,0 +1,25 @@
+// src/events.ts
+var DECANTR_TELEMETRY_SCHEMA_VERSION = "0.1.0";
+var DECANTR_TELEMETRY_EVENT_NAMES = [
+  "api_key.created",
+  "audit.completed",
+  "cli.command.completed",
+  "content.publish.completed",
+  "content.validation.completed",
+  "critique.completed",
+  "execution_pack.compiled",
+  "execution_pack.selected",
+  "org.created",
+  "registry.item.resolved",
+  "registry.sync.completed",
+  "user.signup.completed"
+];
+function isDecantrTelemetryEventName(value) {
+  return DECANTR_TELEMETRY_EVENT_NAMES.includes(value);
+}
+export {
+  DECANTR_TELEMETRY_EVENT_NAMES,
+  DECANTR_TELEMETRY_SCHEMA_VERSION,
+  isDecantrTelemetryEventName
+};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/events.ts"],"sourcesContent":["export const DECANTR_TELEMETRY_SCHEMA_VERSION = '0.1.0';\n\nexport type TelemetrySource = 'api' | 'cli' | 'content-ci' | 'mcp' | 'registry-web';\nexport type TelemetryEnvironment = 'development' | 'preview' | 'production' | 'test';\nexport type RegistrySource = 'cache' | 'custom' | 'none' | 'official' | 'private';\nexport type WorkflowMode =\n  | 'brownfield-attach'\n  | 'greenfield-contract-only'\n  | 'greenfield-scaffold'\n  | 'hybrid-compose';\nexport type AdoptionMode = 'contract-only' | 'decantr-css' | 'style-bridge';\nexport type ProjectScope = 'single-app' | 'workspace-app';\nexport type TelemetryContentType = 'archetype' | 'blueprint' | 'pattern' | 'shell' | 'theme';\nexport type TelemetryVisibility = 'private' | 'public' | 'team';\nexport type TelemetryAnalysisScope = 'hosted' | 'local';\n\nexport const DECANTR_TELEMETRY_EVENT_NAMES = [\n  'api_key.created',\n  'audit.completed',\n  'cli.command.completed',\n  'content.publish.completed',\n  'content.validation.completed',\n  'critique.completed',\n  'execution_pack.compiled',\n  'execution_pack.selected',\n  'org.created',\n  'registry.item.resolved',\n  'registry.sync.completed',\n  'user.signup.completed',\n] as const;\n\nexport type DecantrTelemetryEventName = (typeof DECANTR_TELEMETRY_EVENT_NAMES)[number];\n\nexport type TelemetryPropertyValue =\n  | TelemetryPropertyValue[]\n  | boolean\n  | null\n  | number\n  | string\n  | undefined\n  | { [key: string]: TelemetryPropertyValue };\n\nexport type TelemetryProperties = Record<string, TelemetryPropertyValue>;\n\nexport interface TelemetryContext {\n  source: TelemetrySource;\n  environment?: TelemetryEnvironment;\n  serviceName?: string;\n  serviceVersion?: string;\n  decantrVersion?: string;\n  registrySource?: RegistrySource;\n  anonymousId?: string;\n  installId?: string;\n  projectId?: string;\n  sessionId?: string;\n  userId?: string;\n  orgId?: string;\n}\n\nexport interface TelemetryEventBase<\n  Name extends DecantrTelemetryEventName = DecantrTelemetryEventName,\n  Properties extends TelemetryProperties = TelemetryProperties,\n> {\n  name: Name;\n  context: TelemetryContext;\n  properties: Properties;\n  timestamp?: Date | string;\n}\n\nexport interface CliCommandCompletedProperties extends TelemetryProperties {\n  command: string;\n  success: boolean;\n  durationMs: number;\n  adoptionMode?: AdoptionMode;\n  errorCode?: string;\n  offline?: boolean;\n  projectScope?: ProjectScope;\n  registrySource?: RegistrySource;\n  targetFramework?: string;\n  workflowMode?: WorkflowMode;\n}\n\nexport interface RegistryItemResolvedProperties extends TelemetryProperties {\n  contentType: TelemetryContentType;\n  success: boolean;\n  cacheHit?: boolean;\n  durationMs?: number;\n  errorCode?: string;\n  itemId?: string;\n  namespace?: string;\n  registrySource?: RegistrySource;\n  version?: string;\n  visibility?: TelemetryVisibility;\n}\n\nexport interface RegistrySyncCompletedProperties extends TelemetryProperties {\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  registrySource?: RegistrySource;\n  totalItems?: number;\n}\n\nexport interface ExecutionPackCompiledProperties extends TelemetryProperties {\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  pageCount?: number;\n  patternCount?: number;\n  sectionCount?: number;\n  targetFramework?: string;\n}\n\nexport interface ExecutionPackSelectedProperties extends TelemetryProperties {\n  packType: 'mutation' | 'page' | 'review' | 'scaffold' | 'section';\n  success: boolean;\n  durationMs?: number;\n  errorCode?: string;\n  id?: string;\n}\n\nexport interface AuditCompletedProperties extends TelemetryProperties {\n  scope: TelemetryAnalysisScope;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorCount?: number;\n  pageCount?: number;\n  runtimePassed?: boolean;\n  score?: number;\n  warnCount?: number;\n}\n\nexport interface CritiqueCompletedProperties extends TelemetryProperties {\n  scope: TelemetryAnalysisScope;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorCount?: number;\n  infoCount?: number;\n  overall?: number;\n  warnCount?: number;\n}\n\nexport interface ContentValidationCompletedProperties extends TelemetryProperties {\n  valid: boolean;\n  contentType?: TelemetryContentType;\n  durationMs?: number;\n  errorCount?: number;\n  itemCount?: number;\n  warningCount?: number;\n}\n\nexport interface ContentPublishCompletedProperties extends TelemetryProperties {\n  contentType: TelemetryContentType;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  namespace?: string;\n  visibility?: TelemetryVisibility;\n}\n\nexport interface ProductEventProperties extends TelemetryProperties {\n  success?: boolean;\n  channel?: string;\n  entrypoint?: string;\n  plan?: string;\n}\n\nexport type DecantrTelemetryEvent =\n  | TelemetryEventBase<'api_key.created', ProductEventProperties>\n  | TelemetryEventBase<'audit.completed', AuditCompletedProperties>\n  | TelemetryEventBase<'cli.command.completed', CliCommandCompletedProperties>\n  | TelemetryEventBase<'content.publish.completed', ContentPublishCompletedProperties>\n  | TelemetryEventBase<'content.validation.completed', ContentValidationCompletedProperties>\n  | TelemetryEventBase<'critique.completed', CritiqueCompletedProperties>\n  | TelemetryEventBase<'execution_pack.compiled', ExecutionPackCompiledProperties>\n  | TelemetryEventBase<'execution_pack.selected', ExecutionPackSelectedProperties>\n  | TelemetryEventBase<'org.created', ProductEventProperties>\n  | TelemetryEventBase<'registry.item.resolved', RegistryItemResolvedProperties>\n  | TelemetryEventBase<'registry.sync.completed', RegistrySyncCompletedProperties>\n  | TelemetryEventBase<'user.signup.completed', ProductEventProperties>;\n\nexport function isDecantrTelemetryEventName(value: string): value is DecantrTelemetryEventName {\n  return (DECANTR_TELEMETRY_EVENT_NAMES as readonly string[]).includes(value);\n}\n"],"mappings":";AAAO,IAAM,mCAAmC;AAgBzC,IAAM,gCAAgC;AAAA,EAC3C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA0JO,SAAS,4BAA4B,OAAmD;AAC7F,SAAQ,8BAAoD,SAAS,KAAK;AAC5E;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { FetchTelemetrySinkOptions, TelemetryClient, TelemetryClientOptions, TelemetrySink, createFetchTelemetrySink, createNoopTelemetrySink, createTelemetryClient } from './client.js';
+export { AdoptionMode, AuditCompletedProperties, CliCommandCompletedProperties, ContentPublishCompletedProperties, ContentValidationCompletedProperties, CritiqueCompletedProperties, DECANTR_TELEMETRY_EVENT_NAMES, DECANTR_TELEMETRY_SCHEMA_VERSION, DecantrTelemetryEvent, DecantrTelemetryEventName, ExecutionPackCompiledProperties, ExecutionPackSelectedProperties, ProductEventProperties, ProjectScope, RegistryItemResolvedProperties, RegistrySource, RegistrySyncCompletedProperties, TelemetryAnalysisScope, TelemetryContentType, TelemetryContext, TelemetryEnvironment, TelemetryProperties, TelemetryPropertyValue, TelemetrySource, TelemetryVisibility, WorkflowMode, isDecantrTelemetryEventName } from './events.js';
+export { PostHogTelemetrySinkOptions, createPostHogTelemetrySink } from './posthog.js';
+export { REDACTED_VALUE, TelemetryRedactionOptions, isSensitiveTelemetryKey, sanitizeTelemetryEvent, sanitizeTelemetryValue } from './privacy.js';

package/dist/index.js

@@ -0,0 +1,248 @@
+// src/events.ts
+var DECANTR_TELEMETRY_SCHEMA_VERSION = "0.1.0";
+var DECANTR_TELEMETRY_EVENT_NAMES = [
+  "api_key.created",
+  "audit.completed",
+  "cli.command.completed",
+  "content.publish.completed",
+  "content.validation.completed",
+  "critique.completed",
+  "execution_pack.compiled",
+  "execution_pack.selected",
+  "org.created",
+  "registry.item.resolved",
+  "registry.sync.completed",
+  "user.signup.completed"
+];
+function isDecantrTelemetryEventName(value) {
+  return DECANTR_TELEMETRY_EVENT_NAMES.includes(value);
+}
+
+// src/privacy.ts
+var REDACTED_VALUE = "[redacted]";
+var DEFAULT_MAX_STRING_LENGTH = 240;
+var DEFAULT_MAX_ARRAY_LENGTH = 25;
+var DEFAULT_MAX_OBJECT_KEYS = 80;
+var DEFAULT_MAX_DEPTH = 4;
+var SENSITIVE_KEY_PATTERNS = [
+  /^api[_-]?key$/i,
+  /^authorization$/i,
+  /^code$/i,
+  /^content$/i,
+  /^contents$/i,
+  /^cookie$/i,
+  /^cwd$/i,
+  /^email$/i,
+  /^env$/i,
+  /^file[_-]?contents$/i,
+  /^file[_-]?path$/i,
+  /^home$/i,
+  /^ip[_-]?address$/i,
+  /^password$/i,
+  /^path$/i,
+  /^prompt$/i,
+  /^raw[_-]?prompt$/i,
+  /^secret$/i,
+  /^source$/i,
+  /^source[_-]?code$/i,
+  /^token$/i,
+  /^url$/i,
+  /^user[_-]?agent$/i
+];
+function isSensitiveTelemetryKey(key, patterns = SENSITIVE_KEY_PATTERNS) {
+  return patterns.some((pattern) => pattern.test(key));
+}
+function sanitizeTelemetryValue(value, options = {}, depth = 0) {
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  if (depth > maxDepth) {
+    return options.redactedValue ?? REDACTED_VALUE;
+  }
+  if (typeof value === "string") {
+    const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
+    return value.length > maxStringLength ? `${value.slice(0, maxStringLength)}...` : value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || value === null) {
+    return value;
+  }
+  if (value === void 0) {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    const maxArrayLength = options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH;
+    return value.slice(0, maxArrayLength).map((entry) => sanitizeTelemetryValue(entry, options, depth + 1));
+  }
+  const redactedValue = options.redactedValue ?? REDACTED_VALUE;
+  const sensitiveKeyPatterns = options.sensitiveKeyPatterns ?? SENSITIVE_KEY_PATTERNS;
+  const maxObjectKeys = options.maxObjectKeys ?? DEFAULT_MAX_OBJECT_KEYS;
+  const entries = Object.entries(value).slice(0, maxObjectKeys);
+  const sanitized = {};
+  for (const [key, entryValue] of entries) {
+    sanitized[key] = isSensitiveTelemetryKey(key, sensitiveKeyPatterns) ? redactedValue : sanitizeTelemetryValue(entryValue, options, depth + 1);
+  }
+  return sanitized;
+}
+function sanitizeTelemetryEvent(event, options = {}) {
+  return {
+    ...event,
+    properties: sanitizeTelemetryValue(
+      event.properties,
+      options
+    )
+  };
+}
+
+// src/client.ts
+function createNoopTelemetrySink() {
+  return {
+    capture() {
+      return void 0;
+    }
+  };
+}
+function createTelemetryClient(options = {}) {
+  const enabled = options.enabled ?? true;
+  const sink = options.sink ?? createNoopTelemetrySink();
+  const pending = /* @__PURE__ */ new Set();
+  async function capture(event) {
+    if (!enabled) return;
+    const enriched = sanitizeTelemetryEvent(
+      {
+        ...event,
+        context: {
+          ...options.context,
+          ...event.context
+        },
+        timestamp: normalizeTimestamp(event.timestamp)
+      },
+      options.redaction
+    );
+    const promise = Promise.resolve().then(() => sink.capture(enriched)).catch((error) => {
+      options.onError?.(error, enriched);
+    }).then(() => void 0);
+    pending.add(promise);
+    promise.finally(() => pending.delete(promise));
+    await promise;
+  }
+  async function flush() {
+    await Promise.allSettled([...pending]);
+    await sink.flush?.();
+  }
+  return { capture, flush };
+}
+function createFetchTelemetrySink(options) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  return {
+    async capture(event) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+      try {
+        const response = await fetchImpl(options.endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...normalizeHeaders(
+              typeof options.headers === "function" ? options.headers() : options.headers
+            )
+          },
+          body: JSON.stringify({
+            schemaVersion: DECANTR_TELEMETRY_SCHEMA_VERSION,
+            event
+          }),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`Telemetry endpoint returned HTTP ${response.status}.`);
+        }
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
+function normalizeTimestamp(timestamp) {
+  if (timestamp instanceof Date) {
+    return timestamp.toISOString();
+  }
+  return timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
+}
+function normalizeHeaders(headers) {
+  if (!headers) return {};
+  if (headers instanceof Headers) {
+    return Object.fromEntries(headers.entries());
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return headers;
+}
+
+// src/posthog.ts
+function createPostHogTelemetrySink(options) {
+  const host = (options.host ?? "https://us.i.posthog.com").replace(/\/+$/, "");
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  return {
+    async capture(event) {
+      const distinctId = resolveDistinctId(event);
+      if (!distinctId) {
+        throw new Error(
+          "PostHog telemetry requires an opaque user, install, project, or anonymous id."
+        );
+      }
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+      try {
+        const response = await fetchImpl(`${host}/i/v0/e/`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            api_key: options.apiKey,
+            event: event.name,
+            distinct_id: distinctId,
+            properties: toPostHogProperties(event, options),
+            timestamp: event.timestamp
+          }),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`PostHog capture returned HTTP ${response.status}.`);
+        }
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
+function resolveDistinctId(event) {
+  return event.context.userId ?? event.context.installId ?? event.context.projectId ?? event.context.anonymousId;
+}
+function toPostHogProperties(event, options) {
+  const groups = {};
+  if (event.context.orgId) groups.organization = event.context.orgId;
+  if (event.context.projectId) groups.project = event.context.projectId;
+  return {
+    ...event.properties,
+    $groups: groups,
+    $process_person_profile: options.processPersonProfile ?? false,
+    decantr_schema_version: DECANTR_TELEMETRY_SCHEMA_VERSION,
+    decantr_source: event.context.source,
+    decantr_environment: event.context.environment ?? "production",
+    decantr_version: event.context.decantrVersion ?? null,
+    registry_source: event.context.registrySource ?? null,
+    service_name: event.context.serviceName ?? null,
+    service_version: event.context.serviceVersion ?? null
+  };
+}
+export {
+  DECANTR_TELEMETRY_EVENT_NAMES,
+  DECANTR_TELEMETRY_SCHEMA_VERSION,
+  REDACTED_VALUE,
+  createFetchTelemetrySink,
+  createNoopTelemetrySink,
+  createPostHogTelemetrySink,
+  createTelemetryClient,
+  isDecantrTelemetryEventName,
+  isSensitiveTelemetryKey,
+  sanitizeTelemetryEvent,
+  sanitizeTelemetryValue
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/events.ts","../src/privacy.ts","../src/client.ts","../src/posthog.ts"],"sourcesContent":["export const DECANTR_TELEMETRY_SCHEMA_VERSION = '0.1.0';\n\nexport type TelemetrySource = 'api' | 'cli' | 'content-ci' | 'mcp' | 'registry-web';\nexport type TelemetryEnvironment = 'development' | 'preview' | 'production' | 'test';\nexport type RegistrySource = 'cache' | 'custom' | 'none' | 'official' | 'private';\nexport type WorkflowMode =\n  | 'brownfield-attach'\n  | 'greenfield-contract-only'\n  | 'greenfield-scaffold'\n  | 'hybrid-compose';\nexport type AdoptionMode = 'contract-only' | 'decantr-css' | 'style-bridge';\nexport type ProjectScope = 'single-app' | 'workspace-app';\nexport type TelemetryContentType = 'archetype' | 'blueprint' | 'pattern' | 'shell' | 'theme';\nexport type TelemetryVisibility = 'private' | 'public' | 'team';\nexport type TelemetryAnalysisScope = 'hosted' | 'local';\n\nexport const DECANTR_TELEMETRY_EVENT_NAMES = [\n  'api_key.created',\n  'audit.completed',\n  'cli.command.completed',\n  'content.publish.completed',\n  'content.validation.completed',\n  'critique.completed',\n  'execution_pack.compiled',\n  'execution_pack.selected',\n  'org.created',\n  'registry.item.resolved',\n  'registry.sync.completed',\n  'user.signup.completed',\n] as const;\n\nexport type DecantrTelemetryEventName = (typeof DECANTR_TELEMETRY_EVENT_NAMES)[number];\n\nexport type TelemetryPropertyValue =\n  | TelemetryPropertyValue[]\n  | boolean\n  | null\n  | number\n  | string\n  | undefined\n  | { [key: string]: TelemetryPropertyValue };\n\nexport type TelemetryProperties = Record<string, TelemetryPropertyValue>;\n\nexport interface TelemetryContext {\n  source: TelemetrySource;\n  environment?: TelemetryEnvironment;\n  serviceName?: string;\n  serviceVersion?: string;\n  decantrVersion?: string;\n  registrySource?: RegistrySource;\n  anonymousId?: string;\n  installId?: string;\n  projectId?: string;\n  sessionId?: string;\n  userId?: string;\n  orgId?: string;\n}\n\nexport interface TelemetryEventBase<\n  Name extends DecantrTelemetryEventName = DecantrTelemetryEventName,\n  Properties extends TelemetryProperties = TelemetryProperties,\n> {\n  name: Name;\n  context: TelemetryContext;\n  properties: Properties;\n  timestamp?: Date | string;\n}\n\nexport interface CliCommandCompletedProperties extends TelemetryProperties {\n  command: string;\n  success: boolean;\n  durationMs: number;\n  adoptionMode?: AdoptionMode;\n  errorCode?: string;\n  offline?: boolean;\n  projectScope?: ProjectScope;\n  registrySource?: RegistrySource;\n  targetFramework?: string;\n  workflowMode?: WorkflowMode;\n}\n\nexport interface RegistryItemResolvedProperties extends TelemetryProperties {\n  contentType: TelemetryContentType;\n  success: boolean;\n  cacheHit?: boolean;\n  durationMs?: number;\n  errorCode?: string;\n  itemId?: string;\n  namespace?: string;\n  registrySource?: RegistrySource;\n  version?: string;\n  visibility?: TelemetryVisibility;\n}\n\nexport interface RegistrySyncCompletedProperties extends TelemetryProperties {\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  registrySource?: RegistrySource;\n  totalItems?: number;\n}\n\nexport interface ExecutionPackCompiledProperties extends TelemetryProperties {\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  pageCount?: number;\n  patternCount?: number;\n  sectionCount?: number;\n  targetFramework?: string;\n}\n\nexport interface ExecutionPackSelectedProperties extends TelemetryProperties {\n  packType: 'mutation' | 'page' | 'review' | 'scaffold' | 'section';\n  success: boolean;\n  durationMs?: number;\n  errorCode?: string;\n  id?: string;\n}\n\nexport interface AuditCompletedProperties extends TelemetryProperties {\n  scope: TelemetryAnalysisScope;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorCount?: number;\n  pageCount?: number;\n  runtimePassed?: boolean;\n  score?: number;\n  warnCount?: number;\n}\n\nexport interface CritiqueCompletedProperties extends TelemetryProperties {\n  scope: TelemetryAnalysisScope;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorCount?: number;\n  infoCount?: number;\n  overall?: number;\n  warnCount?: number;\n}\n\nexport interface ContentValidationCompletedProperties extends TelemetryProperties {\n  valid: boolean;\n  contentType?: TelemetryContentType;\n  durationMs?: number;\n  errorCount?: number;\n  itemCount?: number;\n  warningCount?: number;\n}\n\nexport interface ContentPublishCompletedProperties extends TelemetryProperties {\n  contentType: TelemetryContentType;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  namespace?: string;\n  visibility?: TelemetryVisibility;\n}\n\nexport interface ProductEventProperties extends TelemetryProperties {\n  success?: boolean;\n  channel?: string;\n  entrypoint?: string;\n  plan?: string;\n}\n\nexport type DecantrTelemetryEvent =\n  | TelemetryEventBase<'api_key.created', ProductEventProperties>\n  | TelemetryEventBase<'audit.completed', AuditCompletedProperties>\n  | TelemetryEventBase<'cli.command.completed', CliCommandCompletedProperties>\n  | TelemetryEventBase<'content.publish.completed', ContentPublishCompletedProperties>\n  | TelemetryEventBase<'content.validation.completed', ContentValidationCompletedProperties>\n  | TelemetryEventBase<'critique.completed', CritiqueCompletedProperties>\n  | TelemetryEventBase<'execution_pack.compiled', ExecutionPackCompiledProperties>\n  | TelemetryEventBase<'execution_pack.selected', ExecutionPackSelectedProperties>\n  | TelemetryEventBase<'org.created', ProductEventProperties>\n  | TelemetryEventBase<'registry.item.resolved', RegistryItemResolvedProperties>\n  | TelemetryEventBase<'registry.sync.completed', RegistrySyncCompletedProperties>\n  | TelemetryEventBase<'user.signup.completed', ProductEventProperties>;\n\nexport function isDecantrTelemetryEventName(value: string): value is DecantrTelemetryEventName {\n  return (DECANTR_TELEMETRY_EVENT_NAMES as readonly string[]).includes(value);\n}\n","import type { DecantrTelemetryEvent, TelemetryPropertyValue } from './events.js';\n\nexport const REDACTED_VALUE = '[redacted]';\n\nconst DEFAULT_MAX_STRING_LENGTH = 240;\nconst DEFAULT_MAX_ARRAY_LENGTH = 25;\nconst DEFAULT_MAX_OBJECT_KEYS = 80;\nconst DEFAULT_MAX_DEPTH = 4;\n\nconst SENSITIVE_KEY_PATTERNS = [\n  /^api[_-]?key$/i,\n  /^authorization$/i,\n  /^code$/i,\n  /^content$/i,\n  /^contents$/i,\n  /^cookie$/i,\n  /^cwd$/i,\n  /^email$/i,\n  /^env$/i,\n  /^file[_-]?contents$/i,\n  /^file[_-]?path$/i,\n  /^home$/i,\n  /^ip[_-]?address$/i,\n  /^password$/i,\n  /^path$/i,\n  /^prompt$/i,\n  /^raw[_-]?prompt$/i,\n  /^secret$/i,\n  /^source$/i,\n  /^source[_-]?code$/i,\n  /^token$/i,\n  /^url$/i,\n  /^user[_-]?agent$/i,\n];\n\nexport interface TelemetryRedactionOptions {\n  maxArrayLength?: number;\n  maxDepth?: number;\n  maxObjectKeys?: number;\n  maxStringLength?: number;\n  redactedValue?: string;\n  sensitiveKeyPatterns?: RegExp[];\n}\n\nexport function isSensitiveTelemetryKey(key: string, patterns = SENSITIVE_KEY_PATTERNS): boolean {\n  return patterns.some((pattern) => pattern.test(key));\n}\n\nexport function sanitizeTelemetryValue(\n  value: TelemetryPropertyValue,\n  options: TelemetryRedactionOptions = {},\n  depth = 0,\n): TelemetryPropertyValue {\n  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;\n  if (depth > maxDepth) {\n    return options.redactedValue ?? REDACTED_VALUE;\n  }\n\n  if (typeof value === 'string') {\n    const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;\n    return value.length > maxStringLength ? `${value.slice(0, maxStringLength)}...` : value;\n  }\n\n  if (typeof value === 'number' || typeof value === 'boolean' || value === null) {\n    return value;\n  }\n\n  if (value === undefined) {\n    return null;\n  }\n\n  if (Array.isArray(value)) {\n    const maxArrayLength = options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH;\n    return value\n      .slice(0, maxArrayLength)\n      .map((entry) => sanitizeTelemetryValue(entry, options, depth + 1));\n  }\n\n  const redactedValue = options.redactedValue ?? REDACTED_VALUE;\n  const sensitiveKeyPatterns = options.sensitiveKeyPatterns ?? SENSITIVE_KEY_PATTERNS;\n  const maxObjectKeys = options.maxObjectKeys ?? DEFAULT_MAX_OBJECT_KEYS;\n  const entries = Object.entries(value).slice(0, maxObjectKeys);\n  const sanitized: Record<string, TelemetryPropertyValue> = {};\n\n  for (const [key, entryValue] of entries) {\n    sanitized[key] = isSensitiveTelemetryKey(key, sensitiveKeyPatterns)\n      ? redactedValue\n      : sanitizeTelemetryValue(entryValue, options, depth + 1);\n  }\n\n  return sanitized;\n}\n\nexport function sanitizeTelemetryEvent(\n  event: DecantrTelemetryEvent,\n  options: TelemetryRedactionOptions = {},\n): DecantrTelemetryEvent {\n  return {\n    ...event,\n    properties: sanitizeTelemetryValue(\n      event.properties,\n      options,\n    ) as DecantrTelemetryEvent['properties'],\n  } as DecantrTelemetryEvent;\n}\n","import {\n  DECANTR_TELEMETRY_SCHEMA_VERSION,\n  type DecantrTelemetryEvent,\n  type TelemetryContext,\n} from './events.js';\nimport { sanitizeTelemetryEvent, type TelemetryRedactionOptions } from './privacy.js';\n\nexport interface TelemetrySink {\n  capture(event: DecantrTelemetryEvent): Promise<void> | void;\n  flush?(): Promise<void> | void;\n}\n\nexport interface TelemetryClient {\n  capture(event: DecantrTelemetryEvent): Promise<void>;\n  flush(): Promise<void>;\n}\n\nexport interface TelemetryClientOptions {\n  context?: Partial<TelemetryContext>;\n  enabled?: boolean;\n  onError?: (error: unknown, event: DecantrTelemetryEvent) => void;\n  redaction?: TelemetryRedactionOptions;\n  sink?: TelemetrySink;\n}\n\nexport interface FetchTelemetrySinkOptions {\n  endpoint: string;\n  fetch?: typeof fetch;\n  headers?: HeadersInit | (() => HeadersInit);\n  timeoutMs?: number;\n}\n\nexport function createNoopTelemetrySink(): TelemetrySink {\n  return {\n    capture() {\n      return undefined;\n    },\n  };\n}\n\nexport function createTelemetryClient(options: TelemetryClientOptions = {}): TelemetryClient {\n  const enabled = options.enabled ?? true;\n  const sink = options.sink ?? createNoopTelemetrySink();\n  const pending = new Set<Promise<void>>();\n\n  async function capture(event: DecantrTelemetryEvent): Promise<void> {\n    if (!enabled) return;\n\n    const enriched = sanitizeTelemetryEvent(\n      {\n        ...event,\n        context: {\n          ...options.context,\n          ...event.context,\n        },\n        timestamp: normalizeTimestamp(event.timestamp),\n      } as DecantrTelemetryEvent,\n      options.redaction,\n    );\n\n    const promise = Promise.resolve()\n      .then(() => sink.capture(enriched))\n      .catch((error) => {\n        options.onError?.(error, enriched);\n      })\n      .then(() => undefined);\n\n    pending.add(promise);\n    promise.finally(() => pending.delete(promise));\n    await promise;\n  }\n\n  async function flush(): Promise<void> {\n    await Promise.allSettled([...pending]);\n    await sink.flush?.();\n  }\n\n  return { capture, flush };\n}\n\nexport function createFetchTelemetrySink(options: FetchTelemetrySinkOptions): TelemetrySink {\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n\n  return {\n    async capture(event) {\n      const controller = new AbortController();\n      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3000);\n\n      try {\n        const response = await fetchImpl(options.endpoint, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            ...normalizeHeaders(\n              typeof options.headers === 'function' ? options.headers() : options.headers,\n            ),\n          },\n          body: JSON.stringify({\n            schemaVersion: DECANTR_TELEMETRY_SCHEMA_VERSION,\n            event,\n          }),\n          signal: controller.signal,\n        });\n\n        if (!response.ok) {\n          throw new Error(`Telemetry endpoint returned HTTP ${response.status}.`);\n        }\n      } finally {\n        clearTimeout(timeout);\n      }\n    },\n  };\n}\n\nfunction normalizeTimestamp(timestamp: Date | string | undefined): string {\n  if (timestamp instanceof Date) {\n    return timestamp.toISOString();\n  }\n  return timestamp ?? new Date().toISOString();\n}\n\nfunction normalizeHeaders(headers: HeadersInit | undefined): Record<string, string> {\n  if (!headers) return {};\n\n  if (headers instanceof Headers) {\n    return Object.fromEntries(headers.entries());\n  }\n\n  if (Array.isArray(headers)) {\n    return Object.fromEntries(headers);\n  }\n\n  return headers as Record<string, string>;\n}\n","import type { TelemetrySink } from './client.js';\nimport {\n  DECANTR_TELEMETRY_SCHEMA_VERSION,\n  type DecantrTelemetryEvent,\n  type TelemetryProperties,\n} from './events.js';\n\nexport interface PostHogTelemetrySinkOptions {\n  apiKey: string;\n  fetch?: typeof fetch;\n  host?: string;\n  processPersonProfile?: boolean;\n  timeoutMs?: number;\n}\n\nexport function createPostHogTelemetrySink(options: PostHogTelemetrySinkOptions): TelemetrySink {\n  const host = (options.host ?? 'https://us.i.posthog.com').replace(/\\/+$/, '');\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n\n  return {\n    async capture(event) {\n      const distinctId = resolveDistinctId(event);\n      if (!distinctId) {\n        throw new Error(\n          'PostHog telemetry requires an opaque user, install, project, or anonymous id.',\n        );\n      }\n\n      const controller = new AbortController();\n      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3000);\n\n      try {\n        const response = await fetchImpl(`${host}/i/v0/e/`, {\n          method: 'POST',\n          headers: { 'Content-Type': 'application/json' },\n          body: JSON.stringify({\n            api_key: options.apiKey,\n            event: event.name,\n            distinct_id: distinctId,\n            properties: toPostHogProperties(event, options),\n            timestamp: event.timestamp,\n          }),\n          signal: controller.signal,\n        });\n\n        if (!response.ok) {\n          throw new Error(`PostHog capture returned HTTP ${response.status}.`);\n        }\n      } finally {\n        clearTimeout(timeout);\n      }\n    },\n  };\n}\n\nfunction resolveDistinctId(event: DecantrTelemetryEvent): string | undefined {\n  return (\n    event.context.userId ??\n    event.context.installId ??\n    event.context.projectId ??\n    event.context.anonymousId\n  );\n}\n\nfunction toPostHogProperties(\n  event: DecantrTelemetryEvent,\n  options: PostHogTelemetrySinkOptions,\n): TelemetryProperties {\n  const groups: Record<string, string> = {};\n  if (event.context.orgId) groups.organization = event.context.orgId;\n  if (event.context.projectId) groups.project = event.context.projectId;\n\n  return {\n    ...event.properties,\n    $groups: groups,\n    $process_person_profile: options.processPersonProfile ?? false,\n    decantr_schema_version: DECANTR_TELEMETRY_SCHEMA_VERSION,\n    decantr_source: event.context.source,\n    decantr_environment: event.context.environment ?? 'production',\n    decantr_version: event.context.decantrVersion ?? null,\n    registry_source: event.context.registrySource ?? null,\n    service_name: event.context.serviceName ?? null,\n    service_version: event.context.serviceVersion ?? null,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/posthog.d.ts

@@ -0,0 +1,14 @@
+import { TelemetrySink } from './client.js';
+import './events.js';
+import './privacy.js';
+
+interface PostHogTelemetrySinkOptions {
+    apiKey: string;
+    fetch?: typeof fetch;
+    host?: string;
+    processPersonProfile?: boolean;
+    timeoutMs?: number;
+}
+declare function createPostHogTelemetrySink(options: PostHogTelemetrySinkOptions): TelemetrySink;
+
+export { type PostHogTelemetrySinkOptions, createPostHogTelemetrySink };

package/dist/posthog.js

@@ -0,0 +1,63 @@
+// src/events.ts
+var DECANTR_TELEMETRY_SCHEMA_VERSION = "0.1.0";
+
+// src/posthog.ts
+function createPostHogTelemetrySink(options) {
+  const host = (options.host ?? "https://us.i.posthog.com").replace(/\/+$/, "");
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  return {
+    async capture(event) {
+      const distinctId = resolveDistinctId(event);
+      if (!distinctId) {
+        throw new Error(
+          "PostHog telemetry requires an opaque user, install, project, or anonymous id."
+        );
+      }
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+      try {
+        const response = await fetchImpl(`${host}/i/v0/e/`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            api_key: options.apiKey,
+            event: event.name,
+            distinct_id: distinctId,
+            properties: toPostHogProperties(event, options),
+            timestamp: event.timestamp
+          }),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`PostHog capture returned HTTP ${response.status}.`);
+        }
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
+function resolveDistinctId(event) {
+  return event.context.userId ?? event.context.installId ?? event.context.projectId ?? event.context.anonymousId;
+}
+function toPostHogProperties(event, options) {
+  const groups = {};
+  if (event.context.orgId) groups.organization = event.context.orgId;
+  if (event.context.projectId) groups.project = event.context.projectId;
+  return {
+    ...event.properties,
+    $groups: groups,
+    $process_person_profile: options.processPersonProfile ?? false,
+    decantr_schema_version: DECANTR_TELEMETRY_SCHEMA_VERSION,
+    decantr_source: event.context.source,
+    decantr_environment: event.context.environment ?? "production",
+    decantr_version: event.context.decantrVersion ?? null,
+    registry_source: event.context.registrySource ?? null,
+    service_name: event.context.serviceName ?? null,
+    service_version: event.context.serviceVersion ?? null
+  };
+}
+export {
+  createPostHogTelemetrySink
+};
+//# sourceMappingURL=posthog.js.map

package/dist/posthog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/events.ts","../src/posthog.ts"],"sourcesContent":["export const DECANTR_TELEMETRY_SCHEMA_VERSION = '0.1.0';\n\nexport type TelemetrySource = 'api' | 'cli' | 'content-ci' | 'mcp' | 'registry-web';\nexport type TelemetryEnvironment = 'development' | 'preview' | 'production' | 'test';\nexport type RegistrySource = 'cache' | 'custom' | 'none' | 'official' | 'private';\nexport type WorkflowMode =\n  | 'brownfield-attach'\n  | 'greenfield-contract-only'\n  | 'greenfield-scaffold'\n  | 'hybrid-compose';\nexport type AdoptionMode = 'contract-only' | 'decantr-css' | 'style-bridge';\nexport type ProjectScope = 'single-app' | 'workspace-app';\nexport type TelemetryContentType = 'archetype' | 'blueprint' | 'pattern' | 'shell' | 'theme';\nexport type TelemetryVisibility = 'private' | 'public' | 'team';\nexport type TelemetryAnalysisScope = 'hosted' | 'local';\n\nexport const DECANTR_TELEMETRY_EVENT_NAMES = [\n  'api_key.created',\n  'audit.completed',\n  'cli.command.completed',\n  'content.publish.completed',\n  'content.validation.completed',\n  'critique.completed',\n  'execution_pack.compiled',\n  'execution_pack.selected',\n  'org.created',\n  'registry.item.resolved',\n  'registry.sync.completed',\n  'user.signup.completed',\n] as const;\n\nexport type DecantrTelemetryEventName = (typeof DECANTR_TELEMETRY_EVENT_NAMES)[number];\n\nexport type TelemetryPropertyValue =\n  | TelemetryPropertyValue[]\n  | boolean\n  | null\n  | number\n  | string\n  | undefined\n  | { [key: string]: TelemetryPropertyValue };\n\nexport type TelemetryProperties = Record<string, TelemetryPropertyValue>;\n\nexport interface TelemetryContext {\n  source: TelemetrySource;\n  environment?: TelemetryEnvironment;\n  serviceName?: string;\n  serviceVersion?: string;\n  decantrVersion?: string;\n  registrySource?: RegistrySource;\n  anonymousId?: string;\n  installId?: string;\n  projectId?: string;\n  sessionId?: string;\n  userId?: string;\n  orgId?: string;\n}\n\nexport interface TelemetryEventBase<\n  Name extends DecantrTelemetryEventName = DecantrTelemetryEventName,\n  Properties extends TelemetryProperties = TelemetryProperties,\n> {\n  name: Name;\n  context: TelemetryContext;\n  properties: Properties;\n  timestamp?: Date | string;\n}\n\nexport interface CliCommandCompletedProperties extends TelemetryProperties {\n  command: string;\n  success: boolean;\n  durationMs: number;\n  adoptionMode?: AdoptionMode;\n  errorCode?: string;\n  offline?: boolean;\n  projectScope?: ProjectScope;\n  registrySource?: RegistrySource;\n  targetFramework?: string;\n  workflowMode?: WorkflowMode;\n}\n\nexport interface RegistryItemResolvedProperties extends TelemetryProperties {\n  contentType: TelemetryContentType;\n  success: boolean;\n  cacheHit?: boolean;\n  durationMs?: number;\n  errorCode?: string;\n  itemId?: string;\n  namespace?: string;\n  registrySource?: RegistrySource;\n  version?: string;\n  visibility?: TelemetryVisibility;\n}\n\nexport interface RegistrySyncCompletedProperties extends TelemetryProperties {\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  registrySource?: RegistrySource;\n  totalItems?: number;\n}\n\nexport interface ExecutionPackCompiledProperties extends TelemetryProperties {\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  pageCount?: number;\n  patternCount?: number;\n  sectionCount?: number;\n  targetFramework?: string;\n}\n\nexport interface ExecutionPackSelectedProperties extends TelemetryProperties {\n  packType: 'mutation' | 'page' | 'review' | 'scaffold' | 'section';\n  success: boolean;\n  durationMs?: number;\n  errorCode?: string;\n  id?: string;\n}\n\nexport interface AuditCompletedProperties extends TelemetryProperties {\n  scope: TelemetryAnalysisScope;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorCount?: number;\n  pageCount?: number;\n  runtimePassed?: boolean;\n  score?: number;\n  warnCount?: number;\n}\n\nexport interface CritiqueCompletedProperties extends TelemetryProperties {\n  scope: TelemetryAnalysisScope;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorCount?: number;\n  infoCount?: number;\n  overall?: number;\n  warnCount?: number;\n}\n\nexport interface ContentValidationCompletedProperties extends TelemetryProperties {\n  valid: boolean;\n  contentType?: TelemetryContentType;\n  durationMs?: number;\n  errorCount?: number;\n  itemCount?: number;\n  warningCount?: number;\n}\n\nexport interface ContentPublishCompletedProperties extends TelemetryProperties {\n  contentType: TelemetryContentType;\n  success: boolean;\n  durationMs: number;\n  errorCode?: string;\n  namespace?: string;\n  visibility?: TelemetryVisibility;\n}\n\nexport interface ProductEventProperties extends TelemetryProperties {\n  success?: boolean;\n  channel?: string;\n  entrypoint?: string;\n  plan?: string;\n}\n\nexport type DecantrTelemetryEvent =\n  | TelemetryEventBase<'api_key.created', ProductEventProperties>\n  | TelemetryEventBase<'audit.completed', AuditCompletedProperties>\n  | TelemetryEventBase<'cli.command.completed', CliCommandCompletedProperties>\n  | TelemetryEventBase<'content.publish.completed', ContentPublishCompletedProperties>\n  | TelemetryEventBase<'content.validation.completed', ContentValidationCompletedProperties>\n  | TelemetryEventBase<'critique.completed', CritiqueCompletedProperties>\n  | TelemetryEventBase<'execution_pack.compiled', ExecutionPackCompiledProperties>\n  | TelemetryEventBase<'execution_pack.selected', ExecutionPackSelectedProperties>\n  | TelemetryEventBase<'org.created', ProductEventProperties>\n  | TelemetryEventBase<'registry.item.resolved', RegistryItemResolvedProperties>\n  | TelemetryEventBase<'registry.sync.completed', RegistrySyncCompletedProperties>\n  | TelemetryEventBase<'user.signup.completed', ProductEventProperties>;\n\nexport function isDecantrTelemetryEventName(value: string): value is DecantrTelemetryEventName {\n  return (DECANTR_TELEMETRY_EVENT_NAMES as readonly string[]).includes(value);\n}\n","import type { TelemetrySink } from './client.js';\nimport {\n  DECANTR_TELEMETRY_SCHEMA_VERSION,\n  type DecantrTelemetryEvent,\n  type TelemetryProperties,\n} from './events.js';\n\nexport interface PostHogTelemetrySinkOptions {\n  apiKey: string;\n  fetch?: typeof fetch;\n  host?: string;\n  processPersonProfile?: boolean;\n  timeoutMs?: number;\n}\n\nexport function createPostHogTelemetrySink(options: PostHogTelemetrySinkOptions): TelemetrySink {\n  const host = (options.host ?? 'https://us.i.posthog.com').replace(/\\/+$/, '');\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n\n  return {\n    async capture(event) {\n      const distinctId = resolveDistinctId(event);\n      if (!distinctId) {\n        throw new Error(\n          'PostHog telemetry requires an opaque user, install, project, or anonymous id.',\n        );\n      }\n\n      const controller = new AbortController();\n      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3000);\n\n      try {\n        const response = await fetchImpl(`${host}/i/v0/e/`, {\n          method: 'POST',\n          headers: { 'Content-Type': 'application/json' },\n          body: JSON.stringify({\n            api_key: options.apiKey,\n            event: event.name,\n            distinct_id: distinctId,\n            properties: toPostHogProperties(event, options),\n            timestamp: event.timestamp,\n          }),\n          signal: controller.signal,\n        });\n\n        if (!response.ok) {\n          throw new Error(`PostHog capture returned HTTP ${response.status}.`);\n        }\n      } finally {\n        clearTimeout(timeout);\n      }\n    },\n  };\n}\n\nfunction resolveDistinctId(event: DecantrTelemetryEvent): string | undefined {\n  return (\n    event.context.userId ??\n    event.context.installId ??\n    event.context.projectId ??\n    event.context.anonymousId\n  );\n}\n\nfunction toPostHogProperties(\n  event: DecantrTelemetryEvent,\n  options: PostHogTelemetrySinkOptions,\n): TelemetryProperties {\n  const groups: Record<string, string> = {};\n  if (event.context.orgId) groups.organization = event.context.orgId;\n  if (event.context.projectId) groups.project = event.context.projectId;\n\n  return {\n    ...event.properties,\n    $groups: groups,\n    $process_person_profile: options.processPersonProfile ?? false,\n    decantr_schema_version: DECANTR_TELEMETRY_SCHEMA_VERSION,\n    decantr_source: event.context.source,\n    decantr_environment: event.context.environment ?? 'production',\n    decantr_version: event.context.decantrVersion ?? null,\n    registry_source: event.context.registrySource ?? null,\n    service_name: event.context.serviceName ?? null,\n    service_version: event.context.serviceVersion ?? null,\n  };\n}\n"],"mappings":";AAAO,IAAM,mCAAmC;;;ACezC,SAAS,2BAA2B,SAAqD;AAC9F,QAAM,QAAQ,QAAQ,QAAQ,4BAA4B,QAAQ,QAAQ,EAAE;AAC5E,QAAM,YAAY,QAAQ,SAAS,WAAW;AAE9C,SAAO;AAAA,IACL,MAAM,QAAQ,OAAO;AACnB,YAAM,aAAa,kBAAkB,KAAK;AAC1C,UAAI,CAAC,YAAY;AACf,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AAEA,YAAM,aAAa,IAAI,gBAAgB;AACvC,YAAM,UAAU,WAAW,MAAM,WAAW,MAAM,GAAG,QAAQ,aAAa,GAAI;AAE9E,UAAI;AACF,cAAM,WAAW,MAAM,UAAU,GAAG,IAAI,YAAY;AAAA,UAClD,QAAQ;AAAA,UACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,UAC9C,MAAM,KAAK,UAAU;AAAA,YACnB,SAAS,QAAQ;AAAA,YACjB,OAAO,MAAM;AAAA,YACb,aAAa;AAAA,YACb,YAAY,oBAAoB,OAAO,OAAO;AAAA,YAC9C,WAAW,MAAM;AAAA,UACnB,CAAC;AAAA,UACD,QAAQ,WAAW;AAAA,QACrB,CAAC;AAED,YAAI,CAAC,SAAS,IAAI;AAChB,gBAAM,IAAI,MAAM,iCAAiC,SAAS,MAAM,GAAG;AAAA,QACrE;AAAA,MACF,UAAE;AACA,qBAAa,OAAO;AAAA,MACtB;AAAA,IACF;AAAA,EACF;AACF;AAEA,SAAS,kBAAkB,OAAkD;AAC3E,SACE,MAAM,QAAQ,UACd,MAAM,QAAQ,aACd,MAAM,QAAQ,aACd,MAAM,QAAQ;AAElB;AAEA,SAAS,oBACP,OACA,SACqB;AACrB,QAAM,SAAiC,CAAC;AACxC,MAAI,MAAM,QAAQ,MAAO,QAAO,eAAe,MAAM,QAAQ;AAC7D,MAAI,MAAM,QAAQ,UAAW,QAAO,UAAU,MAAM,QAAQ;AAE5D,SAAO;AAAA,IACL,GAAG,MAAM;AAAA,IACT,SAAS;AAAA,IACT,yBAAyB,QAAQ,wBAAwB;AAAA,IACzD,wBAAwB;AAAA,IACxB,gBAAgB,MAAM,QAAQ;AAAA,IAC9B,qBAAqB,MAAM,QAAQ,eAAe;AAAA,IAClD,iBAAiB,MAAM,QAAQ,kBAAkB;AAAA,IACjD,iBAAiB,MAAM,QAAQ,kBAAkB;AAAA,IACjD,cAAc,MAAM,QAAQ,eAAe;AAAA,IAC3C,iBAAiB,MAAM,QAAQ,kBAAkB;AAAA,EACnD;AACF;","names":[]}

package/dist/privacy.d.ts

@@ -0,0 +1,16 @@
+import { DecantrTelemetryEvent, TelemetryPropertyValue } from './events.js';
+
+declare const REDACTED_VALUE = "[redacted]";
+interface TelemetryRedactionOptions {
+    maxArrayLength?: number;
+    maxDepth?: number;
+    maxObjectKeys?: number;
+    maxStringLength?: number;
+    redactedValue?: string;
+    sensitiveKeyPatterns?: RegExp[];
+}
+declare function isSensitiveTelemetryKey(key: string, patterns?: RegExp[]): boolean;
+declare function sanitizeTelemetryValue(value: TelemetryPropertyValue, options?: TelemetryRedactionOptions, depth?: number): TelemetryPropertyValue;
+declare function sanitizeTelemetryEvent(event: DecantrTelemetryEvent, options?: TelemetryRedactionOptions): DecantrTelemetryEvent;
+
+export { REDACTED_VALUE, type TelemetryRedactionOptions, isSensitiveTelemetryKey, sanitizeTelemetryEvent, sanitizeTelemetryValue };

package/dist/privacy.js

@@ -0,0 +1,79 @@
+// src/privacy.ts
+var REDACTED_VALUE = "[redacted]";
+var DEFAULT_MAX_STRING_LENGTH = 240;
+var DEFAULT_MAX_ARRAY_LENGTH = 25;
+var DEFAULT_MAX_OBJECT_KEYS = 80;
+var DEFAULT_MAX_DEPTH = 4;
+var SENSITIVE_KEY_PATTERNS = [
+  /^api[_-]?key$/i,
+  /^authorization$/i,
+  /^code$/i,
+  /^content$/i,
+  /^contents$/i,
+  /^cookie$/i,
+  /^cwd$/i,
+  /^email$/i,
+  /^env$/i,
+  /^file[_-]?contents$/i,
+  /^file[_-]?path$/i,
+  /^home$/i,
+  /^ip[_-]?address$/i,
+  /^password$/i,
+  /^path$/i,
+  /^prompt$/i,
+  /^raw[_-]?prompt$/i,
+  /^secret$/i,
+  /^source$/i,
+  /^source[_-]?code$/i,
+  /^token$/i,
+  /^url$/i,
+  /^user[_-]?agent$/i
+];
+function isSensitiveTelemetryKey(key, patterns = SENSITIVE_KEY_PATTERNS) {
+  return patterns.some((pattern) => pattern.test(key));
+}
+function sanitizeTelemetryValue(value, options = {}, depth = 0) {
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  if (depth > maxDepth) {
+    return options.redactedValue ?? REDACTED_VALUE;
+  }
+  if (typeof value === "string") {
+    const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
+    return value.length > maxStringLength ? `${value.slice(0, maxStringLength)}...` : value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || value === null) {
+    return value;
+  }
+  if (value === void 0) {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    const maxArrayLength = options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH;
+    return value.slice(0, maxArrayLength).map((entry) => sanitizeTelemetryValue(entry, options, depth + 1));
+  }
+  const redactedValue = options.redactedValue ?? REDACTED_VALUE;
+  const sensitiveKeyPatterns = options.sensitiveKeyPatterns ?? SENSITIVE_KEY_PATTERNS;
+  const maxObjectKeys = options.maxObjectKeys ?? DEFAULT_MAX_OBJECT_KEYS;
+  const entries = Object.entries(value).slice(0, maxObjectKeys);
+  const sanitized = {};
+  for (const [key, entryValue] of entries) {
+    sanitized[key] = isSensitiveTelemetryKey(key, sensitiveKeyPatterns) ? redactedValue : sanitizeTelemetryValue(entryValue, options, depth + 1);
+  }
+  return sanitized;
+}
+function sanitizeTelemetryEvent(event, options = {}) {
+  return {
+    ...event,
+    properties: sanitizeTelemetryValue(
+      event.properties,
+      options
+    )
+  };
+}
+export {
+  REDACTED_VALUE,
+  isSensitiveTelemetryKey,
+  sanitizeTelemetryEvent,
+  sanitizeTelemetryValue
+};
+//# sourceMappingURL=privacy.js.map

package/dist/privacy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/privacy.ts"],"sourcesContent":["import type { DecantrTelemetryEvent, TelemetryPropertyValue } from './events.js';\n\nexport const REDACTED_VALUE = '[redacted]';\n\nconst DEFAULT_MAX_STRING_LENGTH = 240;\nconst DEFAULT_MAX_ARRAY_LENGTH = 25;\nconst DEFAULT_MAX_OBJECT_KEYS = 80;\nconst DEFAULT_MAX_DEPTH = 4;\n\nconst SENSITIVE_KEY_PATTERNS = [\n  /^api[_-]?key$/i,\n  /^authorization$/i,\n  /^code$/i,\n  /^content$/i,\n  /^contents$/i,\n  /^cookie$/i,\n  /^cwd$/i,\n  /^email$/i,\n  /^env$/i,\n  /^file[_-]?contents$/i,\n  /^file[_-]?path$/i,\n  /^home$/i,\n  /^ip[_-]?address$/i,\n  /^password$/i,\n  /^path$/i,\n  /^prompt$/i,\n  /^raw[_-]?prompt$/i,\n  /^secret$/i,\n  /^source$/i,\n  /^source[_-]?code$/i,\n  /^token$/i,\n  /^url$/i,\n  /^user[_-]?agent$/i,\n];\n\nexport interface TelemetryRedactionOptions {\n  maxArrayLength?: number;\n  maxDepth?: number;\n  maxObjectKeys?: number;\n  maxStringLength?: number;\n  redactedValue?: string;\n  sensitiveKeyPatterns?: RegExp[];\n}\n\nexport function isSensitiveTelemetryKey(key: string, patterns = SENSITIVE_KEY_PATTERNS): boolean {\n  return patterns.some((pattern) => pattern.test(key));\n}\n\nexport function sanitizeTelemetryValue(\n  value: TelemetryPropertyValue,\n  options: TelemetryRedactionOptions = {},\n  depth = 0,\n): TelemetryPropertyValue {\n  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;\n  if (depth > maxDepth) {\n    return options.redactedValue ?? REDACTED_VALUE;\n  }\n\n  if (typeof value === 'string') {\n    const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;\n    return value.length > maxStringLength ? `${value.slice(0, maxStringLength)}...` : value;\n  }\n\n  if (typeof value === 'number' || typeof value === 'boolean' || value === null) {\n    return value;\n  }\n\n  if (value === undefined) {\n    return null;\n  }\n\n  if (Array.isArray(value)) {\n    const maxArrayLength = options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH;\n    return value\n      .slice(0, maxArrayLength)\n      .map((entry) => sanitizeTelemetryValue(entry, options, depth + 1));\n  }\n\n  const redactedValue = options.redactedValue ?? REDACTED_VALUE;\n  const sensitiveKeyPatterns = options.sensitiveKeyPatterns ?? SENSITIVE_KEY_PATTERNS;\n  const maxObjectKeys = options.maxObjectKeys ?? DEFAULT_MAX_OBJECT_KEYS;\n  const entries = Object.entries(value).slice(0, maxObjectKeys);\n  const sanitized: Record<string, TelemetryPropertyValue> = {};\n\n  for (const [key, entryValue] of entries) {\n    sanitized[key] = isSensitiveTelemetryKey(key, sensitiveKeyPatterns)\n      ? redactedValue\n      : sanitizeTelemetryValue(entryValue, options, depth + 1);\n  }\n\n  return sanitized;\n}\n\nexport function sanitizeTelemetryEvent(\n  event: DecantrTelemetryEvent,\n  options: TelemetryRedactionOptions = {},\n): DecantrTelemetryEvent {\n  return {\n    ...event,\n    properties: sanitizeTelemetryValue(\n      event.properties,\n      options,\n    ) as DecantrTelemetryEvent['properties'],\n  } as DecantrTelemetryEvent;\n}\n"],"mappings":";AAEO,IAAM,iBAAiB;AAE9B,IAAM,4BAA4B;AAClC,IAAM,2BAA2B;AACjC,IAAM,0BAA0B;AAChC,IAAM,oBAAoB;AAE1B,IAAM,yBAAyB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAWO,SAAS,wBAAwB,KAAa,WAAW,wBAAiC;AAC/F,SAAO,SAAS,KAAK,CAAC,YAAY,QAAQ,KAAK,GAAG,CAAC;AACrD;AAEO,SAAS,uBACd,OACA,UAAqC,CAAC,GACtC,QAAQ,GACgB;AACxB,QAAM,WAAW,QAAQ,YAAY;AACrC,MAAI,QAAQ,UAAU;AACpB,WAAO,QAAQ,iBAAiB;AAAA,EAClC;AAEA,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,kBAAkB,QAAQ,mBAAmB;AACnD,WAAO,MAAM,SAAS,kBAAkB,GAAG,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ;AAAA,EACpF;AAEA,MAAI,OAAO,UAAU,YAAY,OAAO,UAAU,aAAa,UAAU,MAAM;AAC7E,WAAO;AAAA,EACT;AAEA,MAAI,UAAU,QAAW;AACvB,WAAO;AAAA,EACT;AAEA,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,UAAM,iBAAiB,QAAQ,kBAAkB;AACjD,WAAO,MACJ,MAAM,GAAG,cAAc,EACvB,IAAI,CAAC,UAAU,uBAAuB,OAAO,SAAS,QAAQ,CAAC,CAAC;AAAA,EACrE;AAEA,QAAM,gBAAgB,QAAQ,iBAAiB;AAC/C,QAAM,uBAAuB,QAAQ,wBAAwB;AAC7D,QAAM,gBAAgB,QAAQ,iBAAiB;AAC/C,QAAM,UAAU,OAAO,QAAQ,KAAK,EAAE,MAAM,GAAG,aAAa;AAC5D,QAAM,YAAoD,CAAC;AAE3D,aAAW,CAAC,KAAK,UAAU,KAAK,SAAS;AACvC,cAAU,GAAG,IAAI,wBAAwB,KAAK,oBAAoB,IAC9D,gBACA,uBAAuB,YAAY,SAAS,QAAQ,CAAC;AAAA,EAC3D;AAEA,SAAO;AACT;AAEO,SAAS,uBACd,OACA,UAAqC,CAAC,GACf;AACvB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,YAAY;AAAA,MACV,MAAM;AAAA,MACN;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@decantr/telemetry",
+  "version": "0.1.0",
+  "description": "Privacy-preserving telemetry contracts, clients, and analytics sinks for Decantr",
+  "author": "Decantr AI",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/decantr-ai/decantr/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/decantr-ai/decantr.git",
+    "directory": "packages/telemetry"
+  },
+  "homepage": "https://decantr.ai",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    },
+    "./events": {
+      "import": "./dist/events.js",
+      "types": "./dist/events.d.ts"
+    },
+    "./posthog": {
+      "import": "./dist/posthog.js",
+      "types": "./dist/posthog.d.ts"
+    },
+    "./privacy": {
+      "import": "./dist/privacy.js",
+      "types": "./dist/privacy.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "preversion": "pnpm build && pnpm test"
+  }
+}