nuget-api-client

TypeScript client for the NuGet v3 REST API. Covers package metadata, version listings, search, and autocomplete. Works in Node.js and the browser (isomorphic). Fully typed, zero runtime dependencies.

Data sources:

| Source | What it provides | | --- | --- | | api.nuget.org | Package registration (metadata, version catalog) | | api.nuget.org flat container | Complete list of published versions | | azuresearch-usnc.nuget.org | Full-text search and autocomplete |

Installation

npm install nuget-api-client

Quick start

import { NuGetClient } from 'nuget-api-client';

// Public API — no auth required
const nuget = new NuGetClient();

// Custom feed (Azure Artifacts, GitHub Packages, etc.)
const privateFeed = new NuGetClient({
  registryUrl: 'https://pkgs.dev.azure.com/my-org/_packaging/my-feed/nuget/v3',
  apiKey: 'my-api-key',
});

API reference

Package versions

// All published versions (ordered oldest → newest)
const versions = await nuget.package('Newtonsoft.Json').versions();
console.log(versions); // ['1.0.0', '3.5.8', ..., '13.0.3']

// Latest stable listed version
const latest = await nuget.package('Newtonsoft.Json').latest();
console.log(latest.version);     // '13.0.3'
console.log(latest.authors);     // 'James Newton-King'
console.log(latest.description); // 'Json.NET is a popular...'
console.log(latest.published);   // '2023-03-08T00:00:00Z'

// Specific version metadata
const v13 = await nuget.package('Newtonsoft.Json').version('13.0.3');
console.log(v13.id);      // 'Newtonsoft.Json'
console.log(v13.version); // '13.0.3'
console.log(v13.listed);  // true
console.log(v13.dependencyGroups);

Package IDs are case-insensitive — Newtonsoft.Json, newtonsoft.json, and NEWTONSOFT.JSON all resolve to the same package.

Search

const results = await nuget.search({ query: 'json serializer', take: 10 });

console.log(results.totalHits); // total matching packages

results.data.forEach(pkg => {
  console.log(pkg.id, pkg.version, pkg.totalDownloads);
  console.log(pkg.description);
  console.log(pkg.authors);
  console.log(pkg.tags);
});

// Include prerelease versions
const preResults = await nuget.search({ query: 'Serilog', prerelease: true, take: 5 });

// Paginate
const page2 = await nuget.search({ query: 'logging', skip: 20, take: 20 });

| Parameter | Type | Description | | --- | --- | --- | | query | string | Search text (optional — omit for all packages) | | skip | number | Offset for pagination (default: 0) | | take | number | Results per page (default: 20, max: 1000) | | prerelease | boolean | Include prerelease versions (default: false) | | packageType | string | Filter by package type, e.g. 'DotnetTool' | | semVerLevel | string | SemVer compatibility level, e.g. '2.0.0' |

Autocomplete

const ac = await nuget.autocomplete({ q: 'Newtonsoft', take: 5 });

console.log(ac.totalHits); // 552
console.log(ac.data);
// ['Newtonsoft.Json', 'Newtonsoft.Json.Bson', 'Microsoft.AspNetCore.Mvc.NewtonsoftJson', ...]

| Parameter | Type | Description | | --- | --- | --- | | q | string | Prefix to match against package IDs | | skip | number | Offset for pagination | | take | number | Results to return | | prerelease | boolean | Include prerelease packages | | packageType | string | Filter by package type |

Cancelling requests

Pass an AbortSignal to any method to cancel the in-flight request:

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await nuget.package('Newtonsoft.Json').versions(controller.signal);
await nuget.package('Newtonsoft.Json').latest(controller.signal);
await nuget.package('Newtonsoft.Json').version('13.0.3', controller.signal);
await nuget.search({ query: 'json' }, controller.signal);
await nuget.autocomplete({ q: 'New' }, controller.signal);

When aborted, fetch throws a DOMException with name === 'AbortError'. The request event is still emitted with the error attached.

Request events

Subscribe to every HTTP request for logging, monitoring, or debugging:

nuget.on('request', (event) => {
  console.log(`[${event.statusCode}] ${event.method} ${event.url} (${event.durationMs}ms)`);
  if (event.error) {
    console.error('Request failed:', event.error.message);
  }
});

| Field | Type | Description | | --- | --- | --- | | url | string | Full URL requested | | method | 'GET' | HTTP method | | startedAt | Date | When the request started | | finishedAt | Date | When the request finished | | durationMs | number | Duration in milliseconds | | statusCode | number \| undefined | HTTP status code, if a response was received | | error | Error \| undefined | Present only if the request failed |

on() is chainable and supports multiple listeners:

nuget
  .on('request', logToConsole)
  .on('request', sendToDatadog);

Error handling

Non-2xx responses throw a NuGetApiError:

import { NuGetApiError } from 'nuget-api-client';

try {
  await nuget.package('NonExistentPackage').versions();
} catch (err) {
  if (err instanceof NuGetApiError) {
    console.log(err.status);     // 404
    console.log(err.statusText); // 'Not Found'
    console.log(err.message);    // 'NuGet API error: 404 Not Found'
  }
}

TypeScript types

All domain types are exported:

import type {
  // Client
  NuGetClientOptions,
  RequestEvent,
  NuGetClientEvents,

  // Package registration
  NuGetRegistrationIndex,
  NuGetRegistrationPage,
  NuGetRegistrationLeaf,
  NuGetCatalogEntry,
  NuGetDependencyGroup,
  NuGetDependency,

  // Flat container
  NuGetVersionsList,

  // Search
  NuGetSearchParams,
  NuGetSearchResult,
  NuGetSearchPackage,
  NuGetSearchVersion,

  // Autocomplete
  NuGetAutocompleteParams,
  NuGetAutocompleteResult,
} from 'nuget-api-client';

License

MIT