{"id":15290332,"url":"https://github.com/npm/libnpmhook","last_synced_at":"2025-10-07T03:32:59.344Z","repository":{"id":46913862,"uuid":"125480737","full_name":"npm/libnpmhook","owner":"npm","description":"programmatic registry hooks API","archived":true,"fork":false,"pushed_at":"2022-01-18T21:30:01.000Z","size":682,"stargazers_count":8,"open_issues_count":0,"forks_count":6,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-10-01T16:07:08.117Z","etag":null,"topics":["npm-cli"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-16T07:37:28.000Z","updated_at":"2023-01-28T03:56:19.000Z","dependencies_parsed_at":"2022-09-26T18:41:44.672Z","dependency_job_id":null,"html_url":"https://github.com/npm/libnpmhook","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Flibnpmhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Flibnpmhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Flibnpmhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Flibnpmhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npm","download_url":"https://codeload.github.com/npm/libnpmhook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235586092,"owners_count":19014028,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["npm-cli"],"created_at":"2024-09-30T16:07:09.633Z","updated_at":"2025-10-07T03:32:54.030Z","avatar_url":"https://github.com/npm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# We've Moved! 🚚\nThe code for this repo is now a workspace in the npm CLI repo.\n\n[github.com/npm/cli](https://github.com/npm/cli)\n\nYou can find the workspace in /workspaces/libnpmhook\n\nPlease file bugs and feature requests as issues on the CLI and tag the issue with \"ws:libnpmhook\".\n\n[github.com/npm/cli/issues](https://github.com/npm/cli)\n\n# libnpmhook\n\n[![npm version](https://img.shields.io/npm/v/libnpmhook.svg)](https://npm.im/libnpmhook)\n[![license](https://img.shields.io/npm/l/libnpmhook.svg)](https://npm.im/libnpmhook)\n[![Coverage Status](https://coveralls.io/repos/github/npm/libnpmhook/badge.svg?branch=latest)](https://coveralls.io/github/npm/libnpmhook?branch=latest)\n\n[`libnpmhook`](https://github.com/npm/libnpmhook) is a Node.js library for\nprogrammatically managing the npm registry's server-side hooks.\n\nFor a more general introduction to managing hooks, see [the introductory blog\npost](https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm).\n\n## Table of Contents\n\n* [Example](#example)\n* [Install](#install)\n* [Contributing](#contributing)\n* [API](#api)\n  * [hook opts](#opts)\n  * [`add()`](#add)\n  * [`rm()`](#rm)\n  * [`ls()`](#ls)\n  * [`ls.stream()`](#ls-stream)\n  * [`update()`](#update)\n\n## Example\n\n```js\nconst hooks = require('libnpmhook')\n\nconsole.log(await hooks.ls('mypkg', {token: 'deadbeef'}))\n// array of hook objects on `mypkg`.\n```\n\n## Install\n\n`$ npm install libnpmhook`\n\n### API\n\n#### \u003ca name=\"opts\"\u003e\u003c/a\u003e `opts` for `libnpmhook` commands\n\n`libnpmhook` uses [`npm-registry-fetch`](https://npm.im/npm-registry-fetch).\nAll options are passed through directly to that library, so please refer to [its\nown `opts`\ndocumentation](https://www.npmjs.com/package/npm-registry-fetch#fetch-options)\nfor options that can be passed in.\n\nA couple of options of note for those in a hurry:\n\n* `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.\n* `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: \u003c2fa token\u003e}`\n\n#### \u003ca name=\"add\"\u003e\u003c/a\u003e `\u003e hooks.add(name, endpoint, secret, [opts]) -\u003e Promise`\n\n`name` is the name of the package, org, or user/org scope to watch. The type is\ndetermined by the name syntax: `'@foo/bar'` and `'foo'` are treated as packages,\n`@foo` is treated as a scope, and `~user` is treated as an org name or scope.\nEach type will attach to different events.\n\nThe `endpoint` should be a fully-qualified http URL for the endpoint the hook\nwill send its payload to when it fires. `secret` is a shared secret that the\nhook will send to that endpoint to verify that it's actually coming from the\nregistry hook.\n\nThe returned Promise resolves to the full hook object that was created,\nincluding its generated `id`.\n\nSee also: [`POST\n/v1/hooks/hook`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#post-v1hookshook)\n\n##### Example\n\n```javascript\nawait hooks.add('~zkat', 'https://example.com/api/added', 'supersekrit', {\n  token: 'myregistrytoken',\n  otp: '694207'\n})\n\n=\u003e\n\n{ id: '16f7xoal',\n  username: 'zkat',\n  name: 'zkat',\n  endpoint: 'https://example.com/api/added',\n  secret: 'supersekrit',\n  type: 'owner',\n  created: '2018-08-21T20:05:25.125Z',\n  updated: '2018-08-21T20:05:25.125Z',\n  deleted: false,\n  delivered: false,\n  last_delivery: null,\n  response_code: 0,\n  status: 'active' }\n```\n\n#### \u003ca name=\"find\"\u003e\u003c/a\u003e `\u003e hooks.find(id, [opts]) -\u003e Promise`\n\nReturns the hook identified by `id`.\n\nThe returned Promise resolves to the full hook object that was found, or error\nwith `err.code` of `'E404'` if it didn't exist.\n\nSee also: [`GET\n/v1/hooks/hook/:id`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#get-v1hookshookid)\n\n##### Example\n\n```javascript\nawait hooks.find('16f7xoal', {token: 'myregistrytoken'})\n\n=\u003e\n\n{ id: '16f7xoal',\n  username: 'zkat',\n  name: 'zkat',\n  endpoint: 'https://example.com/api/added',\n  secret: 'supersekrit',\n  type: 'owner',\n  created: '2018-08-21T20:05:25.125Z',\n  updated: '2018-08-21T20:05:25.125Z',\n  deleted: false,\n  delivered: false,\n  last_delivery: null,\n  response_code: 0,\n  status: 'active' }\n```\n\n#### \u003ca name=\"rm\"\u003e\u003c/a\u003e `\u003e hooks.rm(id, [opts]) -\u003e Promise`\n\nRemoves the hook identified by `id`.\n\nThe returned Promise resolves to the full hook object that was removed, if it\nexisted, or `null` if no such hook was there (instead of erroring).\n\nSee also: [`DELETE\n/v1/hooks/hook/:id`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#delete-v1hookshookid)\n\n##### Example\n\n```javascript\nawait hooks.rm('16f7xoal', {\n  token: 'myregistrytoken',\n  otp: '694207'\n})\n\n=\u003e\n\n{ id: '16f7xoal',\n  username: 'zkat',\n  name: 'zkat',\n  endpoint: 'https://example.com/api/added',\n  secret: 'supersekrit',\n  type: 'owner',\n  created: '2018-08-21T20:05:25.125Z',\n  updated: '2018-08-21T20:05:25.125Z',\n  deleted: true,\n  delivered: false,\n  last_delivery: null,\n  response_code: 0,\n  status: 'active' }\n\n// Repeat it...\nawait hooks.rm('16f7xoal', {\n  token: 'myregistrytoken',\n  otp: '694207'\n})\n\n=\u003e null\n```\n\n#### \u003ca name=\"update\"\u003e\u003c/a\u003e `\u003e hooks.update(id, endpoint, secret, [opts]) -\u003e Promise`\n\nThe `id` should be a hook ID from a previously-created hook.\n\nThe `endpoint` should be a fully-qualified http URL for the endpoint the hook\nwill send its payload to when it fires. `secret` is a shared secret that the\nhook will send to that endpoint to verify that it's actually coming from the\nregistry hook.\n\nThe returned Promise resolves to the full hook object that was updated, if it\nexisted. Otherwise, it will error with an `'E404'` error code.\n\nSee also: [`PUT\n/v1/hooks/hook/:id`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#put-v1hookshookid)\n\n##### Example\n\n```javascript\nawait hooks.update('16fxoal', 'https://example.com/api/other', 'newsekrit', {\n  token: 'myregistrytoken',\n  otp: '694207'\n})\n\n=\u003e\n\n{ id: '16f7xoal',\n  username: 'zkat',\n  name: 'zkat',\n  endpoint: 'https://example.com/api/other',\n  secret: 'newsekrit',\n  type: 'owner',\n  created: '2018-08-21T20:05:25.125Z',\n  updated: '2018-08-21T20:14:41.964Z',\n  deleted: false,\n  delivered: false,\n  last_delivery: null,\n  response_code: 0,\n  status: 'active' }\n```\n\n#### \u003ca name=\"ls\"\u003e\u003c/a\u003e `\u003e hooks.ls([opts]) -\u003e Promise`\n\nResolves to an array of hook objects associated with the account you're\nauthenticated as.\n\nResults can be further filtered with three values that can be passed in through\n`opts`:\n\n* `opts.package` - filter results by package name\n* `opts.limit` - maximum number of hooks to return\n* `opts.offset` - pagination offset for results (use with `opts.limit`)\n\nSee also:\n  * [`hooks.ls.stream()`](#ls-stream)\n  * [`GET\n/v1/hooks`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#get-v1hooks)\n\n##### Example\n\n```javascript\nawait hooks.ls({token: 'myregistrytoken'})\n\n=\u003e\n[\n  { id: '16f7xoal', ... },\n  { id: 'wnyf98a1', ... },\n  ...\n]\n```\n\n#### \u003ca name=\"ls-stream\"\u003e\u003c/a\u003e `\u003e hooks.ls.stream([opts]) -\u003e Stream`\n\nReturns a stream of hook objects associated with the account you're\nauthenticated as. The returned stream is a valid `Symbol.asyncIterator` on\n`node@\u003e=10`.\n\nResults can be further filtered with three values that can be passed in through\n`opts`:\n\n* `opts.package` - filter results by package name\n* `opts.limit` - maximum number of hooks to return\n* `opts.offset` - pagination offset for results (use with `opts.limit`)\n\nSee also:\n  * [`hooks.ls()`](#ls)\n  * [`GET\n/v1/hooks`](https://github.com/npm/registry/blob/master/docs/hooks/endpoints.md#get-v1hooks)\n\n##### Example\n\n```javascript\nfor await (let hook of hooks.ls.stream({token: 'myregistrytoken'})) {\n  console.log('found hook:', hook.id)\n}\n\n=\u003e\n// outputs:\n// found hook: 16f7xoal\n// found hook: wnyf98a1\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Flibnpmhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpm%2Flibnpmhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Flibnpmhook/lists"}