@crvouga/mockingbird-service-sentry 0.1.0

package/CHANGELOG.md

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

package/DISCOVERY.md

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

package/README.md

@@ -0,0 +1,166 @@
+# @crvouga/mockingbird-service-sentry
+
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+A stateful Sentry SDK transport and event/issue assertion mock. This initial package is **wip**:
+its bounded surface follows the official envelope protocol and Relay responses, not the entire
+Sentry product. No vendor account, container, secret or outbound call is needed for tests.
+
+## Install
+
+```sh
+bun add -d @crvouga/mockingbird-service-sentry
+```
+
+## Usage
+
+```ts
+import { createRuntime, DEFAULT_PROJECT } from "@crvouga/mockingbird-service-sentry"
+
+const sentry = createRuntime()
+const response = await sentry.fetch(new Request(
+  `http://sentry.local/api/1/store/?sentry_key=${DEFAULT_PROJECT.publicKey}&sentry_version=7`,
+  { method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ message: "Fixture failure", fingerprint: ["fixture-group"] }) },
+))
+console.log(response.status) // 200
+```
+
+For the official `@sentry/nextjs` or `@sentry/node` SDK, start `createServer()` from the `/server`
+entry and set `SENTRY_DSN` to `http://<DEFAULT_PROJECT.publicKey>@127.0.0.1:<port>/1`, or give that
+DSN to `init`/`NodeClient`. Both SDKs are tested at **11.4.0** (the report supplied no pinned version).
+Use SDK `flush()` to finish submission, then `POST /__admin/flush {"eventIds": […], "count": n}`
+for an immediate assertion: `flushed: false` means the condition is not met; it never sleeps.
+
+REST requests use `Authorization: Bearer fixture-rest-token`. `projects` and `restTokens` options
+replace these constructor fixtures. Each project includes its organization, numeric-string ID,
+slug, name and 32-hex public key. The defaults are obviously synthetic. Each namespace receives
+its own constructor fixtures and returns to them on reset.
+
+```sh
+mockingbird-sentry serve --port 8810
+```
+
+## Routes and behavior
+
+- `POST /api/{project}/envelope/`: byte-accurate envelope parsing, implicit or explicit lengths,
+  UTF-8 JSON headers, binary attachments, unknown item retention, event/transaction/session/
+  sessions/client-report items. Gzip/deflate request compression is supported. Responses are
+  `200 {"id": "<event ID>"}` when an ID applies, or `200 {}` for session/report-only envelopes.
+- `POST /api/{project}/store/`: JSON event ingestion; generates a deterministic 32-hex event ID
+  when absent. Legacy `message: false` is accepted and ignored, matching Relay LogEntry; raw
+  input attributes cannot overwrite normalized REST fields. Event IDs dedupe per project, including concurrent retries: a replay returns the
+  same ID without a second capture, issue count or attachment.
+- `POST /api/{project}/minidump/`: raw native minidump or multipart `upload_file_minidump`, optional
+  `sentry` JSON and additional files. Returns the hyphenated event UUID as plain text, like Relay.
+  Validates the MDMP/PMDM magic and retains bytes; native crash symbolication is not simulated.
+- `GET /api/0/projects/{organization}/{project}/events/`: error events newest first, bare array,
+  `full=true` caps a page at 10. Transactions remain available in event detail and admin search.
+- `GET /api/0/projects/{organization}/{project}/events/{event}/`: event ID, message/title,
+  exception/stacktrace entries, contexts, breadcrumbs, tags and fixture user identity.
+- `GET /api/0/projects/{organization}/{project}/issues/`: bare-array groups; defaults to
+  `is:unresolved`, `query=` includes all statuses. Explicit fingerprints take priority; fallback
+  grouping is deterministically based on exception title/frames, or message when configured.
+- `GET`/`PUT /api/0/issues/{issue}/` and `/api/0/organizations/{organization}/issues/{issue}/`:
+  read or set `status` to `unresolved`, `resolved`, or `ignored`. Resolving persists until an
+  explicit status update; automatic regression detection is outside this initial mock.
+- `GET /api/0/projects/{organization}/{project}/events/{event}/attachments/` and `/{attachment}/`:
+  attachment metadata; `?download=1` on detail returns the original bytes to the authenticated caller.
+
+Read pagination uses `limit` (1–100), `cursor=0:<offset>:<previous flag>` and Sentry's `Link`
+header with both `rel="previous"` and `rel="next"`, their cursors, and `results="true|false"`.
+Stable insertion order avoids duplicates when walking a fixed result set. Links preserve filters
+and the selected namespace, including a custom admin prefix. The mock supports release/tag/trace
+and status filters; production search syntax, sampling, trend/rank sorting and statistics are
+not silently represented as implemented features (see boundaries below).
+
+Ingest auth accepts `X-Sentry-Auth: Sentry sentry_key=…, sentry_version=7`, query `sentry_key`
+with optional `sentry_version`, or a self-authenticated envelope DSN. Conflicting header/query
+credentials, missing auth, malformed keys, incompatible protocol versions, bad envelopes and
+unknown project keys receive Relay-shaped `{"detail": "…"}` errors. There is no invented generic
+API error code or request ID: the ingest response's `id` is the vendor event identifier. Exact
+production quota, filter-reason details and REST error text beyond the documented cases are bounded
+approximations. The default payload ceiling is 20 MiB, configurable with `maxPayloadBytes`.
+
+## Test controls
+
+All internal endpoints move together with `adminPrefix` (default `/__admin`). Namespace carriers:
+`x-mockingbird-namespace`, `/__admin/ns/<suite>/…`, or DSN query/header credentials and REST tokens
+mapped with `PUT /__admin/credentials`. Self-authenticated envelope-only DSNs use header/path
+namespaces; credential mapping cannot inspect a body before the shared runtime selects a namespace.
+Clock, reset, Timeline checkpoints/branches and snapshot aliases, request journal, metrics, admin
+UI, collection introspection and generic faults are the shared service contract.
+
+- `GET /__admin/events?project=1&release=…&tag=key:value&trace=…`: normalized captured errors and
+  transactions. All listed fields, timestamps, fingerprints, tags, contexts and breadcrumbs survive
+  subject to redaction; `user` retains only the fake fixture `id`.
+- `GET /__admin/issues`: matching groups with current resolution state, using the same filters.
+- `GET /__admin/envelopes?project=1`: item/header metadata and rejection flags; never raw bytes.
+- `GET`/`PUT /__admin/settings`: `grouping: "exception"|"message"`, `sensitivePaths` (dot paths;
+  defaults `request.data`, `request.cookies`) and `rejectItems` (types to discard while accepting
+  other items with 200). These are synthetic controls, not public Sentry settings APIs.
+- `POST /__admin/flush {eventIds?, count?, project?}`: immediate capture condition/result.
+- `POST /__admin/issues/{id}/status {status}`: resolve/reopen/ignore.
+- `POST /__admin/projects/{id}/clear`: clear that project's telemetry while retaining its fixture.
+
+Presets: `rate_limited` (429, `Retry-After: 60`, `X-Sentry-Rate-Limits: 60:error:organization`),
+`server_error` (503), `network_reset` (socket drop) and `item_rejected` (synthetic 403 filter).
+Each is scoped to ingestion and operates before writes. Generic faults can force other 5xx/429
+responses. The official SDK test proves error-category quotas drop further errors without blocking
+transactions. It verifies behavior immediately, without retry sleeps.
+
+### Raw capture and redaction
+
+Authorization/cookies and credential-named fields are filtered recursively, including header
+pairs. Configured sensitive body paths are filtered before normalized data enters storage or
+vendor/admin diagnostics. Personal email, name and IP attributes are dropped. Journals/log sinks
+contain request metadata and resource IDs only, never bodies, headers or attachment bytes.
+Raw wire bodies and attachment bytes are retained **encrypted with AES-GCM** in ordinary Collections,
+so reset/Timeline cover them without disclosing plaintext through generic state diagnostics.
+`runtime.instance(namespace).rawEnvelope(id)` is explicit programmatic owner access to original
+wire bytes; it is not exposed by an admin HTTP route. Supply a `captureKey` from `createCaptureKey()`
+when reopening persistent SQLite storage; the default key lives only for that runtime's lifetime.
+Treat this explicit raw access as sensitive test-owner access. Normal event/detail/search paths
+return redacted data, while authenticated attachment download is an explicit byte retrieval.
+
+## Oracle evidence
+
+- [Official envelope grammar and item rules](https://develop.sentry.dev/sdk/foundations/envelopes/).
+- [Official transport rate limits](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting/).
+- [Official pagination headers and cursor examples](https://docs.sentry.io/api/pagination/).
+- [Project event list](https://docs.sentry.io/api/events/list-a-projects-error-events/),
+  [project issue list](https://docs.sentry.io/api/events/list-a-projects-issues/) and
+  [issue detail](https://docs.sentry.io/api/events/retrieve-an-issue/).
+- [Relay envelope response](https://github.com/getsentry/relay/blob/c4e9930349068039dd6ecd06cf338c527ee90165/relay-server/src/endpoints/envelope.rs),
+  [auth status/messages](https://github.com/getsentry/relay/blob/c4e9930349068039dd6ecd06cf338c527ee90165/relay-server/src/extractors/request_meta.rs),
+  [ingest errors, quota headers and minidump response](https://github.com/getsentry/relay/blob/c4e9930349068039dd6ecd06cf338c527ee90165/relay-server/src/endpoints/common.rs).
+- [Relay legacy message normalization](https://github.com/getsentry/relay/blob/c4e9930349068039dd6ecd06cf338c527ee90165/relay-event-schema/src/protocol/logentry.rs) explicitly ignores `message: false`; its CI-discovered seed is retained in the regression registry.
+- Official npm SDK source for `@sentry/node`, `@sentry/core` and `@sentry/nextjs` 11.4.0; served
+  tests use the actual clients and transport, not a reimplementation of SDK quota handling.
+
+`bun run parity:service -- sentry` requires `SENTRY_API_URL`, `SENTRY_AUTH_TOKEN`,
+`SENTRY_ORGANIZATION_SLUG`, `SENTRY_PROJECT_ID` and `SENTRY_PROJECT_SLUG`. The runner compares only
+safe reads and never submits to a live vendor. Tests need none of these keys. Live parity has not
+been claimed without access; docs and SDK source are the initial oracle.
+
+## Deliberately not modelled
+
+Vendor dashboards/billing, full organization/project/release management, production quotas,
+complete search DSL and search time windows, sort modes other than newest/last-seen, statistical
+series/sampling, source-map/native symbolication, sessions aggregate analytics, profiling/replays,
+full crash dump validation, legacy compressed-base64 store ingestion, automatic issue regressions,
+alert-rule evaluation or optional issue-alert webhooks. Unknown envelope items are retained, not
+processed as unsupported product features. Group fallback rules and forced filter behavior are
+explicit deterministic test policies, not Sentry's production grouping algorithm. Issues are
+explicitly resolved/reopened by controls or vendor PUT, and never invent asynchronous workers.
+
+## API
+
+Main entry runtime exports: `SentryAPI` (`fetch`, `reset`, `rawEnvelope`, `captured`, `issueWire`,
+`sqlite`, `state`, `app`), `createRuntime`, `SENTRY_NAMESPACE`, `SENTRY_PRESETS`, `DEFAULT_PROJECT`,
+`createCaptureKey`, `sentryCredential`, `document` and `supportedOperationIds`.
+Types include `SentryAPIOptions`, `SentryRuntime`, `SentryRuntimeOptions`, `ProjectFixture`,
+`SentrySettings`, `CapturedEvent`, `CapturedEnvelope`, and `IssueRecord`.
+Server entry runtime exports: `createServer`, `DEFAULT_PORT`, `serveTarget`. Server types:
+`SentryServer`, `SentryServerOptions`. `createServer` returns `{url, runtime, close, …}`; close the
+server after each test. The CLI entry runs `serve` with the common host/port/admin-prefix options.

package/SUPPORT.md

@@ -0,0 +1,22 @@
+# Sentry transport and event API — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **12**
+- supported by the mock: **12**
+- parity enabled: **10**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `IngestEnvelope` | `POST /api/{project}/envelope/` | ✅ supported | ❌ disabled | Envelope byte lengths and mixed binary items require the dedicated official SDK and codec acceptance tests. |
+| `StoreEvent` | `POST /api/{project}/store/` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `IngestMinidump` | `POST /api/{project}/minidump/` | ✅ supported | ❌ disabled | Native minidump and multipart bodies require the dedicated served binary tests. |
+| `ListProjectEvents` | `GET /api/0/projects/{organization}/{project}/events/` | ✅ supported | ✅ |  |
+| `GetProjectEvent` | `GET /api/0/projects/{organization}/{project}/events/{event}/` | ✅ supported | ✅ |  |
+| `ListProjectIssues` | `GET /api/0/projects/{organization}/{project}/issues/` | ✅ supported | ✅ |  |
+| `GetIssue` | `GET /api/0/issues/{issue}/` | ✅ supported | ✅ |  |
+| `UpdateIssue` | `PUT /api/0/issues/{issue}/` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetOrganizationIssue` | `GET /api/0/organizations/{organization}/issues/{issue}/` | ✅ supported | ✅ |  |
+| `UpdateOrganizationIssue` | `PUT /api/0/organizations/{organization}/issues/{issue}/` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `ListEventAttachments` | `GET /api/0/projects/{organization}/{project}/events/{event}/attachments/` | ✅ supported | ✅ |  |
+| `GetEventAttachment` | `GET /api/0/projects/{organization}/{project}/events/{event}/attachments/{attachment}/` | ✅ supported | ✅ |  |