@generazioneai/events 0.0.1 → 0.1.0

package/dist/types.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RETRY_SCHEDULE_MS = void 0;
+exports.resolveOptions = resolveOptions;
+exports.DEFAULT_RETRY_SCHEDULE_MS = [10_000, 60_000, 300_000, 1_800_000, 7_200_000, 21_600_000, 43_200_000];
+function resolveOptions(o, env = process.env) {
+    const mode = (o.mode ?? env.EVENTS_MODE ?? 'off');
+    const sig = (o.signatureMode ?? env.EVENTS_SIGNATURE ?? 'off');
+    if (!['off', 'outbox', 'on'].includes(mode))
+        throw new Error(`EVENTS_MODE non valido: ${mode}`);
+    if (!['off', 'shadow', 'enforce'].includes(sig))
+        throw new Error(`EVENTS_SIGNATURE non valido: ${sig}`);
+    return {
+        service: o.service,
+        stream: o.stream ?? `EVT_${o.service.toUpperCase()}`,
+        mode,
+        signatureMode: sig,
+        createStream: o.createStream ?? true,
+        streamReplicas: o.streamReplicas ?? (env.EVENTS_STREAM_REPLICAS ? Number(env.EVENTS_STREAM_REPLICAS) : 3),
+        streamMaxBytes: o.streamMaxBytes ?? (env.EVENTS_STREAM_MAX_BYTES ? Number(env.EVENTS_STREAM_MAX_BYTES) : 5 * 1024 ** 3),
+        retryScheduleMs: o.retryScheduleMs ?? exports.DEFAULT_RETRY_SCHEDULE_MS,
+        relayIntervalMs: o.relayIntervalMs ?? 500,
+        relayBatchSize: o.relayBatchSize ?? 100,
+        pollMs: o.pollMs ?? 5_000,
+        outboxRetentionDays: o.outboxRetentionDays ?? 7,
+        inboxRetentionDays: o.inboxRetentionDays ?? 30,
+        natsUrl: o.natsUrl ?? env.EVENTS_NATS_URL ?? env.NATS_URL,
+        signer: o.signer,
+        verifier: o.verifier,
+        connection: o.connection,
+        traceparent: o.traceparent,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AA0IA,wCAyBC;AArDY,QAAA,yBAAyB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AA4BjH,SAAgB,cAAc,CAAC,CAAsB,EAAE,MAAyB,OAAO,CAAC,GAAG;IACzF,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAK,GAAG,CAAC,WAA0B,IAAI,KAAK,CAAe,CAAC;IAChF,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,aAAa,IAAK,GAAG,CAAC,gBAAwC,IAAI,KAAK,CAAwB,CAAC;IAC/G,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,EAAE,CAAC,CAAC;IAChG,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;IACxG,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE;QACpD,IAAI;QACJ,aAAa,EAAE,GAAG;QAClB,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,IAAI;QACpC,cAAc,EAAE,CAAC,CAAC,cAAc,IAAI,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzG,cAAc,EAAE,CAAC,CAAC,cAAc,IAAI,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QACvH,eAAe,EAAE,CAAC,CAAC,eAAe,IAAI,iCAAyB;QAC/D,eAAe,EAAE,CAAC,CAAC,eAAe,IAAI,GAAG;QACzC,cAAc,EAAE,CAAC,CAAC,cAAc,IAAI,GAAG;QACvC,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,KAAK;QACzB,mBAAmB,EAAE,CAAC,CAAC,mBAAmB,IAAI,CAAC;QAC/C,kBAAkB,EAAE,CAAC,CAAC,kBAAkB,IAAI,EAAE;QAC9C,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,QAAQ;QACzD,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,WAAW,EAAE,CAAC,CAAC,WAAW;KAC3B,CAAC;AACJ,CAAC"}

package/dist/uuid.d.ts

@@ -0,0 +1,7 @@
+/**
+ * UUID v7 (RFC 9562): 48 bit di millisecondi + 12 bit di contatore monotono nello stesso millisecondo + 62 bit casuali.
+ * Gli id si ordinano come testo nell'ordine in cui sono stati generati (da questo processo).
+ */
+export declare function uuidv7(now?: number): string;
+export declare const UUID_RE: RegExp;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAgBvD;AAED,eAAO,MAAM,OAAO,QAAoE,CAAC"}

package/dist/uuid.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UUID_RE = void 0;
+exports.uuidv7 = uuidv7;
+const crypto_1 = require("crypto");
+let lastMs = 0;
+let seq = 0;
+/**
+ * UUID v7 (RFC 9562): 48 bit di millisecondi + 12 bit di contatore monotono nello stesso millisecondo + 62 bit casuali.
+ * Gli id si ordinano come testo nell'ordine in cui sono stati generati (da questo processo).
+ */
+function uuidv7(now = Date.now()) {
+    if (now <= lastMs) {
+        now = lastMs;
+        seq = (seq + 1) & 0xfff;
+        if (seq === 0)
+            now = ++lastMs; // contatore esaurito: avanza il millisecondo
+    }
+    else {
+        seq = (0, crypto_1.randomBytes)(2).readUInt16BE(0) & 0x1ff; // parte bassa, lascia spazio al contatore
+    }
+    lastMs = now;
+    const b = (0, crypto_1.randomBytes)(16);
+    b.writeUIntBE(now, 0, 6);
+    b[6] = 0x70 | ((seq >> 8) & 0x0f);
+    b[7] = seq & 0xff;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = b.toString('hex');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+exports.UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+//# sourceMappingURL=uuid.js.map

package/dist/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":";;;AASA,wBAgBC;AAzBD,mCAAqC;AAErC,IAAI,MAAM,GAAG,CAAC,CAAC;AACf,IAAI,GAAG,GAAG,CAAC,CAAC;AAEZ;;;GAGG;AACH,SAAgB,MAAM,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IAC7C,IAAI,GAAG,IAAI,MAAM,EAAE,CAAC;QAClB,GAAG,GAAG,MAAM,CAAC;QACb,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;QACxB,IAAI,GAAG,KAAK,CAAC;YAAE,GAAG,GAAG,EAAE,MAAM,CAAC,CAAC,6CAA6C;IAC9E,CAAC;SAAM,CAAC;QACN,GAAG,GAAG,IAAA,oBAAW,EAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,0CAA0C;IAC1F,CAAC;IACD,MAAM,GAAG,GAAG,CAAC;IACb,MAAM,CAAC,GAAG,IAAA,oBAAW,EAAC,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC;IAClB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC5B,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;AACnG,CAAC;AAEY,QAAA,OAAO,GAAG,iEAAiE,CAAC"}

package/package.json

@@ -1,8 +1,69 @@
 {
   "name": "@generazioneai/events",
-  "version": "0.0.1",
-  "description": "Segnaposto: il pacchetto vero arriva con la 0.1.0 dal repo GenerazioneAI-SRL/authz.",
+  "version": "0.1.0",
+  "description": "Eventi durevoli fra i servizi (ADR-009): outbox transazionale, relay su NATS JetStream, consumer durevoli con inbox idempotente, riprove con attesa crescente e dead letter comune.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "sql",
+    "prisma",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GenerazioneAI-SRL/authz.git",
+    "directory": "packages/events"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "jest --maxWorkers=2",
+    "typecheck": "tsc -p tsconfig.spec.json",
+    "test:prepare": "prisma generate --config test/prisma/prisma.config.ts"
+  },
+  "dependencies": {
+    "@nats-io/jetstream": "^3.4.0",
+    "@nats-io/transport-node": "^3.4.0"
+  },
+  "peerDependencies": {
+    "@generazioneai/authz": "^0.7.0",
+    "@nestjs/common": "^11.0.0 || ^12.0.0",
+    "@nestjs/core": "^11.0.0 || ^12.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@generazioneai/authz": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.2.7",
+    "@nestjs/core": "^11.2.7",
+    "@nestjs/testing": "^11.2.7",
+    "@prisma/adapter-pg": "^7.8.0",
+    "@prisma/client": "^7.8.0",
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.15.0",
+    "pg": "^8.16.0",
+    "prisma": "^7.8.0",
+    "rxjs": "^7.8.1",
+    "typescript": "^5.1.3"
+  },
+  "keywords": [
+    "jetstream",
+    "nats",
+    "outbox",
+    "events"
+  ],
   "license": "UNLICENSED",
-  "repository": { "type": "git", "url": "git+https://github.com/GenerazioneAI-SRL/authz.git", "directory": "packages/events" },
-  "files": ["README.md"]
+  "homepage": "https://github.com/GenerazioneAI-SRL/authz/tree/main/packages/events#readme"
 }

package/prisma/events.prisma

@@ -0,0 +1,30 @@
+// @generazioneai/events 0.1.0 — da copiare nello schema del servizio (con prismaSchemaFolder: prisma/schema/events.prisma).
+// Poi `prisma migrate dev --name events_outbox` (o l'SQL di sql/001-events-outbox-inbox.sql nel registro, per HR).
+// I nomi delle tabelle e delle colonne sono quelli che la libreria usa nelle sue query: non cambiarli.
+model OutboxEvent {
+  id               String    @id @db.Uuid // UUID v7: ordinato nel tempo
+  subject          String // evt.id.employment.changed
+  aggregateType    String
+  aggregateId      String
+  aggregateVersion Int
+  juridicalId      String? // l'azienda, anche in Gen-Tenant
+  payload          Json // `data` della busta: solo id e stati
+  headers          Json? // { occurredAt, traceparent? }
+  createdAt        DateTime  @default(now())
+  publishedAt      DateTime?
+  attempts         Int       @default(0)
+  lastError        String?
+
+  @@index([publishedAt, id])
+  @@map("outbox_events")
+}
+
+model InboxProcessed {
+  consumer    String
+  eventId     String   @db.Uuid
+  processedAt DateTime @default(now())
+
+  @@id([consumer, eventId])
+  @@index([processedAt])
+  @@map("inbox_processed")
+}

package/sql/001-events-outbox-inbox-rientro.sql

@@ -0,0 +1,3 @@
+-- Rientro di 001-events-outbox-inbox.sql: perde gli eventi non ancora pubblicati e l'inbox. Solo con EVENTS_MODE=off.
+DROP TABLE IF EXISTS "inbox_processed";
+DROP TABLE IF EXISTS "outbox_events";

package/sql/001-events-outbox-inbox.sql

@@ -0,0 +1,28 @@
+-- @generazioneai/events 0.1.0: outbox e inbox. Solo aggiunte; il rientro è 001-events-outbox-inbox-rientro.sql.
+-- Equivalente SQL di prisma/events.prisma (stesse colonne e tipi di quelli che Prisma 7 genera): copiare nella migrazione
+-- del servizio (Prisma: `prisma migrate`; HR: nel registro SQL con `-- db:` e il suo -rientro).
+CREATE TABLE IF NOT EXISTS "outbox_events" (
+  "id"               UUID         NOT NULL,
+  "subject"          TEXT         NOT NULL,
+  "aggregateType"    TEXT         NOT NULL,
+  "aggregateId"      TEXT         NOT NULL,
+  "aggregateVersion" INTEGER      NOT NULL,
+  "juridicalId"      TEXT,
+  "payload"          JSONB        NOT NULL,
+  "headers"          JSONB,
+  "createdAt"        TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "publishedAt"      TIMESTAMP(3),
+  "attempts"         INTEGER      NOT NULL DEFAULT 0,
+  "lastError"        TEXT,
+  CONSTRAINT "outbox_events_pkey" PRIMARY KEY ("id")
+);
+-- il relay legge solo le righe non pubblicate, in ordine di id (UUID v7 = ordine di scrittura)
+CREATE INDEX IF NOT EXISTS "outbox_events_publishedAt_id_idx" ON "outbox_events" ("publishedAt", "id");
+
+CREATE TABLE IF NOT EXISTS "inbox_processed" (
+  "consumer"    TEXT         NOT NULL,
+  "eventId"     UUID         NOT NULL,
+  "processedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "inbox_processed_pkey" PRIMARY KEY ("consumer", "eventId")
+);
+CREATE INDEX IF NOT EXISTS "inbox_processed_processedAt_idx" ON "inbox_processed" ("processedAt");