@crvouga/mockingbird-service-meta
Local emulators. Real API contracts. Part of Mockingbird.
Stateful Meta Graph v26 emulator for server-side Conversions API events and marketing reporting. It preserves privacy-safe hashed user fields, event deduplication, ambiguous writes, Graph errors, campaign objects, dated insights, breakdowns, and cursor pagination without contacting Meta.
Install
npm install -D @crvouga/mockingbird-service-meta
ESM only. Node >= 22 or Bun >= 1.2. Serve with npx mockingbird-meta serve, createServer from
./server, or mount createRuntime() in any Fetch-compatible process.
Usage
Make the Graph origin injectable and point it at the emulator. Any non-empty synthetic Bearer token or
access_token query value authenticates unless /__admin/settings restricts tokens.
import { createServer } from "@crvouga/mockingbird-service-meta/server"
const server = await createServer()
// The application's own Conversions API request. Only the Graph origin changes:
// server.url instead of https://graph.facebook.com.
const response = await fetch(`${server.url}/v26.0/pixel_test/events`, {
method: "POST",
headers: { authorization: "Bearer meta_test", "content-type": "application/json" },
body: JSON.stringify({ data: [{
event_name: "Purchase",
event_time: Math.floor(Date.now() / 1000),
event_id: "order_42",
action_source: "website",
user_data: { em: ["a".repeat(64)] },
custom_data: { currency: "USD", value: 42 },
}] }),
})
console.log(await response.json())
// → {events_received: 1, messages: [], fbtrace_id: "trace_…"}
await server.close()
Routes
| Route | Behaviour |
|---|---|
POST /v26.0/:pixelId/events | Accepts CAPI data[] and test_event_code; keeps event name/time/id, action source, source URL, hashed user data and custom data. Repeated event_id values are acknowledged without a second stored event. Events older than seven days, future events, malformed hashes and invalid bodies receive Graph error envelopes. |
GET /v26.0/:accountId/insights | Filters seeded or admin-inserted insight rows by inclusive JSON time_range, paginates with limit/after, and includes country when requested as a breakdown. |
GET /v26.0/:objectId | Reads seeded/admin-inserted campaign, ad-set, or ad records. |
Seed fixtures are act_mockingbird, cmp_mockingbird, set_mockingbird, and ad_mockingbird,
with three dated insight rows from 2026-01-01 through 2026-01-03.
Admin and faults
GET /__admin/events returns the namespace's privacy-safe stored requests. GET/PUT /__admin/settings controls accessTokens and maxEventAgeSeconds. Standard /__admin/state
routes seed or edit events, objects, and insights directly.
Presets: expired_token, rate_limited, server_error, partial_event_acceptance,
accepted_then_drop, and slow. The ambiguous-write preset persists the event before dropping the
connection; retrying the same event_id remains deduplicated.
Namespaces use x-mockingbird-namespace, /__admin/ns/<name>/…, or credential mapping through
PUT /__admin/credentials.
API
The main entry exports MetaAPI, MetaState, createRuntime, META_NAMESPACE, META_PRESETS,
DEFAULT_SETTINGS, accessTokenCredential, the generated document, operationIds,
supportedOperationIds, and their public option/state/event/insight types.
@crvouga/mockingbird-service-meta/server exports
createServer, serveTarget, DEFAULT_PORT, and server option/result types.
Deliberately not modelled
- Real ad delivery, attribution calculation, hashing of plaintext PII, app-secret proof, or OAuth.
- Campaign/ad-set/ad mutation, creatives, audiences, pixels configuration, dashboards, or billing.
- The complete Insights fields/breakdowns matrix and asynchronous report jobs.
- Meta-side probabilistic matching: the emulator records only the supplied synthetic hashed fields.