@adityanair98/api-oracle 0.5.0

package/dist/dashboard/routes/api.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Dashboard REST API routes.
+ * All routes return { success: true, data: ... } or { success: false, error: "..." }
+ *
+ * Exports: apiRouter
+ */
+export declare const apiRouter: import("express-serve-static-core").Router;

package/dist/dashboard/routes/api.js

@@ -0,0 +1,245 @@
+/**
+ * Dashboard REST API routes.
+ * All routes return { success: true, data: ... } or { success: false, error: "..." }
+ *
+ * Exports: apiRouter
+ */
+import { Router } from "express";
+import { getAllEntries, getBySlug as getEntryBySlug } from "../../knowledge/db.js";
+import { findApis } from "../../knowledge/search.js";
+import { checkAllEntries, checkStaleness } from "../../updater/staleness.js";
+import { buildFreshnessReport, formatReport } from "../../updater/report.js";
+import { lintEntry } from "../../updater/linter.js";
+import { createLogger } from "../../utils/logger.js";
+const logger = createLogger("dashboard:api");
+export const apiRouter = Router();
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function ok(res, data) {
+    res.json({ success: true, data });
+}
+function err(res, status, message) {
+    res.status(status).json({ success: false, error: message });
+}
+const LEVEL_ORDER = {
+    fresh: 0, aging: 1, stale: 2, critical: 3,
+};
+function sortEntries(entries, sort, order) {
+    const stalenessMap = new Map(checkAllEntries(entries).map((i) => [i.slug, i.level]));
+    return [...entries].sort((a, b) => {
+        let cmp = 0;
+        switch (sort) {
+            case "name":
+                cmp = a.name.localeCompare(b.name);
+                break;
+            case "qualityScore":
+                cmp = a.qualityScore - b.qualityScore;
+                break;
+            case "lastVerified":
+                cmp = a.lastVerified.localeCompare(b.lastVerified);
+                break;
+            case "staleness": {
+                const la = LEVEL_ORDER[stalenessMap.get(a.slug) ?? "fresh"];
+                const lb = LEVEL_ORDER[stalenessMap.get(b.slug) ?? "fresh"];
+                cmp = la - lb;
+                break;
+            }
+        }
+        return order === "desc" ? -cmp : cmp;
+    });
+}
+// ─── GET /api/entries ─────────────────────────────────────────────────────────
+apiRouter.get("/entries", (req, res) => {
+    try {
+        let entries = getAllEntries();
+        const { category, search, sort = "name", order = "asc" } = req.query;
+        if (category && category !== "all") {
+            entries = entries.filter((e) => e.category === category);
+        }
+        if (search && search.trim()) {
+            const results = findApis(search.trim(), undefined, 68);
+            const slugSet = new Set(results.map((r) => r.entry.slug));
+            entries = entries.filter((e) => slugSet.has(e.slug));
+            // Preserve search order
+            const slugOrder = new Map(results.map((r, i) => [r.entry.slug, i]));
+            entries.sort((a, b) => (slugOrder.get(a.slug) ?? 99) - (slugOrder.get(b.slug) ?? 99));
+        }
+        else {
+            entries = sortEntries(entries, sort, order);
+        }
+        const stalenessInfos = checkAllEntries(entries);
+        const stalenessMap = new Map(stalenessInfos.map((i) => [i.slug, i]));
+        const data = entries.map((e) => {
+            const staleness = stalenessMap.get(e.slug);
+            return {
+                slug: e.slug,
+                name: e.name,
+                category: e.category,
+                subcategory: e.subcategory,
+                description: e.description.slice(0, 120) + (e.description.length > 120 ? "…" : ""),
+                qualityScore: e.qualityScore,
+                pricing: { model: e.pricing.model, freeTier: e.pricing.freeTier },
+                bestFor: e.bestFor,
+                lastVerified: e.lastVerified,
+                staleness: staleness
+                    ? { level: staleness.level, daysSinceVerified: staleness.daysSinceVerified }
+                    : null,
+            };
+        });
+        ok(res, data);
+    }
+    catch (e) {
+        logger.error("GET /api/entries error", { error: String(e) });
+        err(res, 500, "Internal server error");
+    }
+});
+// ─── GET /api/entries/:slug ───────────────────────────────────────────────────
+apiRouter.get("/entries/:slug", (req, res) => {
+    try {
+        const { slug } = req.params;
+        const entry = getEntryBySlug(slug);
+        if (!entry) {
+            err(res, 404, `No entry found with slug: ${slug}`);
+            return;
+        }
+        const staleness = checkStaleness(entry);
+        const lintResult = lintEntry(entry);
+        ok(res, { entry, staleness, lintResult });
+    }
+    catch (e) {
+        logger.error("GET /api/entries/:slug error", { error: String(e) });
+        err(res, 500, "Internal server error");
+    }
+});
+// ─── GET /api/categories ──────────────────────────────────────────────────────
+apiRouter.get("/categories", (_req, res) => {
+    try {
+        const entries = getAllEntries();
+        const counts = new Map();
+        for (const e of entries) {
+            counts.set(e.category, (counts.get(e.category) ?? 0) + 1);
+        }
+        const data = [...counts.entries()]
+            .map(([category, count]) => ({ category, count }))
+            .sort((a, b) => a.category.localeCompare(b.category));
+        ok(res, data);
+    }
+    catch (e) {
+        logger.error("GET /api/categories error", { error: String(e) });
+        err(res, 500, "Internal server error");
+    }
+});
+// ─── GET /api/stats ───────────────────────────────────────────────────────────
+apiRouter.get("/stats", (_req, res) => {
+    try {
+        const entries = getAllEntries();
+        const stalenessInfos = checkAllEntries(entries);
+        const staleness = { fresh: 0, aging: 0, stale: 0, critical: 0 };
+        for (const info of stalenessInfos)
+            staleness[info.level]++;
+        const lintResults = entries.map(lintEntry);
+        const lintPassing = lintResults.filter((r) => r.passed).length;
+        const avgQuality = entries.reduce((sum, e) => sum + e.qualityScore, 0) / entries.length;
+        const categories = new Set(entries.map((e) => e.category)).size;
+        ok(res, {
+            totalEntries: entries.length,
+            categories,
+            staleness,
+            linterResults: { passing: lintPassing, failing: entries.length - lintPassing },
+            averageQualityScore: Math.round(avgQuality * 10) / 10,
+            lastUpdated: new Date().toISOString(),
+        });
+    }
+    catch (e) {
+        logger.error("GET /api/stats error", { error: String(e) });
+        err(res, 500, "Internal server error");
+    }
+});
+// ─── GET /api/search ─────────────────────────────────────────────────────────
+apiRouter.get("/search", (req, res) => {
+    try {
+        const { q } = req.query;
+        if (!q || !q.trim()) {
+            err(res, 400, "Query param 'q' is required");
+            return;
+        }
+        const results = findApis(q.trim(), undefined, 5);
+        const data = {
+            query: q.trim(),
+            count: results.length,
+            results: results.map((r) => ({
+                slug: r.entry.slug,
+                name: r.entry.name,
+                category: r.entry.category,
+                score: Math.round(r.score * 1000) / 1000,
+                confidence: Math.round((r.confidence ?? 0) * 100),
+                scoreBreakdown: r.scoreBreakdown,
+                bestFor: r.entry.bestFor,
+                description: r.entry.description.slice(0, 120) + "…",
+            })),
+        };
+        ok(res, data);
+    }
+    catch (e) {
+        logger.error("GET /api/search error", { error: String(e) });
+        err(res, 500, "Internal server error");
+    }
+});
+// ─── GET /api/refresh-report ──────────────────────────────────────────────────
+apiRouter.get("/refresh-report", (_req, res) => {
+    try {
+        const entries = getAllEntries();
+        const allInfos = checkAllEntries(entries);
+        const report = buildFreshnessReport(allInfos);
+        ok(res, { report, markdown: formatReport(report) });
+    }
+    catch (e) {
+        logger.error("GET /api/refresh-report error", { error: String(e) });
+        err(res, 500, "Internal server error");
+    }
+});
+// ─── POST /api/entries/:slug/verify ──────────────────────────────────────────
+apiRouter.post("/entries/:slug/verify", (req, res) => {
+    try {
+        const { slug } = req.params;
+        const entry = getEntryBySlug(slug);
+        if (!entry) {
+            err(res, 404, `No entry found with slug: ${slug}`);
+            return;
+        }
+        // In a real setup this would write to the JSON file and re-seed.
+        // For the dashboard, we return the updated staleness as if verified now.
+        const today = new Date().toISOString().slice(0, 10);
+        const updatedEntry = { ...entry, lastVerified: today };
+        const staleness = checkStaleness(updatedEntry);
+        logger.info("Mark as verified (read-only — update JSON file to persist)", { slug, today });
+        ok(res, {
+            slug,
+            lastVerified: today,
+            staleness,
+            note: `To persist: update lastVerified in src/entries/**/${slug}.json and run npm run seed`,
+        });
+    }
+    catch (e) {
+        logger.error("POST /api/entries/:slug/verify error", { error: String(e) });
+        err(res, 500, "Internal server error");
+    }
+});
+// ─── GET /api/lint ────────────────────────────────────────────────────────────
+apiRouter.get("/lint", (_req, res) => {
+    try {
+        const entries = getAllEntries();
+        const results = entries.map(lintEntry);
+        const failing = results.filter((r) => !r.passed);
+        const passing = results.filter((r) => r.passed);
+        ok(res, {
+            total: results.length,
+            passing: passing.length,
+            failing: failing.length,
+            results: results.sort((a, b) => b.issues.length - a.issues.length),
+        });
+    }
+    catch (e) {
+        logger.error("GET /api/lint error", { error: String(e) });
+        err(res, 500, "Internal server error");
+    }
+});

package/dist/dashboard/server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * API Oracle Web Dashboard — Express server.
+ *
+ * Runs as a separate process from the MCP server.
+ * Start with: npm run dashboard
+ *
+ * Exports: startDashboard
+ */
+export declare function startDashboard(): void;

package/dist/dashboard/server.js

@@ -0,0 +1,45 @@
+/**
+ * API Oracle Web Dashboard — Express server.
+ *
+ * Runs as a separate process from the MCP server.
+ * Start with: npm run dashboard
+ *
+ * Exports: startDashboard
+ */
+import express from "express";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { initDb } from "../knowledge/db.js";
+import { config } from "../utils/config.js";
+import { createLogger } from "../utils/logger.js";
+import { apiRouter } from "./routes/api.js";
+const logger = createLogger("dashboard");
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3737;
+export function startDashboard() {
+    const app = express();
+    // Parse JSON bodies
+    app.use(express.json());
+    // Serve static frontend files
+    const publicDir = join(__dirname, "public");
+    app.use(express.static(publicDir));
+    // Mount REST API
+    app.use("/api", apiRouter);
+    // Catch-all: serve index.html for client-side routing
+    app.get("*", (_req, res) => {
+        res.sendFile(join(publicDir, "index.html"));
+    });
+    app.listen(PORT, () => {
+        process.stdout.write(`\n  API Oracle Dashboard\n`);
+        process.stdout.write(`  ───────────────────────────────\n`);
+        process.stdout.write(`  Local:   http://localhost:${PORT}\n`);
+        process.stdout.write(`  Entries: 68 APIs across 23 categories\n\n`);
+    });
+}
+// When run directly (npm run dashboard)
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+    logger.info("Initializing database for dashboard", { dbPath: config.dbPath });
+    initDb(config.dbPath);
+    startDashboard();
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Entry point — initializes the SQLite database and starts the MCP server.
+ * Run with: npm run dev (via tsx) or node dist/index.js (compiled).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * Entry point — initializes the SQLite database and starts the MCP server.
+ * Run with: npm run dev (via tsx) or node dist/index.js (compiled).
+ */
+import { initDb } from "./knowledge/db.js";
+import { startServer } from "./server.js";
+import { config } from "./utils/config.js";
+import { logger } from "./utils/logger.js";
+async function main() {
+    logger.info("Starting API Oracle MCP server", {
+        dbPath: config.dbPath,
+        nodeEnv: config.nodeEnv,
+    });
+    // Initialize SQLite database (creates tables if they don't exist)
+    initDb(config.dbPath);
+    logger.info("Database initialized");
+    // Start the MCP server on stdio
+    await startServer();
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${String(err)}\n`);
+    process.exit(1);
+});

package/dist/knowledge/db.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SQLite database initialization and query layer.
+ * Uses better-sqlite3 for synchronous access (safe in MCP server context).
+ * Complex nested objects are stored as JSON columns.
+ *
+ * Exports: initDb, insertEntry, getBySlug, getByCategory,
+ *          searchByText, getAllEntries, deleteBySlug, closeDb
+ */
+import Database from "better-sqlite3";
+import { type ApiEntry } from "./schema.js";
+export declare function initDb(dbPath?: string): void;
+export declare function getDb(): Database.Database;
+export declare function closeDb(): void;
+/** Allows tests to inject their own in-memory database instance */
+export declare function _setDbForTesting(testDb: Database.Database): void;
+export declare function insertEntry(entry: ApiEntry): void;
+export declare function getBySlug(slug: string): ApiEntry | null;
+export declare function getByCategory(category: string): ApiEntry[];
+export declare function searchByText(query: string): ApiEntry[];
+export declare function getAllEntries(): ApiEntry[];
+export declare function deleteBySlug(slug: string): void;
+export declare function slugExists(slug: string): boolean;

package/dist/knowledge/db.js

@@ -0,0 +1,182 @@
+/**
+ * SQLite database initialization and query layer.
+ * Uses better-sqlite3 for synchronous access (safe in MCP server context).
+ * Complex nested objects are stored as JSON columns.
+ *
+ * Exports: initDb, insertEntry, getBySlug, getByCategory,
+ *          searchByText, getAllEntries, deleteBySlug, closeDb
+ */
+import Database from "better-sqlite3";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+import { ApiEntrySchema, validateEntry } from "./schema.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("db");
+// Module-level db instance (singleton)
+let db = null;
+// ─── JSON columns — stored as serialized JSON strings ────────────────────────
+const JSON_COLUMNS = [
+    "useCases",
+    "auth",
+    "pricing",
+    "rateLimits",
+    "sdk",
+    "codeExamples",
+    "gotchas",
+    "reliability",
+    "alternatives",
+    "complementary",
+];
+// ─── Schema DDL ───────────────────────────────────────────────────────────────
+const CREATE_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS apis (
+    slug TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    category TEXT NOT NULL,
+    subcategory TEXT NOT NULL,
+    website TEXT NOT NULL,
+    description TEXT NOT NULL,
+    useCases TEXT NOT NULL,
+    auth TEXT NOT NULL,
+    pricing TEXT NOT NULL,
+    rateLimits TEXT NOT NULL,
+    sdk TEXT NOT NULL,
+    codeExamples TEXT NOT NULL,
+    gotchas TEXT NOT NULL,
+    reliability TEXT NOT NULL,
+    qualityScore REAL NOT NULL,
+    qualityJustification TEXT NOT NULL,
+    alternatives TEXT NOT NULL,
+    complementary TEXT NOT NULL,
+    bestFor TEXT NOT NULL,
+    lastVerified TEXT NOT NULL,
+    entryVersion INTEGER NOT NULL,
+    addedBy TEXT NOT NULL
+  );
+`;
+const CREATE_CATEGORY_INDEX_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_apis_category ON apis(category);
+`;
+const CREATE_QUALITY_INDEX_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_apis_quality ON apis(qualityScore DESC);
+`;
+// ─── Serialization helpers ────────────────────────────────────────────────────
+function serializeEntry(entry) {
+    const row = { ...entry };
+    for (const col of JSON_COLUMNS) {
+        row[col] = JSON.stringify(entry[col]);
+    }
+    return row;
+}
+function deserializeRow(row) {
+    const deserialized = { ...row };
+    for (const col of JSON_COLUMNS) {
+        if (typeof deserialized[col] === "string") {
+            deserialized[col] = JSON.parse(deserialized[col]);
+        }
+    }
+    const result = ApiEntrySchema.safeParse(deserialized);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => i.message).join(", ");
+        throw new Error(`Stored entry is invalid: ${issues}`);
+    }
+    return result.data;
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+export function initDb(dbPath = "./data/api-oracle.db") {
+    if (db)
+        return; // already initialized
+    if (dbPath !== ":memory:") {
+        mkdirSync(dirname(dbPath), { recursive: true });
+    }
+    db = new Database(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    db.exec(CREATE_TABLE_SQL);
+    db.exec(CREATE_CATEGORY_INDEX_SQL);
+    db.exec(CREATE_QUALITY_INDEX_SQL);
+    logger.info("Database initialized", { dbPath });
+}
+export function getDb() {
+    if (!db)
+        throw new Error("Database not initialized — call initDb() first");
+    return db;
+}
+export function closeDb() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}
+/** Allows tests to inject their own in-memory database instance */
+export function _setDbForTesting(testDb) {
+    testDb.exec(CREATE_TABLE_SQL);
+    testDb.exec(CREATE_CATEGORY_INDEX_SQL);
+    testDb.exec(CREATE_QUALITY_INDEX_SQL);
+    db = testDb;
+}
+export function insertEntry(entry) {
+    const validation = validateEntry(entry);
+    if (!validation.success) {
+        throw new Error(`Invalid entry: ${validation.errors.join("; ")}`);
+    }
+    const row = serializeEntry(validation.data);
+    const database = getDb();
+    const columns = Object.keys(row);
+    const placeholders = columns.map((c) => `@${c}`).join(", ");
+    const sql = `INSERT INTO apis (${columns.join(", ")}) VALUES (${placeholders})`;
+    const stmt = database.prepare(sql);
+    stmt.run(row);
+    logger.info("Inserted entry", { slug: entry.slug });
+}
+export function getBySlug(slug) {
+    const database = getDb();
+    const row = database
+        .prepare("SELECT * FROM apis WHERE slug = ?")
+        .get(slug);
+    if (!row)
+        return null;
+    return deserializeRow(row);
+}
+export function getByCategory(category) {
+    const database = getDb();
+    const rows = database
+        .prepare("SELECT * FROM apis WHERE category = ? ORDER BY qualityScore DESC")
+        .all(category);
+    return rows.map(deserializeRow);
+}
+export function searchByText(query) {
+    const database = getDb();
+    const pattern = `%${query}%`;
+    // Search across name, description, subcategory, bestFor, and JSON-encoded useCases
+    const rows = database
+        .prepare(`SELECT * FROM apis
+       WHERE name LIKE ?
+          OR description LIKE ?
+          OR subcategory LIKE ?
+          OR bestFor LIKE ?
+          OR useCases LIKE ?
+          OR category LIKE ?
+       ORDER BY qualityScore DESC`)
+        .all(pattern, pattern, pattern, pattern, pattern, pattern);
+    return rows.map(deserializeRow);
+}
+export function getAllEntries() {
+    const database = getDb();
+    const rows = database
+        .prepare("SELECT * FROM apis ORDER BY qualityScore DESC")
+        .all();
+    return rows.map(deserializeRow);
+}
+export function deleteBySlug(slug) {
+    const database = getDb();
+    database.prepare("DELETE FROM apis WHERE slug = ?").run(slug);
+    logger.info("Deleted entry", { slug });
+}
+export function slugExists(slug) {
+    const database = getDb();
+    const row = database
+        .prepare("SELECT 1 FROM apis WHERE slug = ?")
+        .get(slug);
+    return row !== undefined;
+}