search

npm / npm-registry-client

http://npm.im/npm-registry-client
ISC License
264 stars 108 forks source link

readme

npm-registry-client

The code that npm uses to talk to the registry.

It handles all the caching and HTTP calls.

Usage

var RegClient = require('npm-registry-client')
var client = new RegClient(config)
var uri = "https://registry.npmjs.org/npm"
var params = {timeout: 1000}

client.get(uri, params, function (error, data, raw, res) {
  // error is an error if there was a problem.
  // data is the parsed data object
  // raw is the json string
  // res is the response from couch
})

Registry URLs

The registry calls take either a full URL pointing to a resource in the registry, or a base URL for the registry as a whole (including the registry path – but be sure to terminate the path with /). http and https URLs are the only ones supported.

Using the client

Every call to the client follows the same pattern:

Credentials

Many requests to the registry can be authenticated, and require credentials for authorization. These credentials always look the same:

or

Requests

As of npm-registry-client@8, all requests are made with an Accept header of application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*.

This enables filtered document responses to requests for package metadata. You know that you got a filtered response if the mime type is set to application/vnd.npm.install-v1+json and not application/json.

This filtering substantially reduces the over all data size. For example for https://registry.npmjs.org/npm, the compressed metadata goes from 410kB to 21kB.

API

client.access(uri, params, cb)

Set the access level for scoped packages. For now, there are only two access levels: "public" and "restricted".

client.adduser(uri, params, cb)

Add a user account to the registry, or verify the credentials.

client.deprecate(uri, params, cb)

Deprecate a version of a package in the registry.

client.distTags.fetch(uri, params, cb)

Fetch all of the dist-tags for the named package.

client.distTags.add(uri, params, cb)

Add (or replace) a single dist-tag onto the named package.

client.distTags.set(uri, params, cb)

Set all of the dist-tags for the named package at once, creating any dist-tags that do not already exist. Any dist-tags not included in the distTags map will be removed.

client.distTags.update(uri, params, cb)

Update the values of multiple dist-tags, creating any dist-tags that do not already exist. Any pre-existing dist-tags not included in the distTags map will be left alone.

client.distTags.rm(uri, params, cb)

Remove a single dist-tag from the named package.

client.get(uri, params, cb)

Fetches data from the registry via a GET request, saving it in the cache folder with the ETag or the "Last Modified" timestamp.

client.publish(uri, params, cb)

Publish a package to the registry.

Note that this does not create the tarball from a folder.

client.sendAnonymousCLIMetrics(uri, params, cb)

PUT a metrics object to the /-/npm/anon-metrics/v1/ endpoint on the registry.

client.star(uri, params, cb)

Star or unstar a package.

Note that the user does not have to be the package owner to star or unstar a package, though other writes do require that the user be the package owner.

client.stars(uri, params, cb)

View your own or another user's starred packages.

client.tag(uri, params, cb)

Mark a version in the dist-tags hash, so that pkg@tag will fetch the specified version.

client.unpublish(uri, params, cb)

Remove a version of a package (or all versions) from the registry. When the last version us unpublished, the entire document is removed from the database.

client.whoami(uri, params, cb)

Simple call to see who the registry thinks you are. Especially useful with token-based auth.

PLUMBING

The below are primarily intended for use by the rest of the API, or by the npm caching logic directly.

client.request(uri, params, cb)

Make a generic request to the registry. All the other methods are wrappers around client.request.

client.fetch(uri, params, cb)

Fetch a package from a URL, with auth set appropriately if included. Used to cache remote tarballs as well as request package tarballs from the registry.

Configuration

The client uses its own configuration, which is just passed in as a simple nested object. The following are the supported values (with their defaults, if any):