@emulates/eventbridge 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — @emulates/eventbridge
+
+## 1.0.0 (2026-10-07)
+
+### ⚠️ Breaking changes
+
+- point the repo at crvouga/emulates ([cdb5e53](https://github.com/crvouga/emulates/commit/cdb5e536ed8c1f52345e3984f089001c25fdb08a))
+
+### Fixes and improvements
+
+- format the emulates records query ([8698872](https://github.com/crvouga/emulates/commit/8698872509d06002be5a8fcdc85d79f8462320c3))
+
+### Dependencies
+
+- `@emulates/sqlite`
+
+## 0.1.1 (2026-10-06)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/eventbridge discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/eventbridge/`; no repository checkout is needed to discover the emulator'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 `emulates.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: **Seeded rule and target discovery with pagination**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- eventbridge`.
+- Evidence model: Run from an Emulates 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 Emulates
+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-emulates-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/emulates/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator 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: `eventbridge`.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @emulates/eventbridge
 
-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.
+> Part of [Emulates](https://github.com/crvouga/emulates): high-fidelity, in-process emulators for APIs and databases.
+
+WIP AWS EventBridge control-plane discovery. Seeded rule and target reads use AWS JSON 1.1;
+no containers or infrastructure are executed. Follows the official
+[ListRules](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_ListRules.html),
+[ListTargetsByRule](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_ListTargetsByRule.html)
+and [common errors](https://docs.aws.amazon.com/eventbridge/latest/APIReference/CommonErrors.html).
+
+## Install
+
+`bun add @emulates/eventbridge`
+
+## Usage
+
+```ts
+import { createServer } from "@emulates/eventbridge/server"
+const server = await createServer({
+  rules: [{ rule: { Name: "nightly", Arn: "arn:aws:events:us-east-1:000000000000:rule/nightly" }, targets: [] }],
+})
+// boto3.client("events", endpoint_url=server.url, region_name="us-east-1",
+//              aws_access_key_id="fixture", aws_secret_access_key="fixture")
+await server.close()
+```
+
+CLI: `emulates-eventbridge serve --port 12128`. Set your client factory's endpoint_url
+or AWS_ENDPOINT_URL_EVENTBRIDGE to that URL. The default instance has no rules.
+POST / dispatches X-Amz-Target AWSEvents.ListRules and AWSEvents.ListTargetsByRule.
+NamePrefix filters names; Limit (1–100) and NextToken paginate rules and targets.
+The terminal page omits NextToken. Missing buses/rules return ResourceNotFoundException (400).
+
+## Controls and state
+
+Seed through options.rules ({rule, targets}) or POST /__admin/state/rules with
+{id: "default:nightly", value: {rule: {Name, Arn}, targets: [{Id, Arn, EcsParameters}]}}.
+Custom buses must also be seeded in options.buses or /__admin/state/buses ({name}).
+The default bus always exists. Rule.EventBusName defaults to default.
+Target objects, including TaskDefinitionArn and awsvpcConfiguration, round-trip without execution.
+State collections: rules, buses, cursors and initialization marker.
+Shared /__admin provides health, state, reset, Timeline checkpoints, clock, journal, metrics and UI.
+Namespaces work via x-emulates-namespace, /__admin/ns/name and SigV4 access-key mappings
+set with PUT /__admin/credentials. No cryptographic signature or IAM evaluation is performed.
+The journal records metadata, not request bodies or credentials.
+
+Presets: access_denied (403), throttled (AWS 400), rate_limited (explicit HTTP 429 fault),
+internal_error (500), connection_drop. Standard faults support deterministic latency.
+No outbound webhooks are emitted.
+
+## Verification
+
+Run `bun test` here for acceptance, JS SDK, self-parity and deliberate divergence tests.
+Run `bun scripts/sdk.ts` with uv installed for the separate pinned boto3 1.43.56
+drop-in/paginator/error proof (uv obtains that exact package; no AWS credentials are needed).
+Live safe empty-prefix discovery: `bun run parity` with EVENTBRIDGE_ACCESS_KEY_ID,
+EVENTBRIDGE_SECRET_ACCESS_KEY, optional EVENTBRIDGE_REGION. Missing credentials exit 2.
+The SDK tests prove client compatibility, not live AWS equivalence.
+
+## Deliberately not modelled
+
+Rule/target mutation, event delivery, schedules, IAM policy evaluation, cryptographic SigV4
+validation, real execution, provisioning and deployment. Seeded resources are fixtures, not
+AWS accounts. Cursor strings and their one-hour emulator-clock lifetime are deterministic local
+stand-ins; AWS does not document a fixed lifetime or wire token format. Pagination binds
+arguments but does not freeze a snapshot of concurrent fixture edits. Result order is fixture
+insertion order, not a guarantee about AWS ordering. HTTP 429 is a test fault, not the normal
+EventBridge throttling status.
+
+## API
+
+- `EventbridgeAPI`, `createAwsRuntime`, and `createAwsServer` (server entry): separate extended AWS operations runtime.
+
+Main exports: EventBridgeAPI, EVENTBRIDGE_NAMESPACE, createRuntime, EVENTBRIDGE_PRESETS,
+document, operationIds, supportedOperationIds.
+Types: Rule, Target, SeedRule, EventBridgeAPIOptions, EventBridgeRuntimeOptions, EventBridgeRuntime.
+Server entry: createServer, DEFAULT_PORT, serveTarget; type EventBridgeServerOptions.
+CLI entry runs the serve command and exports no runtime values.
+
+## Extended AWS operations runtime
+
+`createAwsRuntime` (and `createAwsServer` from the server entry) exposes the additional LocalStack-oriented event bus, rule, target, event ingestion and tagging operations. It has separate state and does not claim the seeded discovery runtime's pagination behavior. The default `createRuntime` retains the documented discovery contract and fixtures. Both modes remain WIP. Run `bun run parity:localstack` for the extended runtime.

package/SUPPORT.md

@@ -0,0 +1,11 @@
+# AWS EventBridge discovery — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **1**
+- supported by the emulator: **1**
+- parity enabled: **1**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `EventBridgeRpc` | `POST /` | ✅ supported | ✅ |  |