@crvouga/mockingbird-service-klaviyo

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Klaviyo events API for test suites: the JSON:API create-event endpoint our backend posts Ordered Product and Placed Order to after checkout, the event reads, and an outbox a suite asserts on. Errors come back in Klaviyo's JSON:API errors[] shape, so the text our client throws (and logs) is the text the real API would produce.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is trimmed from Klaviyo's published API (revision 2024-02-15, the one our backend pins) to what our consumer sends.

Install

npm install -D @crvouga/mockingbird-service-klaviyo

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-klaviyo serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

Point KLAVIYO_URL (Joi-required, fully overridable) at the emulator's event endpoint; any KLAVIYO_API_KEY works.

npx mockingbird-klaviyo serve --port 8811
# KLAVIYO_URL=http://127.0.0.1:8811/api/events/

import { ApiKeySession, EventEnum, EventsApi, MetricEnum, ProfileEnum } from "klaviyo-api"
import { createServer } from "@crvouga/mockingbird-service-klaviyo/server"

const klaviyo = await createServer()

// The application's Klaviyo client. Only basePath changes.
const events = new EventsApi(new ApiKeySession("any-key"))
events.basePath = klaviyo.url
await events.createEvent({
  data: {
    type: EventEnum.Event,
    attributes: {
      properties: { OrderId: "1001" },
      value: 29,
      uniqueId: "order-1001",
      metric: { data: { type: MetricEnum.Metric, attributes: { name: "Placed Order" } } },
      profile: { data: { type: ProfileEnum.Profile, attributes: { email: "[email protected]" } } },
    },
  },
})

// Test assertion: the outbox holds what the emulator accepted.
const response = await fetch(`${klaviyo.url}/__admin/[email protected]&metric=Placed%20Order`)
const { messages } = (await response.json()) as { messages: { metric: string; value: number }[] }
// messages → [{ metric: "Placed Order", value: 29, … }]

await klaviyo.close()

Routes

Every call needs Authorization: Klaviyo-API-Key <key> (else 401 not_authenticated) and a revision: YYYY-MM-DD header (else 400). Paths answer with or without the trailing slash.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): throttled (429 + Retry-After: 1), invalid_api_key (401), server_error (500), service_unavailable (503), connection_drop (the socket closes; nothing is stored).

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix in KLAVIYO_URL, or by private key: PUT /__admin/credentials {"credentials": {"<KLAVIYO_API_KEY>": "<namespace>"}}.

Deliberately not modelled

• Flows, lists, segments and campaigns: an event never triggers an email (use the outbox).
• Profile-id validation: Klaviyo profile ids are Klaviyo-generated; our backend sends the user token as profile.data.id, which the emulator adopts as the profile id rather than rejecting. Whether the real API accepts an unknown id is unverified (no sandbox credentials).
• Pagination (page[cursor]), filter, fields[…] and include on reads.
• Rate limits, except through the throttled preset.

API

Part of mockingbird.