@mcptoolshop/registry-stats 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,130 @@
+import * as node_http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+type RegistryName = 'npm' | 'pypi' | 'nuget' | 'vscode' | 'docker';
+interface PackageStats {
+    registry: RegistryName;
+    package: string;
+    downloads: {
+        total?: number;
+        lastDay?: number;
+        lastWeek?: number;
+        lastMonth?: number;
+    };
+    extra?: Record<string, unknown>;
+    fetchedAt: string;
+}
+interface DailyDownloads {
+    date: string;
+    downloads: number;
+}
+interface RateLimitConfig {
+    /** Max requests per window */
+    maxRequests: number;
+    /** Window duration in seconds */
+    windowSeconds: number;
+    /** Whether auth raises the limit */
+    authRaisesLimit: boolean;
+}
+interface RegistryProvider {
+    name: string;
+    getStats(pkg: string, options?: StatsOptions): Promise<PackageStats | null>;
+    getRange?(pkg: string, start: string, end: string): Promise<DailyDownloads[]>;
+    rateLimit?: RateLimitConfig;
+}
+interface StatsCache {
+    get(key: string): PackageStats | DailyDownloads[] | undefined;
+    set(key: string, value: PackageStats | DailyDownloads[], ttlMs: number): void;
+}
+interface StatsOptions {
+    dockerToken?: string;
+    /** Max concurrent requests for bulk operations (default: 5) */
+    concurrency?: number;
+    /** Cache instance — use createCache() for built-in TTL cache */
+    cache?: StatsCache;
+    /** Cache TTL in milliseconds (default: 300000 = 5 min) */
+    cacheTtlMs?: number;
+}
+interface PackageConfig {
+    /** Registry-specific package identifiers */
+    [registry: string]: string;
+}
+interface Config {
+    /** Default registries to query when none specified */
+    registries?: string[];
+    /** Tracked packages — key is display name, value maps registries to package IDs */
+    packages?: Record<string, PackageConfig>;
+    /** Enable caching (default: true) */
+    cache?: boolean;
+    /** Cache TTL in milliseconds (default: 300000 = 5 min) */
+    cacheTtlMs?: number;
+    /** Max concurrent requests (default: 5) */
+    concurrency?: number;
+    /** Docker Hub auth token */
+    dockerToken?: string;
+}
+interface ComparisonResult {
+    package: string;
+    registries: Record<string, PackageStats>;
+    fetchedAt: string;
+}
+interface ChartData {
+    labels: string[];
+    datasets: {
+        label: string;
+        data: number[];
+    }[];
+}
+declare class RegistryError extends Error {
+    registry: RegistryName;
+    statusCode: number;
+    retryAfter?: number | undefined;
+    constructor(registry: RegistryName, statusCode: number, message: string, retryAfter?: number | undefined);
+}
+
+declare const calc: {
+    total(records: DailyDownloads[]): number;
+    avg(records: DailyDownloads[]): number;
+    group(records: DailyDownloads[], fn: (r: DailyDownloads) => string): Record<string, DailyDownloads[]>;
+    monthly(records: DailyDownloads[]): Record<string, DailyDownloads[]>;
+    yearly(records: DailyDownloads[]): Record<string, DailyDownloads[]>;
+    groupTotals(grouped: Record<string, DailyDownloads[]>): Record<string, number>;
+    groupAvgs(grouped: Record<string, DailyDownloads[]>): Record<string, number>;
+    trend(records: DailyDownloads[], windowDays?: number): {
+        slope: number;
+        direction: "up" | "down" | "flat";
+        changePercent: number;
+    };
+    movingAvg(records: DailyDownloads[], windowDays?: number): DailyDownloads[];
+    popularity(records: DailyDownloads[]): number;
+    toCSV(records: DailyDownloads[]): string;
+    toChartData(records: DailyDownloads[], label?: string): ChartData;
+};
+
+declare function loadConfig(startDir?: string): Config | null;
+declare function defaultConfig(): Config;
+declare function starterConfig(): string;
+
+interface ServerOptions {
+    port?: number;
+    cache?: boolean;
+    corsOrigin?: string;
+}
+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;
+/** Starts an HTTP server. Returns the server instance. */
+declare function serve(opts?: ServerOptions): node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
+
+declare function createCache(): StatsCache;
+
+declare function registerProvider(provider: RegistryProvider): void;
+declare function stats(registry: string, pkg: string, options?: StatsOptions): Promise<PackageStats | null>;
+declare namespace stats {
+    var all: (pkg: string, options?: StatsOptions) => Promise<PackageStats[]>;
+    var bulk: (registry: string, packages: string[], options?: StatsOptions) => Promise<(PackageStats | null)[]>;
+    var range: (registry: string, pkg: string, start: string, end: string, options?: StatsOptions) => Promise<DailyDownloads[]>;
+    var compare: (pkg: string, registries?: string[], options?: StatsOptions) => Promise<ComparisonResult>;
+}
+
+export { type ChartData, type ComparisonResult, type Config, type DailyDownloads, type PackageConfig, type PackageStats, type RateLimitConfig, RegistryError, type RegistryName, type RegistryProvider, type ServerOptions, type StatsCache, type StatsOptions, calc, createCache, createHandler, defaultConfig, loadConfig, registerProvider, serve, starterConfig, stats };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+import * as node_http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+type RegistryName = 'npm' | 'pypi' | 'nuget' | 'vscode' | 'docker';
+interface PackageStats {
+    registry: RegistryName;
+    package: string;
+    downloads: {
+        total?: number;
+        lastDay?: number;
+        lastWeek?: number;
+        lastMonth?: number;
+    };
+    extra?: Record<string, unknown>;
+    fetchedAt: string;
+}
+interface DailyDownloads {
+    date: string;
+    downloads: number;
+}
+interface RateLimitConfig {
+    /** Max requests per window */
+    maxRequests: number;
+    /** Window duration in seconds */
+    windowSeconds: number;
+    /** Whether auth raises the limit */
+    authRaisesLimit: boolean;
+}
+interface RegistryProvider {
+    name: string;
+    getStats(pkg: string, options?: StatsOptions): Promise<PackageStats | null>;
+    getRange?(pkg: string, start: string, end: string): Promise<DailyDownloads[]>;
+    rateLimit?: RateLimitConfig;
+}
+interface StatsCache {
+    get(key: string): PackageStats | DailyDownloads[] | undefined;
+    set(key: string, value: PackageStats | DailyDownloads[], ttlMs: number): void;
+}
+interface StatsOptions {
+    dockerToken?: string;
+    /** Max concurrent requests for bulk operations (default: 5) */
+    concurrency?: number;
+    /** Cache instance — use createCache() for built-in TTL cache */
+    cache?: StatsCache;
+    /** Cache TTL in milliseconds (default: 300000 = 5 min) */
+    cacheTtlMs?: number;
+}
+interface PackageConfig {
+    /** Registry-specific package identifiers */
+    [registry: string]: string;
+}
+interface Config {
+    /** Default registries to query when none specified */
+    registries?: string[];
+    /** Tracked packages — key is display name, value maps registries to package IDs */
+    packages?: Record<string, PackageConfig>;
+    /** Enable caching (default: true) */
+    cache?: boolean;
+    /** Cache TTL in milliseconds (default: 300000 = 5 min) */
+    cacheTtlMs?: number;
+    /** Max concurrent requests (default: 5) */
+    concurrency?: number;
+    /** Docker Hub auth token */
+    dockerToken?: string;
+}
+interface ComparisonResult {
+    package: string;
+    registries: Record<string, PackageStats>;
+    fetchedAt: string;
+}
+interface ChartData {
+    labels: string[];
+    datasets: {
+        label: string;
+        data: number[];
+    }[];
+}
+declare class RegistryError extends Error {
+    registry: RegistryName;
+    statusCode: number;
+    retryAfter?: number | undefined;
+    constructor(registry: RegistryName, statusCode: number, message: string, retryAfter?: number | undefined);
+}
+
+declare const calc: {
+    total(records: DailyDownloads[]): number;
+    avg(records: DailyDownloads[]): number;
+    group(records: DailyDownloads[], fn: (r: DailyDownloads) => string): Record<string, DailyDownloads[]>;
+    monthly(records: DailyDownloads[]): Record<string, DailyDownloads[]>;
+    yearly(records: DailyDownloads[]): Record<string, DailyDownloads[]>;
+    groupTotals(grouped: Record<string, DailyDownloads[]>): Record<string, number>;
+    groupAvgs(grouped: Record<string, DailyDownloads[]>): Record<string, number>;
+    trend(records: DailyDownloads[], windowDays?: number): {
+        slope: number;
+        direction: "up" | "down" | "flat";
+        changePercent: number;
+    };
+    movingAvg(records: DailyDownloads[], windowDays?: number): DailyDownloads[];
+    popularity(records: DailyDownloads[]): number;
+    toCSV(records: DailyDownloads[]): string;
+    toChartData(records: DailyDownloads[], label?: string): ChartData;
+};
+
+declare function loadConfig(startDir?: string): Config | null;
+declare function defaultConfig(): Config;
+declare function starterConfig(): string;
+
+interface ServerOptions {
+    port?: number;
+    cache?: boolean;
+    corsOrigin?: string;
+}
+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;
+/** Starts an HTTP server. Returns the server instance. */
+declare function serve(opts?: ServerOptions): node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
+
+declare function createCache(): StatsCache;
+
+declare function registerProvider(provider: RegistryProvider): void;
+declare function stats(registry: string, pkg: string, options?: StatsOptions): Promise<PackageStats | null>;
+declare namespace stats {
+    var all: (pkg: string, options?: StatsOptions) => Promise<PackageStats[]>;
+    var bulk: (registry: string, packages: string[], options?: StatsOptions) => Promise<(PackageStats | null)[]>;
+    var range: (registry: string, pkg: string, start: string, end: string, options?: StatsOptions) => Promise<DailyDownloads[]>;
+    var compare: (pkg: string, registries?: string[], options?: StatsOptions) => Promise<ComparisonResult>;
+}
+
+export { type ChartData, type ComparisonResult, type Config, type DailyDownloads, type PackageConfig, type PackageStats, type RateLimitConfig, RegistryError, type RegistryName, type RegistryProvider, type ServerOptions, type StatsCache, type StatsOptions, calc, createCache, createHandler, defaultConfig, loadConfig, registerProvider, serve, starterConfig, stats };