@mdsiha369/adonis-mercure 2.1.2

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mdsiha/adonis-mercure/main/assets/logo.svg" width="100" alt="adonis-mercure" />
+</p>
+
+<h1 align="center">@mdsiha369/adonis-mercure</h1>
+
+<p align="center">
+  <a href="https://github.com/mdsiha/adonis-mercure/actions/workflows/test.yml"><img src="https://github.com/mdsiha/adonis-mercure/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
+  <a href="https://www.npmjs.com/package/@mdsiha369/adonis-mercure"><img src="https://img.shields.io/npm/dm/@mdsiha369/adonis-mercure.svg?style=flat-square" alt="Downloads"></a>
+  <a href="https://www.npmjs.com/package/@mdsiha369/adonis-mercure"><img src="https://img.shields.io/npm/v/@mdsiha369/adonis-mercure.svg?style=flat-square" alt="Version"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/npm/l/@mdsiha369/adonis-mercure.svg?style=flat-square" alt="License"></a>
+</p>
+
+<p align="center">
+  AdonisJS v6 package to publish real-time updates via a <a href="https://mercure.rocks">Mercure Hub</a> (SSE)
+</p>
+
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Publish an update](#publish-an-update)
+  - [Multiple topics](#multiple-topics)
+  - [Private updates](#private-updates)
+  - [SSE options](#sse-options-id-type-retry)
+  - [Generate a subscriber token](#generate-a-subscriber-token)
+  - [Health check](#health-check)
+- [Testing](#testing)
+- [API Reference](#api-reference)
+- [Roadmap](#roadmap)
+- [License](#license)
+
+---
+
+## Requirements
+
+- AdonisJS **v6**
+- Node.js **>= 20.6.0**
+- A running [Mercure Hub](https://mercure.rocks/docs/hub/install)
+
+## Installation
+
+```bash
+npm install @mdsiha369/adonis-mercure
+node ace configure @mdsiha369/adonis-mercure
+```
+
+## Configuration
+
+After running `ace configure`, a `config/mercure.ts` file is created and your `.env` is updated automatically.
+
+```ts
+// config/mercure.ts
+import env from '#start/env'
+import { defineConfig } from '@mdsiha369/adonis-mercure'
+
+export default defineConfig({
+  endpoint: env.get('MERCURE_ENDPOINT'),
+  adminToken: env.get('MERCURE_ADMIN_JWT'),
+  jwt: {
+    alg: 'HS256',
+    secret: env.get('MERCURE_JWT_SECRET'),
+  },
+  // optional — default: 5000ms, set to 0 to disable
+  http: {
+    timeout: 5000,
+  },
+})
+```
+
+Set the following env variables in your `.env`:
+
+```env
+MERCURE_ENDPOINT=http://localhost:3000/.well-known/mercure
+MERCURE_ADMIN_JWT=<your-admin-jwt>
+MERCURE_JWT_SECRET=<your-jwt-secret>
+```
+
+> **Note:** The `adminToken` must be a JWT signed with your hub's secret and a `"publish": ["*"]` claim in the `mercure` field. See the [Mercure auth docs](https://mercure.rocks/docs/hub/auth) for details.
+
+---
+
+## Usage
+
+Import the service anywhere in your app:
+
+```ts
+import mercure from '@mdsiha369/adonis-mercure/services/main'
+```
+
+### Publish an update
+
+```ts
+await mercure.send('/orders/42', { status: 'shipped' })
+```
+
+### Multiple topics
+
+```ts
+await mercure.send(['/orders/42', '/notifications/user/1'], { status: 'shipped' })
+```
+
+### Private updates
+
+Private updates are only delivered to authenticated subscribers who hold a valid token for that topic.
+
+```ts
+// shorthand (backward compatible)
+await mercure.send('/orders/42', { status: 'shipped' }, true)
+
+// options object
+await mercure.send('/orders/42', { status: 'shipped' }, { private: true })
+```
+
+### SSE options (id, type, retry)
+
+```ts
+await mercure.send(
+  '/orders/42',
+  { status: 'shipped' },
+  {
+    id: 'msg-001', // event ID — enables reconnection recovery
+    type: 'order.shipped', // event type
+    retry: 5000, // client reconnect delay in ms
+    private: true,
+  }
+)
+```
+
+### Generate a subscriber token
+
+Use this to create JWT tokens for your frontend clients so they can subscribe to topics, including private ones.
+
+```ts
+// typed shorthand
+const token = await mercure.generateSubscribeToken(['/orders/42'])
+
+// or low-level
+const token = await mercure.generate({ subscribe: ['/orders/42'] })
+```
+
+Pass the token to your frontend:
+
+```ts
+const url = new URL('http://localhost:3000/.well-known/mercure')
+url.searchParams.append('topic', '/orders/42')
+
+const eventSource = new EventSource(url.toString(), {
+  headers: { Authorization: `Bearer ${token}` },
+})
+```
+
+### Health check
+
+```ts
+const isReachable = await mercure.ping() // true | false
+```
+
+---
+
+## Testing
+
+`FakeMercure` lets you test your application code without a real Mercure Hub.
+
+**Swap the container binding in your test setup:**
+
+```ts
+import { FakeMercure } from '@mdsiha369/adonis-mercure'
+
+// before your test
+app.container.swap('mercure', () => new FakeMercure())
+
+// after your test
+app.container.restore('mercure')
+```
+
+**Assert on what was sent:**
+
+```ts
+const fake = (await app.container.make('mercure')) as FakeMercure
+
+// assert a topic received a message
+fake.assertSent('/orders/42')
+
+// assert a topic received a specific payload
+fake.assertSent('/orders/42', { status: 'shipped' })
+
+// assert a topic was never sent to
+fake.assertNotSent('/admin/secret')
+
+// assert nothing was sent at all
+fake.assertNothingSent()
+
+// inspect all recorded messages
+const messages = fake.getSent()
+
+// reset between tests
+fake.clear()
+```
+
+---
+
+## API Reference
+
+### `send(topics, data?, options?)`
+
+Publishes an update to the Mercure Hub.
+
+| Parameter | Type                      | Default | Description                                            |
+| --------- | ------------------------- | ------- | ------------------------------------------------------ |
+| `topics`  | `string \| string[]`      | —       | Topic(s) to publish to                                 |
+| `data`    | `Record<string, unknown>` | `{}`    | Payload — serialized as JSON                           |
+| `options` | `boolean \| SendOptions`  | `false` | `true` for private (legacy), or a `SendOptions` object |
+
+**`SendOptions`**
+
+| Property  | Type      | Description                                    |
+| --------- | --------- | ---------------------------------------------- |
+| `private` | `boolean` | Restrict delivery to authenticated subscribers |
+| `id`      | `string`  | SSE event ID (enables reconnection recovery)   |
+| `type`    | `string`  | SSE event type                                 |
+| `retry`   | `number`  | Client reconnect delay in milliseconds         |
+
+Throws `MercurePublishError` if the hub returns a non-2xx response.  
+Throws `MercureTimeoutError` if the hub does not respond within the configured timeout.
+
+---
+
+### `generateSubscribeToken(topics)`
+
+Generates a JWT with `{ subscribe: topics }` for a frontend client.
+
+```ts
+const token = await mercure.generateSubscribeToken(['/chat/1', '/notifications/me'])
+```
+
+---
+
+### `generate(payload)`
+
+Low-level JWT generation. Wraps `payload` under the `mercure` claim.
+
+```ts
+const token = await mercure.generate({ subscribe: ['/chat/1'], publish: ['/chat/1'] })
+```
+
+---
+
+### `ping()`
+
+Returns `true` if the hub is reachable, `false` on network error or timeout.
+
+---
+
+## Roadmap
+
+Features planned for upcoming releases:
+
+- **`generatePublishToken(topics)`** — typed shorthand for publisher JWT tokens (symmetric to `generateSubscribeToken`)
+- **`sendBatch(messages[])`** — publish multiple updates in a single call
+- **Retry with backoff** — automatic retry on transient hub errors with configurable strategy
+- **Typed event classes** — define reusable event objects (`new OrderShippedEvent(id)`) instead of inline payloads
+
+Have a use case or suggestion? [Open an issue](https://github.com/mdsiha/adonis-mercure/issues).
+
+---
+
+## License
+
+MIT — [Michael DAŞ](https://github.com/mdsiha)

package/build/bin/test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/bin/test.js

@@ -0,0 +1,8 @@
+import { assert } from '@japa/assert';
+import { configure, processCLIArgs, run } from '@japa/runner';
+processCLIArgs(process.argv.splice(2));
+configure({
+    files: ['tests/**/*.spec.ts'],
+    plugins: [assert()],
+});
+run();

package/build/configure.d.ts

@@ -0,0 +1,2 @@
+import ConfigureCommand from '@adonisjs/core/commands/configure';
+export declare function configure(_command: ConfigureCommand): Promise<void>;

package/build/configure.js

@@ -0,0 +1,34 @@
+/*
+|--------------------------------------------------------------------------
+| Configure hook
+|--------------------------------------------------------------------------
+|
+| The configure hook is called when someone runs "node ace configure <package>"
+| command. You are free to perform any operations inside this function to
+| configure the package.
+|
+| To make things easier, you have access to the underlying "ConfigureCommand"
+| instance and you can use codemods to modify the source files.
+|
+*/
+import { stubsRoot } from './stubs/main.js';
+export async function configure(_command) {
+    const codemods = await _command.createCodemods();
+    await codemods.makeUsingStub(stubsRoot, 'config/mercure.stub', {});
+    await codemods.defineEnvVariables({
+        MERCURE_ENDPOINT: 'http://localhost:3000/.well-known/mercure',
+        MERCURE_ADMIN_JWT: '',
+        MERCURE_JWT_SECRET: '',
+    });
+    await codemods.defineEnvValidations({
+        variables: {
+            MERCURE_ENDPOINT: `Env.schema.string({ format: 'url' })`,
+            MERCURE_ADMIN_JWT: `Env.schema.string()`,
+            MERCURE_JWT_SECRET: `Env.schema.string()`,
+        },
+        leadingComment: 'Mercure configuration',
+    });
+    await codemods.updateRcFile((rcFile) => {
+        rcFile.addProvider('@mdsiha369/adonis-mercure/mercure_provider');
+    });
+}

package/build/index.d.ts

@@ -0,0 +1,9 @@
+export { configure } from './configure.js';
+export { Mercure } from './src/mercure.js';
+export { FakeMercure } from './src/fake_mercure.js';
+export { defineConfig } from './src/define_config.js';
+export { stubsRoot } from './stubs/main.js';
+export { MercureError } from './src/errors/mercure_error.js';
+export { MercurePublishError } from './src/errors/publish_error.js';
+export { MercureConfigError } from './src/errors/config_error.js';
+export { MercureTimeoutError } from './src/errors/timeout_error.js';

package/build/index.js

@@ -0,0 +1,14 @@
+/*
+|--------------------------------------------------------------------------
+| Package entrypoint
+|--------------------------------------------------------------------------
+*/
+export { configure } from './configure.js';
+export { Mercure } from './src/mercure.js';
+export { FakeMercure } from './src/fake_mercure.js';
+export { defineConfig } from './src/define_config.js';
+export { stubsRoot } from './stubs/main.js';
+export { MercureError } from './src/errors/mercure_error.js';
+export { MercurePublishError } from './src/errors/publish_error.js';
+export { MercureConfigError } from './src/errors/config_error.js';
+export { MercureTimeoutError } from './src/errors/timeout_error.js';

package/build/providers/mercure_provider.d.ts

@@ -0,0 +1,7 @@
+import '../src/types/extended.js';
+import type { ApplicationService } from '@adonisjs/core/types';
+export default class MercureProvider {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    boot(): Promise<void>;
+}

package/build/providers/mercure_provider.js

@@ -0,0 +1,18 @@
+import '../src/types/extended.js';
+import { Mercure } from '../src/mercure.js';
+import { MercureConfigError } from '../src/errors/config_error.js';
+export default class MercureProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    async boot() {
+        this.app.container.singleton('mercure', async () => {
+            const config = this.app.config.get('mercure');
+            if (!config?.endpoint || !config?.adminToken || !config?.jwt?.secret) {
+                throw new MercureConfigError('Missing or incomplete Mercure config. Run "node ace configure @mdsiha369/adonis-mercure"');
+            }
+            return new Mercure(config);
+        });
+    }
+}

package/build/services/mercure.d.ts

@@ -0,0 +1,3 @@
+import { Mercure } from '../src/mercure.js';
+declare let mercure: Mercure;
+export { mercure as default };

package/build/services/mercure.js

@@ -0,0 +1,6 @@
+import app from '@adonisjs/core/services/app';
+let mercure;
+await app.booted(async () => {
+    mercure = await app.container.make('mercure');
+});
+export { mercure as default };

package/build/src/define_config.d.ts

@@ -0,0 +1,2 @@
+import type { MercureConfig } from './types/main.js';
+export declare function defineConfig<T extends MercureConfig>(config: T): T;

package/build/src/define_config.js

@@ -0,0 +1,11 @@
+import { MercureConfigError } from './errors/config_error.js';
+const ALLOWED_ALGORITHMS = ['HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512'];
+export function defineConfig(config) {
+    if (!ALLOWED_ALGORITHMS.includes(config.jwt.alg)) {
+        throw new MercureConfigError(`Algorithm "${config.jwt.alg}" is not allowed. Use one of: ${ALLOWED_ALGORITHMS.join(', ')}`);
+    }
+    if (config.jwt.secret.length < 32) {
+        throw new MercureConfigError('jwt.secret must be at least 32 characters long');
+    }
+    return config;
+}

package/build/src/errors/config_error.d.ts

@@ -0,0 +1,4 @@
+import { MercureError } from './mercure_error.js';
+export declare class MercureConfigError extends MercureError {
+    constructor(message: string);
+}

package/build/src/errors/config_error.js

@@ -0,0 +1,7 @@
+import { MercureError } from './mercure_error.js';
+export class MercureConfigError extends MercureError {
+    constructor(message) {
+        super(message);
+        this.name = 'MercureConfigError';
+    }
+}

package/build/src/errors/mercure_error.d.ts

@@ -0,0 +1,3 @@
+export declare class MercureError extends Error {
+    constructor(message: string);
+}

package/build/src/errors/mercure_error.js

@@ -0,0 +1,6 @@
+export class MercureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MercureError';
+    }
+}

package/build/src/errors/publish_error.d.ts

@@ -0,0 +1,6 @@
+import { MercureError } from './mercure_error.js';
+export declare class MercurePublishError extends MercureError {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    constructor(statusCode: number, responseBody: string);
+}

package/build/src/errors/publish_error.js

@@ -0,0 +1,11 @@
+import { MercureError } from './mercure_error.js';
+export class MercurePublishError extends MercureError {
+    statusCode;
+    responseBody;
+    constructor(statusCode, responseBody) {
+        super(`Mercure hub returned ${statusCode}`);
+        this.statusCode = statusCode;
+        this.name = 'MercurePublishError';
+        this.responseBody = responseBody.slice(0, 200);
+    }
+}

package/build/src/errors/timeout_error.d.ts

@@ -0,0 +1,5 @@
+import { MercureError } from './mercure_error.js';
+export declare class MercureTimeoutError extends MercureError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}

package/build/src/errors/timeout_error.js

@@ -0,0 +1,9 @@
+import { MercureError } from './mercure_error.js';
+export class MercureTimeoutError extends MercureError {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Request to Mercure hub timed out after ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'MercureTimeoutError';
+    }
+}

package/build/src/fake_mercure.d.ts

@@ -0,0 +1,18 @@
+import type { MercureContract, SendOptions } from './types/main.js';
+export interface SentMessage {
+    topics: string[];
+    data: Record<string, unknown>;
+    options: SendOptions;
+}
+export declare class FakeMercure implements MercureContract {
+    #private;
+    generate(payload: Record<string, unknown>): Promise<string>;
+    generateSubscribeToken(topics: string[]): Promise<string>;
+    send(topics: string | string[], data?: Record<string, unknown>, isPrivateOrOptions?: boolean | SendOptions): Promise<Response>;
+    ping(): Promise<boolean>;
+    assertSent(topic: string, data?: Record<string, unknown>): void;
+    assertNotSent(topic: string): void;
+    assertNothingSent(): void;
+    getSent(): SentMessage[];
+    clear(): void;
+}

package/build/src/fake_mercure.js

@@ -0,0 +1,52 @@
+export class FakeMercure {
+    #sent = [];
+    #tokens = [];
+    async generate(payload) {
+        this.#tokens.push(payload);
+        return 'fake-token';
+    }
+    async generateSubscribeToken(topics) {
+        return this.generate({ subscribe: topics });
+    }
+    async send(topics, data = {}, isPrivateOrOptions = false) {
+        const topicList = Array.isArray(topics) ? topics : [topics];
+        const options = typeof isPrivateOrOptions === 'boolean' ? { private: isPrivateOrOptions } : isPrivateOrOptions;
+        this.#sent.push({ topics: topicList, data, options });
+        return new Response('1', { status: 200 });
+    }
+    async ping() {
+        return true;
+    }
+    assertSent(topic, data) {
+        const match = this.#sent.find((msg) => {
+            if (!msg.topics.includes(topic))
+                return false;
+            if (!data)
+                return true;
+            return JSON.stringify(msg.data) === JSON.stringify(data);
+        });
+        if (!match) {
+            const found = this.#sent.map((m) => m.topics.join(', ')).join('; ') || 'nothing';
+            throw new Error(`Expected a message on topic "${topic}" but found: [${found}]`);
+        }
+    }
+    assertNotSent(topic) {
+        const match = this.#sent.find((msg) => msg.topics.includes(topic));
+        if (match) {
+            throw new Error(`Expected no message on topic "${topic}" but one was found`);
+        }
+    }
+    assertNothingSent() {
+        if (this.#sent.length > 0) {
+            const topics = this.#sent.map((m) => m.topics.join(', ')).join('; ');
+            throw new Error(`Expected nothing to be sent but found messages on: [${topics}]`);
+        }
+    }
+    getSent() {
+        return [...this.#sent];
+    }
+    clear() {
+        this.#sent = [];
+        this.#tokens = [];
+    }
+}

package/build/src/mercure.d.ts

@@ -0,0 +1,9 @@
+import type { MercureConfig, MercureContract, SendOptions } from './types/main.js';
+export declare class Mercure implements MercureContract {
+    #private;
+    constructor(config: MercureConfig);
+    generate(payload: Record<string, unknown>): Promise<string>;
+    generateSubscribeToken(topics: string[]): Promise<string>;
+    send(topics: string | string[], data?: Record<string, unknown>, isPrivateOrOptions?: boolean | SendOptions): Promise<Response>;
+    ping(): Promise<boolean>;
+}

package/build/src/mercure.js

@@ -0,0 +1,42 @@
+import { TokenGenerator } from './token_generator.js';
+import { Publisher } from './publisher.js';
+const DEFAULT_TIMEOUT = 5000;
+export class Mercure {
+    #config;
+    #tokenGenerator;
+    #publisher;
+    constructor(config) {
+        this.#config = config;
+        this.#tokenGenerator = new TokenGenerator(config);
+        this.#publisher = new Publisher(config);
+    }
+    generate(payload) {
+        return this.#tokenGenerator.generate(payload);
+    }
+    generateSubscribeToken(topics) {
+        return this.#tokenGenerator.generateSubscribeToken(topics);
+    }
+    send(topics, data = {}, isPrivateOrOptions = false) {
+        const options = typeof isPrivateOrOptions === 'boolean' ? { private: isPrivateOrOptions } : isPrivateOrOptions;
+        return this.#publisher.publish(topics, data, options);
+    }
+    async ping() {
+        const timeout = this.#config.http?.timeout ?? DEFAULT_TIMEOUT;
+        const controller = timeout > 0 ? new AbortController() : null;
+        const timer = controller ? setTimeout(() => controller.abort(), timeout) : null;
+        try {
+            await fetch(this.#config.endpoint, {
+                method: 'HEAD',
+                signal: controller?.signal,
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+}

package/build/src/publisher.d.ts

@@ -0,0 +1,6 @@
+import type { MercureConfig, SendOptions } from './types/main.js';
+export declare class Publisher {
+    #private;
+    constructor(config: MercureConfig);
+    publish(topics: string | string[], data?: Record<string, unknown>, options?: SendOptions): Promise<Response>;
+}