@adityanair98/api-oracle 0.5.0

package/dist/tools/get-setup-guide.js

@@ -0,0 +1,127 @@
+/**
+ * MCP Tool: get_api_setup_guide
+ * Returns detailed, step-by-step setup instructions for a specific API.
+ *
+ * Exports: registerGetSetupGuide
+ */
+import { z } from "zod";
+import { getApiBySlug } from "../knowledge/search.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("tool:get-setup-guide");
+const inputSchema = {
+    slug: z.string().min(1).describe("The API slug to get setup instructions for, e.g. 'resend', 'stripe', 'clerk'"),
+    language: z
+        .string()
+        .optional()
+        .describe("Preferred language for code examples (default: 'typescript'). Must be a language the API supports."),
+};
+export function registerGetSetupGuide(server) {
+    server.tool("get_api_setup_guide", "Get complete, step-by-step setup instructions for a specific API including install command, auth setup, and working code examples.", inputSchema, async ({ slug, language }) => {
+        logger.info("get_api_setup_guide called", { slug, language });
+        try {
+            const entry = getApiBySlug(slug);
+            if (!entry) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: `API '${slug}' not found in the knowledge base`,
+                                suggestion: "Use find_best_api to discover available APIs and their slugs.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const targetLanguage = (language ?? "typescript").toLowerCase();
+            // Select appropriate code examples
+            const allExamples = entry.codeExamples;
+            const languageExamples = allExamples.filter((ex) => ex.language.toLowerCase() === targetLanguage);
+            const examples = languageExamples.length > 0 ? languageExamples : allExamples;
+            // Check if the requested language is supported
+            const supportedLanguages = [
+                entry.sdk.primaryLanguage,
+                ...entry.sdk.otherLanguages,
+            ];
+            const isLanguageSupported = supportedLanguages.some((l) => l.toLowerCase() === targetLanguage);
+            // Build the full code example (all examples concatenated with titles)
+            const fullCodeExample = examples.length > 0
+                ? examples
+                    .map((ex) => `// === ${ex.title} ===\n${ex.code}${ex.notes ? `\n// NOTE: ${ex.notes}` : ""}`)
+                    .join("\n\n")
+                : "// See documentation at " + entry.website;
+            // Build rate limit warning
+            const rateLimitWarning = `${entry.rateLimits.tier}: ${entry.rateLimits.limit}. ${entry.rateLimits.notes}. Retry strategy: ${entry.rateLimits.retryStrategy}`;
+            // Build pricing summary
+            const pricingParts = [
+                entry.pricing.freeTier ? `Free tier: ${entry.pricing.freeTier}` : null,
+                entry.pricing.startingPrice ? `Paid: ${entry.pricing.startingPrice}` : null,
+                entry.pricing.costPer ? `Per unit: ${entry.pricing.costPer}` : null,
+            ].filter(Boolean);
+            const response = {
+                name: entry.name,
+                slug: entry.slug,
+                website: entry.website,
+                category: entry.category,
+                description: entry.description,
+                // Auth setup
+                setupSteps: entry.auth.setupSteps,
+                envVarName: entry.auth.envVarName,
+                authMethod: entry.auth.method,
+                authCodeSnippet: entry.auth.codeSnippet,
+                // SDK info
+                installCommand: entry.sdk.installCommand,
+                importStatement: entry.sdk.importStatement,
+                supportedLanguages,
+                // Language warning if not supported
+                languageNote: !isLanguageSupported
+                    ? `Note: ${entry.name} does not have an official ${targetLanguage} SDK. Showing ${entry.sdk.primaryLanguage} examples instead. Community clients may exist.`
+                    : null,
+                // Code
+                codeExamples: examples.map((ex) => ({
+                    title: ex.title,
+                    language: ex.language,
+                    code: ex.code,
+                    notes: ex.notes,
+                })),
+                fullCodeExample,
+                // Practical info
+                gotchas: entry.gotchas,
+                rateLimitWarning,
+                pricing: pricingParts.join(". "),
+                pricingUrl: entry.pricing.pricingUrl,
+                // Reliability
+                uptimeGuarantee: entry.reliability.uptimeGuarantee,
+                statusPage: entry.reliability.statusPageUrl,
+                // Related
+                alternatives: entry.alternatives,
+                complementaryApis: entry.complementary,
+                // Meta
+                qualityScore: entry.qualityScore,
+                lastVerified: entry.lastVerified,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            logger.error("get_api_setup_guide error", err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Internal error while fetching setup guide",
+                            details: String(err),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/updater/linter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Entry quality linter for API Oracle.
+ *
+ * Applies heuristic quality rules beyond Zod schema validation.
+ * Checks for common content issues: vague descriptions, thin code examples,
+ * missing gotchas detail, suspicious field values, etc.
+ *
+ * Exports: LintIssue, LintSeverity, LintResult, lintEntry, lintAllEntries
+ */
+import type { ApiEntry } from "../knowledge/schema.js";
+export type LintSeverity = "error" | "warning" | "info";
+export interface LintIssue {
+    field: string;
+    severity: LintSeverity;
+    message: string;
+}
+export interface LintResult {
+    slug: string;
+    name: string;
+    issues: LintIssue[];
+    /** Entries with zero errors and warnings pass */
+    passed: boolean;
+}
+/**
+ * Lint a single entry and return all issues found.
+ */
+export declare function lintEntry(entry: ApiEntry): LintResult;
+/**
+ * Lint all entries. Returns results sorted: failed first, then passed.
+ */
+export declare function lintAllEntries(entries: ApiEntry[]): LintResult[];

package/dist/updater/linter.js

@@ -0,0 +1,219 @@
+/**
+ * Entry quality linter for API Oracle.
+ *
+ * Applies heuristic quality rules beyond Zod schema validation.
+ * Checks for common content issues: vague descriptions, thin code examples,
+ * missing gotchas detail, suspicious field values, etc.
+ *
+ * Exports: LintIssue, LintSeverity, LintResult, lintEntry, lintAllEntries
+ */
+const RULES = [
+    // ── Description quality ─────────────────────────────────────────────────
+    (e) => {
+        const issues = [];
+        if (e.description.length < 80) {
+            issues.push({
+                field: "description",
+                severity: "warning",
+                message: `Description is short (${e.description.length} chars). Aim for 100+ chars of useful context.`,
+            });
+        }
+        return issues;
+    },
+    // ── Code examples quality ───────────────────────────────────────────────
+    (e) => {
+        const issues = [];
+        if (e.codeExamples.length < 2) {
+            issues.push({
+                field: "codeExamples",
+                severity: "warning",
+                message: "Only 1 code example. 2+ examples showing different use cases are recommended.",
+            });
+        }
+        for (const ex of e.codeExamples) {
+            if (ex.code.split("\n").length < 5) {
+                issues.push({
+                    field: `codeExamples[${ex.title}].code`,
+                    severity: "warning",
+                    message: `Code example "${ex.title}" is very short (< 5 lines). Consider a more complete example.`,
+                });
+            }
+            if (!ex.notes || ex.notes.trim().length < 20) {
+                issues.push({
+                    field: `codeExamples[${ex.title}].notes`,
+                    severity: "info",
+                    message: `Code example "${ex.title}" has sparse notes. Add context about what the example demonstrates.`,
+                });
+            }
+        }
+        return issues;
+    },
+    // ── Gotchas quality ─────────────────────────────────────────────────────
+    (e) => {
+        const issues = [];
+        for (const gotcha of e.gotchas) {
+            if (gotcha.length < 50) {
+                issues.push({
+                    field: "gotchas",
+                    severity: "warning",
+                    message: `Gotcha is very short: "${gotcha.slice(0, 40)}...". Each gotcha should explain WHY it matters.`,
+                });
+            }
+        }
+        if (e.gotchas.length < 3) {
+            issues.push({
+                field: "gotchas",
+                severity: "info",
+                message: `Only ${e.gotchas.length} gotchas. Consider adding a 3rd with a less obvious pitfall.`,
+            });
+        }
+        return issues;
+    },
+    // ── Pricing completeness ─────────────────────────────────────────────────
+    (e) => {
+        const issues = [];
+        if (e.pricing.model === "paid" && e.pricing.startingPrice === null) {
+            issues.push({
+                field: "pricing.startingPrice",
+                severity: "warning",
+                message: "Pricing model is 'paid' but startingPrice is null. Add a price if publicly listed.",
+            });
+        }
+        if (e.pricing.model === "usage_based" && e.pricing.costPer === null) {
+            issues.push({
+                field: "pricing.costPer",
+                severity: "info",
+                message: "Usage-based pricing with no costPer breakdown. Add $/unit info if available.",
+            });
+        }
+        return issues;
+    },
+    // ── Setup steps quality ──────────────────────────────────────────────────
+    (e) => {
+        const issues = [];
+        if (e.auth.setupSteps.length < 3) {
+            issues.push({
+                field: "auth.setupSteps",
+                severity: "info",
+                message: `Only ${e.auth.setupSteps.length} setup step(s). Consider adding more detail for a complete setup guide.`,
+            });
+        }
+        return issues;
+    },
+    // ── Quality score vs justification consistency ───────────────────────────
+    (e) => {
+        const issues = [];
+        if (e.qualityScore >= 9 && e.qualityJustification.length < 80) {
+            issues.push({
+                field: "qualityJustification",
+                severity: "info",
+                message: `Score is ${e.qualityScore}/10 but justification is brief. Explain what earns this high rating.`,
+            });
+        }
+        if (e.qualityScore <= 4 && e.qualityJustification.length < 80) {
+            issues.push({
+                field: "qualityJustification",
+                severity: "info",
+                message: `Score is ${e.qualityScore}/10. Explain specifically why the score is low to help users make decisions.`,
+            });
+        }
+        return issues;
+    },
+    // ── Alternatives and complementary relationships ─────────────────────────
+    (e) => {
+        const issues = [];
+        if (e.alternatives.length === 0 && e.qualityScore < 9) {
+            issues.push({
+                field: "alternatives",
+                severity: "info",
+                message: "No alternatives listed. Most APIs have at least one competitor worth mentioning.",
+            });
+        }
+        if (e.complementary.length === 0) {
+            issues.push({
+                field: "complementary",
+                severity: "info",
+                message: "No complementary APIs listed. Most APIs work well with at least one other service.",
+            });
+        }
+        return issues;
+    },
+    // ── Reliability info ─────────────────────────────────────────────────────
+    (e) => {
+        const issues = [];
+        if (e.reliability.uptimeGuarantee === null && e.pricing.model !== "open_source") {
+            issues.push({
+                field: "reliability.uptimeGuarantee",
+                severity: "info",
+                message: "No uptime guarantee listed. Check the provider's SLA page.",
+            });
+        }
+        if (e.reliability.statusPageUrl === null && e.pricing.model !== "open_source") {
+            issues.push({
+                field: "reliability.statusPageUrl",
+                severity: "info",
+                message: "No status page URL. Most hosted APIs have a status page — check status.[provider].com.",
+            });
+        }
+        return issues;
+    },
+    // ── Use cases coverage ───────────────────────────────────────────────────
+    (e) => {
+        const issues = [];
+        if (e.useCases.length < 3) {
+            issues.push({
+                field: "useCases",
+                severity: "info",
+                message: `Only ${e.useCases.length} use case(s). Consider adding more to improve search discoverability.`,
+            });
+        }
+        const hasPerfect = e.useCases.some((u) => u.fit === "perfect");
+        if (!hasPerfect) {
+            issues.push({
+                field: "useCases",
+                severity: "warning",
+                message: "No use case has fit='perfect'. At least one core use case should be a perfect fit.",
+            });
+        }
+        return issues;
+    },
+];
+// ─── Core Functions ───────────────────────────────────────────────────────────
+/**
+ * Lint a single entry and return all issues found.
+ */
+export function lintEntry(entry) {
+    const issues = [];
+    for (const rule of RULES) {
+        issues.push(...rule(entry));
+    }
+    const passed = !issues.some((i) => i.severity === "error" || i.severity === "warning");
+    return { slug: entry.slug, name: entry.name, issues, passed };
+}
+/**
+ * Lint all entries. Returns results sorted: failed first, then passed.
+ */
+export function lintAllEntries(entries) {
+    return entries
+        .map(lintEntry)
+        .sort((a, b) => {
+        // Sort by issue count descending, then by slug
+        const aScore = issueScore(a);
+        const bScore = issueScore(b);
+        if (bScore !== aScore)
+            return bScore - aScore;
+        return a.slug.localeCompare(b.slug);
+    });
+}
+function issueScore(result) {
+    let score = 0;
+    for (const issue of result.issues) {
+        if (issue.severity === "error")
+            score += 100;
+        else if (issue.severity === "warning")
+            score += 10;
+        else
+            score += 1;
+    }
+    return score;
+}

package/dist/updater/report.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Report formatter for the API Oracle auto-updater.
+ *
+ * Formats staleness info and version diffs into a human-readable
+ * markdown/text report for the refresh-report script and MCP tool.
+ *
+ * Exports: FreshnessReport, buildFreshnessReport, formatReport
+ */
+import type { StalenessInfo, StalenessLevel } from "./staleness.js";
+import type { VersionDiff } from "./version-tracker.js";
+export interface FreshnessReport {
+    generatedAt: string;
+    totalEntries: number;
+    summary: Record<StalenessLevel, number>;
+    staleEntries: StalenessInfo[];
+    recentlyUpdated: VersionDiff[];
+}
+/**
+ * Build a structured freshness report from staleness data.
+ */
+export declare function buildFreshnessReport(allInfos: StalenessInfo[], versionDiffs?: VersionDiff[]): FreshnessReport;
+/**
+ * Format a freshness report as a human-readable markdown string.
+ */
+export declare function formatReport(report: FreshnessReport): string;
+/**
+ * Format a brief staleness summary suitable for an MCP tool response.
+ */
+export declare function formatBriefSummary(report: FreshnessReport): string;

package/dist/updater/report.js

@@ -0,0 +1,96 @@
+/**
+ * Report formatter for the API Oracle auto-updater.
+ *
+ * Formats staleness info and version diffs into a human-readable
+ * markdown/text report for the refresh-report script and MCP tool.
+ *
+ * Exports: FreshnessReport, buildFreshnessReport, formatReport
+ */
+// ─── Builders ─────────────────────────────────────────────────────────────────
+/**
+ * Build a structured freshness report from staleness data.
+ */
+export function buildFreshnessReport(allInfos, versionDiffs = []) {
+    const summary = {
+        fresh: 0,
+        aging: 0,
+        stale: 0,
+        critical: 0,
+    };
+    for (const info of allInfos) {
+        summary[info.level]++;
+    }
+    const staleEntries = allInfos.filter((i) => i.level === "stale" || i.level === "critical" || i.level === "aging");
+    return {
+        generatedAt: new Date().toISOString(),
+        totalEntries: allInfos.length,
+        summary,
+        staleEntries,
+        recentlyUpdated: versionDiffs,
+    };
+}
+// ─── Formatters ───────────────────────────────────────────────────────────────
+const LEVEL_EMOJI = {
+    fresh: "✅",
+    aging: "🟡",
+    stale: "🟠",
+    critical: "🔴",
+};
+/**
+ * Format a freshness report as a human-readable markdown string.
+ */
+export function formatReport(report) {
+    const lines = [];
+    lines.push("# API Oracle — Freshness Report");
+    lines.push(`Generated: ${report.generatedAt}`);
+    lines.push("");
+    lines.push("## Summary");
+    lines.push(`Total entries: **${report.totalEntries}**`);
+    lines.push("");
+    lines.push(`| Status | Count | Threshold |`, `|--------|-------|-----------|`, `| ${LEVEL_EMOJI.fresh} Fresh    | ${report.summary.fresh}  | Verified < 90 days ago |`, `| ${LEVEL_EMOJI.aging} Aging    | ${report.summary.aging}  | 90–180 days ago |`, `| ${LEVEL_EMOJI.stale} Stale    | ${report.summary.stale}  | 180–365 days ago |`, `| ${LEVEL_EMOJI.critical} Critical | ${report.summary.critical}  | > 365 days ago |`);
+    if (report.staleEntries.length === 0) {
+        lines.push("");
+        lines.push("## All entries are fresh — nothing to update! 🎉");
+    }
+    else {
+        lines.push("");
+        lines.push("## Entries Needing Attention");
+        lines.push(`| Slug | Name | Last Verified | Age (days) | Status |`, `|------|------|--------------|------------|--------|`);
+        for (const entry of report.staleEntries) {
+            const emoji = LEVEL_EMOJI[entry.level];
+            lines.push(`| ${entry.slug} | ${entry.name} | ${entry.lastVerified} | ${entry.daysSinceVerified} | ${emoji} ${entry.level} |`);
+        }
+    }
+    if (report.recentlyUpdated.length > 0) {
+        lines.push("");
+        lines.push("## Recently Updated Entries");
+        lines.push(`| Slug | Name | Change | Version |`, `|------|------|--------|---------|`);
+        for (const diff of report.recentlyUpdated) {
+            const versionStr = diff.changeType === "new"
+                ? `new (v${diff.currentVersion})`
+                : `v${diff.previousVersion ?? "?"} → v${diff.currentVersion}`;
+            lines.push(`| ${diff.slug} | ${diff.name} | ${diff.changeType} | ${versionStr} |`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Format a brief staleness summary suitable for an MCP tool response.
+ */
+export function formatBriefSummary(report) {
+    const { summary, totalEntries } = report;
+    const issues = summary.aging + summary.stale + summary.critical;
+    if (issues === 0) {
+        return `All ${totalEntries} entries are fresh (verified within 90 days). No updates needed.`;
+    }
+    const parts = [];
+    if (summary.critical > 0)
+        parts.push(`${summary.critical} critical (>1 year old)`);
+    if (summary.stale > 0)
+        parts.push(`${summary.stale} stale (6–12 months old)`);
+    if (summary.aging > 0)
+        parts.push(`${summary.aging} aging (3–6 months old)`);
+    return (`${totalEntries} entries total: ${summary.fresh} fresh, ${issues} need attention — ` +
+        parts.join(", ") +
+        ".");
+}

package/dist/updater/staleness.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Staleness checker for API Oracle knowledge base entries.
+ *
+ * Determines how "fresh" each entry is based on its lastVerified date
+ * and exposes structured staleness metadata per entry.
+ *
+ * Exports: StalenessLevel, StalenessInfo, checkStaleness, checkAllEntries
+ */
+import type { ApiEntry } from "../knowledge/schema.js";
+export type StalenessLevel = "fresh" | "aging" | "stale" | "critical";
+export interface StalenessInfo {
+    slug: string;
+    name: string;
+    lastVerified: string;
+    daysSinceVerified: number;
+    level: StalenessLevel;
+    /** ISO date of when this was computed */
+    checkedAt: string;
+}
+/**
+ * Compute staleness level from a day count.
+ */
+export declare function getStalenessLevel(daysSince: number): StalenessLevel;
+/**
+ * Compute the number of days between a date string (YYYY-MM-DD) and today.
+ */
+export declare function daysSince(dateStr: string, today?: Date): number;
+/**
+ * Check staleness for a single entry.
+ */
+export declare function checkStaleness(entry: ApiEntry, today?: Date): StalenessInfo;
+/**
+ * Check staleness for all entries, sorted from most stale to freshest.
+ */
+export declare function checkAllEntries(entries: ApiEntry[], today?: Date): StalenessInfo[];
+/**
+ * Filter entries by staleness level.
+ */
+export declare function filterByLevel(infos: StalenessInfo[], level: StalenessLevel): StalenessInfo[];

package/dist/updater/staleness.js

@@ -0,0 +1,66 @@
+/**
+ * Staleness checker for API Oracle knowledge base entries.
+ *
+ * Determines how "fresh" each entry is based on its lastVerified date
+ * and exposes structured staleness metadata per entry.
+ *
+ * Exports: StalenessLevel, StalenessInfo, checkStaleness, checkAllEntries
+ */
+// ─── Thresholds ───────────────────────────────────────────────────────────────
+// How many days since lastVerified before an entry is considered each level.
+const THRESHOLDS = {
+    fresh: 90, // < 90 days → fresh
+    aging: 180, // 90–180 days → aging
+    stale: 365, // 180–365 days → stale
+    // > 365 days → critical
+};
+// ─── Core Functions ───────────────────────────────────────────────────────────
+/**
+ * Compute staleness level from a day count.
+ */
+export function getStalenessLevel(daysSince) {
+    if (daysSince < THRESHOLDS.fresh)
+        return "fresh";
+    if (daysSince < THRESHOLDS.aging)
+        return "aging";
+    if (daysSince < THRESHOLDS.stale)
+        return "stale";
+    return "critical";
+}
+/**
+ * Compute the number of days between a date string (YYYY-MM-DD) and today.
+ */
+export function daysSince(dateStr, today = new Date()) {
+    const then = new Date(dateStr + "T00:00:00Z");
+    const todayUtc = Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate());
+    const diff = todayUtc - then.getTime();
+    return Math.max(0, Math.floor(diff / (1000 * 60 * 60 * 24)));
+}
+/**
+ * Check staleness for a single entry.
+ */
+export function checkStaleness(entry, today) {
+    const days = daysSince(entry.lastVerified, today);
+    return {
+        slug: entry.slug,
+        name: entry.name,
+        lastVerified: entry.lastVerified,
+        daysSinceVerified: days,
+        level: getStalenessLevel(days),
+        checkedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Check staleness for all entries, sorted from most stale to freshest.
+ */
+export function checkAllEntries(entries, today) {
+    return entries
+        .map((e) => checkStaleness(e, today))
+        .sort((a, b) => b.daysSinceVerified - a.daysSinceVerified);
+}
+/**
+ * Filter entries by staleness level.
+ */
+export function filterByLevel(infos, level) {
+    return infos.filter((i) => i.level === level);
+}

package/dist/updater/version-tracker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Version tracker for API Oracle entries.
+ *
+ * Reads the current entryVersion from each entry and compares to a stored
+ * baseline to detect entries that have been updated since the last review.
+ *
+ * Exports: VersionSnapshot, VersionDiff, buildSnapshot, diffSnapshot
+ */
+import type { ApiEntry } from "../knowledge/schema.js";
+/** A map of slug → entryVersion, stored as a JSON snapshot. */
+export type VersionSnapshot = Record<string, number>;
+export interface VersionDiff {
+    slug: string;
+    name: string;
+    previousVersion: number | null;
+    currentVersion: number;
+    /** "new" = entry added since snapshot; "updated" = version incremented */
+    changeType: "new" | "updated";
+}
+/**
+ * Build a version snapshot from a list of entries.
+ */
+export declare function buildSnapshot(entries: ApiEntry[]): VersionSnapshot;
+/**
+ * Diff a current entry list against a stored snapshot.
+ * Returns entries that are new or have an incremented version.
+ */
+export declare function diffSnapshot(entries: ApiEntry[], previousSnapshot: VersionSnapshot): VersionDiff[];