bps-kit 1.0.1 → 1.0.2

package/templates/vault/instagram/scripts/governance.py

@@ -0,0 +1,233 @@
+"""
+Governança: rate limiting, audit log e confirmações para ações do Instagram.
+
+Rate limits são rastreados via SQLite (action_log table).
+Confirmações usam padrão 2-step: retorna JSON com requires_confirmation,
+Claude apresenta ao usuário, e na segunda chamada com --confirm executa.
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from config import (
+    ACTION_CATEGORIES,
+    RATE_LIMIT_DMS_PER_HOUR,
+    RATE_LIMIT_HASHTAGS_PER_WEEK,
+    RATE_LIMIT_PUBLISHES_PER_DAY,
+    RATE_LIMIT_REQUESTS_PER_HOUR,
+    RATE_LIMIT_WARNING_THRESHOLD,
+)
+from db import Database
+
+
+class RateLimitExceeded(Exception):
+    """Limite de taxa excedido."""
+
+    def __init__(self, limit_type: str, current: int, maximum: int, retry_after_seconds: int):
+        self.limit_type = limit_type
+        self.current = current
+        self.maximum = maximum
+        self.retry_after_seconds = retry_after_seconds
+        super().__init__(
+            f"Rate limit '{limit_type}' excedido: {current}/{maximum}. "
+            f"Tente novamente em {retry_after_seconds}s."
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "error": "rate_limit_exceeded",
+            "limit_type": self.limit_type,
+            "current": self.current,
+            "maximum": self.maximum,
+            "retry_after_seconds": self.retry_after_seconds,
+        }
+
+
+class GovernanceManager:
+    """Gerencia rate limits, logging e confirmações."""
+
+    def __init__(self, db: Optional[Database] = None):
+        self.db = db or Database()
+        self.db.init()
+
+    # ── Rate Limiting ─────────────────────────────────────────────────────────
+
+    def check_rate_limit(self, action: str, account_id: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Verifica rate limits antes de uma ação.
+        Retorna dict com remaining e warnings.
+        Raises RateLimitExceeded se o limite foi atingido.
+        """
+        requests_used = self.db.count_requests_last_hour()
+        publishes_used = self.db.count_publishes_today()
+
+        result = {
+            "requests": {
+                "used": requests_used,
+                "limit": RATE_LIMIT_REQUESTS_PER_HOUR,
+                "remaining": RATE_LIMIT_REQUESTS_PER_HOUR - requests_used,
+            },
+            "publishes": {
+                "used": publishes_used,
+                "limit": RATE_LIMIT_PUBLISHES_PER_DAY,
+                "remaining": RATE_LIMIT_PUBLISHES_PER_DAY - publishes_used,
+            },
+            "warnings": [],
+        }
+
+        # Verificar limite de requests
+        if requests_used >= RATE_LIMIT_REQUESTS_PER_HOUR:
+            raise RateLimitExceeded(
+                "requests_per_hour", requests_used,
+                RATE_LIMIT_REQUESTS_PER_HOUR, 3600,
+            )
+
+        # Verificar limite de publicações
+        if action.startswith("publish_") and publishes_used >= RATE_LIMIT_PUBLISHES_PER_DAY:
+            raise RateLimitExceeded(
+                "publishes_per_day", publishes_used,
+                RATE_LIMIT_PUBLISHES_PER_DAY, 86400,
+            )
+
+        # Verificar limite de hashtags
+        if action == "search_hashtag" and account_id:
+            hashtag_count = self.db.count_hashtag_searches_last_week(account_id)
+            result["hashtags"] = {
+                "used": hashtag_count,
+                "limit": RATE_LIMIT_HASHTAGS_PER_WEEK,
+                "remaining": RATE_LIMIT_HASHTAGS_PER_WEEK - hashtag_count,
+            }
+            if hashtag_count >= RATE_LIMIT_HASHTAGS_PER_WEEK:
+                raise RateLimitExceeded(
+                    "hashtags_per_week", hashtag_count,
+                    RATE_LIMIT_HASHTAGS_PER_WEEK, 604800,
+                )
+
+        # Warnings em 90% do limite
+        if requests_used >= RATE_LIMIT_REQUESTS_PER_HOUR * RATE_LIMIT_WARNING_THRESHOLD:
+            result["warnings"].append(
+                f"Atenção: {requests_used}/{RATE_LIMIT_REQUESTS_PER_HOUR} requests na última hora"
+            )
+        if publishes_used >= RATE_LIMIT_PUBLISHES_PER_DAY * RATE_LIMIT_WARNING_THRESHOLD:
+            result["warnings"].append(
+                f"Atenção: {publishes_used}/{RATE_LIMIT_PUBLISHES_PER_DAY} publicações hoje"
+            )
+
+        return result
+
+    def get_rate_status(self) -> Dict[str, Any]:
+        """Retorna status atual de todos os rate limits."""
+        return {
+            "requests_per_hour": {
+                "used": self.db.count_requests_last_hour(),
+                "limit": RATE_LIMIT_REQUESTS_PER_HOUR,
+            },
+            "publishes_per_day": {
+                "used": self.db.count_publishes_today(),
+                "limit": RATE_LIMIT_PUBLISHES_PER_DAY,
+            },
+        }
+
+    # ── Action Logging ────────────────────────────────────────────────────────
+
+    def log_action(
+        self,
+        action: str,
+        params: Optional[Dict] = None,
+        result: Optional[Dict] = None,
+        confirmed: bool = True,
+        account_id: Optional[int] = None,
+    ) -> None:
+        """Registra uma ação no audit log."""
+        rate_status = self.get_rate_status()
+        self.db.log_action({
+            "account_id": account_id,
+            "action": action,
+            "params": json.dumps(params, ensure_ascii=False) if params else None,
+            "result": json.dumps(result, ensure_ascii=False) if result else None,
+            "confirmed": 1 if confirmed else 0,
+            "rate_remaining": json.dumps(rate_status),
+        })
+
+    # ── Confirmation ──────────────────────────────────────────────────────────
+
+    def requires_confirmation(self, action: str) -> bool:
+        """Verifica se uma ação requer confirmação do usuário."""
+        for category in ("ENGAGE", "PUBLISH", "DELETE", "MESSAGE"):
+            if action in ACTION_CATEGORIES.get(category, []):
+                return True
+        return False
+
+    def get_confirmation_category(self, action: str) -> str:
+        """Retorna a categoria de confirmação de uma ação."""
+        for category, actions in ACTION_CATEGORIES.items():
+            if action in actions:
+                return category
+        return "READ"
+
+    def create_confirmation_request(
+        self,
+        action: str,
+        details: Dict[str, Any],
+        account_id: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """
+        Cria um pedido de confirmação para o Claude apresentar ao usuário.
+        Retorna JSON estruturado com action_id para confirmar depois.
+        """
+        action_id = str(uuid.uuid4())[:8]
+        rate_status = self.get_rate_status()
+
+        return {
+            "requires_confirmation": True,
+            "action_id": action_id,
+            "action": action,
+            "category": self.get_confirmation_category(action),
+            "details": details,
+            "rate_limits": rate_status,
+            "message": self._format_confirmation_message(action, details, rate_status),
+        }
+
+    def _format_confirmation_message(
+        self, action: str, details: Dict[str, Any], rate_status: Dict[str, Any],
+    ) -> str:
+        """Formata mensagem de confirmação legível."""
+        category = self.get_confirmation_category(action)
+        action_names = {
+            "publish_photo": "PUBLICAR uma foto",
+            "publish_video": "PUBLICAR um vídeo",
+            "publish_reel": "PUBLICAR um reel",
+            "publish_story": "PUBLICAR um story",
+            "publish_carousel": "PUBLICAR um carrossel",
+            "schedule_post": "AGENDAR uma publicação",
+            "reply_comment": "RESPONDER a um comentário",
+            "delete_comment": "DELETAR um comentário",
+            "hide_comment": "OCULTAR um comentário",
+            "send_dm": "ENVIAR uma mensagem direta",
+        }
+        action_desc = action_names.get(action, action)
+
+        lines = [f"[CONFIRMAÇÃO] Prestes a {action_desc}:"]
+        for key, value in details.items():
+            if value is not None:
+                lines.append(f"  {key}: {value}")
+
+        req = rate_status["requests_per_hour"]
+        pub = rate_status["publishes_per_day"]
+        lines.append(f"\n  Rate limits: {req['used']}/{req['limit']} requests/hr, "
+                      f"{pub['used']}/{pub['limit']} publicações/dia")
+
+        return "\n".join(lines)
+
+
+# ── CLI para verificação ─────────────────────────────────────────────────────
+if __name__ == "__main__":
+    gov = GovernanceManager()
+    status = gov.get_rate_status()
+    print(json.dumps(status, indent=2))
+    print("\nÚltimas ações:")
+    for a in gov.db.get_recent_actions(10):
+        print(f"  [{a['created_at']}] {a['action']}")

package/templates/vault/instagram/scripts/hashtags.py

@@ -0,0 +1,114 @@
+"""
+Pesquisa e tracking de hashtags do Instagram.
+
+Uso:
+    python scripts/hashtags.py --search "artificialintelligence" --limit 25
+    python scripts/hashtags.py --top "tecnologia"
+    python scripts/hashtags.py --info "marketing"
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from api_client import InstagramAPI
+from auth import auto_refresh_if_needed
+from db import Database
+from governance import GovernanceManager, RateLimitExceeded
+
+db = Database()
+db.init()
+gov = GovernanceManager(db)
+
+
+async def search_hashtag(hashtag: str, limit: int = 25, mode: str = "recent") -> None:
+    """Busca posts com uma hashtag."""
+    await auto_refresh_if_needed()
+
+    account = db.get_active_account()
+    if not account:
+        print(json.dumps({"error": "Nenhuma conta configurada"}, indent=2))
+        return
+
+    # Verificar rate limit de hashtags
+    try:
+        gov.check_rate_limit("search_hashtag", account["id"])
+    except RateLimitExceeded as e:
+        print(json.dumps(e.to_dict(), indent=2))
+        return
+
+    api = InstagramAPI()
+
+    # Step 1: Buscar ID da hashtag
+    search_result = await api.search_hashtag(hashtag)
+    hashtag_data = search_result.get("data", [])
+    if not hashtag_data:
+        print(json.dumps({"error": f"Hashtag '{hashtag}' não encontrada"}, indent=2))
+        await api.close()
+        return
+
+    hashtag_id = hashtag_data[0]["id"]
+
+    # Registrar busca
+    db.insert_hashtag_search({
+        "account_id": account["id"],
+        "hashtag": hashtag,
+        "ig_hashtag_id": hashtag_id,
+    })
+
+    # Step 2: Buscar posts
+    if mode == "top":
+        result = await api.get_hashtag_top_media(hashtag_id, limit=limit)
+    else:
+        result = await api.get_hashtag_recent_media(hashtag_id, limit=limit)
+
+    await api.close()
+
+    # Contagem de buscas na semana
+    weekly_count = db.count_hashtag_searches_last_week(account["id"])
+
+    output = {
+        "hashtag": hashtag,
+        "hashtag_id": hashtag_id,
+        "mode": mode,
+        "results": result.get("data", []),
+        "total": len(result.get("data", [])),
+        "hashtag_searches_this_week": weekly_count,
+        "hashtag_searches_limit": 30,
+    }
+    print(json.dumps(output, indent=2, ensure_ascii=False))
+
+
+async def hashtag_info(hashtag: str) -> None:
+    """Info de uma hashtag (apenas o ID — media_count requer permissões especiais)."""
+    await auto_refresh_if_needed()
+    api = InstagramAPI()
+    result = await api.search_hashtag(hashtag)
+    await api.close()
+    print(json.dumps({"hashtag": hashtag, "data": result.get("data", [])}, indent=2, ensure_ascii=False))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Hashtags do Instagram")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--search", metavar="TAG", help="Buscar posts recentes com hashtag")
+    group.add_argument("--top", metavar="TAG", help="Top posts de uma hashtag")
+    group.add_argument("--info", metavar="TAG", help="Info da hashtag")
+    parser.add_argument("--limit", type=int, default=25, help="Limite de resultados")
+    args = parser.parse_args()
+
+    if args.search:
+        asyncio.run(search_hashtag(args.search, args.limit, mode="recent"))
+    elif args.top:
+        asyncio.run(search_hashtag(args.top, args.limit, mode="top"))
+    elif args.info:
+        asyncio.run(hashtag_info(args.info))
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/instagram/scripts/insights.py

@@ -0,0 +1,170 @@
+"""
+Analytics e insights do Instagram.
+
+Uso:
+    python scripts/insights.py --media --media-id 12345
+    python scripts/insights.py --user --period day --since 7
+    python scripts/insights.py --fetch-all --limit 20
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from api_client import InstagramAPI
+from auth import auto_refresh_if_needed
+from db import Database
+
+db = Database()
+db.init()
+
+
+async def media_insights(media_id: str, metrics: list = None) -> None:
+    """Busca insights de um post específico."""
+    await auto_refresh_if_needed()
+    api = InstagramAPI()
+    try:
+        result = await api.get_media_insights(media_id, metrics=metrics)
+    except Exception as e:
+        print(json.dumps({"error": str(e), "media_id": media_id}, indent=2))
+        await api.close()
+        return
+
+    # Salvar no banco
+    account = db.get_active_account()
+    if account:
+        raw = json.dumps(result, ensure_ascii=False)
+        for item in result.get("data", []):
+            values = item.get("values", [{}])
+            value = values[0].get("value", 0) if values else 0
+            db.insert_insights([{
+                "account_id": account["id"],
+                "ig_media_id": media_id,
+                "metric_name": item.get("name", ""),
+                "metric_value": float(value) if isinstance(value, (int, float)) else 0,
+                "period": item.get("period", ""),
+                "raw_json": raw,
+            }])
+
+    await api.close()
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+async def user_insights(period: str = "day", since_days: int = 7, metrics: list = None) -> None:
+    """Busca insights da conta."""
+    await auto_refresh_if_needed()
+    api = InstagramAPI()
+
+    now = datetime.now(timezone.utc)
+    since = (now - timedelta(days=since_days)).strftime("%Y-%m-%d")
+    until = now.strftime("%Y-%m-%d")
+
+    result = await api.get_user_insights(
+        period=period,
+        metrics=metrics,
+        since=since,
+        until=until,
+    )
+
+    # Salvar no banco
+    account = db.get_active_account()
+    if account:
+        for item in result.get("data", []):
+            for value_entry in item.get("values", []):
+                db.insert_user_insights([{
+                    "account_id": account["id"],
+                    "metric_name": item.get("name", ""),
+                    "metric_value": float(value_entry.get("value", 0)),
+                    "period": period,
+                    "end_time": value_entry.get("end_time", ""),
+                }])
+
+    await api.close()
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+async def fetch_all_insights(limit: int = 20) -> None:
+    """Busca insights de todos os posts recentes."""
+    await auto_refresh_if_needed()
+    api = InstagramAPI()
+
+    media_result = await api.get_user_media(limit=limit)
+    media_list = media_result.get("data", [])
+
+    results = []
+    for media in media_list:
+        media_id = media["id"]
+        media_type = media.get("media_type", "IMAGE")
+        try:
+            # Métricas variam por tipo
+            metrics = ["impressions", "reach", "engagement", "saved"]
+            if media_type == "VIDEO":
+                metrics.append("video_views")
+            if media_type == "REELS" or "reel" in media.get("permalink", "").lower():
+                metrics = ["impressions", "reach", "likes", "comments", "saves", "shares", "plays"]
+
+            insights = await api.get_media_insights(media_id, metrics=metrics)
+
+            # Salvar
+            account = db.get_active_account()
+            if account:
+                raw = json.dumps(insights, ensure_ascii=False)
+                for item in insights.get("data", []):
+                    values = item.get("values", [{}])
+                    value = values[0].get("value", 0) if values else 0
+                    db.insert_insights([{
+                        "account_id": account["id"],
+                        "ig_media_id": media_id,
+                        "metric_name": item.get("name", ""),
+                        "metric_value": float(value) if isinstance(value, (int, float)) else 0,
+                        "period": item.get("period", ""),
+                        "raw_json": raw,
+                    }])
+
+            results.append({
+                "media_id": media_id,
+                "type": media_type,
+                "caption": (media.get("caption", "") or "")[:50],
+                "metrics": {
+                    d["name"]: d["values"][0]["value"] if d.get("values") else 0
+                    for d in insights.get("data", [])
+                },
+            })
+        except Exception as e:
+            results.append({"media_id": media_id, "error": str(e)})
+
+    await api.close()
+    print(json.dumps({"fetched": len(results), "insights": results}, indent=2, ensure_ascii=False))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Insights do Instagram")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--media", action="store_true", help="Insights de um post")
+    group.add_argument("--user", action="store_true", help="Insights da conta")
+    group.add_argument("--fetch-all", action="store_true", help="Buscar insights de todos os posts recentes")
+    parser.add_argument("--media-id", help="ID da mídia")
+    parser.add_argument("--period", default="day", choices=["day", "week", "days_28", "month", "lifetime"])
+    parser.add_argument("--since", type=int, default=7, help="Dias atrás (default: 7)")
+    parser.add_argument("--metrics", nargs="+", help="Métricas específicas")
+    parser.add_argument("--limit", type=int, default=20, help="Limite de posts para --fetch-all")
+    args = parser.parse_args()
+
+    if args.media:
+        if not args.media_id:
+            parser.error("--media-id é obrigatório com --media")
+        asyncio.run(media_insights(args.media_id, args.metrics))
+    elif args.user:
+        asyncio.run(user_insights(args.period, args.since, args.metrics))
+    elif args.fetch_all:
+        asyncio.run(fetch_all_insights(args.limit))
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/instagram/scripts/media.py

@@ -0,0 +1,65 @@
+"""
+Listagem e detalhes de mídia do Instagram.
+
+Uso:
+    python scripts/media.py --list [--limit 10]
+    python scripts/media.py --details --media-id 12345
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from api_client import InstagramAPI
+from auth import auto_refresh_if_needed
+
+
+async def list_media(limit: int = 25, after: str = None) -> None:
+    """Lista mídia do usuário."""
+    await auto_refresh_if_needed()
+    api = InstagramAPI()
+    result = await api.get_user_media(limit=limit, after=after)
+    await api.close()
+
+    data = result.get("data", [])
+    print(json.dumps({
+        "total": len(data),
+        "media": data,
+        "paging": result.get("paging", {}),
+    }, indent=2, ensure_ascii=False))
+
+
+async def media_details(media_id: str) -> None:
+    """Detalhes de uma mídia específica."""
+    await auto_refresh_if_needed()
+    api = InstagramAPI()
+    result = await api.get_media_details(media_id)
+    await api.close()
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Mídia do Instagram")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--list", action="store_true", help="Listar mídia")
+    group.add_argument("--details", action="store_true", help="Detalhes de uma mídia")
+    parser.add_argument("--limit", type=int, default=25, help="Limite de resultados")
+    parser.add_argument("--media-id", help="ID da mídia")
+    parser.add_argument("--after", help="Cursor de paginação")
+    args = parser.parse_args()
+
+    if args.list:
+        asyncio.run(list_media(args.limit, args.after))
+    elif args.details:
+        if not args.media_id:
+            parser.error("--media-id é obrigatório com --details")
+        asyncio.run(media_details(args.media_id))
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/instagram/scripts/messages.py

@@ -0,0 +1,103 @@
+"""
+Mensagens diretas do Instagram (DMs).
+
+Uso:
+    python scripts/messages.py --send --user-id 12345 --text "Olá!"
+    python scripts/messages.py --conversations
+    python scripts/messages.py --thread --conversation-id 12345
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from api_client import InstagramAPI
+from auth import auto_refresh_if_needed
+from db import Database
+from governance import GovernanceManager
+
+db = Database()
+db.init()
+gov = GovernanceManager(db)
+
+
+async def send_message(user_id: str, text: str) -> None:
+    """Envia DM para um usuário."""
+    await auto_refresh_if_needed()
+
+    if gov.requires_confirmation("send_dm"):
+        result = gov.create_confirmation_request(
+            "send_dm",
+            {"recipient_id": user_id, "text": text},
+        )
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return
+
+    api = InstagramAPI()
+    result = await api.send_message(user_id, text)
+    await api.close()
+
+    account = db.get_active_account()
+    gov.log_action(
+        "send_dm",
+        params={"recipient_id": user_id, "text": text},
+        result=result,
+        account_id=account["id"] if account else None,
+    )
+
+    print(json.dumps({"status": "sent", "result": result}, indent=2, ensure_ascii=False))
+
+
+async def list_conversations(limit: int = 20) -> None:
+    """Lista conversas recentes."""
+    await auto_refresh_if_needed()
+    api = InstagramAPI()
+    result = await api.get_conversations(limit=limit)
+    await api.close()
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+async def show_thread(conversation_id: str) -> None:
+    """Mostra mensagens de uma conversa."""
+    await auto_refresh_if_needed()
+    api = InstagramAPI()
+    result = await api.get(
+        f"{conversation_id}/messages",
+        params={"fields": "id,message,from,created_time"},
+        action="get_thread",
+    )
+    await api.close()
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="DMs do Instagram")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--send", action="store_true", help="Enviar DM")
+    group.add_argument("--conversations", action="store_true", help="Listar conversas")
+    group.add_argument("--thread", action="store_true", help="Ver mensagens de uma conversa")
+    parser.add_argument("--user-id", help="ID do destinatário")
+    parser.add_argument("--text", help="Texto da mensagem")
+    parser.add_argument("--conversation-id", help="ID da conversa")
+    parser.add_argument("--limit", type=int, default=20, help="Limite")
+    args = parser.parse_args()
+
+    if args.send:
+        if not args.user_id or not args.text:
+            parser.error("--user-id e --text são obrigatórios com --send")
+        asyncio.run(send_message(args.user_id, args.text))
+    elif args.conversations:
+        asyncio.run(list_conversations(args.limit))
+    elif args.thread:
+        if not args.conversation_id:
+            parser.error("--conversation-id é obrigatório com --thread")
+        asyncio.run(show_thread(args.conversation_id))
+
+
+if __name__ == "__main__":
+    main()