A self-generating client for npm's new registry API
Note: This client was designed to work with a private API that is only accessible to employees of npm, Inc. If that API is ever made public, this client will become relevant/useful.
var npm = require('acl-client')()
npm.packages.get('browserify')
.then(function(pkg){ /* yay */ })
.catch(function(err){ /* oof */ })
- The client is stateless and has zero configuration.
- All operations return a request request wrapped in a promise.
- To override the default host of
api.npmjs.com
setprocess.env.ACL_CLIENT_HOST
.
Every request takes an optional options
object as its last argument. The following options are allowed:
ttl
- time in seconds to cache the response in redis. If not set, cache will not be used. Value can also be a human-friendly string like5 minutes
or4 hours
.bearer
- a string of the current username. Can be used ifhapiRequest
is not available. If bothhapiRequest
andbearer
options are specified,bearer
takes precedence.logger
- an object with four methods:debug
,info
,warn
, anderror
. See the bole API for more info.hapiRequest
- a Hapi request object. If the request is from a logged-in user, this will setbearer
automatically. The client will also emit log messages using the given request'slogger
.
All PUT
, POST
, and DELETE
operations require a bearer token. Some GET
requests do too.
To inject a bearer token into the request, pass a hapi request object as the last argument, or an object with a bearer
string:
npm.collaborators.get('@npm/foo', {hapiRequest: request})
// or
npm.collaborators.get('@npm/foo', {bearer: 'zeke'})
To enable the built-in redis cache, set ACL_CLIENT_REDIS_URL
in the environment before
requiring the client. To cache a request, specify a TTL in seconds or a human-friendly
string like 5 hours
or 20 minutes
.
// set this _before_ requiring the module
process.env.ACL_CLIENT_REDIS_URL = 'redis://localhost:6379'
// initialize the client. The redis instance will be attached to each method
var npm = require('npm-api-client')()
// set a `ttl` option in seconds
npm.packages.get('browserify', {ttl: 60})
// or use a human-friendly string
npm.packages.get('browserify', {ttl: '2 hours'})
To invalidate the cache for a specific request, call that request's cache.drop
method,
passing the same arguments used when making the initial request:
npm.packages.get.cache.drop('browserify')
.then(function(){
// bye-bye browserify
})
Note: the optional options
object used to initially make the request, e.g.
{ttl: 60, logger: null}
, need not be present when calling cache.drop()
ACL_CLIENT_HOST
(required): the hostname (and optional port) to make requests to, sanshttp(s)
scheme.ACL_CLIENT_CUSTOMER_HOST
(optional): the hostname fornpm.customer
requestsACL_CLIENT_REDIS_URL
(optional): a redis instance for caching request responses
See dist/operations.json for more details about the methods below.
- Get metadata for a specific npm package
- GET /package/{packageName}
- Get collections of packages, sorted various ways
- GET /package
- Get a count of all the public packages in the registry
- GET /package/-/count
- Star a package
- PUT /package/{packageName}/star
- Get an aggregate permissions object for a package. This endpoint is used internally by the cache.
- GET /package/{packageName}/perms
- Delete a package. Meant for admin purposes, such as unpublish.
- DELETE /package/{packageName}
- create a new package (infers whether org or user based on scope).
- PUT /package
- Get the default team for the package. Bearer user must be super-admin, team-admin of the default team or owner of the package
- GET /package/{packageName}/default-team
- Get all collaborators on a package
- GET /package/{packageName}/collaborators
- Add a new collaborator to a package
- PUT /package/{packageName}/collaborators
- Update a collaborator
- POST /package/{packageName}/collaborators/{userName}
- Remove a collaborator from package
- DELETE /package/{packageName}/collaborators/{userName}
- Create a new npm user account
- PUT /user
- Update an npm user account
- POST /user/{userName}
- Get metdata for a specific user
- GET /user/{userName}
- Delete a user
- DELETE /user/{userName}
- Authenticate a user with username and password.
- POST /user/{userName}/login
- Verify a user's email address
- POST /user/{userName}/verify
- Get all packages collaborated on by a specific user. A bearer token is provided indicating the user requesting the listing. Returns all packages that user has write access to, and that the user associated with the bearer token has read or write access to.
- GET /user/{userName}/package
- Get a list of packages starred by the given user.
- GET /user/{userName}/stars
- Create a placeholder package
- PUT /user/{userName}/package
- Associate a license with a user. internal API endpoint, no bearer token required.
- POST /user/{userName}/license
- Fetch the license associated with a user.
- POST /user/{userName}/license
- Perform typeahead search based on email or name.
- GET /user/-/search
- Update a team's meta-information. Bearer token must be provided, and bearer user must be team-admin or super-admin
- POST /team/{teamName}
- Delete a team.
- DELETE /team/{teamName}
- Add a package to a team. Bearer token must be provided, and bearer user must be team-admin or super-admin.
- POST /team/{teamName}/package
- Remove a package from the team. Bearer token must be provided, and bearer user must be team-admin or super-admin
- DELETE /team/{teamName}/package
- Add a user to the team. Bearer user must be team-admin or super-admin
- POST /team/{teamName}/user
- Remove a user from the team. Bearer user must be team-admin or super-admin
- DELETE /team/{teamName}/user
- Create an organization.
- PUT /org
- Get an organization's meta information.
- GET /org/{orgName}
- Delete an organization. Bearer token must be provided, and bearer user must be a super-admin of org.
- DEL /org/{orgName}
- update the organization's meta information. bearer token must be provided. bearer must be a super-admin of the org.
- POST /org/{orgName}
- Add a user to the organization. Bearer token must be provided. Bearer must be a super-admin of the org
- PUT /org/{orgName}/user
- Get users within organization. TODO: we should allow users to announce whether or not they are within the org. Currently we default to this information being public.
- GET /org/{orgName}/user
- Delete user from organization. Bearer token must be provided, and bearer must be super-admin of organization.
- DEL /org/{orgName}/user
- Update a user's role within the organization. Bearer token must be provided. Bearer must be super-admin of organization
- POST /org/{orgName}/user/{userName}
- Get all packages within organization. Bearer token must be provided. If bearer is not part of org, public packages for org are returned. If bearer is developer, or team-admin, packages for teams that they are on are returned. If the bearer is a super-admin of the org, all packages for the org are returned.
- GET /org/{orgName}/package
- Create a package. Bearer token must be provided, and bearer must be member of organization.
- PUT /org/{orgName}/package
- Get all teams within the organization. Bearer token must be provided. Bearer must be member of organization. If bearer is developer a list of all the teams that they are part of is returned. If bearer is team-admin or super-admin, a list of all teams is returned.
- GET /org/{orgName}/team
- Create a team. Bearer token must be provided, and bearer must be super-admin or team-admin.
- PUT /org/{orgName}/team
- List an organization's scopes. Bearer token must be provided. Bearer must be a member of the organization.
- GET /org/{orgName}/scope
- Associate a license with an org by id. Internal API endpoint, no bearer token required.
- POST /org/{orgName}/license
- Fetch a customer record by npm username.
- GET /stripe/{userName}
- Create a new customer.
- PUT /stripe
- Create a new customer.
- POST /stripe/{userName}
- Delete a customer by npm username.
- DELETE /stripe/{userName}
src/operations.yml defines a list of http operations. An operation looks like this:
name: packages.get
description: Get metadata for a specific npm package
path: /package/{name}
method: GET
When you require('acl-client')()
, the index iterates over each
operation in the schema and binds a reusable request function to each. The end result
is a tree of functions, namespaced by their dot-delimited name
property from the schema:
packages: {
get: [Function],
list: [Function],
count: [Function],
star: [Function],
perms: [Function],
delete: [Function],
create: [Function],
getDefaultTeam: [Function]
},
collaborators: {
list: [Function],
add: [Function],
update: [Function],
delete: [Function]
},
...