• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# libnpmorg
2
3[![npm version](https://img.shields.io/npm/v/libnpmorg.svg)](https://npm.im/libnpmorg)
4[![license](https://img.shields.io/npm/l/libnpmorg.svg)](https://npm.im/libnpmorg)
5[![CI - libnpmorg](https://github.com/npm/cli/actions/workflows/ci-libnpmorg.yml/badge.svg)](https://github.com/npm/cli/actions/workflows/ci-libnpmorg.yml)
6
7[`libnpmorg`](https://github.com/npm/libnpmorg) is a Node.js library for
8programmatically accessing the [npm Org membership
9API](https://github.com/npm/registry/blob/master/docs/orgs/memberships.md#membership-detail).
10
11## Table of Contents
12
13* [Example](#example)
14* [Install](#install)
15* [Contributing](#contributing)
16* [API](#api)
17  * [hook opts](#opts)
18  * [`set()`](#set)
19  * [`rm()`](#rm)
20  * [`ls()`](#ls)
21  * [`ls.stream()`](#ls-stream)
22
23## Example
24
25```js
26const org = require('libnpmorg')
27
28console.log(await org.ls('myorg', {token: 'deadbeef'}))
29=>
30Roster {
31  zkat: 'developer',
32  iarna: 'admin',
33  isaacs: 'owner'
34}
35```
36
37## Install
38
39`$ npm install libnpmorg`
40
41### API
42
43#### <a name="opts"></a> `opts` for `libnpmorg` commands
44
45`libnpmorg` uses [`npm-registry-fetch`](https://npm.im/npm-registry-fetch).
46All options are passed through directly to that library, so please refer to [its
47own `opts`
48documentation](https://www.npmjs.com/package/npm-registry-fetch#fetch-options)
49for options that can be passed in.
50
51A couple of options of note for those in a hurry:
52
53* `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.
54* `opts.otp` - certain operations will require an OTP token to be passed in. If a `libnpmorg` command fails with `err.code === EOTP`, please retry the request with `{otp: <2fa token>}`
55
56#### <a name="set"></a> `> org.set(org, user, [role], [opts]) -> Promise`
57
58The returned Promise resolves to a [Membership
59Detail](https://github.com/npm/registry/blob/master/docs/orgs/memberships.md#membership-detail)
60object.
61
62The `role` is optional and should be one of `admin`, `owner`, or `developer`.
63`developer` is the default if no `role` is provided.
64
65`org` and `user` must be scope names for the org name and user name
66respectively. They can optionally be prefixed with `@`.
67
68See also: [`PUT
69/-/org/:scope/user`](https://github.com/npm/registry/blob/master/docs/orgs/memberships.md#org-membership-replace)
70
71##### Example
72
73```javascript
74await org.set('@myorg', '@myuser', 'admin', {token: 'deadbeef'})
75=>
76MembershipDetail {
77  org: {
78    name: 'myorg',
79    size: 15
80  },
81  user: 'myuser',
82  role: 'admin'
83}
84```
85
86#### <a name="rm"></a> `> org.rm(org, user, [opts]) -> Promise`
87
88The Promise resolves to `null` on success.
89
90`org` and `user` must be scope names for the org name and user name
91respectively. They can optionally be prefixed with `@`.
92
93See also: [`DELETE
94/-/org/:scope/user`](https://github.com/npm/registry/blob/master/docs/orgs/memberships.md#org-membership-delete)
95
96##### Example
97
98```javascript
99await org.rm('myorg', 'myuser', {token: 'deadbeef'})
100```
101
102#### <a name="ls"></a> `> org.ls(org, [opts]) -> Promise`
103
104The Promise resolves to a
105[Roster](https://github.com/npm/registry/blob/master/docs/orgs/memberships.md#roster)
106object.
107
108`org` must be a scope name for an org, and can be optionally prefixed with `@`.
109
110See also: [`GET
111/-/org/:scope/user`](https://github.com/npm/registry/blob/master/docs/orgs/memberships.md#org-roster)
112
113##### Example
114
115```javascript
116await org.ls('myorg', {token: 'deadbeef'})
117=>
118Roster {
119  zkat: 'developer',
120  iarna: 'admin',
121  isaacs: 'owner'
122}
123```
124
125#### <a name="ls-stream"></a> `> org.ls.stream(org, [opts]) -> Stream`
126
127Returns a stream of entries for a
128[Roster](https://github.com/npm/registry/blob/master/docs/orgs/memberships.md#roster),
129with each emitted entry in `[key, value]` format.
130
131`org` must be a scope name for an org, and can be optionally prefixed with `@`.
132
133The returned stream is a valid `Symbol.asyncIterator`.
134
135See also: [`GET
136/-/org/:scope/user`](https://github.com/npm/registry/blob/master/docs/orgs/memberships.md#org-roster)
137
138##### Example
139
140```javascript
141for await (let [user, role] of org.ls.stream('myorg', {token: 'deadbeef'})) {
142  console.log(`user: ${user} (${role})`)
143}
144=>
145user: zkat (developer)
146user: iarna (admin)
147user: isaacs (owner)
148```
149