npm-downloads

# Get npm Download Statistics

Retrieve download statistics for an npm package over a specified time period.

## Usage

```bash
npx tsx scripts/downloads.ts <package-name> [options]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `package-name` | Yes | The exact package name (case-sensitive) |

### Options

| Option | Description |
|--------|-------------|
| `--period=PERIOD` | Time period: last-week, last-month, last-year (default: last-month) |
| `--no-cache` | Bypass cache and fetch fresh data from API |

### Output

```
Downloads for react (last-month)
--------------------------------
Period: 2023-10-01 to 2023-10-31 (31 days)
Total downloads: 15,234,567
Average per day: 491,438
Peak day: 2023-10-15 (678,234 downloads)
```

## Script Execution (Preferred)

```bash
npx tsx scripts/downloads.ts <package-name> [options]
```

Options:
- `--period=PERIOD` - Time period: last-week, last-month, last-year (default: last-month)
- `--no-cache` - Bypass cache and fetch fresh data from API

Run from the npm-registry plugin directory: `~/.claude/plugins/cache/npm-registry/`

## Downloads API

```
GET https://api.npmjs.org/downloads/range/{period}:{package}
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `period` | Yes | Time period: `last-week`, `last-month`, `last-year`, or date range (`YYYY-MM-DD:YYYY-MM-DD`) |
| `package` | Yes | The exact package name (case-sensitive) |

### Examples

Last week:
```
https://api.npmjs.org/downloads/range/last-week:react
```

Last month:
```
https://api.npmjs.org/downloads/range/last-month:react
```

Last year:
```
https://api.npmjs.org/downloads/range/last-year:react
```

Custom date range:
```
https://api.npmjs.org/downloads/range/2023-01-01:2023-12-31:react
```

## Response Format

```json
{
  "downloads": [
    {
      "downloads": 1234567,
      "day": "2023-10-01"
    }
  ],
  "start": "2023-10-01",
  "end": "2023-10-31",
  "package