@crvouga/mockingbird-service-vibe 0.1.0

package/CHANGELOG.md

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

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-vibe discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-vibe/`; 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: **OAuth and asynchronous JSON reports**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- vibe`.
+- 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: `vibe`.

package/README.md

@@ -0,0 +1,95 @@
+# @crvouga/mockingbird-service-vibe
+
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+WIP Vibe revision **2026-06-01** OAuth and asynchronous campaign-spend reports.
+
+## Install
+
+```sh
+bun add @crvouga/mockingbird-service-vibe
+```
+
+## Usage
+
+```ts
+import { createRuntime, DEFAULT_ADVERTISER } from "@crvouga/mockingbird-service-vibe"
+const vibe = createRuntime({ rows: [{
+  advertiser_id: DEFAULT_ADVERTISER, impression_date: "2026-01-01", spend: "12.50",
+}] })
+const response = await vibe.fetch(new Request("http://vibe.test/reports", {
+  method: "POST",
+  headers: { authorization: "Bearer mock_vibe_token", "x-vibe-revision": "2026-06-01", "content-type": "application/json" },
+  body: JSON.stringify({ start_date: "2026-01-01", end_date: "2026-01-02", advertiser_ids: [DEFAULT_ADVERTISER], dimensions: ["impression_date"], metrics: ["spend"] }),
+}))
+const report = await response.json()
+console.log(report.id, report.status)
+```
+
+Run `mockingbird-vibe serve --port 12128`, then inject `http://localhost:12128` as the
+consumer's API origin. Downloads point at this same origin. There is no universal vendor
+environment variable for that override; keep the consumer's production HTTPS policy intact.
+
+### Contract
+
+- `POST /oauth2/token`: form-encoded client_credentials with HTTP Basic credentials.
+  Default synthetic client is mock_client / mock_client_secret. Optional scope must be a
+  subset of the client's scopes. Response includes bearer token, scope and expires_in.
+  This endpoint does not require X-Vibe-Revision; failures use the standard OAuth envelope.
+- `POST /reports`: JSON report request, Bearer token and pinned revision. Returns 201
+  with UUID/status/created_at. Advertisers must belong to the client. Windows are start-inclusive,
+  end-exclusive, positive and at most 45 days. JSON/DAY fixtures only.
+- `GET /reports/{report_id}`: only the owning client can poll. Default clock progression:
+  CREATED initially, PROCESSING at one second, READY at two seconds. READY includes the
+  local download_url and generation/expiration timestamps; FAILED includes failure_reason.
+- Internal `/__admin/blobs/{id}?token=…`: local stand-in for the vendor's pre-signed download.
+  Returns a JSON array of synthetic rows, preserves numeric-as-string metrics and nulls,
+  and expires 24 hours after generation. Capability values are deterministic test stand-ins,
+  not production signing. No browser tracking or real campaign data is fetched.
+
+Seed `clients`, pre-aggregated `rows` and `settings` through constructor options or shared
+`/__admin/state`. Reports retain fixture rows at creation time and select requested columns.
+Fixture dates are already in the requested reporting timezone; no attribution or aggregation
+engine is implied. Default bearer mock_vibe_token is valid for one hour from initial seeding.
+
+### Test controls
+
+Collections: clients, tokens, rows, reports, settings. Settings expose processingMs, readyMs
+and tokenTtlSeconds. Reports expose readyAt (null means stuck), failure and missingArtifact.
+Use the shared clock to advance lifecycle/expiry, and shared Timeline/reset/state/journal APIs.
+Reset restores constructor fixtures. Journals contain metadata, never report rows or credentials.
+Namespaces work by header, mapped bearer token or `/__admin/ns/{name}` path. Download links
+retain namespace and custom `adminPrefix` routing.
+
+Presets: rate_limited (scripted 429/Retry-After), server_error (500), connection_drop,
+report_failed and report_stuck. Shared fault rules also provide deterministic latency.
+These are test controls; they do not model a real sliding-window quota or actual processing SLA.
+No webhooks are needed for this subset.
+
+Acceptance tests exercise all four issue #271 behaviors, OAuth expiry/scope, local artifact
+expiry/missing files, namespaces/reset/redacted journals and served HTTP. Property tests run
+every parity-enabled operation and detect divergence. `bun scripts/parity.ts` uses
+VIBE_ACCESS_TOKEN and VIBE_REPORT_ID for a read-only existing-report envelope check; live
+authenticated parity has not run. `bun scripts/parity.ts --unauthenticated` compares missing/
+invalid synthetic-token errors against the real endpoint. This probe passed and confirms
+`token_invalid` plus `WWW-Authenticate: Bearer`, differing from the documentation's
+`invalid_token` example. The rest of the contract follows the published OpenAPI reference.
+
+### Deliberately not modelled
+
+Ad purchases, campaign mutation, attribution inference, production JWT signing, OAuth browser
+consent/refresh, CSV or non-DAY reports, metric aggregation, timezone conversion, and report
+filter expressions. Seed already-aggregated rows for the requested dimensions. The mock
+rejects CSV/non-DAY requests even though the vendor supports them; those are outside this
+initial consumer subset. It does not claim full vendor API or live rate-limit parity.
+
+## API
+
+- `VibeAPI`: FetchAPI, reset and state collections.
+- `createRuntime`: shared admin/namespace/clock/fault surface.
+- `VIBE_NAMESPACE`, `VIBE_PRESETS`, `DEFAULT_ADVERTISER`: service constants.
+- `document`, `operationIds`, `supportedOperationIds`: generated contract metadata.
+- `createServer`, `serveTarget`, `DEFAULT_PORT` from `./server`: Node HTTP/CLI entry points.
+
+Public types: Client, Token, Row, Report, Settings, VibeAPIOptions, OperationId,
+SupportedOperationId; server types are VibeServerOptions and VibeServer.

package/SUPPORT.md

@@ -0,0 +1,14 @@
+# Vibe Public API — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **4**
+- supported by the mock: **4**
+- parity enabled: **3**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `CreateReport` | `POST /reports` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetReport` | `GET /reports/{report_id}` | ✅ supported | ✅ |  |
+| `OAuthToken` | `POST /oauth2/token` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `DownloadReport` | `GET /__admin/blobs/{id}` | ✅ supported | ❌ disabled | Mock-only capability URL; exercised by acceptance tests. |