@oondemand/oon-core-back 0.3.56 → 0.3.58

package/src/modules/integrations/routes.js

@@ -0,0 +1,215 @@
+"use strict";
+
+const express = require("express");
+const GenericError = require("../../core/errors/GenericError");
+const auth = require("../../core/middlewares/auth");
+const { rbac } = require("../../core/middlewares/rbac");
+const { asyncHandler } = require("../../core/utils/helpers");
+const { getIntegrationModels } = require("./models");
+const { getIntegrationProvider, listIntegrationProviders } = require("./registry");
+const {
+  archiveIntegrationTicket,
+  integrationHealth,
+  processIntegrationQueue,
+  processWebhookInbox,
+  receiveWebhook,
+  reprocessIntegrationTicket,
+  synchronizeAll,
+  synchronizeResource,
+} = require("./runtime");
+const { sanitizeIntegrationValue } = require("./sanitizer");
+
+const READ_ROLES = ["admin", "desenvolvedor"];
+const WRITE_ROLES = ["admin", "desenvolvedor"];
+
+function number(value, fallback, max = 100) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.min(max, Math.max(1, parsed)) : fallback;
+}
+
+function pagination(query = {}) {
+  const limit = number(query.limit || query.pageSize, 20, 200);
+  const page = number(query.page || query.pageIndex, 1, 100_000);
+  return { limit, page, skip: (page - 1) * limit };
+}
+
+function requireProviderExtension(provider, method, message) {
+  if (typeof provider[method] !== "function") {
+    throw new GenericError(message || `O provedor ${provider.label} não oferece ${method}.`, {
+      statusCode: 404,
+    });
+  }
+  return provider[method].bind(provider);
+}
+
+function buildIntegrationRouter() {
+  const router = express.Router();
+
+  router.post("/webhooks/:provider/:token", asyncHandler(async (req, res) => {
+    const event = await receiveWebhook({
+      provider: req.params.provider,
+      token: req.params.token,
+      headers: req.headers,
+      payload: req.body,
+      resource: req.query.resource,
+      eventType: req.body?.eventType || req.body?.event_type || req.body?.topic || "unknown",
+      externalEventId: req.body?.eventId || req.body?.event_id || req.body?.id,
+    });
+    res.status(202).json({ accepted: true, id: String(event._id), duplicate: event.status !== "Pendente" });
+  }));
+
+  router.use(auth);
+  router.get("/providers", rbac(READ_ROLES), (_req, res) => {
+    res.json({ results: listIntegrationProviders() });
+  });
+  router.get("/providers/:provider/catalog", rbac(READ_ROLES), (req, res) => {
+    const provider = getIntegrationProvider(req.params.provider);
+    const metadata = listIntegrationProviders().find((item) => item.key === provider.key);
+    res.json({ provider: provider.key, resources: metadata?.resources || [] });
+  });
+  router.get("/providers/:provider/configuration", rbac(READ_ROLES), asyncHandler(async (req, res) => {
+    const provider = getIntegrationProvider(req.params.provider);
+    const getConfiguration = requireProviderExtension(
+      provider,
+      "getConfiguration",
+      `O provedor ${provider.label} não possui configuração gerenciada pelo Core.`,
+    );
+    res.json({ provider: provider.key, instances: sanitizeIntegrationValue(await getConfiguration()) });
+  }));
+  router.put("/providers/:provider/configuration/:instanceId", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    const provider = getIntegrationProvider(req.params.provider);
+    const saveConfiguration = requireProviderExtension(provider, "saveConfiguration");
+    const saved = await saveConfiguration(req.params.instanceId, req.body || {});
+    res.json({ provider: provider.key, configuration: sanitizeIntegrationValue(saved) });
+  }));
+  router.post("/providers/:provider/configuration/:instanceId/test", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    const provider = getIntegrationProvider(req.params.provider);
+    const testConnection = requireProviderExtension(provider, "testConnection");
+    res.json(await testConnection(req.params.instanceId, {
+      input: req.body || {},
+      source: "api",
+      requestId: req.requestId || "",
+    }));
+  }));
+  router.get("/providers/:provider/mappings", rbac(READ_ROLES), asyncHandler(async (req, res) => {
+    const provider = getIntegrationProvider(req.params.provider);
+    const describe = requireProviderExtension(provider, "describe");
+    res.json({ provider: provider.key, ...sanitizeIntegrationValue(await describe()) });
+  }));
+  router.post("/providers/:provider/calls/:call", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    const provider = getIntegrationProvider(req.params.provider);
+    const executeCall = requireProviderExtension(provider, "executeCall");
+    res.json(await executeCall(req.params.call, req.body?.input || req.body || {}, {
+      instanceId: req.body?.instanceId || "default",
+      source: "api",
+      requestId: req.requestId || "",
+    }));
+  }));
+  router.get("/health", rbac(READ_ROLES), asyncHandler(async (_req, res) => {
+    res.json({ results: await integrationHealth() });
+  }));
+
+  router.get("/history", rbac(READ_ROLES), asyncHandler(async (req, res) => {
+    const { Execution } = getIntegrationModels();
+    const { limit, page, skip } = pagination(req.query);
+    const filter = {};
+    for (const field of ["provider", "resource", "operation", "status"]) {
+      if (req.query[field]) filter[field] = String(req.query[field]);
+    }
+    const [results, totalItems] = await Promise.all([
+      Execution.find(filter).sort({ startedAt: -1 }).skip(skip).limit(limit).lean(),
+      Execution.countDocuments(filter),
+    ]);
+    res.json({
+      results: sanitizeIntegrationValue(results),
+      pagination: {
+        currentPage: page,
+        totalItems,
+        totalPages: Math.ceil(totalItems / limit),
+        itemsPerPage: limit,
+      },
+    });
+  }));
+
+  router.get("/queue", rbac(READ_ROLES), asyncHandler(async (req, res) => {
+    const { Outbox } = getIntegrationModels();
+    const { limit, page, skip } = pagination(req.query);
+    const filter = {};
+    for (const field of ["provider", "resource", "operation", "status", "aggregateType", "aggregateId"]) {
+      if (req.query[field]) filter[field] = String(req.query[field]);
+    }
+    const [results, totalItems] = await Promise.all([
+      Outbox.find(filter).sort({ createdAt: -1 }).skip(skip).limit(limit).lean(),
+      Outbox.countDocuments(filter),
+    ]);
+    res.json({
+      results: sanitizeIntegrationValue(results),
+      pagination: {
+        currentPage: page,
+        totalItems,
+        totalPages: Math.ceil(totalItems / limit),
+        itemsPerPage: limit,
+      },
+    });
+  }));
+
+  router.get("/events", rbac(READ_ROLES), asyncHandler(async (req, res) => {
+    const { Inbox } = getIntegrationModels();
+    const { limit, page, skip } = pagination(req.query);
+    const filter = {};
+    for (const field of ["provider", "resource", "eventType", "status"]) {
+      if (req.query[field]) filter[field] = String(req.query[field]);
+    }
+    const [results, totalItems] = await Promise.all([
+      Inbox.find(filter).sort({ receivedAt: -1 }).skip(skip).limit(limit).lean(),
+      Inbox.countDocuments(filter),
+    ]);
+    res.json({
+      results: sanitizeIntegrationValue(results),
+      pagination: {
+        currentPage: page,
+        totalItems,
+        totalPages: Math.ceil(totalItems / limit),
+        itemsPerPage: limit,
+      },
+    });
+  }));
+
+  router.post("/providers/:provider/resources/:resource/sync", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    const result = await synchronizeResource(req.params.provider, req.params.resource, {
+      payload: req.body,
+      metadata: { source: "api", requestId: req.requestId || "", user: req.usuario?.email || "" },
+    });
+    res.status(200).json(result);
+  }));
+  router.post("/providers/:provider/sync-all", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    const result = await synchronizeAll(req.params.provider, {
+      payload: req.body,
+      metadata: { source: "api", requestId: req.requestId || "", user: req.usuario?.email || "" },
+    });
+    res.status(result.status === "Concluído" ? 200 : 207).json(result);
+  }));
+  router.post("/queue/process", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    res.json(await processIntegrationQueue({ provider: req.body?.provider, limit: req.body?.limit }));
+  }));
+  router.post("/events/process", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    res.json(await processWebhookInbox({ provider: req.body?.provider, limit: req.body?.limit }));
+  }));
+  router.post("/queue/:id/archive", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    res.json(await archiveIntegrationTicket(req.params.id, req.body?.reason));
+  }));
+  router.post("/queue/:id/reprocess", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    res.json(await reprocessIntegrationTicket(req.params.id));
+  }));
+  router.post("/actions/process-active", rbac(WRITE_ROLES), asyncHandler(async (req, res) => {
+    const [queue, events] = await Promise.all([
+      processIntegrationQueue({ limit: req.body?.limit }),
+      processWebhookInbox({ limit: req.body?.eventLimit }),
+    ]);
+    res.json({ queue, events });
+  }));
+
+  return router;
+}
+
+module.exports = { buildIntegrationRouter };

package/src/modules/integrations/runtime/inbox.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const GenericError = require("../../../core/errors/GenericError");
+const { getIntegrationModels } = require("../models");
+const { getIntegrationProvider, resolveWebhookHandler } = require("../registry");
+const { sanitizeIntegrationError, sanitizeIntegrationValue } = require("../sanitizer");
+const { acquireNext, finalizeLease, leaseHeartbeat } = require("./lease");
+const { runTrackedOperation } = require("./tracking");
+const { DEFAULT_LEASE_MS, calculateBackoff, classifyError, isEnabled, payloadHash, workerId } = require("./utils");
+
+async function receiveWebhook(input) {
+  const provider = getIntegrationProvider(input.provider);
+  let verificationMetadata = {};
+  if (typeof provider.verifyWebhook === "function") {
+    const verification = await provider.verifyWebhook({
+      token: input.token,
+      headers: input.headers || {},
+      payload: input.payload,
+    });
+    const accepted = verification === true || verification?.accepted === true;
+    if (!accepted) throw new GenericError("Webhook de integração não autorizado.", { statusCode: 401 });
+    verificationMetadata = sanitizeIntegrationValue(verification?.metadata || {});
+  }
+
+  const normalized = typeof provider.normalizeWebhook === "function"
+    ? await provider.normalizeWebhook({ ...input, metadata: verificationMetadata })
+    : input;
+  const sanitizedPayload = sanitizeIntegrationValue(normalized.payload || {});
+  const hash = payloadHash(sanitizedPayload);
+  const externalEventId = String(normalized.externalEventId || "").trim();
+  const deduplicationKey = `${provider.key}:${externalEventId || hash}`;
+  const { Inbox } = getIntegrationModels();
+  return Inbox.findOneAndUpdate(
+    { deduplicationKey },
+    {
+      $setOnInsert: {
+        provider: provider.key,
+        resource: String(normalized.resource || ""),
+        eventType: String(normalized.eventType || "unknown"),
+        externalEventId,
+        deduplicationKey,
+        payloadHash: hash,
+        payload: sanitizedPayload,
+        metadata: sanitizeIntegrationValue({
+          ...verificationMetadata,
+          ...(normalized.metadata || {}),
+        }),
+        receivedAt: new Date(),
+        status: "Pendente",
+        attempts: 0,
+        nextAttemptAt: new Date(),
+      },
+    },
+    { upsert: true, new: true, setDefaultsOnInsert: true },
+  ).lean();
+}
+
+async function processWebhookInbox(options = {}) {
+  const { Inbox } = getIntegrationModels();
+  const limit = Math.min(500, Math.max(1, Number(options.limit || 20)));
+  const worker = options.worker || workerId("inbox");
+  const leaseMs = Number(options.leaseMs || DEFAULT_LEASE_MS);
+  const results = [];
+
+  for (let index = 0; index < limit; index += 1) {
+    const query = { status: { $in: ["Pendente", "Erro temporário", "Processando"] } };
+    if (options.provider) query.provider = String(options.provider).trim().toLowerCase();
+    const event = await acquireNext(Inbox, query, { worker, leaseMs });
+    if (!event) break;
+    const pulse = leaseHeartbeat(Inbox, event, options);
+    pulse.start();
+    let provider;
+    try {
+      const resolved = resolveWebhookHandler(event.provider, event.eventType);
+      provider = resolved.provider;
+      const handler = resolved.handler;
+      if (!isEnabled(provider)) {
+        throw new GenericError(`A integração ${provider.label} está desativada.`, { statusCode: 503 });
+      }
+      const tracked = await runTrackedOperation({
+        provider: provider.key,
+        resource: event.resource || "",
+        operation: "webhook",
+        title: `${provider.label}: webhook ${event.eventType}`,
+        metadata: {
+          source: "inbox",
+          inboxId: String(event._id),
+          externalEventId: event.externalEventId || "",
+          ...sanitizeIntegrationValue(event.metadata || {}),
+        },
+        runner: (trace) => handler(event, {
+          ...options,
+          ...trace,
+          provider,
+          heartbeat: pulse.beat,
+          sanitize: sanitizeIntegrationValue,
+        }),
+      });
+      const committed = await finalizeLease(Inbox, event, {
+        status: "Concluído",
+        processedAt: new Date(),
+        lastError: {},
+        nextAttemptAt: null,
+      });
+      if (!committed) {
+        throw new GenericError("Resultado do webhook ignorado porque o lease expirou.", { statusCode: 409 });
+      }
+      results.push({ id: String(event._id), status: "Concluído", response: tracked.result });
+    } catch (error) {
+      const effectiveProvider = provider || { maxAttempts: 1, retryPolicy: { jitter: false } };
+      const classification = classifyError(effectiveProvider, error, Number(event.attempts || 1));
+      const committed = await finalizeLease(Inbox, event, {
+        status: classification.definitive ? "Erro definitivo" : "Erro temporário",
+        lastError: sanitizeIntegrationError(error),
+        nextAttemptAt: classification.definitive
+          ? null
+          : new Date(Date.now() + calculateBackoff(event.attempts, effectiveProvider.retryPolicy)),
+      });
+      if (!committed) {
+        throw new GenericError("Erro do webhook ignorado porque o lease expirou.", { statusCode: 409 });
+      }
+      results.push({
+        id: String(event._id),
+        status: classification.definitive ? "Erro definitivo" : "Erro temporário",
+        error: sanitizeIntegrationError(error),
+      });
+    } finally {
+      pulse.stop();
+    }
+  }
+  return { processed: results.filter((item) => item.status === "Concluído").length, results };
+}
+
+module.exports = { processWebhookInbox, receiveWebhook };

package/src/modules/integrations/runtime/lease.js

@@ -0,0 +1,94 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const GenericError = require("../../../core/errors/GenericError");
+const { DEFAULT_HEARTBEAT_MS, DEFAULT_LEASE_MS } = require("./utils");
+
+async function acquireNext(Model, query, { worker, leaseMs }) {
+  const now = new Date();
+  const leaseId = crypto.randomUUID();
+  const document = await Model.findOneAndUpdate(
+    {
+      ...query,
+      $and: [
+        {
+          $or: [
+            { nextAttemptAt: { $lte: now } },
+            { nextAttemptAt: null },
+            { nextAttemptAt: { $exists: false } },
+          ],
+        },
+        {
+          $or: [
+            { leaseExpiresAt: { $lte: now } },
+            { leaseExpiresAt: null },
+            { leaseExpiresAt: { $exists: false } },
+          ],
+        },
+      ],
+    },
+    {
+      $set: {
+        status: "Processando",
+        leaseId,
+        lockedAt: now,
+        lockedBy: worker,
+        heartbeatAt: now,
+        leaseExpiresAt: new Date(now.getTime() + leaseMs),
+      },
+      $inc: { attempts: 1 },
+    },
+    { sort: { createdAt: 1, receivedAt: 1 }, new: true },
+  ).lean();
+  return document ? { ...document, leaseId } : null;
+}
+
+async function heartbeat(Model, id, leaseId, leaseMs = DEFAULT_LEASE_MS) {
+  const now = new Date();
+  const result = await Model.updateOne(
+    { _id: id, leaseId, status: "Processando" },
+    { $set: { heartbeatAt: now, leaseExpiresAt: new Date(now.getTime() + leaseMs) } },
+  );
+  if (result.matchedCount !== 1) {
+    throw new GenericError("Lease da integração não pertence mais a este worker.", { statusCode: 409 });
+  }
+}
+
+function leaseHeartbeat(Model, document, options = {}) {
+  const leaseMs = Number(options.leaseMs || DEFAULT_LEASE_MS);
+  const intervalMs = Math.min(leaseMs / 2, Number(options.heartbeatMs || DEFAULT_HEARTBEAT_MS));
+  let timer;
+  let stopped = false;
+  const beat = () => heartbeat(Model, document._id, document.leaseId, leaseMs);
+  return {
+    start() {
+      timer = setInterval(() => {
+        beat().catch((error) => {
+          if (!stopped) console.error("[integration-heartbeat]", error.message);
+        });
+      }, intervalMs);
+      timer.unref?.();
+    },
+    async beat() { return beat(); },
+    stop() { stopped = true; if (timer) clearInterval(timer); },
+  };
+}
+
+async function finalizeLease(Model, event, patch) {
+  const result = await Model.updateOne(
+    { _id: event._id, leaseId: event.leaseId, status: "Processando" },
+    {
+      $set: {
+        ...patch,
+        leaseId: "",
+        lockedAt: null,
+        lockedBy: "",
+        leaseExpiresAt: null,
+        heartbeatAt: null,
+      },
+    },
+  );
+  return result.matchedCount === 1;
+}
+
+module.exports = { acquireNext, finalizeLease, heartbeat, leaseHeartbeat };

package/src/modules/integrations/runtime/outbox.js

@@ -0,0 +1,199 @@
+"use strict";
+
+const GenericError = require("../../../core/errors/GenericError");
+const { getIntegrationModels } = require("../models");
+const { getIntegrationProvider, resolveIntegrationHandler } = require("../registry");
+const { sanitizeIntegrationError, sanitizeIntegrationValue } = require("../sanitizer");
+const { acquireNext, finalizeLease, leaseHeartbeat } = require("./lease");
+const { runTrackedOperation } = require("./tracking");
+const { DEFAULT_LEASE_MS, calculateBackoff, classifyError, isEnabled, workerId } = require("./utils");
+
+async function enqueueIntegration(input) {
+  const provider = getIntegrationProvider(input.provider);
+  const handler = String(input.handler || input.type || "").trim();
+  const idempotencyKey = String(input.idempotencyKey || "").trim();
+  if (!handler) throw new GenericError("Informe o handler da integração.", { statusCode: 422 });
+  if (!idempotencyKey) throw new GenericError("Informe a chave de idempotência.", { statusCode: 422 });
+  if (!provider.handlers[handler]) {
+    throw new GenericError(`Handler ${handler} não registrado para ${provider.label}.`, { statusCode: 422 });
+  }
+
+  const { Outbox } = getIntegrationModels();
+  return Outbox.findOneAndUpdate(
+    { idempotencyKey },
+    {
+      $setOnInsert: {
+        provider: provider.key,
+        handler,
+        resource: String(input.resource || ""),
+        operation: String(input.operation || "execute"),
+        aggregateType: String(input.aggregateType || ""),
+        aggregateId: String(input.aggregateId || ""),
+        idempotencyKey,
+        payload: sanitizeIntegrationValue(input.payload || {}),
+        status: "Pendente",
+        attempts: 0,
+        nextAttemptAt: new Date(),
+      },
+    },
+    { upsert: true, new: true, setDefaultsOnInsert: true },
+  ).lean();
+}
+
+async function processOutboxEvent(event, options = {}) {
+  const { Outbox } = getIntegrationModels();
+  const pulse = leaseHeartbeat(Outbox, event, options);
+  pulse.start();
+  let provider;
+  let handlerKey = event.handler;
+  try {
+    const resolved = resolveIntegrationHandler(event.provider, event.handler);
+    provider = resolved.provider;
+    handlerKey = resolved.handlerKey;
+    const handler = resolved.handler;
+    if (!isEnabled(provider)) {
+      throw new GenericError(`A integração ${provider.label} está desativada.`, { statusCode: 503 });
+    }
+    const tracked = await runTrackedOperation({
+      provider: provider.key,
+      resource: event.resource || "",
+      operation: event.operation || "execute",
+      title: `${provider.label}: ${handlerKey}`,
+      metadata: {
+        source: "outbox",
+        outboxId: String(event._id),
+        aggregateType: event.aggregateType || "",
+        aggregateId: event.aggregateId || "",
+        attempts: event.attempts,
+      },
+      runner: (trace) => handler(event, {
+        ...options,
+        ...trace,
+        provider,
+        heartbeat: pulse.beat,
+        sanitize: sanitizeIntegrationValue,
+      }),
+    });
+    const response = tracked.result;
+    const committed = await finalizeLease(Outbox, event, {
+      status: "Concluído",
+      completedAt: new Date(),
+      responseSummary: sanitizeIntegrationValue(tracked.summary || response || {}),
+      lastError: {},
+      nextAttemptAt: null,
+    });
+    if (!committed) throw new GenericError("Resultado ignorado porque o lease expirou.", { statusCode: 409 });
+    return { id: String(event._id), handler: handlerKey, status: "Concluído", response };
+  } catch (error) {
+    const attempts = Number(event.attempts || 1);
+    const effectiveProvider = provider || { maxAttempts: 1, retryPolicy: { jitter: false } };
+    const classification = classifyError(effectiveProvider, error, attempts);
+    const retryPolicy = { ...effectiveProvider.retryPolicy, ...(error?.retryPolicy || {}) };
+    const committed = await finalizeLease(Outbox, event, {
+      status: classification.definitive ? "Erro definitivo" : "Erro temporário",
+      lastError: sanitizeIntegrationError(error),
+      nextAttemptAt: classification.definitive
+        ? null
+        : new Date(Date.now() + calculateBackoff(attempts, retryPolicy)),
+    });
+    if (!committed) throw new GenericError("Erro ignorado porque o lease expirou.", { statusCode: 409 });
+    return {
+      id: String(event._id),
+      handler: handlerKey,
+      status: classification.definitive ? "Erro definitivo" : "Erro temporário",
+      error: sanitizeIntegrationError(error),
+    };
+  } finally {
+    pulse.stop();
+  }
+}
+
+async function processIntegrationQueue(options = {}) {
+  const { Outbox } = getIntegrationModels();
+  const limit = Math.min(500, Math.max(1, Number(options.limit || 20)));
+  const worker = options.worker || workerId("outbox");
+  const leaseMs = Number(options.leaseMs || DEFAULT_LEASE_MS);
+  const statuses = ["Pendente", "Erro temporário", "Processando"];
+  const results = [];
+
+  for (let index = 0; index < limit; index += 1) {
+    const query = { status: { $in: statuses } };
+    if (options.provider) query.provider = String(options.provider).trim().toLowerCase();
+    const event = await acquireNext(Outbox, query, { worker, leaseMs });
+    if (!event) break;
+    try {
+      results.push(await processOutboxEvent(event, options));
+    } catch (error) {
+      results.push({ id: String(event._id), status: "Erro", error: sanitizeIntegrationError(error) });
+    }
+  }
+
+  return {
+    processed: results.filter((item) => item.status === "Concluído").length,
+    errors: results.filter((item) => item.status !== "Concluído"),
+    results,
+  };
+}
+
+async function archiveIntegrationTicket(id, reason) {
+  const { Outbox } = getIntegrationModels();
+  const ticket = await Outbox.findById(id).lean();
+  if (!ticket) throw new GenericError("Ticket de integração não encontrado.", { statusCode: 404 });
+  if (!["Erro temporário", "Erro definitivo"].includes(ticket.status)) {
+    throw new GenericError("Somente tickets com erro podem ser arquivados.", { statusCode: 409 });
+  }
+  return Outbox.findOneAndUpdate(
+    { _id: id, status: ticket.status },
+    {
+      $set: {
+        previousStatus: ticket.status,
+        status: "Arquivado",
+        archivedAt: new Date(),
+        archiveReason: String(reason || "Erro reconhecido e arquivado manualmente.").slice(0, 500),
+        nextAttemptAt: null,
+        leaseId: "",
+        lockedAt: null,
+        lockedBy: "",
+        leaseExpiresAt: null,
+        heartbeatAt: null,
+      },
+    },
+    { new: true },
+  ).lean();
+}
+
+async function reprocessIntegrationTicket(id) {
+  const { Outbox } = getIntegrationModels();
+  const ticket = await Outbox.findById(id).lean();
+  if (!ticket) throw new GenericError("Ticket de integração não encontrado.", { statusCode: 404 });
+  if (!["Erro temporário", "Erro definitivo", "Arquivado"].includes(ticket.status)) {
+    throw new GenericError("Este ticket não permite reprocessamento.", { statusCode: 409 });
+  }
+  return Outbox.findOneAndUpdate(
+    { _id: id, status: ticket.status },
+    {
+      $set: {
+        previousStatus: ticket.status,
+        status: "Pendente",
+        attempts: 0,
+        nextAttemptAt: new Date(),
+        lastError: {},
+        archivedAt: null,
+        archiveReason: "",
+        leaseId: "",
+        lockedAt: null,
+        lockedBy: "",
+        leaseExpiresAt: null,
+        heartbeatAt: null,
+      },
+    },
+    { new: true },
+  ).lean();
+}
+
+module.exports = {
+  archiveIntegrationTicket,
+  enqueueIntegration,
+  processIntegrationQueue,
+  reprocessIntegrationTicket,
+};