deaf-intelligence 1.0.1

package/dist/validation.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Data validation pipeline — 5 rules applied to scraped data.
+ *
+ * Runs after scraping, before Excel generation. Flags issues but
+ * does not modify data — the scraper stores raw values, validation
+ * produces a report.
+ *
+ * Rules:
+ *   1. Future dates — no data point should be in the future
+ *   2. Negative values — streams/listeners/saves/adds can't be negative
+ *   3. Null/missing — required fields must be present
+ *   4. Spikes — value > 10× rolling average = flag (bot removal or viral)
+ *   5. Gaps — missing days in timeseries = flag
+ *
+ * SPEC-10 #5, P0.
+ */
+export interface ValidationIssue {
+    rule: "future_date" | "negative" | "null_required" | "spike" | "gap";
+    severity: "error" | "warning";
+    track?: string;
+    metric?: string;
+    date?: string;
+    value?: number;
+    message: string;
+}
+export interface ValidationReport {
+    timestamp: string;
+    issues: ValidationIssue[];
+    trackCount: number;
+    metricCount: number;
+    dateRange: {
+        from: string;
+        to: string;
+    } | null;
+}
+/**
+ * Validate S4A scraped data before Excel generation.
+ */
+export declare function validateS4AData(s4a: any): ValidationReport;
+/**
+ * Print validation report to console.
+ */
+export declare function printValidationReport(report: ValidationReport): void;

package/dist/validation.js

@@ -0,0 +1,138 @@
+/**
+ * Data validation pipeline — 5 rules applied to scraped data.
+ *
+ * Runs after scraping, before Excel generation. Flags issues but
+ * does not modify data — the scraper stores raw values, validation
+ * produces a report.
+ *
+ * Rules:
+ *   1. Future dates — no data point should be in the future
+ *   2. Negative values — streams/listeners/saves/adds can't be negative
+ *   3. Null/missing — required fields must be present
+ *   4. Spikes — value > 10× rolling average = flag (bot removal or viral)
+ *   5. Gaps — missing days in timeseries = flag
+ *
+ * SPEC-10 #5, P0.
+ */
+const METRICS = ["streams", "listeners", "saves", "playlist_adds", "streams_per_listener"];
+/**
+ * Validate S4A scraped data before Excel generation.
+ */
+export function validateS4AData(s4a) {
+    const issues = [];
+    const today = new Date().toISOString().slice(0, 10);
+    let trackCount = 0;
+    let earliestDate = "9999-99-99";
+    let latestDate = "0000-00-00";
+    if (!s4a?.perSong) {
+        issues.push({ rule: "null_required", severity: "error", message: "s4a.perSong is missing — no per-song data" });
+        return { timestamp: new Date().toISOString(), issues, trackCount: 0, metricCount: 0, dateRange: null };
+    }
+    for (const [tid, tData] of Object.entries(s4a.perSong)) {
+        trackCount++;
+        const trackName = tData.metadata?.name || tData.name || tid;
+        for (const metric of METRICS) {
+            const mData = tData[metric];
+            if (!mData)
+                continue;
+            // Rule 3: Required fields
+            if (mData.current_period_agg == null) {
+                issues.push({
+                    rule: "null_required", severity: "warning", track: trackName, metric,
+                    message: `${metric}.current_period_agg is null`,
+                });
+            }
+            const ts = mData.current_period_timeseries;
+            if (!ts || !Array.isArray(ts) || ts.length === 0)
+                continue;
+            // Collect dates for gap detection
+            const dates = [];
+            let prevDate = null;
+            const rollingWindow = [];
+            for (const pt of ts) {
+                const date = pt.x;
+                const val = Number(pt.y) || 0;
+                if (!date)
+                    continue;
+                dates.push(date);
+                if (date < earliestDate)
+                    earliestDate = date;
+                if (date > latestDate)
+                    latestDate = date;
+                // Rule 1: Future dates
+                if (date > today) {
+                    issues.push({
+                        rule: "future_date", severity: "error", track: trackName, metric, date, value: val,
+                        message: `Data point in the future: ${date} (today: ${today})`,
+                    });
+                }
+                // Rule 2: Negative values
+                if (val < 0 && metric !== "streams_per_listener") {
+                    issues.push({
+                        rule: "negative", severity: "warning", track: trackName, metric, date, value: val,
+                        message: `Negative value ${val} — possible bot removal or data correction`,
+                    });
+                }
+                // Rule 4: Spike detection (>10× rolling 30-day average)
+                rollingWindow.push(val);
+                if (rollingWindow.length > 30)
+                    rollingWindow.shift();
+                if (rollingWindow.length >= 14) {
+                    const avg = rollingWindow.slice(0, -1).reduce((a, b) => a + b, 0) / (rollingWindow.length - 1);
+                    if (avg > 0 && val > avg * 10) {
+                        issues.push({
+                            rule: "spike", severity: "warning", track: trackName, metric, date, value: val,
+                            message: `Spike: ${val} is ${(val / avg).toFixed(1)}× rolling avg (${avg.toFixed(0)})`,
+                        });
+                    }
+                }
+                // Rule 5: Gap detection (missing days)
+                if (prevDate) {
+                    const prevMs = new Date(prevDate).getTime();
+                    const curMs = new Date(date).getTime();
+                    const dayGap = Math.round((curMs - prevMs) / 86400000);
+                    if (dayGap > 1) {
+                        issues.push({
+                            rule: "gap", severity: "warning", track: trackName, metric, date,
+                            message: `${dayGap - 1} day gap: ${prevDate} → ${date}`,
+                        });
+                    }
+                }
+                prevDate = date;
+            }
+        }
+    }
+    return {
+        timestamp: new Date().toISOString(),
+        issues,
+        trackCount,
+        metricCount: METRICS.length,
+        dateRange: earliestDate < "9999" ? { from: earliestDate, to: latestDate } : null,
+    };
+}
+/**
+ * Print validation report to console.
+ */
+export function printValidationReport(report) {
+    const errors = report.issues.filter(i => i.severity === "error");
+    const warnings = report.issues.filter(i => i.severity === "warning");
+    console.log(`\n=== Validation Report (${report.timestamp}) ===`);
+    console.log(`Tracks: ${report.trackCount} | Metrics: ${report.metricCount}`);
+    if (report.dateRange)
+        console.log(`Date range: ${report.dateRange.from} → ${report.dateRange.to}`);
+    console.log(`Issues: ${errors.length} errors, ${warnings.length} warnings`);
+    if (errors.length > 0) {
+        console.log(`\nERRORS:`);
+        for (const e of errors)
+            console.log(`  ❌ [${e.track || ""}] ${e.message}`);
+    }
+    if (warnings.length > 0) {
+        console.log(`\nWARNINGS (first 20):`);
+        for (const w of warnings.slice(0, 20))
+            console.log(`  ⚠️  [${w.track || ""}] ${w.message}`);
+        if (warnings.length > 20)
+            console.log(`  ... and ${warnings.length - 20} more`);
+    }
+    if (report.issues.length === 0)
+        console.log(`\n✅ All checks passed.`);
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "deaf-intelligence",
+  "version": "1.0.1",
+  "description": "Spotify career intelligence. Track any artist, build history, get insights. MCP server.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "deaf-intelligence": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "spotify",
+    "music",
+    "analytics",
+    "artist",
+    "archivist",
+    "streaming",
+    "career",
+    "intelligence",
+    "model-context-protocol"
+  ],
+  "author": "Karel Dittrich (https://deaf.audio)",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://deaf.audio",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kareldittrich/deaf-audio.git",
+    "directory": "artist-os"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "exceljs": "^4.4.0",
+    "node-sqlite3-wasm": "^0.8.55",
+    "playwright-core": "^1.58.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}