@danhachuel/prodmaker 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 Todas as versões seguem a etiqueta visual `MAJOR.MINOR.PATCH` com patch de dois dígitos
 (o registry NPM normaliza `0.1.00` → `0.1.0`).
 
+## 0.1.16 — 2026-10-31
+
+- **Fase 12 — Billing Stripe + E-mail Marketing (AdsAcademy) + Supabase multi-tenant pronto.**
+- **Billing:** `seed/planos.json` (Local grátis / Lançador PRO R$97 / Escala AGENCY R$297),
+  página **Plano & Assinatura** com cards, e-mail de conta e botão Assinar (abre o
+  Checkout do Stripe em nova aba); `POST /api/billing/checkout`, `/api/billing/assinatura`,
+  `/api/billing/historico` e **webhook público** `/api/billing/webhook` com verificação
+  de assinatura HMAC-SHA256 (t=...,v1=...) processando checkout.session.completed,
+  invoice.paid e customer.subscription.deleted. Sem chaves Stripe o app segue 100%
+  liberado em modo local (nenhuma trava de pré-registo).
+- **E-mail Marketing (AdsAcademy):** sequências com gatilho (`venda_recebida` dispara
+  automaticamente a cada webhook de venda, `produto_salvo`, `manual`), variáveis
+  {{nome}}/{{produto}}/{{valor}}/{{link}}, envio pelo apprise já integrado (mailtos://,
+  tgram://...), editor de sequências, envio manual e histórico com status/erro. A
+  plataforma completa emareach fica como backlog da nuvem.
+- **Supabase multi-tenant:** `DATABASE_URL` agora também aceita o alias **`SUPABASE_DB_URL`**
+  (connection string do Supabase) mantendo SQLite como fallback — user_id já cobre as
+  15 tabelas; a ativação do multi-tenant depende apenas do Supabase Auth (backlog).
+- Novas tabelas: `assinaturas`, `email_sequencias`, `email_envios`.
+
+## 0.1.15 — 2026-10-31
+
+- **Fase 11 — TikTok Ads real + Anti-Fraude AdsPixel (Redis).**
+- **TikTok Ads (publicação automática):** `publish_tiktok.py` — troca do auth_code por
+  access_token/refresh_token (`POST /api/tiktok/token`) e criação de campanha + grupo
+  PAUSADOS via Marketing API v1.3 (objective CONVERSIONS, budget diário US$,
+  placement automático); passo final do criativo com instrução honesta quando não há
+  mídia. Erros da API atribuídos. Card TikTok em Chaves de API ganhou auth_code +
+  botão "Trocar auth_code por token". AdsCreator passa a publicar TikTok de verdade.
+- **Anti-Fraude (AdsPixel):** `fraude.py` seguindo o padrão do redis-datasets/fraud-detection —
+  **IP blacklist (Redis Cuckoo Filter)** + **click spamming (Sorted Set com janela de 60s e
+  limite de 10 cliques)**; **fallback SQLite automático sem Redis**; página **Anti-Fraude**
+  (/tracking/fraude) com status do motor, bloqueio/desbloqueio manual, cópia da lista e
+  métricas de spam 24h. O `/track` agora avalia IP bloqueado antes de gravar e o pixel
+  nunca quebra a página do visitante. Card **Redis** em Chaves de API (REDIS_URL).
+- OAuth Google Ads (item 1 da Fase 11) já estava entregue na 0.1.12.
+
 ## 0.1.14 — 2026-10-31
 
 - **Fase 10 — REVISÃO (fechamento das lacunas apontadas na criação de produto/PDF).**

package/app/api/ads.py

@@ -143,11 +143,9 @@ def campanhas_publicar(campanha_id: int):
         elif plataforma == "meta":
             resultado = publish_ads.publicar_meta(campanha)
         else:
-            resultado = {
-                "plataforma": "tiktok",
-                "etapas": [{"etapa": "manual", "observacao": "TikTok: siga o checklist do plano (formato 9:16 UGC) e crie manualmente no TikTok Ads Manager."}],
-                "observacao": "Plano manual — crie manualmente no TikTok Ads Manager.",
-            }
+            from ..services import publish_tiktok
+
+            resultado = publish_tiktok.publicar_campanha(campanha)
     except LLMError as exc:
         campaigns.marcar_publicada(campanha_id, {}, status="erro", erro=str(exc))
         raise HTTPException(status_code=400, detail=str(exc))

package/app/api/billing.py

@@ -0,0 +1,63 @@
+"""Billing — planos (seed), checkout Stripe, webhook público e status da assinatura."""
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import Response
+from pydantic import BaseModel
+
+from ..services import stripe_billing
+from ..services.llm import LLMError
+
+router = APIRouter(prefix="/api/billing", tags=["billing"])
+
+
+class CheckoutBody(BaseModel):
+    plano_id: str
+    email: str
+
+
+@router.get("/planos")
+def planos():
+    return stripe_billing.planos_local()
+
+
+@router.get("/assinatura")
+def assinatura():
+    return stripe_billing.assinatura_atual()
+
+
+@router.get("/historico")
+def historico():
+    return stripe_billing.historico()
+
+
+@router.post("/checkout")
+def checkout(body: CheckoutBody, request: Request):
+    base = f"{request.url.scheme}://{request.headers.get('host', 'localhost:8188')}"
+    try:
+        return stripe_billing.criar_checkout(
+            body.plano_id,
+            body.email,
+            f"{base}/configuracoes?checkout=ok",
+            f"{base}/configuracoes?checkout=cancelado",
+        )
+    except LLMError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.options("/webhook")
+def webhook_options():
+    return Response(status_code=204)
+
+
+@router.post("/webhook")
+async def webhook_stripe(request: Request):
+    """Webhook público do Stripe — verifica assinatura e processa o evento."""
+    body = await request.body()
+    if not stripe_billing.verificar_assinatura(body, request.headers.get("stripe-signature", "")):
+        raise HTTPException(status_code=400, detail="Assinatura do webhook inválida.")
+    import json
+
+    try:
+        evento = json.loads(body)
+    except json.JSONDecodeError:
+        raise HTTPException(status_code=400, detail="Payload inválido.")
+    return stripe_billing.processar_webhook(evento)

package/app/api/email_mkt.py

@@ -0,0 +1,65 @@
+"""E-mail Marketing (AdsAcademy) — sequências com gatilho, envio manual e histórico."""
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from ..services import email_mkt
+from ..services.llm import LLMError
+
+router = APIRouter(prefix="/api/email", tags=["email"])
+
+
+class SequenciaBody(BaseModel):
+    nome: str
+    gatilho: str
+    assunto: str
+    corpo: str
+    ativo: bool = True
+
+
+class EnviarBody(BaseModel):
+    sequencia_id: int
+    destinos: list = []
+    variaveis: dict = {}
+
+
+@router.get("/sequencias")
+def sequencias():
+    return email_mkt.listar()
+
+
+@router.post("/sequencias")
+def criar(body: SequenciaBody):
+    try:
+        return email_mkt.salvar(body.nome, body.gatilho, body.assunto, body.corpo, body.ativo)
+    except LLMError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.put("/sequencias/{sequencia_id}")
+def atualizar(sequencia_id: int, body: SequenciaBody):
+    try:
+        return email_mkt.salvar(body.nome, body.gatilho, body.assunto, body.corpo, body.ativo, sequencia_id)
+    except LLMError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.delete("/sequencias/{sequencia_id}")
+def remover(sequencia_id: int):
+    try:
+        email_mkt.remover(sequencia_id)
+    except LLMError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    return {"ok": True}
+
+
+@router.post("/enviar")
+def enviar(body: EnviarBody):
+    try:
+        return email_mkt.enviar_manual(body.sequencia_id, body.destinos, body.variaveis)
+    except LLMError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.get("/historico")
+def historico():
+    return email_mkt.historico()

package/app/api/fraude.py

@@ -0,0 +1,35 @@
+"""Anti-Fraude (AdsPixel) — painel de IPs bloqueados, bloqueio/desbloqueio e resumo."""
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from ..services import fraude
+from ..services.llm import LLMError
+
+router = APIRouter(prefix="/api/fraude", tags=["anti-fraude"])
+
+
+class BloquearBody(BaseModel):
+    ip: str
+    motivo: str = "manual"
+
+
+@router.get("/resumo")
+def resumo():
+    return fraude.resumo()
+
+
+@router.post("/bloquear")
+def bloquear(body: BloquearBody):
+    try:
+        return fraude.bloquear_ip(body.ip, body.motivo)
+    except LLMError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.delete("/ips/{ip}")
+def desbloquear(ip: str):
+    try:
+        fraude.desbloquear_ip(ip)
+    except LLMError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    return {"ok": True}

package/app/api/tiktok.py

@@ -0,0 +1,16 @@
+"""TikTok Ads — troca do auth_code por access_token (1 clique)."""
+from fastapi import APIRouter, HTTPException
+
+from ..services.llm import LLMError
+from ..services.publish_tiktok import trocar_auth_code
+
+router = APIRouter(prefix="/api/tiktok", tags=["tiktok"])
+
+
+@router.post("/token")
+def token():
+    """Troca o auth_code salvo em Chaves de API por access_token + refresh_token."""
+    try:
+        return trocar_auth_code()
+    except LLMError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))

package/app/main.py

@@ -15,7 +15,7 @@ from .services.database import ensure_db, get_db, now_str, row_to_dict
 from .services.llm import LLMError, analyze_product, list_providers
 from .services.store import PRODMAKER_HOME, STORAGE, STATE, ensure_state_dir, get_master_code, get_settings, save_settings
 
-APP_VERSION = "0.1.14"
+APP_VERSION = "0.1.16"
 COOKIE_NAME = "prodmaker_session"
 SESSION_DAYS = 30
 MASTER_ALIAS = "admin"
@@ -41,6 +41,10 @@ from .api import guias as guias_router  # noqa: E402
 from .api import contas as contas_router  # noqa: E402
 from .api import invest as invest_router  # noqa: E402
 from .api import builder as builder_router  # noqa: E402
+from .api import fraude as fraude_router  # noqa: E402
+from .api import tiktok as tiktok_router  # noqa: E402
+from .api import billing as billing_router  # noqa: E402
+from .api import email_mkt as email_mkt_router  # noqa: E402
 
 app.include_router(llm_router.router)
 app.include_router(infoprodutos_router.router)
@@ -58,6 +62,10 @@ app.include_router(guias_router.router)
 app.include_router(contas_router.router)
 app.include_router(invest_router.router)
 app.include_router(builder_router.router)
+app.include_router(fraude_router.router)
+app.include_router(tiktok_router.router)
+app.include_router(billing_router.router)
+app.include_router(email_mkt_router.router)
 
 ensure_db()
 
@@ -264,7 +272,7 @@ def health():
 
 @app.get("/api/version")
 def version():
-    return {"version": APP_VERSION, "canonical": "0.1.14"}
+    return {"version": APP_VERSION, "canonical": "0.1.16"}
 
 
 @app.get("/api/settings")
@@ -300,6 +308,20 @@ def track(request: Request):
     forwarded = request.headers.get("x-forwarded-for", "")
     ip = forwarded.split(",")[0].strip() or (request.client.host if request.client else "")
     known = {"event", "page", "gclid", "utm_source", "utm_medium", "utm_campaign", "ref"}
+
+    # Anti-fraude (AdsPixel): IP bloqueado nao entra no tracking; spam e sinalizado
+    from .services import fraude
+
+    try:
+        avaliacao = fraude.avaliar_visita(ip)
+        if avaliacao.get("bloqueado"):
+            # IP na blacklist: nao grava a visita (o pixel segue respondendo 204)
+            return Response(status_code=204, headers={"Access-Control-Allow-Origin": "*"})
+        if params.get("event") == "cta_click":
+            fraude.registrar_clique(ip, params.get("page", ""))
+    except Exception:
+        pass  # anti-fraude nunca quebra o pixel
+    extra_params = json.dumps({k: v for k, v in params.items() if k not in known}, ensure_ascii=False)
     try:
         with get_db() as conn:
             conn.execute(
@@ -314,7 +336,7 @@ def track(request: Request):
                     params.get("ref", ""),
                     ip,
                     request.headers.get("user-agent", ""),
-                    json.dumps({k: v for k, v in params.items() if k not in known}, ensure_ascii=False),
+                    extra_params,
                     now_str(),
                 ),
             )

package/app/services/database.py

@@ -1,17 +1,17 @@
-"""Banco de dados — façade sobre dbengine (SQLite padrão, PostgreSQL/Supabase via DATABASE_URL).
+"""Banco de dados — fachada sobre dbengine (SQLite padrao, PostgreSQL/Supabase via DATABASE_URL).
 
-Esquema único para os dois engines. Todas as tabelas carregam `user_id` (preparação
-multi-tenant — hoje vazio). `ensure_db()` cria o que falta e aplica ALTERs de migração.
+Esquema unico para os dois engines. Todas as tabelas carregam `user_id` (preparacao
+multi-tenant — hoje vazio). `ensure_db()` cria o que falta e aplica ALTERs de migracao.
 """
 from .dbengine import (
     add_column_if_missing,
     is_postgres,
-    now_str,  # noqa: F401  (reexportado para os serviços)
-    row_to_dict,  # noqa: F401  (reexportado para os serviços)
+    now_str,  # noqa: F401  (reexportado para os servicos)
+    row_to_dict,  # noqa: F401  (reexportado para os servicos)
 )
 
 # ---------------------------------------------------------------------------
-# Esquema — SQLite DDL; para PostgreSQL as mesmas definições são traduzidas.
+# Esquema — SQLite DDL; para PostgreSQL as mesmas definicoes sao traduzidas.
 # ---------------------------------------------------------------------------
 
 TABLES = {
@@ -201,6 +201,62 @@ TABLES = {
             created_at TEXT NOT NULL
         )
     """,
+    "ips_bloqueados": """
+        CREATE TABLE IF NOT EXISTS ips_bloqueados (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            ip TEXT NOT NULL,
+            motivo TEXT NOT NULL DEFAULT 'manual',
+            origem TEXT NOT NULL DEFAULT 'sqlite',
+            created_at TEXT NOT NULL
+        )
+    """,
+    "fraude_eventos": """
+        CREATE TABLE IF NOT EXISTS fraude_eventos (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            ip TEXT NOT NULL,
+            page TEXT NOT NULL DEFAULT '',
+            created_epoch REAL NOT NULL DEFAULT 0,
+            created_at TEXT NOT NULL
+        )
+    """,
+    "assinaturas": """
+        CREATE TABLE IF NOT EXISTS assinaturas (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            plano TEXT NOT NULL DEFAULT '',
+            email TEXT NOT NULL DEFAULT '',
+            stripe_ref TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'checkout',
+            current_period_end TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL
+        )
+    """,
+    "email_sequencias": """
+        CREATE TABLE IF NOT EXISTS email_sequencias (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            nome TEXT NOT NULL,
+            gatilho TEXT NOT NULL DEFAULT 'manual',
+            assunto TEXT NOT NULL,
+            corpo TEXT NOT NULL,
+            ativo INTEGER NOT NULL DEFAULT 1,
+            created_at TEXT NOT NULL
+        )
+    """,
+    "email_envios": """
+        CREATE TABLE IF NOT EXISTS email_envios (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            sequencia_id INTEGER NOT NULL DEFAULT 0,
+            destino TEXT NOT NULL DEFAULT '',
+            assunto TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'pendente',
+            erro TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL
+        )
+    """,
 }
 
 ALL_TABLES = list(TABLES.keys())
@@ -225,11 +281,9 @@ def ensure_db() -> None:
         else:
             for ddl in TABLES.values():
                 conn.execute(ddl)
-            # Migração: bancos criados antes da coluna user_id / da tabela investimentos
+            # Migracao: bancos criados antes da coluna user_id / da tabela investimentos
             for table in ALL_TABLES:
                 add_column_if_missing(conn, table, "user_id TEXT NOT NULL DEFAULT ''", "user_id")
-            if "investimentos" not in [row["name"] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")]:
-                conn.execute(TABLES["investimentos"])
         conn.execute("CREATE INDEX IF NOT EXISTS idx_vendas_gclid ON vendas (gclid)")
         conn.execute("CREATE INDEX IF NOT EXISTS idx_visitas_gclid ON visitas (gclid)")
 

package/app/services/dbengine.py

@@ -31,7 +31,8 @@ def row_to_dict(row) -> dict:
 
 
 def dsn() -> str | None:
-    return (os.environ.get("DATABASE_URL") or "").strip() or None
+    """Connection string do PostgreSQL — aceita DATABASE_URL ou SUPABASE_DB_URL."""
+    return (os.environ.get("DATABASE_URL") or os.environ.get("SUPABASE_DB_URL") or "").strip() or None
 
 
 def is_postgres() -> bool:

package/app/services/email_mkt.py

@@ -0,0 +1,146 @@
+"""E-mail Marketing / AdsAcademy — sequências transacionais via apprise.
+
+Emareach (plataforma completa self-hosted) fica como backlog da nuvem; aqui o
+motor honesto é o apprise já integrado: sequências com gatilho (venda recebida,
+produto salvo, manual), variáveis {{nome}}, {{produto}}, {{valor}}, {{link}} e
+histórico de envios. Sem canais configurados: erro claro, nunca silencioso.
+"""
+import re
+
+from .database import get_db, now_str, row_to_dict
+from .llm import LLMError
+
+
+def _render(texto: str, variaveis: dict) -> str:
+    for chave, valor in (variaveis or {}).items():
+        texto = texto.replace("{{" + chave + "}}", str(valor or ""))
+    return texto
+
+
+def listar(gatilho: str = "") -> list[dict]:
+    query = "SELECT * FROM email_sequencias"
+    params: tuple = ()
+    if gatilho:
+        query += " WHERE gatilho = ?"
+        params = (gatilho,)
+    query += " ORDER BY id DESC"
+    with get_db() as conn:
+        rows = conn.execute(query, params).fetchall()
+    return [row_to_dict(row) for row in rows]
+
+
+def salvar(nome: str, gatilho: str, assunto: str, corpo: str, ativo: bool = True, sequencia_id: int | None = None) -> dict:
+    if not nome.strip() or not assunto.strip() or not corpo.strip():
+        raise LLMError("Informe nome, assunto e corpo da sequência.")
+    if gatilho not in ("venda_recebida", "produto_salvo", "manual"):
+        raise LLMError("Gatilho inválido: use venda_recebida, produto_salvo ou manual.")
+    with get_db() as conn:
+        if sequencia_id:
+            cursor = conn.execute(
+                "UPDATE email_sequencias SET nome = ?, gatilho = ?, assunto = ?, corpo = ?, ativo = ? WHERE id = ?",
+                (nome.strip(), gatilho, assunto.strip(), corpo, bool(ativo), sequencia_id),
+            )
+            if cursor.rowcount == 0:
+                raise LLMError("Sequência não encontrada.")
+        else:
+            cursor = conn.execute(
+                "INSERT INTO email_sequencias (nome, gatilho, assunto, corpo, ativo, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+                (nome.strip(), gatilho, assunto.strip(), corpo, bool(ativo), now_str()),
+            )
+            sequencia_id = cursor.lastrowid
+        row = conn.execute("SELECT * FROM email_sequencias WHERE id = ?", (sequencia_id,)).fetchone()
+    return row_to_dict(row)
+
+
+def remover(sequencia_id: int) -> None:
+    with get_db() as conn:
+        cursor = conn.execute("DELETE FROM email_sequencias WHERE id = ?", (sequencia_id,))
+        if cursor.rowcount == 0:
+            raise LLMError("Sequência não encontrada.")
+
+
+def _variaveis_padrao() -> dict:
+    settings_nome = "cliente"
+    return {"nome": settings_nome, "produto": "seu produto", "valor": "", "link": ""}
+
+
+def aplicar_gatilho(gatilho: str, variaveis: dict, destinos: list[str] | None = None) -> dict:
+    """Dispara as sequências ativas do gatilho (usado pelos hooks de venda/produto)."""
+    enviados = []
+    erros = []
+    for sequencia in listar(gatilho):
+        if not sequencia["ativo"]:
+            continue
+        assunto = _render(sequencia["assunto"], variaveis)
+        corpo = _render(sequencia["corpo"], variaveis)
+        try:
+            _enviar(sequencia, destinos or [], assunto, corpo)
+            enviados.append(sequencia["id"])
+        except LLMError as exc:
+            _registrar_envio(sequencia["id"], "", assunto, "erro", str(exc))
+            erros.append(str(exc))
+    return {"enviados": enviados, "erros": erros}
+
+
+def enviar_manual(sequencia_id: int, destinos: list[str], variaveis: dict) -> dict:
+    with get_db() as conn:
+        row = conn.execute("SELECT * FROM email_sequencias WHERE id = ?", (sequencia_id,)).fetchone()
+    if not row:
+        raise LLMError("Sequência não encontrada.")
+    sequencia = row_to_dict(row)
+    if not destinos:
+        raise LLMError("Informe ao menos um destino (URL apprise, ex.: mailtos://user:senha@smtp.com).")
+    assunto = _render(sequencia["assunto"], {**_variaveis_padrao(), **(variaveis or {})})
+    corpo = _render(sequencia["corpo"], {**_variaveis_padrao(), **(variaveis or {})})
+    _enviar(sequencia, destinos, assunto, corpo)
+    return {"ok": True, "assunto": assunto}
+
+
+def _enviar(sequencia: dict, destinos: list, assunto: str, corpo: str) -> None:
+    from . import notify
+
+    alvos = [str(item).strip() for item in (destinos or []) if str(item).strip()]
+    if not alvos:
+        config = notify.listar_config()
+        alvos = [item for item in (config.get("targets") or [])]
+    if not alvos:
+        erro = "Nenhum canal apprise configurado (settings.notifications.targets)."
+        _registrar_envio(sequencia["id"], "", assunto, "erro", erro)
+        raise LLMError(erro)
+    telegram = notify._telegram_target()
+    if telegram and telegram not in alvos:
+        alvos.insert(0, telegram)
+    try:
+        import apprise
+
+        apobj = apprise.Apprise()
+        validos = [alvo for alvo in alvos if apobj.add(alvo)]
+        if not validos:
+            erro = "Nenhum canal apprise válido."
+            _registrar_envio(sequencia["id"], ",".join(alvos), assunto, "erro", erro)
+            raise LLMError(erro)
+        if apobj.notify(title=assunto, body=corpo):
+            _registrar_envio(sequencia["id"], ",".join(validos), assunto, "enviada")
+        else:
+            erro = "apprise não conseguiu entregar."
+            _registrar_envio(sequencia["id"], ",".join(validos), assunto, "erro", erro)
+            raise LLMError(erro)
+    except ImportError as exc:
+        erro = f"apprise ausente ({exc.name}) — rode 'prodmaker install'."
+        _registrar_envio(sequencia["id"], "", assunto, "erro", erro)
+        raise LLMError(erro)
+
+
+def _registrar_envio(sequencia_id: int, destino: str, assunto: str, status: str, erro: str = "") -> None:
+    with get_db() as conn:
+        conn.execute(
+            "INSERT INTO email_envios (sequencia_id, destino, assunto, status, erro, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+            (sequencia_id, destino, assunto[:180], status, erro[:500], now_str()),
+        )
+
+
+def historico(limit: int = 50) -> dict:
+    with get_db() as conn:
+        envios = [row_to_dict(row) for row in conn.execute("SELECT * FROM email_envios ORDER BY id DESC LIMIT ?", (limit,))]
+        totais = {row["status"]: row["n"] for row in conn.execute("SELECT status, COUNT(*) AS n FROM email_envios GROUP BY status")}
+    return {"envios": envios, "totais": totais}