@mcptoolshop/registry-stats 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,206 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <strong>Español</strong> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a>
+</p>
+
+<p align="center">
+  <img src="assets/logo.png" alt="logo de registry-stats" width="280" />
+</p>
+
+<h1 align="center">@mcptoolshop/registry-stats</h1>
+
+<p align="center">
+  Un comando. Cinco registros. Todas tus estadísticas de descargas.
+</p>
+
+<p align="center">
+  <a href="#instalación">Instalación</a> &middot;
+  <a href="#cli">CLI</a> &middot;
+  <a href="#archivo-de-configuración">Configuración</a> &middot;
+  <a href="#api-programática">API</a> &middot;
+  <a href="#servidor-rest-api">Servidor REST</a> &middot;
+  <a href="#licencia">Licencia</a>
+</p>
+
+---
+
+Si publicas en npm, PyPI, NuGet, VS Code Marketplace o Docker Hub, actualmente necesitas cinco APIs diferentes para responder "¿cuántas descargas tuve este mes?" Esta biblioteca te ofrece una interfaz unificada — como CLI o API programática.
+
+Sin dependencias. Usa `fetch()` nativo. Node 18+.
+
+## Instalación
+
+```bash
+npm install @mcptoolshop/registry-stats
+```
+
+## CLI
+
+```bash
+# Consultar un solo registro
+registry-stats express -r npm
+
+# Consultar todos los registros a la vez
+registry-stats express
+
+# Serie temporal con desglose mensual + tendencia
+registry-stats express -r npm --range 2025-01-01:2025-06-30
+
+# Salida JSON
+registry-stats express -r npm --json
+
+# Otros registros
+registry-stats requests -r pypi
+registry-stats Newtonsoft.Json -r nuget
+registry-stats esbenp.prettier-vscode -r vscode
+registry-stats library/node -r docker
+
+# Crear archivo de configuración
+registry-stats --init
+
+# Ejecutar con configuración — obtiene todos los paquetes rastreados
+registry-stats
+
+# Comparar entre registros
+registry-stats express --compare
+
+# Exportar como CSV o JSON para gráficos
+registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
+registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart
+
+# Iniciar servidor REST API
+registry-stats serve --port 3000
+```
+
+## Archivo de Configuración
+
+Crea un `registry-stats.config.json` en la raíz de tu proyecto (o ejecuta `registry-stats --init`):
+
+```json
+{
+  "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
+  "packages": {
+    "mcpt": {
+      "npm": "mcpt",
+      "pypi": "mcpt"
+    },
+    "tool-compass": {
+      "npm": "@mcptoolshop/tool-compass",
+      "vscode": "mcp-tool-shop.tool-compass"
+    }
+  },
+  "cache": true,
+  "cacheTtlMs": 300000,
+  "concurrency": 5
+}
+```
+
+Ejecuta `registry-stats` sin argumentos para obtener estadísticas de todos los paquetes configurados. El CLI busca el archivo de configuración hacia arriba desde el directorio actual.
+
+## API Programática
+
+```typescript
+import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
+
+// Registro individual
+const npm = await stats('npm', 'express');
+const pypi = await stats('pypi', 'requests');
+
+// Todos los registros (usa Promise.allSettled — nunca lanza error)
+const all = await stats.all('express');
+
+// Masivo — múltiples paquetes, concurrencia limitada (por defecto: 5)
+const bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);
+
+// Serie temporal (solo npm + pypi)
+const daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');
+
+// Cálculos
+calc.total(daily);                         // total de descargas
+calc.avg(daily);                           // promedio diario
+calc.trend(daily);                         // { direction: 'up', changePercent: 8.3 }
+calc.movingAvg(daily, 7);                  // media móvil de 7 días
+calc.popularity(daily);                    // puntuación 0-100 escala logarítmica
+
+// Formatos de exportación
+calc.toCSV(daily);                         // cadena CSV
+calc.toChartData(daily, 'express');        // { labels: [...], datasets: [...] }
+
+// Comparación — mismo paquete entre registros
+const comparison = await stats.compare('express');
+await stats.compare('express', ['npm', 'pypi']);
+
+// Caché (TTL 5 min, en memoria)
+const cache = createCache();
+await stats('npm', 'express', { cache });
+```
+
+## Soporte de Registros
+
+| Registro | Formato de paquete | Serie temporal | Datos disponibles |
+|----------|-------------------|----------------|-------------------|
+| `npm` | `express`, `@scope/pkg` | Sí (549 días) | lastDay, lastWeek, lastMonth |
+| `pypi` | `requests` | Sí (180 días) | lastDay, lastWeek, lastMonth, total |
+| `nuget` | `Newtonsoft.Json` | No | total |
+| `vscode` | `publisher.extension` | No | total (instalaciones), rating, trends |
+| `docker` | `namespace/repo` | No | total (pulls), stars |
+
+## Fiabilidad Integrada
+
+- Reintento automático con retroceso exponencial en errores 429/5xx
+- Respeta las cabeceras `Retry-After`
+- Limitación de concurrencia para solicitudes masivas
+- Caché TTL opcional (extensible — usa Redis/archivo via interfaz `StatsCache`)
+
+## Servidor REST API
+
+Ejecuta como microservicio o intégralo en tu propio servidor:
+
+```bash
+registry-stats serve --port 3000
+```
+
+```
+GET /stats/:package              # todos los registros
+GET /stats/:registry/:package    # registro individual
+GET /compare/:package?registries=npm,pypi
+GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
+```
+
+```typescript
+import { createHandler, serve } from '@mcptoolshop/registry-stats';
+
+// Inicio rápido
+serve({ port: 3000 });
+
+// Servidor personalizado
+import { createServer } from 'node:http';
+const handler = createHandler();
+createServer(handler).listen(3000);
+```
+
+## Registros Personalizados
+
+```typescript
+import { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';
+
+const cargo: RegistryProvider = {
+  name: 'cargo',
+  async getStats(pkg) {
+    const res = await fetch(`https://crates.io/api/v1/crates/${pkg}`);
+    const json = await res.json();
+    return {
+      registry: 'cargo' as any,
+      package: pkg,
+      downloads: { total: json.crate.downloads },
+      fetchedAt: new Date().toISOString(),
+    };
+  },
+};
+
+registerProvider(cargo);
+await stats('cargo', 'serde');
+```
+
+## Licencia
+
+MIT

package/README.fr.md

@@ -0,0 +1,206 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <strong>Français</strong> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a>
+</p>
+
+<p align="center">
+  <img src="assets/logo.png" alt="logo registry-stats" width="280" />
+</p>
+
+<h1 align="center">@mcptoolshop/registry-stats</h1>
+
+<p align="center">
+  Une commande. Cinq registres. Toutes vos statistiques de téléchargement.
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> &middot;
+  <a href="#cli">CLI</a> &middot;
+  <a href="#fichier-de-configuration">Configuration</a> &middot;
+  <a href="#api-programmatique">API</a> &middot;
+  <a href="#serveur-rest-api">Serveur REST</a> &middot;
+  <a href="#licence">Licence</a>
+</p>
+
+---
+
+Si vous publiez sur npm, PyPI, NuGet, VS Code Marketplace ou Docker Hub, vous avez actuellement besoin de cinq API différentes pour répondre à « combien de téléchargements ce mois-ci ? » Cette bibliothèque offre une interface unifiée — en CLI ou API programmatique.
+
+Zéro dépendance. Utilise `fetch()` natif. Node 18+.
+
+## Installation
+
+```bash
+npm install @mcptoolshop/registry-stats
+```
+
+## CLI
+
+```bash
+# Interroger un seul registre
+registry-stats express -r npm
+
+# Interroger tous les registres
+registry-stats express
+
+# Série temporelle avec ventilation mensuelle + tendance
+registry-stats express -r npm --range 2025-01-01:2025-06-30
+
+# Sortie JSON
+registry-stats express -r npm --json
+
+# Autres registres
+registry-stats requests -r pypi
+registry-stats Newtonsoft.Json -r nuget
+registry-stats esbenp.prettier-vscode -r vscode
+registry-stats library/node -r docker
+
+# Créer un fichier de configuration
+registry-stats --init
+
+# Exécuter avec la configuration — récupère tous les paquets suivis
+registry-stats
+
+# Comparer entre registres
+registry-stats express --compare
+
+# Exporter en CSV ou JSON pour graphiques
+registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
+registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart
+
+# Démarrer un serveur REST API
+registry-stats serve --port 3000
+```
+
+## Fichier de Configuration
+
+Créez un `registry-stats.config.json` à la racine de votre projet (ou exécutez `registry-stats --init`) :
+
+```json
+{
+  "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
+  "packages": {
+    "mcpt": {
+      "npm": "mcpt",
+      "pypi": "mcpt"
+    },
+    "tool-compass": {
+      "npm": "@mcptoolshop/tool-compass",
+      "vscode": "mcp-tool-shop.tool-compass"
+    }
+  },
+  "cache": true,
+  "cacheTtlMs": 300000,
+  "concurrency": 5
+}
+```
+
+Exécutez `registry-stats` sans arguments pour obtenir les statistiques de tous les paquets configurés. Le CLI remonte les répertoires depuis le dossier courant pour trouver le fichier de configuration.
+
+## API Programmatique
+
+```typescript
+import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
+
+// Registre unique
+const npm = await stats('npm', 'express');
+const pypi = await stats('pypi', 'requests');
+
+// Tous les registres (utilise Promise.allSettled — ne lance jamais d'erreur)
+const all = await stats.all('express');
+
+// En masse — plusieurs paquets, concurrence limitée (par défaut : 5)
+const bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);
+
+// Série temporelle (npm + pypi uniquement)
+const daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');
+
+// Calculs
+calc.total(daily);                         // total des téléchargements
+calc.avg(daily);                           // moyenne journalière
+calc.trend(daily);                         // { direction: 'up', changePercent: 8.3 }
+calc.movingAvg(daily, 7);                  // moyenne mobile sur 7 jours
+calc.popularity(daily);                    // score 0-100 échelle logarithmique
+
+// Formats d'exportation
+calc.toCSV(daily);                         // chaîne CSV
+calc.toChartData(daily, 'express');        // { labels: [...], datasets: [...] }
+
+// Comparaison — même paquet entre registres
+const comparison = await stats.compare('express');
+await stats.compare('express', ['npm', 'pypi']);
+
+// Cache (TTL 5 min, en mémoire)
+const cache = createCache();
+await stats('npm', 'express', { cache });
+```
+
+## Support des Registres
+
+| Registre | Format de paquet | Série temporelle | Données disponibles |
+|----------|-----------------|-----------------|---------------------|
+| `npm` | `express`, `@scope/pkg` | Oui (549 jours) | lastDay, lastWeek, lastMonth |
+| `pypi` | `requests` | Oui (180 jours) | lastDay, lastWeek, lastMonth, total |
+| `nuget` | `Newtonsoft.Json` | Non | total |
+| `vscode` | `publisher.extension` | Non | total (installations), rating, trends |
+| `docker` | `namespace/repo` | Non | total (pulls), stars |
+
+## Fiabilité Intégrée
+
+- Réessai automatique avec recul exponentiel sur erreurs 429/5xx
+- Respecte les en-têtes `Retry-After`
+- Limitation de concurrence pour les requêtes en masse
+- Cache TTL optionnel (extensible — utilisez Redis/fichier via l'interface `StatsCache`)
+
+## Serveur REST API
+
+Exécutez comme microservice ou intégrez dans votre propre serveur :
+
+```bash
+registry-stats serve --port 3000
+```
+
+```
+GET /stats/:package              # tous les registres
+GET /stats/:registry/:package    # registre unique
+GET /compare/:package?registries=npm,pypi
+GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
+```
+
+```typescript
+import { createHandler, serve } from '@mcptoolshop/registry-stats';
+
+// Démarrage rapide
+serve({ port: 3000 });
+
+// Serveur personnalisé
+import { createServer } from 'node:http';
+const handler = createHandler();
+createServer(handler).listen(3000);
+```
+
+## Registres Personnalisés
+
+```typescript
+import { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';
+
+const cargo: RegistryProvider = {
+  name: 'cargo',
+  async getStats(pkg) {
+    const res = await fetch(`https://crates.io/api/v1/crates/${pkg}`);
+    const json = await res.json();
+    return {
+      registry: 'cargo' as any,
+      package: pkg,
+      downloads: { total: json.crate.downloads },
+      fetchedAt: new Date().toISOString(),
+    };
+  },
+};
+
+registerProvider(cargo);
+await stats('cargo', 'serde');
+```
+
+## Licence
+
+MIT

package/README.hi.md

@@ -0,0 +1,206 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <strong>हिन्दी</strong> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a>
+</p>
+
+<p align="center">
+  <img src="assets/logo.png" alt="registry-stats लोगो" width="280" />
+</p>
+
+<h1 align="center">@mcptoolshop/registry-stats</h1>
+
+<p align="center">
+  एक कमांड। पाँच रजिस्ट्री। आपके सभी डाउनलोड आँकड़े।
+</p>
+
+<p align="center">
+  <a href="#इंस्टॉल">इंस्टॉल</a> &middot;
+  <a href="#cli">CLI</a> &middot;
+  <a href="#कॉन्फ़िग-फ़ाइल">कॉन्फ़िग</a> &middot;
+  <a href="#प्रोग्रामैटिक-api">API</a> &middot;
+  <a href="#rest-api-सर्वर">REST सर्वर</a> &middot;
+  <a href="#लाइसेंस">लाइसेंस</a>
+</p>
+
+---
+
+यदि आप npm, PyPI, NuGet, VS Code Marketplace, या Docker Hub पर पैकेज प्रकाशित करते हैं, तो "इस महीने मेरे कितने डाउनलोड हुए?" का जवाब देने के लिए आपको पाँच अलग-अलग API की आवश्यकता होती है। यह लाइब्रेरी सभी के लिए एक इंटरफ़ेस प्रदान करती है — CLI या प्रोग्रामैटिक API के रूप में।
+
+शून्य निर्भरता। नेटिव `fetch()` का उपयोग। Node 18+.
+
+## इंस्टॉल
+
+```bash
+npm install @mcptoolshop/registry-stats
+```
+
+## CLI
+
+```bash
+# एकल रजिस्ट्री क्वेरी
+registry-stats express -r npm
+
+# सभी रजिस्ट्री एक साथ क्वेरी
+registry-stats express
+
+# मासिक ब्रेकडाउन + ट्रेंड के साथ टाइम सीरीज़
+registry-stats express -r npm --range 2025-01-01:2025-06-30
+
+# JSON आउटपुट
+registry-stats express -r npm --json
+
+# अन्य रजिस्ट्री
+registry-stats requests -r pypi
+registry-stats Newtonsoft.Json -r nuget
+registry-stats esbenp.prettier-vscode -r vscode
+registry-stats library/node -r docker
+
+# कॉन्फ़िग फ़ाइल बनाएँ
+registry-stats --init
+
+# कॉन्फ़िग से चलाएँ — सभी ट्रैक किए गए पैकेज प्राप्त करें
+registry-stats
+
+# रजिस्ट्री में तुलना करें
+registry-stats express --compare
+
+# CSV या चार्ट-फ्रेंडली JSON में एक्सपोर्ट
+registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
+registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart
+
+# REST API सर्वर शुरू करें
+registry-stats serve --port 3000
+```
+
+## कॉन्फ़िग फ़ाइल
+
+अपने प्रोजेक्ट रूट में `registry-stats.config.json` बनाएँ (या `registry-stats --init` चलाएँ):
+
+```json
+{
+  "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
+  "packages": {
+    "mcpt": {
+      "npm": "mcpt",
+      "pypi": "mcpt"
+    },
+    "tool-compass": {
+      "npm": "@mcptoolshop/tool-compass",
+      "vscode": "mcp-tool-shop.tool-compass"
+    }
+  },
+  "cache": true,
+  "cacheTtlMs": 300000,
+  "concurrency": 5
+}
+```
+
+बिना तर्क के `registry-stats` चलाएँ और सभी कॉन्फ़िगर किए गए पैकेजों के आँकड़े प्राप्त करें। CLI वर्तमान डायरेक्टरी से ऊपर की ओर कॉन्फ़िग फ़ाइल खोजता है।
+
+## प्रोग्रामैटिक API
+
+```typescript
+import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
+
+// एकल रजिस्ट्री
+const npm = await stats('npm', 'express');
+const pypi = await stats('pypi', 'requests');
+
+// सभी रजिस्ट्री (Promise.allSettled का उपयोग — कभी एरर नहीं फेंकता)
+const all = await stats.all('express');
+
+// बल्क — कई पैकेज, सीमित कंकरेंसी (डिफ़ॉल्ट: 5)
+const bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);
+
+// टाइम सीरीज़ (केवल npm + pypi)
+const daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');
+
+// गणनाएँ
+calc.total(daily);                         // कुल डाउनलोड
+calc.avg(daily);                           // दैनिक औसत
+calc.trend(daily);                         // { direction: 'up', changePercent: 8.3 }
+calc.movingAvg(daily, 7);                  // 7-दिन मूविंग एवरेज
+calc.popularity(daily);                    // 0-100 लॉग-स्केल स्कोर
+
+// एक्सपोर्ट फ़ॉर्मेट
+calc.toCSV(daily);                         // CSV स्ट्रिंग
+calc.toChartData(daily, 'express');        // { labels: [...], datasets: [...] }
+
+// तुलना — रजिस्ट्री में एक ही पैकेज
+const comparison = await stats.compare('express');
+await stats.compare('express', ['npm', 'pypi']);
+
+// कैश (5 मिनट TTL, इन-मेमोरी)
+const cache = createCache();
+await stats('npm', 'express', { cache });
+```
+
+## रजिस्ट्री सपोर्ट
+
+| रजिस्ट्री | पैकेज फ़ॉर्मेट | टाइम सीरीज़ | उपलब्ध डेटा |
+|-----------|---------------|------------|-------------|
+| `npm` | `express`, `@scope/pkg` | हाँ (549 दिन) | lastDay, lastWeek, lastMonth |
+| `pypi` | `requests` | हाँ (180 दिन) | lastDay, lastWeek, lastMonth, total |
+| `nuget` | `Newtonsoft.Json` | नहीं | total |
+| `vscode` | `publisher.extension` | नहीं | total (इंस्टॉल), rating, trends |
+| `docker` | `namespace/repo` | नहीं | total (पुल), stars |
+
+## अंतर्निर्मित विश्वसनीयता
+
+- 429/5xx त्रुटियों पर एक्सपोनेंशियल बैकऑफ़ के साथ स्वचालित रीट्राई
+- `Retry-After` हेडर का सम्मान
+- बल्क अनुरोधों के लिए कंकरेंसी सीमा
+- वैकल्पिक TTL कैश (प्लगेबल — `StatsCache` इंटरफ़ेस के माध्यम से Redis/फ़ाइल बैकएंड)
+
+## REST API सर्वर
+
+माइक्रोसर्विस के रूप में चलाएँ, या अपने सर्वर में एम्बेड करें:
+
+```bash
+registry-stats serve --port 3000
+```
+
+```
+GET /stats/:package              # सभी रजिस्ट्री
+GET /stats/:registry/:package    # एकल रजिस्ट्री
+GET /compare/:package?registries=npm,pypi
+GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
+```
+
+```typescript
+import { createHandler, serve } from '@mcptoolshop/registry-stats';
+
+// क्विक स्टार्ट
+serve({ port: 3000 });
+
+// कस्टम सर्वर
+import { createServer } from 'node:http';
+const handler = createHandler();
+createServer(handler).listen(3000);
+```
+
+## कस्टम रजिस्ट्री
+
+```typescript
+import { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';
+
+const cargo: RegistryProvider = {
+  name: 'cargo',
+  async getStats(pkg) {
+    const res = await fetch(`https://crates.io/api/v1/crates/${pkg}`);
+    const json = await res.json();
+    return {
+      registry: 'cargo' as any,
+      package: pkg,
+      downloads: { total: json.crate.downloads },
+      fetchedAt: new Date().toISOString(),
+    };
+  },
+};
+
+registerProvider(cargo);
+await stats('cargo', 'serde');
+```
+
+## लाइसेंस
+
+MIT