@mcptoolshop/registry-stats 0.3.0

package/README.it.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> | <a href="README.hi.md">हिन्दी</a> | <strong>Italiano</strong> | <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">
+  Un comando. Cinque registri. Tutte le tue statistiche di download.
+</p>
+
+<p align="center">
+  <a href="#installazione">Installazione</a> &middot;
+  <a href="#cli">CLI</a> &middot;
+  <a href="#file-di-configurazione">Configurazione</a> &middot;
+  <a href="#api-programmatica">API</a> &middot;
+  <a href="#server-rest-api">Server REST</a> &middot;
+  <a href="#licenza">Licenza</a>
+</p>
+
+---
+
+Se pubblichi su npm, PyPI, NuGet, VS Code Marketplace o Docker Hub, attualmente hai bisogno di cinque API diverse per rispondere a "quanti download ho avuto questo mese?" Questa libreria offre un'interfaccia unificata — come CLI o API programmatica.
+
+Zero dipendenze. Usa `fetch()` nativo. Node 18+.
+
+## Installazione
+
+```bash
+npm install @mcptoolshop/registry-stats
+```
+
+## CLI
+
+```bash
+# Interrogare un singolo registro
+registry-stats express -r npm
+
+# Interrogare tutti i registri
+registry-stats express
+
+# Serie temporale con ripartizione mensile + tendenza
+registry-stats express -r npm --range 2025-01-01:2025-06-30
+
+# Output JSON
+registry-stats express -r npm --json
+
+# Altri registri
+registry-stats requests -r pypi
+registry-stats Newtonsoft.Json -r nuget
+registry-stats esbenp.prettier-vscode -r vscode
+registry-stats library/node -r docker
+
+# Creare file di configurazione
+registry-stats --init
+
+# Eseguire con configurazione — recupera tutti i pacchetti tracciati
+registry-stats
+
+# Confrontare tra registri
+registry-stats express --compare
+
+# Esportare come CSV o JSON per grafici
+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
+
+# Avviare server REST API
+registry-stats serve --port 3000
+```
+
+## File di Configurazione
+
+Crea un `registry-stats.config.json` nella root del progetto (o esegui `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
+}
+```
+
+Esegui `registry-stats` senza argomenti per ottenere le statistiche di tutti i pacchetti configurati. Il CLI cerca il file di configurazione risalendo dalla directory corrente.
+
+## API Programmatica
+
+```typescript
+import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
+
+// Registro singolo
+const npm = await stats('npm', 'express');
+const pypi = await stats('pypi', 'requests');
+
+// Tutti i registri (usa Promise.allSettled — non lancia mai errori)
+const all = await stats.all('express');
+
+// In massa — più pacchetti, concorrenza limitata (predefinito: 5)
+const bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);
+
+// Serie temporale (solo npm + pypi)
+const daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');
+
+// Calcoli
+calc.total(daily);                         // totale download
+calc.avg(daily);                           // media giornaliera
+calc.trend(daily);                         // { direction: 'up', changePercent: 8.3 }
+calc.movingAvg(daily, 7);                  // media mobile 7 giorni
+calc.popularity(daily);                    // punteggio 0-100 scala logaritmica
+
+// Formati di esportazione
+calc.toCSV(daily);                         // stringa CSV
+calc.toChartData(daily, 'express');        // { labels: [...], datasets: [...] }
+
+// Confronto — stesso pacchetto tra registri
+const comparison = await stats.compare('express');
+await stats.compare('express', ['npm', 'pypi']);
+
+// Cache (TTL 5 min, in memoria)
+const cache = createCache();
+await stats('npm', 'express', { cache });
+```
+
+## Supporto Registri
+
+| Registro | Formato pacchetto | Serie temporale | Dati disponibili |
+|----------|------------------|-----------------|-----------------|
+| `npm` | `express`, `@scope/pkg` | Sì (549 giorni) | lastDay, lastWeek, lastMonth |
+| `pypi` | `requests` | Sì (180 giorni) | lastDay, lastWeek, lastMonth, total |
+| `nuget` | `Newtonsoft.Json` | No | total |
+| `vscode` | `publisher.extension` | No | total (installazioni), rating, trends |
+| `docker` | `namespace/repo` | No | total (pull), stars |
+
+## Affidabilità Integrata
+
+- Retry automatico con backoff esponenziale su errori 429/5xx
+- Rispetta le intestazioni `Retry-After`
+- Limitazione della concorrenza per richieste in massa
+- Cache TTL opzionale (estensibile — usa Redis/file tramite interfaccia `StatsCache`)
+
+## Server REST API
+
+Esegui come microservizio o integra nel tuo server:
+
+```bash
+registry-stats serve --port 3000
+```
+
+```
+GET /stats/:package              # tutti i registri
+GET /stats/:registry/:package    # registro singolo
+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';
+
+// Avvio rapido
+serve({ port: 3000 });
+
+// Server personalizzato
+import { createServer } from 'node:http';
+const handler = createHandler();
+createServer(handler).listen(3000);
+```
+
+## Registri Personalizzati
+
+```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');
+```
+
+## Licenza
+
+MIT

package/README.ja.md

@@ -0,0 +1,206 @@
+<p align="center">
+  <a href="README.md">English</a> | <strong>日本語</strong> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <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="registry-stats ロゴ" width="280" />
+</p>
+
+<h1 align="center">@mcptoolshop/registry-stats</h1>
+
+<p align="center">
+  1つのコマンド。5つのレジストリ。すべてのダウンロード統計。
+</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にパッケージを公開している場合、「今月のダウンロード数は？」という質問に答えるために5つの異なるAPIが必要です。このライブラリは、CLIまたはプログラマティックAPIとして、すべてを1つのインターフェースで提供します。
+
+依存関係ゼロ。ネイティブ`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はcwdから上方に設定ファイルを検索します。
+
+## プログラマティック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

package/README.md

@@ -0,0 +1,239 @@
+<p align="center">
+  <strong>English</strong> | <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> | <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="registry-stats logo" width="280" />
+</p>
+
+<h1 align="center">@mcptoolshop/registry-stats</h1>
+
+<p align="center">
+  One command. Five registries. All your download stats.
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> &middot;
+  <a href="#cli">CLI</a> &middot;
+  <a href="#config-file">Config</a> &middot;
+  <a href="#programmatic-api">API</a> &middot;
+  <a href="#rest-api-server">REST Server</a> &middot;
+  <a href="#license">License</a>
+</p>
+
+---
+
+If you publish to npm, PyPI, NuGet, VS Code Marketplace, or Docker Hub, you currently need five different APIs to answer "how many downloads did I get this month?" This library gives you one interface for all of them — as a CLI or programmatic API.
+
+Zero dependencies. Uses native `fetch()`. Node 18+.
+
+## Install
+
+```bash
+npm install @mcptoolshop/registry-stats
+```
+
+## CLI
+
+```bash
+# Query a single registry
+registry-stats express -r npm
+#  npm     | express
+#            month: 283,472,710  week: 67,367,773  day: 11,566,113
+
+# Query all registries at once
+registry-stats express
+
+# Time series with monthly breakdown + trend
+registry-stats express -r npm --range 2025-01-01:2025-06-30
+#  2025-01  142,359,021
+#  2025-02  147,522,528
+#  ...
+#  Total: 448,383,383  Avg/day: 4,982,038  Trend: flat (-0.46%)
+
+# Raw JSON output
+registry-stats express -r npm --json
+
+# Other registries
+registry-stats requests -r pypi
+registry-stats Newtonsoft.Json -r nuget
+registry-stats esbenp.prettier-vscode -r vscode
+registry-stats library/node -r docker
+
+# Create a config file
+registry-stats --init
+
+# Run with config — fetches all tracked packages
+registry-stats
+
+# Compare across registries
+registry-stats express --compare
+#  express — comparison
+#
+#  Metric        npm         pypi
+#  ─────────────────────────────────
+#  Total         -           -
+#  Month         283,472     47,201
+#  Week          67,367      11,800
+#  Day           11,566      1,686
+
+# Export as CSV or chart-friendly 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
+
+# Start a REST API server
+registry-stats serve --port 3000
+```
+
+## Config File
+
+Create a `registry-stats.config.json` in your project root (or run `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
+}
+```
+
+Run `registry-stats` with no arguments to fetch stats for all configured packages. The CLI walks up from cwd to find the nearest config file.
+
+The config is also available programmatically:
+
+```typescript
+import { loadConfig, defaultConfig, starterConfig } from '@mcptoolshop/registry-stats';
+
+const config = loadConfig();          // finds nearest config file, or null
+const defaults = defaultConfig();     // returns default Config object
+const template = starterConfig();     // returns starter JSON string
+```
+
+## Programmatic API
+
+```typescript
+import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
+
+// Single registry
+const npm = await stats('npm', 'express');
+const pypi = await stats('pypi', 'requests');
+const nuget = await stats('nuget', 'Newtonsoft.Json');
+const vscode = await stats('vscode', 'esbenp.prettier-vscode');
+const docker = await stats('docker', 'library/node');
+
+// All registries at once (uses Promise.allSettled — never throws)
+const all = await stats.all('express');
+
+// Bulk — multiple packages, concurrency-limited (default: 5)
+const bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);
+
+// Time series (npm + pypi only)
+const daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');
+
+// Calculations
+calc.total(daily);                         // sum of all downloads
+calc.avg(daily);                           // daily average
+calc.groupTotals(calc.monthly(daily));     // { '2025-01': 134982, ... }
+calc.trend(daily);                         // { direction: 'up', changePercent: 8.3 }
+calc.movingAvg(daily, 7);                  // 7-day moving average
+calc.popularity(daily);                    // 0-100 log-scale score
+
+// Export formats
+calc.toCSV(daily);                         // "date,downloads\n2025-01-01,1234\n..."
+calc.toChartData(daily, 'express');        // { labels: [...], datasets: [{ label, data }] }
+
+// Comparison — same package across registries
+const comparison = await stats.compare('express');
+// → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
+await stats.compare('express', ['npm', 'pypi']);  // specific registries only
+
+// Caching (5 min TTL, in-memory)
+const cache = createCache();
+await stats('npm', 'express', { cache });  // fetches
+await stats('npm', 'express', { cache });  // cache hit
+```
+
+## Registry Support
+
+| Registry | Package format | Time series | Data available |
+|----------|---------------|-------------|----------------|
+| `npm` | `express`, `@scope/pkg` | Yes (549 days) | lastDay, lastWeek, lastMonth |
+| `pypi` | `requests` | Yes (180 days) | lastDay, lastWeek, lastMonth, total |
+| `nuget` | `Newtonsoft.Json` | No | total |
+| `vscode` | `publisher.extension` | No | total (installs), rating, trends |
+| `docker` | `namespace/repo` | No | total (pulls), stars |
+
+## Built-in Reliability
+
+- Automatic retry with exponential backoff on 429/5xx errors
+- Respects `Retry-After` headers
+- Concurrency limiting for bulk requests
+- Optional TTL cache (pluggable — bring your own Redis/file backend via `StatsCache` interface)
+
+## REST API Server
+
+Run as a microservice or embed in your own server:
+
+```bash
+# CLI
+registry-stats serve --port 3000
+```
+
+```
+GET /stats/:package              # all registries
+GET /stats/:registry/:package    # single registry
+GET /compare/:package?registries=npm,pypi
+GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
+```
+
+Programmatic usage for custom servers or serverless:
+
+```typescript
+import { createHandler, serve } from '@mcptoolshop/registry-stats';
+
+// Option 1: Quick start
+serve({ port: 3000 });
+
+// Option 2: Bring your own server
+import { createServer } from 'node:http';
+const handler = createHandler();
+createServer(handler).listen(3000);
+```
+
+## Custom Registries
+
+```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');
+```
+
+## License
+
+MIT