Battle Card API: Generate and Maintain Competitive Battle Cards at Scale

curl -s -H "Authorization: Bearer $RIVALCHECK_API_KEY" \
  "https://app.rivalcheck.com/api/v1/competitors/42/battle_card?format=structured"

{
  "status": "generating",
  "message": "Battle card generation started. Check back in 30-60 seconds.",
  "competitor_id": 42,
  "estimated_completion": "2026-03-24T15:01:00Z"
}

# Slack slash command handler (Python + Flask)
from flask import Flask, request, jsonify
import requests

app = Flask(__name__)
RIVALCHECK_API = "https://app.rivalcheck.com/api/v1"
API_KEY = os.environ["RIVALCHECK_API_KEY"]

@app.route("/slack/battlecard", methods=["POST"])
def battlecard_command():
    competitor_name = request.form.get("text", "").strip()

    # Find the competitor by name
    resp = requests.get(
        f"{RIVALCHECK_API}/competitors",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    competitors = resp.json()["competitors"]
    match = next(
        (c for c in competitors
         if competitor_name.lower() in c["name"].lower()),
        None
    )

    if not match:
        return jsonify({
            "response_type": "ephemeral",
            "text": f"No competitor found matching '{competitor_name}'."
        })

    # Fetch the battle card in markdown format
    card_resp = requests.get(
        f"{RIVALCHECK_API}/competitors/{match['id']}/battle_card?format=markdown",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    card = card_resp.json()["battle_card"]

    # Format for Slack
    sections = card["sections"]
    blocks = [
        {
            "type": "header",
            "text": {"type": "plain_text",
                     "text": f"Battle Card: {match['name']}"}
        },
        {
            "type": "section",
            "text": {"type": "mrkdwn",
                     "text": f"*Overview:* {sections['overview']}"}
        },
        {"type": "divider"},
        {
            "type": "section",
            "text": {"type": "mrkdwn",
                     "text": "*How We Win:*\n" + "\n".join(
                         f"- {point}" for point in sections["how_we_win"]
                     )}
        },
        {"type": "divider"},
        {
            "type": "section",
            "text": {"type": "mrkdwn",
                     "text": f"*Elevator Pitch:*\n>{sections['elevator_pitch']}"}
        },
        {
            "type": "context",
            "elements": [{
                "type": "mrkdwn",
                "text": f"Generated {card['generated_at'][:10]} "
                        f"| {'Stale' if card['stale'] else 'Current'} "
                        f"| "
            }]
        }
    ]

    return jsonify({
        "response_type": "in_channel",
        "blocks": blocks
    })

# Sync battle cards to Notion database
from notion_client import Client
import requests

notion = Client(auth=os.environ["NOTION_TOKEN"])
DATABASE_ID = "your-database-id"

def sync_to_notion():
    headers = {"Authorization": f"Bearer {API_KEY}"}

    # Get all competitors
    resp = requests.get(f"{RIVALCHECK_API}/competitors", headers=headers)
    competitors = resp.json()["competitors"]

    for comp in competitors:
        if not comp.get("has_battle_card"):
            continue

        # Fetch markdown format
        card_resp = requests.get(
            f"{RIVALCHECK_API}/competitors/{comp['id']}/battle_card"
            f"?format=markdown",
            headers=headers
        )
        card = card_resp.json()["battle_card"]

        # Check if page exists in Notion
        existing = notion.databases.query(
            database_id=DATABASE_ID,
            filter={"property": "Competitor",
                    "title": {"equals": comp["name"]}}
        )

        page_content = [
            {"type": "paragraph", "paragraph": {
                "rich_text": [{"type": "text",
                               "text": {"content": card["content"]}}]
            }}
        ]

        if existing["results"]:
            # Update existing page
            page_id = existing["results"][0]["id"]
            # Clear and rewrite content blocks
            notion.blocks.children.append(page_id, children=page_content)
        else:
            # Create new page
            notion.pages.create(
                parent={"database_id": DATABASE_ID},
                properties={
                    "Competitor": {"title": [{"text": {"content": comp["name"]}}]},
                    "Status": {"select": {"name": "Current" if not card["stale"]
                                          else "Stale"}},
                    "Last Updated": {"date": {"start": card["generated_at"][:10]}}
                },
                children=page_content
            )

# Generate a competitive slide using python-pptx
from pptx import Presentation
from pptx.util import Inches, Pt

def create_competitive_slide(competitor_id):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    card_resp = requests.get(
        f"{RIVALCHECK_API}/competitors/{competitor_id}/battle_card",
        headers=headers
    )
    card = card_resp.json()["battle_card"]["sections"]

    prs = Presentation("template.pptx")
    slide = prs.slides.add_slide(prs.slide_layouts[1])

    slide.shapes.title.text = f"Why Us vs {card_resp.json()['battle_card']['competitor_name']}"

    body = slide.placeholders[1]
    tf = body.text_frame
    tf.clear()

    for point in card["how_we_win"]:
        p = tf.add_paragraph()
        p.text = point
        p.font.size = Pt(14)
        p.level = 0

    prs.save(f"competitive_slide_{competitor_id}.pptx")
    return f"competitive_slide_{competitor_id}.pptx"

@app.route("/webhooks/rivalcheck", methods=["POST"])
def auto_regenerate_battle_card():
    event = request.json

    if event["event"] != "change.detected":
        return "OK", 200

    change = event["data"]

    # Only regenerate for high-severity changes
    if change["severity"] != "high":
        return "OK", 200

    competitor_id = change["competitor"]["id"]

    # Trigger battle card regeneration
    requests.post(
        f"{RIVALCHECK_API}/competitors/{competitor_id}/battle_card/generate",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"force": True}
    )

    # Notify the team
    slack_webhook = os.environ["SLACK_WEBHOOK_URL"]
    requests.post(slack_webhook, json={
        "text": f"Battle card for {change['competitor']['name']} is being "
                f"regenerated due to: {change['title']}"
    })

    return "OK", 200

# .github/workflows/regenerate-battle-cards.yml
name: Regenerate Battle Cards
on:
  schedule:
    - cron: '0 8 * * 1'  # Every Monday at 8 AM UTC

jobs:
  regenerate:
    runs-on: ubuntu-latest
    steps:
      - name: Regenerate all battle cards
        env:
          RIVALCHECK_API_KEY: ${{ secrets.RIVALCHECK_API_KEY }}
        run: |
          # Get all active competitors
          COMPETITORS=$(curl -s \
            -H "Authorization: Bearer $RIVALCHECK_API_KEY" \
            "https://app.rivalcheck.com/api/v1/competitors?status=active")

          # Regenerate each battle card
          echo "$COMPETITORS" | jq -r '.competitors[].id' | while read id; do
            echo "Regenerating battle card for competitor $id..."
            curl -X POST \
              -H "Authorization: Bearer $RIVALCHECK_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"force": true}' \
              "https://app.rivalcheck.com/api/v1/competitors/$id/battle_card/generate"
            sleep 2  # Rate limiting courtesy
          done

# Check all battle cards for staleness
def audit_battle_card_freshness():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    resp = requests.get(f"{RIVALCHECK_API}/competitors", headers=headers)
    stale_cards = []

    for comp in resp.json()["competitors"]:
        if not comp.get("has_battle_card"):
            continue

        card = requests.get(
            f"{RIVALCHECK_API}/competitors/{comp['id']}/battle_card",
            headers=headers
        ).json()["battle_card"]

        if card["stale"]:
            stale_cards.append({
                "competitor": comp["name"],
                "reason": card["staleness_reason"],
                "last_generated": card["generated_at"]
            })

    if stale_cards:
        # Alert the team
        message = "Stale battle cards detected:\n"
        for card in stale_cards:
            message += (f"- {card['competitor']}: {card['reason']} "
                       f"(last updated {card['last_generated'][:10]})\n")
        send_slack_alert(message)

    return stale_cards