Class NpmClient

Main entry point for the npm Registry API client.

Example

import { NpmClient } from 'npmjs-api-client';

const npm = new NpmClient();

// Get full package metadata
const pkg = await npm.package('react');

// Get a specific version
const v18 = await npm.package('react').version('18.2.0');

// Get the latest version
const latest = await npm.package('react').latest();

// Get dist-tags
const tags = await npm.package('react').distTags();

// Search packages
const results = await npm.search({ text: 'react hooks', size: 10 });

// Get download stats
const stats = await npm.package('react').downloads('last-week');

// Get all packages by a maintainer
const result = await npm.maintainer('sindresorhus').packages();

Index

Constructors

constructor

Methods

audit auditQuick bulkDownloads downloadRange downloads maintainer on org package search topByKeyword topByMaintenance topByPopularity topByQuality topByScope topPackages user

Constructors

constructor

new NpmClient(options?: NpmClientOptions): NpmClient
Parameters
- options: NpmClientOptions = {}
  Optional configuration for registry URL, downloads API URL, and auth token
Returns NpmClient
- Defined in src/NpmClient.ts:137

Methods

audit

audit(payload: NpmAuditPayload, signal?: AbortSignal): Promise<NpmAuditResult>
Runs a full security audit against the npm registry.

The payload mirrors the top-level structure of package-lock.json: a name, version, and a dependencies map of resolved packages with their versions, integrity hashes, and nested sub-dependencies.

Returns detailed advisory objects for every vulnerability found, along with recommended actions (update, install, or manual review).

POST /-/npm/v1/security/audits
Parameters
- payload: NpmAuditPayload
  Lock-file-shaped dependency tree to audit
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmAuditResult>
Full audit report with advisories, actions, and vulnerability counts
Example
```
const result = await npm.audit({
  name: 'my-app',
  version: '1.0.0',
  requires: { lodash: '^4.17.11' },
  dependencies: {
    lodash: { version: '4.17.11', integrity: 'sha512-...' },
  },
});

console.log(result.metadata.vulnerabilities);
// { info: 0, low: 0, moderate: 1, high: 0, critical: 0 }

Object.values(result.advisories).forEach(a => {
  console.log(`[${a.severity}] ${a.title} — ${a.module_name}@${a.vulnerable_versions}`);
  console.log(`  Fix: upgrade to ${a.patched_versions}`);
});
```
- Defined in src/NpmClient.ts:645

auditQuick

auditQuick(
payload: NpmAuditPayload,
signal?: AbortSignal,
): Promise<NpmAuditQuickResult>
Runs a quick security audit against the npm registry.

Same payload as audit but returns only vulnerability counts by severity — no advisory details or recommended actions. Faster and lighter than the full audit.

POST /-/npm/v1/security/audits/quick
Parameters
- payload: NpmAuditPayload
  Lock-file-shaped dependency tree to audit
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmAuditQuickResult>
Vulnerability counts by severity and dependency totals
Example
```
const result = await npm.auditQuick({
  name: 'my-app',
  version: '1.0.0',
  requires: { lodash: '^4.17.11' },
  dependencies: {
    lodash: { version: '4.17.11', integrity: 'sha512-...' },
  },
});

const { high, critical } = result.metadata.vulnerabilities;
if (high + critical > 0) {
  console.error(`Found ${high} high and ${critical} critical vulnerabilities`);
}
```
- Defined in src/NpmClient.ts:678

bulkDownloads

bulkDownloads(
    packages: string[],
    period?: NpmDownloadPeriod,
    signal?: AbortSignal,
): Promise<NpmBulkDownloads>
Fetches the total download count for multiple packages in a single request.

GET /downloads/point/{period}/{name1},{name2},... (via api.npmjs.org)
Parameters
- packages: string[]
  Array of package names to fetch downloads for (max 128)
- period: NpmDownloadPeriod = 'last-month'
  Named period or date range (default: 'last-month')
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmBulkDownloads>
A map of package name to download point data
Example
```
const stats = await npm.bulkDownloads(['react', 'vue', 'angular']);
console.log(stats['react'].downloads); // 18591460
console.log(stats['vue'].downloads);   // 4200000
```
- Defined in src/NpmClient.ts:595

downloadRange

downloadRange(
    period: NpmDownloadPeriod,
    packageName: string,
    signal?: AbortSignal,
): Promise<NpmDownloadRange>
Fetches the per-day download breakdown for a package over a given period.

GET /downloads/range/{period}/{package} (via api.npmjs.org)

Convenience method — equivalent to npm.package(name).downloadRange(period).
Parameters
- period: NpmDownloadPeriod
  Named period or date range
- packageName: string
  The package name
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmDownloadRange>
Download range data with a per-day array
Example
```
const range = await npm.downloadRange('last-month', 'react');
range.downloads.forEach(d => console.log(d.day, d.downloads));
```
- Defined in src/NpmClient.ts:565

downloads

downloads(
    period: NpmDownloadPeriod,
    packageName: string,
    signal?: AbortSignal,
): Promise<NpmDownloadPoint>
Fetches the total download count for a package over a given period.

GET /downloads/point/{period}/{package} (via api.npmjs.org)

Convenience method — equivalent to npm.package(name).downloads(period).
Parameters
- period: NpmDownloadPeriod
  Named period or date range
- packageName: string
  The package name
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmDownloadPoint>
Download point data including total count and date range
Example
```
const stats = await npm.downloads('last-week', 'react');
console.log(stats.downloads);
```
- Defined in src/NpmClient.ts:534

maintainer

maintainer(username: string): MaintainerResource
Returns a MaintainerResource for a given npm username, providing access to all packages they maintain.

GET /-/v1/search?text=maintainer:{username}
Parameters
- username: string
  The npm username (e.g. 'sindresorhus', 'pilmee')
Returns MaintainerResource
A maintainer resource with a packages() method
Example
```
const result = await npm.maintainer('sindresorhus').packages();
console.log(`${result.total} packages`);
result.objects.forEach(o => console.log(o.package.name, o.package.version));

// Paginate
const page2 = await npm.maintainer('sindresorhus').packages({ size: 25, from: 25 });
```
- Defined in src/NpmClient.ts:460

on

on<K extends "request">(event: K, callback: NpmClientEvents[K]): this
Subscribes to a client event.
Type Parameters
- K extends "request"
Parameters
- event: K
- callback: NpmClientEvents[K]
Returns this
Example
```
npm.on('request', (event) => {
  console.log(`${event.method} ${event.url} — ${event.durationMs}ms`);
  if (event.error) console.error('Request failed:', event.error);
});
```
- Defined in src/NpmClient.ts:176

org

org(org: string): OrgResource
Returns an OrgResource for a given npm organization, providing authenticated access to org packages, teams, and members.

These endpoints require a registry auth token with org access.
Parameters
- org: string
  The npm org name, with or without the leading @
Returns OrgResource
An org resource with packages(), teams(), members(), and teamMembers() methods
Example
```
const npm = new NpmClient({ token: 'npm_...' });
const packages = await npm.org('npmcli').packages();
const teams = await npm.org('npmcli').teams();
```
- Defined in src/NpmClient.ts:508

package

package(name: string): PackageResource
Returns a PackageResource for a given package name, providing access to package metadata, versions, dist-tags, and download statistics.

The returned resource can be awaited directly to fetch the full packument, or chained to access nested resources.
Parameters
- name: string
  The package name (e.g. 'react', '@types/node')
Returns PackageResource
A chainable package resource
Example
```
const pkg  = await npm.package('react');
const v18  = await npm.package('react').version('18.2.0');
const tags = await npm.package('react').distTags();
```
- Defined in src/NpmClient.ts:305

search

search(params: NpmSearchParams, signal?: AbortSignal): Promise<NpmSearchResult>
Searches for packages on the npm registry.

GET /-/v1/search
Parameters
- params: NpmSearchParams
  Search parameters (required: text)
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmSearchResult>
Search results including packages, scores, and total count
Example
```
const results = await npm.search({ text: 'react state management', size: 5 });
results.objects.forEach(o => console.log(o.package.name, o.package.version));
```
- Defined in src/NpmClient.ts:328

topByKeyword

topByKeyword(
    keyword: string,
    n?: number,
    signal?: AbortSignal,
): Promise<NpmSearchResult>
Returns top packages for a keyword.

GET /-/v1/search?text=keywords:{keyword}&size={n}
Parameters
- keyword: string
  Keyword to filter by
- n: number = 20
  Number of packages to return (default: 20, max: 250)
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmSearchResult>
Search results including packages, scores, and total count
- Defined in src/NpmClient.ts:422

topByMaintenance

topByMaintenance(n?: number, signal?: AbortSignal): Promise<NpmSearchResult>
Returns top packages ranked by maintenance.

GET /-/v1/search?text=keywords:javascript&size={n}&maintenance=1&quality=0&popularity=0
Parameters
- n: number = 20
  Number of packages to return (default: 20, max: 250)
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmSearchResult>
Search results including packages, scores, and total count
- Defined in src/NpmClient.ts:405

topByPopularity

topByPopularity(n?: number, signal?: AbortSignal): Promise<NpmSearchResult>
Returns top packages ranked by popularity.

GET /-/v1/search?text=keywords:javascript&size={n}&popularity=1&quality=0&maintenance=0
Parameters
- n: number = 20
  Number of packages to return (default: 20, max: 250)
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmSearchResult>
Search results including packages, scores, and total count
- Defined in src/NpmClient.ts:373

topByQuality

topByQuality(n?: number, signal?: AbortSignal): Promise<NpmSearchResult>
Returns top packages ranked by quality.

GET /-/v1/search?text=keywords:javascript&size={n}&quality=1&popularity=0&maintenance=0
Parameters
- n: number = 20
  Number of packages to return (default: 20, max: 250)
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmSearchResult>
Search results including packages, scores, and total count
- Defined in src/NpmClient.ts:389

topByScope

topByScope(
    scope: string,
    n?: number,
    signal?: AbortSignal,
): Promise<NpmSearchResult>
Returns top packages for a scope.

GET /-/v1/search?text=scope:{scope}&size={n}
Parameters
- scope: string
  Scope to filter by, with or without the leading @
- n: number = 20
  Number of packages to return (default: 20, max: 250)
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmSearchResult>
Search results including packages, scores, and total count
- Defined in src/NpmClient.ts:436

topPackages

topPackages(n?: number, signal?: AbortSignal): Promise<NpmSearchResult>
Returns the top packages according to npm search's default ranking.

GET /-/v1/search?text=keywords:javascript&size={n}

The default npm ranking combines quality, popularity, and maintenance. npm requires a non-empty text query, so this helper uses a broad JavaScript keyword search.
Parameters
- n: number = 20
  Number of packages to return (default: 20, max: 250)
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmSearchResult>
Search results including packages, scores, and total count
Example
```
const top = await npm.topPackages(10);
top.objects.forEach(o => console.log(o.package.name, o.score.final));
```
- Defined in src/NpmClient.ts:360

user

user(username: string): UserResource
Returns a UserResource for a given npm username, providing authenticated access to the registry user profile and user package list.

These endpoints require a registry auth token.
Parameters
- username: string
  The npm username (e.g. 'pilmee')
Returns UserResource
A user resource with get() and packages() methods
Example
```
const npm = new NpmClient({ token: 'npm_...' });
const user = await npm.user('pilmee').get();
const packages = await npm.user('pilmee').packages();
```
- Defined in src/NpmClient.ts:484

Class NpmClient

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns NpmClient

Methods

audit

Parameters

Returns Promise<NpmAuditResult>

Example

auditQuick

Parameters

Returns Promise<NpmAuditQuickResult>

Example

bulkDownloads

Parameters

Returns Promise<NpmBulkDownloads>

Example

downloadRange

Parameters

Returns Promise<NpmDownloadRange>

Example

downloads

Parameters

Returns Promise<NpmDownloadPoint>

Example

maintainer

Parameters

Returns MaintainerResource

Example

on

Type Parameters

Parameters

Returns this

Example

org

Parameters

Returns OrgResource

Example

package

Parameters

Returns PackageResource

Example

search

Parameters

Returns Promise<NpmSearchResult>

Example

topByKeyword

Parameters

Returns Promise<NpmSearchResult>

topByMaintenance

Parameters

Returns Promise<NpmSearchResult>

topByPopularity

Parameters

Returns Promise<NpmSearchResult>

topByQuality

Parameters

Returns Promise<NpmSearchResult>

topByScope

Parameters

Returns Promise<NpmSearchResult>

topPackages

Parameters

Returns Promise<NpmSearchResult>

Example

user

Parameters

Returns UserResource

Example

Settings

On This Page