@oondemand/create-central-oon 0.6.9 → 0.6.11

package/docs/AGENTS.md

@@ -28,13 +28,15 @@ O `AGENTS.md` da raiz pertence ao projeto e nunca pode ser sobrescrito pelo scaf
 | Domínio, models, validações e fórmulas | [BACKEND_API.md](BACKEND_API.md), [BACKEND_DOMAIN_MANIFEST.md](BACKEND_DOMAIN_MANIFEST.md), [BACKEND_PATTERNS.md](BACKEND_PATTERNS.md), [REACTIVE_DOMAIN_FORMULAS.md](REACTIVE_DOMAIN_FORMULAS.md) |
 | CRUD, metadata e UI | [METADATA_CRUD_UI.md](METADATA_CRUD_UI.md), [FRONTEND_API.md](FRONTEND_API.md), [FRONTEND_CODE_FIRST.md](FRONTEND_CODE_FIRST.md) |
 | Auth, ativação, tenant ou permissões | [AUTH_ACTIVATION_RBAC.md](AUTH_ACTIVATION_RBAC.md), [RBAC_SECURITY.md](RBAC_SECURITY.md), [DO_AND_DONT.md](DO_AND_DONT.md) |
-| Renderizar, visualizar ou baixar PDF | [PDF_RENDERING.md](PDF_RENDERING.md), [BACKEND_API.md](BACKEND_API.md), [FRONTEND_API.md](FRONTEND_API.md) |
-| Configurar templates ou enviar e-mail | [TRANSACTIONAL_EMAIL.md](TRANSACTIONAL_EMAIL.md), [RBAC_SECURITY.md](RBAC_SECURITY.md) |
+| Renderizar, visualizar ou baixar PDF | [APP_LICENSING.md](APP_LICENSING.md), [PDF_RENDERING.md](PDF_RENDERING.md), [BACKEND_API.md](BACKEND_API.md), [FRONTEND_API.md](FRONTEND_API.md) |
+| Configurar templates ou enviar e-mail | [APP_LICENSING.md](APP_LICENSING.md), [TRANSACTIONAL_EMAIL.md](TRANSACTIONAL_EMAIL.md), [RBAC_SECURITY.md](RBAC_SECURITY.md) |
 | Execução local | [RUNTIME_MODES.md](RUNTIME_MODES.md), [LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md), [LOCAL_SECURITY_BOUNDARY.md](LOCAL_SECURITY_BOUNDARY.md) |
-| Rotas, hooks, jobs e filas | [ROUTES_HOOKS_WORKERS.md](ROUTES_HOOKS_WORKERS.md), [BACKEND_PATTERNS.md](BACKEND_PATTERNS.md) |
+| Rotas, hooks, jobs e filas | [APP_LICENSING.md](APP_LICENSING.md), [ROUTES_HOOKS_WORKERS.md](ROUTES_HOOKS_WORKERS.md), [BACKEND_PATTERNS.md](BACKEND_PATTERNS.md) |
 | Upgrade do Core | [CORE_UPGRADE.md](CORE_UPGRADE.md), [TESTING_CONFORMANCE.md](TESTING_CONFORMANCE.md), [releases/0.6.0.md](releases/0.6.0.md) |
 | UX avançada | [ADVANCED_UX_PATTERNS.md](ADVANCED_UX_PATTERNS.md), [DETAIL_MODAL_AND_RELATED_GRIDS.md](DETAIL_MODAL_AND_RELATED_GRIDS.md), [PORTAL_COCKPIT_PATTERNS.md](PORTAL_COCKPIT_PATTERNS.md) |
 
+Antes de copiar exemplos de efeitos de negócio, determine a categoria do App pelo contrato governado. Em App comercial licenciado, aplique [APP_LICENSING.md](APP_LICENSING.md) antes de cada novo efeito. Root/globais tenantless não recebem tenant ou licença comercial artificiais; ausência de tenant em um App comercial não é isenção. Runtime local permanece sem efeitos operacionais.
+
 ## Fronteira obrigatória
 
 - O App declara domínio e experiência em código; o Core fornece bootstrap, autenticação, ativação, RBAC, tenant, CRUD, metadata, shell, componentes genéricos e deployment.
@@ -54,3 +56,4 @@ npm test
 ```
 
 Uma entrega que depende da leitura de fonte privada ou de outro App não está concluída: registre a lacuna na documentação distribuída.
+

package/docs/APP_LICENSING.md

@@ -28,6 +28,14 @@ Um contrato bloqueado retorna HTTP 423 com código `APP_LICENSE_REQUIRED`,
 Bloqueios organizacionais e de entitlement também são preservados.
 Exiba a razão comercial; deixe a operação pendente. Pagamento não renova nem reativa sozinho.
 
+## Aplicabilidade: comercial, root/global e local
+
+O guard abaixo se aplica a novos efeitos de negócio de um **App comercial licenciado**, com tenant obtido do contexto autenticado do backend. A licença de uso do App e a assinatura própria do cliente são independentes; o consumidor consulta a decisão da Central, sem recalcular essas regras.
+
+Root e globais tenantless seguem sua autoridade operacional e RBAC próprios: não crie tenant, proprietário comercial ou licença fictícios para fazê-los passar pelo guard. A categoria vem do contrato governado do App, nunca de um booleano enviado pelo cliente, da ausência de tenant ou de um override de ambiente. Contexto de tenant ausente em App comercial deve falhar, sem executar o efeito.
+
+No runtime local não existe autorização operacional. Use mocks da fronteira de licenciamento e da capability somente em testes isolados; não transforme indisponibilidade em sucesso nem injete credenciais operacionais.
+
 ## Gateway que recebe chamadas de outros Apps
 
 ```js
@@ -64,3 +72,4 @@ Este contrato oferece o guard de efeitos, não um executor durável de integraç
 A documentação de process jobs existente não especifica registro público de handlers
 externos, inbox/outbox e retomada autônoma necessários ao gateway da issue #170.
 Essa extensão precisa de contrato e testes próprios antes de declarar I4 concluída.
+

package/docs/PDF_RENDERING.md

@@ -21,9 +21,12 @@ Não adicione URL, usuário, senha ou implementation reference. O runtime resolv
 
 ## API pública do backend
 
+O exemplo é para **App comercial licenciado**; leia [APP_LICENSING.md](APP_LICENSING.md) antes de usá-lo. Root/globais tenantless não recebem tenant ou licença artificiais, e ausência de tenant em App comercial não dispensa o guard. A categoria não é escolhida pelo request. Runtime local não autoriza geração operacional.
+
 ```js
 const {
   capabilities,
+  licensing,
   defineRoutes,
   GenericError,
   requirePermission,
@@ -47,6 +50,10 @@ defineRoutes("/pdf", (router) => {
       res.once("close", abort);
 
       try {
+        await licensing.assertBusinessOperation({
+          tenantId: req.accessContext?.tenantId,
+          correlationId: req.id,
+        });
         const pdf = await capabilities.pdf.render(
           {
             html: req.body.html,
@@ -130,6 +137,8 @@ Nunca envie a geração diretamente a um endpoint de infraestrutura pelo navegad
 
 ## Erros
 
+O guard propaga `423` com o código comercial (por exemplo, `APP_LICENSE_SUSPENDED`) ou `503`/`LICENSE_AUTHORITY_UNAVAILABLE`. Preserve o erro no tratamento padrão do Core, mostre o motivo e mantenha a operação pendente; não capture para continuar a geração nem devolva sucesso. O frontend deve tratar esses status também quando a resposta foi solicitada como blob. Contexto comercial ausente também impede a geração.
+
 `PdfRenderingError` expõe `code`, `statusCode`, `retryable` e detalhes sanitizados.
 
 | Código | Retry | Significado |
@@ -144,7 +153,7 @@ Nunca envie a geração diretamente a um endpoint de infraestrutura pelo navegad
 | `PDF_RENDERING_TRANSPORT_ERROR` | sim | falha transitória de transporte |
 | `PDF_RENDERING_INVALID_OUTPUT` | sim | saída inválida ou acima do limite |
 
-Use retentativas apenas quando `error.retryable === true`, com backoff e idempotência na operação chamadora.
+Use retentativas da capability apenas quando `error.retryable === true`, com backoff e idempotência na operação chamadora. Cada nova tentativa de geração deve passar novamente pelo guard; uma decisão anterior ou um job já aceito não autoriza a próxima chamada. A consulta é pontual, não atômica com o start: não cancela nem desfaz geração já iniciada. Downloads de documentos já produzidos não iniciam nova geração e seguem as regras de acesso existentes.
 
 ## Segurança e runtime local
 
@@ -155,3 +164,4 @@ Use retentativas apenas quando `error.retryable === true`, com backoff e idempot
 - propague cancelamento do request por `AbortSignal`;
 - no runtime local, a capability falha fechado com `PDF_RENDERING_UNAVAILABLE` quando não resolvida;
 - em testes automatizados, um transport fake pode ser injetado por `capabilities.configurePdfRendering` e deve devolver bytes iniciados por `%PDF-`; não gere um “PDF” textual falso no código do App.
+

package/docs/TRANSACTIONAL_EMAIL.md

@@ -54,10 +54,16 @@ Templates usam somente interpolação Handlebars escapada. Blocos, helpers, sube
 
 ## Envio no backend
 
+Leia [APP_LICENSING.md](APP_LICENSING.md). O exemplo de **App comercial licenciado** demonstra somente a revalidação antes de enfileirar, verificável com mocks isolados. **Não habilita envio comercial assíncrono operacional**: a pendência do executor abaixo precisa ser resolvida antes disso. Root/globais tenantless seguem autoridade/RBAC próprios, sem tenant ou licença artificiais. A categoria não vem do request; tenant ausente em App comercial não é isenção. Runtime local não autoriza envio operacional.
+
 ```js
-const { capabilities } = require("@oondemand/oon-core-back");
+const { capabilities, licensing } = require("@oondemand/oon-core-back");
 
 async function enviarConfirmacao({ email, nome, idempotencyKey }, req) {
+  await licensing.assertBusinessOperation({
+    tenantId: req.accessContext?.tenantId,
+    correlationId: req.id,
+  });
   return capabilities.transactionalEmail.send(
     {
       templateCode: "confirmacao",
@@ -77,6 +83,14 @@ async function enviarConfirmacao({ email, nome, idempotencyKey }, req) {
 
 `idempotencyKey` é obrigatória. O retorno é `{ dispatchId, status, correlationId }`; `status` é `accepted` ou `duplicate`. Não trate `accepted` como entrega confirmada.
 
+### Licenciamento, fila e retentativas
+
+O guard propaga `423` com o código comercial (por exemplo, `APP_LICENSE_SUSPENDED`) ou `503`/`LICENSE_AUTHORITY_UNAVAILABLE`. Preserve status/código no tratamento padrão do Core, mostre o motivo e mantenha a operação pendente, sem enfileirar ou devolver sucesso. Contexto comercial ausente também impede o enqueue. Não use pagamento, cache positivo ou captura do erro como autorização.
+
+A autorização no enqueue não autoriza um envio futuro. O executor precisa revalidar a autoridade e o contexto antes de **cada tentativa** no provedor, inclusive retry automático e retry de dead letter. Em OonCore 0.6.10, este exemplo não comprova essa integração no worker; não há neste contrato uma opção pública para adicioná-la. Não habilite esse caminho comercial até existir contrato/implementação e prova isolada de suspensão ou revogação entre enqueue e envio, indisponibilidade, contexto divergente e retentativa. Não contorne essa lacuna acessando internals do SDK ou criando executor paralelo no App.
+
+Mesmo uma revalidação correta é pontual e não atômica com o envio: não cancela chamada já iniciada nem desfaz e-mail aceito pelo provedor. Recibos, callbacks, reconciliação e histórico de efeitos anteriores devem continuar acessíveis conforme suas regras; não confunda essas operações com um novo envio. `accepted` e `duplicate` não são comprovantes de autorização duradoura nem de entrega.
+
 Outras operações públicas do namespace `capabilities.transactionalEmail` incluem preview e versionamento de templates, consulta de dispatches e retry de dead letter. Para administração interativa, prefira o componente do Core.
 
 ## Painel administrativo
@@ -109,3 +123,4 @@ O componente usa as rotas autenticadas em `/core/transactional-email/*`. Credenc
 - erros usam `TransactionalEmailError` e códigos `EMAIL_*` sanitizados;
 - no runtime local, falhe fechado até a capability e seu secret store/configuração estarem disponíveis;
 - testes devem substituir a fronteira externa; não envie e-mail real e não grave credenciais de teste.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/create-central-oon",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/templates/_base/backend/package.json

@@ -12,6 +12,6 @@
     "deploy": "oonCore-back deploy"
   },
   "dependencies": {
-    "@oondemand/oon-core-back": "^0.6.9"
+    "@oondemand/oon-core-back": "^0.6.11"
   }
 }

package/templates/_base/frontend/package.json

@@ -11,7 +11,7 @@
     "sync:metadata": "oonCore-front sync:metadata"
   },
   "dependencies": {
-    "@oondemand/oon-core-front": "^0.6.9",
+    "@oondemand/oon-core-front": "^0.6.11",
     "@chakra-ui/react": "^3.13.0",
     "@emotion/react": "^11.14.0",
     "@tanstack/react-query": "^5.65.0",

package/templates/_base/package.json

@@ -13,6 +13,6 @@
     "dev:frontend": "npm run dev --prefix frontend"
   },
   "devDependencies": {
-    "@oondemand/create-central-oon": "0.6.9"
+    "@oondemand/create-central-oon": "0.6.11"
   }
 }