@modainteract/moda-interact-shared 1.5.0 → 2.0.0

package/dist/incidents/index.d.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+
+/** Durable outcome of one occurrence; duplicate deliveries have no side effects. */
+type IncidentReportResult = {
+    incidentKey: string;
+    recorded: boolean;
+    occurrenceCount: number;
+    status: "OPEN" | "RESOLVED";
+};
+type IncidentSnapshot = {
+    incidentKey: string;
+    status: "OPEN" | "RESOLVED";
+    occurrenceCount: number;
+    lastOccurredAt: Date;
+};
+/**
+ * Transactional persistence contract, implemented by the consuming service.
+ * transactionForKey MUST serialize operations for the same key across processes,
+ * INCLUDING first creation; the callback must be retried on a conflicting insert.
+ * insertOccurrenceIfNew MUST enforce a GLOBAL unique occurrenceId (not only per
+ * incident); an occurrenceId already belonging to another key MUST throw.
+ * On creation loadOrCreate MUST initialise occurrenceCount=1; recordOccurrence
+ * MUST NOT increment that first occurrence again. If a duplicate is encountered
+ * when newlyCreated=true, the transaction MUST fail and roll back creation.
+ * Every operation in this port, including optional support notification, MUST
+ * participate in the SAME database transaction and roll back together.
+ */
+interface IncidentTransaction {
+    loadOrCreate(input: {
+        incidentKey: string;
+        occurrence: OperationalIncidentOccurrenceV1;
+    }): Promise<IncidentSnapshot & {
+        newlyCreated: boolean;
+    }>;
+    insertOccurrenceIfNew(input: {
+        incidentKey: string;
+        occurrence: OperationalIncidentOccurrenceV1;
+    }): Promise<boolean>;
+    recordOccurrence(input: {
+        incidentKey: string;
+        occurrence: OperationalIncidentOccurrenceV1;
+        reopen: boolean;
+        newlyCreated: boolean;
+    }): Promise<IncidentSnapshot>;
+    /** Optional, safe internal support projection; at most one per incident key. */
+    notifySupportOnce?(input: {
+        incidentKey: string;
+        occurrence: OperationalIncidentOccurrenceV1;
+    }): Promise<void>;
+}
+interface IncidentPersistence {
+    transactionForKey<T>(key: string, fn: (tx: IncidentTransaction) => Promise<T>): Promise<T>;
+}
+interface IncidentReporterLogger {
+    error(event: string, fields: Record<string, unknown>): void;
+}
+/** Reporter never turns an operational-notification failure into the producer's failure. */
+declare function createOperationalIncidentReporter(options: {
+    persistence: IncidentPersistence;
+    logger: IncidentReporterLogger;
+    notifySupport?: boolean;
+}): {
+    report(raw: unknown): Promise<IncidentReportResult | null>;
+};
+
+/** A deliberately small interface; the application's Prisma transaction client supplies it. */
+interface OperationalIncidentSqlClient {
+    $queryRawUnsafe<T = unknown>(query: string, ...parameters: unknown[]): Promise<T>;
+}
+interface OperationalIncidentPrismaClient {
+    $transaction<T>(fn: (tx: OperationalIncidentSqlClient) => Promise<T>, options?: {
+        maxWait?: number;
+        timeout?: number;
+        isolationLevel?: "Serializable";
+    }): Promise<T>;
+}
+/** Optional merchant-support projection. This callback MUST use the supplied transaction. */
+type OperationalIncidentSupportWriter = (input: {
+    tx: OperationalIncidentSqlClient;
+    incidentId: string;
+    incidentKey: string;
+    occurrence: OperationalIncidentOccurrenceV1;
+}) => Promise<void>;
+/**
+ * PostgreSQL/Prisma adapter. No global Prisma client or credentials are created.
+ * All writes and an optional support projection occur within a single transaction.
+ * Uses a per-key transaction advisory lock and a row lock for cross-process safety.
+ */
+declare function createPrismaOperationalIncidentPersistence(options: {
+    prisma: OperationalIncidentPrismaClient;
+    supportWriter?: OperationalIncidentSupportWriter;
+    maxAttempts?: number;
+}): IncidentPersistence;
+
+declare const OPERATIONAL_INCIDENT_CONTRACT_VERSION: "operational-incident.v1";
+declare const OperationalIncidentOccurrenceV1Schema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"operational-incident.v1">;
+    sourceService: z.ZodString;
+    environment: z.ZodEnum<{
+        local: "local";
+        development: "development";
+        test: "test";
+        staging: "staging";
+        production: "production";
+    }>;
+    category: z.ZodString;
+    reasonCode: z.ZodString;
+    resourceKey: z.ZodString;
+    shopId: z.ZodNullable<z.ZodString>;
+    severity: z.ZodEnum<{
+        LOW: "LOW";
+        MEDIUM: "MEDIUM";
+        HIGH: "HIGH";
+        CRITICAL: "CRITICAL";
+    }>;
+    occurrenceId: z.ZodString;
+    correlationId: z.ZodString;
+    occurredAt: z.ZodISODateTime;
+}, z.core.$strict>;
+type OperationalIncidentOccurrenceV1 = z.infer<typeof OperationalIncidentOccurrenceV1Schema>;
+declare function parseOperationalIncidentOccurrenceV1(input: unknown): OperationalIncidentOccurrenceV1;
+declare function createOperationalIncidentKey(input: Pick<OperationalIncidentOccurrenceV1, "sourceService" | "environment" | "category" | "reasonCode" | "resourceKey" | "shopId">): string;
+
+export { type IncidentPersistence, type IncidentReportResult, type IncidentReporterLogger, type IncidentSnapshot, type IncidentTransaction, OPERATIONAL_INCIDENT_CONTRACT_VERSION, type OperationalIncidentOccurrenceV1, OperationalIncidentOccurrenceV1Schema, type OperationalIncidentPrismaClient, type OperationalIncidentSqlClient, type OperationalIncidentSupportWriter, createOperationalIncidentKey, createOperationalIncidentReporter, createPrismaOperationalIncidentPersistence, parseOperationalIncidentOccurrenceV1 };

package/dist/incidents/index.js

@@ -0,0 +1,264 @@
+// src/incidents/index.ts
+import { createHash } from "crypto";
+import { z } from "zod";
+
+// src/incidents/reporter.ts
+function createOperationalIncidentReporter(options) {
+  return {
+    async report(raw) {
+      let occurrence;
+      try {
+        occurrence = parseOperationalIncidentOccurrenceV1(raw);
+      } catch {
+        options.logger.error("operational_incident.invalid_occurrence", {});
+        return null;
+      }
+      const incidentKey = createOperationalIncidentKey({
+        sourceService: occurrence.sourceService,
+        environment: occurrence.environment,
+        category: occurrence.category,
+        reasonCode: occurrence.reasonCode,
+        resourceKey: occurrence.resourceKey,
+        shopId: occurrence.shopId
+      });
+      try {
+        return await options.persistence.transactionForKey(incidentKey, async (tx) => {
+          const current = await tx.loadOrCreate({ incidentKey, occurrence });
+          const recorded = await tx.insertOccurrenceIfNew({ incidentKey, occurrence });
+          if (!recorded) {
+            return {
+              incidentKey,
+              recorded: false,
+              occurrenceCount: current.occurrenceCount,
+              status: current.status
+            };
+          }
+          const updated = await tx.recordOccurrence({
+            incidentKey,
+            occurrence,
+            reopen: current.status === "RESOLVED",
+            newlyCreated: current.newlyCreated
+          });
+          if (options.notifySupport && occurrence.shopId !== null && tx.notifySupportOnce) {
+            await tx.notifySupportOnce({ incidentKey, occurrence });
+          }
+          return {
+            incidentKey,
+            recorded: true,
+            occurrenceCount: updated.occurrenceCount,
+            status: "OPEN"
+          };
+        });
+      } catch {
+        options.logger.error("operational_incident.report_failed", {
+          incidentKey,
+          sourceService: occurrence.sourceService,
+          environment: occurrence.environment,
+          occurrenceId: occurrence.occurrenceId
+        });
+        return null;
+      }
+    }
+  };
+}
+
+// src/incidents/postgres.ts
+import { randomUUID } from "crypto";
+async function rows(tx, statement, ...params) {
+  return tx.$queryRawUnsafe(statement, ...params);
+}
+function snapshot(row) {
+  return {
+    incidentKey: row.incidentKey,
+    status: row.status,
+    occurrenceCount: row.occurrenceCount,
+    lastOccurredAt: row.lastOccurredAt
+  };
+}
+var PgIncidentTransaction = class {
+  constructor(tx, supportWriter) {
+    this.tx = tx;
+    this.supportWriter = supportWriter;
+  }
+  tx;
+  supportWriter;
+  incidentId = null;
+  newIncident = false;
+  async loadOrCreate({ incidentKey, occurrence }) {
+    const inserted = await rows(
+      this.tx,
+      `
+      INSERT INTO support."OperationalIncident" (
+        "id", "incidentKey", "sourceService", "environment", "category", "reasonCode",
+        "resourceKey", "shopId", "severity", "status", "occurrenceCount",
+        "firstOccurredAt", "lastOccurredAt", "lastCorrelationId")
+      VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,'OPEN',1,$10::timestamptz,$10::timestamptz,$11)
+      ON CONFLICT ("incidentKey") DO NOTHING RETURNING *`,
+      randomUUID(),
+      incidentKey,
+      occurrence.sourceService,
+      occurrence.environment,
+      occurrence.category,
+      occurrence.reasonCode,
+      occurrence.resourceKey,
+      occurrence.shopId,
+      occurrence.severity,
+      occurrence.occurredAt,
+      occurrence.correlationId
+    );
+    this.newIncident = inserted.length > 0;
+    const found = await rows(
+      this.tx,
+      `SELECT * FROM support."OperationalIncident" WHERE "incidentKey" = $1 FOR UPDATE`,
+      incidentKey
+    );
+    if (found.length !== 1) throw new Error("incident row not found after upsert");
+    this.incidentId = found[0].id;
+    return { ...snapshot(found[0]), newlyCreated: this.newIncident };
+  }
+  async insertOccurrenceIfNew({ incidentKey, occurrence }) {
+    if (!this.incidentId) throw new Error("incident not loaded");
+    const created = await rows(
+      this.tx,
+      `
+      INSERT INTO support."OperationalIncidentEvent"
+        ("id", "incidentId", "eventType", "correlationId", "occurredAt")
+      VALUES ($1::uuid, $2, 'OCCURRED', $3, $4::timestamptz)
+      ON CONFLICT ("id") DO NOTHING RETURNING "id"`,
+      occurrence.occurrenceId,
+      this.incidentId,
+      occurrence.correlationId,
+      occurrence.occurredAt
+    );
+    if (!created.length) {
+      if (this.newIncident) throw new Error("duplicate occurrence cannot create new incident");
+      const existing = await rows(this.tx, `
+        SELECT i."incidentKey" FROM support."OperationalIncidentEvent" e
+        JOIN support."OperationalIncident" i ON i."id" = e."incidentId"
+        WHERE e."id" = $1::uuid`, occurrence.occurrenceId);
+      if (existing.length !== 1 || existing[0].incidentKey !== incidentKey) {
+        throw new Error("occurrence already belongs to another incident");
+      }
+      return false;
+    }
+    return true;
+  }
+  async recordOccurrence({ incidentKey, occurrence, reopen, newlyCreated }) {
+    if (!this.incidentId) throw new Error("incident not loaded");
+    if (reopen) {
+      await rows(
+        this.tx,
+        `INSERT INTO support."OperationalIncidentEvent"
+        ("id", "incidentId", "eventType", "correlationId", "occurredAt")
+        VALUES ($1::uuid,$2,'REOPENED',$3,$4::timestamptz)`,
+        randomUUID(),
+        this.incidentId,
+        occurrence.correlationId,
+        occurrence.occurredAt
+      );
+    }
+    const updated = await rows(
+      this.tx,
+      `
+      UPDATE support."OperationalIncident" SET
+        "occurrenceCount" = "occurrenceCount" + $2::integer,
+        "lastOccurredAt" = GREATEST("lastOccurredAt", $3::timestamptz),
+        "lastCorrelationId" = $4,
+        "severity" = $5,
+        "status" = 'OPEN', "resolvedAt" = NULL,
+        "resolvedByPlatformAdminId" = NULL, "resolutionNote" = NULL,
+        "revision" = "revision" + 1
+      WHERE "incidentKey" = $1 RETURNING *`,
+      incidentKey,
+      newlyCreated ? 0 : 1,
+      occurrence.occurredAt,
+      occurrence.correlationId,
+      occurrence.severity
+    );
+    if (updated.length !== 1) throw new Error("incident update failed");
+    return snapshot(updated[0]);
+  }
+  async notifySupportOnce(input) {
+    if (this.supportWriter && this.incidentId) await this.supportWriter({
+      tx: this.tx,
+      incidentId: this.incidentId,
+      incidentKey: input.incidentKey,
+      occurrence: input.occurrence
+    });
+  }
+};
+function retryable(error) {
+  const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+  return code === "P2034" || code === "40001" || code === "40P01";
+}
+function createPrismaOperationalIncidentPersistence(options) {
+  const maxAttempts = options.maxAttempts ?? 3;
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10) {
+    throw new Error("maxAttempts must be between 1 and 10");
+  }
+  return {
+    async transactionForKey(key, fn) {
+      for (let attempt = 1; ; attempt++) {
+        try {
+          return await options.prisma.$transaction(async (tx) => {
+            await rows(tx, `SELECT pg_advisory_xact_lock(hashtextextended($1::text, 0))::text AS acquired`, key);
+            return fn(new PgIncidentTransaction(tx, options.supportWriter));
+          }, { isolationLevel: "Serializable", timeout: 15e3 });
+        } catch (error) {
+          if (attempt >= maxAttempts || !retryable(error)) throw error;
+        }
+      }
+    }
+  };
+}
+
+// src/incidents/index.ts
+var OPERATIONAL_INCIDENT_CONTRACT_VERSION = "operational-incident.v1";
+var identifier = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+var smallIdentifier = z.string().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+var opaqueId = z.string().uuid();
+var OperationalIncidentOccurrenceV1Schema = z.strictObject({
+  contractVersion: z.literal(OPERATIONAL_INCIDENT_CONTRACT_VERSION),
+  sourceService: smallIdentifier,
+  environment: z.enum(["local", "development", "test", "staging", "production"]),
+  category: smallIdentifier,
+  reasonCode: identifier,
+  resourceKey: identifier,
+  shopId: z.string().min(1).max(128).nullable(),
+  severity: z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]),
+  occurrenceId: opaqueId,
+  correlationId: identifier,
+  occurredAt: z.iso.datetime({ offset: true })
+  // Deliberately no arbitrary metadata bag, message, headers or exception object.
+});
+function parseOperationalIncidentOccurrenceV1(input) {
+  return OperationalIncidentOccurrenceV1Schema.parse(input);
+}
+function createOperationalIncidentKey(input) {
+  const parsed = OperationalIncidentOccurrenceV1Schema.pick({
+    sourceService: true,
+    environment: true,
+    category: true,
+    reasonCode: true,
+    resourceKey: true,
+    shopId: true
+  }).parse(input);
+  return createHash("sha256").update(JSON.stringify([
+    "operational-incident-key.v1",
+    parsed.sourceService,
+    parsed.environment,
+    parsed.category,
+    parsed.reasonCode,
+    parsed.shopId,
+    parsed.resourceKey
+  ])).digest("hex");
+}
+export {
+  OPERATIONAL_INCIDENT_CONTRACT_VERSION,
+  OperationalIncidentOccurrenceV1Schema,
+  createOperationalIncidentKey,
+  createOperationalIncidentReporter,
+  createPrismaOperationalIncidentPersistence,
+  parseOperationalIncidentOccurrenceV1
+};
+//# sourceMappingURL=index.js.map

package/dist/incidents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/incidents/index.ts","../../src/incidents/reporter.ts","../../src/incidents/postgres.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { z } from \"zod\";\n\n// ARCH-033 v1: safe, internal-only occurrence envelope. Producer classifies actionability.\nexport const OPERATIONAL_INCIDENT_CONTRACT_VERSION = \"operational-incident.v1\" as const;\nconst identifier = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);\nconst smallIdentifier = z.string().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);\nconst opaqueId = z.string().uuid();\nexport const OperationalIncidentOccurrenceV1Schema = z.strictObject({\n  contractVersion: z.literal(OPERATIONAL_INCIDENT_CONTRACT_VERSION),\n  sourceService: smallIdentifier,\n  environment: z.enum([\"local\", \"development\", \"test\", \"staging\", \"production\"]),\n  category: smallIdentifier,\n  reasonCode: identifier,\n  resourceKey: identifier,\n  shopId: z.string().min(1).max(128).nullable(),\n  severity: z.enum([\"LOW\", \"MEDIUM\", \"HIGH\", \"CRITICAL\"]),\n  occurrenceId: opaqueId,\n  correlationId: identifier,\n  occurredAt: z.iso.datetime({ offset: true }),\n  // Deliberately no arbitrary metadata bag, message, headers or exception object.\n});\nexport type OperationalIncidentOccurrenceV1 = z.infer<typeof OperationalIncidentOccurrenceV1Schema>;\nexport function parseOperationalIncidentOccurrenceV1(input: unknown): OperationalIncidentOccurrenceV1 {\n  return OperationalIncidentOccurrenceV1Schema.parse(input);\n}\nexport function createOperationalIncidentKey(input: Pick<OperationalIncidentOccurrenceV1,\n  \"sourceService\" | \"environment\" | \"category\" | \"reasonCode\" | \"resourceKey\" | \"shopId\">): string {\n  const parsed = OperationalIncidentOccurrenceV1Schema.pick({\n    sourceService: true, environment: true, category: true, reasonCode: true, resourceKey: true, shopId: true,\n  }).parse(input);\n  return createHash(\"sha256\").update(JSON.stringify([\n    \"operational-incident-key.v1\", parsed.sourceService, parsed.environment, parsed.category,\n    parsed.reasonCode, parsed.shopId, parsed.resourceKey,\n  ])).digest(\"hex\");\n}\n\nexport { createOperationalIncidentReporter } from \"./reporter.js\";\nexport type {\n  IncidentPersistence, IncidentTransaction, IncidentSnapshot, IncidentReportResult,\n  IncidentReporterLogger,\n} from \"./reporter.js\";\n\nexport { createPrismaOperationalIncidentPersistence } from \"./postgres.js\";\nexport type { OperationalIncidentPrismaClient, OperationalIncidentSqlClient, OperationalIncidentSupportWriter } from \"./postgres.js\";\n","import { createOperationalIncidentKey, parseOperationalIncidentOccurrenceV1 } from \"./index.js\";\nimport type { OperationalIncidentOccurrenceV1 } from \"./index.js\";\n\n/** Durable outcome of one occurrence; duplicate deliveries have no side effects. */\nexport type IncidentReportResult = {\n  incidentKey: string;\n  recorded: boolean;\n  occurrenceCount: number;\n  status: \"OPEN\" | \"RESOLVED\";\n};\n\nexport type IncidentSnapshot = {\n  incidentKey: string;\n  status: \"OPEN\" | \"RESOLVED\";\n  occurrenceCount: number;\n  lastOccurredAt: Date;\n};\n\n/**\n * Transactional persistence contract, implemented by the consuming service.\n * transactionForKey MUST serialize operations for the same key across processes,\n * INCLUDING first creation; the callback must be retried on a conflicting insert.\n * insertOccurrenceIfNew MUST enforce a GLOBAL unique occurrenceId (not only per\n * incident); an occurrenceId already belonging to another key MUST throw.\n * On creation loadOrCreate MUST initialise occurrenceCount=1; recordOccurrence\n * MUST NOT increment that first occurrence again. If a duplicate is encountered\n * when newlyCreated=true, the transaction MUST fail and roll back creation.\n * Every operation in this port, including optional support notification, MUST\n * participate in the SAME database transaction and roll back together.\n */\nexport interface IncidentTransaction {\n  loadOrCreate(input: { incidentKey: string; occurrence: OperationalIncidentOccurrenceV1 }): Promise<IncidentSnapshot & { newlyCreated: boolean }>;\n  insertOccurrenceIfNew(input: { incidentKey: string; occurrence: OperationalIncidentOccurrenceV1 }): Promise<boolean>;\n  recordOccurrence(input: {\n    incidentKey: string;\n    occurrence: OperationalIncidentOccurrenceV1;\n    reopen: boolean;\n    newlyCreated: boolean;\n  }): Promise<IncidentSnapshot>;\n  /** Optional, safe internal support projection; at most one per incident key. */\n  notifySupportOnce?(input: { incidentKey: string; occurrence: OperationalIncidentOccurrenceV1 }): Promise<void>;\n}\nexport interface IncidentPersistence {\n  transactionForKey<T>(key: string, fn: (tx: IncidentTransaction) => Promise<T>): Promise<T>;\n}\nexport interface IncidentReporterLogger {\n  error(event: string, fields: Record<string, unknown>): void;\n}\n\n/** Reporter never turns an operational-notification failure into the producer's failure. */\nexport function createOperationalIncidentReporter(options: {\n  persistence: IncidentPersistence;\n  logger: IncidentReporterLogger;\n  notifySupport?: boolean;\n}) {\n  return {\n    async report(raw: unknown): Promise<IncidentReportResult | null> {\n      let occurrence: OperationalIncidentOccurrenceV1;\n      try {\n        occurrence = parseOperationalIncidentOccurrenceV1(raw);\n      } catch {\n        // Fail closed, and do not log potentially sensitive invalid payloads.\n        options.logger.error(\"operational_incident.invalid_occurrence\", {});\n        return null;\n      }\n      const incidentKey = createOperationalIncidentKey({\n        sourceService: occurrence.sourceService, environment: occurrence.environment,\n        category: occurrence.category, reasonCode: occurrence.reasonCode,\n        resourceKey: occurrence.resourceKey, shopId: occurrence.shopId,\n      });\n      try {\n        return await options.persistence.transactionForKey(incidentKey, async (tx) => {\n          const current = await tx.loadOrCreate({ incidentKey, occurrence });\n          const recorded = await tx.insertOccurrenceIfNew({ incidentKey, occurrence });\n          if (!recorded) {\n            return { incidentKey, recorded: false, occurrenceCount: current.occurrenceCount,\n              status: current.status };\n          }\n          const updated = await tx.recordOccurrence({ incidentKey, occurrence,\n            reopen: current.status === \"RESOLVED\", newlyCreated: current.newlyCreated });\n          if (options.notifySupport && occurrence.shopId !== null && tx.notifySupportOnce) {\n            await tx.notifySupportOnce({ incidentKey, occurrence });\n          }\n          return { incidentKey, recorded: true, occurrenceCount: updated.occurrenceCount,\n            status: \"OPEN\" as const };\n        });\n      } catch {\n        options.logger.error(\"operational_incident.report_failed\", {\n          incidentKey, sourceService: occurrence.sourceService,\n          environment: occurrence.environment, occurrenceId: occurrence.occurrenceId,\n        });\n        return null;\n      }\n    },\n  };\n}\n","import { randomUUID } from \"node:crypto\";\nimport type { OperationalIncidentOccurrenceV1 } from \"./index.js\";\nimport type { IncidentPersistence, IncidentSnapshot, IncidentTransaction } from \"./reporter.js\";\n\n/** A deliberately small interface; the application's Prisma transaction client supplies it. */\nexport interface OperationalIncidentSqlClient {\n  $queryRawUnsafe<T = unknown>(query: string, ...parameters: unknown[]): Promise<T>;\n}\nexport interface OperationalIncidentPrismaClient {\n  $transaction<T>(fn: (tx: OperationalIncidentSqlClient) => Promise<T>, options?: {\n    maxWait?: number; timeout?: number; isolationLevel?: \"Serializable\";\n  }): Promise<T>;\n}\n\n/** Optional merchant-support projection. This callback MUST use the supplied transaction. */\nexport type OperationalIncidentSupportWriter = (input: {\n  tx: OperationalIncidentSqlClient;\n  incidentId: string;\n  incidentKey: string;\n  occurrence: OperationalIncidentOccurrenceV1;\n}) => Promise<void>;\n\ninterface IncidentRow {\n  id: string;\n  incidentKey: string;\n  status: \"OPEN\" | \"RESOLVED\";\n  occurrenceCount: number;\n  lastOccurredAt: Date;\n}\n\nasync function rows<T>(tx: OperationalIncidentSqlClient, statement: string, ...params: unknown[]): Promise<T[]> {\n  return tx.$queryRawUnsafe<T[]>(statement, ...params);\n}\n\nfunction snapshot(row: IncidentRow): IncidentSnapshot {\n  return { incidentKey: row.incidentKey, status: row.status,\n    occurrenceCount: row.occurrenceCount, lastOccurredAt: row.lastOccurredAt };\n}\n\nclass PgIncidentTransaction implements IncidentTransaction {\n  private incidentId: string | null = null;\n  private newIncident = false;\n  constructor(private readonly tx: OperationalIncidentSqlClient,\n    private readonly supportWriter?: OperationalIncidentSupportWriter) {}\n\n  async loadOrCreate({ incidentKey, occurrence }: {\n    incidentKey: string; occurrence: OperationalIncidentOccurrenceV1;\n  }): Promise<IncidentSnapshot & { newlyCreated: boolean }> {\n    const inserted = await rows<IncidentRow>(this.tx, `\n      INSERT INTO support.\"OperationalIncident\" (\n        \"id\", \"incidentKey\", \"sourceService\", \"environment\", \"category\", \"reasonCode\",\n        \"resourceKey\", \"shopId\", \"severity\", \"status\", \"occurrenceCount\",\n        \"firstOccurredAt\", \"lastOccurredAt\", \"lastCorrelationId\")\n      VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,'OPEN',1,$10::timestamptz,$10::timestamptz,$11)\n      ON CONFLICT (\"incidentKey\") DO NOTHING RETURNING *`,\n      randomUUID(), incidentKey, occurrence.sourceService, occurrence.environment,\n      occurrence.category, occurrence.reasonCode, occurrence.resourceKey,\n      occurrence.shopId, occurrence.severity, occurrence.occurredAt, occurrence.correlationId);\n    this.newIncident = inserted.length > 0;\n    const found = await rows<IncidentRow>(this.tx,\n      `SELECT * FROM support.\"OperationalIncident\" WHERE \"incidentKey\" = $1 FOR UPDATE`, incidentKey);\n    if (found.length !== 1) throw new Error(\"incident row not found after upsert\");\n    this.incidentId = found[0]!.id;\n    return { ...snapshot(found[0]!), newlyCreated: this.newIncident };\n  }\n\n  async insertOccurrenceIfNew({ incidentKey, occurrence }: {\n    incidentKey: string; occurrence: OperationalIncidentOccurrenceV1;\n  }): Promise<boolean> {\n    if (!this.incidentId) throw new Error(\"incident not loaded\");\n    const created = await rows<{ id: string }>(this.tx, `\n      INSERT INTO support.\"OperationalIncidentEvent\"\n        (\"id\", \"incidentId\", \"eventType\", \"correlationId\", \"occurredAt\")\n      VALUES ($1::uuid, $2, 'OCCURRED', $3, $4::timestamptz)\n      ON CONFLICT (\"id\") DO NOTHING RETURNING \"id\"`,\n      occurrence.occurrenceId, this.incidentId, occurrence.correlationId, occurrence.occurredAt);\n    if (!created.length) {\n      if (this.newIncident) throw new Error(\"duplicate occurrence cannot create new incident\");\n      const existing = await rows<{ incidentKey: string }>(this.tx, `\n        SELECT i.\"incidentKey\" FROM support.\"OperationalIncidentEvent\" e\n        JOIN support.\"OperationalIncident\" i ON i.\"id\" = e.\"incidentId\"\n        WHERE e.\"id\" = $1::uuid`, occurrence.occurrenceId);\n      if (existing.length !== 1 || existing[0]!.incidentKey !== incidentKey) {\n        throw new Error(\"occurrence already belongs to another incident\");\n      }\n      return false;\n    }\n    return true;\n  }\n\n  async recordOccurrence({ incidentKey, occurrence, reopen, newlyCreated }: {\n    incidentKey: string; occurrence: OperationalIncidentOccurrenceV1;\n    reopen: boolean; newlyCreated: boolean;\n  }): Promise<IncidentSnapshot> {\n    if (!this.incidentId) throw new Error(\"incident not loaded\");\n    if (reopen) {\n      await rows(this.tx, `INSERT INTO support.\"OperationalIncidentEvent\"\n        (\"id\", \"incidentId\", \"eventType\", \"correlationId\", \"occurredAt\")\n        VALUES ($1::uuid,$2,'REOPENED',$3,$4::timestamptz)`,\n        randomUUID(), this.incidentId, occurrence.correlationId, occurrence.occurredAt);\n    }\n    const updated = await rows<IncidentRow>(this.tx, `\n      UPDATE support.\"OperationalIncident\" SET\n        \"occurrenceCount\" = \"occurrenceCount\" + $2::integer,\n        \"lastOccurredAt\" = GREATEST(\"lastOccurredAt\", $3::timestamptz),\n        \"lastCorrelationId\" = $4,\n        \"severity\" = $5,\n        \"status\" = 'OPEN', \"resolvedAt\" = NULL,\n        \"resolvedByPlatformAdminId\" = NULL, \"resolutionNote\" = NULL,\n        \"revision\" = \"revision\" + 1\n      WHERE \"incidentKey\" = $1 RETURNING *`, incidentKey,\n      newlyCreated ? 0 : 1, occurrence.occurredAt, occurrence.correlationId, occurrence.severity);\n    if (updated.length !== 1) throw new Error(\"incident update failed\");\n    return snapshot(updated[0]!);\n  }\n\n  async notifySupportOnce(input: { incidentKey: string; occurrence: OperationalIncidentOccurrenceV1 }): Promise<void> {\n    if (this.supportWriter && this.incidentId) await this.supportWriter({\n      tx: this.tx, incidentId: this.incidentId,\n      incidentKey: input.incidentKey, occurrence: input.occurrence,\n    });\n  }\n}\n\nfunction retryable(error: unknown): boolean {\n  const code = typeof error === \"object\" && error !== null && \"code\" in error\n    ? (error as { code?: unknown }).code : undefined;\n  return code === \"P2034\" || code === \"40001\" || code === \"40P01\";\n}\n\n/**\n * PostgreSQL/Prisma adapter. No global Prisma client or credentials are created.\n * All writes and an optional support projection occur within a single transaction.\n * Uses a per-key transaction advisory lock and a row lock for cross-process safety.\n */\nexport function createPrismaOperationalIncidentPersistence(options: {\n  prisma: OperationalIncidentPrismaClient;\n  supportWriter?: OperationalIncidentSupportWriter;\n  maxAttempts?: number;\n}): IncidentPersistence {\n  const maxAttempts = options.maxAttempts ?? 3;\n  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10) {\n    throw new Error(\"maxAttempts must be between 1 and 10\");\n  }\n  return {\n    async transactionForKey<T>(key: string, fn: (tx: IncidentTransaction) => Promise<T>): Promise<T> {\n      for (let attempt = 1; ; attempt++) {\n        try {\n          return await options.prisma.$transaction(async (tx) => {\n            await rows(tx, `SELECT pg_advisory_xact_lock(hashtextextended($1::text, 0))::text AS acquired`, key);\n            return fn(new PgIncidentTransaction(tx, options.supportWriter));\n          }, { isolationLevel: \"Serializable\", timeout: 15000 });\n        } catch (error) {\n          if (attempt >= maxAttempts || !retryable(error)) throw error;\n        }\n      }\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modainteract/moda-interact-shared",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -95,6 +95,10 @@
     "./merchant-knowledge/node": {
       "types": "./dist/merchant-knowledge/node.d.ts",
       "import": "./dist/merchant-knowledge/node.js"
+    },
+    "./incidents": {
+      "types": "./dist/incidents/index.d.ts",
+      "import": "./dist/incidents/index.js"
     }
   },
   "files": [
@@ -114,7 +118,8 @@
     "prepack": "npm run build",
     "validate:commerce-entrypoints": "node scripts/validate-commerce-entrypoints.mjs",
     "validate:arch023-shared-entrypoints": "npm run build && node scripts/validate-arch023-shared-entrypoints.mjs",
-    "validate:arch024-model-entrypoints": "npm run build && node scripts/validate-arch024-model-entrypoints.mjs"
+    "validate:arch024-model-entrypoints": "npm run build && node scripts/validate-arch024-model-entrypoints.mjs",
+    "test:arch033-incidents:postgres": "node scripts/test-arch033-incidents-postgres.mjs"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",