deps/npm/node_modules/npm-registry-client/README.md

   1 # npm-registry-client
   2
   3 The code that npm uses to talk to the registry.
   4
   5 It handles all the caching and HTTP calls.
   6
   7 ## Usage
   8
   9 ```javascript
  10 var RegClient = require('npm-registry-client')
  11 var client = new RegClient(config)
  12
  13 client.get("npm", "latest", 1000, function (er, data, raw, res) {
  14   // error is an error if there was a problem.
  15   // data is the parsed data object
  16   // raw is the json string
  17   // res is the response from couch
  18 })
  19 ```
  20
  21 # Configuration
  22
  23 This program is designed to work with
  24 [npmconf](https://npmjs.org/package/npmconf), but you can also pass in
  25 a plain-jane object with the appropriate configs, and it'll shim it
  26 for you.  Any configuration thingie that has get/set/del methods will
  27 also be accepted.
  28
  29 * `registry` **Required** {String} URL to the registry
  30 * `cache` **Required** {String} Path to the cache folder
  31 * `always-auth` {Boolean} Auth even for GET requests.
  32 * `auth` {String} A base64-encoded `username:password`
  33 * `email` {String} User's email address
  34 * `tag` {String} The default tag to use when publishing new packages.
  35   Default = `"latest"`
  36 * `ca` {String} Cerficate signing authority certificates to trust.
  37 * `cert` {String} Client certificate (PEM encoded). Enable access
  38   to servers that require client certificates
  39 * `key` {String} Private key (PEM encoded) for client certificate 'cert'
  40 * `strict-ssl` {Boolean} Whether or not to be strict with SSL
  41   certificates.  Default = `true`
  42 * `user-agent` {String} User agent header to send.  Default =
  43   `"node/{process.version} {process.platform} {process.arch}"`
  44 * `log` {Object} The logger to use.  Defaults to `require("npmlog")` if
  45   that works, otherwise logs are disabled.
  46 * `fetch-retries` {Number} Number of times to retry on GET failures.
  47   Default=2
  48 * `fetch-retry-factor` {Number} `factor` setting for `node-retry`. Default=10
  49 * `fetch-retry-mintimeout` {Number} `minTimeout` setting for `node-retry`.
  50   Default=10000 (10 seconds)
  51 * `fetch-retry-maxtimeout` {Number} `maxTimeout` setting for `node-retry`.
  52   Default=60000 (60 seconds)
  53 * `proxy` {URL} The url to proxy requests through.
  54 * `https-proxy` {URL} The url to proxy https requests through.
  55   Defaults to be the same as `proxy` if unset.
  56 * `_auth` {String} The base64-encoded authorization header.
  57 * `username` `_password` {String} Username/password to use to generate
  58   `_auth` if not supplied.
  59 * `_token` {Object} A token for use with
  60   [couch-login](https://npmjs.org/package/couch-login)
  61
  62 # client.request(method, where, [what], [etag], [nofollow], cb)
  63
  64 * `method` {String} HTTP method
  65 * `where` {String} Path to request on the server
  66 * `what` {Stream | Buffer | String | Object} The request body.  Objects
  67   that are not Buffers or Streams are encoded as JSON.
  68 * `etag` {String} The cached ETag
  69 * `nofollow` {Boolean} Prevent following 302/301 responses
  70 * `cb` {Function}
  71   * `error` {Error | null}
  72   * `data` {Object} the parsed data object
  73   * `raw` {String} the json
  74   * `res` {Response Object} response from couch
  75
  76 Make a request to the registry.  All the other methods are wrappers
  77 around this. one.
  78
  79 # client.adduser(username, password, email, cb)
  80
  81 * `username` {String}
  82 * `password` {String}
  83 * `email` {String}
  84 * `cb` {Function}
  85
  86 Add a user account to the registry, or verify the credentials.
  87
  88 # client.deprecate(name, version, message, cb)
  89
  90 * `name` {String} The package name
  91 * `version` {String} Semver version range
  92 * `message` {String} The message to use as a deprecation warning
  93 * `cb` {Function}
  94
  95 Deprecate a version of a package in the registry.
  96
  97 # client.bugs(name, cb)
  98
  99 * `name` {String} the name of the package
 100 * `cb` {Function}
 101
 102 Get the url for bugs of a package
 103
 104 # client.get(url, [timeout], [nofollow], [staleOk], cb)
 105
 106 * `url` {String} The url path to fetch
 107 * `timeout` {Number} Number of seconds old that a cached copy must be
 108   before a new request will be made.
 109 * `nofollow` {Boolean} Do not follow 301/302 responses
 110 * `staleOk` {Boolean} If there's cached data available, then return that
 111   to the callback quickly, and update the cache the background.
 112
 113 Fetches data from the registry via a GET request, saving it in
 114 the cache folder with the ETag.
 115
 116 # client.publish(data, tarball, [readme], cb)
 117
 118 * `data` {Object} Package data
 119 * `tarball` {String | Stream} Filename or stream of the package tarball
 120 * `readme` {String} Contents of the README markdown file
 121 * `cb` {Function}
 122
 123 Publish a package to the registry.
 124
 125 Note that this does not create the tarball from a folder.  However, it
 126 can accept a gzipped tar stream or a filename to a tarball.
 127
 128 # client.star(package, starred, cb)
 129
 130 * `package` {String} Name of the package to star
 131 * `starred` {Boolean} True to star the package, false to unstar it.
 132 * `cb` {Function}
 133
 134 Star or unstar a package.
 135
 136 Note that the user does not have to be the package owner to star or
 137 unstar a package, though other writes do require that the user be the
 138 package owner.
 139
 140 # client.stars(username, cb)
 141
 142 * `username` {String} Name of user to fetch starred packages for.
 143 * `cb` {Function}
 144
 145 View your own or another user's starred packages.
 146
 147 # client.tag(project, version, tag, cb)
 148
 149 * `project` {String} Project name
 150 * `version` {String} Version to tag
 151 * `tag` {String} Tag name to apply
 152 * `cb` {Function}
 153
 154 Mark a version in the `dist-tags` hash, so that `pkg@tag`
 155 will fetch the specified version.
 156
 157 # client.unpublish(name, [ver], cb)
 158
 159 * `name` {String} package name
 160 * `ver` {String} version to unpublish. Leave blank to unpublish all
 161   versions.
 162 * `cb` {Function}
 163
 164 Remove a version of a package (or all versions) from the registry.  When
 165 the last version us unpublished, the entire document is removed from the
 166 database.
 167
 168 # client.upload(where, file, [etag], [nofollow], cb)
 169
 170 * `where` {String} URL path to upload to
 171 * `file` {String | Stream} Either the filename or a readable stream
 172 * `etag` {String} Cache ETag
 173 * `nofollow` {Boolean} Do not follow 301/302 responses
 174 * `cb` {Function}
 175
 176 Upload an attachment.  Mostly used by `client.publish()`.