@generazioneai/events 0.0.1 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.1 — 2026-10-31
+
+- Le metriche `events_*` passano anche all'API di OpenTelemetry (contatori e gauge osservabili, no-op senza SDK; `@opentelemetry/api` ~1.9.0
+  come `@generazioneai/jobs`): con `@generazioneai/telemetry` arrivano al Collector e a VictoriaMetrics senza un endpoint in ogni servizio.
+  `EventsMetrics.render()` e i nomi non cambiano. I servizi la prendono alzando la versione, senza altro codice.
+
+## 0.1.0 — 2026-10-25
+
+Prima versione (treno 3+4, tappa E1; ADR-009, spec «Fondamenta enterprise» §1).
+
+- `EventsModule.forRoot({ service, stream?, prisma, … })`, globale; `EVENTS_MODE` off | outbox | on, `EVENTS_SIGNATURE` off | shadow | enforce,
+  `EVENTS_NATS_URL` (ripiego `NATS_URL`).
+- `enqueue` ammette anche `audit.<svc>[.…]`, pubblicato sullo stream `AUDIT`.
+- Fix: il riconoscimento della transazione non guarda più `$transaction` sul client (Prisma 7 lo ha anche nel `tx`) ma usa `SAVEPOINT` lato Postgres; con `EVENTS_MODE=off` `enqueue` non lancia mai. Prove con il client Prisma 7 vero.
+- `OutboxService.enqueue(tx, { subject, aggregate, juridicalId?, data })`: scrive `outbox_events` nella transazione del dato; fuori
+  da una `$transaction` lancia `EVENTS_OUTSIDE_TX`.
+- Relay: `FOR UPDATE SKIP LOCKED`, 100 righe, `Nats-Msg-Id` = id, attesa del PubAck; pulizia a 7 giorni.
+- `@OnEvent(subject, { consumer, maxAckPending? })`: consumer durevole pull, transazione + `inbox_processed` + gestore + ack.
+- Busta `EventEnvelope` v1 con UUID v7; intestazioni `Nats-Msg-Id`, `Gen-Tenant`, `Gen-Event-Version`, `Gen-Sig`, `traceparent`.
+- Riprove 10s, 1m, 5m, 30m, 2h, 6h, 12h (8 consegne), poi `dlq.<stream>.<consumer>`; `EventValidationError` va subito in dead letter;
+  avviso `MAX_DELIVERIES` per i pod morti a metà.
+- Metriche `events_*` (`EventsMetrics.render()`).
+- `streamMaxBytes` / `EVENTS_STREAM_MAX_BYTES` (default 5 GiB, invariato): il tetto dello stream è riservato sul `max_file_store` di NATS,
+  e su un NATS piccolo due stream da 5 GiB non ci stanno (era la causa dei timeout delle prove in CI).
+- `sql/001-events-outbox-inbox.sql` (+ rientro) e `prisma/events.prisma` da copiare nei servizi.

package/README.md

@@ -1,3 +1,108 @@
 # @generazioneai/events
 
-Segnaposto. Il pacchetto vero arriva con la 0.1.0.
+Eventi **durevoli** fra i servizi della piattaforma (ADR-009, spec «Fondamenta enterprise» §1): l'evento si scrive nella stessa
+transazione del dato (outbox), un relay lo pubblica su NATS JetStream, chi lo riceve lo applica una volta sola (inbox) con riprove
+e dead letter. Consegna «almeno una volta», effetto «una volta sola». I **comandi** restano su NATS core, invariati.
+
+```bash
+npm i @generazioneai/events
+```
+
+Peer: `@nestjs/common`, `@nestjs/core`, `reflect-metadata`. Client NATS: `@nats-io/transport-node` + `@nats-io/jetstream`, su una connessione
+**propria** (diversa da quella del trasporto Nest).
+
+## Nel servizio
+
+1. Copia nello schema le tabelle: `prisma/events.prisma` (Prisma) o `sql/001-events-outbox-inbox.sql` + `-rientro.sql` (HR: registro SQL).
+   Non cambiare i nomi di tabelle e colonne: la libreria li usa in SQL.
+2. Registra il modulo:
+
+```ts
+EventsModule.forRoot({
+  service: 'id',               // id | hr | train | ops | notify | ai | sign | bill | audit
+  prisma: PrismaService,       // la classe (risolta da Nest) o l'istanza
+  // facoltativi:
+  signer: (p) => signEventToken(ctx, { eventId: p.eventId, subject: p.subject }),            // authz 0.7
+  verifier: (token, p) => verifyEventToken(token, { eventId: p.eventId, subject: p.subject, mode: p.mode }),
+  traceparent: () => currentTraceparent(),                                                   // @generazioneai/telemetry
+})
+```
+
+3. Pubblica **dentro la transazione del dato**:
+
+```ts
+await this.prisma.$transaction(async (tx) => {
+  const emp = await tx.employment.update(…);
+  await this.outbox.enqueue(tx, {                          // OutboxService
+    subject: 'evt.id.employment.changed',                  // evt.<servizio>.<entità>.<fatto>, il servizio è il proprio
+    aggregate: { type: 'Employment', id: emp.id, version: emp.version },
+    juridicalId: emp.juridicalId,
+    data: { juridicalId, individualId, juridicalIndividualId, status: 'ENDED' }, // solo id e stati
+  });
+});
+```
+
+Fuori da una transazione lancia `EVENTS_OUTSIDE_TX`. Il riconoscimento è fatto dal database, non dalla forma del client (in Prisma 7 anche il `tx` ha `$transaction`):
+la prima `enqueue` su un `tx` esegue `SAVEPOINT` (esiste solo dentro un blocco di transazione, altrimenti Postgres risponde 25P01) e `RELEASE`; il `tx` verificato
+non si riprova. Con `EVENTS_MODE=off` non lancia mai, non scrive nulla e restituisce `null`.
+
+4. Consuma:
+
+```ts
+@OnEvent('evt.id.employment.changed', { consumer: 'hr.employment-changed', maxAckPending: 50 })
+async onEmploymentChanged(evt: EventEnvelope<EmploymentChanged>, tx: PrismaTx) {
+  if (!evt.data.individualId) throw new EventValidationError('manca individualId'); // subito in dead letter
+  await tx.… // gli effetti nella transazione della libreria
+}
+```
+
+La libreria apre la transazione, inserisce `(consumer, eventId)` in `inbox_processed` (già presente: salta il gestore), chiama il gestore
+col `tx`, fa COMMIT e poi `ack`. Il gestore deve restare dentro il `tx` per gli effetti sul database; gli effetti fuori dal database
+(chiamate NATS, email) devono essere idempotenti.
+
+## Contratto
+
+- **Busta** `EventEnvelope<T> = { v: 1, id (UUID v7), subject, aggregateType, aggregateId, aggregateVersion, occurredAt, juridicalId?, data: T }`.
+- **Intestazioni**: `Nats-Msg-Id` (= `id`), `Gen-Tenant`, `Gen-Event-Version` (1), `Gen-Sig` (JWT della firma interna, audience `events`), `traceparent`.
+- **Subject ammessi in `enqueue`**: `evt.<proprio servizio>.…` (stream `EVT_<SVC>`) e `audit.<proprio servizio>[.…]` (stream `AUDIT`, creato da `genai-audit`; NATS sceglie lo stream dal subject, quindi lo stream deve esistere). Altri prefissi: `EVENTS_INVALID`. `@OnEvent` su `audit.…` si lega a `AUDIT`.
+- **Stream** `EVT_<SVC>` (`evt.<svc>.>`): lo crea il proprietario all'avvio (R3, file, 7 giorni o 5 GiB, `discard: old`, `duplicate_window` 10 m; `streamReplicas`
+  o `EVENTS_STREAM_REPLICAS` per sviluppo). Il tetto (`streamMaxBytes` o `EVENTS_STREAM_MAX_BYTES`) JetStream lo riserva sul `max_file_store`
+  del server: con un NATS piccolo (sviluppo, staging, CI) va abbassato, se no il secondo stream non si crea e l'avvio degli eventi resta a riprovare. `DLQ` (`dlq.>`) e `AUDIT` li crea `genai-audit`: se `DLQ` non esiste il messaggio non va perso, resta in coda.
+- **Consumer**: pull, durevole, `ack_wait` 30 s (con `working()` ogni 3 s mentre il gestore lavora), `max_deliver` 8, `backoff` 10 s, 1 m, 5 m, 30 m, 2 h, 6 h, 12 h,
+  `filter_subject` stretto. Il nome del durable è il nome logico con i punti sostituiti da `_` (NATS non li ammette): `hr.employment-changed` → `hr_employment-changed`;
+  nella dead letter e nelle metriche resta il nome logico. Lo stream si deduce dal subject (`evt.id.…` → `EVT_ID`).
+- **Riprove e dead letter**: errore del gestore → `nak` con l'attesa crescente; all'ottava consegna (o subito per `EventValidationError`, busta non valida, firma
+  rifiutata) copia in `dlq.<stream>.<consumer>` con `Gen-Dlq-Reason`, `Gen-Dlq-Stream`, `Gen-Dlq-Consumer`, `Gen-Dlq-Seq`, `Gen-Dlq-Deliveries`, `Gen-Original-Id`,
+  `Gen-Original-Subject` e il **corpo originale**, poi `term`. Per i pod morti a metà ascolta l'avviso `$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.<stream>.>`
+  (un solo ricevente per servizio, gruppo di coda) e copia il messaggio per numero di sequenza; il `Nats-Msg-Id` della copia è
+  `dlq-<stream>-<consumer>-<seq>`, quindi i due percorsi non duplicano.
+- **Firma** (`EVENTS_SIGNATURE`): off = niente; shadow = firma, verifica e conta gli errori senza rifiutare; enforce = rifiuta (dead letter) le firme assenti o errate
+  e richiede `signer` e `verifier` (altrimenti l'avvio fallisce). La libreria non importa authz: `signer` e `verifier` si iniettano (con authz 0.7: `signEventToken`
+  / `verifyEventToken`).
+- **Connessione**: `EVENTS_NATS_URL` (ripiego `NATS_URL`); `NATS_NKEY_SEED` → autenticazione nkey; `connection: {…}` per altre opzioni di `connect`.
+  Con NATS giù l'app parte lo stesso e l'outbox accumula.
+
+## Garanzie e limiti
+
+- Pubblicazione **esattamente una volta** nella finestra di 10 minuti (`Nats-Msg-Id`); oltre, il doppione lo scarta l'inbox di chi consuma.
+- **Ordine**: il relay legge per id (UUID v7), ma transazioni che committano fuori ordine, più repliche (`SKIP LOCKED`) e le riprove non lo garantiscono. Chi
+  ha bisogno dell'ordine confronta `aggregateVersion`. I consumer elaborano un messaggio alla volta per consumer.
+- Il relay tiene aperta una transazione mentre pubblica (fino a `relayBatchSize` righe, 100); per questo usa il timeout di 60 s di `$transaction`.
+- `JetStream` non è uno scheduler: le code con regole di dominio restano nei servizi.
+
+## Metriche
+
+`EventsMetrics.render()` produce testo Prometheus: `events_outbox_pending`, `events_outbox_oldest_seconds`, `events_published_total{subject}`,
+`events_delivered_total{consumer}`, `events_nak_total{consumer}`, `events_term_total{consumer}`, `events_consumer_lag{consumer}`, più
+`events_duplicates_total{consumer}` e `events_signature_invalid_total{mode}`. Il servizio le aggiunge al suo endpoint (o telemetry le legge).
+
+## Test
+
+`npm test -w @generazioneai/events` (prima `npm run test:prepare -w @generazioneai/events`, genera il client Prisma 7 vero delle prove): le prove unitarie girano sempre; quelle di integrazione vogliono `EVENTS_TEST_NATS_URL` (un `nats-server` con JetStream) e
+`EVENTS_TEST_DATABASE_URL` (Postgres), altrimenti sono saltate (con `EVENTS_REQUIRE_INTEGRATION=1` mancano e il test fallisce). In locale:
+
+```bash
+docker run -d --rm --name evt-nats -p 14222:4222 nats:2.12 -js
+docker run -d --rm --name evt-pg -e POSTGRES_PASSWORD=postgres -p 15432:5432 postgres:18
+EVENTS_TEST_NATS_URL=nats://127.0.0.1:14222 EVENTS_TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:15432/postgres npm test -w @generazioneai/events
+```

package/dist/connection.d.ts

@@ -0,0 +1,23 @@
+import { type NatsConnection } from '@nats-io/transport-node';
+import { type JetStreamClient, type JetStreamManager } from '@nats-io/jetstream';
+import type { ResolvedEventsOptions } from './types';
+/** Connessione NATS propria della libreria (diversa da quella del trasporto Nest) + JetStream. */
+export declare class EventsConnection {
+    private readonly opts;
+    private readonly log;
+    private nc?;
+    private js?;
+    private jsm?;
+    private starting?;
+    constructor(opts: ResolvedEventsOptions);
+    /** Connette (una sola volta). Con NATS giù aspetta: l'app non si ferma, l'outbox accumula. */
+    ensure(): Promise<void>;
+    get connected(): boolean;
+    get client(): NatsConnection;
+    get jetstream(): JetStreamClient;
+    get manager(): JetStreamManager;
+    /** Crea o aggiorna lo stream del servizio (`EVT_<SVC>`, `evt.<svc>.>`): R3, file, 7 giorni o `streamMaxBytes` (5 GiB), `duplicate_window` 10 m. */
+    ensureOwnStream(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC1F,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAIrD,kGAAkG;AAClG,qBACa,gBAAgB;IAOS,OAAO,CAAC,QAAQ,CAAC,IAAI;IANzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAC5C,OAAO,CAAC,EAAE,CAAC,CAAiB;IAC5B,OAAO,CAAC,EAAE,CAAC,CAAkB;IAC7B,OAAO,CAAC,GAAG,CAAC,CAAmB;IAC/B,OAAO,CAAC,QAAQ,CAAC,CAAgB;gBAEoB,IAAI,EAAE,qBAAqB;IAEhF,8FAA8F;IAC9F,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BvB,IAAI,SAAS,IAAI,OAAO,CAEvB;IACD,IAAI,MAAM,IAAI,cAAc,CAG3B;IACD,IAAI,SAAS,IAAI,eAAe,CAG/B;IACD,IAAI,OAAO,IAAI,gBAAgB,CAG9B;IAED,mJAAmJ;IAC7I,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B"}

package/dist/connection.js

@@ -0,0 +1,113 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsConnection = void 0;
+const common_1 = require("@nestjs/common");
+const transport_node_1 = require("@nats-io/transport-node");
+const jetstream_1 = require("@nats-io/jetstream");
+const tokens_1 = require("./tokens");
+const NS = 1_000_000;
+/** Connessione NATS propria della libreria (diversa da quella del trasporto Nest) + JetStream. */
+let EventsConnection = class EventsConnection {
+    constructor(opts) {
+        this.opts = opts;
+        this.log = new common_1.Logger('Events');
+    }
+    /** Connette (una sola volta). Con NATS giù aspetta: l'app non si ferma, l'outbox accumula. */
+    ensure() {
+        if (!this.starting) {
+            this.starting = (async () => {
+                const url = this.opts.natsUrl;
+                if (!url)
+                    throw new Error('EVENTS_NATS_URL / NATS_URL non impostato');
+                const extra = {};
+                if (process.env.NATS_NKEY_SEED)
+                    extra.authenticator = (0, transport_node_1.nkeyAuthenticator)(new TextEncoder().encode(process.env.NATS_NKEY_SEED));
+                this.nc = await (0, transport_node_1.connect)({
+                    servers: url,
+                    name: `genai-events-${this.opts.service}`,
+                    maxReconnectAttempts: -1,
+                    waitOnFirstConnect: true,
+                    ...extra,
+                    ...(this.opts.connection ?? {}),
+                });
+                this.js = (0, jetstream_1.jetstream)(this.nc);
+                this.jsm = await (0, jetstream_1.jetstreamManager)(this.nc);
+                this.log.log(`connesso a NATS (${this.opts.service}, stream ${this.opts.stream})`);
+            })().catch((e) => {
+                this.starting = undefined;
+                throw e;
+            });
+        }
+        return this.starting;
+    }
+    get connected() {
+        return !!this.nc && !this.nc.isClosed();
+    }
+    get client() {
+        if (!this.nc)
+            throw new Error('NATS non connesso');
+        return this.nc;
+    }
+    get jetstream() {
+        if (!this.js)
+            throw new Error('NATS non connesso');
+        return this.js;
+    }
+    get manager() {
+        if (!this.jsm)
+            throw new Error('NATS non connesso');
+        return this.jsm;
+    }
+    /** Crea o aggiorna lo stream del servizio (`EVT_<SVC>`, `evt.<svc>.>`): R3, file, 7 giorni o `streamMaxBytes` (5 GiB), `duplicate_window` 10 m. */
+    async ensureOwnStream() {
+        if (!this.opts.createStream)
+            return;
+        const cfg = {
+            name: this.opts.stream,
+            subjects: [`evt.${this.opts.service}.>`],
+            storage: jetstream_1.StorageType.File,
+            retention: jetstream_1.RetentionPolicy.Limits,
+            discard: jetstream_1.DiscardPolicy.Old,
+            num_replicas: this.opts.streamReplicas,
+            max_age: 7 * 24 * 3600 * 1000 * NS,
+            max_bytes: this.opts.streamMaxBytes,
+            duplicate_window: 10 * 60 * 1000 * NS,
+        };
+        try {
+            await this.manager.streams.info(cfg.name);
+            await this.manager.streams.update(cfg.name, cfg);
+        }
+        catch (e) {
+            if (e?.code === '404' || /not found/i.test(String(e?.message)))
+                await this.manager.streams.add(cfg);
+            else
+                throw e;
+        }
+    }
+    async close() {
+        const nc = this.nc;
+        this.nc = this.js = this.jsm = undefined;
+        this.starting = undefined;
+        if (nc && !nc.isClosed())
+            await nc.drain().catch(() => undefined);
+    }
+};
+exports.EventsConnection = EventsConnection;
+exports.EventsConnection = EventsConnection = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(tokens_1.EVENTS_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], EventsConnection);
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAA4D;AAC5D,4DAA0F;AAC1F,kDAQ4B;AAC5B,qCAA0C;AAG1C,MAAM,EAAE,GAAG,SAAS,CAAC;AAErB,kGAAkG;AAE3F,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IAO3B,YAAoC,IAA4C;QAA3B,SAAI,GAAJ,IAAI,CAAuB;QAN/D,QAAG,GAAG,IAAI,eAAM,CAAC,QAAQ,CAAC,CAAC;IAMuC,CAAC;IAEpF,8FAA8F;IAC9F,MAAM;QACJ,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;gBAC9B,IAAI,CAAC,GAAG;oBAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;gBACtE,MAAM,KAAK,GAA4B,EAAE,CAAC;gBAC1C,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;oBAAE,KAAK,CAAC,aAAa,GAAG,IAAA,kCAAiB,EAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;gBAC9H,IAAI,CAAC,EAAE,GAAG,MAAM,IAAA,wBAAO,EAAC;oBACtB,OAAO,EAAE,GAAG;oBACZ,IAAI,EAAE,gBAAgB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;oBACzC,oBAAoB,EAAE,CAAC,CAAC;oBACxB,kBAAkB,EAAE,IAAI;oBACxB,GAAG,KAAK;oBACR,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;iBACzB,CAAC,CAAC;gBACV,IAAI,CAAC,EAAE,GAAG,IAAA,qBAAS,EAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAC7B,IAAI,CAAC,GAAG,GAAG,MAAM,IAAA,4BAAgB,EAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAC3C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,oBAAoB,IAAI,CAAC,IAAI,CAAC,OAAO,YAAY,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YACrF,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;gBACf,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;gBAC1B,MAAM,CAAC,CAAC;YACV,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC;IAC1C,CAAC;IACD,IAAI,MAAM;QACR,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IACD,IAAI,SAAS;QACX,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IACD,IAAI,OAAO;QACT,IAAI,CAAC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,mJAAmJ;IACnJ,KAAK,CAAC,eAAe;QACnB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY;YAAE,OAAO;QACpC,MAAM,GAAG,GAAG;YACV,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;YACtB,QAAQ,EAAE,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC;YACxC,OAAO,EAAE,uBAAW,CAAC,IAAI;YACzB,SAAS,EAAE,2BAAe,CAAC,MAAM;YACjC,OAAO,EAAE,yBAAa,CAAC,GAAG;YAC1B,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc;YACtC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,GAAG,EAAE;YAClC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc;YACnC,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,EAAE;SACtC,CAAC;QACF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC1C,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,CAAM,EAAE,CAAC;YAChB,IAAI,CAAC,EAAE,IAAI,KAAK,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;gBAAE,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;;gBAC/F,MAAM,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC1B,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE;YAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACpE,CAAC;CACF,CAAA;AAjFY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;IAQE,WAAA,IAAA,eAAM,EAAC,uBAAc,CAAC,CAAA;;GAPxB,gBAAgB,CAiF5B"}

package/dist/consumers.service.d.ts

@@ -0,0 +1,54 @@
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { type JsMsg } from '@nats-io/jetstream';
+import { EventsConnection } from './connection';
+import type { OnEventMetadata } from './decorators';
+import { EventsMetrics } from './metrics';
+import { PrismaResolver } from './prisma-resolver';
+import type { EventHandler, ResolvedEventsOptions } from './types';
+interface Registered extends OnEventMetadata {
+    handler: EventHandler;
+    stream: string;
+    durable: string;
+}
+/** Durable di NATS non ammette il punto: `hr.employment-changed` → `hr_employment-changed`. Il nome logico resta quello originale. */
+export declare const durableName: (consumer: string) => string;
+/** `evt.<svc>.…` → `EVT_<SVC>`. */
+export declare function streamForSubject(subject: string): string;
+/** Trova i gestori `@OnEvent`, crea i consumer durevoli e li serve: transazione + inbox + gestore + ack. */
+export declare class EventsConsumers {
+    private readonly opts;
+    private readonly conn;
+    private readonly prisma;
+    private readonly metrics;
+    private readonly discovery;
+    private readonly scanner;
+    private readonly log;
+    private registered;
+    private stopped;
+    private loops;
+    private advisorySubs;
+    private lagTimer?;
+    private readonly consumers;
+    constructor(opts: ResolvedEventsOptions, conn: EventsConnection, prisma: PrismaResolver, metrics: EventsMetrics, discovery: DiscoveryService, scanner: MetadataScanner);
+    /** Cerca i `@OnEvent` fra i provider. Ripetibile (non duplica). */
+    discover(): Registered[];
+    get handlers(): readonly Registered[];
+    /** Registra a mano un gestore (senza decoratore): per i test e per codice non Nest. */
+    register(meta: OnEventMetadata, handler: EventHandler): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private runWithRetry;
+    private consumerConfig;
+    private ensureConsumer;
+    private loop;
+    /** Una consegna: verifica, transazione con inbox, ack/nak/term. Pubblico per i test. */
+    handle(r: Registered, m: JsMsg): Promise<void>;
+    private delayFor;
+    private parse;
+    private verify;
+    private toDlq;
+    private onMaxDeliveries;
+    private refreshLag;
+}
+export {};
+//# sourceMappingURL=consumers.service.d.ts.map

package/dist/consumers.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumers.service.d.ts","sourceRoot":"","sources":["../src/consumers.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEjE,OAAO,EAA2C,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,KAAK,EAAiB,YAAY,EAAY,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAK5F,UAAU,UAAW,SAAQ,eAAe;IAC1C,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sIAAsI;AACtI,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,WAAyC,CAAC;AAEtF,mCAAmC;AACnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,4GAA4G;AAC5G,qBACa,eAAe;IAUA,OAAO,CAAC,QAAQ,CAAC,IAAI;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAd1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;IACrD,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,YAAY,CAAsC;IAC1D,OAAO,CAAC,QAAQ,CAAC,CAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;gBAGd,IAAI,EAAE,qBAAqB,EACnD,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,eAAe;IAG3C,mEAAmE;IACnE,QAAQ,IAAI,UAAU,EAAE;IA8BxB,IAAI,QAAQ,IAAI,SAAS,UAAU,EAAE,CAEpC;IAED,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAStD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAYb,YAAY;IAa1B,OAAO,CAAC,cAAc;YAcR,cAAc;YAkBd,IAAI;IASlB,wFAAwF;IAClF,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDpD,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,KAAK;YAkBC,MAAM;YAmBN,KAAK;YAgBL,eAAe;YASf,UAAU;CAUzB"}