bps-kit 1.0.1 → 1.0.2

package/templates/vault/whatsapp-cloud-api/assets/boilerplate/nodejs/src/whatsapp-client.ts

@@ -0,0 +1,193 @@
+import axios, { AxiosInstance } from 'axios';
+import { WhatsAppConfig, SendMessagePayload, SendMessageResponse } from './types';
+
+export class WhatsAppClient {
+  private client: AxiosInstance;
+  private phoneNumberId: string;
+  private wabaId: string;
+
+  constructor(config: WhatsAppConfig) {
+    const version = config.graphApiVersion || 'v21.0';
+    this.phoneNumberId = config.phoneNumberId;
+    this.wabaId = config.wabaId;
+
+    this.client = axios.create({
+      baseURL: `https://graph.facebook.com/${version}`,
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+        'Content-Type': 'application/json',
+      },
+    });
+  }
+
+  async sendMessage(payload: SendMessagePayload): Promise<SendMessageResponse> {
+    return this.sendWithRetry(payload);
+  }
+
+  async sendText(to: string, body: string, previewUrl = false): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'text',
+      text: { body, preview_url: previewUrl },
+    });
+  }
+
+  async sendTemplate(
+    to: string,
+    templateName: string,
+    languageCode: string,
+    components?: SendMessagePayload['template']
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'template',
+      template: {
+        name: templateName,
+        language: { code: languageCode },
+        ...components,
+      },
+    });
+  }
+
+  async sendImage(to: string, imageUrl: string, caption?: string): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'image',
+      image: { link: imageUrl, caption },
+    });
+  }
+
+  async sendDocument(
+    to: string,
+    documentUrl: string,
+    filename: string,
+    caption?: string
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'document',
+      document: { link: documentUrl, filename, caption },
+    });
+  }
+
+  async sendInteractiveButtons(
+    to: string,
+    bodyText: string,
+    buttons: Array<{ id: string; title: string }>,
+    headerText?: string,
+    footerText?: string
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'interactive',
+      interactive: {
+        type: 'button',
+        ...(headerText && { header: { type: 'text', text: headerText } }),
+        body: { text: bodyText },
+        ...(footerText && { footer: { text: footerText } }),
+        action: {
+          buttons: buttons.map((b) => ({
+            type: 'reply' as const,
+            reply: { id: b.id, title: b.title },
+          })),
+        },
+      },
+    });
+  }
+
+  async sendInteractiveList(
+    to: string,
+    bodyText: string,
+    buttonText: string,
+    sections: Array<{
+      title: string;
+      rows: Array<{ id: string; title: string; description?: string }>;
+    }>,
+    headerText?: string,
+    footerText?: string
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'interactive',
+      interactive: {
+        type: 'list',
+        ...(headerText && { header: { type: 'text', text: headerText } }),
+        body: { text: bodyText },
+        ...(footerText && { footer: { text: footerText } }),
+        action: { button: buttonText, sections },
+      },
+    });
+  }
+
+  async sendReaction(to: string, messageId: string, emoji: string): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'reaction',
+      reaction: { message_id: messageId, emoji },
+    });
+  }
+
+  async sendLocation(
+    to: string,
+    latitude: number,
+    longitude: number,
+    name?: string,
+    address?: string
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'location',
+      location: { latitude, longitude, name, address },
+    });
+  }
+
+  async markAsRead(messageId: string): Promise<void> {
+    await this.client.post(`/${this.phoneNumberId}/messages`, {
+      messaging_product: 'whatsapp',
+      status: 'read',
+      message_id: messageId,
+    });
+  }
+
+  private async sendWithRetry(
+    payload: SendMessagePayload,
+    maxRetries = 3
+  ): Promise<SendMessageResponse> {
+    const nonRetryableCodes = [100, 131026, 131051, 132000, 132001, 132005, 133010];
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        const response = await this.client.post<SendMessageResponse>(
+          `/${this.phoneNumberId}/messages`,
+          payload
+        );
+        return response.data;
+      } catch (error: any) {
+        const errorCode = error.response?.data?.error?.code;
+        const errorMessage = error.response?.data?.error?.message || error.message;
+
+        if (nonRetryableCodes.includes(errorCode)) {
+          throw new Error(`WhatsApp API Error ${errorCode}: ${errorMessage}`);
+        }
+
+        if (attempt < maxRetries) {
+          const delay = Math.pow(2, attempt) * 1000;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+
+        throw new Error(`WhatsApp API Error after ${maxRetries} retries: ${errorMessage}`);
+      }
+    }
+
+    throw new Error('Unexpected: retry loop exited without return or throw');
+  }
+}

package/templates/vault/whatsapp-cloud-api/scripts/send_test_message.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Send a test message via WhatsApp Cloud API.
+
+Quick way to validate your setup by sending a text message.
+
+Usage:
+    python send_test_message.py --to 5511999999999 --message "Hello from WhatsApp API!"
+    python send_test_message.py --to 5511999999999  # Uses default test message
+"""
+
+import argparse
+import json
+import os
+import sys
+
+try:
+    import httpx
+except ImportError:
+    print("Error: httpx not installed. Run: pip install httpx")
+    sys.exit(1)
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    load_dotenv = None
+
+GRAPH_API = "https://graph.facebook.com/v21.0"
+
+
+def _mask_secret(value: str) -> str:
+    """Return a masked version of a secret for safe logging."""
+    if not value or len(value) < 8:
+        return "***masked***"
+    return f"{value[:6]}...masked"
+
+
+def send_test(to: str, message: str) -> None:
+    """Send a test text message."""
+    token = os.environ.get("WHATSAPP_TOKEN")
+    phone_id = os.environ.get("PHONE_NUMBER_ID")
+
+    if not token or not phone_id:
+        print("Error: WHATSAPP_TOKEN and PHONE_NUMBER_ID must be set.")
+        print("Configure your .env file or set environment variables.")
+        sys.exit(1)
+
+    payload = {
+        "messaging_product": "whatsapp",
+        "to": to,
+        "type": "text",
+        "text": {"body": message},
+    }
+
+    print(f"Sending message to: {to}")
+    print(f"Message: {message}")
+    print()
+
+    try:
+        response = httpx.post(
+            f"{GRAPH_API}/{phone_id}/messages",
+            json=payload,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+        )
+
+        data = response.json()
+
+        if response.status_code == 200:
+            msg_id = data.get("messages", [{}])[0].get("id", "N/A")
+            print("Message sent successfully!")
+            print(f"  Message ID: {msg_id}")
+            print(f"  Status: 200 OK")
+        else:
+            error = data.get("error", {})
+            print(f"Error sending message:")
+            print(f"  Code: {error.get('code', '?')}")
+            print(f"  Message: {error.get('message', 'Unknown error')}")
+            if error.get("error_data"):
+                print(f"  Details: {error['error_data'].get('details', '')}")
+
+        print()
+        print("Full response:")
+        # Mask token in response output to prevent credential leakage
+        response_str = json.dumps(data, indent=2)
+        if token and token in response_str:
+            response_str = response_str.replace(token, _mask_secret(token))
+        print(response_str)
+
+    except httpx.ConnectError:
+        print("Error: Connection failed. Check your internet connection.")
+        sys.exit(1)
+    except httpx.TimeoutException:
+        print("Error: Request timed out.")
+        sys.exit(1)
+    except Exception as e:
+        # Mask token in error output to prevent credential leakage
+        safe_err = str(e).replace(token, _mask_secret(token)) if token else str(e)
+        print(f"Error: {safe_err}")
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Send a test WhatsApp message")
+    parser.add_argument(
+        "--to",
+        required=True,
+        help="Recipient phone number with country code (e.g., 5511999999999)",
+    )
+    parser.add_argument(
+        "--message",
+        default="Teste de integracao WhatsApp Cloud API - Mensagem enviada com sucesso!",
+        help="Message text to send",
+    )
+    parser.add_argument(
+        "--env-file",
+        default=".env",
+        help="Path to .env file (default: .env)",
+    )
+
+    args = parser.parse_args()
+
+    # Load environment
+    if load_dotenv:
+        for env_path in [args.env_file, os.path.join(os.getcwd(), ".env")]:
+            if os.path.exists(env_path):
+                load_dotenv(env_path)
+                break
+
+    send_test(args.to, args.message)
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/whatsapp-cloud-api/scripts/setup_project.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+Setup a new WhatsApp Cloud API project with boilerplate code.
+
+Usage:
+    python setup_project.py --language nodejs --path ./my-whatsapp-project
+    python setup_project.py --language python --path ./my-whatsapp-project
+"""
+
+import argparse
+import os
+import shutil
+import sys
+
+
+def get_skill_dir() -> str:
+    """Get the skill directory (parent of scripts/)."""
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def setup_project(language: str, path: str, name: str | None = None) -> None:
+    """Copy boilerplate and configure a new WhatsApp project."""
+    skill_dir = get_skill_dir()
+    boilerplate_dir = os.path.join(skill_dir, "assets", "boilerplate", language)
+
+    if not os.path.exists(boilerplate_dir):
+        print(f"Error: Boilerplate not found for language '{language}'")
+        print(f"Available: nodejs, python")
+        sys.exit(1)
+
+    target_path = os.path.abspath(path)
+
+    if os.path.exists(target_path) and os.listdir(target_path):
+        print(f"Warning: Directory '{target_path}' already exists and is not empty.")
+        response = input("Continue and overwrite? (y/N): ").strip().lower()
+        if response != "y":
+            print("Aborted.")
+            sys.exit(0)
+
+    # Copy boilerplate
+    print(f"Creating {language} project at: {target_path}")
+    shutil.copytree(boilerplate_dir, target_path, dirs_exist_ok=True)
+
+    # Rename .env.example to .env
+    env_example = os.path.join(target_path, ".env.example")
+    env_file = os.path.join(target_path, ".env")
+    if os.path.exists(env_example) and not os.path.exists(env_file):
+        shutil.copy2(env_example, env_file)
+        print("Created .env from .env.example")
+
+    # Update project name if provided
+    if name and language == "nodejs":
+        package_json = os.path.join(target_path, "package.json")
+        if os.path.exists(package_json):
+            with open(package_json, "r") as f:
+                content = f.read()
+            content = content.replace('"whatsapp-cloud-api"', f'"{name}"')
+            with open(package_json, "w") as f:
+                f.write(content)
+
+    print()
+    print("=" * 50)
+    print("Project created successfully!")
+    print("=" * 50)
+    print()
+    print("Next steps:")
+    print()
+
+    if language == "nodejs":
+        print(f"  1. cd {target_path}")
+        print("  2. npm install")
+        print("  3. Edit .env with your WhatsApp API credentials")
+        print("  4. npm run dev")
+        print()
+        print("For production:")
+        print("  npm run build && npm start")
+    else:
+        print(f"  1. cd {target_path}")
+        print("  2. pip install -r requirements.txt")
+        print("  3. Edit .env with your WhatsApp API credentials")
+        print("  4. python app.py")
+        print()
+        print("For production:")
+        print("  gunicorn -w 4 -b 0.0.0.0:3000 app:app")
+
+    print()
+    print("For local development with webhooks:")
+    print("  ngrok http 3000")
+    print("  Then configure the ngrok URL in Meta Developers > WhatsApp > Configuration")
+    print()
+    print("Need help with setup? Read: references/setup-guide.md")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Setup a new WhatsApp Cloud API project")
+    parser.add_argument(
+        "--language",
+        choices=["nodejs", "python"],
+        required=True,
+        help="Project language (nodejs or python)",
+    )
+    parser.add_argument(
+        "--path",
+        required=True,
+        help="Path where the project will be created",
+    )
+    parser.add_argument(
+        "--name",
+        default=None,
+        help="Project name (optional, used in package.json for nodejs)",
+    )
+
+    args = parser.parse_args()
+    setup_project(args.language, args.path, args.name)
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/whatsapp-cloud-api/scripts/validate_config.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Validate WhatsApp Cloud API configuration.
+
+Checks environment variables and tests API connectivity.
+
+Usage:
+    python validate_config.py
+    python validate_config.py --env-file /path/to/.env
+"""
+
+import argparse
+import os
+import sys
+
+try:
+    import httpx
+except ImportError:
+    print("Error: httpx not installed. Run: pip install httpx")
+    sys.exit(1)
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    print("Warning: python-dotenv not installed. Using system environment only.")
+    load_dotenv = None
+
+GRAPH_API = "https://graph.facebook.com/v21.0"
+
+REQUIRED_VARS = [
+    ("WHATSAPP_TOKEN", "Access token for WhatsApp Cloud API"),
+    ("PHONE_NUMBER_ID", "Phone Number ID from API Setup"),
+    ("WABA_ID", "WhatsApp Business Account ID"),
+    ("APP_SECRET", "App Secret from App Settings > Basic"),
+    ("VERIFY_TOKEN", "Custom token for webhook verification"),
+]
+
+
+def check_env_vars() -> tuple[bool, list[str]]:
+    """Check if all required environment variables are set."""
+    missing = []
+    for var_name, description in REQUIRED_VARS:
+        value = os.environ.get(var_name)
+        if not value or value.startswith("your_"):
+            missing.append(f"  {var_name} - {description}")
+
+    return len(missing) == 0, missing
+
+
+def _mask_secret(value: str) -> str:
+    """Return a masked version of a secret for safe logging."""
+    if not value or len(value) < 8:
+        return "***masked***"
+    return f"{value[:6]}...masked"
+
+
+def test_api_connection() -> tuple[bool, str]:
+    """Test connection to WhatsApp Cloud API."""
+    token = os.environ.get("WHATSAPP_TOKEN", "")
+    phone_id = os.environ.get("PHONE_NUMBER_ID", "")
+
+    try:
+        response = httpx.get(
+            f"{GRAPH_API}/{phone_id}",
+            params={"fields": "verified_name,code_verification_status,display_phone_number,quality_rating"},
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10.0,
+        )
+
+        if response.status_code == 200:
+            data = response.json()
+            return True, (
+                f"Phone: {data.get('display_phone_number', 'N/A')}\n"
+                f"  Name: {data.get('verified_name', 'N/A')}\n"
+                f"  Status: {data.get('code_verification_status', 'N/A')}\n"
+                f"  Quality: {data.get('quality_rating', 'N/A')}"
+            )
+        else:
+            error = response.json().get("error", {})
+            return False, f"API Error {error.get('code', '?')}: {error.get('message', 'Unknown')}"
+
+    except httpx.ConnectError:
+        return False, "Connection failed. Check your internet connection."
+    except httpx.TimeoutException:
+        return False, "Request timed out after 10 seconds."
+    except Exception as e:
+        # Mask token in error output to prevent credential leakage
+        safe_err = str(e).replace(token, _mask_secret(token)) if token else str(e)
+        return False, f"Unexpected error: {safe_err}"
+
+
+def test_waba_access() -> tuple[bool, str]:
+    """Test access to WhatsApp Business Account."""
+    token = os.environ.get("WHATSAPP_TOKEN", "")
+    waba_id = os.environ.get("WABA_ID", "")
+
+    try:
+        response = httpx.get(
+            f"{GRAPH_API}/{waba_id}/phone_numbers",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10.0,
+        )
+
+        if response.status_code == 200:
+            data = response.json()
+            count = len(data.get("data", []))
+            return True, f"WABA accessible. {count} phone number(s) found."
+        else:
+            error = response.json().get("error", {})
+            return False, f"API Error {error.get('code', '?')}: {error.get('message', 'Unknown')}"
+
+    except Exception as e:
+        # Mask token in error output to prevent credential leakage
+        safe_err = str(e).replace(token, _mask_secret(token)) if token else str(e)
+        return False, f"Error: {safe_err}"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate WhatsApp Cloud API configuration")
+    parser.add_argument("--env-file", default=".env", help="Path to .env file (default: .env)")
+    args = parser.parse_args()
+
+    # Load environment
+    if load_dotenv and os.path.exists(args.env_file):
+        load_dotenv(args.env_file)
+        print(f"Loaded: {args.env_file}")
+    elif not os.path.exists(args.env_file):
+        print(f"Warning: {args.env_file} not found. Using system environment.")
+
+    print()
+    print("=" * 50)
+    print("WhatsApp Cloud API - Configuration Validator")
+    print("=" * 50)
+    print()
+
+    all_ok = True
+
+    # Check 1: Environment variables
+    print("[1/3] Checking environment variables...")
+    env_ok, missing = check_env_vars()
+    if env_ok:
+        print("  OK - All required variables are set")
+    else:
+        print("  FAIL - Missing variables:")
+        for m in missing:
+            print(f"    {m}")
+        all_ok = False
+
+    print()
+
+    if not env_ok:
+        print("Cannot test API without required variables. Fix the above and retry.")
+        sys.exit(1)
+
+    # Check 2: API connection
+    print("[2/3] Testing API connection (Phone Number)...")
+    api_ok, api_msg = test_api_connection()
+    if api_ok:
+        print(f"  OK - Connected successfully")
+        print(f"  {api_msg}")
+    else:
+        print(f"  FAIL - {api_msg}")
+        all_ok = False
+
+    print()
+
+    # Check 3: WABA access
+    print("[3/3] Testing WABA access...")
+    waba_ok, waba_msg = test_waba_access()
+    if waba_ok:
+        print(f"  OK - {waba_msg}")
+    else:
+        print(f"  FAIL - {waba_msg}")
+        all_ok = False
+
+    print()
+    print("=" * 50)
+    if all_ok:
+        print("All checks passed! Your configuration is valid.")
+        print("You can start sending messages.")
+    else:
+        print("Some checks failed. Please fix the issues above.")
+        print("Need help? Read: references/setup-guide.md")
+    print("=" * 50)
+
+    sys.exit(0 if all_ok else 1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/youtube-summarizer/scripts/extract-transcript.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Extract YouTube video transcript
+Usage: ./extract-transcript.py VIDEO_ID [LANGUAGE_CODE]
+"""
+
+import sys
+from youtube_transcript_api import YouTubeTranscriptApi, TranscriptsDisabled, NoTranscriptFound
+
+def extract_transcript(video_id, language='en'):
+    """Extract transcript from YouTube video"""
+    try:
+        # Try to get transcript in specified language with fallback to English
+        transcript = YouTubeTranscriptApi.get_transcript(
+            video_id,
+            languages=[language, 'en']
+        )
+        
+        # Combine all transcript segments
+        full_text = " ".join([entry['text'] for entry in transcript])
+        return full_text
+        
+    except TranscriptsDisabled:
+        print(f"❌ Transcripts are disabled for video {video_id}", file=sys.stderr)
+        sys.exit(1)
+    except NoTranscriptFound:
+        print(f"❌ No transcript found for video {video_id}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+def list_available_transcripts(video_id):
+    """List all available transcripts for a video"""
+    try:
+        transcript_list = YouTubeTranscriptApi.list_transcripts(video_id)
+        print(f"✅ Available transcripts for {video_id}:")
+        
+        for transcript in transcript_list:
+            generated = "[Auto-generated]" if transcript.is_generated else "[Manual]"
+            translatable = "(translatable)" if transcript.is_translatable else ""
+            print(f"  - {transcript.language} ({transcript.language_code}) {generated} {translatable}")
+        
+        return True
+    except Exception as e:
+        print(f"❌ Error listing transcripts: {e}", file=sys.stderr)
+        return False
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: ./extract-transcript.py VIDEO_ID [LANGUAGE_CODE]")
+        print("       ./extract-transcript.py VIDEO_ID --list  (list available transcripts)")
+        sys.exit(1)
+    
+    video_id = sys.argv[1]
+    
+    # Check if user wants to list available transcripts
+    if len(sys.argv) > 2 and sys.argv[2] == "--list":
+        success = list_available_transcripts(video_id)
+        sys.exit(0 if success else 1)
+    
+    # Extract transcript
+    language = sys.argv[2] if len(sys.argv) > 2 else 'en'
+    transcript = extract_transcript(video_id, language)
+    print(transcript)