Skip to content

Latest commit

 

History

History
306 lines (231 loc) · 6.95 KB

npm.md

File metadata and controls

306 lines (231 loc) · 6.95 KB
Raw

npm registry docs

The npm registry (api) isn’t documented very well. You can find some docs in npm/registry, but most of it can be best perused by reading code, such as libnpmaccess.

…or read this document.

Table of Contents

Authentication

First, make sure to set npm to use 2fa for auth-only. Proper 2fa doesn’t work well as you’d have to fill in OTPs all the time.

npm profile enable-2fa auth-only

Then, create an npm token:

npm token create

Store that somewhere in a dotenv.

Org

List teams in an org

org=remarkjs

curl "https://registry.npmjs.org/-/org/$org/team" \
  -H "Authorization: Bearer $token"
# ["remarkjs:developers","remarkjs:foo"]

List packages in an org

org=remarkjs

curl "https://registry.npmjs.org/-/org/$org/package"
# {"remark":"write",…"remark-external-links":"write"}

List users in an org

Only users the token can see are shown.

org=remarkjs

curl "https://registry.npmjs.org/-/org/$org/user" \
  -H "Authorization: Bearer $token"
# {"wooorm":"owner",…"murderlon":"admin"}

Add or change a user in an org

org=remarkjs
user="wooorm"
role="owner" # "developer", "owner", or "admin"
# See https://docs.npmjs.com/org-roles-and-permissions.

curl "https://registry.npmjs.org/-/org/$org/user" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"user\": \"$user\", \"role\": \"$role\"}"
# {"org":{"name":"remarkjs","size":5},"user":"wooorm","role":"owner"}

Remove a user from an org

org=remarkjs
user="wooorm"

curl "https://registry.npmjs.org/-/org/$org/user" \
  -X DELETE \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"user\": \"$user\"}"

Team

Add or change a team

org=remarkjs
team=bar
description=bravo

curl "https://registry.npmjs.org/-/org/$org/team" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$team\",\"description\": \"$description\"}"
# {"name":"bar"}

List users in a team

org=remarkjs
team=developers

curl "https://registry.npmjs.org/-/team/$org/$team/user" \
  -H "Authorization: Bearer $token"
# ["wooorm",…]

Add a user to a team

org=remarkjs
team=foo
user=wooorm

curl "https://registry.npmjs.org/-/team/$org/$team/user" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"user\":\"$user\"}"
# {}

Remove a user from a team

org=remarkjs
team=foo
user=johno

curl "https://registry.npmjs.org/-/team/$org/$team/user" \
  -X DELETE \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"user\":\"$user\"}"
# empty

List packages in a team

org=remarkjs
team=developers

curl "https://registry.npmjs.org/-/team/$org/$team/package" \
  -H "Authorization: Bearer $token"
# {"remark":"write",…"remark-external-links":"write"}

Add or change a package in a team

org=remarkjs
team=foo
package=remark-parse
permissions="read-write" # "read-only" or "read-write"

curl "https://registry.npmjs.org/-/team/$org/$team/package" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"package\": \"$package\", \"permissions\": \"$permissions\"}"
# {}

Remove a package from a team

org=remarkjs
team=foo
package=remark-parse

curl "https://registry.npmjs.org/-/team/$org/$team/package" \
  -X DELETE \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"package\": \"$package\"}"
# empty response

Packages

Get a package

package=remark-parse # Use "@foo%2bar" for scoped packages

curl "https://registry.npmjs.org/$package" \
  -H "Accept: application/vnd.npm.install-v1+json" # Remove for full metadata.
# {"_id":"remark-parse","_rev":"35-c4b211558296c2be5fad20fd0a7b3b25","name":"remark-parse","maintainers":[…],…}

This can be used to find maintainers.

Get collaborators of a package

package=remark-parse

curl "https://registry.npmjs.org/-/package/$package/collaborators" \
  -H "Authorization: Bearer $token"
# {"wooorm":"write",…}

Set maintainers for a package

package=remark-parse
rev=10-4193cf2ba92283e3e8fd605d75108054

curl "https://registry.npmjs.org/$package/-rev/$rev" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{
    \"_id\": \"$package\",
    \"_rev\": \"$rev\",
    \"maintainers\": [
      {\"email\":\"[email protected]\",\"name\":\"vweevers\"},
      {\"email\":\"[email protected]\",\"name\":\"wooorm\"}
    ]
  }" \
  --verbose

Set 2fa access of a package

package=remark-parse
tfa=true # true or false

curl "https://registry.npmjs.org/-/package/$package/access" \
  -X POST \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"publish_requires_tfa\": $tfa}"
# empty

Users

Get the current user (from the token)

curl "https://registry.npmjs.org/-/npm/v1/user" \
  -H "Authorization: Bearer $token"
# {"tfa":{"pending":false,…"fullname":"Titus Wormer",…"twitter":"wooorm","github":"wooorm"}

Get a user

user=wooorm

curl "https://registry.npmjs.org/-/user/org.couchdb.user:$user"
# {"_id":"org.couchdb.user:wooorm","email":"[email protected]","name":"wooorm"}

List packages for a user

user=wooorm

curl "https://registry.npmjs.org/-/user/$user/package"
# {"retext-latin":"write",…"remark-bookmarks":"write"}