npm-registry-client API sketch

nrc-api

## SUMMARY

* request
* get

* adduser
* bugs
* deprecate
* fetch
* publish
* star
* stars
* tag
* unpublish
* upload

## METHODS

`+` denotes required parameter
`-` denotes private data added to params by call

`name:Type[=default]`

adduser(uri, params, cb)
  +uri:String
  +params:Object
    +auth:Credentials
  +cb:Function

bugs(uri, params, cb)
  +uri:String
  +params:Object
    auth:Credentials
  +cb:Function

deprecate(uri, params, cb)
  +uri:String
  +params:Object
    +version:Semver
    +message:String
    +auth:Credentials
  +cb:Function

get(uri, params, cb)
  +uri:String
  +params:Object
    timeout:Number=-1
    follow:Boolean=false
    staleOk:Boolean=false
    auth:credentials
    -stat:fs.Stats
    -data:Object
  +cb:Function

publish(uri, params, cb)
  +uri:String
  +params:Object
    +metadata:Object
    +body:Stream
    +auth:Credentials
  +cb:Function

star(uri, params, cb)
  +uri:String
  +params:Object
    starred:Boolean=false
    +auth:Credentials
  +cb:Function

stars(uri, params, cb)
  +uri:String
  +params:Object
    +username:String
    auth:Credentials
  +cb:Function

tag(uri, params, cb)
  +uri:String
  +params:Object
    +version:String
    +tag:String
    +auth:Credentials
  +cb:Function

unpublish(uri, params, cb)
  +uri:String
  +params:Object
    version:String=delete all versions
    +auth:Credentials
  +cb:Function

whoami(uri, params, cb)
  +uri:String
  +params:Object
    +auth:Credentials
  +cb:Function

## PLUMBING

request(uri, params, cb)
  +uri:String
  +params:Object
    method:String="GET"
    body:Stream|Buffer|String|Object=operation is read-only
    etag:String
    follow:Boolean=true
    auth:Credentials={}
  +cb:Function

fetch(uri, params, cb)
  +uri:String
  +params:Object
    headers:Object={}
    +auth:Credentials={}
  +cb:Function

upload(uri, params, cb)
  +uri:String
  +params:Object
    +body:Stream
    etag:String
    follow:Boolean=true
    +auth:Credentials
  +cb:Function

See also this rework of the README (from this diff).

As a casual onlooker, I find this reasonable.

• Has deprecation always required a message?
• What does follow mean in get()?
• What does staleOk mean in get()?
• If staleOk is a new thing, there's probably a less mis-spellable name for it.
• Confused by version:String=delete all versions
• I think I heard you say that this new thing doesnt use npmconf, but the README you link to above still mentions npmconf.

The bugs api seems weirdly out of place

Has deprecation always required a message?

As far as I know, yes.

What does follow mean in get()?
What does staleOk mean in get()?

From the linked README:

• follow {Boolean} Follow 302/301 responses. Optional (default: true).
• staleOk {Boolean} If there's cached data available, then return that to
  the callback quickly, and update the cache the background. Optional
  (default: false).

If staleOk is a new thing, there's probably a less mis-spellable name for it.

Too bad! It's been the name forever!

Confused by version:String=delete all versions

That's the default action, although I meant "unpublish", not "delete".

I think I heard you say that this new thing doesnt use npmconf, but the README you link to above still mentions npmconf.

Yeah, that's the next thing to do after I finish reworking the API. Doing this one piece at a time.

@iarna

The bugs api seems weirdly out of place

No more than stars, although it should probably also support repo and the other metadata views that are currently fetched using get or request right now. I'll add those before releasing version 4.

@othiym23: stars is a module search isn't it? Not a metadata fetch?

@iarna it's a metadata fetch, just using a non-default view:

function stars (base, name, cb) {
  name = encodeURIComponent(name)
  var path = "/-/_view/starredByUser?key=\""+name+"\""
  this.request("GET", url.resolve(base, path), null, cb)
}

👍