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