klaviyo-sdk-patterns

name	klaviyo-sdk-patterns
description	Apply production-ready Klaviyo SDK patterns for the klaviyo-api package. Use when implementing Klaviyo integrations, refactoring SDK usage, or establishing team coding standards for Klaviyo API calls. Trigger with phrases like "klaviyo SDK patterns", "klaviyo best practices", "klaviyo code patterns", "idiomatic klaviyo", "klaviyo wrapper".
allowed-tools	Read, Write, Edit
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","klaviyo","email-marketing","cdp"]
compatibility	Designed for Claude Code

Klaviyo SDK Patterns

Overview

Production-ready patterns for the klaviyo-api Node.js SDK: singleton sessions, type-safe wrappers, retry logic, cursor pagination, and multi-tenant support. Read the target project's Klaviyo files, then Write or Edit the src/klaviyo/ modules below into place so every call goes through one consistent, retry-aware layer instead of ad-hoc new ApiKeySession(...) calls scattered across the codebase.

The six patterns are summarized here with the essential skeleton; the full, copy-paste implementation for all of them lives in references/implementation.md, and combined worked examples with expected output are in references/examples.md.

Prerequisites

• klaviyo-api package installed in the target project.
• The klaviyo-install-auth setup completed, so KLAVIYO_PRIVATE_KEY is available in the environment.
• A TypeScript project with strict mode enabled — every pattern is typed.

Instructions

Step 1: Singleton session (the foundation)

Create one lazily-initialized ApiKeySession and reuse it everywhere. Read the key from the environment, fail fast if it is missing, and expose a reset hook for tests.

// src/klaviyo/session.ts
import { ApiKeySession } from 'klaviyo-api';

let _session: ApiKeySession | null = null;

export function getSession(apiKey?: string): ApiKeySession {
  if (!_session) {
    const key = apiKey || process.env.KLAVIYO_PRIVATE_KEY;
    if (!key) throw new ();
    _session =  (key);
  }
   _session;
}
  ():  { _session = ; }