pub-api-client

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

Data source:

Source	What it provides
pub.dev	Dart and Flutter package metadata, versions, scores, and search

---

Installation

npm install pub-api-client

---

Quick start

import { PubClient } from 'pub-api-client';

// Public API — no auth required
const client = new PubClient();

// Custom base URL (e.g. a self-hosted instance)
const custom = new PubClient({
  baseUrl: 'https://my-pub.example.com',
});

---

API reference

Package

// Full package info (latest + all versions)
const info = await client.package('flutter').info();
console.log(info.name);           // 'flutter'
console.log(info.latest.version); // '3.7.0'
console.log(info.versions.length); // total number of versions

// All published versions
const versions = await client.package('riverpod').versions();
console.log(versions[0].version); // '0.1.0'
console.log(versions[0].published); // '2020-10-20T...'

// Specific version metadata
const v = await client.package('riverpod').version('2.0.0');
console.log(v.version);    // '2.0.0'
console.log(v.archiveUrl); // 'https://pub.dev/packages/riverpod/versions/2.0.0.tar.gz'
console.log(v.published);  // '2022-09-14T...'

// Latest version
const latest = await client.package('riverpod').latest();
console.log(latest.version);        // e.g. '2.6.1'
console.log(latest.pubspec.name);   // 'riverpod'

Search

const results = await client.search({ query: 'state management', page: 1 });

console.log(results.packages.length); // results on this page
results.packages.forEach(pkg => {
  console.log(pkg.package); // 'riverpod', 'bloc', ...
});

// Next page
if (results.next) {
  const page2 = await client.search({ query: 'state management', page: 2 });
}

Parameter	Type	Description
query	string	Search text (optional — omit for all packages)
page	number	Page number for pagination (1-based)

Package score

const score = await client.package('flutter').score();
console.log(score.grantedPoints);  // 130
console.log(score.maxPoints);      // 140
console.log(score.likeCount);      // number of likes
console.log(score.popularityScore); // 0.0 – 1.0
console.log(score.lastUpdated);    // ISO date string

---

Cancelling requests

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

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

await client.package('flutter').info(controller.signal);
await client.package('flutter').versions(controller.signal);
await client.package('flutter').version('3.7.0', controller.signal);
await client.package('flutter').latest(controller.signal);
await client.package('flutter').score(controller.signal);
await client.search({ query: 'riverpod' }, 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:

client.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:

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

---

Error handling

Non-2xx responses throw a PubApiError:

import { PubApiError } from 'pub-api-client';

try {
  await client.package('nonexistent-package-xyz').info();
} catch (err) {
  if (err instanceof PubApiError) {
    console.log(err.status);     // 404
    console.log(err.statusText); // 'Not Found'
    console.log(err.message);    // 'Pub API error: 404 Not Found'
  }
}

---

TypeScript types

All domain types are exported:

import type {
  // Client
  PubClientOptions,
  RequestEvent,
  PubClientEvents,

  // Search
  PubSearchParams,
  PubSearchResult,
  PubSearchPackage,

  // Package
  PubPackageInfo,
  PubVersionInfo,
  PubPubspec,
  PubPackageScore,
} from 'pub-api-client';

---

License

MIT