Agent skill
klaviyo-debug-bundle
Collect Klaviyo debug evidence for support tickets and troubleshooting. Use when encountering persistent issues, preparing support tickets, or collecting diagnostic information for Klaviyo API problems. Trigger with phrases like "klaviyo debug", "klaviyo support bundle", "collect klaviyo logs", "klaviyo diagnostic", "klaviyo troubleshoot".
Install this agent skill to your Project
npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/klaviyo-pack/skills/klaviyo-debug-bundle
SKILL.md
Klaviyo Debug Bundle
Overview
Collect all diagnostic information needed for Klaviyo support tickets: SDK version, API connectivity, rate limit status, recent errors, and environment config (with secrets redacted).
Prerequisites
klaviyo-apiSDK installedKLAVIYO_PRIVATE_KEYenvironment variable set- Access to application logs
Instructions
Step 1: Create Debug Bundle Script
#!/bin/bash
# klaviyo-debug-bundle.sh
set -euo pipefail
BUNDLE_DIR="klaviyo-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
echo "=== Klaviyo Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"
Step 2: Collect Environment Info
# --- Runtime ---
echo "--- Runtime Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node.js: $(node --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -srm)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"
# --- SDK Version ---
echo "--- Klaviyo SDK ---" >> "$BUNDLE_DIR/summary.txt"
npm list klaviyo-api 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "klaviyo-api: not installed" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"
# --- API Key Check (redacted) ---
echo "--- API Key Status ---" >> "$BUNDLE_DIR/summary.txt"
if [ -n "${KLAVIYO_PRIVATE_KEY:-}" ]; then
echo "KLAVIYO_PRIVATE_KEY: SET (${#KLAVIYO_PRIVATE_KEY} chars, prefix: ${KLAVIYO_PRIVATE_KEY:0:3}***)" >> "$BUNDLE_DIR/summary.txt"
else
echo "KLAVIYO_PRIVATE_KEY: NOT SET" >> "$BUNDLE_DIR/summary.txt"
fi
echo "" >> "$BUNDLE_DIR/summary.txt"
Step 3: API Connectivity Tests
# --- API Connectivity ---
echo "--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
# Test base connectivity
echo -n "DNS resolve a.klaviyo.com: " >> "$BUNDLE_DIR/summary.txt"
nslookup a.klaviyo.com > /dev/null 2>&1 && echo "OK" >> "$BUNDLE_DIR/summary.txt" || echo "FAILED" >> "$BUNDLE_DIR/summary.txt"
# Test API authentication
if [ -n "${KLAVIYO_PRIVATE_KEY:-}" ]; then
HTTP_CODE=$(curl -s -o "$BUNDLE_DIR/api-response.json" -w "%{http_code}" \
-H "Authorization: Klaviyo-API-Key $KLAVIYO_PRIVATE_KEY" \
-H "revision: 2024-10-15" \
-H "Accept: application/vnd.api+json" \
"https://a.klaviyo.com/api/accounts/" 2>/dev/null || echo "000")
echo "API Auth Test: HTTP $HTTP_CODE" >> "$BUNDLE_DIR/summary.txt"
# Capture rate limit headers
curl -s -I \
-H "Authorization: Klaviyo-API-Key $KLAVIYO_PRIVATE_KEY" \
-H "revision: 2024-10-15" \
"https://a.klaviyo.com/api/profiles/?page[size]=1" 2>/dev/null \
| grep -i "ratelimit\|retry-after" >> "$BUNDLE_DIR/rate-limits.txt" || echo "No rate limit headers" >> "$BUNDLE_DIR/rate-limits.txt"
fi
# Check Klaviyo status page
echo -n "Status Page: " >> "$BUNDLE_DIR/summary.txt"
curl -s "https://status.klaviyo.com/api/v2/status.json" 2>/dev/null \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('status',{}).get('description','unknown'))" >> "$BUNDLE_DIR/summary.txt" 2>/dev/null \
|| echo "Could not reach status page" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"
Step 4: Application Log Collection
# --- Recent Error Logs (redacted) ---
echo "--- Recent Klaviyo Errors ---" >> "$BUNDLE_DIR/summary.txt"
# Search common log locations for Klaviyo errors
for logdir in logs/ /var/log/app/; do
if [ -d "$logdir" ]; then
grep -i "klaviyo\|a\.klaviyo\.com" "$logdir"*.log 2>/dev/null \
| tail -50 \
| sed -E 's/pk_[a-zA-Z0-9]+/pk_***REDACTED***/g' \
| sed -E 's/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/***@redacted***/g' \
>> "$BUNDLE_DIR/recent-errors.txt"
fi
done
# Redact any remaining secrets from all collected files
for file in "$BUNDLE_DIR"/*.txt "$BUNDLE_DIR"/*.json; do
[ -f "$file" ] && sed -i -E 's/pk_[a-zA-Z0-9]{20,}/pk_***REDACTED***/g' "$file"
done
Step 5: Package and Output
# Package bundle
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo ""
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo "Review before sharing -- ensure no secrets remain."
Programmatic Debug Info
// src/klaviyo/debug.ts
import { ApiKeySession, AccountsApi, ProfilesApi } from 'klaviyo-api';
interface KlaviyoDebugInfo {
sdkVersion: string;
apiConnected: boolean;
accountId?: string;
accountName?: string;
apiLatencyMs: number;
rateLimitStatus?: string;
error?: string;
}
export async function collectKlaviyoDebugInfo(): Promise<KlaviyoDebugInfo> {
const start = Date.now();
const sdkVersion = require('klaviyo-api/package.json').version;
try {
const session = new ApiKeySession(process.env.KLAVIYO_PRIVATE_KEY!);
const accountsApi = new AccountsApi(session);
const result = await accountsApi.getAccounts();
const account = result.body.data[0];
return {
sdkVersion,
apiConnected: true,
accountId: account.id,
accountName: account.attributes.contactInformation?.organizationName,
apiLatencyMs: Date.now() - start,
};
} catch (error: any) {
return {
sdkVersion,
apiConnected: false,
apiLatencyMs: Date.now() - start,
error: `${error.status || 'N/A'}: ${error.body?.errors?.[0]?.detail || error.message}`,
};
}
}
Output
klaviyo-debug-YYYYMMDD-HHMMSS.tar.gzcontaining:summary.txt-- Environment, SDK version, API key status, connectivityrate-limits.txt-- Current rate limit header valuesapi-response.json-- Account API response (confirms auth)recent-errors.txt-- Redacted error logs
Redaction Rules
ALWAYS redacted:
- API keys (
pk_***) - Email addresses
- Phone numbers
- Webhook secrets
Safe to include:
- Error codes and HTTP status codes
- SDK and runtime versions
- Stack traces (with PII redacted)
- Rate limit header values
- Klaviyo account ID
Resources
Next Steps
For rate limit issues, see klaviyo-rate-limits.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dockerfile-generator
Dockerfile Generator - Auto-activating skill for DevOps Basics. Triggers on: dockerfile generator, dockerfile generator Part of the DevOps Basics skill category.
branch-naming-helper
Branch Naming Helper - Auto-activating skill for DevOps Basics. Triggers on: branch naming helper, branch naming helper Part of the DevOps Basics skill category.
readme-generator
Readme Generator - Auto-activating skill for DevOps Basics. Triggers on: readme generator, readme generator Part of the DevOps Basics skill category.
makefile-generator
Makefile Generator - Auto-activating skill for DevOps Basics. Triggers on: makefile generator, makefile generator Part of the DevOps Basics skill category.
gitignore-generator
Gitignore Generator - Auto-activating skill for DevOps Basics. Triggers on: gitignore generator, gitignore generator Part of the DevOps Basics skill category.
pre-commit-hook-setup
Pre Commit Hook Setup - Auto-activating skill for DevOps Basics. Triggers on: pre commit hook setup, pre commit hook setup Part of the DevOps Basics skill category.
Didn't find tool you were looking for?