# npm Package Release Monitor - Versions & Dependency Changes (`maydit/npm-package-release-monitor`) Actor

Watch npm releases, dependencies, engine requirements and declared metadata. Optional saved comparisons and changes-only output. Public registry; no API key or package installation.

- **URL**: https://apify.com/maydit/npm-package-release-monitor.md
- **Developed by:** [Brandt May](https://apify.com/maydit) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 package observations

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

![Know what changed in a package — illustrative workflow](https://api.apify.com/v2/key-value-stores/YGxD9JRpduom8Q5Zd/records/npm-package-release-monitor-25bd8c0d8bb5.png?signature=6I34YzXdrWWOn4vYVqay)

### Know what changed in a package

For maintainers following dependencies: collect the public npm metadata behind a selected release tag, including version, declared dependencies and engine requirements. The Actor does not install packages, download tarballs or execute package scripts.

[Open this Actor in Console](https://console.apify.com/actors/gZubzpyNyVRoN71Th/input) · [First run](#try-this-actor) · [Results](#result-preview) · [Cost](#usage-and-pricing) · [Full guide](#full-guide)

### Try this Actor

- **First run:** Use **Latest release watchlist** below: apify, cheerio and lodash, with three saved observations. Inspect the selected tag and version before turning on changes-only output.
- **Read the results:** Open the default Dataset for package observations and **SUMMARY** for registry coverage. Saved comparisons identify new packages or changed metadata within your watchlist.
- **Keep in mind:** Dependency ranges and licenses are registry declarations, not resolved dependency trees or verified legal conclusions. Version monitoring is not a package safety or malware assessment.

**Check Apify, Cheerio and Lodash Releases** — copy this input into the JSON editor in Console.

```json
{"packages":["apify","cheerio","lodash"],"maxResults":3}
```

### Result preview

The dataset view highlights these columns:

- **Package** · `packageName`
- **Release tag** · `distTag`
- **Version** · `version`
- **Published** · `publishedAt`
- **Declared license** · `license`
- **Comparison** · `comparisonStatus`

Use the original source links and the field definitions below when interpreting the results. CSV works well for flat columns; JSON preserves nested values.

### Usage and pricing

Base result rate on the FREE tier: **$2 per 1,000 package observations**. The [Pricing tab](https://apify.com/maydit/npm-package-release-monitor/pricing) shows your plan's result rate and any Actor Start charge. Set a small result limit for the first run; the requested limit is not a guarantee of that many results.

***

### Full guide

Read a watchlist of public npm packages and compare their selected release metadata over time. This Actor helps engineering teams and agencies feed release and dependency changes into scheduled workflows. It uses the documented public registry, requires no API key, and never downloads tarballs or executes package scripts.

#### Quick start

Run with `{}` for **apify, cheerio and lodash**. The default follows each package's `latest` distribution tag. Supply exact package names, including scoped names such as `@apify/log`; arbitrary URLs and private registries are unsupported.

Each saved row contains `packageName`, `distTag`, `version`, exact source `publishedAt`, dependency maps, engine requirements, lifecycle script declarations, public maintainer usernames, source links and `observedAt`. Source-provided description, declared license, deprecation text, integrity/shasum and unpacked size/file count are included when present. Empty maps mean no declarations were supplied. Maintainer emails and other contact fields are omitted.

#### Saved comparisons

Set `comparePrevious: true` and a `snapshotName`. The first observation has `comparisonStatus: "new"`; later observations are `changed` or `unchanged`. Without comparison the status is `not_requested`. `changedFields`, `previous` and `previousObservedAt` retain the comparison evidence. `onlyChanges: true` implies comparison and omits unchanged results; its first run still saves initial observations.

Watched fields are version, release publication time, description, declared license, deprecation text, dependencies/optional dependencies/peer dependencies, engines, lifecycle scripts, maintainer usernames, integrity, shasum and source file-size/count metadata. `registryModifiedAt` is provenance only: an update to another version or tag does not alone trigger a change. The selected tag can move backward; the Actor reports the observed version without declaring an upgrade or security event.

History is isolated by package and tag within the named store. Only confirmed saved rows advance history. Failed requests, rejected spending-limit rows and unchanged rows suppressed by `onlyChanges` preserve previous observations. A reread detects known overlapping writes, but key-value storage has no atomic compare-and-swap: **run the same snapshot namespace sequentially**. Time expiry or a concurrent history change can leave a saved row without a history update; inspect SUMMARY before assuming the next run will suppress it. A malformed stored snapshot is preserved and reported as a failed source. No package disappearance or version removal is inferred.

#### Inputs and limits

| Input | Default | Meaning |
|---|---|---|
| `packages` | Empty, using three demo packages | Up to 100 exact public names |
| `distTag` | `latest` | A registry tag such as `latest`, `next` or `beta` |
| `maxResults` | 25 | 1–100 confirmed saved observations |
| `comparePrevious` / `onlyChanges` | false | Optional persistent comparison |
| `snapshotName` | `default` | 1–40 letters, digits, underscores or hyphens |
| `maxRunSeconds` | 240 | 30–3600 seconds, also bounded by the platform deadline |

Sources are processed sequentially. The result limit selects a bounded watchlist sample and does not imply all requested packages were checked. Each full registry document is limited to 8 MiB; extremely large package histories may be rejected. HTTP 429/5xx retries honor Retry-After within the remaining deadline. Robots rules, public-address checks, TLS and response/decompression limits apply. Redirects on the fixed registry endpoint are rejected. No proxies are required.

SUMMARY reports real `rowsSaved`, `rowsObserved`, `unchangedSkipped`, `historyUpdated`, source coverage, failed sources and stop flags. All-source failures and zero-output deadline failures fail the run. A clean unchanged repeat succeeds with zero results. A selected result cap is reported separately from operational incomplete coverage.

#### Three exact examples

##### Latest release watchlist

Use the [copyable first-run input](#try-this-actor) above.

##### Scoped packages

```json
{"packages":["@apify/log","@crawlee/core"],"maxResults":2}
```

##### Persistent release comparison

```json
{"packages":["apify","cheerio"],"maxResults":2,"comparePrevious":true,"snapshotName":"example-npm-release-watch"}
```

Repeat the last input with `onlyChanges: true` to emit only changed or new observations. Use a separate snapshotName for production workflows.

#### Scope and pricing

This is a **declared metadata monitor**. Dependency ranges are not resolved, tarball content and signatures are not verified, scripts are not run, and licenses are not legally interpreted. Maintainer lists are source declarations, not proof of authorization. This Actor does not detect malware or certify package safety. Use the official registry and your normal dependency-review tools to investigate changes.

Pricing is $0.002 per saved package observation ($2 per 1,000), plus the listed Actor-start event. Unchanged rows are charged when saved; `onlyChanges` can suppress them. Failed sources and SUMMARY are not result rows.

Source documentation: [npm Public Registry API](https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md) and [package metadata format](https://github.com/npm/registry/blob/main/docs/responses/package-metadata.md). Node.js 20.19+; pinned Apify SDK 3.7.2. Run `npm ci` and `npm test` for local fixture tests.

### Help with your run

Open the **Issues** tab on this Actor with the run URL, the input field that caused trouble and what you expected to receive. Remove API keys and private information before posting.

[Explore more Mayd-It Actors](https://apify.com/maydit)

### Understand your run

Open **Run report** in the run’s Output tab for saved-record counts, reported source issues and limits, and suggested next steps. Use **CSV export** to take the saved results into a spreadsheet. The existing JSON results and detailed machine-readable summary remain available.

The report reflects this run’s recorded coverage. A successful run or a saved result does not establish that every possible source record was collected.

# Actor input Schema

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

Up to 100 exact names, including @scope/package. Empty uses apify, cheerio and lodash. No URLs, private registry or auth token.

## `distTag` (type: `string`):

Follow this registry tag for every package. Defaults to latest. Missing tags are reported as failed sources; versions are not guessed.

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

Stops after this many confirmed saved package observations. Unchanged rows skipped by onlyChanges do not consume this limit. Selected cap is not a full watchlist scan.

## `comparePrevious` (type: `boolean`):

Use a named history store. First observation is new; saved rows advance history. Run the same snapshotName sequentially.

## `onlyChanges` (type: `boolean`):

Implies comparePrevious. The first run saves initial observations; an unchanged repeat saves zero rows. Do not enable for a guaranteed nonempty sample.

## `snapshotName` (type: `string`):

Separate history namespaces for different workflows. 1-40 letters, digits, hyphens or underscores. Concurrent use of the same namespace is unsupported.

## `maxRunSeconds` (type: `integer`):

Own deadline, also bounded by the platform deadline minus 25 seconds. Includes source requests and history operations.

## Actor input object example

```json
{
  "packages": [
    "apify",
    "cheerio",
    "lodash"
  ],
  "distTag": "latest",
  "maxResults": 25,
  "comparePrevious": false,
  "onlyChanges": false,
  "snapshotName": "default",
  "maxRunSeconds": 240
}
```

# Actor output Schema

## `results` (type: `string`):

Real registry metadata, comparisons and provenance. Failed requests are never paid data rows.

## `runReport` (type: `string`):

Readable summary of saved records, reported source coverage, limits and next steps. Available when this run saves its SUMMARY.

## `csvExport` (type: `string`):

Download saved dataset records as a CSV file for spreadsheets and other tools.

## `summary` (type: `string`):

Actual saved rows, unchanged skips, failed packages, selected limits, time/spending stops and history commits.

# 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": [
        "apify",
        "cheerio",
        "lodash"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maydit/npm-package-release-monitor").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": [
        "apify",
        "cheerio",
        "lodash",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("maydit/npm-package-release-monitor").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": [
    "apify",
    "cheerio",
    "lodash"
  ]
}' |
apify call maydit/npm-package-release-monitor --silent --output-dataset

```

## MCP server setup

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

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/gZubzpyNyVRoN71Th/builds/yDtaEIDzDJDcA0gv9/openapi.json