1 | # libnpmteam [![npm version](https://img.shields.io/npm/v/libnpmteam.svg)](https://npm.im/libnpmteam) [![license](https://img.shields.io/npm/l/libnpmteam.svg)](https://npm.im/libnpmteam) [![Travis](https://img.shields.io/travis/npm/libnpmteam/latest.svg)](https://travis-ci.org/npm/libnpmteam) [![AppVeyor](https://img.shields.io/appveyor/ci/zkat/libnpmteam/latest.svg)](https://ci.appveyor.com/project/zkat/libnpmteam) [![Coverage Status](https://coveralls.io/repos/github/npm/libnpmteam/badge.svg?branch=latest)](https://coveralls.io/github/npm/libnpmteam?branch=latest)
|
2 |
|
3 | [`libnpmteam`](https://github.com/npm/libnpmteam) is a Node.js
|
4 | library that provides programmatic access to the guts of the npm CLI's `npm
|
5 | team` command and its various subcommands.
|
6 |
|
7 | ## Example
|
8 |
|
9 | ```javascript
|
10 | const access = require('libnpmteam')
|
11 |
|
12 | // List all teams for the @npm org.
|
13 | console.log(await team.lsTeams('npm'))
|
14 | ```
|
15 |
|
16 | ## Table of Contents
|
17 |
|
18 | * [Installing](#install)
|
19 | * [Example](#example)
|
20 | * [Contributing](#contributing)
|
21 | * [API](#api)
|
22 | * [team opts](#opts)
|
23 | * [`create()`](#create)
|
24 | * [`destroy()`](#destroy)
|
25 | * [`add()`](#add)
|
26 | * [`rm()`](#rm)
|
27 | * [`lsTeams()`](#ls-teams)
|
28 | * [`lsTeams.stream()`](#ls-teams-stream)
|
29 | * [`lsUsers()`](#ls-users)
|
30 | * [`lsUsers.stream()`](#ls-users-stream)
|
31 |
|
32 | ### Install
|
33 |
|
34 | `$ npm install libnpmteam`
|
35 |
|
36 | ### Contributing
|
37 |
|
38 | The npm team enthusiastically welcomes contributions and project participation!
|
39 | There's a bunch of things you can do if you want to contribute! The [Contributor
|
40 | Guide](CONTRIBUTING.md) has all the information you need for everything from
|
41 | reporting bugs to contributing entire new features. Please don't hesitate to
|
42 | jump in if you'd like to, or even ask us questions if something isn't clear.
|
43 |
|
44 | All participants and maintainers in this project are expected to follow [Code of
|
45 | Conduct](CODE_OF_CONDUCT.md), and just generally be excellent to each other.
|
46 |
|
47 | Please refer to the [Changelog](CHANGELOG.md) for project history details, too.
|
48 |
|
49 | Happy hacking!
|
50 |
|
51 | ### API
|
52 |
|
53 | #### <a name="opts"></a> `opts` for `libnpmteam` commands
|
54 |
|
55 | `libnpmteam` uses [`npm-registry-fetch`](https://npm.im/npm-registry-fetch).
|
56 | All options are passed through directly to that library, so please refer to [its
|
57 | own `opts`
|
58 | documentation](https://www.npmjs.com/package/npm-registry-fetch#fetch-options)
|
59 | for options that can be passed in.
|
60 |
|
61 | A couple of options of note for those in a hurry:
|
62 |
|
63 | * `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.
|
64 | * `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>}`
|
65 | * `opts.Promise` - If you pass this in, the Promises returned by `libnpmteam` commands will use this Promise class instead. For example: `{Promise: require('bluebird')}`
|
66 |
|
67 | #### <a name="create"></a> `> team.create(team, [opts]) -> Promise`
|
68 |
|
69 | Creates a team named `team`. Team names use the format `@<scope>:<name>`, with
|
70 | the `@` being optional.
|
71 |
|
72 | Additionally, `opts.description` may be passed in to include a description.
|
73 |
|
74 | ##### Example
|
75 |
|
76 | ```javascript
|
77 | await team.create('@npm:cli', {token: 'myregistrytoken'})
|
78 | // The @npm:cli team now exists.
|
79 | ```
|
80 |
|
81 | #### <a name="destroy"></a> `> team.destroy(team, [opts]) -> Promise`
|
82 |
|
83 | Destroys a team named `team`. Team names use the format `@<scope>:<name>`, with
|
84 | the `@` being optional.
|
85 |
|
86 | ##### Example
|
87 |
|
88 | ```javascript
|
89 | await team.destroy('@npm:cli', {token: 'myregistrytoken'})
|
90 | // The @npm:cli team has been destroyed.
|
91 | ```
|
92 |
|
93 | #### <a name="add"></a> `> team.add(user, team, [opts]) -> Promise`
|
94 |
|
95 | Adds `user` to `team`.
|
96 |
|
97 | ##### Example
|
98 |
|
99 | ```javascript
|
100 | await team.add('zkat', '@npm:cli', {token: 'myregistrytoken'})
|
101 | // @zkat now belongs to the @npm:cli team.
|
102 | ```
|
103 |
|
104 | #### <a name="rm"></a> `> team.rm(user, team, [opts]) -> Promise`
|
105 |
|
106 | Removes `user` from `team`.
|
107 |
|
108 | ##### Example
|
109 |
|
110 | ```javascript
|
111 | await team.rm('zkat', '@npm:cli', {token: 'myregistrytoken'})
|
112 | // @zkat is no longer part of the @npm:cli team.
|
113 | ```
|
114 |
|
115 | #### <a name="ls-teams"></a> `> team.lsTeams(scope, [opts]) -> Promise`
|
116 |
|
117 | Resolves to an array of team names belonging to `scope`.
|
118 |
|
119 | ##### Example
|
120 |
|
121 | ```javascript
|
122 | await team.lsTeams('@npm', {token: 'myregistrytoken'})
|
123 | =>
|
124 | [
|
125 | 'npm:cli',
|
126 | 'npm:web',
|
127 | 'npm:registry',
|
128 | 'npm:developers'
|
129 | ]
|
130 | ```
|
131 |
|
132 | #### <a name="ls-teams-stream"></a> `> team.lsTeams.stream(scope, [opts]) -> Stream`
|
133 |
|
134 | Returns a stream of teams belonging to `scope`.
|
135 |
|
136 | For a Promise-based version of these results, see [`team.lsTeams()`](#ls-teams).
|
137 |
|
138 | ##### Example
|
139 |
|
140 | ```javascript
|
141 | for await (let team of team.lsTeams.stream('@npm', {token: 'myregistrytoken'})) {
|
142 | console.log(team)
|
143 | }
|
144 |
|
145 | // outputs
|
146 | // npm:cli
|
147 | // npm:web
|
148 | // npm:registry
|
149 | // npm:developers
|
150 | ```
|
151 |
|
152 | #### <a name="ls-users"></a> `> team.lsUsers(team, [opts]) -> Promise`
|
153 |
|
154 | Resolves to an array of usernames belonging to `team`.
|
155 |
|
156 | For a streamed version of these results, see [`team.lsUsers.stream()`](#ls-users-stream).
|
157 |
|
158 | ##### Example
|
159 |
|
160 | ```javascript
|
161 | await team.lsUsers('@npm:cli', {token: 'myregistrytoken'})
|
162 | =>
|
163 | [
|
164 | 'iarna',
|
165 | 'zkat'
|
166 | ]
|
167 | ```
|
168 |
|
169 | #### <a name="ls-users-stream"></a> `> team.lsUsers.stream(team, [opts]) -> Stream`
|
170 |
|
171 | Returns a stream of usernames belonging to `team`.
|
172 |
|
173 | For a Promise-based version of these results, see [`team.lsUsers()`](#ls-users).
|
174 |
|
175 | ##### Example
|
176 |
|
177 | ```javascript
|
178 | for await (let user of team.lsUsers.stream('@npm:cli', {token: 'myregistrytoken'})) {
|
179 | console.log(user)
|
180 | }
|
181 |
|
182 | // outputs
|
183 | // iarna
|
184 | // zkat
|
185 | ```
|