@skillsmith/core 0.5.5 → 0.5.6

package/dist/analytics/UsageAnalyticsService.d.ts

@@ -0,0 +1,55 @@
+/**
+ * UsageAnalyticsService - Epic 3: Attribution During Use
+ *
+ * Implements:
+ * - Local SQLite analytics storage
+ * - Usage tracking API with 30-day rolling window
+ * - Export functionality (JSON, CSV)
+ * - Value summary reports
+ */
+import type { Database as DatabaseType } from '../db/database-interface.js';
+import type { UsageEvent, UsageEventInput, UsageAnalyticsSummary, ExportFormat } from './types.js';
+export interface UsageStatsOptions {
+    startDate?: string;
+    endDate?: string;
+    skillId?: string;
+    userId?: string;
+}
+export declare class UsageAnalyticsService {
+    private repo;
+    private readonly RETENTION_DAYS;
+    constructor(db: DatabaseType);
+    /**
+     * Track a skill usage event
+     */
+    trackUsage(input: UsageEventInput): UsageEvent;
+    /**
+     * Get usage summary for a time period (defaults to last 30 days)
+     */
+    getUsageSummary(options?: UsageStatsOptions): UsageAnalyticsSummary;
+    /**
+     * Get weekly digest for a user
+     */
+    getWeeklyDigest(userId: string): UsageAnalyticsSummary;
+    /**
+     * Get monthly summary for a user
+     */
+    getMonthlySummary(userId: string): UsageAnalyticsSummary;
+    /**
+     * Export usage data in specified format
+     */
+    exportUsageData(options: UsageStatsOptions & {
+        format: ExportFormat;
+    }): string;
+    /**
+     * Clean up events older than retention period
+     */
+    cleanupOldData(): number;
+    private getDateRange;
+    private getAllEvents;
+    private groupEventsByType;
+    private calculateAverageValueScore;
+    private getTopSkills;
+    private convertToCSV;
+}
+//# sourceMappingURL=UsageAnalyticsService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UsageAnalyticsService.d.ts","sourceRoot":"","sources":["../../src/analytics/UsageAnalyticsService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAE3E,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAElG,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAK;gBAExB,EAAE,EAAE,YAAY;IAI5B;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU;IAI9C;;OAEG;IACH,eAAe,CAAC,OAAO,GAAE,iBAAsB,GAAG,qBAAqB;IAiCvE;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB;IAYtD;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB;IAYxD;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,GAAG,MAAM;IAkB9E;;OAEG;IACH,cAAc,IAAI,MAAM;IAMxB,OAAO,CAAC,YAAY;IAuBpB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,YAAY;CA8BrB"}

package/dist/analytics/UsageAnalyticsService.js

@@ -0,0 +1,180 @@
+/**
+ * UsageAnalyticsService - Epic 3: Attribution During Use
+ *
+ * Implements:
+ * - Local SQLite analytics storage
+ * - Usage tracking API with 30-day rolling window
+ * - Export functionality (JSON, CSV)
+ * - Value summary reports
+ */
+import { AnalyticsRepository } from './AnalyticsRepository.js';
+export class UsageAnalyticsService {
+    repo;
+    RETENTION_DAYS = 30;
+    constructor(db) {
+        this.repo = new AnalyticsRepository(db);
+    }
+    /**
+     * Track a skill usage event
+     */
+    trackUsage(input) {
+        return this.repo.recordUsageEvent(input);
+    }
+    /**
+     * Get usage summary for a time period (defaults to last 30 days)
+     */
+    getUsageSummary(options = {}) {
+        const { startDate, endDate, skillId, userId } = this.getDateRange(options);
+        // Get all events in the period
+        let events;
+        if (skillId) {
+            events = this.repo.getUsageEventsForSkill(skillId, startDate, endDate);
+        }
+        else if (userId) {
+            events = this.repo.getUsageEventsForUser(userId, startDate, endDate);
+        }
+        else {
+            // Get all events (for stakeholder view)
+            events = this.getAllEvents(startDate, endDate);
+        }
+        // Calculate statistics
+        const eventsByType = this.groupEventsByType(events);
+        const uniqueUsers = new Set(events.map((e) => e.userId)).size;
+        const uniqueSkills = new Set(events.map((e) => e.skillId)).size;
+        const avgValueScore = this.calculateAverageValueScore(events);
+        const topSkills = this.getTopSkills(events, 10);
+        return {
+            periodStart: startDate,
+            periodEnd: endDate,
+            totalEvents: events.length,
+            eventsByType,
+            uniqueUsers,
+            uniqueSkills,
+            avgValueScore,
+            topSkills,
+        };
+    }
+    /**
+     * Get weekly digest for a user
+     */
+    getWeeklyDigest(userId) {
+        const endDate = new Date();
+        const startDate = new Date(endDate);
+        startDate.setDate(startDate.getDate() - 7);
+        return this.getUsageSummary({
+            userId,
+            startDate: startDate.toISOString(),
+            endDate: endDate.toISOString(),
+        });
+    }
+    /**
+     * Get monthly summary for a user
+     */
+    getMonthlySummary(userId) {
+        const endDate = new Date();
+        const startDate = new Date(endDate);
+        startDate.setDate(startDate.getDate() - 30);
+        return this.getUsageSummary({
+            userId,
+            startDate: startDate.toISOString(),
+            endDate: endDate.toISOString(),
+        });
+    }
+    /**
+     * Export usage data in specified format
+     */
+    exportUsageData(options) {
+        const summary = this.getUsageSummary(options);
+        switch (options.format) {
+            case 'json':
+                return JSON.stringify(summary, null, 2);
+            case 'csv':
+                return this.convertToCSV(summary);
+            case 'pdf':
+                throw new Error('PDF export not yet implemented. Use json or csv format.');
+            default:
+                throw new Error(`Unsupported export format: ${options.format}`);
+        }
+    }
+    /**
+     * Clean up events older than retention period
+     */
+    cleanupOldData() {
+        return this.repo.cleanupOldEvents(this.RETENTION_DAYS);
+    }
+    // ==================== Private Helper Methods ====================
+    getDateRange(options) {
+        const endDate = options.endDate || new Date().toISOString();
+        let startDate = options.startDate;
+        if (!startDate) {
+            const date = new Date(endDate);
+            date.setDate(date.getDate() - this.RETENTION_DAYS);
+            startDate = date.toISOString();
+        }
+        return {
+            startDate,
+            endDate,
+            skillId: options.skillId,
+            userId: options.userId,
+        };
+    }
+    getAllEvents(startDate, endDate) {
+        return this.repo.getAllUsageEvents(startDate, endDate);
+    }
+    groupEventsByType(events) {
+        const groups = {
+            activation: 0,
+            invocation: 0,
+            success: 0,
+            failure: 0,
+        };
+        for (const event of events) {
+            groups[event.eventType] = (groups[event.eventType] || 0) + 1;
+        }
+        return groups;
+    }
+    calculateAverageValueScore(events) {
+        // Filter events that have a valid valueScore (not null or undefined)
+        const eventsWithScore = events.filter((e) => e.valueScore != null);
+        if (eventsWithScore.length === 0)
+            return 0;
+        const sum = eventsWithScore.reduce((acc, e) => acc + (e.valueScore || 0), 0);
+        return sum / eventsWithScore.length;
+    }
+    getTopSkills(events, limit) {
+        const counts = new Map();
+        for (const event of events) {
+            counts.set(event.skillId, (counts.get(event.skillId) || 0) + 1);
+        }
+        return Array.from(counts.entries())
+            .map(([skillId, count]) => ({ skillId, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, limit);
+    }
+    convertToCSV(summary) {
+        const lines = [];
+        // Header
+        lines.push('Metric,Value');
+        // Summary stats
+        lines.push(`Period Start,${summary.periodStart}`);
+        lines.push(`Period End,${summary.periodEnd}`);
+        lines.push(`Total Events,${summary.totalEvents}`);
+        lines.push(`Unique Users,${summary.uniqueUsers}`);
+        lines.push(`Unique Skills,${summary.uniqueSkills}`);
+        lines.push(`Average Value Score,${summary.avgValueScore.toFixed(2)}`);
+        // Events by type
+        lines.push('');
+        lines.push('Event Type,Count');
+        for (const [type, count] of Object.entries(summary.eventsByType)) {
+            lines.push(`${type},${count}`);
+        }
+        // Top skills
+        lines.push('');
+        lines.push('Skill ID,Usage Count');
+        for (const { skillId, count } of summary.topSkills) {
+            lines.push(`${skillId},${count}`);
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=UsageAnalyticsService.js.map

package/dist/analytics/UsageAnalyticsService.js.map

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

package/dist/analytics/anonymizer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * SMI-914: User Data Anonymization
+ * SMI-917: Per-installation salt for improved anonymization security
+ *
+ * Provides one-way hashing functions to anonymize user identifiers
+ * and project context without storing any PII.
+ */
+/**
+ * Get the path to the installation-specific salt file
+ *
+ * @returns Path to ~/.skillsmith/anonymizer-salt
+ */
+export declare function getSaltPath(): string;
+/**
+ * Load existing salt or create a new one for this installation
+ *
+ * The salt is:
+ * - Generated once per installation (32 random bytes)
+ * - Stored at ~/.skillsmith/anonymizer-salt
+ * - Cached in memory after first load
+ * - Falls back to static salt if file operations fail
+ *
+ * @returns Buffer containing the salt
+ */
+export declare function loadOrCreateSalt(): Buffer;
+/**
+ * Clear the cached salt (primarily for testing)
+ */
+export declare function clearSaltCache(): void;
+/**
+ * Anonymize a user identifier using SHA-256 hash
+ *
+ * The hash is:
+ * - One-way: Cannot recover the original identifier
+ * - Consistent: Same input always produces same output
+ * - Truncated: 16 characters for storage efficiency
+ *
+ * @param identifier - The user identifier to anonymize (e.g., machine ID, username)
+ * @returns Anonymized 16-character hex string
+ */
+export declare function anonymizeUserId(identifier: string): string;
+/**
+ * Hash project context to avoid storing PII
+ *
+ * Creates a deterministic hash of the project context object,
+ * allowing grouping of usage events by project type without
+ * storing actual project paths or names.
+ *
+ * @param context - Object containing project context (framework, language, etc.)
+ * @returns 8-character hex hash of the context
+ */
+export declare function hashProjectContext(context: Record<string, unknown>): string;
+//# sourceMappingURL=anonymizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"anonymizer.d.ts","sourceRoot":"","sources":["../../src/analytics/anonymizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAmBzC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAW1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAS3E"}

package/dist/analytics/anonymizer.js

@@ -0,0 +1,107 @@
+/**
+ * SMI-914: User Data Anonymization
+ * SMI-917: Per-installation salt for improved anonymization security
+ *
+ * Provides one-way hashing functions to anonymize user identifiers
+ * and project context without storing any PII.
+ */
+import { createHash, randomBytes } from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { CONTEXT_HASH_LENGTH, USER_ID_HASH_LENGTH } from './constants.js';
+/**
+ * Fallback salt used when file operations fail
+ */
+const FALLBACK_SALT = 'skillsmith-fallback-salt-v1';
+/**
+ * Cached salt buffer to avoid repeated file reads
+ */
+let cachedSalt = null;
+/**
+ * Get the path to the installation-specific salt file
+ *
+ * @returns Path to ~/.skillsmith/anonymizer-salt
+ */
+export function getSaltPath() {
+    return join(homedir(), '.skillsmith', 'anonymizer-salt');
+}
+/**
+ * Load existing salt or create a new one for this installation
+ *
+ * The salt is:
+ * - Generated once per installation (32 random bytes)
+ * - Stored at ~/.skillsmith/anonymizer-salt
+ * - Cached in memory after first load
+ * - Falls back to static salt if file operations fail
+ *
+ * @returns Buffer containing the salt
+ */
+export function loadOrCreateSalt() {
+    if (cachedSalt) {
+        return cachedSalt;
+    }
+    const saltPath = getSaltPath();
+    try {
+        if (existsSync(saltPath)) {
+            cachedSalt = readFileSync(saltPath);
+        }
+        else {
+            mkdirSync(join(homedir(), '.skillsmith'), { recursive: true });
+            cachedSalt = randomBytes(32);
+            writeFileSync(saltPath, cachedSalt);
+        }
+        return cachedSalt;
+    }
+    catch {
+        // Fallback to static salt if file operations fail
+        return Buffer.from(FALLBACK_SALT);
+    }
+}
+/**
+ * Clear the cached salt (primarily for testing)
+ */
+export function clearSaltCache() {
+    cachedSalt = null;
+}
+/**
+ * Anonymize a user identifier using SHA-256 hash
+ *
+ * The hash is:
+ * - One-way: Cannot recover the original identifier
+ * - Consistent: Same input always produces same output
+ * - Truncated: 16 characters for storage efficiency
+ *
+ * @param identifier - The user identifier to anonymize (e.g., machine ID, username)
+ * @returns Anonymized 16-character hex string
+ */
+export function anonymizeUserId(identifier) {
+    if (!identifier || identifier.trim().length === 0) {
+        throw new Error('User identifier cannot be empty');
+    }
+    const salt = loadOrCreateSalt();
+    return createHash('sha256')
+        .update(identifier)
+        .update(salt)
+        .digest('hex')
+        .slice(0, USER_ID_HASH_LENGTH);
+}
+/**
+ * Hash project context to avoid storing PII
+ *
+ * Creates a deterministic hash of the project context object,
+ * allowing grouping of usage events by project type without
+ * storing actual project paths or names.
+ *
+ * @param context - Object containing project context (framework, language, etc.)
+ * @returns 8-character hex hash of the context
+ */
+export function hashProjectContext(context) {
+    if (!context || Object.keys(context).length === 0) {
+        return '00000000'; // Empty context hash
+    }
+    // Sort keys for deterministic output
+    const normalized = JSON.stringify(context, Object.keys(context).sort());
+    return createHash('sha256').update(normalized).digest('hex').slice(0, CONTEXT_HASH_LENGTH);
+}
+//# sourceMappingURL=anonymizer.js.map

package/dist/analytics/anonymizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymizer.js","sourceRoot":"","sources":["../../src/analytics/anonymizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,IAAI,CAAA;AACvE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAA;AAC5B,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAEzE;;GAEG;AACH,MAAM,aAAa,GAAG,6BAA6B,CAAA;AAEnD;;GAEG;AACH,IAAI,UAAU,GAAkB,IAAI,CAAA;AAEpC;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,iBAAiB,CAAC,CAAA;AAC1D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,UAAU,CAAA;IACnB,CAAC;IAED,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;QACrC,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YAC9D,UAAU,GAAG,WAAW,CAAC,EAAE,CAAC,CAAA;YAC5B,aAAa,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QACrC,CAAC;QACD,OAAO,UAAU,CAAA;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;QAClD,OAAO,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IACnC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,UAAU,GAAG,IAAI,CAAA;AACnB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;IACpD,CAAC;IAED,MAAM,IAAI,GAAG,gBAAgB,EAAE,CAAA;IAC/B,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,UAAU,CAAC;SAClB,MAAM,CAAC,IAAI,CAAC;SACZ,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAA;AAClC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgC;IACjE,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,UAAU,CAAA,CAAC,qBAAqB;IACzC,CAAC;IAED,qCAAqC;IACrC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IAEvE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAA;AAC5F,CAAC"}

package/dist/analytics/constants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SMI-918: Analytics Constants
+ *
+ * Shared constants for analytics modules to eliminate magic numbers
+ * and improve code maintainability.
+ */
+/** Number of days to retain analytics data before cleanup */
+export declare const RETENTION_DAYS = 30;
+/** Cooldown period between suggestions in milliseconds */
+export declare const SUGGESTION_COOLDOWN_MS: number;
+/** Maximum suggestions per day per user */
+export declare const MAX_SUGGESTIONS_PER_DAY = 3;
+/** Length of truncated context hash */
+export declare const CONTEXT_HASH_LENGTH = 8;
+/** Milliseconds in one day */
+export declare const MS_PER_DAY: number;
+/** Length of truncated user ID hash */
+export declare const USER_ID_HASH_LENGTH = 16;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/analytics/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,cAAc,KAAK,CAAA;AAEhC,0DAA0D;AAC1D,eAAO,MAAM,sBAAsB,QAAgB,CAAA;AAEnD,2CAA2C;AAC3C,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,8BAA8B;AAC9B,eAAO,MAAM,UAAU,QAAsB,CAAA;AAE7C,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,KAAK,CAAA"}

package/dist/analytics/constants.js

@@ -0,0 +1,19 @@
+/**
+ * SMI-918: Analytics Constants
+ *
+ * Shared constants for analytics modules to eliminate magic numbers
+ * and improve code maintainability.
+ */
+/** Number of days to retain analytics data before cleanup */
+export const RETENTION_DAYS = 30;
+/** Cooldown period between suggestions in milliseconds */
+export const SUGGESTION_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+/** Maximum suggestions per day per user */
+export const MAX_SUGGESTIONS_PER_DAY = 3;
+/** Length of truncated context hash */
+export const CONTEXT_HASH_LENGTH = 8;
+/** Milliseconds in one day */
+export const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Length of truncated user ID hash */
+export const USER_ID_HASH_LENGTH = 16;
+//# sourceMappingURL=constants.js.map

package/dist/analytics/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/analytics/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAA;AAEhC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA,CAAC,YAAY;AAEhE,2CAA2C;AAC3C,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAExC,uCAAuC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAEpC,8BAA8B;AAC9B,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAE7C,uCAAuC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAA"}

package/dist/analytics/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Analytics Module - Phase 4 Product Strategy
+ *
+ * Exports all analytics infrastructure for:
+ * - Epic 3: Skill usage attribution and tracking
+ * - Epic 4: A/B testing and experimentation
+ * - Epic 4: ROI metrics and dashboards
+ * - SMI-914: Skill usage event tracking with anonymization
+ */
+export * from './types.js';
+export * from './schema.js';
+export * from './AnalyticsRepository.js';
+export * from './UsageAnalyticsService.js';
+export * from './ExperimentService.js';
+export * from './ROIDashboardService.js';
+export * from './anonymizer.js';
+export { AnalyticsStorage } from './storage.js';
+export { UsageTracker, type UsageTrackerOptions } from './usage-tracker.js';
+export { MetricsAggregator } from './metrics-aggregator.js';
+export type { AggregationPeriod, GlobalMetrics } from './metrics-aggregator.js';
+export { MetricsExporter } from './metrics-exporter.js';
+export type { MetricsExport, ExportOptions } from './metrics-exporter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AACtC,cAAc,0BAA0B,CAAA;AAGxC,cAAc,iBAAiB,CAAA;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAG3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/analytics/index.js

@@ -0,0 +1,23 @@
+/**
+ * Analytics Module - Phase 4 Product Strategy
+ *
+ * Exports all analytics infrastructure for:
+ * - Epic 3: Skill usage attribution and tracking
+ * - Epic 4: A/B testing and experimentation
+ * - Epic 4: ROI metrics and dashboards
+ * - SMI-914: Skill usage event tracking with anonymization
+ */
+export * from './types.js';
+export * from './schema.js';
+export * from './AnalyticsRepository.js';
+export * from './UsageAnalyticsService.js';
+export * from './ExperimentService.js';
+export * from './ROIDashboardService.js';
+// SMI-914: Skill usage event tracking
+export * from './anonymizer.js';
+export { AnalyticsStorage } from './storage.js';
+export { UsageTracker } from './usage-tracker.js';
+// SMI-915: Metrics aggregation and export
+export { MetricsAggregator } from './metrics-aggregator.js';
+export { MetricsExporter } from './metrics-exporter.js';
+//# sourceMappingURL=index.js.map

package/dist/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AACtC,cAAc,0BAA0B,CAAA;AAExC,sCAAsC;AACtC,cAAc,iBAAiB,CAAA;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,YAAY,EAA4B,MAAM,oBAAoB,CAAA;AAE3E,0CAA0C;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAE3D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/analytics/metrics-aggregator.d.ts

@@ -0,0 +1,98 @@
+/**
+ * SMI-915: Metrics Aggregator
+ *
+ * Aggregates skill usage events into actionable metrics for value measurement.
+ * Provides:
+ * - Per-skill metrics aggregation
+ * - Global metrics across all skills
+ * - Retention rate calculation
+ * - Time-period filtering
+ */
+import type { Database as DatabaseType } from '../db/database-interface.js';
+import type { SkillMetrics } from './types.js';
+/**
+ * Time period for aggregation queries
+ */
+export interface AggregationPeriod {
+    /** Start timestamp in milliseconds */
+    start: number;
+    /** End timestamp in milliseconds */
+    end: number;
+}
+/**
+ * Global metrics across all skills
+ */
+export interface GlobalMetrics {
+    /** Total number of skill invocations */
+    totalInvocations: number;
+    /** Count of unique users */
+    uniqueUsers: number;
+    /** Overall success rate (0-1) */
+    overallSuccessRate: number;
+    /** Average task duration in milliseconds */
+    avgTaskDuration: number;
+    /** Top skills by invocation count */
+    topSkills: Array<{
+        skillId: string;
+        invocations: number;
+    }>;
+}
+/**
+ * Aggregates skill usage metrics from the database
+ */
+export declare class MetricsAggregator {
+    private db;
+    /**
+     * Create a metrics aggregator
+     *
+     * @param db - SQLite database instance
+     */
+    constructor(db: DatabaseType);
+    /**
+     * Get metrics for a specific skill
+     *
+     * @param skillId - The skill identifier
+     * @param period - Optional time period filter
+     * @returns Aggregated metrics for the skill
+     */
+    getSkillMetrics(skillId: string, period?: AggregationPeriod): SkillMetrics;
+    /**
+     * Get metrics for all skills
+     *
+     * @param period - Optional time period filter
+     * @returns Array of metrics for each skill
+     */
+    getAllSkillMetrics(period?: AggregationPeriod): SkillMetrics[];
+    /**
+     * Get global metrics across all skills
+     *
+     * @param period - Optional time period filter
+     * @returns Aggregated metrics for all skills
+     */
+    getGlobalMetrics(period?: AggregationPeriod): GlobalMetrics;
+    /**
+     * Calculate retention rate (users who used skill again within N days)
+     *
+     * @param skillId - The skill identifier
+     * @param days - Retention window in days (default: 7)
+     * @returns Retention rate (0-1)
+     */
+    getRetentionRate(skillId: string, days?: number): number;
+    /**
+     * Get skills with usage in the specified period
+     *
+     * @param period - Time period filter
+     * @returns Array of skill IDs with usage
+     */
+    getActiveSkills(period: AggregationPeriod): string[];
+    /**
+     * Get the date range of available data
+     *
+     * @returns Object with min and max timestamps, or null if no data
+     */
+    getDataRange(): {
+        minTimestamp: number;
+        maxTimestamp: number;
+    } | null;
+}
+//# sourceMappingURL=metrics-aggregator.d.ts.map

package/dist/analytics/metrics-aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-aggregator.d.ts","sourceRoot":"","sources":["../../src/analytics/metrics-aggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAA;IACxB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,kBAAkB,EAAE,MAAM,CAAA;IAC1B,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAA;IACvB,qCAAqC;IACrC,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC3D;AA0CD;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,EAAE,CAAc;IAExB;;;;OAIG;gBACS,EAAE,EAAE,YAAY;IAI5B;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,YAAY;IAgC1E;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,YAAY,EAAE;IAY9D;;;;;OAKG;IACH,gBAAgB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,aAAa;IAyC3D;;;;;;OAMG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,MAAM;IAgC3D;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,EAAE;IAcpD;;;;OAIG;IACH,YAAY,IAAI;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAmBtE"}