@oondemand/oon-core-back 0.4.15 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/oon-core-back",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",
@@ -40,11 +40,13 @@
     ".": "./src/index.js"
   },
   "dependencies": {
+    "ajv": "^8.17.1",
     "axios": "^1.7.7",
     "cors": "^2.8.5",
     "dotenv": "^16.4.5",
     "express": "^4.21.2",
     "helmet": "^8.0.0",
+    "handlebars": "^4.7.8",
     "mongoose": "^8.5.4",
     "morgan": "^1.10.0"
   },

package/src/api/core.routes.js

@@ -33,6 +33,7 @@ function appSummary() {
     appKind: manifest.appKind,
     modules: manifest.modules,
     capabilities: manifest.capabilities,
+    capabilitySettings: manifest.capabilitySettings,
     compatibility: manifest.compatibility,
   };
 }

package/src/boot/createApp.js

@@ -17,6 +17,7 @@ const statusRoutes = require("../api/status.routes");
 const authRoutes = require("../api/auth.routes");
 const activationRoutes = require("../api/activation.routes");
 const activationGuard = require("../core/middlewares/activationGuard");
+const transactionalEmail = require("../capabilities/transactionalEmail");
 
 function createApp() {
   const app = express();
@@ -34,6 +35,7 @@ function createApp() {
   app.use("/auth", authRoutes);
   app.use("/core", accessRoutes);
   app.use("/core", coreRoutes);
+  if (transactionalEmail.enabled()) app.use("/core/transactional-email", transactionalEmail.buildRouter());
 
   if (integrationsEnabled(ctx.config)) {
     const integrationRouter = buildIntegrationRouter();

package/src/boot/loadCentral.js

@@ -39,6 +39,7 @@ const APP_CONFIG_KEYS = new Set([
   "activation",
   "modules",
   "capabilities",
+  "capabilitySettings",
 ]);
 
 function assertConfigBoundary(config, appManifest) {
@@ -58,6 +59,16 @@ function assertConfigBoundary(config, appManifest) {
       message: "autenticação de Centrais member/portal é fornecida pelo OonCore.",
     });
   }
+  if (Object.prototype.hasOwnProperty.call(config, "activationHooks")) {
+    if (appManifest.appKind !== "root-central" || !config.activationHooks || typeof config.activationHooks !== "object") {
+      issues.push({ path: "central.config.js.activationHooks", message: "é permitido somente para a root-central." });
+    } else {
+      const allowedHooks = new Set(["hasActiveRootApp", "rootBootstrap"]);
+      for (const [key, value] of Object.entries(config.activationHooks)) {
+        if (!allowedHooks.has(key) || typeof value !== "function") issues.push({ path: `central.config.js.activationHooks.${key}`, message: "hook de runtime não suportado." });
+      }
+    }
+  }
   if (issues.length) throw new AppManifestError("central.config.js viola a fronteira declarativa.", issues);
 }
 
@@ -73,7 +84,9 @@ function loadCentral(cwd = process.cwd()) {
     const exported = require(configPath);
     const config = typeof exported === "function" ? exported() : exported;
     assertConfigBoundary(config, appManifest);
-    ctx.setConfig(config);
+    const { activationHooks, ...runtimeConfig } = config || {};
+    ctx.setConfig(runtimeConfig);
+    if (activationHooks) ctx.setConfig({ activation: { ...ctx.config.activation, ...activationHooks } });
   }
 
   const domainManifestPath = path.join(cwd, DOMAIN_MANIFEST_FILENAME);

package/src/boot/startServer.js

@@ -2,6 +2,7 @@ const ctx = require("../core/context");
 const { connectDB } = require("./database");
 const { createApp } = require("./createApp");
 const { loadCentral } = require("./loadCentral");
+const transactionalEmail = require("../capabilities/transactionalEmail");
 
 /**
  * Sobe a aplicação completa: carrega a Central do consumidor, conecta no
@@ -13,6 +14,7 @@ const { loadCentral } = require("./loadCentral");
 async function start({ cwd = process.cwd(), listen = true } = {}) {
   loadCentral(cwd);
   await connectDB();
+  await transactionalEmail.initialize();
   const app = createApp();
 
   if (!listen) return { app };
@@ -23,6 +25,8 @@ async function start({ cwd = process.cwd(), listen = true } = {}) {
       console.log("****************************************************************");
       console.log(`${ctx.config.serviceName} rodando na porta ${port} e conectado ao MongoDB`);
       console.log("****************************************************************");
+      const stop = () => transactionalEmail.stopWorker();
+      server.once("close", stop);
       resolve({ app, server });
     });
   });

package/src/capabilities/index.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const pdfRendering = require("./pdfRendering");
+const transactionalEmail = require("./transactionalEmail");
 
 const pdf = Object.freeze({ render: pdfRendering.render });
 
@@ -9,4 +10,6 @@ module.exports = Object.freeze({
   pdfRendering: pdf,
   configurePdfRendering: pdfRendering.configurePdfRendering,
   PdfRenderingError: pdfRendering.PdfRenderingError,
+  transactionalEmail,
+  TransactionalEmailError: transactionalEmail.TransactionalEmailError,
 });

package/src/capabilities/transactionalEmail/bootstrap.js

@@ -0,0 +1,37 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const ctx = require("../../core/context");
+const { getModels, syncIndexes } = require("./models");
+const { capabilityConfig, appScopeKey, enabled } = require("./scope");
+const { validateDefinition, contentHash } = require("./templates");
+const { TransactionalEmailError } = require("./errors");
+
+function definitionPath(relative) {
+  const root = path.dirname(ctx.config.appManifestPath || path.join(process.cwd(), "central.app.json"));
+  const resolved = path.resolve(root, relative);
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) throw new TransactionalEmailError("Template escapou da raiz do App.", { code: "EMAIL_TEMPLATE_PATH_INVALID" });
+  return resolved;
+}
+async function bootstrap() {
+  if (!enabled()) return { enabled: false, created: [], preserved: [] };
+  await syncIndexes();
+  const { Template } = getModels();
+  const scopeKey = appScopeKey();
+  const result = { enabled: true, scopeKey, created: [], preserved: [] };
+  for (const declared of capabilityConfig().templates || []) {
+    let input; try { input = JSON.parse(fs.readFileSync(definitionPath(declared.definition), "utf8")); } catch (cause) { throw new TransactionalEmailError(`Não foi possível carregar ${declared.definition}: ${cause.message}`, { code: "EMAIL_TEMPLATE_DEFINITION_UNAVAILABLE" }); }
+    const definition = validateDefinition({ ...input, code: declared.code, initialStatus: declared.initialStatus }, declared.code);
+    try {
+      const created = await Template.create({ scopeKey, code: definition.code, version: 1, name: definition.name, description: definition.description, subject: definition.subject, htmlContent: definition.htmlContent, textContent: definition.textContent, variablesSchema: definition.variablesSchema, locale: definition.locale, attachmentsPolicy: definition.attachmentsPolicy, status: definition.initialStatus, origin: "manifest", contentHash: contentHash(definition), activatedAt: definition.initialStatus === "active" ? new Date() : undefined });
+      result.created.push({ code: created.code, version: created.version });
+    } catch (error) {
+      if (error?.code !== 11000) throw error;
+      result.preserved.push({ code: declared.code });
+    }
+  }
+  console.log(JSON.stringify({ event: "transactionalEmail.bootstrap", ...result }));
+  return result;
+}
+module.exports = { bootstrap, definitionPath };

package/src/capabilities/transactionalEmail/errors.js

@@ -0,0 +1,13 @@
+"use strict";
+
+const GenericError = require("../../core/errors/GenericError");
+
+class TransactionalEmailError extends GenericError {
+  constructor(message, { code = "TRANSACTIONAL_EMAIL_ERROR", statusCode = 422, retryable = false, details } = {}) {
+    super(message, { code, statusCode, details });
+    this.name = "TransactionalEmailError";
+    this.retryable = retryable;
+  }
+}
+
+module.exports = { TransactionalEmailError };

package/src/capabilities/transactionalEmail/index.js

@@ -0,0 +1,11 @@
+"use strict";
+
+const service = require("./service");
+const worker = require("./worker");
+const scope = require("./scope");
+const { bootstrap } = require("./bootstrap");
+const { buildRouter } = require("./routes");
+const { TransactionalEmailError } = require("./errors");
+
+async function initialize() { if (!scope.enabled()) return { enabled: false }; const result = await bootstrap(); worker.startWorker(); return result; }
+module.exports = { ...service, ...scope, ...worker, initialize, bootstrap, buildRouter, TransactionalEmailError };

package/src/capabilities/transactionalEmail/models.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const mongoose = require("mongoose");
+
+const envelope = { keyId: String, version: Number, algorithm: String, iv: String, authTag: String, ciphertext: String };
+const common = { scopeKey: { type: String, required: true, index: true } };
+
+function model(name, schema, collection) { return mongoose.models[name] || mongoose.model(name, schema, collection); }
+function getModels() {
+  const ConfigSchema = new mongoose.Schema({ ...common, provider: { type: String, default: "sendgrid" }, encryptedEnvelope: envelope, previousEnvelopes: [envelope], apiKeyMasked: String, fingerprint: String, credentialConfigured: Boolean, senderEmail: String, senderName: String, replyTo: String, enabled: { type: Boolean, default: false }, status: String, connectionStatus: String, lastTestAt: Date, lastError: String, configuredBy: String }, { timestamps: true, strict: true });
+  ConfigSchema.index({ scopeKey: 1, provider: 1 }, { unique: true });
+  const TemplateSchema = new mongoose.Schema({ ...common, code: String, version: Number, name: String, description: String, subject: String, htmlContent: String, textContent: String, variablesSchema: mongoose.Schema.Types.Mixed, locale: String, attachmentsPolicy: mongoose.Schema.Types.Mixed, status: { type: String, enum: ["draft", "active", "archived"] }, origin: { type: String, enum: ["manifest", "interface"] }, contentHash: String, createdBy: String, activatedAt: Date }, { timestamps: true, strict: true });
+  TemplateSchema.index({ scopeKey: 1, code: 1, version: 1 }, { unique: true });
+  TemplateSchema.index({ scopeKey: 1, code: 1, status: 1 }, { unique: true, partialFilterExpression: { status: "active" } });
+  const DispatchSchema = new mongoose.Schema({ ...common, templateCode: String, templateVersion: Number, protectedPayload: envelope, payloadExpiresAt: Date, recipientFingerprint: String, idempotencyKey: String, correlationId: String, providerMessageId: String, status: { type: String, enum: ["accepted", "processing", "provider_accepted", "failed", "dead_letter", "cancelled"] }, attempts: { type: Number, default: 0 }, maxAttempts: { type: Number, default: 5 }, nextRetryAt: Date, leaseOwner: String, leaseExpiresAt: Date, sentAt: Date, failedAt: Date, lastError: { code: String, message: String, retryable: Boolean }, retryAudit: [{ actorId: String, at: Date, previousStatus: String }] }, { timestamps: true, strict: true });
+  DispatchSchema.index({ scopeKey: 1, idempotencyKey: 1 }, { unique: true });
+  DispatchSchema.index({ status: 1, nextRetryAt: 1, leaseExpiresAt: 1 });
+  return { Config: model("OonTransactionalEmailConfig", ConfigSchema, "oon_transactional_email_configs"), Template: model("OonEmailTemplate", TemplateSchema, "oon_email_templates"), Dispatch: model("OonEmailDispatch", DispatchSchema, "oon_email_dispatches") };
+}
+async function syncIndexes() { const models = getModels(); return Promise.all(Object.values(models).map((entry) => entry.syncIndexes())); }
+module.exports = { getModels, syncIndexes };

package/src/capabilities/transactionalEmail/providers.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const { TransactionalEmailError } = require("./errors");
+
+function providerError(response, body) {
+  const retryable = response.status === 429 || response.status >= 500;
+  return new TransactionalEmailError(retryable ? "SendGrid temporariamente indisponível." : "SendGrid recusou a solicitação.", { code: retryable ? "EMAIL_PROVIDER_TRANSIENT" : "EMAIL_PROVIDER_REJECTED", statusCode: retryable ? 503 : 422, retryable, details: { providerStatus: response.status, providerCode: body?.errors?.[0]?.field } });
+}
+async function request(path, apiKey, options = {}) {
+  const response = await (options.fetchImpl || globalThis.fetch)(`https://api.sendgrid.com/v3${path}`, { ...options, headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json", ...(options.headers || {}) } });
+  let body; try { body = await response.json(); } catch { body = undefined; }
+  if (!response.ok) throw providerError(response, body);
+  return { response, body };
+}
+async function validateCredential(apiKey, options = {}) { await request("/scopes", apiKey, { fetchImpl: options.fetchImpl }); return { valid: true }; }
+async function send(message, apiKey, options = {}) {
+  const payload = { personalizations: [{ to: message.to.map((email) => ({ email })) }], from: { email: message.from.email, name: message.from.name || undefined }, reply_to: message.replyTo ? { email: message.replyTo } : undefined, subject: message.subject, content: [{ type: "text/plain", value: message.text }, { type: "text/html", value: message.html }] };
+  const { response } = await request("/mail/send", apiKey, { method: "POST", body: JSON.stringify(payload), fetchImpl: options.fetchImpl });
+  return { providerMessageId: response.headers.get("x-message-id") || undefined };
+}
+module.exports = { sendgrid: { validateCredential, send } };

package/src/capabilities/transactionalEmail/routes.js

@@ -0,0 +1,27 @@
+"use strict";
+
+const express = require("express");
+const auth = require("../../core/middlewares/auth");
+const { requirePermission } = require("../../core/middlewares/permissions");
+const { asyncHandler } = require("../../core/utils/helpers");
+const service = require("./service");
+const worker = require("./worker");
+const { enabled } = require("./scope");
+const { keyring } = require("./secretStore");
+
+function context(req) { return { ...(req.accessContext || {}), userId: req.accessContext?.userId || req.usuario?.id, fetchImpl: req.app.locals.transactionalEmailFetch }; }
+function buildRouter() {
+  const router = express.Router(); router.use(auth);
+  router.get("/health", requirePermission("transactionalEmail.config.read"), asyncHandler(async (req, res) => { let secretStore = "active"; try { keyring(); } catch { secretStore = "degraded"; } const config = await service.getConfiguration(context(req)); const status = !config?.credentialConfigured ? "configuration_required" : secretStore === "degraded" || worker.health().status === "degraded" ? "degraded" : "active"; res.json({ declared: enabled(), status, secretStore, worker: worker.health(), configuration: config }); }));
+  router.get("/configuration", requirePermission("transactionalEmail.config.read"), asyncHandler(async (req, res) => res.json({ configuration: await service.getConfiguration(context(req)) })));
+  router.put("/configuration", requirePermission("transactionalEmail.config.manage"), asyncHandler(async (req, res) => res.json({ configuration: await service.saveConfiguration(req.body || {}, context(req)) })));
+  router.get("/templates", requirePermission("transactionalEmail.templates.read"), asyncHandler(async (req, res) => res.json({ results: await service.listTemplates(context(req)) })));
+  router.post("/templates/:code/versions", requirePermission("transactionalEmail.templates.manage"), asyncHandler(async (req, res) => res.status(201).json(await service.createTemplateVersion(req.params.code, req.body || {}, context(req)))));
+  router.post("/templates/:code/versions/:version/activate", requirePermission("transactionalEmail.templates.manage"), asyncHandler(async (req, res) => res.json(await service.activateTemplate(req.params.code, Number(req.params.version), context(req)))));
+  router.post("/templates/:code/versions/:version/archive", requirePermission("transactionalEmail.templates.manage"), asyncHandler(async (req, res) => res.json(await service.archiveTemplate(req.params.code, Number(req.params.version), context(req)))));
+  router.post("/templates/:code/test", requirePermission("transactionalEmail.templates.manage"), asyncHandler(async (req, res) => res.status(202).json(await service.testTemplate(req.params.code, req.body || {}, context(req)))));
+  router.get("/dispatches", requirePermission("transactionalEmail.dispatches.read"), asyncHandler(async (req, res) => res.json({ results: await service.listDispatches(context(req), req.query) })));
+  router.post("/dispatches/:id/retry", requirePermission("transactionalEmail.dispatches.retry"), asyncHandler(async (req, res) => res.json(await service.retryDispatch(req.params.id, context(req)))));
+  return router;
+}
+module.exports = { buildRouter };

package/src/capabilities/transactionalEmail/scope.js

@@ -0,0 +1,48 @@
+"use strict";
+
+const ctx = require("../../core/context");
+const { TransactionalEmailError } = require("./errors");
+
+function capabilityConfig(config = ctx.config) {
+  return config.capabilitySettings?.["core.transactional-email"] || config.appManifest?.capabilitySettings?.["core.transactional-email"];
+}
+
+function enabled(config = ctx.config) {
+  return config.capabilities?.includes("core.transactional-email") && capabilityConfig(config)?.enabled === true;
+}
+
+function appCode(context = {}, config = ctx.config) {
+  const runtimeCode = String(config.appCode || config.appManifest?.id || "").trim().toLowerCase();
+  const requestedCode = String(context.appCode || "").trim().toLowerCase();
+  if (requestedCode && runtimeCode && requestedCode !== runtimeCode) {
+    throw new TransactionalEmailError("O contexto não pertence a este App.", { code: "EMAIL_APP_SCOPE_DENIED", statusCode: 403 });
+  }
+  return runtimeCode;
+}
+
+function appScopeKey(context = {}, config = ctx.config) {
+  const code = appCode(context, config);
+  if (!code) throw new TransactionalEmailError("APP_CODE não resolvido para e-mail transacional.", { code: "EMAIL_APP_CONTEXT_REQUIRED", statusCode: 500 });
+  return `app:${code}`;
+}
+
+function tenantScopeKey(context = {}, config = ctx.config) {
+  const tenantId = String(context.tenantId || "").trim();
+  if (!tenantId) throw new TransactionalEmailError("Contexto de tenant obrigatório para e-mail transacional.", { code: "EMAIL_TENANT_CONTEXT_REQUIRED", statusCode: 403 });
+  return `${appScopeKey(context, config)}:tenant:${tenantId}`;
+}
+
+function requestedScopeKey(context = {}, config = ctx.config) {
+  const policy = capabilityConfig(config)?.scopePolicy || "app_only";
+  if (policy === "app_only") return appScopeKey(context, config);
+  if (policy === "tenant_required") return tenantScopeKey(context, config);
+  return context.tenantId ? tenantScopeKey(context, config) : appScopeKey(context, config);
+}
+
+function candidateScopeKeys(context = {}, config = ctx.config) {
+  const policy = capabilityConfig(config)?.scopePolicy || "app_only";
+  if (policy === "tenant_override" && context.tenantId) return [tenantScopeKey(context, config), appScopeKey(context, config)];
+  return [requestedScopeKey(context, config)];
+}
+
+module.exports = { capabilityConfig, enabled, appScopeKey, tenantScopeKey, requestedScopeKey, candidateScopeKeys };

package/src/capabilities/transactionalEmail/secretStore.js

@@ -0,0 +1,45 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const { TransactionalEmailError } = require("./errors");
+
+function keyring(env = process.env) {
+  let input;
+  if (env.OON_TRANSACTIONAL_EMAIL_KEK_KEYRING) {
+    try { input = JSON.parse(env.OON_TRANSACTIONAL_EMAIL_KEK_KEYRING); } catch { input = null; }
+  } else if (env.OON_TRANSACTIONAL_EMAIL_KEK) {
+    input = { currentKeyId: env.OON_TRANSACTIONAL_EMAIL_KEK_ID || "v1", keys: { [env.OON_TRANSACTIONAL_EMAIL_KEK_ID || "v1"]: env.OON_TRANSACTIONAL_EMAIL_KEK } };
+  }
+  const keys = new Map();
+  for (const [id, encoded] of Object.entries(input?.keys || {})) {
+    const key = Buffer.from(String(encoded), "base64");
+    if (key.length === 32) keys.set(id, key);
+  }
+  if (!input?.currentKeyId || !keys.has(input.currentKeyId)) throw new TransactionalEmailError("SecretStore de e-mail indisponível.", { code: "EMAIL_SECRET_STORE_UNAVAILABLE", statusCode: 503 });
+  return { currentKeyId: input.currentKeyId, keys };
+}
+
+function encrypt(value, options = {}) {
+  const ring = options.keyring || keyring(options.env);
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", ring.keys.get(ring.currentKeyId), iv);
+  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final()]);
+  return { keyId: ring.currentKeyId, version: 1, algorithm: "AES-256-GCM", iv: iv.toString("base64"), authTag: cipher.getAuthTag().toString("base64"), ciphertext: ciphertext.toString("base64") };
+}
+
+function decrypt(envelope, options = {}) {
+  try {
+    const ring = options.keyring || keyring(options.env);
+    const key = ring.keys.get(envelope?.keyId);
+    if (!key) throw new Error("keyId ausente");
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(envelope.iv, "base64"));
+    decipher.setAuthTag(Buffer.from(envelope.authTag, "base64"));
+    return JSON.parse(Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, "base64")), decipher.final()]).toString("utf8"));
+  } catch (cause) {
+    throw new TransactionalEmailError("Não foi possível abrir o segredo de e-mail.", { code: "EMAIL_SECRET_STORE_UNAVAILABLE", statusCode: 503, details: { keyId: envelope?.keyId } });
+  }
+}
+
+function fingerprint(value) { return crypto.createHash("sha256").update(String(value)).digest("hex").slice(0, 16); }
+function maskSecret(value) { const text = String(value || ""); return text ? `${text.slice(0, 3)}…${text.slice(-4)}` : undefined; }
+module.exports = { keyring, encrypt, decrypt, fingerprint, maskSecret };

package/src/capabilities/transactionalEmail/service.js

@@ -0,0 +1,66 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const { getModels } = require("./models");
+const { candidateScopeKeys, requestedScopeKey, capabilityConfig, enabled } = require("./scope");
+const secrets = require("./secretStore");
+const providers = require("./providers");
+const { validateDefinition, renderTemplate, contentHash } = require("./templates");
+const { TransactionalEmailError } = require("./errors");
+
+function assertEnabled() { if (!enabled()) throw new TransactionalEmailError("Capability de e-mail não declarada pelo App.", { code: "EMAIL_CAPABILITY_NOT_DECLARED", statusCode: 404 }); }
+function sanitizedConfig(config) { if (!config) return null; return { scopeKey: config.scopeKey, provider: config.provider, apiKeyMasked: config.apiKeyMasked, fingerprint: config.fingerprint, credentialConfigured: Boolean(config.credentialConfigured), senderEmail: config.senderEmail, senderName: config.senderName, replyTo: config.replyTo, enabled: Boolean(config.enabled), status: config.status, connectionStatus: config.connectionStatus, lastTestAt: config.lastTestAt, lastError: config.lastError, updatedAt: config.updatedAt }; }
+function sanitizeError(error) { return { code: String(error?.code || "EMAIL_PROVIDER_ERROR").slice(0, 80), message: String(error?.message || "Falha no envio.").slice(0, 240), retryable: error?.retryable === true }; }
+
+async function configuration(context = {}) { assertEnabled(); const { Config } = getModels(); for (const scopeKey of candidateScopeKeys(context)) { const value = await Config.findOne({ scopeKey, provider: "sendgrid" }).lean(); if (value?.enabled && value?.credentialConfigured) return value; } throw new TransactionalEmailError("Configure API key e remetente para habilitar os envios.", { code: "EMAIL_CONFIGURATION_REQUIRED", statusCode: 503 }); }
+async function getConfiguration(context = {}) { assertEnabled(); const { Config } = getModels(); return sanitizedConfig(await Config.findOne({ scopeKey: requestedScopeKey(context), provider: "sendgrid" }).lean()); }
+
+async function saveConfiguration(input, context = {}) {
+  assertEnabled();
+  const senderEmail = String(input.senderEmail || "").trim().toLowerCase();
+  const { Config } = getModels();
+  const scopeKey = requestedScopeKey(context);
+  const current = await Config.findOne({ scopeKey, provider: "sendgrid" });
+  const suppliedApiKey = String(input.apiKey || "").trim();
+  const apiKey = suppliedApiKey || (current?.encryptedEnvelope?.ciphertext ? secrets.decrypt(current.encryptedEnvelope) : "");
+  if (!apiKey || !senderEmail.includes("@")) throw new TransactionalEmailError("API key e remetente válidos são obrigatórios.", { code: "EMAIL_CONFIGURATION_INVALID" });
+  await providers.sendgrid.validateCredential(apiKey, context);
+  if (input.testRecipient) {
+    await providers.sendgrid.send({ to: [String(input.testRecipient).trim()], from: { email: senderEmail, name: input.senderName }, replyTo: input.replyTo, subject: "Teste de e-mail transacional Oon", text: "Configuração validada.", html: "<p>Configuração validada.</p>" }, apiKey, context);
+  }
+  const envelope = suppliedApiKey ? secrets.encrypt(apiKey) : current.encryptedEnvelope;
+  const update = { encryptedEnvelope: envelope, apiKeyMasked: secrets.maskSecret(apiKey), fingerprint: secrets.fingerprint(apiKey), credentialConfigured: true, senderEmail, senderName: String(input.senderName || "").trim(), replyTo: String(input.replyTo || "").trim().toLowerCase(), enabled: input.enabled !== false, status: input.enabled === false ? "configuration_required" : "active", connectionStatus: "valid", lastTestAt: new Date(), lastError: undefined, configuredBy: context.userId };
+  if (suppliedApiKey && current?.encryptedEnvelope?.ciphertext) update.previousEnvelopes = [...(current.previousEnvelopes || []), current.encryptedEnvelope].slice(-3);
+  const saved = await Config.findOneAndUpdate({ scopeKey, provider: "sendgrid" }, { $set: update, $setOnInsert: { scopeKey, provider: "sendgrid" } }, { upsert: true, new: true });
+  return sanitizedConfig(saved.toObject());
+}
+
+async function listTemplates(context = {}) { assertEnabled(); const { Template } = getModels(); return Template.find({ scopeKey: requestedScopeKey(context) }).sort({ code: 1, version: -1 }).lean(); }
+async function createTemplateVersion(code, input, context = {}) {
+  const { Template } = getModels(); const scopeKey = requestedScopeKey(context); const definition = validateDefinition({ ...input, code, initialStatus: "draft", attachmentsPolicy: input.attachmentsPolicy || { allowed: false } }, code);
+  const latest = await Template.findOne({ scopeKey, code }).sort({ version: -1 }).lean();
+  return Template.create({ ...definition, scopeKey, code, version: Number(latest?.version || 0) + 1, status: "draft", origin: "interface", contentHash: contentHash(definition), createdBy: context.userId });
+}
+async function activateTemplate(code, version, context = {}) { const { Template } = getModels(); const scopeKey = requestedScopeKey(context); const target = await Template.findOne({ scopeKey, code, version }); if (!target) throw new TransactionalEmailError("Versão de template não encontrada.", { code: "EMAIL_TEMPLATE_NOT_FOUND", statusCode: 404 }); await Template.updateMany({ scopeKey, code, status: "active" }, { $set: { status: "archived" } }); target.status = "active"; target.activatedAt = new Date(); target.createdBy ||= context.userId; await target.save(); return target; }
+async function archiveTemplate(code, version, context = {}) { const { Template } = getModels(); const value = await Template.findOneAndUpdate({ scopeKey: requestedScopeKey(context), code, version }, { $set: { status: "archived" } }, { new: true }); if (!value) throw new TransactionalEmailError("Template não encontrado.", { code: "EMAIL_TEMPLATE_NOT_FOUND", statusCode: 404 }); return value; }
+async function testTemplate(code, input, context = {}) { return send({ templateCode: code, to: input.to, variables: input.variables || {}, idempotencyKey: `template-test:${code}:${crypto.randomUUID()}`, correlationId: input.correlationId }, context); }
+
+function recipients(to) { const values = (Array.isArray(to) ? to : [to]).map((value) => String(value || "").trim().toLowerCase()).filter(Boolean); if (!values.length || values.some((value) => !value.includes("@"))) throw new TransactionalEmailError("Destinatário inválido.", { code: "EMAIL_RECIPIENT_INVALID" }); return [...new Set(values)]; }
+async function send(input, context = {}) {
+  assertEnabled(); if (input.attachments?.length) throw new TransactionalEmailError("Anexos não são permitidos nesta versão.", { code: "EMAIL_ATTACHMENTS_NOT_ALLOWED" });
+  const scopeKey = requestedScopeKey(context); const to = recipients(input.to); const { Template, Dispatch } = getModels();
+  const template = await Template.findOne({ scopeKey, code: input.templateCode, status: "active" }).lean();
+  if (!template) throw new TransactionalEmailError("Template ativo não encontrado.", { code: "EMAIL_TEMPLATE_NOT_ACTIVE", statusCode: 409 });
+  renderTemplate(template, input.variables || {});
+  const idempotencyKey = String(input.idempotencyKey || "").trim(); if (!idempotencyKey) throw new TransactionalEmailError("idempotencyKey é obrigatória.", { code: "EMAIL_IDEMPOTENCY_KEY_REQUIRED" });
+  try {
+    const retention = capabilityConfig()?.retentionDays || 30;
+    const dispatch = await Dispatch.create({ scopeKey, templateCode: template.code, templateVersion: template.version, protectedPayload: secrets.encrypt({ to, variables: input.variables || {} }), payloadExpiresAt: new Date(Date.now() + retention * 86400000), recipientFingerprint: secrets.fingerprint(to.join(",")), idempotencyKey, correlationId: String(input.correlationId || crypto.randomUUID()), status: "accepted", nextRetryAt: new Date(), maxAttempts: Math.max(1, Math.min(10, Number(input.maxAttempts || 5))) });
+    return { dispatchId: String(dispatch._id), status: "accepted", correlationId: dispatch.correlationId };
+  } catch (error) {
+    if (error?.code !== 11000) throw error; const existing = await Dispatch.findOne({ scopeKey, idempotencyKey }).lean(); return { dispatchId: String(existing._id), status: "duplicate", providerMessageId: existing.providerMessageId, correlationId: existing.correlationId };
+  }
+}
+async function listDispatches(context = {}, query = {}) { const { Dispatch } = getModels(); const limit = Math.min(100, Math.max(1, Number(query.limit || 25))); return Dispatch.find({ scopeKey: requestedScopeKey(context), ...(query.status ? { status: query.status } : {}) }, { protectedPayload: 0 }).sort({ createdAt: -1 }).limit(limit).lean(); }
+async function retryDispatch(id, context = {}) { const { Dispatch } = getModels(); const filter = { _id: id, scopeKey: requestedScopeKey(context), status: "dead_letter", protectedPayload: { $exists: true } }; const dispatch = await Dispatch.findOneAndUpdate(filter, { $set: { status: "accepted", nextRetryAt: new Date(), leaseOwner: null, leaseExpiresAt: null }, $push: { retryAudit: { actorId: context.userId, at: new Date(), previousStatus: "dead_letter" } } }, { new: true }); if (!dispatch) throw new TransactionalEmailError("Dispatch inelegível para reprocessamento.", { code: "EMAIL_DISPATCH_NOT_RETRYABLE", statusCode: 409 }); return dispatch; }
+module.exports = { configuration, getConfiguration, saveConfiguration, listTemplates, createTemplateVersion, activateTemplate, archiveTemplate, testTemplate, send, listDispatches, retryDispatch, sanitizeError, sanitizedConfig };

package/src/capabilities/transactionalEmail/templates.js

@@ -0,0 +1,53 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const Handlebars = require("handlebars");
+const Ajv = require("ajv");
+const { TransactionalEmailError } = require("./errors");
+
+const ajv = new Ajv({ allErrors: true, strict: true });
+const remoteContent = /<(?:script|iframe|link|img)\b[^>]*(?:src|href)\s*=\s*["']https?:\/\//i;
+const compileOptions = { strict: true, noEscape: false, knownHelpersOnly: true, knownHelpers: {} };
+
+function assertRestrictedHandlebars(source) {
+  const ast = Handlebars.parse(source);
+  function visit(node) {
+    if (!node || typeof node !== "object") return;
+    if (["BlockStatement", "PartialStatement", "PartialBlockStatement", "SubExpression", "Decorator", "DecoratorBlock"].includes(node.type)) {
+      throw new Error(`construção Handlebars não permitida: ${node.type}`);
+    }
+    if (node.type === "MustacheStatement" && (node.escaped === false || node.params?.length || node.hash?.pairs?.length || node.path?.type !== "PathExpression")) {
+      throw new Error("somente interpolação escapada de variáveis é permitida");
+    }
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) value.forEach(visit);
+      else if (value && typeof value === "object") visit(value);
+    }
+  }
+  visit(ast);
+}
+
+function validateDefinition(input, expectedCode) {
+  const definition = { ...input };
+  const required = ["code", "name", "subject", "htmlContent", "textContent", "variablesSchema", "locale", "initialStatus", "attachmentsPolicy"];
+  for (const field of required) if (definition[field] === undefined) throw new TransactionalEmailError(`Template sem ${field}.`, { code: "EMAIL_TEMPLATE_INVALID" });
+  if (expectedCode && definition.code !== expectedCode) throw new TransactionalEmailError("O código do template difere do manifesto.", { code: "EMAIL_TEMPLATE_INVALID" });
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(definition.code)) throw new TransactionalEmailError("Código de template inválido.", { code: "EMAIL_TEMPLATE_INVALID" });
+  if (!["draft", "active"].includes(definition.initialStatus)) throw new TransactionalEmailError("Status inicial inválido.", { code: "EMAIL_TEMPLATE_INVALID" });
+  if (definition.attachmentsPolicy?.allowed !== false) throw new TransactionalEmailError("Anexos não são permitidos nesta versão.", { code: "EMAIL_ATTACHMENTS_NOT_ALLOWED" });
+  if (remoteContent.test(definition.htmlContent)) throw new TransactionalEmailError("Conteúdo remoto não é permitido no HTML.", { code: "EMAIL_TEMPLATE_REMOTE_CONTENT" });
+  try { ajv.compile(definition.variablesSchema); for (const source of [definition.subject, definition.htmlContent, definition.textContent]) { assertRestrictedHandlebars(source); Handlebars.precompile(source, compileOptions); } }
+  catch (cause) { throw new TransactionalEmailError(`Template inválido: ${cause.message}`, { code: "EMAIL_TEMPLATE_INVALID" }); }
+  return definition;
+}
+
+function renderTemplate(template, variables) {
+  const validate = ajv.compile(template.variablesSchema || {});
+  if (!validate(variables)) throw new TransactionalEmailError("Variáveis não atendem ao schema do template.", { code: "EMAIL_VARIABLES_INVALID", details: { errors: validate.errors } });
+  try {
+    return { subject: Handlebars.compile(template.subject, compileOptions)(variables), html: Handlebars.compile(template.htmlContent, compileOptions)(variables), text: Handlebars.compile(template.textContent, compileOptions)(variables) };
+  } catch (cause) { throw new TransactionalEmailError(`Falha ao renderizar template: ${cause.message}`, { code: "EMAIL_TEMPLATE_RENDER_FAILED" }); }
+}
+
+function contentHash(definition) { return crypto.createHash("sha256").update(JSON.stringify(definition)).digest("hex"); }
+module.exports = { validateDefinition, renderTemplate, contentHash };

package/src/capabilities/transactionalEmail/worker.js

@@ -0,0 +1,34 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const { getModels } = require("./models");
+const { configuration, sanitizeError } = require("./service");
+const secrets = require("./secretStore");
+const providers = require("./providers");
+const { renderTemplate } = require("./templates");
+
+const state = { running: false, owner: `${process.pid}:${crypto.randomUUID()}`, lastProgressAt: null, timer: null };
+function backoff(attempt) { const base = Math.min(3600000, 1000 * (2 ** Math.max(0, attempt - 1))); return base + Math.floor(Math.random() * Math.max(250, base * 0.2)); }
+async function lease() { const { Dispatch } = getModels(); const now = new Date(); return Dispatch.findOneAndUpdate({ status: { $in: ["accepted", "failed", "processing"] }, nextRetryAt: { $lte: now }, $or: [{ leaseExpiresAt: { $exists: false } }, { leaseExpiresAt: null }, { leaseExpiresAt: { $lte: now } }] }, { $set: { status: "processing", leaseOwner: state.owner, leaseExpiresAt: new Date(Date.now() + 60000) }, $inc: { attempts: 1 } }, { new: true, sort: { nextRetryAt: 1, createdAt: 1 } }); }
+async function processOne() {
+  const dispatch = await lease(); if (!dispatch) return false;
+  const { Template } = getModels();
+  try {
+    const config = await configuration({ appCode: dispatch.scopeKey.split(":")[1], tenantId: dispatch.scopeKey.includes(":tenant:") ? dispatch.scopeKey.split(":tenant:")[1] : undefined });
+    const template = await Template.findOne({ scopeKey: dispatch.scopeKey, code: dispatch.templateCode, version: dispatch.templateVersion }).lean();
+    const payload = secrets.decrypt(dispatch.protectedPayload); const rendered = renderTemplate(template, payload.variables); const apiKey = secrets.decrypt(config.encryptedEnvelope);
+    const result = await providers.sendgrid.send({ to: payload.to, from: { email: config.senderEmail, name: config.senderName }, replyTo: config.replyTo, ...rendered }, apiKey);
+    dispatch.status = "provider_accepted"; dispatch.providerMessageId = result.providerMessageId; dispatch.sentAt = new Date(); dispatch.leaseOwner = undefined; dispatch.leaseExpiresAt = undefined; dispatch.lastError = undefined;
+  } catch (error) {
+    const normalized = sanitizeError(error); dispatch.lastError = normalized; dispatch.leaseOwner = undefined; dispatch.leaseExpiresAt = undefined;
+    if (normalized.retryable && dispatch.attempts < dispatch.maxAttempts) { dispatch.status = "failed"; dispatch.nextRetryAt = new Date(Date.now() + backoff(dispatch.attempts)); }
+    else { dispatch.status = "dead_letter"; dispatch.failedAt = new Date(); }
+  }
+  await dispatch.save(); state.lastProgressAt = new Date(); return true;
+}
+async function scrubExpired() { const { Dispatch } = getModels(); await Dispatch.updateMany({ payloadExpiresAt: { $lte: new Date() }, status: { $in: ["provider_accepted", "dead_letter", "cancelled"] } }, { $unset: { protectedPayload: 1 } }); }
+async function tick() { if (!state.running) return; try { let count = 0; while (state.running && count < 20 && await processOne()) count += 1; if (Math.random() < 0.05) await scrubExpired(); } catch (error) { console.error(JSON.stringify({ event: "transactionalEmail.worker.failed", code: error?.code || "EMAIL_WORKER_FAILED" })); } finally { if (state.running) state.timer = setTimeout(tick, 1000); } }
+function startWorker() { if (state.running) return; state.running = true; state.timer = setTimeout(tick, 10); }
+function stopWorker() { state.running = false; if (state.timer) clearTimeout(state.timer); state.timer = null; }
+function health() { const stale = state.running && state.lastProgressAt && Date.now() - state.lastProgressAt.getTime() > 300000; return { running: state.running, owner: state.owner, lastProgressAt: state.lastProgressAt, status: !state.running || stale ? "degraded" : "active" }; }
+module.exports = { startWorker, stopWorker, processOne, health, backoff, state };

package/src/delivery/buildImage.js

@@ -72,6 +72,23 @@ function prepareAppManifest(workspace, deliveryDirectory) {
 
   if (fs.existsSync(manifestSource)) {
     fs.copyFileSync(manifestSource, manifestTarget);
+    const manifest = JSON.parse(fs.readFileSync(manifestSource, "utf8"));
+    const declaredTemplates = manifest.capabilitySettings?.["core.transactional-email"]?.templates || [];
+    const workspaceRoot = fs.realpathSync(workspace);
+    for (const declared of declaredTemplates) {
+      const relative = String(declared?.definition || "");
+      const source = path.resolve(workspace, relative);
+      const realSource = fs.realpathSync(source);
+      if (realSource !== workspaceRoot && !realSource.startsWith(`${workspaceRoot}${path.sep}`)) {
+        throw new Error(`Definição de template fora da raiz do App: ${relative}`);
+      }
+      const target = path.resolve(manifestDirectory, relative);
+      if (target !== manifestDirectory && !target.startsWith(`${manifestDirectory}${path.sep}`)) {
+        throw new Error(`Destino de template inválido: ${relative}`);
+      }
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(realSource, target);
+    }
   }
 
   return manifestTarget;

package/src/index.js

@@ -89,5 +89,6 @@ module.exports = {
   capabilities,
   operationalRequestHeaders,
   PdfRenderingError: capabilities.PdfRenderingError,
+  TransactionalEmailError: capabilities.TransactionalEmailError,
   GenericError, registry,
 };

package/src/manifest/appManifest.js

@@ -19,6 +19,8 @@ const SUPPORTED_AUTHORIZATION_MODES = Object.freeze(["none", "rbac"]);
 // Compatibilidade de leitura para manifestos anteriores à separação das duas dimensões.
 const SUPPORTED_ACCESS_POLICIES = Object.freeze(["tenant_members", "explicit_users", "rbac"]);
 const SUPPORTED_DEPLOYMENT_MODES = Object.freeze(["singleton", "shared", "dedicated", "hybrid"]);
+const TRANSACTIONAL_EMAIL_CAPABILITY = "core.transactional-email";
+const EMAIL_SCOPE_POLICIES = Object.freeze(["app_only", "tenant_required", "tenant_override"]);
 const APP_KIND_ROLE = Object.freeze({
   "root-central": "root",
   "member-central": "member",
@@ -135,6 +137,54 @@ function validateActivation(activation, issues) {
   }
 }
 
+function validateCapabilitySettings(settings, capabilities, issues) {
+  if (settings === undefined) return;
+  if (!isPlainObject(settings)) {
+    addIssue(issues, "capabilitySettings", "deve ser um objeto.");
+    return;
+  }
+  for (const [capability, config] of Object.entries(settings)) {
+    const base = `capabilitySettings.${capability}`;
+    if (!capabilities?.includes(capability)) {
+      addIssue(issues, base, "exige a mesma capability declarada em capabilities.");
+      continue;
+    }
+    if (capability !== TRANSACTIONAL_EMAIL_CAPABILITY) {
+      addIssue(issues, base, "capability configurável desconhecida.");
+      continue;
+    }
+    if (!isPlainObject(config)) {
+      addIssue(issues, base, "deve ser um objeto.");
+      continue;
+    }
+    const allowed = new Set(["enabled", "scopePolicy", "templates", "retentionDays", "attachmentsPolicy"]);
+    for (const key of Object.keys(config)) if (!allowed.has(key)) addIssue(issues, `${base}.${key}`, "propriedade não suportada.");
+    if (typeof config.enabled !== "boolean") addIssue(issues, `${base}.enabled`, "deve ser booleano.");
+    if (!EMAIL_SCOPE_POLICIES.includes(config.scopePolicy)) addIssue(issues, `${base}.scopePolicy`, `deve ser um de: ${EMAIL_SCOPE_POLICIES.join(", ")}.`);
+    if (config.retentionDays !== undefined && (!Number.isInteger(config.retentionDays) || config.retentionDays < 1 || config.retentionDays > 90)) {
+      addIssue(issues, `${base}.retentionDays`, "deve ser inteiro entre 1 e 90.");
+    }
+    if (!Array.isArray(config.templates)) {
+      addIssue(issues, `${base}.templates`, "deve ser uma lista.");
+      continue;
+    }
+    const codes = new Set();
+    config.templates.forEach((template, index) => {
+      const item = `${base}.templates[${index}]`;
+      if (!isPlainObject(template)) { addIssue(issues, item, "deve ser um objeto."); return; }
+      const templateAllowed = new Set(["code", "definition", "initialStatus"]);
+      for (const key of Object.keys(template)) if (!templateAllowed.has(key)) addIssue(issues, `${item}.${key}`, "propriedade não suportada.");
+      if (typeof template.code !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(template.code)) addIssue(issues, `${item}.code`, "deve ser um código em kebab-case.");
+      else if (codes.has(template.code)) addIssue(issues, `${item}.code`, `template duplicado: ${template.code}.`);
+      else codes.add(template.code);
+      if (typeof template.definition !== "string" || !template.definition.trim() || path.isAbsolute(template.definition) || template.definition.split(/[\\/]/).includes("..")) {
+        addIssue(issues, `${item}.definition`, "deve ser um caminho relativo sem escapar da raiz do App.");
+      }
+      if (!["draft", "active"].includes(template.initialStatus)) addIssue(issues, `${item}.initialStatus`, "deve ser draft ou active.");
+    });
+  }
+}
+
 function validateDimension(value, field, supported, issues) {
   if (value === undefined) return;
   if (!supported.includes(value)) {
@@ -170,7 +220,7 @@ function validateAppManifest(input, { coreVersion = corePackage.version } = {})
   const allowedTopLevel = new Set([
     "$schema", "schemaVersion", "id", "name", "slug", "appKind",
     "tenancyModel", "availability", "accessMode", "authorizationMode", "accessPolicy", "deploymentMode",
-    "modules", "capabilities", "compatibility", "activation", "rbac",
+    "modules", "capabilities", "capabilitySettings", "compatibility", "activation", "rbac",
   ]);
   for (const key of Object.keys(input)) {
     if (!allowedTopLevel.has(key)) addIssue(issues, key, "propriedade não suportada.");
@@ -233,6 +283,7 @@ function validateAppManifest(input, { coreVersion = corePackage.version } = {})
       else seen.add(capability);
     });
   }
+  validateCapabilitySettings(input.capabilitySettings, input.capabilities, issues);
   validateCompatibility(input.compatibility, issues, coreVersion);
   validateActivation(input.activation, issues);
   validateRbac(input.rbac, issues);
@@ -268,6 +319,7 @@ function appManifestToConfig(manifest, manifestPath) {
     },
     modules: { ...manifest.modules },
     capabilities: [...manifest.capabilities],
+    capabilitySettings: JSON.parse(JSON.stringify(manifest.capabilitySettings || {})),
     rbac: manifest.rbac ? JSON.parse(JSON.stringify(manifest.rbac)) : undefined,
     appManifest: manifest,
     appManifestPath: manifestPath,
@@ -303,6 +355,8 @@ module.exports = {
   SUPPORTED_AUTHORIZATION_MODES,
   SUPPORTED_ACCESS_POLICIES,
   SUPPORTED_DEPLOYMENT_MODES,
+  TRANSACTIONAL_EMAIL_CAPABILITY,
+  EMAIL_SCOPE_POLICIES,
   APP_KIND_DIMENSIONS,
   AppManifestError,
   parseVersion,