@mcptoolshop/registry-stats 3.2.0 → 3.2.3

package/dist/index.cjs

@@ -59,9 +59,10 @@ var RETRYABLE = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var MAX_RETRIES = 3;
 var BASE_DELAY = 1e3;
 var registryLocks = /* @__PURE__ */ new Map();
+var MAX_LOCK_ENTRIES = 50;
 var REGISTRY_DELAYS = {
-  npm: 400,
-  // ~2.5 req/s — safe for 54+ scoped packages
+  npm: 800,
+  // ~1.25 req/s — safe for 91+ scoped packages (429s at 400ms)
   pypi: 2200,
   // 30 req/60s = 1 per 2s, with headroom
   docker: 4e3
@@ -73,13 +74,27 @@ function acquireSlot(registry) {
   const prev = registryLocks.get(registry) ?? Promise.resolve();
   const slot = prev.then(() => new Promise((r) => setTimeout(r, minDelay)));
   registryLocks.set(registry, slot);
+  if (registryLocks.size > MAX_LOCK_ENTRIES) {
+    const oldest = registryLocks.keys().next().value;
+    if (oldest !== void 0) registryLocks.delete(oldest);
+  }
   return prev;
 }
-async function fetchWithRetry(url, registry, init) {
+async function fetchRetryCore(url, registry, init, preRequest) {
   let lastError;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    await acquireSlot(registry);
-    const res = await fetch(url, { signal: AbortSignal.timeout(3e4), ...init });
+    if (preRequest) await preRequest();
+    let res;
+    try {
+      res = await fetch(url, { signal: AbortSignal.timeout(3e4), ...init });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      lastError = new RegistryError(registry, 0, `Network error: ${message} \u2014 ${url}`);
+      if (attempt === MAX_RETRIES) break;
+      const backoff2 = BASE_DELAY * Math.pow(2, attempt);
+      await new Promise((r) => setTimeout(r, backoff2));
+      continue;
+    }
     if (res.status === 404) return null;
     if (res.ok) return res.json();
     const retryAfter = res.headers.get("retry-after");
@@ -96,29 +111,13 @@ async function fetchWithRetry(url, registry, init) {
     const delay = Math.max(backoff, retryAfterMs);
     await new Promise((r) => setTimeout(r, delay));
   }
-  throw lastError;
+  throw lastError ?? new RegistryError(registry, 0, `Fetch failed after ${MAX_RETRIES} retries: ${url}`);
+}
+async function fetchWithRetry(url, registry, init) {
+  return fetchRetryCore(url, registry, init, () => acquireSlot(registry));
 }
 async function fetchDirect(url, registry, init) {
-  let lastError;
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    const res = await fetch(url, { signal: AbortSignal.timeout(3e4), ...init });
-    if (res.status === 404) return null;
-    if (res.ok) return res.json();
-    const retryAfter = res.headers.get("retry-after");
-    const retryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : void 0;
-    lastError = new RegistryError(
-      registry,
-      res.status,
-      `${res.statusText}: ${url}`,
-      retryAfterSeconds
-    );
-    if (!RETRYABLE.has(res.status) || attempt === MAX_RETRIES) break;
-    const backoff = BASE_DELAY * Math.pow(2, attempt);
-    const retryAfterMs = retryAfterSeconds ? retryAfterSeconds * 1e3 : 0;
-    const delay = Math.max(backoff, retryAfterMs);
-    await new Promise((r) => setTimeout(r, delay));
-  }
-  throw lastError;
+  return fetchRetryCore(url, registry, init);
 }
 
 // src/providers/npm.ts
@@ -130,7 +129,7 @@ var npm = {
     const start = new Date(end);
     start.setDate(start.getDate() - 30);
     const data = await fetchWithRetry(
-      `${API}/range/${fmt(start)}:${fmt(end)}/${pkg}`,
+      `${API}/range/${fmt(start)}:${fmt(end)}/${encodeNpmPackage(pkg)}`,
       "npm"
     );
     if (!data || !data.downloads || data.downloads.length === 0) return null;
@@ -157,7 +156,7 @@ var npm = {
       const actualEnd = chunkEnd > endDate ? endDate : chunkEnd;
       const s = fmt(cursor);
       const e = fmt(actualEnd);
-      const data = await fetchWithRetry(`${API}/range/${s}:${e}/${pkg}`, "npm");
+      const data = await fetchWithRetry(`${API}/range/${s}:${e}/${encodeNpmPackage(pkg)}`, "npm");
       if (data) {
         for (const d of data.downloads) {
           chunks.push({ date: d.day, downloads: d.downloads });
@@ -193,6 +192,9 @@ async function npmBulkPoint(packages, period = "last-month") {
 function fmt(d) {
   return d.toISOString().slice(0, 10);
 }
+function encodeNpmPackage(pkg) {
+  return encodeURIComponent(pkg);
+}
 
 // src/providers/pypi.ts
 var API2 = "https://pypistats.org/api";
@@ -200,9 +202,10 @@ var pypi = {
   name: "pypi",
   rateLimit: { maxRequests: 30, windowSeconds: 60, authRaisesLimit: false },
   async getStats(pkg) {
+    const safePkg = encodeURIComponent(pkg);
     const [recent, overall] = await Promise.all([
-      fetchWithRetry(`${API2}/packages/${pkg}/recent`, "pypi"),
-      fetchWithRetry(`${API2}/packages/${pkg}/overall?mirrors=false`, "pypi")
+      fetchWithRetry(`${API2}/packages/${safePkg}/recent`, "pypi"),
+      fetchWithRetry(`${API2}/packages/${safePkg}/overall?mirrors=false`, "pypi")
     ]);
     if (!recent && !overall) return null;
     const total = overall?.data?.filter((d) => d.category === "without_mirrors")?.reduce((sum, d) => sum + d.downloads, 0);
@@ -219,8 +222,9 @@ var pypi = {
     };
   },
   async getRange(pkg, start, end) {
+    const safePkg = encodeURIComponent(pkg);
     const data = await fetchWithRetry(
-      `${API2}/packages/${pkg}/overall?mirrors=false`,
+      `${API2}/packages/${safePkg}/overall?mirrors=false`,
       "pypi"
     );
     if (!data) return [];
@@ -343,13 +347,16 @@ var docker = {
 
 // src/calc.ts
 var calc = {
+  /** Sum all downloads in the given records. */
   total(records) {
     return records.reduce((sum, r) => sum + r.downloads, 0);
   },
+  /** Compute average daily downloads. Returns 0 for empty input. */
   avg(records) {
     if (records.length === 0) return 0;
     return calc.total(records) / records.length;
   },
+  /** Group records by a custom key function. */
   group(records, fn) {
     const groups = {};
     for (const r of records) {
@@ -358,12 +365,15 @@ var calc = {
     }
     return groups;
   },
+  /** Group records by month (YYYY-MM keys). */
   monthly(records) {
     return calc.group(records, (r) => r.date.slice(0, 7));
   },
+  /** Group records by year (YYYY keys). */
   yearly(records) {
     return calc.group(records, (r) => r.date.slice(0, 4));
   },
+  /** Sum downloads within each group. */
   groupTotals(grouped) {
     const result = {};
     for (const [key, records] of Object.entries(grouped)) {
@@ -371,6 +381,7 @@ var calc = {
     }
     return result;
   },
+  /** Average downloads within each group. */
   groupAvgs(grouped) {
     const result = {};
     for (const [key, records] of Object.entries(grouped)) {
@@ -378,6 +389,7 @@ var calc = {
     }
     return result;
   },
+  /** Detect trend direction (up/down/flat) by comparing recent vs previous window averages. */
   trend(records, windowDays = 7) {
     if (records.length < windowDays * 2) {
       return { slope: 0, direction: "flat", changePercent: 0 };
@@ -393,6 +405,7 @@ var calc = {
     const direction = slope > threshold ? "up" : slope < -threshold ? "down" : "flat";
     return { slope: Math.round(slope * 100) / 100, direction, changePercent: Math.round(changePercent * 100) / 100 };
   },
+  /** Compute a simple moving average over a sliding window. */
   movingAvg(records, windowDays = 7) {
     if (records.length < windowDays) return [];
     const sorted = [...records].sort((a, b) => a.date.localeCompare(b.date));
@@ -409,6 +422,7 @@ var calc = {
     }
     return result;
   },
+  /** Compute a 0-100 popularity score based on log-scaled recent daily downloads. */
   popularity(records) {
     if (records.length === 0) return 0;
     const sorted = [...records].sort((a, b) => a.date.localeCompare(b.date));
@@ -418,6 +432,7 @@ var calc = {
     const score = Math.max(0, Math.min(100, Math.log10(Math.max(1, avgDaily)) / 6 * 100));
     return Math.round(score * 10) / 10;
   },
+  /** Convert records to CSV string with date,downloads columns. */
   toCSV(records) {
     const sorted = [...records].sort((a, b) => a.date.localeCompare(b.date));
     const lines = ["date,downloads"];
@@ -426,6 +441,7 @@ var calc = {
     }
     return lines.join("\n");
   },
+  /** Convert records to a ChartData object suitable for chart libraries. */
   toChartData(records, label = "downloads") {
     const sorted = [...records].sort((a, b) => a.date.localeCompare(b.date));
     return {
@@ -445,7 +461,14 @@ function loadConfig(startDir) {
     const configPath = (0, import_node_path.resolve)(dir, CONFIG_NAME);
     if ((0, import_node_fs.existsSync)(configPath)) {
       const raw = (0, import_node_fs.readFileSync)(configPath, "utf-8");
-      return JSON.parse(raw);
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid JSON in ${configPath}: ${message}`);
+      }
+      return validateConfig(parsed, configPath);
     }
     const parent = (0, import_node_path.dirname)(dir);
     if (parent === dir) break;
@@ -453,6 +476,50 @@ function loadConfig(startDir) {
   }
   return null;
 }
+function validateConfig(raw, source) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`Config in ${source} must be a JSON object, got ${Array.isArray(raw) ? "array" : typeof raw}`);
+  }
+  const obj = raw;
+  const config = {};
+  if (obj.registries !== void 0) {
+    if (!Array.isArray(obj.registries) || !obj.registries.every((r) => typeof r === "string")) {
+      throw new Error(`Config "registries" must be an array of strings in ${source}`);
+    }
+    config.registries = obj.registries;
+  }
+  if (obj.packages !== void 0) {
+    if (typeof obj.packages !== "object" || obj.packages === null || Array.isArray(obj.packages)) {
+      throw new Error(`Config "packages" must be an object in ${source}`);
+    }
+    config.packages = obj.packages;
+  }
+  if (obj.cache !== void 0) {
+    if (typeof obj.cache !== "boolean") {
+      throw new Error(`Config "cache" must be a boolean in ${source}`);
+    }
+    config.cache = obj.cache;
+  }
+  if (obj.cacheTtlMs !== void 0) {
+    if (typeof obj.cacheTtlMs !== "number" || obj.cacheTtlMs <= 0 || !Number.isFinite(obj.cacheTtlMs)) {
+      throw new Error(`Config "cacheTtlMs" must be a positive number in ${source}`);
+    }
+    config.cacheTtlMs = obj.cacheTtlMs;
+  }
+  if (obj.concurrency !== void 0) {
+    if (typeof obj.concurrency !== "number" || obj.concurrency < 1 || !Number.isInteger(obj.concurrency)) {
+      throw new Error(`Config "concurrency" must be a positive integer in ${source}`);
+    }
+    config.concurrency = obj.concurrency;
+  }
+  if (obj.dockerToken !== void 0) {
+    if (typeof obj.dockerToken !== "string") {
+      throw new Error(`Config "dockerToken" must be a string in ${source}`);
+    }
+    config.dockerToken = obj.dockerToken;
+  }
+  return config;
+}
 function defaultConfig() {
   return {
     registries: ["npm", "pypi", "nuget", "vscode", "docker"],
@@ -481,6 +548,36 @@ function starterConfig() {
 
 // src/server.ts
 var import_node_http = require("http");
+function createRateLimiter(maxRequests, windowSeconds) {
+  const buckets = /* @__PURE__ */ new Map();
+  const cleanup = setInterval(() => {
+    const now = Date.now();
+    for (const [ip, bucket] of buckets) {
+      if (now > bucket.resetAt) buckets.delete(ip);
+    }
+  }, 6e4);
+  cleanup.unref();
+  return {
+    /** Returns true if the request is allowed, false if rate-limited. */
+    allow(ip) {
+      const now = Date.now();
+      const bucket = buckets.get(ip);
+      if (!bucket || now > bucket.resetAt) {
+        buckets.set(ip, { count: 1, resetAt: now + windowSeconds * 1e3 });
+        return true;
+      }
+      bucket.count++;
+      return bucket.count <= maxRequests;
+    },
+    /** Exposed for testing — clear all buckets. */
+    reset() {
+      buckets.clear();
+    }
+  };
+}
+function sanitizeFilename(value) {
+  return value.replace(/[^a-zA-Z0-9._@/-]/g, "_").slice(0, 200);
+}
 function json(res, data, status = 200) {
   res.writeHead(status, { "Content-Type": "application/json" });
   res.end(JSON.stringify(data));
@@ -500,13 +597,43 @@ function parseUrl(url) {
   }
   return { path, query };
 }
+function withTimeout(promise, ms) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => reject(new Error("__TIMEOUT__")), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve2(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+function getClientIp(req) {
+  const forwarded = req.headers["x-forwarded-for"];
+  if (typeof forwarded === "string") return forwarded.split(",")[0].trim();
+  return req.socket.remoteAddress ?? "0.0.0.0";
+}
 function createHandler(opts) {
   const options = { ...opts };
   if (!options.cache) {
     options.cache = createCache();
   }
+  const corsOrigin = opts?.corsOrigin ?? "*";
+  const timeoutMs = opts?.requestTimeoutMs ?? 3e4;
+  const limiter = createRateLimiter(
+    opts?.rateLimitMax ?? 60,
+    opts?.rateLimitWindowSeconds ?? 60
+  );
   return async (req, res) => {
-    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("X-Frame-Options", "DENY");
+    res.setHeader("X-XSS-Protection", "1; mode=block");
+    res.setHeader("Cache-Control", "no-store");
+    res.setHeader("Access-Control-Allow-Origin", corsOrigin);
     res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type");
     if (req.method === "OPTIONS") {
@@ -514,6 +641,11 @@ function createHandler(opts) {
       res.end();
       return;
     }
+    const clientIp = getClientIp(req);
+    if (!limiter.allow(clientIp)) {
+      error(res, "Too many requests", 429);
+      return;
+    }
     if (req.method !== "GET") {
       error(res, "Method not allowed", 405);
       return;
@@ -523,14 +655,14 @@ function createHandler(opts) {
       if (path[0] === "stats") {
         if (path.length === 2) {
           const pkg = decodeURIComponent(path[1]);
-          const results = await stats.all(pkg, options);
+          const results = await withTimeout(stats.all(pkg, options), timeoutMs);
           json(res, results);
           return;
         }
         if (path.length >= 3) {
           const registry = path[1];
           const pkg = path.slice(2).join("/");
-          const result = await stats(registry, pkg, options);
+          const result = await withTimeout(stats(registry, pkg, options), timeoutMs);
           if (!result) {
             error(res, `Package "${pkg}" not found on ${registry}`, 404);
             return;
@@ -542,7 +674,7 @@ function createHandler(opts) {
       if (path[0] === "compare" && path.length >= 2) {
         const pkg = decodeURIComponent(path[1]);
         const registries = query.registries ? query.registries.split(",") : void 0;
-        const result = await stats.compare(pkg, registries, options);
+        const result = await withTimeout(stats.compare(pkg, registries, options), timeoutMs);
         json(res, result);
         return;
       }
@@ -554,11 +686,14 @@ function createHandler(opts) {
           error(res, "Missing start and end query parameters");
           return;
         }
-        const data = await stats.range(registry, pkg, start, end, options);
+        const data = await withTimeout(stats.range(registry, pkg, start, end, options), timeoutMs);
         if (format === "csv") {
+          const safePkg = sanitizeFilename(pkg);
+          const safeStart = sanitizeFilename(start);
+          const safeEnd = sanitizeFilename(end);
           res.writeHead(200, {
             "Content-Type": "text/csv",
-            "Content-Disposition": `attachment; filename="${pkg}-${start}-${end}.csv"`
+            "Content-Disposition": `attachment; filename="${safePkg}-${safeStart}-${safeEnd}.csv"`
           });
           res.end(calc.toCSV(data));
           return;
@@ -584,11 +719,13 @@ function createHandler(opts) {
       }
       error(res, "Not found", 404);
     } catch (e) {
-      if (e instanceof RegistryError) {
+      if (e?.message === "__TIMEOUT__") {
+        error(res, "Gateway timeout", 504);
+      } else if (e instanceof RegistryError) {
         const status = e.statusCode === 429 ? 429 : e.statusCode === 404 ? 404 : e.statusCode >= 500 ? 502 : 500;
         error(res, e.message, status);
       } else {
-        error(res, e.message, 500);
+        error(res, "Internal server error", 500);
       }
     }
   };
@@ -596,7 +733,11 @@ function createHandler(opts) {
 function serve(opts) {
   const port = opts?.port ?? 3e3;
   const handler = createHandler({
-    cache: opts?.cache !== false ? createCache() : void 0
+    cache: opts?.cache !== false ? createCache() : void 0,
+    corsOrigin: opts?.corsOrigin,
+    rateLimitMax: opts?.rateLimitMax,
+    rateLimitWindowSeconds: opts?.rateLimitWindowSeconds,
+    requestTimeoutMs: opts?.requestTimeoutMs
   });
   const server = (0, import_node_http.createServer)(handler);
   server.listen(port, () => {
@@ -612,6 +753,9 @@ Endpoints:`);
 }
 
 // src/inference.ts
+function sanitize(arr) {
+  return arr.filter((v) => Number.isFinite(v));
+}
 function mean(arr) {
   if (arr.length === 0) return 0;
   return arr.reduce((a, b) => a + b, 0) / arr.length;
@@ -619,7 +763,7 @@ function mean(arr) {
 function stddev(arr) {
   if (arr.length < 2) return 0;
   const m = mean(arr);
-  const variance = arr.reduce((s, v) => s + (v - m) ** 2, 0) / arr.length;
+  const variance = arr.reduce((s, v) => s + (v - m) ** 2, 0) / (arr.length - 1);
   return Math.sqrt(variance);
 }
 function linearRegression(ys) {
@@ -647,6 +791,7 @@ function linearRegression(ys) {
 }
 var DAY_NAMES = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
 function forecast(series, days = 7) {
+  series = sanitize(series);
   if (series.length < 7) return [];
   const window = series.slice(-Math.min(14, series.length));
   const n = window.length;
@@ -690,6 +835,7 @@ function forecast(series, days = 7) {
   return results;
 }
 function detectAnomalies(series, threshold = 2) {
+  series = sanitize(series);
   if (series.length < 7) return [];
   const anomalies = [];
   const windowSize = Math.min(14, Math.floor(series.length * 0.7));
@@ -712,7 +858,11 @@ function detectAnomalies(series, threshold = 2) {
   return anomalies;
 }
 function segmentTrends(series, minSegmentLength = 5) {
+  series = sanitize(series);
   if (series.length < minSegmentLength) return [];
+  if (series.length > 1e3) {
+    series = series.slice(-1e3);
+  }
   const segments = [];
   let segStart = 0;
   while (segStart < series.length - minSegmentLength + 1) {
@@ -740,10 +890,11 @@ function segmentTrends(series, minSegmentLength = 5) {
   }
   return segments;
 }
-function detectSeasonality(series, startDaysAgo) {
+function detectSeasonality(series, startDaysAgo, referenceDate) {
+  series = sanitize(series);
   if (series.length < 14) return null;
   const buckets = [[], [], [], [], [], [], []];
-  const today = /* @__PURE__ */ new Date();
+  const today = referenceDate ?? /* @__PURE__ */ new Date();
   for (let i = 0; i < series.length; i++) {
     const date = new Date(today);
     date.setDate(date.getDate() - (startDaysAgo - i));
@@ -762,6 +913,7 @@ function detectSeasonality(series, startDaysAgo) {
   };
 }
 function computeMomentum(series) {
+  series = sanitize(series);
   if (series.length < 14) return 0;
   const last7 = series.slice(-7);
   const prev7 = series.slice(-14, -7);
@@ -914,8 +1066,7 @@ function generateActionableAdvice(packages, healthScores, opts = {}) {
     });
   }
   const highVolume = packages.filter((p) => {
-    const pkg = packages.find((pp) => pp.name === p.name);
-    return pkg && pkg.forecast7.length > 0 && pkg.forecast7[6]?.predicted > 100;
+    return p.forecast7.length > 0 && p.forecast7[6]?.predicted > 100;
   });
   for (const pkg of highVolume.slice(0, 3)) {
     const weekSum = pkg.forecast7.reduce((s, f) => s + f.predicted, 0);
@@ -1087,6 +1238,18 @@ function inferPortfolio(leaderboard, opts = {}) {
 }
 
 // src/index.ts
+var VALID_PKG_NAME = /^[@a-zA-Z0-9][\w./@-]*$/;
+function validatePackageName(pkg, registry) {
+  if (!pkg || typeof pkg !== "string") {
+    throw new RegistryError(registry, 0, `Invalid package name: must be a non-empty string`);
+  }
+  if (pkg.includes("..") || pkg.includes("\\")) {
+    throw new RegistryError(registry, 0, `Invalid package name "${pkg}": path traversal not allowed`);
+  }
+  if (!VALID_PKG_NAME.test(pkg)) {
+    throw new RegistryError(registry, 0, `Invalid package name "${pkg}": contains illegal characters`);
+  }
+}
 function createCache() {
   const store = /* @__PURE__ */ new Map();
   return {
@@ -1135,6 +1298,7 @@ function registerProvider(provider) {
 }
 var DEFAULT_TTL = 3e5;
 async function stats(registry, pkg, options) {
+  validatePackageName(pkg, registry);
   const provider = providers[registry];
   if (!provider) {
     throw new RegistryError(registry, 0, `Unknown registry "${registry}". Use registerProvider() to add custom registries.`);

package/dist/index.d.cts

@@ -76,43 +76,69 @@ interface ChartData {
     }[];
 }
 declare class RegistryError extends Error {
-    registry: RegistryName;
+    registry: RegistryName | string;
     statusCode: number;
     retryAfter?: number | undefined;
-    constructor(registry: RegistryName, statusCode: number, message: string, retryAfter?: number | undefined);
+    constructor(registry: RegistryName | string, statusCode: number, message: string, retryAfter?: number | undefined);
 }
 
+/** Download stats calculation utilities for DailyDownloads time-series data. */
 declare const calc: {
+    /** Sum all downloads in the given records. */
     total(records: DailyDownloads[]): number;
+    /** Compute average daily downloads. Returns 0 for empty input. */
     avg(records: DailyDownloads[]): number;
+    /** Group records by a custom key function. */
     group(records: DailyDownloads[], fn: (r: DailyDownloads) => string): Record<string, DailyDownloads[]>;
+    /** Group records by month (YYYY-MM keys). */
     monthly(records: DailyDownloads[]): Record<string, DailyDownloads[]>;
+    /** Group records by year (YYYY keys). */
     yearly(records: DailyDownloads[]): Record<string, DailyDownloads[]>;
+    /** Sum downloads within each group. */
     groupTotals(grouped: Record<string, DailyDownloads[]>): Record<string, number>;
+    /** Average downloads within each group. */
     groupAvgs(grouped: Record<string, DailyDownloads[]>): Record<string, number>;
+    /** Detect trend direction (up/down/flat) by comparing recent vs previous window averages. */
     trend(records: DailyDownloads[], windowDays?: number): {
         slope: number;
         direction: "up" | "down" | "flat";
         changePercent: number;
     };
+    /** Compute a simple moving average over a sliding window. */
     movingAvg(records: DailyDownloads[], windowDays?: number): DailyDownloads[];
+    /** Compute a 0-100 popularity score based on log-scaled recent daily downloads. */
     popularity(records: DailyDownloads[]): number;
+    /** Convert records to CSV string with date,downloads columns. */
     toCSV(records: DailyDownloads[]): string;
+    /** Convert records to a ChartData object suitable for chart libraries. */
     toChartData(records: DailyDownloads[], label?: string): ChartData;
 };
 
+/**
+ * Load and validate a registry-stats config file by walking up from startDir.
+ * Returns null if no config file is found.
+ * Throws a descriptive error if the config is malformed or invalid.
+ */
 declare function loadConfig(startDir?: string): Config | null;
+/** Returns sensible default config with all registries enabled. */
 declare function defaultConfig(): Config;
+/** Returns a starter config JSON string for `registry-stats init`. */
 declare function starterConfig(): string;
 
 interface ServerOptions {
     port?: number;
     cache?: boolean;
     corsOrigin?: string;
+    /** Max requests per IP per window (default: 60) */
+    rateLimitMax?: number;
+    /** Rate limit window in seconds (default: 60) */
+    rateLimitWindowSeconds?: number;
+    /** Upstream fetch timeout in ms (default: 30000) */
+    requestTimeoutMs?: number;
 }
 type Handler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
 /** Creates a request handler suitable for Node http.createServer or serverless adapters. */
-declare function createHandler(opts?: StatsOptions): Handler;
+declare function createHandler(opts?: StatsOptions & Pick<ServerOptions, 'corsOrigin' | 'rateLimitMax' | 'rateLimitWindowSeconds' | 'requestTimeoutMs'>): Handler;
 /** Starts an HTTP server. Returns the server instance. */
 declare function serve(opts?: ServerOptions): node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
 
@@ -224,30 +250,56 @@ interface PortfolioInference {
  * Forecast next N days using weighted linear regression on recent data.
  * Uses the last 14 days with exponential weighting (recent days matter more).
  * Returns predictions with 80% confidence intervals.
+ *
+ * @remarks
+ * - Requires at least 7 data points; returns empty array otherwise.
+ * - NaN/Infinity values in the input are filtered before processing.
+ * - Confidence intervals use a uniform-variance approximation for the x-spread
+ *   (see inline comment) and an approximate DoF correction for weighted RSE.
+ *   Both are adequate for windows of 7-14 points but not for long series.
  */
 declare function forecast(series: number[], days?: number): ForecastPoint[];
 /**
  * Detect anomalies using adaptive z-score with rolling baseline.
  * More sophisticated than simple global z-score — uses a 14-day rolling
  * window so seasonal patterns don't trigger false positives.
+ *
+ * @remarks
+ * - Requires at least 7 data points; returns empty array otherwise.
+ * - NaN/Infinity values are filtered before processing.
+ * - Uses sample stddev (n-1) for z-score computation.
  */
 declare function detectAnomalies(series: number[], threshold?: number): Anomaly[];
 /**
  * Segment a time series into directional trend segments.
  * Uses a simple piecewise linear approach with minimum segment length.
+ *
+ * @remarks
+ * - NaN/Infinity values are filtered before processing.
+ * - O(n^2) complexity: calls linearRegression in a nested loop. Designed for
+ *   series of up to ~365 points. Input is capped at 1000 elements as a safety guard.
  */
 declare function segmentTrends(series: number[], minSegmentLength?: number): TrendSegment[];
 /**
  * Detect day-of-week seasonality patterns.
  * Requires at least 14 days of data to identify weekly cycles.
+ *
+ * @param referenceDate - Optional fixed date for day-of-week calculation.
+ *   Defaults to `new Date()`. Inject a fixed date for deterministic testing.
+ * @remarks
+ * - NaN/Infinity values are filtered before processing.
  */
-declare function detectSeasonality(series: number[], startDaysAgo: number): {
+declare function detectSeasonality(series: number[], startDaysAgo: number, referenceDate?: Date): {
     dayOfWeek: number[];
     peakDay: string;
 } | null;
 /**
  * Compute a composite momentum score (-100 to +100).
  * Combines: short-term trend, acceleration, volume, and consistency.
+ *
+ * @remarks
+ * - Requires at least 14 data points; returns 0 otherwise.
+ * - NaN/Infinity values are filtered before processing.
  */
 declare function computeMomentum(series: number[]): number;
 /**
@@ -293,9 +345,16 @@ declare function inferPortfolio(leaderboard: Array<{
     totalWeekly?: number;
 }): PortfolioInference;
 
+/** Create an in-memory TTL cache for stats and range results. */
 declare function createCache(): StatsCache;
 
+/** Register a custom registry provider. The provider's name becomes the registry key for stats(). */
 declare function registerProvider(provider: RegistryProvider): void;
+/**
+ * Fetch download stats for a single package from one registry.
+ * Returns null if the package is not found (404).
+ * Supports caching via options.cache.
+ */
 declare function stats(registry: string, pkg: string, options?: StatsOptions): Promise<PackageStats | null>;
 declare namespace stats {
     var all: (pkg: string, options?: StatsOptions) => Promise<PackageStats[]>;