@skillsmith/core 0.5.4 → 0.5.6

package/dist/analytics/types.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Type definitions for Analytics Infrastructure
+ *
+ * Covers:
+ * - Skill usage events and attribution
+ * - A/B testing experiments
+ * - ROI metrics and dashboards
+ */
+/**
+ * Skill usage event types
+ */
+export type UsageEventType = 'activation' | 'invocation' | 'success' | 'failure';
+/**
+ * Skill usage event
+ */
+export interface UsageEvent {
+    id: string;
+    skillId: string;
+    userId: string;
+    sessionId: string;
+    eventType: UsageEventType;
+    context?: Record<string, unknown>;
+    valueScore?: number;
+    timestamp: string;
+    createdAt: string;
+}
+/**
+ * Input for creating a usage event
+ */
+export interface UsageEventInput {
+    skillId: string;
+    userId: string;
+    sessionId: string;
+    eventType: UsageEventType;
+    context?: Record<string, unknown>;
+    valueScore?: number;
+}
+/**
+ * Experiment status
+ */
+export type ExperimentStatus = 'draft' | 'active' | 'paused' | 'completed';
+/**
+ * Experiment variant
+ */
+export type ExperimentVariant = 'control' | 'treatment';
+/**
+ * A/B testing experiment
+ */
+export interface Experiment {
+    id: string;
+    name: string;
+    description?: string;
+    hypothesis?: string;
+    status: ExperimentStatus;
+    variantA: Record<string, unknown>;
+    variantB: Record<string, unknown>;
+    startDate?: string;
+    endDate?: string;
+    targetSampleSize: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Input for creating an experiment
+ */
+export interface ExperimentInput {
+    name: string;
+    description?: string;
+    hypothesis?: string;
+    variantA: Record<string, unknown>;
+    variantB: Record<string, unknown>;
+    targetSampleSize?: number;
+}
+/**
+ * Experiment assignment
+ */
+export interface ExperimentAssignment {
+    id: string;
+    experimentId: string;
+    userId: string;
+    variant: ExperimentVariant;
+    assignedAt: string;
+}
+/**
+ * Experiment outcome measurement
+ */
+export interface ExperimentOutcome {
+    id: string;
+    experimentId: string;
+    assignmentId: string;
+    outcomeType: string;
+    outcomeValue: number;
+    metadata?: Record<string, unknown>;
+    measuredAt: string;
+    createdAt: string;
+}
+/**
+ * Input for recording an outcome
+ */
+export interface OutcomeInput {
+    experimentId: string;
+    assignmentId: string;
+    outcomeType: string;
+    outcomeValue: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * ROI metric types
+ */
+export type ROIMetricType = 'daily' | 'weekly' | 'monthly' | 'user' | 'skill';
+/**
+ * ROI metrics
+ */
+export interface ROIMetrics {
+    id: string;
+    metricType: ROIMetricType;
+    entityId?: string;
+    periodStart: string;
+    periodEnd: string;
+    totalActivations: number;
+    totalInvocations: number;
+    totalSuccesses: number;
+    totalFailures: number;
+    avgValueScore: number;
+    estimatedTimeSaved: number;
+    estimatedValueUsd: number;
+    metadata?: Record<string, unknown>;
+    computedAt: string;
+    createdAt: string;
+}
+/**
+ * Value attribution types
+ */
+export type AttributionType = 'inline' | 'metadata' | 'session';
+/**
+ * Value dimensions for ROI calculation
+ */
+export type ValueDimension = 'time_saved' | 'quality_improved' | 'error_prevented';
+/**
+ * Value attribution
+ */
+export interface ValueAttribution {
+    id: string;
+    usageEventId: string;
+    skillId: string;
+    attributionType: AttributionType;
+    valueDimension: ValueDimension;
+    valueAmount: number;
+    confidence: number;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+/**
+ * Usage analytics summary for a time period
+ */
+export interface UsageAnalyticsSummary {
+    periodStart: string;
+    periodEnd: string;
+    totalEvents: number;
+    eventsByType: Record<UsageEventType, number>;
+    uniqueUsers: number;
+    uniqueSkills: number;
+    avgValueScore: number;
+    topSkills: Array<{
+        skillId: string;
+        count: number;
+    }>;
+}
+/**
+ * Experiment analysis results
+ */
+export interface ExperimentAnalysis {
+    experimentId: string;
+    experimentName: string;
+    controlGroup: {
+        sampleSize: number;
+        outcomes: Record<string, {
+            mean: number;
+            stdDev: number;
+        }>;
+    };
+    treatmentGroup: {
+        sampleSize: number;
+        outcomes: Record<string, {
+            mean: number;
+            stdDev: number;
+        }>;
+    };
+    pValues: Record<string, number>;
+    confidenceIntervals: Record<string, {
+        lower: number;
+        upper: number;
+    }>;
+    recommendation: 'continue' | 'stop_control_wins' | 'stop_treatment_wins' | 'inconclusive';
+}
+/**
+ * ROI dashboard data
+ */
+export interface ROIDashboard {
+    user?: {
+        userId: string;
+        totalTimeSaved: number;
+        estimatedValueUsd: number;
+        topSkills: Array<{
+            skillId: string;
+            skillName: string;
+            timeSaved: number;
+        }>;
+        weeklyTrend: Array<{
+            week: string;
+            timeSaved: number;
+        }>;
+    };
+    stakeholder?: {
+        totalUsers: number;
+        totalActivations: number;
+        avgTimeSavedPerUser: number;
+        totalEstimatedValue: number;
+        adoptionRate: number;
+        skillLeaderboard: Array<{
+            skillId: string;
+            skillName: string;
+            userCount: number;
+            totalValue: number;
+        }>;
+    };
+}
+/**
+ * Export format options
+ */
+export type ExportFormat = 'json' | 'csv' | 'pdf';
+/**
+ * Export options
+ */
+export interface ExportOptions {
+    format: ExportFormat;
+    startDate?: string;
+    endDate?: string;
+    includeCharts?: boolean;
+}
+/**
+ * SMI-914: Skill Usage Event tracking types
+ *
+ * These types support per-skill usage analytics with:
+ * - Anonymized user tracking (no PII)
+ * - Task duration measurement
+ * - Success/error/abandoned outcomes
+ * - 30-day rolling window storage
+ */
+/**
+ * Outcome of a skill invocation
+ */
+export type SkillUsageOutcome = 'success' | 'error' | 'abandoned';
+/**
+ * Individual skill usage event (anonymized)
+ */
+export interface SkillUsageEvent {
+    id?: number;
+    skillId: string;
+    userId: string;
+    timestamp: number;
+    taskDuration: number;
+    outcome: SkillUsageOutcome;
+    contextHash: string;
+}
+/**
+ * Aggregated metrics for a skill
+ */
+export interface SkillMetrics {
+    skillId: string;
+    totalInvocations: number;
+    successRate: number;
+    avgTaskDuration: number;
+    uniqueUsers: number;
+    lastUsed: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/analytics/types.d.ts.map

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

package/dist/analytics/types.js

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for Analytics Infrastructure
+ *
+ * Covers:
+ * - Skill usage events and attribution
+ * - A/B testing experiments
+ * - ROI metrics and dashboards
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/analytics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/analytics/usage-tracker.d.ts

@@ -0,0 +1,138 @@
+/**
+ * SMI-914: Usage Tracker
+ *
+ * High-level API for tracking skill usage events.
+ * Handles:
+ * - Start/end tracking for duration measurement
+ * - User ID anonymization
+ * - Context hashing
+ * - Periodic cleanup of old events
+ */
+import type { SkillUsageEvent, SkillUsageOutcome, SkillMetrics } from './types.js';
+/**
+ * UsageTracker configuration options
+ */
+export interface UsageTrackerOptions {
+    /**
+     * Custom database path (defaults to ~/.skillsmith/analytics.db)
+     */
+    dbPath?: string;
+    /**
+     * Auto-cleanup interval in milliseconds (0 to disable, default: 1 hour)
+     */
+    cleanupInterval?: number;
+}
+/**
+ * High-level usage tracking API
+ *
+ * @example
+ * ```typescript
+ * const tracker = new UsageTracker();
+ *
+ * // Start tracking a skill invocation
+ * const trackingId = tracker.startTracking('anthropic/commit', 'user123');
+ *
+ * // ... skill execution ...
+ *
+ * // End tracking with outcome
+ * tracker.endTracking(trackingId, 'success', { framework: 'react' });
+ *
+ * // Get metrics
+ * const metrics = tracker.getMetrics('anthropic/commit');
+ *
+ * // Cleanup when done
+ * tracker.close();
+ * ```
+ */
+export declare class UsageTracker {
+    private storage;
+    private pendingEvents;
+    private cleanupTimer;
+    private sessionCleanupTimer;
+    /**
+     * @deprecated Use UsageTracker.create(options) — async factory with WASM fallback.
+     * This constructor always throws to prevent silent data loss.
+     */
+    constructor(_options?: UsageTrackerOptions);
+    /**
+     * Async factory — supports both native and WASM SQLite.
+     *
+     * @param options - Configuration options
+     * @returns Fully initialised UsageTracker instance
+     */
+    static create(options?: UsageTrackerOptions): Promise<UsageTracker>;
+    /**
+     * Start tracking a skill invocation
+     *
+     * @param skillId - The skill identifier (e.g., 'anthropic/commit')
+     * @param userId - Raw user identifier (will be anonymized)
+     * @returns Tracking ID to use when ending tracking
+     */
+    startTracking(skillId: string, userId: string): string;
+    /**
+     * End tracking and record the event
+     *
+     * @param trackingId - The tracking ID from startTracking
+     * @param outcome - The outcome of the skill invocation
+     * @param context - Optional project context (will be hashed)
+     */
+    endTracking(trackingId: string, outcome: SkillUsageOutcome, context?: Record<string, unknown>): void;
+    /**
+     * Record a complete event directly (for events that don't need start/end tracking)
+     *
+     * @param skillId - The skill identifier
+     * @param userId - Raw user identifier (will be anonymized)
+     * @param taskDuration - Duration in milliseconds
+     * @param outcome - The outcome
+     * @param context - Optional project context
+     */
+    recordEvent(skillId: string, userId: string, taskDuration: number, outcome: SkillUsageOutcome, context?: Record<string, unknown>): void;
+    /**
+     * Get metrics for a skill
+     *
+     * @param skillId - The skill identifier
+     * @returns Aggregated metrics or null if no data
+     */
+    getMetrics(skillId: string): SkillMetrics | null;
+    /**
+     * Get events for a skill
+     *
+     * @param skillId - The skill identifier
+     * @param limit - Maximum number of events
+     * @returns Array of usage events
+     */
+    getEvents(skillId: string, limit?: number): SkillUsageEvent[];
+    /**
+     * Get total event count
+     *
+     * @returns Number of stored events
+     */
+    getEventCount(): number;
+    /**
+     * Get count of pending (unfinished) trackings
+     *
+     * @returns Number of pending trackings
+     */
+    getPendingCount(): number;
+    /**
+     * Clean up events older than 30 days
+     *
+     * @returns Number of deleted events
+     */
+    cleanup(): number;
+    /**
+     * Clean up stale sessions that have exceeded the timeout
+     * This prevents unbounded memory growth from sessions that are started but never ended
+     */
+    private cleanupStaleSessions;
+    /**
+     * Close the tracker and release resources
+     */
+    close(): void;
+    /**
+     * Dispose of the tracker (alias for close)
+     * Clears all intervals and releases resources
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=usage-tracker.d.ts.map

package/dist/analytics/usage-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-tracker.d.ts","sourceRoot":"","sources":["../../src/analytics/usage-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAiBlF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,aAAa,CAA0C;IAC/D,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,mBAAmB,CAA8C;IAEzE;;;OAGG;gBACS,QAAQ,CAAC,EAAE,mBAAmB;IAO1C;;;;;OAKG;WACU,MAAM,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC;IA8B7E;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAetD;;;;;;OAMG;IACH,WAAW,CACT,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,IAAI;IAoBP;;;;;;;;OAQG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,IAAI;IAaP;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAIhD;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAY,GAAG,eAAe,EAAE;IAIlE;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;OAIG;IACH,OAAO,IAAI,MAAM;IAIjB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAYb;;;OAGG;IACH,OAAO,IAAI,IAAI;CAGhB"}

package/dist/analytics/usage-tracker.js

@@ -0,0 +1,226 @@
+/**
+ * SMI-914: Usage Tracker
+ *
+ * High-level API for tracking skill usage events.
+ * Handles:
+ * - Start/end tracking for duration measurement
+ * - User ID anonymization
+ * - Context hashing
+ * - Periodic cleanup of old events
+ */
+import { AnalyticsStorage } from './storage.js';
+import { anonymizeUserId, hashProjectContext } from './anonymizer.js';
+/**
+ * Session timeout in milliseconds (1 hour)
+ * Sessions older than this are considered stale and will be cleaned up
+ */
+const SESSION_TIMEOUT_MS = 60 * 60 * 1000;
+/**
+ * High-level usage tracking API
+ *
+ * @example
+ * ```typescript
+ * const tracker = new UsageTracker();
+ *
+ * // Start tracking a skill invocation
+ * const trackingId = tracker.startTracking('anthropic/commit', 'user123');
+ *
+ * // ... skill execution ...
+ *
+ * // End tracking with outcome
+ * tracker.endTracking(trackingId, 'success', { framework: 'react' });
+ *
+ * // Get metrics
+ * const metrics = tracker.getMetrics('anthropic/commit');
+ *
+ * // Cleanup when done
+ * tracker.close();
+ * ```
+ */
+export class UsageTracker {
+    storage;
+    pendingEvents = new Map();
+    cleanupTimer = null;
+    sessionCleanupTimer = null;
+    /**
+     * @deprecated Use UsageTracker.create(options) — async factory with WASM fallback.
+     * This constructor always throws to prevent silent data loss.
+     */
+    constructor(_options) {
+        throw new Error('[UsageTracker] Cannot construct synchronously. ' +
+            'Use await UsageTracker.create(options) instead.');
+    }
+    /**
+     * Async factory — supports both native and WASM SQLite.
+     *
+     * @param options - Configuration options
+     * @returns Fully initialised UsageTracker instance
+     */
+    static async create(options = {}) {
+        const instance = Object.create(UsageTracker.prototype);
+        instance.storage = await AnalyticsStorage.create(options.dbPath);
+        instance.pendingEvents = new Map();
+        instance.cleanupTimer = null;
+        instance.sessionCleanupTimer = null;
+        // Setup auto-cleanup (default: every hour)
+        const cleanupInterval = options.cleanupInterval ?? 60 * 60 * 1000;
+        if (cleanupInterval > 0) {
+            instance.cleanupTimer = setInterval(() => instance.cleanup(), cleanupInterval);
+            // Don't block Node.js from exiting
+            if (instance.cleanupTimer.unref) {
+                instance.cleanupTimer.unref();
+            }
+        }
+        // Setup session cleanup at half the timeout interval to prevent unbounded growth
+        instance.sessionCleanupTimer = setInterval(() => instance.cleanupStaleSessions(), SESSION_TIMEOUT_MS / 2);
+        // Don't block Node.js from exiting
+        if (instance.sessionCleanupTimer.unref) {
+            instance.sessionCleanupTimer.unref();
+        }
+        return instance;
+    }
+    /**
+     * Start tracking a skill invocation
+     *
+     * @param skillId - The skill identifier (e.g., 'anthropic/commit')
+     * @param userId - Raw user identifier (will be anonymized)
+     * @returns Tracking ID to use when ending tracking
+     */
+    startTracking(skillId, userId) {
+        // Clean up stale sessions opportunistically to prevent buildup
+        this.cleanupStaleSessions();
+        const trackingId = `${skillId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.pendingEvents.set(trackingId, {
+            skillId,
+            startTime: Date.now(),
+            rawUserId: userId,
+        });
+        return trackingId;
+    }
+    /**
+     * End tracking and record the event
+     *
+     * @param trackingId - The tracking ID from startTracking
+     * @param outcome - The outcome of the skill invocation
+     * @param context - Optional project context (will be hashed)
+     */
+    endTracking(trackingId, outcome, context = {}) {
+        const pending = this.pendingEvents.get(trackingId);
+        if (!pending) {
+            // Silently ignore unknown tracking IDs (could be from a previous session)
+            return;
+        }
+        const event = {
+            skillId: pending.skillId,
+            userId: anonymizeUserId(pending.rawUserId),
+            timestamp: Date.now(),
+            taskDuration: Date.now() - pending.startTime,
+            outcome,
+            contextHash: hashProjectContext(context),
+        };
+        this.storage.recordEvent(event);
+        this.pendingEvents.delete(trackingId);
+    }
+    /**
+     * Record a complete event directly (for events that don't need start/end tracking)
+     *
+     * @param skillId - The skill identifier
+     * @param userId - Raw user identifier (will be anonymized)
+     * @param taskDuration - Duration in milliseconds
+     * @param outcome - The outcome
+     * @param context - Optional project context
+     */
+    recordEvent(skillId, userId, taskDuration, outcome, context = {}) {
+        const event = {
+            skillId,
+            userId: anonymizeUserId(userId),
+            timestamp: Date.now(),
+            taskDuration,
+            outcome,
+            contextHash: hashProjectContext(context),
+        };
+        this.storage.recordEvent(event);
+    }
+    /**
+     * Get metrics for a skill
+     *
+     * @param skillId - The skill identifier
+     * @returns Aggregated metrics or null if no data
+     */
+    getMetrics(skillId) {
+        return this.storage.getMetricsForSkill(skillId);
+    }
+    /**
+     * Get events for a skill
+     *
+     * @param skillId - The skill identifier
+     * @param limit - Maximum number of events
+     * @returns Array of usage events
+     */
+    getEvents(skillId, limit = 100) {
+        return this.storage.getEventsForSkill(skillId, limit);
+    }
+    /**
+     * Get total event count
+     *
+     * @returns Number of stored events
+     */
+    getEventCount() {
+        return this.storage.getEventCount();
+    }
+    /**
+     * Get count of pending (unfinished) trackings
+     *
+     * @returns Number of pending trackings
+     */
+    getPendingCount() {
+        return this.pendingEvents.size;
+    }
+    /**
+     * Clean up events older than 30 days
+     *
+     * @returns Number of deleted events
+     */
+    cleanup() {
+        return this.storage.cleanup();
+    }
+    /**
+     * Clean up stale sessions that have exceeded the timeout
+     * This prevents unbounded memory growth from sessions that are started but never ended
+     */
+    cleanupStaleSessions() {
+        const now = Date.now();
+        let expiredCount = 0;
+        for (const [trackingId, pending] of this.pendingEvents.entries()) {
+            if (now - pending.startTime > SESSION_TIMEOUT_MS) {
+                this.pendingEvents.delete(trackingId);
+                expiredCount++;
+            }
+        }
+        if (expiredCount > 0) {
+            console.warn(`[usage-tracker] Cleaned up ${expiredCount} stale sessions`);
+        }
+    }
+    /**
+     * Close the tracker and release resources
+     */
+    close() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        if (this.sessionCleanupTimer) {
+            clearInterval(this.sessionCleanupTimer);
+            this.sessionCleanupTimer = null;
+        }
+        this.storage.close();
+    }
+    /**
+     * Dispose of the tracker (alias for close)
+     * Clears all intervals and releases resources
+     */
+    dispose() {
+        this.close();
+    }
+}
+//# sourceMappingURL=usage-tracker.js.map

package/dist/analytics/usage-tracker.js.map

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