Skip to content

thatrebeccarae/claude-marketing / skills/klaviyo-developer

klaviyo-developer

Flagged

Klaviyo API and developer integration expertise. Event tracking, SDKs, webhooks, rate limits, OAuth, catalog sync, and code patterns. Use when the user asks about Klaviyo API, integrating with Klaviyo, tracking events, building custom integrations, webhook handling, or developer implementation. For marketing strategy, flow optimization, and campaign auditing, see the klaviyo-analyst skill.

FileKindSize
.env.exampleother968 B
EXAMPLES.mdmarkdown15.4 KB
LICENSEother1.0 KB
REFERENCE.mdmarkdown41.1 KB
SKILL.mdskill md19.3 KB
requirements.txtmanifest143 B
scripts/dev_tools.pyscript22.8 KB
scripts/klaviyo_client.pyscript21.5 KB

scripts/dev_tools.py

View on GitHub
#!/usr/bin/env python3
"""
Klaviyo Developer Tools

Higher-level developer utilities for Klaviyo integration management:
- Integration health check
- Event validation
- Webhook testing
- CSV import with progress
- Paginated data export

Usage:
    python dev_tools.py --tool health-check
    python dev_tools.py --tool validate-events --events "Placed Order,Started Checkout"
    python dev_tools.py --tool test-webhook --webhook-url https://example.com/webhook
    python dev_tools.py --tool import-csv --file contacts.csv --list-id LIST_ID
    python dev_tools.py --tool export-data --resource profiles --max-records 1000
"""

import os
import sys
import json
import csv
import time
import argparse
import traceback
import hashlib
import hmac
from typing import Dict, List, Optional
from datetime import datetime
import ipaddress
from urllib.parse import urlparse

try:
    from klaviyo_client import KlaviyoDevClient
except ImportError:
    print("Error: klaviyo_client.py not found in the same directory", file=sys.stderr)
    sys.exit(1)


def _safe_output_path(path: str) -> str:
    """Validate output path does not escape working directory."""
    resolved = os.path.realpath(path)
    cwd = os.path.realpath(os.getcwd())
    if not resolved.startswith(cwd + os.sep) and resolved != cwd:
        raise ValueError(f"Output path must be within working directory: {cwd}")
    return resolved


def _safe_input_file(path: str) -> str:
    """Validate input file path: must be .csv and exist."""
    resolved = os.path.realpath(path)
    if not os.path.exists(resolved):
        raise FileNotFoundError(f"File not found: {path}")
    if not resolved.lower().endswith(".csv"):
        raise ValueError("Input file must be a .csv file")
    return resolved


def _validate_webhook_url(url: str) -> str:
    """Validate webhook URL is not targeting internal/private networks."""
    parsed = urlparse(url)
    if parsed.scheme not in ("https",):
        raise ValueError("Webhook URL must use HTTPS")
    hostname = parsed.hostname or ""
    if hostname in ("localhost", "127.0.0.1", "0.0.0.0", "::1", ""):
        raise ValueError("Webhook URL cannot target localhost")
    # Check for private/reserved IP ranges
    try:
        ip = ipaddress.ip_address(hostname)
        if ip.is_private or ip.is_reserved or ip.is_loopback or ip.is_link_local:
            raise ValueError("Webhook URL cannot target private/reserved IP addresses")
    except ValueError as e:
        if "private" in str(e).lower() or "reserved" in str(e).lower() or "localhost" in str(e).lower():
            raise
        # hostname is a domain name, not an IP — that's fine
    # Block cloud metadata endpoints
    if hostname == "169.254.169.254":
        raise ValueError("Webhook URL cannot target cloud metadata endpoints")
    return url


class KlaviyoDevTools:
    """Developer utilities for Klaviyo integration management."""

    def __init__(self):
        """Initialize with Klaviyo developer client."""
        self.client = KlaviyoDevClient()

    def health_check(self) -> Dict:
        """
        Check API connectivity, scopes, rate limits, and event health.

        Returns:
            Dictionary with health check results
        """
        results = {
            "timestamp": datetime.now().isoformat(),
            "checks": [],
            "status": "healthy",
        }

        # Check 1: API connectivity
        try:
            metrics = self.client.get_metrics()
            results["checks"].append({
                "check": "API Connectivity",
                "status": "pass",
                "detail": "Successfully connected to Klaviyo API",
            })
        except Exception as e:
            results["checks"].append({
                "check": "API Connectivity",
                "status": "fail",
                "detail": "Failed to connect. Check API key and network connection.",
                "underlying_error": f"{type(e).__name__}: {e}",
            })
            results["status"] = "unhealthy"
            return results

        # Check 2: Read scopes (profiles)
        try:
            profiles = self.client.export_profiles(page_size=1, max_pages=1)
            results["checks"].append({
                "check": "Profile Read Scope",
                "status": "pass",
                "detail": "profiles:read scope verified",
            })
        except Exception as e:
            results["checks"].append({
                "check": "Profile Read Scope",
                "status": "fail",
                "detail": "profiles:read may not be enabled. Check API key scopes.",
                "underlying_error": f"{type(e).__name__}: {e}",
            })

        # Check 3: Metrics availability
        try:
            metric_count = len(metrics) if isinstance(metrics, list) else 0
            results["checks"].append({
                "check": "Metrics Available",
                "status": "pass",
                "detail": f"{metric_count} event types found",
            })

            # Check for essential e-commerce events
            metric_names = [
                m.get("name", "").lower()
                for m in metrics
                if isinstance(m, dict)
            ]
            essential_events = [
                "placed order",
                "started checkout",
                "viewed product",
                "added to cart",
            ]
            found_events = [
                e for e in essential_events if e in metric_names
            ]
            missing_events = [
                e for e in essential_events if e not in metric_names
            ]

            if missing_events:
                results["checks"].append({
                    "check": "E-commerce Events",
                    "status": "warning",
                    "detail": f"Missing: {', '.join(missing_events)}",
                })
            else:
                results["checks"].append({
                    "check": "E-commerce Events",
                    "status": "pass",
                    "detail": f"All {len(essential_events)} essential events present",
                })

        except Exception as e:
            results["checks"].append({
                "check": "Metrics Available",
                "status": "fail",
                "detail": "Failed to retrieve metrics. Check API key scopes.",
                "underlying_error": f"{type(e).__name__}: {e}",
            })

        # Check 4: Catalog access
        try:
            catalog = self.client.get_catalog_items()
            item_count = len(catalog) if isinstance(catalog, list) else 0
            results["checks"].append({
                "check": "Catalog Access",
                "status": "pass",
                "detail": f"catalogs:read verified ({item_count} items found)",
            })
        except Exception as e:
            results["checks"].append({
                "check": "Catalog Access",
                "status": "warning",
                "detail": "catalogs:read may not be enabled. Check API key scopes.",
                "underlying_error": f"{type(e).__name__}: {e}",
            })

        # Set overall status
        statuses = [c["status"] for c in results["checks"]]
        if "fail" in statuses:
            results["status"] = "unhealthy"
        elif "warning" in statuses:
            results["status"] = "degraded"

        results["recommendations"] = self._recommend_health_fixes(results["checks"])

        return results

    def validate_events(self, event_names: List[str]) -> Dict:
        """
        Check that expected events exist and are being tracked.

        Args:
            event_names: List of event names to validate

        Returns:
            Dictionary with validation results
        """
        metrics = self.client.get_metrics()
        metric_names = [
            m.get("name", "") for m in metrics if isinstance(m, dict)
        ]
        metric_names_lower = [n.lower() for n in metric_names]

        results = []
        for event in event_names:
            found = event.lower() in metric_names_lower
            results.append({
                "event": event,
                "status": "found" if found else "missing",
            })

        found_count = sum(1 for r in results if r["status"] == "found")

        return {
            "summary": {
                "events_checked": len(event_names),
                "events_found": found_count,
                "events_missing": len(event_names) - found_count,
            },
            "results": results,
            "available_events": metric_names,
            "recommendations": self._recommend_event_fixes(results),
        }

    def test_webhook(self, url: str, secret: Optional[str] = None) -> Dict:
        """
        Send a test payload to a webhook URL and report results.

        Args:
            url: Webhook endpoint URL
            secret: Optional webhook secret for signature generation

        Returns:
            Dictionary with test results
        """
        url = _validate_webhook_url(url)
        if not secret:
            secret = os.environ.get("KLAVIYO_WEBHOOK_SECRET")

        import urllib.request
        import urllib.error

        test_payload = json.dumps({
            "type": "test",
            "data": {
                "type": "event",
                "attributes": {
                    "metric_name": "webhook_test",
                    "timestamp": datetime.now().isoformat(),
                    "properties": {"source": "klaviyo-dev-tools"},
                },
            },
        })

        headers = {"Content-Type": "application/json"}

        if secret:
            signature = hmac.new(
                secret.encode(), test_payload.encode(), hashlib.sha256
            ).hexdigest()
            headers["X-Klaviyo-Webhook-Signature"] = signature

        results = {
            "url": url,
            "payload_size": len(test_payload),
            "signature_included": bool(secret),
        }

        try:
            req = urllib.request.Request(
                url,
                data=test_payload.encode(),
                headers=headers,
                method="POST",
            )
            with urllib.request.urlopen(req, timeout=10) as response:
                results["status"] = "pass"
                results["response_code"] = response.status
                results["response_body"] = response.read().decode()[:500]

        except urllib.error.HTTPError as e:
            results["status"] = "fail"
            results["response_code"] = e.code
            results["error"] = "HTTP error received from webhook endpoint"

        except urllib.error.URLError:
            results["status"] = "fail"
            results["error"] = "Connection failed. Check the webhook URL and network."

        except Exception as e:
            results["status"] = "fail"
            results["error"] = "Webhook test failed. Check the URL and try again."
            results["underlying_error"] = f"{type(e).__name__}: {e}"

        return results

    def import_csv(
        self, filepath: str, list_id: Optional[str] = None
    ) -> Dict:
        """
        Import profiles from CSV with batching and progress reporting.

        Args:
            filepath: Path to CSV file
            list_id: Optional list ID to add profiles to

        Returns:
            Dictionary with import results
        """
        # Read CSV
        profiles = []
        safe_file = _safe_input_file(filepath)
        with open(safe_file, "r", encoding="utf-8") as f:
            reader = csv.DictReader(f)
            for row in reader:
                profiles.append(dict(row))

        total = len(profiles)
        batch_size = 10000
        results = {
            "file": filepath,
            "total_profiles": total,
            "batches": [],
            "errors": [],
        }

        # Process in batches
        for i in range(0, total, batch_size):
            batch = profiles[i : i + batch_size]
            batch_num = (i // batch_size) + 1
            total_batches = (total + batch_size - 1) // batch_size

            print(
                f"Batch {batch_num}/{total_batches}: "
                f"importing {len(batch)} profiles...",
                file=sys.stderr,
            )

            try:
                result = self.client.bulk_import(batch, list_id=list_id)
                results["batches"].append({
                    "batch": batch_num,
                    "profiles": len(batch),
                    "status": "submitted",
                    "job_id": result.get("job_id"),
                })
            except Exception as e:
                results["batches"].append({
                    "batch": batch_num,
                    "profiles": len(batch),
                    "status": "failed",
                    "error": "Batch import failed. Check API key and profile data.",
                    "underlying_error": f"{type(e).__name__}: {e}",
                })
                results["errors"].append(f"Batch import failed: {type(e).__name__}: {e}")

        # Summary
        successful = sum(
            1 for b in results["batches"] if b["status"] == "submitted"
        )
        results["summary"] = {
            "batches_submitted": successful,
            "batches_failed": len(results["batches"]) - successful,
            "profiles_submitted": sum(
                b["profiles"]
                for b in results["batches"]
                if b["status"] == "submitted"
            ),
        }

        return results

    def export_data(
        self,
        resource: str,
        output_path: Optional[str] = None,
        max_records: Optional[int] = None,
    ) -> Dict:
        """
        Export data with pagination to CSV.

        Args:
            resource: Resource type (profiles, events, catalog)
            output_path: Output CSV file path
            max_records: Maximum records to export

        Returns:
            Dictionary with export summary
        """
        max_pages = None
        if max_records:
            max_pages = (max_records + 99) // 100

        if resource == "profiles":
            data = self.client.export_profiles(
                page_size=100, max_pages=max_pages
            )
        elif resource == "catalog":
            data = self.client.get_catalog_items()
        elif resource == "events":
            # Events don't have a simple paginated export via SDK
            data = []
            print(
                "Note: Event export requires metric aggregation API. "
                "Use --resource profiles or catalog instead.",
                file=sys.stderr,
            )
        else:
            raise ValueError(f"Unsupported resource type: {resource}")

        if max_records and len(data) > max_records:
            data = data[:max_records]

        # Write CSV if output specified
        if output_path and data:
            all_keys = []
            for row in data:
                for key in row.keys():
                    if key not in all_keys:
                        all_keys.append(key)

            safe_path = _safe_output_path(output_path)
            with open(safe_path, "w", newline="", encoding="utf-8") as f:
                writer = csv.DictWriter(
                    f, fieldnames=all_keys, extrasaction="ignore"
                )
                writer.writeheader()
                for row in data:
                    clean_row = {}
                    for k, v in row.items():
                        if isinstance(v, (dict, list)):
                            clean_row[k] = json.dumps(v)
                        else:
                            clean_row[k] = v
                    writer.writerow(clean_row)

            print(f"Exported {len(data)} records to {output_path}", file=sys.stderr)

        return {
            "resource": resource,
            "records_exported": len(data),
            "output_file": output_path,
        }

    def _recommend_health_fixes(self, checks: List[Dict]) -> List[Dict]:
        """Generate recommendations from health check results."""
        recommendations = []

        for check in checks:
            if check["status"] == "fail":
                if "connectivity" in check["check"].lower():
                    recommendations.append({
                        "priority": "CRITICAL",
                        "action": "Fix API authentication",
                        "reason": check["detail"],
                        "expected_impact": "Restore all Klaviyo integrations",
                    })
                elif "scope" in check["check"].lower():
                    recommendations.append({
                        "priority": "HIGH",
                        "action": f"Enable missing scope for {check['check']}",
                        "reason": check["detail"],
                        "expected_impact": "Restore access to this resource",
                    })
            elif check["status"] == "warning":
                if "events" in check["check"].lower():
                    recommendations.append({
                        "priority": "HIGH",
                        "action": "Implement missing e-commerce event tracking",
                        "reason": check["detail"],
                        "expected_impact": "Enable automated flows for missing events",
                    })

        if not recommendations:
            recommendations.append({
                "priority": "INFO",
                "action": "All health checks passed",
                "reason": "Integration is healthy",
                "expected_impact": "Continue monitoring",
            })

        return recommendations

    def _recommend_event_fixes(self, results: List[Dict]) -> List[Dict]:
        """Generate recommendations from event validation results."""
        recommendations = []

        missing = [r for r in results if r["status"] == "missing"]

        for event in missing:
            recommendations.append({
                "priority": "HIGH",
                "action": f"Implement tracking for '{event['event']}'",
                "reason": f"Event '{event['event']}' not found in Klaviyo",
                "expected_impact": "Enable flows and segments triggered by this event",
            })

        if not missing:
            recommendations.append({
                "priority": "INFO",
                "action": "All expected events are being tracked",
                "reason": "Event validation passed",
                "expected_impact": "Continue monitoring event freshness",
            })

        return recommendations


def main():
    parser = argparse.ArgumentParser(
        description="Klaviyo developer tools",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # Run integration health check
  python dev_tools.py --tool health-check

  # Validate expected events exist
  python dev_tools.py --tool validate-events \\
      --events "Placed Order,Started Checkout,Viewed Product"

  # Test a webhook endpoint
  python dev_tools.py --tool test-webhook \\
      --webhook-url https://example.com/webhooks/klaviyo

  # Test webhook with signature verification
  python dev_tools.py --tool test-webhook \\
      --webhook-url https://example.com/webhooks/klaviyo \\
      --webhook-secret your-secret-here

  # Import profiles from CSV
  python dev_tools.py --tool import-csv \\
      --file contacts.csv --list-id LIST_ID

  # Export profiles to CSV
  python dev_tools.py --tool export-data \\
      --resource profiles --max-records 5000 --output profiles.csv
        """,
    )

    parser.add_argument(
        "--tool",
        required=True,
        choices=[
            "health-check",
            "validate-events",
            "test-webhook",
            "import-csv",
            "export-data",
        ],
        help="Tool to run",
    )
    parser.add_argument(
        "--events",
        help="Comma-separated event names (for validate-events)",
    )
    parser.add_argument(
        "--webhook-url",
        help="Webhook URL to test (for test-webhook)",
    )
    parser.add_argument(
        "--webhook-secret",
        help="Webhook secret for signature (for test-webhook)",
    )
    parser.add_argument(
        "--file",
        help="CSV file path (for import-csv)",
    )
    parser.add_argument(
        "--list-id",
        help="List ID (for import-csv)",
    )
    parser.add_argument(
        "--resource",
        choices=["profiles", "events", "catalog"],
        help="Resource to export (for export-data)",
    )
    parser.add_argument(
        "--max-records",
        type=int,
        help="Max records to export (for export-data)",
    )
    parser.add_argument(
        "--format",
        choices=["json", "table"],
        default="json",
        help="Output format (default: json)",
    )
    parser.add_argument(
        "--output",
        help="Output file path (default: stdout)",
    )
    parser.add_argument(
        "--debug",
        action="store_true",
        help="Re-raise exceptions with full traceback instead of friendly error",
    )

    args = parser.parse_args()

    try:
        tools = KlaviyoDevTools()

        if args.tool == "health-check":
            result = tools.health_check()

        elif args.tool == "validate-events":
            if not args.events:
                parser.error("--events is required for validate-events")
            event_list = [e.strip() for e in args.events.split(",")]
            result = tools.validate_events(event_list)

        elif args.tool == "test-webhook":
            if not args.webhook_url:
                parser.error("--webhook-url is required for test-webhook")
            result = tools.test_webhook(
                args.webhook_url, secret=args.webhook_secret or os.environ.get("KLAVIYO_WEBHOOK_SECRET")
            )

        elif args.tool == "import-csv":
            if not args.file:
                parser.error("--file is required for import-csv")
            result = tools.import_csv(args.file, list_id=args.list_id)

        elif args.tool == "export-data":
            if not args.resource:
                parser.error("--resource is required for export-data")
            result = tools.export_data(
                args.resource,
                output_path=args.output,
                max_records=args.max_records,
            )

        # Format output
        output = json.dumps(result, indent=2, default=str)

        # Write output
        if args.output and args.tool != "export-data":
            safe_path = _safe_output_path(args.output)
            with open(safe_path, "w", encoding="utf-8") as f:
                f.write(output)
            print(f"Results saved to {args.output}", file=sys.stderr)
        else:
            print(output)

    except (ValueError, FileNotFoundError) as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    except Exception:
        if args.debug:
            traceback.print_exc()
        else:
            print("Error: Operation failed. Check your API key and network connection.", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall