diff options
author | Audrey Eschright <audrey@npmjs.com> | 2019-01-08 22:26:21 +0300 |
---|---|---|
committer | Audrey Eschright <audrey@npmjs.com> | 2019-01-08 22:26:22 +0300 |
commit | 2a59bfc7989bd5575d8cbba912977c6d1ba92567 (patch) | |
tree | 92c33c518f92bc9a5e0b517ca8b064c2fa47d47c /node_modules/libnpmhook | |
parent | d522bd90c3b0cb08518f249ae5b90bd609fff165 (diff) |
libnpmhook@5.0.2
Diffstat (limited to 'node_modules/libnpmhook')
-rw-r--r-- | node_modules/libnpmhook/CHANGELOG.md | 30 | ||||
-rw-r--r-- | node_modules/libnpmhook/README.md | 254 | ||||
-rw-r--r-- | node_modules/libnpmhook/config.js | 13 | ||||
-rw-r--r-- | node_modules/libnpmhook/index.js | 107 | ||||
-rw-r--r-- | node_modules/libnpmhook/package.json | 36 |
5 files changed, 371 insertions, 69 deletions
diff --git a/node_modules/libnpmhook/CHANGELOG.md b/node_modules/libnpmhook/CHANGELOG.md index 6fe3e05b5..251d1f996 100644 --- a/node_modules/libnpmhook/CHANGELOG.md +++ b/node_modules/libnpmhook/CHANGELOG.md @@ -2,6 +2,36 @@ All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. +<a name="5.0.2"></a> +## [5.0.2](https://github.com/npm/libnpmhook/compare/v5.0.1...v5.0.2) (2018-08-24) + + + +<a name="5.0.1"></a> +## [5.0.1](https://github.com/npm/libnpmhook/compare/v5.0.0...v5.0.1) (2018-08-23) + + +### Bug Fixes + +* **deps:** move JSONStream to prod deps ([bb63594](https://github.com/npm/libnpmhook/commit/bb63594)) + + + +<a name="5.0.0"></a> +# [5.0.0](https://github.com/npm/libnpmhook/compare/v4.0.1...v5.0.0) (2018-08-21) + + +### Features + +* **api:** overhauled API ([46b271b](https://github.com/npm/libnpmhook/commit/46b271b)) + + +### BREAKING CHANGES + +* **api:** the API for ls() has changed, and rm() no longer errors on 404 + + + <a name="4.0.1"></a> ## [4.0.1](https://github.com/npm/libnpmhook/compare/v4.0.0...v4.0.1) (2018-04-09) diff --git a/node_modules/libnpmhook/README.md b/node_modules/libnpmhook/README.md index 0e2f018f2..9a13d0553 100644 --- a/node_modules/libnpmhook/README.md +++ b/node_modules/libnpmhook/README.md @@ -1,8 +1,20 @@ -# libnpmhook [![npm version](https://img.shields.io/npm/v/libnpmhook.svg)](https://npm.im/libnpmhook) [![license](https://img.shields.io/npm/l/libnpmhook.svg)](https://npm.im/libnpmhook) [![Travis](https://img.shields.io/travis/npm/libnpmhook.svg)](https://travis-ci.org/npm/libnpmhook) [![AppVeyor](https://ci.appveyor.com/api/projects/status/github/npm/libnpmhook?svg=true)](https://ci.appveyor.com/project/npm/libnpmhook) [![Coverage Status](https://coveralls.io/repos/github/npm/libnpmhook/badge.svg?branch=latest)](https://coveralls.io/github/npm/libnpmhook?branch=latest) +# libnpmhook [![npm version](https://img.shields.io/npm/v/libnpmhook.svg)](https://npm.im/libnpmhook) [![license](https://img.shields.io/npm/l/libnpmhook.svg)](https://npm.im/libnpmhook) [![Travis](https://img.shields.io/travis/npm/libnpmhook.svg)](https://travis-ci.org/npm/libnpmhook) [![AppVeyor](https://ci.appveyor.com/api/projects/status/github/zkat/libnpmhook?svg=true)](https://ci.appveyor.com/project/zkat/libnpmhook) [![Coverage Status](https://coveralls.io/repos/github/npm/libnpmhook/badge.svg?branch=latest)](https://coveralls.io/github/npm/libnpmhook?branch=latest) [`libnpmhook`](https://github.com/npm/libnpmhook) is a Node.js library for programmatically managing the npm registry's server-side hooks. +For a more general introduction to managing hooks, see [the introductory blog +post](https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm). + +## Example + +```js +const hooks = require('libnpmhook') + +console.log(await hooks.ls('mypkg', {token: 'deadbeef'})) +// array of hook objects on `mypkg`. +``` + ## Install `$ npm install libnpmhook` @@ -10,14 +22,246 @@ programmatically managing the npm registry's server-side hooks. ## Table of Contents * [Example](#example) -* [Features](#features) +* [Install](#install) * [API](#api) + * [hook opts](#opts) + * [`add()`](#add) + * [`rm()`](#rm) + * [`ls()`](#ls) + * [`ls.stream()`](#ls-stream) + * [`update()`](#update) + +### API + +#### <a name="opts"></a> `opts` for `libnpmhook` commands + +`libnpmhook` uses [`npm-registry-fetch`](https://npm.im/npm-registry-fetch). +All options are passed through directly to that library, so please refer to [its +own `opts` +documentation](https://www.npmjs.com/package/npm-registry-fetch#fetch-options) +for options that can be passed in. -### Example +A couple of options of note for those in a hurry: + +* `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. +* `opts.otp` - certain operations will require an OTP token to be passed in. If a `libnpmhook` command fails with `err.code === EOTP`, please retry the request with `{otp: <2fa token>}` +* `opts.Promise` - If you pass this in, the Promises returned by `libnpmhook` commands will use this Promise class instead. For example: `{Promise: require('bluebird')}` + +#### <a name="add"></a> `> hooks.add(name, endpoint, secret, [opts]) -> Promise` + +`name` is the name of the package, org, or user/org scope to watch. The type is +determined by the name syntax: `'@foo/bar'` and `'foo'` are treated as packages, +`@foo` is treated as a scope, and `~user` is treated as an org name or scope. +Each type will attach to different events. + +The `endpoint` should be a fully-qualified http URL for the endpoint the hook +will send its payload to when it fires. `secret` is a shared secret that the +hook will send to that endpoint to verify that it's actually coming from the +registry hook. + +The returned Promise resolves to the full hook object that was created, +including its generated `id`. + +See also: [`POST +/v1/hooks/hook`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#post-v1hookshook) + +##### Example ```javascript +await hooks.add('~zkat', 'https://zkat.tech/api/added', 'supersekrit', { + token: 'myregistrytoken', + otp: '694207' +}) + +=> + +{ id: '16f7xoal', + username: 'zkat', + name: 'zkat', + endpoint: 'https://zkat.tech/api/added', + secret: 'supersekrit', + type: 'owner', + created: '2018-08-21T20:05:25.125Z', + updated: '2018-08-21T20:05:25.125Z', + deleted: false, + delivered: false, + last_delivery: null, + response_code: 0, + status: 'active' } ``` -### Features +#### <a name="find"></a> `> hooks.find(id, [opts]) -> Promise` -### API +Returns the hook identified by `id`. + +The returned Promise resolves to the full hook object that was found, or error +with `err.code` of `'E404'` if it didn't exist. + +See also: [`GET +/v1/hooks/hook/:id`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#get-v1hookshookid) + +##### Example + +```javascript +await hooks.find('16f7xoal', {token: 'myregistrytoken'}) + +=> + +{ id: '16f7xoal', + username: 'zkat', + name: 'zkat', + endpoint: 'https://zkat.tech/api/added', + secret: 'supersekrit', + type: 'owner', + created: '2018-08-21T20:05:25.125Z', + updated: '2018-08-21T20:05:25.125Z', + deleted: false, + delivered: false, + last_delivery: null, + response_code: 0, + status: 'active' } +``` + +#### <a name="rm"></a> `> hooks.rm(id, [opts]) -> Promise` + +Removes the hook identified by `id`. + +The returned Promise resolves to the full hook object that was removed, if it +existed, or `null` if no such hook was there (instead of erroring). + +See also: [`DELETE +/v1/hooks/hook/:id`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#delete-v1hookshookid) + +##### Example + +```javascript +await hooks.rm('16f7xoal', { + token: 'myregistrytoken', + otp: '694207' +}) + +=> + +{ id: '16f7xoal', + username: 'zkat', + name: 'zkat', + endpoint: 'https://zkat.tech/api/added', + secret: 'supersekrit', + type: 'owner', + created: '2018-08-21T20:05:25.125Z', + updated: '2018-08-21T20:05:25.125Z', + deleted: true, + delivered: false, + last_delivery: null, + response_code: 0, + status: 'active' } + +// Repeat it... +await hooks.rm('16f7xoal', { + token: 'myregistrytoken', + otp: '694207' +}) + +=> null +``` + +#### <a name="update"></a> `> hooks.update(id, endpoint, secret, [opts]) -> Promise` + +The `id` should be a hook ID from a previously-created hook. + +The `endpoint` should be a fully-qualified http URL for the endpoint the hook +will send its payload to when it fires. `secret` is a shared secret that the +hook will send to that endpoint to verify that it's actually coming from the +registry hook. + +The returned Promise resolves to the full hook object that was updated, if it +existed. Otherwise, it will error with an `'E404'` error code. + +See also: [`PUT +/v1/hooks/hook/:id`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#put-v1hookshookid) + +##### Example + +```javascript +await hooks.update('16fxoal', 'https://zkat.tech/api/other', 'newsekrit', { + token: 'myregistrytoken', + otp: '694207' +}) + +=> + +{ id: '16f7xoal', + username: 'zkat', + name: 'zkat', + endpoint: 'https://zkat.tech/api/other', + secret: 'newsekrit', + type: 'owner', + created: '2018-08-21T20:05:25.125Z', + updated: '2018-08-21T20:14:41.964Z', + deleted: false, + delivered: false, + last_delivery: null, + response_code: 0, + status: 'active' } +``` + +#### <a name="ls"></a> `> hooks.ls([opts]) -> Promise` + +Resolves to an array of hook objects associated with the account you're +authenticated as. + +Results can be further filtered with three values that can be passed in through +`opts`: + +* `opts.package` - filter results by package name +* `opts.limit` - maximum number of hooks to return +* `opts.offset` - pagination offset for results (use with `opts.limit`) + +See also: + * [`hooks.ls.stream()`](#ls-stream) + * [`GET +/v1/hooks`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#get-v1hooks) + +##### Example + +```javascript +await hooks.ls({token: 'myregistrytoken'}) + +=> +[ + { id: '16f7xoal', ... }, + { id: 'wnyf98a1', ... }, + ... +] +``` + +#### <a name="ls-stream"></a> `> hooks.ls.stream([opts]) -> Stream` + +Returns a stream of hook objects associated with the account you're +authenticated as. The returned stream is a valid `Symbol.asyncIterator` on +`node@>=10`. + +Results can be further filtered with three values that can be passed in through +`opts`: + +* `opts.package` - filter results by package name +* `opts.limit` - maximum number of hooks to return +* `opts.offset` - pagination offset for results (use with `opts.limit`) + +See also: + * [`hooks.ls()`](#ls) + * [`GET +/v1/hooks`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#get-v1hooks) + +##### Example + +```javascript +for await (let hook of hooks.ls.stream({token: 'myregistrytoken'})) { + console.log('found hook:', hook.id) +} + +=> +// outputs: +// found hook: 16f7xoal +// found hook: wnyf98a1 +``` diff --git a/node_modules/libnpmhook/config.js b/node_modules/libnpmhook/config.js deleted file mode 100644 index 864e1ede6..000000000 --- a/node_modules/libnpmhook/config.js +++ /dev/null @@ -1,13 +0,0 @@ -'use strict' - -const pudding = require('figgy-pudding') - -const NpmHooksConfig = pudding() - -module.exports = config -function config (opts) { - return NpmHooksConfig.apply( - null, - [opts, opts.config].concat([].slice.call(arguments, 1)) - ) -} diff --git a/node_modules/libnpmhook/index.js b/node_modules/libnpmhook/index.js index b59ff842e..b48929495 100644 --- a/node_modules/libnpmhook/index.js +++ b/node_modules/libnpmhook/index.js @@ -1,41 +1,80 @@ 'use strict' -const config = require('./config') const fetch = require('npm-registry-fetch') +const figgyPudding = require('figgy-pudding') +const getStream = require('get-stream') +const validate = require('aproba') -module.exports = { - add (name, endpoint, secret, opts) { - let type = 'package' - if (name && name.match(/^@[^/]+$/)) { - type = 'scope' - } - if (name && name[0] === '~') { - type = 'owner' - name = name.substr(1) - } +const HooksConfig = figgyPudding({ + package: {}, + limit: {}, + offset: {}, + Promise: {default: () => Promise} +}) - opts = config({ - method: 'POST', - body: { type, name, endpoint, secret } - }, opts) - return fetch.json('/-/npm/v1/hooks/hook', opts) - }, - - rm (id, opts) { - return fetch.json(`/-/npm/v1/hooks/hook/${encodeURIComponent(id)}`, config({ - method: 'DELETE' - }, opts)) - }, - - ls (pkg, opts) { - return fetch.json('/-/npm/v1/hooks', config({query: pkg && {package: pkg}}, opts)) - .then(json => json.objects) - }, - - update (id, endpoint, secret, opts) { - return fetch.json(`/-/npm/v1/hooks/hook/${encodeURIComponent(id)}`, config({ - method: 'PUT', - body: {endpoint, secret} - }, opts)) +const eu = encodeURIComponent +const cmd = module.exports = {} +cmd.add = (name, endpoint, secret, opts) => { + opts = HooksConfig(opts) + validate('SSSO', [name, endpoint, secret, opts]) + let type = 'package' + if (name.match(/^@[^/]+$/)) { + type = 'scope' } + if (name[0] === '~') { + type = 'owner' + name = name.substr(1) + } + return fetch.json('/-/npm/v1/hooks/hook', opts.concat({ + method: 'POST', + body: { type, name, endpoint, secret } + })) +} + +cmd.rm = (id, opts) => { + opts = HooksConfig(opts) + validate('SO', [id, opts]) + return fetch.json(`/-/npm/v1/hooks/hook/${eu(id)}`, opts.concat({ + method: 'DELETE' + }, opts)).catch(err => { + if (err.code === 'E404') { + return null + } else { + throw err + } + }) +} + +cmd.update = (id, endpoint, secret, opts) => { + opts = HooksConfig(opts) + validate('SSSO', [id, endpoint, secret, opts]) + return fetch.json(`/-/npm/v1/hooks/hook/${eu(id)}`, opts.concat({ + method: 'PUT', + body: {endpoint, secret} + }, opts)) +} + +cmd.find = (id, opts) => { + opts = HooksConfig(opts) + validate('SO', [id, opts]) + return fetch.json(`/-/npm/v1/hooks/hook/${eu(id)}`, opts) +} + +cmd.ls = (opts) => { + return getStream.array(cmd.ls.stream(opts)) +} + +cmd.ls.stream = (opts) => { + opts = HooksConfig(opts) + const {package: pkg, limit, offset} = opts + validate('S|Z', [pkg]) + validate('N|Z', [limit]) + validate('N|Z', [offset]) + return fetch.json.stream('/-/npm/v1/hooks', 'objects.*', opts.concat({ + query: { + package: pkg, + limit, + offset + } + })) } diff --git a/node_modules/libnpmhook/package.json b/node_modules/libnpmhook/package.json index 84839475b..ebcc752a3 100644 --- a/node_modules/libnpmhook/package.json +++ b/node_modules/libnpmhook/package.json @@ -1,28 +1,28 @@ { - "_from": "libnpmhook@4.0.1", - "_id": "libnpmhook@4.0.1", + "_from": "libnpmhook@5.0.2", + "_id": "libnpmhook@5.0.2", "_inBundle": false, - "_integrity": "sha512-3qqpfqvBD1712WA6iGe0stkG40WwAeoWcujA6BlC0Be1JArQbqwabnEnZ0CRcD05Tf1fPYJYdCbSfcfedEJCOg==", + "_integrity": "sha512-vLenmdFWhRfnnZiNFPNMog6CK7Ujofy2TWiM2CrpZUjBRIhHkJeDaAbJdYCT6W4lcHtyrJR8yXW8KFyq6UAp1g==", "_location": "/libnpmhook", "_phantomChildren": {}, "_requested": { "type": "version", "registry": true, - "raw": "libnpmhook@4.0.1", + "raw": "libnpmhook@5.0.2", "name": "libnpmhook", "escapedName": "libnpmhook", - "rawSpec": "4.0.1", + "rawSpec": "5.0.2", "saveSpec": null, - "fetchSpec": "4.0.1" + "fetchSpec": "5.0.2" }, "_requiredBy": [ "#USER", "/" ], - "_resolved": "https://registry.npmjs.org/libnpmhook/-/libnpmhook-4.0.1.tgz", - "_shasum": "63641654de772cbeb96a88527a7fd5456ec3c2d7", - "_spec": "libnpmhook@4.0.1", - "_where": "/Users/zkat/Documents/code/work/npm", + "_resolved": "https://registry.npmjs.org/libnpmhook/-/libnpmhook-5.0.2.tgz", + "_shasum": "d12817b0fb893f36f1d5be20017f2aea25825d94", + "_spec": "libnpmhook@5.0.2", + "_where": "/Users/aeschright/code/cli", "author": { "name": "Kat Marchán", "email": "kzm@sykosomatic.org" @@ -32,16 +32,18 @@ }, "bundleDependencies": false, "dependencies": { - "figgy-pudding": "^3.1.0", - "npm-registry-fetch": "^3.0.0" + "aproba": "^2.0.0", + "figgy-pudding": "^3.4.1", + "get-stream": "^4.0.0", + "npm-registry-fetch": "^3.8.0" }, "deprecated": false, "description": "programmatic API for managing npm registry hooks", "devDependencies": { - "nock": "^9.2.3", + "nock": "^9.6.1", "standard": "^11.0.1", - "standard-version": "^4.3.0", - "tap": "^11.1.3", + "standard-version": "^4.4.0", + "tap": "^12.0.1", "weallbehave": "^1.2.0", "weallcontribute": "^1.0.8" }, @@ -68,9 +70,9 @@ "prerelease": "npm t", "pretest": "standard", "release": "standard-version -s", - "test": "tap -J --coverage test/*.js", + "test": "tap -J --100 --coverage test/*.js", "update-coc": "weallbehave -o . && git add CODE_OF_CONDUCT.md && git commit -m 'docs(coc): updated CODE_OF_CONDUCT.md'", "update-contrib": "weallcontribute -o . && git add CONTRIBUTING.md && git commit -m 'docs(contributing): updated CONTRIBUTING.md'" }, - "version": "4.0.1" + "version": "5.0.2" } |