Klaviyo Cloudflare KV Storage

Robust token and PKCE storage utilities for Klaviyo integrations running on Cloudflare Workers KV.

Features

• Encrypts Klaviyo refresh tokens with AES-CBC using Web Crypto
• Simple key-value persistence backed by Cloudflare KV namespaces
• Drop-in implementations for the TokenStorage and Pkce.CodeStorage interfaces from klaviyo-api
• Zero dependencies beyond klaviyo-api and the Cloudflare runtime

Installation

npm install @optizio/klaviyo-cloudflare-kv-storage

Requires Node.js 18+ or Cloudflare Workers with global crypto.subtle support.

Usage

import { KvTokenStorage, KvPkceStorage, type KV } from '@optizio/klaviyo-cloudflare-kv-storage'

declare const SESSION: KV
const refreshTokenKeyHex = process.env.KLAVIYO_REFRESH_TOKEN_AES_KEY_HEX!

const tokenStorage = new KvTokenStorage(SESSION, refreshTokenKeyHex)
const pkceStorage = new KvPkceStorage(SESSION)

KV Interface

The package expects an object that satisfies:

export type KV = {
  get: (key: string) => Promise<string | null>
  put: (key: string, value: string, options?: { expiration?: number; expirationTtl?: number }) => Promise<void>
  delete: (key: string) => Promise<void>
}

Cloudflare Workers KV bindings already conform to this signature.

API

class KvTokenStorage implements TokenStorage

• constructor(kv: KV, hexKey: string) – provide your KV binding and a 32-byte (64-char hex) encryption key
• retrieve(customerIdentifier: string): Promise<RetrievedTokens> – decrypts and returns stored tokens
• save(customerIdentifier: string, tokens: CreatedTokens): Promise<void> – encrypts refresh token and persists tokens

class KvPkceStorage implements Pkce.CodeStorage

• constructor(kv: KV) – provide your KV binding
• retrieve(customerIdentifier: string): Promise<string> – reads stored PKCE verifier
• save(customerIdentifier: string, codeVerifier: string): Promise<void> – stores PKCE verifier
• remove(customerIdentifier: string): Promise<void> – deletes PKCE verifier

Errors are thrown when data is missing or improperly formatted. Store keys use prefixes: klaviyo: for tokens and pkce: for PKCE verifiers.

Testing

npm test           # run Vitest in CI mode
npm run test:watch # run Vitest in watch mode

An in-memory KV implementation is used for tests; see test/index.test.ts for examples.

License

MIT © Optizio