{"id":16935850,"url":"https://github.com/romainlanz/adonis-mercure","last_synced_at":"2025-03-22T12:31:52.035Z","repository":{"id":46097353,"uuid":"507094920","full_name":"RomainLanz/adonis-mercure","owner":"RomainLanz","description":"Mercure Provider - Real-time Made Easy","archived":false,"fork":false,"pushed_at":"2022-07-17T14:27:17.000Z","size":9,"stargazers_count":32,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T11:05:58.601Z","etag":null,"topics":["adonisjs","mercure","real-time","server-sent-events"],"latest_commit_sha":null,"homepage":"","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/RomainLanz.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2022-06-24T17:36:46.000Z","updated_at":"2023-12-17T16:17:39.000Z","dependencies_parsed_at":"2022-09-26T21:10:49.519Z","dependency_job_id":null,"html_url":"https://github.com/RomainLanz/adonis-mercure","commit_stats":null,"previous_names":["setten-io/adonis-mercure"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomainLanz%2Fadonis-mercure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomainLanz%2Fadonis-mercure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomainLanz%2Fadonis-mercure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomainLanz%2Fadonis-mercure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RomainLanz","download_url":"https://codeload.github.com/RomainLanz/adonis-mercure/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244874592,"owners_count":20524578,"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":["adonisjs","mercure","real-time","server-sent-events"],"created_at":"2024-10-13T20:55:30.144Z","updated_at":"2025-03-22T12:31:51.781Z","avatar_url":"https://github.com/RomainLanz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/2793951/179392918-bcfe5b41-44b3-4c9c-b661-9a14d995901b.png\" alt=\"@setten/mercure\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@setten/mercure\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@setten/mercure.svg?style=flat-square\" alt=\"Download\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@setten/mercure\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@setten/mercure.svg?style=flat-square\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/@setten/mercure.svg?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n`@setten/mercure` is a [Mercure](https://mercure.rocks) client for [AdonisJS](https://adonisjs.com/).\n\nMercure allows you to use [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) to push data to your clients using Http.\n\n\u003e **Note**\n\u003e\n\u003e You must have a [Mercure Hub instance running](https://mercure.rocks/docs/hub/install).\n---\n\n## Getting Started\n\nThis package is available in the npm registry.\n\n```bash\nnpm install @setten/mercure\n```\n\nNext, configure the package by running the following command.\n\n```bash\nnode ace configure @setten/mercure\n```\n\nand... Voilà!\n\n### Configuration\n\nYou have to configure the package before you can use it.\nThe configuration is stored in the `config/mercure.ts` file.\n\n* `endpoint`: The endpoint of the Mercure Hub.\n* `adminToken`: The JWT created to authenticate as an admin of the Mercure Hub.\n* `jwt.alg`: The algorithm used to sign the JWT - should correlate to Mercure Hub configuration.\n* `jwt.secret`: The secret used to sign the JWT - should correlate to Mercure Hub configuration.\n\nNote that the `adminToken` must be generated using the same `alg` and `secret` used in the Mercure Hub with the following payload.\n\n```json\n{\n  \"mercure\": {\n    \"publish\": [\n      \"*\"\n    ]\n  }\n}\n```\n\nFor example, given the secret of `ChangeMe` and the algorithm of `HS256`, the JWT would be:\n\n```\neyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.mx2ROlYlE1rp7udoDy-WCdnpLdPuKWzDxoBJXGMK4OE\n```\n\n## Usage\n\nThe Mercure Provider gives you access to two classes.\n\n* `Update`: This class is used to publish updates to the hub.\n* `Token`: This class is used to generate a token for authentication.\n\nYou can easily send an update to the hub using the `Update.send` method.\n\n```ts\nimport { Update } from '@ioc:Setten/Mercure';\n\nUpdate.send('/users/1', { ... });\n```\n\nThe `send` method takes three arguments.\n\n  * `topic`: The topic to publish the update to.\n  * `data`: The data to publish.\n  * `isPrivate`: Whether the update is private or not.\n\nMore information on the topic and data arguments can be found in the [Mercure documentation](https://mercure.rocks/spec#publication).\n\n### Frontend\n\nThe frontend can listen to changes using the standard [`EventSource` web interface](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).\n\n```js\nconst url = new URL(/*  Mercure Endpoint */)\nurl.searchParams.append('topic', '/users/1')\n\nconst eventSource = new EventSource(url)\neventSource.onmessage = (event) =\u003e {\n  console.log(event.data)\n}\n```\n\nMore information on the topic can be found in the [Mercure documentation](https://mercure.rocks/docs/getting-started).\n\n### Authentication\n\nYou may want to send private messages. To do so, you need to set the update as private using the third argument of the `Update.send` method, and authenticate the client using a JWT stored in a cookie.\n\nYou can generate the JWT using the `Token` class.\n\n```ts\nimport { Token } from '@ioc:Setten/Mercure';\n\n// Generating the token allowing the user to listen on private events\n// send to `/users/1`.\nconst token = await Token.generate({\n  subscribe: ['/users/1'],\n})\n\n// Adding the token in a cookie name `mercureAuthorization`.\nresponse.append(\n  'set-cookie',\n  `mercureAuthorization=${token}; Domain=.setten.io; Path=/.well-known/mercure; HttpOnly`\n)\n```\n\nThe cookie must be named `mercureAuthorization` and must be not encoded by AdonisJS (you cannot use `response.cookie()` at the moment for that reason).\n\nNote that the Mercure Hub must run on the same domain as the client since cookies cannot be shared cross-domain.\n\nOnce done, you have to change your client's connection to use cookies.\n\n```js\nconst eventSource = new EventSource(url, { withCredentials: true })\n```\n\nMore information on the topic can be found in the [Mercure documentation](https://mercure.rocks/spec#authorization).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromainlanz%2Fadonis-mercure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromainlanz%2Fadonis-mercure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromainlanz%2Fadonis-mercure/lists"}