• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# libnpmteam
2
3[![npm version](https://img.shields.io/npm/v/libnpmteam.svg)](https://npm.im/libnpmteam)
4[![license](https://img.shields.io/npm/l/libnpmteam.svg)](https://npm.im/libnpmteam)
5[![CI - libnpmteam](https://github.com/npm/cli/actions/workflows/ci-libnpmteam.yml/badge.svg)](https://github.com/npm/cli/actions/workflows/ci-libnpmteam.yml)
6
7[`libnpmteam`](https://github.com/npm/libnpmteam) is a Node.js
8library that provides programmatic access to the guts of the npm CLI's `npm
9team` command and its various subcommands.
10
11## Example
12
13```javascript
14const team = require('libnpmteam')
15
16// List all teams for the @npm org.
17console.log(await team.lsTeams('npm'))
18```
19
20## Publishing
211. Manually create CHANGELOG.md file
221. Commit changes to CHANGELOG.md
23    ```bash
24    $ git commit -m "chore: updated CHANGELOG.md"
25    ```
261. Run `npm version {newVersion}`
27    ```bash
28    # Example
29    $ npm version patch
30    # 1. Runs `coverage` and `lint` scripts
31    # 2. Bumps package version; and **create commit/tag**
32    # 3. Runs `npm publish`; publishing directory with **unpushed commit**
33    # 4. Runs `git push origin --follow-tags`
34    ```
35
36## Table of Contents
37
38* [Installing](#install)
39* [Example](#example)
40* [API](#api)
41  * [team opts](#opts)
42  * [`create()`](#create)
43  * [`destroy()`](#destroy)
44  * [`add()`](#add)
45  * [`rm()`](#rm)
46  * [`lsTeams()`](#ls-teams)
47  * [`lsTeams.stream()`](#ls-teams-stream)
48  * [`lsUsers()`](#ls-users)
49  * [`lsUsers.stream()`](#ls-users-stream)
50
51### Install
52
53`$ npm install libnpmteam`
54
55### API
56
57#### <a name="opts"></a> `opts` for `libnpmteam` commands
58
59`libnpmteam` uses [`npm-registry-fetch`](https://npm.im/npm-registry-fetch).
60All options are passed through directly to that library, so please refer to [its
61own `opts`
62documentation](https://www.npmjs.com/package/npm-registry-fetch#fetch-options)
63for options that can be passed in.
64
65A couple of options of note for those in a hurry:
66
67* `opts.token` - can be passed in and will be used as the authentication token for the registry. For other ways to pass in auth details, see the n-r-f docs.
68* `opts.otp` - certain operations will require an OTP token to be passed in. If a `libnpmteam` command fails with `err.code === EOTP`, please retry the request with `{otp: <2fa token>}`
69
70#### <a name="create"></a> `> team.create(team, [opts]) -> Promise`
71
72Creates a team named `team`. Team names use the format `@<scope>:<name>`, with
73the `@` being optional.
74
75Additionally, `opts.description` may be passed in to include a description.
76
77##### Example
78
79```javascript
80await team.create('@npm:cli', {token: 'myregistrytoken'})
81// The @npm:cli team now exists.
82```
83
84#### <a name="destroy"></a> `> team.destroy(team, [opts]) -> Promise`
85
86Destroys a team named `team`. Team names use the format `@<scope>:<name>`, with
87the `@` being optional.
88
89##### Example
90
91```javascript
92await team.destroy('@npm:cli', {token: 'myregistrytoken'})
93// The @npm:cli team has been destroyed.
94```
95
96#### <a name="add"></a> `> team.add(user, team, [opts]) -> Promise`
97
98Adds `user` to `team`.
99
100##### Example
101
102```javascript
103await team.add('zkat', '@npm:cli', {token: 'myregistrytoken'})
104// @zkat now belongs to the @npm:cli team.
105```
106
107#### <a name="rm"></a> `> team.rm(user, team, [opts]) -> Promise`
108
109Removes `user` from `team`.
110
111##### Example
112
113```javascript
114await team.rm('zkat', '@npm:cli', {token: 'myregistrytoken'})
115// @zkat is no longer part of the @npm:cli team.
116```
117
118#### <a name="ls-teams"></a> `> team.lsTeams(scope, [opts]) -> Promise`
119
120Resolves to an array of team names belonging to `scope`.
121
122##### Example
123
124```javascript
125await team.lsTeams('@npm', {token: 'myregistrytoken'})
126=>
127[
128  'npm:cli',
129  'npm:web',
130  'npm:registry',
131  'npm:developers'
132]
133```
134
135#### <a name="ls-teams-stream"></a> `> team.lsTeams.stream(scope, [opts]) -> Stream`
136
137Returns a stream of teams belonging to `scope`.
138
139For a Promise-based version of these results, see [`team.lsTeams()`](#ls-teams).
140
141##### Example
142
143```javascript
144for await (let team of team.lsTeams.stream('@npm', {token: 'myregistrytoken'})) {
145  console.log(team)
146}
147
148// outputs
149// npm:cli
150// npm:web
151// npm:registry
152// npm:developers
153```
154
155#### <a name="ls-users"></a> `> team.lsUsers(team, [opts]) -> Promise`
156
157Resolves to an array of usernames belonging to `team`.
158
159For a streamed version of these results, see [`team.lsUsers.stream()`](#ls-users-stream).
160
161##### Example
162
163```javascript
164await team.lsUsers('@npm:cli', {token: 'myregistrytoken'})
165=>
166[
167  'iarna',
168  'zkat'
169]
170```
171
172#### <a name="ls-users-stream"></a> `> team.lsUsers.stream(team, [opts]) -> Stream`
173
174Returns a stream of usernames belonging to `team`.
175
176For a Promise-based version of these results, see [`team.lsUsers()`](#ls-users).
177
178##### Example
179
180```javascript
181for await (let user of team.lsUsers.stream('@npm:cli', {token: 'myregistrytoken'})) {
182  console.log(user)
183}
184
185// outputs
186// iarna
187// zkat
188```
189