3 The code that npm uses to talk to the registry.
5 It handles all the caching and HTTP calls.
10 var RegClient = require('npm-registry-client')
11 var client = new RegClient(config)
12 var uri = "https://registry.npmjs.org/npm"
13 var params = {timeout: 1000}
15 client.get(uri, params, function (error, data, raw, res) {
16 // error is an error if there was a problem.
17 // data is the parsed data object
18 // raw is the json string
19 // res is the response from couch
25 The registry calls take either a full URL pointing to a resource in the
26 registry, or a base URL for the registry as a whole (including the registry
27 path – but be sure to terminate the path with `/`). `http` and `https` URLs are
28 the only ones supported.
32 Every call to the client follows the same pattern:
34 * `uri` {String} The *fully-qualified* URI of the registry API method being
36 * `params` {Object} Per-request parameters.
37 * `callback` {Function} Callback to be invoked when the call is complete.
41 Many requests to the registry can by authenticated, and require credentials
42 for authorization. These credentials always look the same:
47 * `alwaysAuth` {Boolean} Whether calls to the target registry are always
53 * `alwaysAuth` {Boolean} Whether calls to the target registry are always
58 ### client.access(uri, params, cb)
60 * `uri` {String} Registry URL for the package's access API endpoint.
61 Looks like `/-/package/<package name>/access`.
62 * `params` {Object} Object containing per-request properties.
63 * `access` {String} New access level for the package. Can be either
64 `public` or `restricted`. Registry will raise an error if trying
65 to change the access level of an unscoped package.
66 * `auth` {Credentials}
68 Set the access level for scoped packages. For now, there are only two
69 access levels: "public" and "restricted".
71 ### client.adduser(uri, params, cb)
73 * `uri` {String} Base registry URL.
74 * `params` {Object} Object containing per-request properties.
75 * `auth` {Credentials}
77 * `error` {Error | null}
78 * `data` {Object} the parsed data object
79 * `raw` {String} the json
80 * `res` {Response Object} response from couch
82 Add a user account to the registry, or verify the credentials.
84 ### client.deprecate(uri, params, cb)
86 * `uri` {String} Full registry URI for the deprecated package.
87 * `params` {Object} Object containing per-request properties.
88 * `version` {String} Semver version range.
89 * `message` {String} The message to use as a deprecation warning.
90 * `auth` {Credentials}
93 Deprecate a version of a package in the registry.
95 ### client.distTags.fetch(uri, params, cb)
97 * `uri` {String} Base URL for the registry.
98 * `params` {Object} Object containing per-request properties.
99 * `package` {String} Name of the package.
100 * `auth` {Credentials}
103 Fetch all of the `dist-tags` for the named package.
105 ### client.distTags.add(uri, params, cb)
107 * `uri` {String} Base URL for the registry.
108 * `params` {Object} Object containing per-request properties.
109 * `package` {String} Name of the package.
110 * `distTag` {String} Name of the new `dist-tag`.
111 * `version` {String} Exact version to be mapped to the `dist-tag`.
112 * `auth` {Credentials}
115 Add (or replace) a single dist-tag onto the named package.
117 ### client.distTags.set(uri, params, cb)
119 * `uri` {String} Base URL for the registry.
120 * `params` {Object} Object containing per-request properties.
121 * `package` {String} Name of the package.
122 * `distTags` {Object} Object containing a map from tag names to package
124 * `auth` {Credentials}
127 Set all of the `dist-tags` for the named package at once, creating any
128 `dist-tags` that do not already exit. Any `dist-tags` not included in the
129 `distTags` map will be removed.
131 ### client.distTags.update(uri, params, cb)
133 * `uri` {String} Base URL for the registry.
134 * `params` {Object} Object containing per-request properties.
135 * `package` {String} Name of the package.
136 * `distTags` {Object} Object containing a map from tag names to package
138 * `auth` {Credentials}
141 Update the values of multiple `dist-tags`, creating any `dist-tags` that do
142 not already exist. Any pre-existing `dist-tags` not included in the `distTags`
143 map will be left alone.
145 ### client.distTags.rm(uri, params, cb)
147 * `uri` {String} Base URL for the registry.
148 * `params` {Object} Object containing per-request properties.
149 * `package` {String} Name of the package.
150 * `distTag` {String} Name of the new `dist-tag`.
151 * `auth` {Credentials}
154 Remove a single `dist-tag` from the named package.
156 ### client.get(uri, params, cb)
158 * `uri` {String} The complete registry URI to fetch
159 * `params` {Object} Object containing per-request properties.
160 * `timeout` {Number} Duration before the request times out. Optional
162 * `follow` {Boolean} Follow 302/301 responses. Optional (default: true).
163 * `staleOk` {Boolean} If there's cached data available, then return that to
164 the callback quickly, and update the cache the background. Optional
166 * `auth` {Credentials} Optional.
169 Fetches data from the registry via a GET request, saving it in the cache folder
170 with the ETag or the "Last Modified" timestamp.
172 ### client.publish(uri, params, cb)
174 * `uri` {String} The registry URI for the package to publish.
175 * `params` {Object} Object containing per-request properties.
176 * `metadata` {Object} Package metadata.
177 * `access` {String} Access for the package. Can be `public` or `restricted` (no default).
178 * `body` {Stream} Stream of the package body / tarball.
179 * `auth` {Credentials}
182 Publish a package to the registry.
184 Note that this does not create the tarball from a folder.
186 ### client.star(uri, params, cb)
188 * `uri` {String} The complete registry URI for the package to star.
189 * `params` {Object} Object containing per-request properties.
190 * `starred` {Boolean} True to star the package, false to unstar it. Optional
192 * `auth` {Credentials}
195 Star or unstar a package.
197 Note that the user does not have to be the package owner to star or unstar a
198 package, though other writes do require that the user be the package owner.
200 ### client.stars(uri, params, cb)
202 * `uri` {String} The base URL for the registry.
203 * `params` {Object} Object containing per-request properties.
204 * `username` {String} Name of user to fetch starred packages for. Optional
205 (default: user in `auth`).
206 * `auth` {Credentials} Optional (required if `username` is omitted).
209 View your own or another user's starred packages.
211 ### client.tag(uri, params, cb)
213 * `uri` {String} The complete registry URI to tag
214 * `params` {Object} Object containing per-request properties.
215 * `version` {String} Version to tag.
216 * `tag` {String} Tag name to apply.
217 * `auth` {Credentials}
220 Mark a version in the `dist-tags` hash, so that `pkg@tag` will fetch the
223 ### client.unpublish(uri, params, cb)
225 * `uri` {String} The complete registry URI of the package to unpublish.
226 * `params` {Object} Object containing per-request properties.
227 * `version` {String} version to unpublish. Optional – omit to unpublish all
229 * `auth` {Credentials}
232 Remove a version of a package (or all versions) from the registry. When the
233 last version us unpublished, the entire document is removed from the database.
235 ### client.whoami(uri, params, cb)
237 * `uri` {String} The base registry for the URI.
238 * `params` {Object} Object containing per-request properties.
239 * `auth` {Credentials}
242 Simple call to see who the registry thinks you are. Especially useful with
248 The below are primarily intended for use by the rest of the API, or by the npm
249 caching logic directly.
251 ### client.request(uri, params, cb)
253 * `uri` {String} URI pointing to the resource to request.
254 * `params` {Object} Object containing per-request properties.
255 * `method` {String} HTTP method. Optional (default: "GET").
256 * `body` {Stream | Buffer | String | Object} The request body. Objects
257 that are not Buffers or Streams are encoded as JSON. Optional – body
258 only used for write operations.
259 * `etag` {String} The cached ETag. Optional.
260 * `lastModified` {String} The cached Last-Modified timestamp. Optional.
261 * `follow` {Boolean} Follow 302/301 responses. Optional (default: true).
262 * `streaming` {Boolean} Stream the request body as it comes, handling error
263 responses in a non-streaming way.
264 * `auth` {Credentials} Optional.
266 * `error` {Error | null}
267 * `data` {Object} the parsed data object
268 * `raw` {String} the json
269 * `res` {Response Object} response from couch
271 Make a generic request to the registry. All the other methods are wrappers
272 around `client.request`.
274 ### client.fetch(uri, params, cb)
276 * `uri` {String} The complete registry URI to upload to
277 * `params` {Object} Object containing per-request properties.
278 * `headers` {Stream} HTTP headers to be included with the request. Optional.
279 * `auth` {Credentials} Optional.
282 Fetch a package from a URL, with auth set appropriately if included. Used to
283 cache remote tarballs as well as request package tarballs from the registry.
287 The client uses its own configuration, which is just passed in as a simple
288 nested object. The following are the supported values (with their defaults, if
291 * `proxy.http` {URL} The URL to proxy HTTP requests through.
292 * `proxy.https` {URL} The URL to proxy HTTPS requests through. Defaults to be
293 the same as `proxy.http` if unset.
294 * `proxy.localAddress` {IP} The local address to use on multi-homed systems.
295 * `ssl.ca` {String} Certificate signing authority certificates to trust.
296 * `ssl.certificate` {String} Client certificate (PEM encoded). Enable access
297 to servers that require client certificates.
298 * `ssl.key` {String} Private key (PEM encoded) for client certificate.
299 * `ssl.strict` {Boolean} Whether or not to be strict with SSL certificates.
301 * `retry.count` {Number} Number of times to retry on GET failures. Default = 2.
302 * `retry.factor` {Number} `factor` setting for `node-retry`. Default = 10.
303 * `retry.minTimeout` {Number} `minTimeout` setting for `node-retry`.
304 Default = 10000 (10 seconds)
305 * `retry.maxTimeout` {Number} `maxTimeout` setting for `node-retry`.
306 Default = 60000 (60 seconds)
307 * `userAgent` {String} User agent header to send. Default =
308 `"node/{process.version}"`
309 * `log` {Object} The logger to use. Defaults to `require("npmlog")` if
310 that works, otherwise logs are disabled.
311 * `defaultTag` {String} The default tag to use when publishing new packages.
313 * `couchToken` {Object} A token for use with
314 [couch-login](https://npmjs.org/package/couch-login).
315 * `sessionToken` {String} A random identifier for this set of client requests.
316 Default = 8 random hexadecimal bytes.
317 * `maxSockets` {Number} The maximum number of connections that will be open per
318 origin (unique combination of protocol:host:port). Passed to the
319 [httpAgent](https://nodejs.org/api/http.html#http_agent_maxsockets).