customerio

A tiny, dependency-free fake of the Customer.io Journeys REST API (Track API + App API + Pipelines API) that speaks the exact wire protocol of the official customerio-node client — like LocalStack, but in-process and zero-cost.

• Default port: 4668
• Protocol: HTTP / JSON (Customer.io REST: Track, App, and Pipelines APIs)
• Compatible client: customerio-node (TrackClient, APIClient, PipelinesClient)
• Healthcheck: GET /health → { "status": "ok" }
• State: in-memory and ephemeral; resettable via POST /__parlel/reset

The real product hosts the App API (api.customer.io) and Pipelines API (cdp.customer.io) on different hosts. This fake serves all three APIs on one port, disambiguated by path prefix. Point every customerio-node client at the same base URL via its url option.

Quick start

import { CustomerioServer } from "./services/customerio/src/server.js";

const server = new CustomerioServer(4668);
await server.start();
// ... run your app/tests ...
await server.stop();

Connect with the real customerio-node client (point url at the fake):

const { TrackClient, APIClient, PipelinesClient } = require("customerio-node");

// Track API (Basic auth: siteId + apiKey)
const cio = new TrackClient("parlel-site-id", "parlel-api-key", {
  url: "http://127.0.0.1:4668/api/v1",
});
await cio.identify("1", { email: "bob@example.com", plan: "pro" });
await cio.track("1", { name: "signup", data: { source: "web" } });

// App API (Bearer auth: app key)
const api = new APIClient("parlel-app-key", { url: "http://127.0.0.1:4668/v1" });
const { SendEmailRequest } = require("customerio-node");
await api.sendEmail(new SendEmailRequest({
  to: "person@example.com",
  identifiers: { email: "person@example.com" },
  transactional_message_id: "welcome",
}));

// Pipelines API (Basic auth: write key)
const cdp = new PipelinesClient("parlel-write-key", { url: "http://127.0.0.1:4668/v1" });
await cdp.identify({ userId: "1", traits: { email: "bob@example.com" } });

The TrackClient derives the Track v2 (batch) base by replacing /api/v1 with /api/v2, so passing url: ".../api/v1" routes batch() to .../api/v2/batch automatically.

Run a standalone instance:

PORT=4668 node services/customerio/src/server.js

Implemented operations

Track API — TrackClient (Basic auth, /api/v1)

App API — APIClient (Bearer auth, /v1)

Pipelines API — PipelinesClient (Basic auth with write key, /v1)

parlel inspection / control endpoints (not part of Customer.io)

These let tests assert what was captured. No auth required.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes & shapes

Errors use the Customer.io envelope that customerio-node's CustomerIORequestError.composeMessage understands:

• Single error: { "meta": { "error": "message" } }
• Multiple errors: { "meta": { "errors": ["message", ...] } }

Successful responses mirror the real API where the client reads them:

• Transactional sends return { "delivery_id": "...", "queued": true }.
• getCustomersByEmail returns { "results": [...] }.
• getAttributes returns { "customer": { ... } }.
• Exports return { "export": { ... } } (and listExports returns { "exports": [...] }).
• Pipelines operations return { "success": true }.
• Track operations return {}.

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

CUSTOMERIO_SITE_ID=parlel-site-id
CUSTOMERIO_API_KEY=parlel-api-key
CUSTOMERIO_APP_KEY=parlel-app-key
CUSTOMERIO_TRACK_URL=http://parlel-bridge:4668/api/v1
CUSTOMERIO_API_URL=http://parlel-bridge:4668/v1
CUSTOMERIO_PIPELINES_URL=http://parlel-bridge:4668/v1