0
# libnpmorg
1

2
libnpmorg is a Node.js library for programmatically managing npm organization memberships and roles. It provides a clean API to add, remove, and list organization members with their roles through the npm registry API, supporting all standard npm authentication methods including tokens and OTP for two-factor authentication.
3

4
## Package Information
5

6
- **Package Name**: libnpmorg
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install libnpmorg`
10

11
## Core Imports
12

13
```javascript
14
const org = require("libnpmorg");
15
```
16

17
For individual functions:
18

19
```javascript
20
const { set, rm, ls } = require("libnpmorg");
21
```
22

23
## Basic Usage
24

25
```javascript
26
const org = require("libnpmorg");
27

28
// List organization members
29
const roster = await org.ls("myorg", { token: "your-npm-token" });
30
console.log(roster);
31
// Roster { alice: 'developer', bob: 'admin', charlie: 'owner' }
32

33
// Add or update a member with specific role
34
const memberDetails = await org.set("myorg", "newuser", "developer", {
35
  token: "your-npm-token"
36
});
37
console.log(memberDetails);
38
// MembershipDetail { org: { name: 'myorg', size: 4 }, user: 'newuser', role: 'developer' }
39

40
// Add member with default 'developer' role (role parameter omitted)
41
const memberDetails2 = await org.set("myorg", "anothernewuser", {
42
  token: "your-npm-token"
43
});
44
console.log(memberDetails2);
45
// MembershipDetail { org: { name: 'myorg', size: 5 }, user: 'anothernewuser', role: 'developer' }
46

47
// Remove a member
48
await org.rm("myorg", "olduser", { token: "your-npm-token" });
49
```
50

51
## Authentication
52

53
All functions accept an options object that supports npm-registry-fetch authentication:
54

55
- **token**: Authentication token for npm registry
56
- **otp**: One-time password for two-factor authentication
57
- **registry**: Custom registry URL (defaults to npm registry)
58

59
Common authentication patterns:
60

61
```javascript
62
// Using npm token
63
const options = { token: "npm_1234567890abcdef" };
64

65
// With two-factor authentication
66
const options = { token: "npm_1234567890abcdef", otp: "123456" };
67

68
// Custom registry
69
const options = { 
70
  token: "your-token",
71
  registry: "https://custom-registry.com/" 
72
};
73
```
74

75
## Capabilities
76

77
### Set Member Role
78

79
Adds a new member to an organization or updates an existing member's role.
80

81
```javascript { .api }
82
/**
83
 * Set or update a user's role in an organization
84
 * @param org - Organization name (with or without @ prefix)
85
 * @param user - Username (with or without @ prefix)
86
 * @param role - Role ('admin', 'owner', or 'developer'). Optional, defaults to 'developer'
87
 * @param opts - npm-registry-fetch options for authentication and configuration
88
 * @returns Promise resolving to MembershipDetail object
89
 */
90
function set(org, user, role, opts);
91

92
/**
93
 * Set or update a user's role in an organization (role omitted, defaults to 'developer')
94
 * @param org - Organization name (with or without @ prefix)
95
 * @param user - Username (with or without @ prefix)  
96
 * @param opts - npm-registry-fetch options for authentication and configuration
97
 * @returns Promise resolving to MembershipDetail object
98
 */
99
function set(org, user, opts);
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
// Add user with default 'developer' role
106
await org.set("myorg", "alice", { token: "your-token" });
107

108
// Add user with specific role
109
await org.set("@myorg", "@bob", "admin", { token: "your-token" });
110

111
// Update existing user's role
112
await org.set("myorg", "charlie", "owner", { 
113
  token: "your-token",
114
  otp: "123456" 
115
});
116
```
117

118
### Remove Member
119

120
Removes a user from an organization.
121

122
```javascript { .api }
123
/**
124
 * Remove a user from an organization
125
 * @param org - Organization name (with or without @ prefix)
126
 * @param user - Username (with or without @ prefix)
127
 * @param opts - npm-registry-fetch options for authentication and configuration
128
 * @returns Promise resolving to null on success
129
 */
130
function rm(org, user, opts);
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
// Remove user from organization
137
await org.rm("myorg", "alice", { token: "your-token" });
138

139
// Remove user with @ prefixes
140
await org.rm("@myorg", "@bob", { token: "your-token" });
141
```
142

143
### List Members
144

145
Lists all members of an organization with their roles.
146

147
```javascript { .api }
148
/**
149
 * List all members of an organization
150
 * @param org - Organization name (with or without @ prefix)
151
 * @param opts - npm-registry-fetch options for authentication and configuration
152
 * @returns Promise resolving to Roster object (username: role mappings)
153
 */
154
function ls(org, opts);
155
```
156

157
**Usage Examples:**
158

159
```javascript
160
// List all organization members
161
const roster = await org.ls("myorg", { token: "your-token" });
162
console.log(roster);
163
// Roster { alice: 'developer', bob: 'admin', charlie: 'owner' }
164

165
// Iterate over members
166
for (const [username, role] of Object.entries(roster)) {
167
  console.log(`${username}: ${role}`);
168
}
169
```
170

171
### Stream Members
172

173
Returns a stream of organization members as [username, role] pairs.
174

175
```javascript { .api }
176
/**
177
 * Stream organization members as [key, value] pairs
178
 * @param org - Organization name (with or without @ prefix) 
179
 * @param opts - npm-registry-fetch options for authentication and configuration
180
 * @returns Stream emitting [username, role] pairs, compatible with Symbol.asyncIterator
181
 */
182
function ls.stream(org, opts);
183
```
184

185
**Usage Examples:**
186

187
```javascript
188
// Stream members using async iteration
189
for await (const [username, role] of org.ls.stream("myorg", { token: "your-token" })) {
190
  console.log(`${username}: ${role}`);
191
}
192

193
// Collect stream results manually
194
const stream = org.ls.stream("myorg", { token: "your-token" });
195
const results = await stream.collect();
196
console.log(results); // [['alice', 'developer'], ['bob', 'admin'], ['charlie', 'owner']]
197
```
198

199
## Types
200

201
```javascript { .api }
202
/**
203
 * Result object returned by set() operations
204
 */
205
class MembershipDetail {
206
  org: {
207
    name: string;    // Organization name
208
    size: number;    // Total number of members
209
  };
210
  user: string;      // Username
211
  role: string;      // User's role in organization
212
}
213

214
/**
215
 * Result object returned by ls() operations
216
 * Keys are usernames, values are roles
217
 */
218
class Roster {
219
  [username: string]: 'admin' | 'owner' | 'developer';
220
}
221

222
/**
223
 * Options object accepted by all functions
224
 * Extends npm-registry-fetch options
225
 */
226
interface Options {
227
  token?: string;           // npm authentication token
228
  otp?: string;             // One-time password for 2FA
229
  registry?: string;        // Registry URL (defaults to npm)
230
  [key: string]: any;       // Other npm-registry-fetch options
231
}
232
```
233

234
## Roles
235

236
npm organizations support three role types:
237

238
- **owner**: Full administrative access including billing and member management
239
- **admin**: Can manage organization members but not billing
240
- **developer**: Can access organization packages but cannot manage members
241

242
## Parameter Validation
243

244
All functions perform parameter validation using the aproba library:
245

246
- Organization names and usernames must be strings
247
- Options must be objects when provided
248
- Invalid parameter types will throw validation errors
249

250
## Error Handling
251

252
Functions may throw errors from npm-registry-fetch and parameter validation:
253

254
- **Validation errors**: Invalid parameter types or missing required parameters
255
- **Authentication errors**: Invalid or missing token
256
- **Permission errors**: Insufficient privileges for the operation
257
- **OTP errors**: Two-factor authentication required (`err.code === 'EOTP'`)
258
- **Network errors**: Registry connectivity issues
259

260
```javascript
261
try {
262
  await org.set("myorg", "alice", "admin", { token: "invalid-token" });
263
} catch (error) {
264
  if (error.code === 'EOTP') {
265
    // Retry with OTP
266
    await org.set("myorg", "alice", "admin", { 
267
      token: "valid-token",
268
      otp: "123456" 
269
    });
270
  } else {
271
    console.error("Operation failed:", error.message);
272
  }
273
}
274
```