# npm Package Intelligence — Downloads, Risk & Health (AI) (`fuze/npm-package-intelligence`) Actor

Analyze any npm package: download trend, dependencies, maintenance recency, maintainers, license and an AI risk read (unmaintained, single-maintainer, heavy deps). For dependency due diligence and dev-tool research.

- **URL**: https://apify.com/fuze/npm-package-intelligence.md
- **Developed by:** [Fredrik Hansson](https://apify.com/fuze) (community)
- **Categories:** Developer tools, AI, Automation
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$100.00 / 1,000 package analyzeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## npm Package Intelligence — Downloads, Risk & Health (AI)

**Due diligence on any npm package in one call.** Hand this Actor a list of package names and it pulls the real numbers from the public npm registry — download trend, dependencies, maintenance recency, maintainers, license, deprecation — then adds an **AI risk read**: is this package unmaintained, single-maintainer, or dragging in a heavy dependency tree? Perfect before you add a dependency, during a **supply-chain audit**, or when choosing between two libraries.

You bring the package names. It hands back a scored health report.

***

### The flow

```
1. List npm packages        2. Public npm data (no key)         3. AI risk read
   ["react",            →      registry.npmjs.org +         →      maintenance signal ·
    "express",                 api.npmjs.org/downloads             popularity · risk flags ·
    "left-pad"]                (metadata + downloads + trend)      alternatives · summary
```

1. **List the packages** you want to check — scoped names like `@scope/name` are supported.
2. **Public npm data is fetched** for each one: latest version, license, maintainers, dependencies, last publish, and weekly/monthly/last-year downloads. No API key, no auth.
3. **The AI layer reads the signals** and returns a maintenance signal, popularity tier, concrete risk flags, a download trend, confident alternatives and a two-sentence summary — grounded only in the data, never invented.

***

### What you get per package

For every package name, the Actor:

1. **Reads registry metadata** from `registry.npmjs.org`: `latestVersion`, `description`, `license`, `maintainers` (count + names), `repository`, `homepage`, `versionCount`, `lastPublish`, `lastPublishAgeDays`, and the latest version's `dependenciesCount` / `devDependenciesCount` and `deprecated` flag.
2. **Reads download stats** from `api.npmjs.org`: `weeklyDownloads`, `monthlyDownloads`, and a `trend` (`growing` / `flat` / `declining`) computed from the last-year daily download range.
3. **Computes derived signals**: how many days since the last publish, how many versions have shipped, how heavy the dependency tree is.

Then the **AI layer** (OpenAI `gpt-4o-mini`, a fast and low-cost model) adds:

- **`maintenanceSignal`** — `abandoned` · `stale` · `maintained` · `active`.
- **`popularityTier`** — `niche` · `growing` · `popular` · `ubiquitous`.
- **`riskFlags`** — a list of concrete concerns, e.g. `"unmaintained (last publish >18mo)"`, `"single maintainer"`, `"deprecated"`, `"heavy dependency tree"`, `"non-permissive/unclear license"`. Empty when there are no material risks.
- **`suggestedAlternatives`** — only well-known, widely-trusted packages the model is confident about (otherwise `[]`).
- **`summary`** — two factual sentences you can drop into a review.

A package that doesn't exist comes back with `error: "package not found (404)"` so your run never breaks.

***

### Three ways people use it

- **Dependency due diligence** — before you `npm install` a new library, check its **package health**: download trend, how recently it was published, how many maintainers stand behind it, and whether it's deprecated. Catch **unmaintained packages** before they become tech debt.
- **Supply-chain risk / audit** — feed your whole `package.json` dependency list and get a **supply chain** risk sweep: single-maintainer packages, abandoned transitive-looking deps, non-permissive licenses, heavy dependency trees. Export the dataset straight into a security review.
- **Dev-tool / library selection** — comparing `axios` vs `got`, `moment` vs `dayjs`, `webpack` vs `vite`? Run them side by side and let the **npm package analysis** rank them on popularity, maintenance and **dependency risk**, with suggested alternatives for anything that scores poorly.

***

### Input

| Field | Type | Notes |
|---|---|---|
| `packages` | array | **Required.** npm package names, one per line. Scoped names like `@scope/name` supported. |
| `maxResults` | integer | Cap how many packages to analyze. Default `200`. |
| `maxConcurrency` | integer | Packages processed in parallel. Default `6`. |
| `model` | string | Override the OpenAI model. Default `gpt-4o-mini`. |

#### Minimal input example

```json
{
  "packages": ["react", "express", "left-pad"]
}
```

***

### Output example

```json
{
  "package": "left-pad",
  "latestVersion": "1.3.0",
  "description": "String left pad",
  "license": "WTFPL",
  "weeklyDownloads": 1850000,
  "monthlyDownloads": 8100000,
  "trend": "declining",
  "lastPublish": "2021-03-17T...",
  "lastPublishAgeDays": 1680,
  "versionCount": 10,
  "maintainersCount": 1,
  "maintainers": ["cameronhunter"],
  "dependenciesCount": 0,
  "devDependenciesCount": 2,
  "deprecated": false,
  "repository": "https://github.com/left-pad/left-pad",
  "homepage": "https://github.com/left-pad/left-pad",
  "maintenanceSignal": "abandoned",
  "popularityTier": "ubiquitous",
  "riskFlags": [
    "unmaintained (last publish >18mo)",
    "single maintainer",
    "declining downloads"
  ],
  "suggestedAlternatives": ["String.prototype.padStart (built-in)"],
  "summary": "left-pad is still pulled millions of times a week but hasn't been published in years and has a single maintainer. Its one job is now covered by the native String.prototype.padStart, so new projects rarely need it."
}
```

***

### Pay-per-event pricing

This Actor uses **pay-per-event** billing with a single event:

| Event | Price | Charged when |
|---|---|---|
| `package-analyzed` | $0.10 | Once per package successfully analyzed (registry + downloads + AI risk read). |

Packages that 404 (not found) are **not** charged. The Actor logs its OpenAI token usage and the estimated AI cost at the end of every run, so the event price always stays safely above the model cost.

***

### Data source

All package data comes from the **fully public npm registry and downloads API** — no key, no auth, no scraping of private resources:

- `https://registry.npmjs.org/<pkg>` — metadata (scoped names URL-encoded as `@scope%2Fname`).
- `https://api.npmjs.org/downloads/point/last-week|last-month/<pkg>` — download counts.
- `https://api.npmjs.org/downloads/range/last-year/<pkg>` — used to compute the trend.

Only the AI risk read requires a key (OpenAI).

***

### Setup

The AI layer calls the OpenAI API. Set the environment variable / secret **`OPENAI_API_KEY`** on the Actor.

***

### Use it from an AI agent (Apify MCP server)

This Actor is available through the [Apify MCP server](https://mcp.apify.com), so AI agents (Claude, ChatGPT, or anything that speaks MCP) can call it as a tool — hand it a list of `packages` and read back the health reports — with no custom integration code.

***

### Run it locally

```bash
npm install
## put your input in storage/key_value_stores/default/INPUT.json
export OPENAI_API_KEY=sk-...
apify run -p
```

***

### Related actors

- [GitHub Repo Analyzer](https://apify.com/fuze/github-repo-analyzer) — Score the health and activity of any GitHub repository.
- [B2B Tech Stack Detector](https://apify.com/fuze/b2b-tech-stack-detector) — Detect the technologies a company's website is built on.
- [GitHub Candidate Scorer](https://apify.com/fuze/github-candidate-scorer) — Turn GitHub profiles into ranked, scored engineering candidates.
- [AI Web Extractor](https://apify.com/fuze/ai-web-extractor) — Turn any URL into structured JSON with a plain-English prompt.

# Actor input Schema

## `packages` (type: `array`):

npm package names, one per line. Scoped packages like "@scope/name" are supported.

## `maxResults` (type: `integer`):

Max packages to analyze. One pay-per-event charge per package analyzed.

## `maxConcurrency` (type: `integer`):

How many packages to process in parallel.

## `model` (type: `string`):

Override the model (default gpt-4o-mini).

## Actor input object example

```json
{
  "packages": [
    "react",
    "express"
  ],
  "maxResults": 200,
  "maxConcurrency": 6
}
```

# Actor output Schema

## `packages` (type: `string`):

All analyzed package records in the default dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "packages": [
        "react",
        "express"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("fuze/npm-package-intelligence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "packages": [
        "react",
        "express",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("fuze/npm-package-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "packages": [
    "react",
    "express"
  ]
}' |
apify call fuze/npm-package-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fuze/npm-package-intelligence"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/EQ4f1r9t94OLhGBgz/builds/Z9YDbSwnSdSioWkEQ/openapi.json