maven-api-client

TypeScript client for the Maven Central Search API. Covers artifact metadata, version listings, search, and suggestions. Works in Node.js and the browser (isomorphic). Fully typed, zero runtime dependencies.

Data source:

| Source | What it provides | | --- | --- | | search.maven.org | Full-text search, artifact versions, and metadata via the Solr search API |

Installation

npm install maven-api-client

Quick start

import { MavenClient } from 'maven-api-client';

// Public API — no auth required
const maven = new MavenClient();

// Custom registry (e.g. a private Nexus/Artifactory instance)
const privateFeed = new MavenClient({
  baseUrl: 'https://my-nexus.example.com',
});

API reference

Artifact versions

// All published versions
const versions = await maven.artifact('com.fasterxml.jackson.core', 'jackson-databind').versions();
console.log(versions); // ['2.0.0', '2.1.0', ..., '2.17.0']

// Latest version (highest timestamp)
const latest = await maven.artifact('com.fasterxml.jackson.core', 'jackson-databind').latest();
console.log(latest.v);         // '2.17.0'
console.log(latest.g);         // 'com.fasterxml.jackson.core'
console.log(latest.a);         // 'jackson-databind'
console.log(latest.timestamp); // 1712000000000

// Specific version metadata
const v2 = await maven.artifact('com.fasterxml.jackson.core', 'jackson-databind').version('2.15.0');
console.log(v2.v);  // '2.15.0'
console.log(v2.p);  // 'jar'
console.log(v2.ec); // ['-sources.jar', '-javadoc.jar', '.jar', '.pom']

Search

const results = await maven.search({ query: 'jackson databind', rows: 10 });

console.log(results.response.numFound); // total matching artifacts

results.response.docs.forEach(doc => {
  console.log(doc.id);            // 'com.fasterxml.jackson.core:jackson-databind'
  console.log(doc.g);             // 'com.fasterxml.jackson.core'
  console.log(doc.a);             // 'jackson-databind'
  console.log(doc.latestVersion); // '2.17.0'
  console.log(doc.versionCount);  // 120
});

// Paginate
const page2 = await maven.search({ query: 'logging', rows: 20, start: 20 });

| Parameter | Type | Description | | --- | --- | --- | | query | string | Search text (optional — omit for all artifacts) | | rows | number | Results per page (default: 20) | | start | number | Offset for pagination (default: 0) |

Suggest

const suggestions = await maven.suggest({ query: 'jackson', rows: 5 });

suggestions.response.docs.forEach(doc => {
  console.log(doc.id); // 'com.fasterxml.jackson.core:jackson-databind'
});

| Parameter | Type | Description | | --- | --- | --- | | query | string | Prefix or keyword to match | | rows | number | Results to return |

Cancelling requests

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

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

await maven.artifact('com.example', 'my-lib').versions(controller.signal);
await maven.artifact('com.example', 'my-lib').latest(controller.signal);
await maven.artifact('com.example', 'my-lib').version('1.0.0', controller.signal);
await maven.search({ query: 'jackson' }, controller.signal);
await maven.suggest({ query: 'jackson' }, 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:

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

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

Error handling

Non-2xx responses throw a MavenApiError:

import { MavenApiError } from 'maven-api-client';

try {
  await maven.artifact('com.example', 'non-existent').versions();
} catch (err) {
  if (err instanceof MavenApiError) {
    console.log(err.status);     // 404
    console.log(err.statusText); // 'Not Found'
    console.log(err.message);    // 'Maven API error: 404 Not Found'
  }
}

TypeScript types

All domain types are exported:

import type {
  // Client
  MavenClientOptions,
  RequestEvent,
  MavenClientEvents,

  // Search & suggest
  MavenSearchParams,
  MavenSuggestParams,
  MavenSearchResult,
  MavenSearchDoc,

  // Versions
  MavenVersionsResult,
  MavenVersionDoc,
} from 'maven-api-client';

License

MIT