About

Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/klaviyo-debug-bundle/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill klaviyo-debug-bundle. Copyright stays with the author (MIT).

Klaviyo Debug Bundle

Name: klaviyo-debug-bundle
Author: jeremylongshore

Overview

Collect all diagnostic information needed for a Klaviyo support ticket into one redacted, shareable tarball: SDK version, API connectivity, auth result, rate limit status, recent errors, and environment config. Every secret (API keys, emails, phone numbers, webhook secrets) is redacted before packaging, so the bundle is safe to attach to a ticket.

The workflow builds a single shell script (klaviyo-debug-bundle.sh) in five steps, then runs it. The full script and a programmatic TypeScript alternative live in the reference files linked below.

Prerequisites

The klaviyo-api SDK installed (npm list klaviyo-api to confirm).
The KLAVIYO_PRIVATE_KEY environment variable set to a private API key.
Read access to your application's log directory (defaults scanned: logs/, /var/log/app/).
curl, tar, and python3 available on the host.

Instructions

Assemble the five blocks below (verbatim from the reference) into one klaviyo-debug-bundle.sh, make it executable, and run it from your application root so the log-collection step can find logs/.

Create the bundle dir — timestamped klaviyo-debug-YYYYMMDD-HHMMSS/ and a summary.txt header.
Collect environment info — Node/npm/OS versions, klaviyo-api SDK version, and a redacted API-key presence check.
Run connectivity tests — DNS resolve, an authenticated GET /api/accounts/ (captures the HTTP code), rate-limit headers, and the Klaviyo status page.
Collect logs — grep known log dirs for Klaviyo errors, redacting keys and emails inline.
Package and clean up — tar -czf the dir, remove the working copy, print the tarball path.

The skeleton of step 1:

#!/bin/bash
# klaviyo-debug-bundle.sh
set -euo pipefail
BUNDLE_DIR="klaviyo-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

See the full shell implementation for all five steps verbatim. To collect the same signals as a structured object (SDK version, connectivity, latency) instead of a tarball, use the TypeScript helper in examples.

Output

klaviyo-debug-YYYYMMDD-HHMMSS.tar.gz containing:
- summary.txt -- Environment, SDK version, API key status, connectivity
- rate-limits.txt -- Current rate limit header values
- api-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/HTTP status codes, SDK and runtime versions, stack traces (with PII redacted), rate limit header values, Klaviyo account ID.

Error Handling

The bundle is designed to never abort on a single failed probe — each check records its failure into the summary rather than exiting, so you always get a complete picture. Read the results with this triage:

KLAVIYO_PRIVATE_KEY: NOT SET — the connectivity and rate-limit steps are skipped. Export the key and re-run before attaching the bundle.
API Auth Test: HTTP 401 — key is invalid or revoked. Rotate the key.
API Auth Test: HTTP 403 — key lacks scope for /api/accounts/. Grant the scope in Klaviyo account settings.
API Auth Test: HTTP 429 — you are rate limited; inspect rate-limits.txt and see the klaviyo-rate-limits skill.
API Auth Test: HTTP 000 or DNS resolve ... FAILED — no response reached Klaviyo (DNS, outbound firewall, or TLS). Fix connectivity before ticketing.
recent-errors.txt empty — no matching log dir was found; pass your real log path by adding it to the for logdir in ... loop in step 4.
Before sharing, open summary.txt and confirm no unredacted pk_ prefix or email survived — the script prints a reminder to do this.

See the examples reference for the full HTTP-code decision matrix.

Examples

Generate a bundle for a failing send — set the key, run the script, read the HTTP 200 / All Systems Operational summary lines.
Programmatic debug info — call collectKlaviyoDebugInfo() from a health check to return SDK version, connectivity, and latency as an object.
Reading the auth result — map the API Auth Test: HTTP NNN line to a next action (200 healthy → check logs; 401 → rotate key; 429 → rate limits).

Full runnable code for all three is in examples.

Resources

Next Steps

For rate limit issues surfaced by the bundle (HTTP 429, retry-after headers), see the klaviyo-rate-limits skill for backoff and quota-management guidance.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-klaviyo-debug-bundle/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-klaviyo-debug-bundle.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-klaviyo-debug-bundle",
  "kind": "skill",
  "name": "klaviyo-debug-bundle",
  "description": "Collect Klaviyo debug evidence for support tickets and troubleshooting. Use when a Klaviyo integration is failing, when preparing a support ticket, or when collecting diagnostic information for a Klaviyo API problem. Trigger with phrases like \"klaviyo debug\", \"klaviyo support bundle\", \"collect klaviyo logs\", \"klaviyo diagnostic\", \"klaviyo troubleshoot\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding",
      "customer_support"
    ],
    "tags": [
      "skill-md",
      "saas",
      "klaviyo",
      "email-marketing",
      "cdp",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Collect Klaviyo debug evidence for support tickets and troubleshooting. Use when a Klaviyo integration is failing, when preparing a support ticket, or when collecting diagnostic information for a Klaviyo API problem. Trigger with phrases like \"klaviyo debug\", \"klaviyo support bundle\", \"collect klaviyo logs\", \"klaviyo diagnostic\", \"klaviyo troubleshoot\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "skills/.curated/klaviyo-debug-bundle/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/skills/.curated/klaviyo-debug-bundle/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/skills/.curated/klaviyo-debug-bundle/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Bash(grep:*),",
      "Bash(curl:*),",
      "Bash(tar:*),",
      "Bash(npm:*)"
    ],
    "license": "MIT"
  },
  "instructions": "# Klaviyo Debug Bundle\n\n## Overview\n\nCollect all diagnostic information needed for a Klaviyo support ticket into one\nredacted, shareable tarball: SDK version, API connectivity, auth result, rate\nlimit status, recent errors, and environment config. Every secret (API keys,\nemails, phone numbers, webhook secrets) is redacted before packaging, so the\nbundle is safe to attach to a ticket.\n\nThe workflow builds a single shell script (`klaviyo-debug-bundle.sh`) in five\nsteps, then runs it. The full script and a programmatic TypeScript alternative\nlive in the reference files linked below.\n\n## Prerequis",
  "cost": {
    "context_tokens": 1241
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-klaviyo-debug-bundle/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.