# npm Package Release Impact & Regression Intelligence (`obliging_persimmon_cki/npm-package-release-impact-regression-intelligence`) Actor

Resolve npm package releases and compare bounded GitHub issue windows for explainable regression signals.

- **URL**: https://apify.com/obliging\_persimmon\_cki/npm-package-release-impact-regression-intelligence.md
- **Developed by:** [Dung Huynh](https://apify.com/obliging_persimmon_cki) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## npm Package Release Impact & Regression Intelligence

Resolve npm package releases, map them to their public GitHub repositories, and compare bounded GitHub issue windows around the selected package boundary. The Actor emits one explainable impact record per requested package rather than a raw metadata dump or an unbounded issue scrape.

Regression signals describe temporal changes in issue reporting. They do not prove that a package release caused an individual issue.

### Input

The default input analyzes `vite` using the newest stable version whose npm publish time is at least seven days old. `packages` accepts one to five public package names. Scoped names such as `@tanstack/react-query` are supported; use `package@1.2.3` with `specific_version` for an exact version.

`comparisonMode` values are:

- `latest_eligible_version` — select the newest stable version published at least `windowDays` ago.
- `specific_version` — analyze the exact version encoded in every package entry.
- `custom_date` — use `comparisonDate` as the temporal boundary and select the newest stable version published by that date.
- `recent_vs_previous` — compare two adjacent rolling windows without requiring an eligible release.

`windowDays` is 1–30 and `maxIssuesPerPeriod` is 10–200. `includeEvidence` controls bounded representative issue references. An optional `githubToken` increases GitHub’s public API rate limit; it is never written to output or logs.

### Sources and resolution

Package metadata is fetched from the public npm registry’s full package packument so publish timestamps and version-level repository metadata are available. Stable versions are selected using publish time, then deterministic semver ordering for ties. Repository resolution prefers version-level metadata, then package-level metadata, bugs/homepage links, and preserves a monorepo `directory` when npm provides one.

Issue data comes from the public GitHub REST Issues API with `state=all`, newest-created ordering, 100 items per page, and a maximum of eight pages. GitHub may return pull requests through this endpoint; every item with `pull_request` is excluded. Issue bodies and titles are classified with deterministic software taxonomy rules. Comments, discussions, commits, diffs, source code, private repositories, security alerts, and webhooks are outside Version 1.

### Output

One Dataset item is emitted per requested package. A package-level registry, version, repository, or GitHub failure becomes a `status: "failed"` item so other packages can finish. Partial coverage is reported instead of silently presenting an incomplete comparison as complete.

### Output fields

| Field | Meaning |
| --- | --- |
| `status` | `ok`, `partial`, or `failed` package result status. |
| `package.name` | Normalized npm package name. |
| `package.selectedVersion` | Version used as the package boundary. |
| `package.previousVersion` | Previous lower stable semver version when available. |
| `package.changeType` | `major`, `minor`, `patch`, `none`, or `unknown`. |
| `package.repository.fullName` | Canonical GitHub repository. |
| `boundary.timestamp` | UTC comparison boundary timestamp. |
| `impact.direction` | Observed regression-signal direction. |
| `impact.level` | Low, medium, high, or unknown impact level. |
| `impact.issueVolume.before` | Issues analyzed before the boundary. |
| `impact.issueVolume.after` | Issues analyzed after the boundary. |
| `impact.issueVolume.absoluteDelta` | Difference in analyzed issue counts. |
| `impact.bugSignalRateDelta` | Change in bug-related signal share. |
| `impact.regressionSignalRateDelta` | Change in regression-related signal share. |
| `coverage.before.coverageStatus` | BEFORE coverage: `full`, `partial`, or `insufficient`. |
| `coverage.after.coverageStatus` | AFTER coverage: `full`, `partial`, or `insufficient`. |
| `impact.confidence.level` | Evidence-quality confidence level. |
| `summary` | Deterministic, non-causal summary. |
| `warnings` | Bounded collection and coverage warnings. |
| `error.code` | Stable error code for failed package items. |
| `fetchedAt` | Report generation timestamp. |

`sources.npm` records registry request count and response bytes. `sources.github` records API request count and rate-limit metadata. The raw npm packument and raw GitHub pages are not emitted.

### Coverage and responsible use

`full` means both requested windows were reached, each has at least eight analyzed issues, and no known truncation occurred. `partial` means usable evidence exists with an incomplete window or source limitation. `insufficient` means the sample is too small for directional analysis. Confidence is an evidence-quality score, not a probability of causation.

Use results to prioritize release follow-up, triage, and investigation. Do not treat a changed issue rate as proof of a defect, security finding, customer harm, or release causality. Validate important findings against release notes, reproduction steps, maintainers’ context, and the package’s own tests.

### Runtime and limits

The default run is intentionally bounded to five packages, eight GitHub pages per package, and 200 analyzed issues per period. Full npm packuments can be large; the Actor records byte counts and avoids retaining raw metadata in output. Unauthenticated GitHub access is subject to GitHub’s public API rate limits. A rate-limit interruption produces a partial or failed package record with a warning/error code.

### Scheduling, pricing, and publication

Scheduled runs can compare rolling windows or monitor newly eligible package versions. This release candidate does not automatically change pricing or publish external content. Store publication requires a separate release gate covering tests, schemas, local runs, Cloud smoke tests, output inspection, and secret-redaction checks; see `docs/publish-readiness-report.md`.

### FAQ

**Does this prove a release caused a regression?** No. It identifies temporal changes in public issue-reporting signals around a package boundary.

**Why is a result partial?** The period may be active, contain too few issues, hit the eight-page safety cap, or encounter a GitHub rate limit.

**Why did the Actor use a monorepo directory?** Version-level npm metadata can identify the package’s directory inside a shared GitHub repository. The directory is provenance, not a claim that every repository issue belongs only to that package.

# Actor input Schema

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

One to five public npm package names. Use package@exact.version for specific\_version mode.

## `comparisonMode` (type: `string`):

Select an eligible package version, an exact version, a custom date, or recent versus previous rolling windows.

## `comparisonDate` (type: `string`):

Required for custom\_date mode; ISO date or datetime in the past.

## `windowDays` (type: `integer`):

Length of each before and after issue period.

## `maxIssuesPerPeriod` (type: `integer`):

Deterministic sample cap for each comparison period.

## `includeEvidence` (type: `boolean`):

Include bounded GitHub issue references supporting changed themes.

## `githubToken` (type: `string`):

Optional token for higher public GitHub API rate limits. Never written to output or logs.

## Actor input object example

```json
{
  "packages": [
    "vite"
  ],
  "comparisonMode": "latest_eligible_version",
  "comparisonDate": "",
  "windowDays": 7,
  "maxIssuesPerPeriod": 50,
  "includeEvidence": true
}
```

# Actor output Schema

## `dataset` (type: `string`):

One normalized report per requested npm package.

## `runStatistics` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("obliging_persimmon_cki/npm-package-release-impact-regression-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("obliging_persimmon_cki/npm-package-release-impact-regression-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 '{}' |
apify call obliging_persimmon_cki/npm-package-release-impact-regression-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,obliging_persimmon_cki/npm-package-release-impact-regression-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/JPfkcM9pYYYmNrtjb/builds/WWVfAIjNxOhFxlIAO/openapi.json