@crvouga/mockingbird-service-meta 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-meta
+
+## 0.1.0 (2026-10-05)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-meta discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-meta/`; no repository checkout is needed to discover the mock's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Conversions events and marketing insights**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- meta`.
+- Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `meta`.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @crvouga/mockingbird-service-meta
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+Stateful Meta Graph v26 mock 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
+
+```bash
+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 mock. Any non-empty synthetic Bearer token or
+`access_token` query value authenticates unless `/__admin/settings` restricts tokens.
+
+```ts
+import { createRuntime } from "@crvouga/mockingbird-service-meta"
+
+const meta = createRuntime()
+const response = await meta.fetch(new Request("http://meta.test/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 },
+  }] }),
+}))
+// → {events_received: 1, messages: [], fbtrace_id: "trace_…"}
+```
+
+### 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 mock records only the supplied synthetic hashed fields.

package/SUPPORT.md

@@ -0,0 +1,13 @@
+# Meta Marketing and Conversions APIs (Mockingbird subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **3**
+- supported by the mock: **3**
+- parity enabled: **2**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `PostPixelEvents` | `POST /v26.0/{pixel_id}/events` | ✅ supported | ❌ disabled | Sends conversion events to a real pixel |
+| `GetInsights` | `GET /v26.0/{account_id}/insights` | ✅ supported | ✅ |  |
+| `GetMarketingObject` | `GET /v26.0/{object_id}` | ✅ supported | ✅ |  |