{"id":25648767,"url":"https://github.com/vandie/webmention-handler","last_synced_at":"2025-04-15T16:34:36.148Z","repository":{"id":41896389,"uuid":"510136279","full_name":"vandie/webmention-handler","owner":"vandie","description":"A handler for web mentions","archived":false,"fork":false,"pushed_at":"2023-11-11T18:27:03.000Z","size":192,"stargazers_count":17,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-23T23:45:41.637Z","etag":null,"topics":["indieweb","javascript","nodejs","nodejs-modules","typescript","typescript-definitions","webmention","webmentions"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/webmention-handler","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vandie.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["vandie"]}},"created_at":"2022-07-03T21:11:19.000Z","updated_at":"2025-01-20T07:09:33.000Z","dependencies_parsed_at":"2024-06-21T20:21:02.877Z","dependency_job_id":"1893a4c1-294a-4177-87d7-f3ae35f785e5","html_url":"https://github.com/vandie/webmention-handler","commit_stats":{"total_commits":29,"total_committers":1,"mean_commits":29.0,"dds":0.0,"last_synced_commit":"b6b51f7c077833f580a0c2e0716b3a0d0cd5f346"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vandie%2Fwebmention-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vandie%2Fwebmention-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vandie%2Fwebmention-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vandie%2Fwebmention-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vandie","download_url":"https://codeload.github.com/vandie/webmention-handler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249108932,"owners_count":21214089,"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":["indieweb","javascript","nodejs","nodejs-modules","typescript","typescript-definitions","webmention","webmentions"],"created_at":"2025-02-23T13:19:10.013Z","updated_at":"2025-04-15T16:34:36.129Z","avatar_url":"https://github.com/vandie.png","language":"TypeScript","funding_links":["https://github.com/sponsors/vandie"],"categories":[],"sub_categories":[],"readme":"# webmention-handler\n\n`webmention-handler` is a Node.js handler for the 2017 W3C Recomendation Spec of [Webmention](https://www.w3.org/TR/webmention/). It is written in TypeScript and includes full type definitions.\n\n[![CI Pipeline](https://github.com/vandie/webmention-handler/actions/workflows/ci.yml/badge.svg)](https://github.com/vandie/webmention-handler/actions/workflows/ci.yml)\n\n## What is a webmention\n\nA Webmention is a notification that one URL links to another. For example, Alice writes an interesting post on her blog. Bob then writes a response to her post on his own site, linking back to Alice's original post. Bob's publishing software sends a Webmention to Alice notifying that her article was replied to, and Alice's software can show that reply as a comment, like, repost or other relevant type on the original post.\n\n## Installation\n\nInstall with NPM:\n\n```bash\nnpm install webmention-handler --save\n```\n\n## Setup\n\nTo begin with, you should create a webmention storage instance. While there is a default implementation, it is not fit for production environments and is included for demonstration purposes only. To create instance of the example storage class, the following code can be used. \n\n```typescript\nimport { LocalWebMentionStorage } from 'webmention-handler';\n\nconst storage = new LocalWebMentionStorage();\n```\n\nDifferent storage implementations may take different parameters so please read the documentation for the chosen implementation. With that, however, you can create an instance of your the webmention handler.\n\n```typescript\nimport { WebMentionHandler } from 'webmention-handler';\n\nconst options = {\n  supportedHosts: ['localhost'] // The domain of any websites this handler should support\n  storageHandler: storage, // Your storage handler instance\n  requiredProtocol: 'https' // Not required, but highly recommended to only allow https mentions\n};\n\nexport const webMentionHandler = new WebMentionHandler(options)\n```\n\n## Usage\n\nExample Express endpoint to accept webmentions:\n\n```typescript\n// Regular Express setup\nimport express from 'express';\nimport bodyParser from 'body-parser';\nimport webMentionHandler from 'path/to/your/webMentionHandler/file.ts';\n\nconst app = express();\n\n// Webmentions require the ability to parse Form encoded data from a post request.\napp.use(bodyParser.urlencoded({ extended: true }));\n\napp.post('/webmentions', async function(req, res) {\n  try {\n    // Pass the source and target of the request to the handler.\n    // No need to run validation on it as this will be validated by the handler.\n    const recommendedResponse = await webMentionHandler.addPendingMention(req.body.source, req.body.target);\n\n    // The response code is dictated by the specification but not enforced by the handler\n    // in case you need to action your own out-of-spec actions. The response body should be human-readable\n    res.status(recommendedResponse.code).send('accepted');\n  } catch (error) {\n    res.status(400).send(error.message);\n  }\n});\n\n// Open your Express server\napp.listen(8080);\n```\n\nOnce your endpoint is set up, you can set up a regular job with the following code to convert pending mentionNotifications into mention objects in your database that you can use.\n\n```typescript\nimport webMentionHandler from 'path/to/your/webMentionHandler/file.ts';\n\nsetInterval(() =\u003e webMentionHandler.processPendingMentions(), 300000);\n```\n\nI'd highly recommend processing mentions in an ephemeral cloud function, rather than a `setInterval` on your main Node application, so that you don't accidentally leak the IP of your server to third parties. Especially if you aren't using the `whitelist` option for source hosts.\n\nYou can now grab the type of mention that you need for any given page.\n\n```typescript\nimport webMentionHandler from 'path/to/your/webMentionHandler/file.ts';\n\nconst likes = webMentionHandler.getMentionsForPage('/blog/example-post', 'like');\nconst replies = webMentionHandler.getMentionsForPage('/blog/example-post', 'reply');\n```\n\n## Writing custom storage handlers\n\nAn example storage handler can be found in the [local storage class](./src/classes/local-web-mention-storage.class.ts). It implements the [IWebMentionStorage](./src/interfaces/web-mention-storage.interface.ts) as any other storage handler should also. This ensures compatibility between storage handlers and allows users to switch between different storage handlers at will without updating the rest of their codebase.\n\n### Functions\n\nThe following functions must be implemented in your storage handler class if you are not using TypesScript.\n\n| Function | Arguments | Returns | Explanation |\n| -------- | --------- | ------- | ----------- |\n| `addPendingMention` | mention: [SimpleMention](./src/types/simple-mention.type.ts) | Promise\u003c[SimpleMention](./src/types/simple-mention.type.ts)\u003e | Allows the web mention handler to add a new pending mention that needs to be handled |\n| `getNextPendingMentions` | N/A | Promise\u003c[SimpleMention](./src/types/simple-mention.type.ts)[]\u003e | Fetches a number of pending mentions to be bulk processed. Any configured limits on the number of pending mentions to fetch should be set in the constructor via an options object rather than passed in to this function directly. |\n| `getMentionsForPage` | page: `string`, type?: `string` | Promise\u003c[Mention](./src/types/mention.type.ts)[]\u003e | Gets mentions based on a given target. Has an optional `type` parameter that allows mentions to be filtered on type. eg. Only Comments or Likes` |\n| `storeMentionForPage` | page: `string`, mention: [Mention](./src/types/mention.type.ts) | Promise\u003c[Mention](./src/types/mention.type.ts)\u003e | This function will store a mention on the given target. If you need to access the type of the mention, you can find that on the `mention.type` property. |\n| `deleteMention` | mention: [SimpleMention](./src/types/simple-mention.type.ts) | Promise\u003c`null`\u003e | This function should delete any processed mentions for a given target from a given source. It should always return `null` and should not error in the event that no mentions are found. |\n\n## Available storage libraries\n\n| Database/storage engine | GitHub Repo | NPM package |\n| ----------------------- | ----------- | ----------- |\n| MongoDB | [vandie/webmention-handler-mongo](https://github.com/vandie/webmention-handler-mongo) | [webmention-handler-mongodb](https://www.npmjs.com/package/webmention-handler-mongodb) |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvandie%2Fwebmention-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvandie%2Fwebmention-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvandie%2Fwebmention-handler/lists"}