diff --git a/README.md b/README.md
index c847e62..6bd16e9 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,8 @@
# pacote [](https://npm.im/pacote) [](https://npm.im/pacote) [](https://travis-ci.org/zkat/pacote) [](https://ci.appveyor.com/project/zkat/pacote) [](https://coveralls.io/github/zkat/pacote?branch=latest)
+
+**NOTE: this package is still under heavy development. Please don't use it yet**
+
[`pacote`](https://github.com/zkat/pacote) is a Node.js library for downloading
[npm](https://npmjs.org)-compatible packages. It supports all package specifier
syntax that `npm install` and its ilk support. It transparently caches anything
@@ -17,20 +20,41 @@ needed to reduce excess operations, using [`cacache`](https://npm.im/cacache).
* [API](#api)
* [`metadata`](#metadata)
* [`manifest`](#manifest)
- * [`tarball.unpack`](#tarball-unpack)
- * [`tarball.stream`](#tarball-stream)
+ * [`extract`](#extract)
+ * [`options`](#options)
### Example
```javascript
const pacote = require('pacote')
-// TODO
+pacote.metadata('pacote', function (err, meta) {
+ console.log(meta.versions) // ['0.0.0', '1.0.0']
+ console.log(meta['dist-tags']) // { latest: '1.0.0' }
+ console.log(meta.dist.shasum) // 'deadbeef'
+})
+
+pacote.manifest('github:zkat/pacote', function (err, pkg) {
+ console.log('package.json from github: ', pkg)
+ // { "name": "pacote", "version": "1.0.0", ... }
+})
+
+pacote.extract('http://hi.com/pkg.tgz', 'deadbeef', './-here', function (err) {
+ console.log('if `deadbeef` is present in the cache, network is skipped')
+ console.log('tarball contents extracted to ./here')
+})
```
### Features
-* gets stuff
+* simple interface to common package-related actions.
+* supports all package types.
+* fault-tolerant, fast, content-addressable cache.
+* authentication support (private git, private npm registries, etc)
+* npm-compatible for all relevant operations
+* github, gitlab, and bitbucket-aware
+* version/tag aware when fetching from git repositories.
+* caches git repositories
### Guide
@@ -38,12 +62,110 @@ const pacote = require('pacote')
### API
-#### `> pacote.get(cb)`
+#### `> pacote.metadata(spec, opts, cb)`
+
+Fetches the full metadata available for the package specified by ``.
+
+All valid metadata includes the following fields:
+
+* `name`
+* `version`
+* `_shasum`
+
+The following fields are included as long as the package specified by `spec`
+also includes them. Values will be from whichever version was specified.
+
+* `dependencies`
+* `devDependencies`
+* `optionalDependencies`
+* `peerDependencies`
+* `bundleDependencies`
+* `hasShrinkwrap`
+
+git and registry packages have two additional fields:
+
+* `versions` - all available versions for this package
+* `dist-tags` - tags/dist-tags associated with the package
##### Example
```javascript
-pacote.get(err => {
- if (err) { throw err }
-}
+pacote.metadata('pacote@1.0.0', function (err, info) {
+ // fetched from registry
+})
+
+pacote.metadata('github:zkat/pacote', function (err, info) {
+ // fetched from github
+})
+
+pacote.metadata('./path/to/tarball.tgz', function (err, info) {
+ // fetched from local tarball
+})
```
+
+#### `> pacote.manifest(spec, [opts], cb)`
+
+Fetches the *manifest* for a package, aka `package.json`. This is a more limited
+request than `metadata` and will even be read from cache if a `cache` option was
+provided and the spec type is cacheable. This will not write to the cache,
+though -- a full download is required to associate a manifest with a package.
+
+Note that depending on the spec type, some additional fields might be present.
+For example, packages from `registry.npmjs.org` have additional metadata
+appended by the registry.
+
+The `_shasum` field will always be present for already-cached packages: if you
+find this field, the package tarball will be cached and ready to extract, barring cache corruption or race conditions (so prepare to do a named extract)
+
+##### Example
+
+```javascript
+pacote.manifest('pacote@1.0.0', function (err, pkgJson) {
+ // fetched `package.json` data from the registry (or cache, if cached)
+})
+```
+
+#### `> pacote.extract(spec, destination, [opts], cb)`
+
+Extracts package data identified by `` into a directory named
+``, which will be created if it does not already exist.
+
+If `opts.digest` is provided and the data it identifies is present in the cache,
+`extract` will bypass most of its operations and go straight to extracting the
+tarball.
+
+##### Example
+
+```javascript
+pacote.extract('pacote@1.0.0', './woot', {
+ digest: 'deadbeef'
+}, function (err) {
+ // Succeeds as long as `pacote@1.0.0` still exists somewhere. Network and
+ // other operations are bypassed entirely if `digest` is present in the cache.
+})
+```
+
+#### `> options`
+
+##### `opts.digest`
+
+If provided, pacote will confirm that the relevant `shasum` for each operation's
+results matches the given digest. The call will return `EBADCHECKSUM` if the
+check fails.
+
+Additionally, `pacote.extract` will check the cache before performing any other
+operations.
+
+##### `opts.cache`
+##### `opts.cacheUid`/`opts.cacheGid`
+##### `opts.uid`/`opts.gid`
+##### `opts.scope`
+##### `opts.registry`
+##### `opts.@somescope:registry`
+##### `opts.auth`
+##### `opts.log`
+
+Default: `silentNpmLog`
+
+An [`npmlog`](https://npm.im/npmlog)-compatible logger. Will be used to log
+various events at the levels specified by `npmlog`.