thatrebeccarae/claude-marketing / skills/klaviyo-developer
klaviyo-developer
FlaggedKlaviyo 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.
| File | Kind | Size |
|---|---|---|
| .env.example | other | 968 B |
| EXAMPLES.md | markdown | 15.4 KB |
| LICENSE | other | 1.0 KB |
| REFERENCE.md | markdown | 41.1 KB |
| SKILL.md | skill md | 19.3 KB |
| requirements.txt | manifest | 143 B |
| scripts/dev_tools.py | script | 22.8 KB |
| scripts/klaviyo_client.py | script | 21.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()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |