1# libnpmpublish
2
3[![npm version](https://img.shields.io/npm/v/libnpmpublish.svg)](https://npm.im/libnpmpublish)
4[![license](https://img.shields.io/npm/l/libnpmpublish.svg)](https://npm.im/libnpmpublish)
5[![CI - libnpmpublish](https://github.com/npm/cli/actions/workflows/ci-libnpmpublish.yml/badge.svg)](https://github.com/npm/cli/actions/workflows/ci-libnpmpublish.yml)
6
7[`libnpmpublish`](https://github.com/npm/libnpmpublish) is a Node.js
8library for programmatically publishing and unpublishing npm packages. Give
9it a manifest as an object and a tarball as a Buffer, and it'll put them on
10the registry for you.
11
12## Table of Contents
13
14* [Example](#example)
15* [Install](#install)
16* [API](#api)
17  * [publish/unpublish opts](#opts)
18  * [`publish()`](#publish)
19  * [`unpublish()`](#unpublish)
20
21## Example
22
23```js
24const { publish, unpublish } = require('libnpmpublish')
25```
26
27## Install
28
29`$ npm install libnpmpublish`
30
31### API
32
33#### <a name="opts"></a> `opts` for `libnpmpublish` commands
34
35`libnpmpublish` uses
36[`npm-registry-fetch`](https://npm.im/npm-registry-fetch).  Most options
37are passed through directly to that library, so please refer to [its own
38`opts` documentation](http://npm.im/npm-registry-fetch#fetch-options) for
39options that can be passed in.
40
41A couple of options of note:
42
43* `opts.defaultTag` - registers the published package with the given tag,
44  defaults to `latest`.
45
46* `opts.access` - tells the registry whether this package should be
47  published as `public` or `restricted`. Only applies to scoped
48  packages.  Defaults to `public`.
49
50* `opts.token` - can be passed in and will be used as the authentication
51  token for the registry. For other ways to pass in auth details, see the
52  n-r-f docs.
53
54* `opts.provenance` - when running in a supported CI environment, will trigger
55  the generation of a signed provenance statement to be published alongside
56  the package. Mutually exclusive with the `provenanceFile` option.
57
58* `opts.provenanceFile` - specifies the path to an externally-generated
59  provenance statement to be published alongside the package. Mutually
60  exclusive with the `provenance` option. The specified file should be a
61  [Sigstore Bundle](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto)
62  containing a [DSSE](https://github.com/secure-systems-lab/dsse)-packaged
63  provenance statement.
64
65#### <a name="publish"></a> `> libpub.publish(manifest, tarData, [opts]) -> Promise`
66
67Sends the package represented by the `manifest` and `tarData` to the
68configured registry.
69
70`manifest` should be the parsed `package.json` for the package being
71published (which can also be the manifest pulled from a packument, a git
72repo, tarball, etc.)
73
74`tarData` is a `Buffer` of the tarball being published.
75
76If `opts.npmVersion` is passed in, it will be used as the `_npmVersion`
77field in the outgoing packument.  You may put your own user-agent string in
78there to identify your publishes.
79
80If `opts.algorithms` is passed in, it should be an array of hashing
81algorithms to generate `integrity` hashes for. The default is `['sha512']`,
82which means you end up with `dist.integrity = 'sha512-deadbeefbadc0ffee'`.
83Any algorithm supported by your current node version is allowed -- npm
84clients that do not support those algorithms will simply ignore the
85unsupported hashes.
86
87##### Example
88
89```js
90// note that pacote.manifest() and pacote.tarball() can also take
91// any spec that npm can install.  a folder shown here, since that's
92// far and away the most common use case.
93const path = '/a/path/to/your/source/code'
94const pacote = require('pacote') // see: http://npm.im/pacote
95const manifest = await pacote.manifest(path)
96const tarData = await pacote.tarball(path)
97await libpub.publish(manifest, tarData, {
98  npmVersion: 'my-pub-script@1.0.2',
99  token: 'my-auth-token-here'
100}, opts)
101// Package has been published to the npm registry.
102```
103
104#### <a name="unpublish"></a> `> libpub.unpublish(spec, [opts]) -> Promise`
105
106Unpublishes `spec` from the appropriate registry. The registry in question may
107have its own limitations on unpublishing.
108
109`spec` should be either a string, or a valid
110[`npm-package-arg`](https://npm.im/npm-package-arg) parsed spec object. For
111legacy compatibility reasons, only `tag` and `version` specs will work as
112expected. `range` specs will fail silently in most cases.
113
114##### Example
115
116```js
117await libpub.unpublish('lodash', { token: 'i-am-the-worst'})
118//
119// `lodash` has now been unpublished, along with all its versions
120```
121