Mockingbird

Meta

@crvouga/mockingbird-service-meta

Stateful emulator of Meta's Conversions and Marketing APIs: server events, deduplication, campaign objects, insights, pagination and Graph error envelopes.

Parity: Conversions events and marketing insightsMarketing3 of 3 operationsIn-process fetchNode servermockingbird-meta
$
npm install -D @crvouga/mockingbird-service-meta
Source npm MarkdownAgent discoverySUPPORT.md

Playground

Requests go to the real emulator running in this tab. State persists across requests, and the journal shows what it received. A green dot marks operations whose sample succeeds as-is; others need ids from earlier responses.

Loads the real @crvouga/mockingbird-service-meta into this tab on first send
https://graph.facebook.com

Send a request to see the emulator's response.

Operations

3 of 3 operations in the vendored contract are emulated.

MethodPathOperationStatus
POST/v26.0/{pixel_id}/eventsPostPixelEvents
GET/v26.0/{account_id}/insightsGetInsights
GET/v26.0/{object_id}GetMarketingObject

Documentation

The package README, the same file that ships in the npm tarball.Edit on GitHub

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

Shell
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.

TypeScript
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.
↑↓ to navigate↵ to open