@skillsmith/core 0.5.4 → 0.5.6

package/dist/telemetry/metric-types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Type definitions for Skillsmith Metrics
+ * @module @skillsmith/core/telemetry/metric-types
+ */
+/**
+ * Metric types
+ */
+export type MetricType = 'counter' | 'histogram' | 'gauge';
+/**
+ * Metrics configuration
+ */
+export interface MetricsConfig {
+    /** Service name for metrics (default: skillsmith) */
+    serviceName?: string;
+    /** OTLP endpoint URL */
+    endpoint?: string;
+    /** Export interval in ms (default: 60000) */
+    exportIntervalMs?: number;
+    /** Enable console export for debugging (default: false) */
+    consoleExport?: boolean;
+}
+/**
+ * Histogram bucket boundaries for latency metrics
+ */
+export declare const LATENCY_BUCKETS: number[];
+/**
+ * Metric labels/attributes
+ */
+export interface MetricLabels {
+    [key: string]: string | number | boolean;
+}
+/**
+ * Counter metric interface
+ */
+export interface Counter {
+    /** Add a value to the counter */
+    add(value: number, labels?: MetricLabels): void;
+    /** Increment by 1 */
+    increment(labels?: MetricLabels): void;
+}
+/**
+ * Histogram metric interface
+ */
+export interface Histogram {
+    /** Record a value */
+    record(value: number, labels?: MetricLabels): void;
+}
+/**
+ * Gauge metric interface
+ */
+export interface Gauge {
+    /** Set the gauge value */
+    set(value: number, labels?: MetricLabels): void;
+    /** Get the current value (if tracked) */
+    getValue(labels?: MetricLabels): number;
+}
+/**
+ * Metrics snapshot for export
+ */
+export interface MetricsSnapshot {
+    timestamp: string;
+    counters: Record<string, number>;
+    histograms: Record<string, {
+        count: number;
+        sum: number;
+        mean: number;
+        p50: number;
+        p95: number;
+        p99: number;
+    }>;
+    gauges: Record<string, number>;
+}
+//# sourceMappingURL=metric-types.d.ts.map

package/dist/telemetry/metric-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-types.d.ts","sourceRoot":"","sources":["../../src/telemetry/metric-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAA;AAE1D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,UAA6D,CAAA;AAEzF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,iCAAiC;IACjC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAC/C,qBAAqB;IACrB,SAAS,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qBAAqB;IACrB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,0BAA0B;IAC1B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAC/C,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,UAAU,EAAE,MAAM,CAChB,MAAM,EACN;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CACpF,CAAA;IACD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B"}

package/dist/telemetry/metric-types.js

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for Skillsmith Metrics
+ * @module @skillsmith/core/telemetry/metric-types
+ */
+/**
+ * Histogram bucket boundaries for latency metrics
+ */
+export const LATENCY_BUCKETS = [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+//# sourceMappingURL=metric-types.js.map

package/dist/telemetry/metric-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-types.js","sourceRoot":"","sources":["../../src/telemetry/metric-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA"}

package/dist/telemetry/metrics.d.ts

@@ -0,0 +1,60 @@
+/**
+ * SMI-739: Custom Metrics Registration
+ * SMI-755: Graceful fallback when OpenTelemetry unavailable
+ *
+ * Provides metrics collection for Skillsmith operations.
+ *
+ * @see metric-types.ts for type definitions
+ * @see metric-helpers.ts for helper classes
+ */
+export type { MetricType, MetricsConfig, MetricLabels, Counter, Histogram, Gauge, MetricsSnapshot, } from './metric-types.js';
+export { LATENCY_BUCKETS } from './metric-types.js';
+import type { Counter, Histogram, Gauge, MetricsConfig, MetricsSnapshot } from './metric-types.js';
+/**
+ * Skillsmith Metrics Registry
+ */
+export declare class MetricsRegistry {
+    private counters;
+    private histograms;
+    private gauges;
+    private enabled;
+    private initialized;
+    private config;
+    readonly mcpRequestLatency: Histogram;
+    readonly mcpRequestCount: Counter;
+    readonly mcpErrorCount: Counter;
+    readonly dbQueryLatency: Histogram;
+    readonly dbQueryCount: Counter;
+    readonly cacheHits: Counter;
+    readonly cacheMisses: Counter;
+    readonly cacheSize: Gauge;
+    readonly embeddingLatency: Histogram;
+    readonly embeddingCount: Counter;
+    readonly searchLatency: Histogram;
+    readonly searchCount: Counter;
+    readonly activeOperations: Gauge;
+    constructor(config?: MetricsConfig);
+    initialize(): Promise<void>;
+    isEnabled(): boolean;
+    createCounter(name: string, _options?: {
+        description?: string;
+        unit?: string;
+    }): Counter;
+    createHistogram(name: string, _options?: {
+        description?: string;
+        unit?: string;
+        buckets?: number[];
+    }): Histogram;
+    createGauge(name: string, _options?: {
+        description?: string;
+        unit?: string;
+    }): Gauge;
+    getCacheHitRatio(): number;
+    getSnapshot(): MetricsSnapshot;
+    reset(): void;
+}
+export declare function getMetrics(): MetricsRegistry;
+export declare function initializeMetrics(config?: MetricsConfig): Promise<MetricsRegistry>;
+export declare function timeAsync<T>(histogram: Histogram, fn: () => Promise<T>, labels?: Record<string, string | number | boolean>): Promise<T>;
+export declare function timeSync<T>(histogram: Histogram, fn: () => T, labels?: Record<string, string | number | boolean>): T;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/telemetry/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EACV,UAAU,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,SAAS,EACT,KAAK,EACL,eAAe,GAChB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAGnD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AASlG;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,MAAM,CAAyB;IAGvC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,CAAA;IACrC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAA;IAClC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAA;IACzB,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAA;IACpC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAA;IACjC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAA;gBAEpB,MAAM,GAAE,aAAkB;IAmEhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BjC,SAAS,IAAI,OAAO;IAIpB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;IAOxF,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GACrE,SAAS;IAOZ,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK;IAOpF,gBAAgB,IAAI,MAAM;IAc1B,WAAW,IAAI,eAAe;IA6B9B,KAAK,IAAI,IAAI;CAKd;AAKD,wBAAgB,UAAU,IAAI,eAAe,CAG5C;AAED,wBAAsB,iBAAiB,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAKxF;AAED,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,SAAS,EACpB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACjD,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,QAAQ,CAAC,CAAC,EACxB,SAAS,EAAE,SAAS,EACpB,EAAE,EAAE,MAAM,CAAC,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACjD,CAAC,CAOH"}

package/dist/telemetry/metrics.js

@@ -0,0 +1,228 @@
+/**
+ * SMI-739: Custom Metrics Registration
+ * SMI-755: Graceful fallback when OpenTelemetry unavailable
+ *
+ * Provides metrics collection for Skillsmith operations.
+ *
+ * @see metric-types.ts for type definitions
+ * @see metric-helpers.ts for helper classes
+ */
+export { LATENCY_BUCKETS } from './metric-types.js';
+import { checkOTelAvailability, dynamicImport, NoOpGauge, InMemoryCounter, InMemoryHistogram, } from './metric-helpers.js';
+/**
+ * Skillsmith Metrics Registry
+ */
+export class MetricsRegistry {
+    counters = new Map();
+    histograms = new Map();
+    gauges = new Map();
+    enabled = false;
+    initialized = false;
+    config;
+    // Predefined metrics
+    mcpRequestLatency;
+    mcpRequestCount;
+    mcpErrorCount;
+    dbQueryLatency;
+    dbQueryCount;
+    cacheHits;
+    cacheMisses;
+    cacheSize;
+    embeddingLatency;
+    embeddingCount;
+    searchLatency;
+    searchCount;
+    activeOperations;
+    constructor(config = {}) {
+        this.config = {
+            serviceName: config.serviceName ?? process.env.OTEL_SERVICE_NAME ?? 'skillsmith',
+            endpoint: config.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? '',
+            exportIntervalMs: config.exportIntervalMs ?? 60000,
+            consoleExport: config.consoleExport ?? false,
+        };
+        const telemetryDisabled = process.env.SKILLSMITH_TELEMETRY_ENABLED === 'false';
+        if (telemetryDisabled) {
+            this.enabled = false;
+        }
+        else {
+            const explicitlyEnabled = process.env.SKILLSMITH_METRICS_ENABLED === 'true';
+            const explicitlyDisabled = process.env.SKILLSMITH_METRICS_ENABLED === 'false';
+            if (explicitlyDisabled) {
+                this.enabled = false;
+            }
+            else if (explicitlyEnabled || this.config.endpoint || this.config.consoleExport) {
+                this.enabled = true;
+            }
+        }
+        // Create predefined metrics
+        this.mcpRequestLatency = this.createHistogram('skillsmith.mcp.request.latency', {
+            description: 'Latency of MCP tool requests in milliseconds',
+            unit: 'ms',
+        });
+        this.mcpRequestCount = this.createCounter('skillsmith.mcp.request.count', {
+            description: 'Total number of MCP tool requests',
+        });
+        this.mcpErrorCount = this.createCounter('skillsmith.mcp.error.count', {
+            description: 'Total number of MCP tool errors',
+        });
+        this.dbQueryLatency = this.createHistogram('skillsmith.db.query.latency', {
+            description: 'Latency of database queries in milliseconds',
+            unit: 'ms',
+        });
+        this.dbQueryCount = this.createCounter('skillsmith.db.query.count', {
+            description: 'Total number of database queries',
+        });
+        this.cacheHits = this.createCounter('skillsmith.cache.hits', {
+            description: 'Total number of cache hits',
+        });
+        this.cacheMisses = this.createCounter('skillsmith.cache.misses', {
+            description: 'Total number of cache misses',
+        });
+        this.cacheSize = this.createGauge('skillsmith.cache.size', {
+            description: 'Current cache size in entries',
+        });
+        this.embeddingLatency = this.createHistogram('skillsmith.embedding.latency', {
+            description: 'Latency of embedding generation in milliseconds',
+            unit: 'ms',
+        });
+        this.embeddingCount = this.createCounter('skillsmith.embedding.count', {
+            description: 'Total number of embeddings generated',
+        });
+        this.searchLatency = this.createHistogram('skillsmith.search.latency', {
+            description: 'Latency of search operations in milliseconds',
+            unit: 'ms',
+        });
+        this.searchCount = this.createCounter('skillsmith.search.count', {
+            description: 'Total number of search operations',
+        });
+        this.activeOperations = this.createGauge('skillsmith.operations.active', {
+            description: 'Number of currently active operations',
+        });
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        if (!this.enabled) {
+            this.initialized = true;
+            return;
+        }
+        const isAvailable = await checkOTelAvailability();
+        if (!isAvailable) {
+            console.info('[Skillsmith Metrics] OpenTelemetry not installed. Using in-memory metrics (available via getSnapshot()).');
+            this.initialized = true;
+            return;
+        }
+        try {
+            await dynamicImport('@opentelemetry/api');
+            this.initialized = true;
+        }
+        catch (error) {
+            console.warn('[Skillsmith Metrics] Failed to initialize OpenTelemetry:', error);
+            this.enabled = false;
+            this.initialized = true;
+        }
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    createCounter(name, _options) {
+        if (this.counters.has(name))
+            return this.counters.get(name);
+        const counter = new InMemoryCounter();
+        this.counters.set(name, counter);
+        return counter;
+    }
+    createHistogram(name, _options) {
+        if (this.histograms.has(name))
+            return this.histograms.get(name);
+        const histogram = new InMemoryHistogram();
+        this.histograms.set(name, histogram);
+        return histogram;
+    }
+    createGauge(name, _options) {
+        if (this.gauges.has(name))
+            return this.gauges.get(name);
+        const gauge = new NoOpGauge();
+        this.gauges.set(name, gauge);
+        return gauge;
+    }
+    getCacheHitRatio() {
+        const hits = this.counters.get('skillsmith.cache.hits');
+        const misses = this.counters.get('skillsmith.cache.misses');
+        if (!hits || !misses)
+            return 0;
+        let totalHits = 0, totalMisses = 0;
+        for (const [, count] of hits.getValues())
+            totalHits += count;
+        for (const [, count] of misses.getValues())
+            totalMisses += count;
+        const total = totalHits + totalMisses;
+        return total > 0 ? totalHits / total : 0;
+    }
+    getSnapshot() {
+        const snapshot = {
+            timestamp: new Date().toISOString(),
+            counters: {},
+            histograms: {},
+            gauges: {},
+        };
+        for (const [name, counter] of this.counters) {
+            if (counter instanceof InMemoryCounter) {
+                let total = 0;
+                for (const [, count] of counter.getValues())
+                    total += count;
+                snapshot.counters[name] = total;
+            }
+        }
+        for (const [name, histogram] of this.histograms) {
+            if (histogram instanceof InMemoryHistogram) {
+                snapshot.histograms[name] = histogram.getStats();
+            }
+        }
+        for (const [name, gauge] of this.gauges) {
+            snapshot.gauges[name] = gauge.getValue();
+        }
+        return snapshot;
+    }
+    reset() {
+        for (const [name] of this.counters)
+            this.counters.set(name, new InMemoryCounter());
+        for (const [name] of this.histograms)
+            this.histograms.set(name, new InMemoryHistogram());
+        for (const [name] of this.gauges)
+            this.gauges.set(name, new NoOpGauge());
+    }
+}
+// Default metrics registry instance
+let defaultRegistry = null;
+export function getMetrics() {
+    if (!defaultRegistry)
+        defaultRegistry = new MetricsRegistry();
+    return defaultRegistry;
+}
+export async function initializeMetrics(config) {
+    if (defaultRegistry)
+        defaultRegistry.reset();
+    defaultRegistry = new MetricsRegistry(config);
+    await defaultRegistry.initialize();
+    return defaultRegistry;
+}
+export async function timeAsync(histogram, fn, labels) {
+    const start = performance.now();
+    try {
+        return await fn();
+    }
+    finally {
+        histogram.record(performance.now() - start, labels);
+    }
+}
+export function timeSync(histogram, fn, labels) {
+    const start = performance.now();
+    try {
+        return fn();
+    }
+    finally {
+        histogram.record(performance.now() - start, labels);
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/telemetry/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/posthog.d.ts

@@ -0,0 +1,147 @@
+/**
+ * SMI-1246: PostHog Telemetry Integration
+ *
+ * Provides product analytics and event tracking via PostHog:
+ * - Skill searches and views
+ * - Installation events
+ * - User engagement metrics
+ * - Feature usage tracking
+ *
+ * Privacy-first: All user IDs are anonymized, no PII collected.
+ */
+import { PostHog } from 'posthog-node';
+/**
+ * PostHog configuration options
+ */
+export interface PostHogConfig {
+    /** PostHog API key (starts with phc_) */
+    apiKey: string;
+    /** PostHog host URL (default: https://app.posthog.com) */
+    host?: string;
+    /** Flush interval in milliseconds (default: 10000) */
+    flushInterval?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Disable telemetry entirely (default: false) */
+    disabled?: boolean;
+}
+/**
+ * Event types for Skillsmith analytics
+ */
+export type SkillsmithEventType = 'skill_search' | 'skill_view' | 'skill_install' | 'skill_uninstall' | 'skill_compare' | 'skill_recommend' | 'api_error' | 'feature_flag_evaluated';
+/**
+ * Event properties for skill-related events
+ */
+export interface SkillEventProperties {
+    /** Skill ID (author/name format) */
+    skill_id?: string;
+    /** Search query */
+    query?: string;
+    /** Number of results returned */
+    result_count?: number;
+    /** Trust tier filter applied */
+    trust_tier?: string;
+    /** Category filter applied */
+    category?: string;
+    /** Response time in milliseconds */
+    duration_ms?: number;
+    /** Error code if applicable */
+    error_code?: string;
+    /** Source of the event (cli, mcp, api) */
+    source?: 'cli' | 'mcp' | 'api';
+    /** Additional custom properties */
+    [key: string]: unknown;
+}
+/**
+ * Initialize PostHog client
+ * Call this at application startup
+ *
+ * @param config - PostHog configuration
+ */
+export declare function initializePostHog(config: PostHogConfig): void;
+/**
+ * Get the PostHog client instance
+ * Returns null if not initialized or disabled
+ */
+export declare function getPostHog(): PostHog | null;
+/**
+ * Check if PostHog is enabled and initialized
+ */
+export declare function isPostHogEnabled(): boolean;
+/**
+ * Track an event with PostHog
+ * Silently no-ops if PostHog is disabled or not initialized
+ *
+ * @param distinctId - Anonymous user identifier
+ * @param event - Event name
+ * @param properties - Event properties
+ */
+export declare function trackEvent(distinctId: string, event: SkillsmithEventType | string, properties?: SkillEventProperties): void;
+/**
+ * Allowed trait keys for user identification.
+ * Only non-PII properties are permitted to prevent data leakage.
+ */
+export declare const ALLOWED_TRAITS: readonly ["tier", "version", "platform", "sdk_version"];
+/**
+ * Type for allowed user traits - restricted to prevent PII leakage.
+ * Only safe, non-identifying properties are permitted.
+ */
+export type AllowedUserTraits = {
+    /** User tier (e.g., 'free', 'pro', 'enterprise') */
+    tier?: string;
+    /** Application version */
+    version?: string;
+    /** Platform identifier (e.g., 'darwin', 'linux', 'win32') */
+    platform?: string;
+    /** SDK version used */
+    sdk_version?: string;
+};
+/**
+ * Identify a user with restricted traits.
+ *
+ * @warning DO NOT pass PII (email, name, IP, etc.) to this function.
+ * Only the following safe traits are allowed: tier, version, platform, sdk_version.
+ * Any other properties will be silently filtered out to prevent data leakage.
+ *
+ * @param distinctId - Anonymous user identifier (should be a hash, not an email)
+ * @param traits - User properties (restricted to AllowedUserTraits)
+ */
+export declare function identifyUser(distinctId: string, traits: AllowedUserTraits): void;
+/**
+ * Check if a feature flag is enabled for a user
+ *
+ * @param distinctId - Anonymous user identifier
+ * @param flagKey - Feature flag key
+ * @returns true if enabled, false otherwise
+ */
+export declare function isFeatureFlagEnabled(distinctId: string, flagKey: string): Promise<boolean>;
+/**
+ * Flush all pending events immediately
+ * Call this before application shutdown
+ */
+export declare function flushPostHog(): Promise<void>;
+/**
+ * Shutdown PostHog client
+ * Call this at application shutdown
+ */
+export declare function shutdownPostHog(): Promise<void>;
+/**
+ * Convenience function to track skill search events
+ */
+export declare function trackSkillSearch(distinctId: string, query: string, resultCount: number, durationMs: number, filters?: {
+    trustTier?: string;
+    category?: string;
+}): void;
+/**
+ * Convenience function to track skill view events
+ */
+export declare function trackSkillView(distinctId: string, skillId: string, source: 'cli' | 'mcp' | 'api'): void;
+/**
+ * Convenience function to track skill install events
+ */
+export declare function trackSkillInstall(distinctId: string, skillId: string, source: 'cli' | 'mcp' | 'api'): void;
+/**
+ * Convenience function to track API errors
+ */
+export declare function trackApiError(distinctId: string, errorCode: string, endpoint: string, durationMs?: number): void;
+//# sourceMappingURL=posthog.d.ts.map

package/dist/telemetry/posthog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posthog.d.ts","sourceRoot":"","sources":["../../src/telemetry/posthog.ts"],"names":[],"mappings":"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"}