Métricas de uso

Apps comercializados na Plataforma podem medir consumo — pedidos emitidos, documentos processados, mensagens enviadas — e a Central de Ativações usa esses números para planos, limites e excedentes.

1. Declare as métricas

{
  "usageMetrics": [
    {
      "code": "pedidos",
      "name": "Pedidos emitidos",
      "unit": "pedido",
      "description": "Cada pedido enviado ao fornecedor.",
      "defaults": {
        "included": 500,
        "onLimit": "block",
        "overage": { "mode": "unit", "priceMinor": 50 }
      }
    }
  ]
}

Até 10 métricas. GET /core/usage-metrics publica a lista para a Central pré-preencher os limites do plano.

2. Registre o consumo

const { usage } = require("@oondemand/oon-core-back");

usage.record("pedidos", 1, { tenantId: req.accessContext.tenantId });

record acumula em memória e envia a cada OON_USAGE_FLUSH_MS (padrão 15 s) um lote com ID único. O lote passa pela outbox oon_usage_outbox no MongoDB do App: sobrevive a reinício, qualquer réplica reenvia (lease de 30 s, backoff, até 20 tentativas) e a Central conta cada ID uma vez. O encerramento do processo grava o que estiver em memória.

3. Bloqueie no limite

// Confere antes de uma operação cara
await usage.assertAvailable("pedidos", { tenantId: req.accessContext.tenantId });

Recusa com 423 USAGE_LIMIT_REACHED quando o plano bloqueia ao atingir o incluído, somando o estado da Central (cache de 60 s) e o consumo ainda não enviado. Sem resposta da Central, a operação segue.

Em uma rota privada, confira antes e registre depois do sucesso:

const { defineRoutes, usage } = require("@oondemand/oon-core-back");

defineRoutes("/pedidos-envio", (router) => {
  router.private.post("/:id/enviar", { permission: "pedidos.write" }, async (req, res) => {
    await usage.assertAvailable("pedidos", { tenantId: req.accessContext.tenantId });
    // ... envia
    usage.record("pedidos", 1, { tenantId: req.accessContext.tenantId });
    res.json({ ok: true });
  });
});

usage.limit(metric) também existe como middleware Express (confere o limite e registra 1 uso nas respostas 2xx) para composições fora de router.private.

Erros

No runtime local nada é enviado ({ recorded: false, reason: "local" }).