@danhachuel/thunderbolt 0.4.93 → 0.4.94

package/README.md

@@ -451,3 +451,11 @@ O Thunderbolt integra o [jusTokenMax](https://github.com/Kalmantic/jusTokenMax)
 A configuração encontra-se em **Configuração API > API Keys > Optimização de tokens — jusTokenMax**. É possível activar ou desactivar o optimizador, controlar os levers por tipo, verificar a versão instalada, consultar métricas e limpar apenas os artefactos derivados. Os originais permanecem em `storage/state/token_optimizer_originals/` e podem ser recuperados pelo hash através do módulo interno.
 
 A instalação do pacote inclui `justokenmax` a partir do repositório oficial. Se o CLI não estiver disponível ou ocorrer um erro, o Thunderbolt usa o conteúdo original e regista um fallback local; a geração não fica bloqueada. API keys, passwords, tokens e blobs base64 são redigidos antes de serem guardados em artefactos derivados.
+
+## Canva Skills — automação criativa
+
+O Thunderbolt inclui as seis Canva Skills activas do pacote oficial `canva-sdks/canva-skills`, adaptadas para chamadas REST directas: `resize-for-social-media`, `bulk-create`, `implement-feedback`, `edit-design`, `get-design-feedback` e `brand-check`. A página `Canva Skills` permite executar as operações sobre um card Canva autorizado em **Configuração API > API Keys > Imagem e Video IA**.
+
+A criação em lote usa o endpoint oficial de Autofill e requer Canva Enterprise (ou quota de trial durante desenvolvimento). A criação de variantes sociais copia o design e exporta cada variante; a Connect REST pública não oferece um endpoint geral de resize responsivo, por isso a dimensão alvo é registada e o link de edição Canva é disponibilizado para ajustes finais. A API REST também não expõe as transacções de edição usadas pelo MCP; `edit-design` e `implement-feedback` funcionam como preparação aprovada e identificam claramente as alterações que exigem edição manual, sem efectuar commits falsos.
+
+O fluxo automático de thumbnails continua a usar Canva exclusivamente no Pool de Imagem para thumbnails. Canva nunca é seleccionado para geração de vídeo. Consulte `app/modules/canva_skills/` para os módulos e `app/pages/canva_skills.py` para a interface.

package/app/modules/canva_skills/__init__.py

@@ -0,0 +1,14 @@
+"""Deterministic REST adaptations of the active Canva agent skills."""
+
+from .config import CANVA_SKILL_SCOPES, PLATFORM_DIMENSIONS
+from .resize import resize_for_social_media
+from .bulk import bulk_create_thumbnails
+from .feedback import get_design_feedback, implement_feedback
+from .edit import edit_design
+from .brand import list_brand_kits, check_brand_compliance
+
+__all__ = [
+    "CANVA_SKILL_SCOPES", "PLATFORM_DIMENSIONS", "resize_for_social_media",
+    "bulk_create_thumbnails", "get_design_feedback", "implement_feedback",
+    "edit_design", "list_brand_kits", "check_brand_compliance",
+]

package/app/modules/canva_skills/brand.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .client import CanvaSkillsClient
+
+
+def list_brand_kits(*, client: CanvaSkillsClient) -> list[dict[str, Any]]:
+    payload = client.get("brand-templates", {"limit": 100})
+    return list(payload.get("items") or payload.get("brand_templates") or [])
+
+
+def check_brand_compliance(design_id: str, brand_kit_id: str, *, client: CanvaSkillsClient) -> dict[str, Any]:
+    design = client.get(f"designs/{design_id}").get("design", {})
+    templates = list_brand_kits(client=client)
+    selected = next((item for item in templates if str(item.get("id")) == brand_kit_id), None)
+    if selected is None:
+        raise ValueError("Brand Template/kit não encontrado ou sem permissão.")
+    return {"design_id": design_id, "brand_kit_id": brand_kit_id, "on_brand": [], "off_brand": [], "cannot_verify": [{"category": "colors", "reason": "A metadata REST não expõe paleta completa."}, {"category": "typography", "reason": "A metadata REST não expõe fontes completas."}, {"category": "logo", "reason": "É necessária inspecção visual no Canva."}], "design_title": design.get("title", ""), "brand_template_title": selected.get("title", "")}

package/app/modules/canva_skills/bulk.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .client import CanvaSkillsClient
+
+
+def _autofill(client: CanvaSkillsClient, template_id: str, row: Mapping[str, Any], title: str) -> str:
+    data = {key: value if isinstance(value, Mapping) else {"type": "text", "text": str(value)} for key, value in row.items()}
+    payload = client.post("autofills", {"type": "create_from_brand_template", "brand_template_id": template_id, "data": data, "title": title[:255] or "Thunderbolt thumbnail"})
+    job = payload.get("job") or payload
+    job_id = str(job.get("id") or "")
+    if not job_id:
+        raise RuntimeError("A Canva não devolveu o job de autofill.")
+    for _ in range(60):
+        status_payload = client.get(f"autofills/{job_id}")
+        status_job = status_payload.get("job") or status_payload
+        status = str(status_job.get("status") or "").lower()
+        if status == "success":
+            design = status_job.get("design") or {}
+            design_id = str(design.get("id") or status_job.get("design_id") or "")
+            if design_id:
+                return design_id
+        if status == "failed":
+            raise RuntimeError(f"Autofill Canva falhou: {status_job.get('error') or status_job}")
+    raise RuntimeError("Autofill Canva excedeu o tempo de espera.")
+
+
+def bulk_create_thumbnails(template_id: str, data: list[Mapping[str, Any]], export_format: str = "png", *, client: CanvaSkillsClient) -> list[dict[str, Any]]:
+    if not template_id.strip():
+        raise ValueError("É necessário indicar um Brand Template Canva.")
+    results = []
+    for row in data:
+        design_id = _autofill(client, template_id, row, str(row.get("titulo") or row.get("title") or "Thunderbolt thumbnail"))
+        job_id = client.export_design(design_id, file_type=export_format.lower())
+        results.append({"design_id": design_id, "export_url": client.wait_export(job_id), "metadata": dict(row)})
+    return results

package/app/modules/canva_skills/client.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from hermes_ui.canva_client import CanvaClient
+
+
+class CanvaSkillsClient(CanvaClient):
+    """REST client shared by the adapted Canva Skills."""
+
+    def get(self, endpoint: str, params: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", endpoint, params=params)
+
+    def post(self, endpoint: str, data: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", endpoint, json=data or {})
+
+    def delete(self, endpoint: str) -> dict[str, Any]:
+        return self.request("DELETE", endpoint)
+
+
+def client_from_card(card: Mapping[str, Any], token_saver=None) -> CanvaSkillsClient:
+    return CanvaSkillsClient(card, token_saver=token_saver)

package/app/modules/canva_skills/config.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+PLATFORM_DIMENSIONS = {
+    "youtube_thumbnail": (1280, 720),
+    "tiktok": (1080, 1920),
+    "instagram_post": (1080, 1080),
+    "instagram_story": (1080, 1920),
+    "facebook_post": (1200, 630),
+    "facebook_story": (1080, 1920),
+    "linkedin_post": (1200, 627),
+}
+
+CANVA_SKILL_SCOPES = "design:content:read design:content:write design:meta:read brandtemplate:meta:read brandtemplate:content:read comment:read comment:write"
+SUPPORTED_EXPORT_FORMATS = {"png", "jpg"}

package/app/modules/canva_skills/edit.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .client import CanvaSkillsClient
+
+
+def edit_design(design_id: str, changes: Mapping[str, Any], *, client: CanvaSkillsClient, auto_commit: bool = False) -> dict[str, Any]:
+    """Prepare a safe edit request; REST Connect has no public edit transaction endpoint."""
+    if not auto_commit:
+        return {"status": "pending_approval", "design_id": design_id, "changes": dict(changes)}
+    return {"status": "manual_action_required", "design_id": design_id, "changes": dict(changes), "message": "A Canva Connect REST API não expõe start/perform/commit editing transactions; abra o edit_url no Canva para aplicar estas alterações manualmente."}

package/app/modules/canva_skills/feedback.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .client import CanvaSkillsClient
+
+
+def get_design_feedback(design_id: str, *, client: CanvaSkillsClient) -> dict[str, Any]:
+    design_payload = client.get(f"designs/{design_id}")
+    design = design_payload.get("design") or design_payload
+    findings = []
+    title = str(design.get("title") or "").strip()
+    if not title:
+        findings.append({"category": "readability", "severity": "medium", "message": "O design não tem título identificável na metadata."})
+    thumb = design.get("thumbnail") or {}
+    if thumb.get("width") and thumb.get("height") and thumb["width"] / thumb["height"] < 1.5:
+        findings.append({"category": "layout", "severity": "high", "message": "A proporção da thumbnail parece inadequada para YouTube 16:9."})
+    return {"design_id": design_id, "visual_hierarchy": findings, "layout": [], "readability": [], "consistency": [], "accessibility": [], "limitations": ["A Connect REST não expõe uma análise visual completa nem listagem de threads de comentários; os itens não verificáveis ficam explícitos."]}
+
+
+def implement_feedback(design_id: str, feedback_items: list[Mapping[str, Any]], *, client: CanvaSkillsClient, approved: bool = False) -> dict[str, Any]:
+    if not approved:
+        return {"status": "pending_approval", "design_id": design_id, "items": [dict(item) for item in feedback_items]}
+    return {"status": "manual_action_required", "design_id": design_id, "applied": [], "manual": [dict(item) for item in feedback_items], "message": "A Connect REST pública não fornece transacções de edição; nenhuma alteração foi cometida."}

package/app/modules/canva_skills/models.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PlatformAsset:
+    platform: str
+    width: int
+    height: int
+    design_id: str = ""
+    export_url: str = ""
+    edit_url: str = ""
+
+
+@dataclass
+class SkillResult:
+    status: str
+    message: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class FeedbackItem:
+    category: str
+    text: str
+    actionable: bool = False
+    source_id: str = ""

package/app/modules/canva_skills/resize.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .client import CanvaSkillsClient
+from .config import PLATFORM_DIMENSIONS, SUPPORTED_EXPORT_FORMATS
+
+
+def resize_for_social_media(design_id: str, platforms: list[str], export_format: str = "png", *, client: CanvaSkillsClient) -> dict[str, dict[str, Any]]:
+    """Create platform variants and export them.
+
+    Connect REST currently has no general resize endpoint. The skill therefore
+    creates a copy for each platform and records target dimensions; users can
+    refine the copy through Canva's edit URL when exact responsive layout is
+    required.
+    """
+    if export_format.lower() not in SUPPORTED_EXPORT_FORMATS:
+        raise ValueError("O formato deve ser png ou jpg.")
+    results: dict[str, dict[str, Any]] = {}
+    for platform in platforms:
+        if platform not in PLATFORM_DIMENSIONS:
+            continue
+        copied = client.post("designs", {"type": "design", "design_id": design_id, "page_numbers": [1]})
+        design = copied.get("design") or copied
+        variant_id = str(design.get("id") or "")
+        if not variant_id:
+            raise RuntimeError(f"A Canva não devolveu o design da variante {platform}.")
+        job_id = client.export_design(variant_id, file_type=export_format.lower())
+        url = client.wait_export(job_id)
+        urls = design.get("urls") or {}
+        results[platform] = {"design_id": variant_id, "export_url": url, "edit_url": urls.get("edit_url", ""), "width": PLATFORM_DIMENSIONS[platform][0], "height": PLATFORM_DIMENSIONS[platform][1], "resize_note": "A Connect REST não aplica resize responsivo; a dimensão é metadado para edição/exportação."}
+    return results

package/hermes_ui/canva_client.py

@@ -35,12 +35,12 @@ class CanvaClient:
             self._save_token(refresh_access_token(self.client_id, self.client_secret, refresh))
         return str(self.token["access_token"])
 
-    def request(self, method: str, path: str, *, json: Mapping[str, Any] | None = None, timeout: int = 60) -> dict[str, Any]:
+    def request(self, method: str, path: str, *, json: Mapping[str, Any] | None = None, params: Mapping[str, Any] | None = None, timeout: int = 60) -> dict[str, Any]:
         refreshed = False
         for attempt in range(4):
             try:
                 token = self._access_token()
-                response = requests.request(method, f"{self.base_url}/{path.lstrip('/')}", headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", "Accept": "application/json"}, json=json, timeout=timeout)
+                response = requests.request(method, f"{self.base_url}/{path.lstrip('/')}", headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", "Accept": "application/json"}, json=json, params=params, timeout=timeout)
             except requests.RequestException as exc:
                 if attempt == 3:
                     raise RuntimeError(f"Falha de rede na Canva: {str(exc)[:200]}") from exc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.4.93",
+  "version": "0.4.94",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "license": "MIT",
   "main": "scripts/cli.mjs",