api-emulator 0.5.1 → 0.6.0

package/README.md

@@ -1,112 +1,130 @@
 <p align="center">
-  <img src="./.README/cover.png" alt="api-emulator" width="1024" />
+  <img src="https://raw.githubusercontent.com/jsj/api-emulator/main/.README/cover.png" alt="api-emulator" width="1024" />
 </p>
 
 <h1 align="center">api-emulator</h1>
 
-<p align="center">
-  Local API emulators you can run, share, and extend with plugins
-</p>
+<p align="center">Fake real APIs locally so your app can test integrations without touching production, sandboxes, or someone else's server.</p>
 
-api-emulator runs local, stateful API emulators for development, CI, and no-network sandboxes. The core package is a runtime plus a default plugin catalog; teams can load public, shared, or private provider-shaped plugins without forking the runtime.
+`api-emulator` is a local app store for fake APIs. Run GitHub, Stripe, Resend, and plugin powered providers on localhost, seed state, inspect behavior, reset data, and test your app in one place.
 
-## Install
+## Why use it?
 
-```bash
-npm install api-emulator
-```
+- Test API integrations locally without real provider credentials.
+- Run multiple fake services together, with shared state, auth, webhooks, seed data, and resets.
+- Keep provider behavior in plugins so public, private, and internal APIs can live outside your app.
 
-For one-off CLI usage:
+## Quick start
 
 ```bash
-npx api-emulator
+npx -p api-emulator api
+npx -p api-emulator api --service github,stripe,resend
 ```
 
-No API keys, Docker daemon, or external sandbox accounts are required for the default plugin catalog.
-
-## CLI
+Then point your app at the local provider URLs:
 
-```bash
-# Start the default plugin catalog
-npx api-emulator
-
-# Start a subset
-npx api-emulator --service github,stripe,resend
-
-# Start on trusted local HTTPS names
-npx api-emulator --portless
-
-# Load a seed file
-npx api-emulator --seed api-emulator.config.yaml
+```text
+http://localhost:4000/github
+http://localhost:4000/stripe
+http://localhost:4000/resend
+```
 
-# Generate a starter config
-npx api-emulator init
+Use trusted local HTTPS names when your app needs browser compatible origins:
 
-# List default and external plugins
-npx api-emulator list
+```bash
+npx -p api-emulator api --service github,stripe,resend --portless
 ```
 
-With `--portless`, each service gets a named local HTTPS URL:
-
 ```text
-GitHub        https://github.api-emulator.localhost
-Stripe        https://stripe.api-emulator.localhost
-Resend        https://resend.api-emulator.localhost
-AWS           https://aws.api-emulator.localhost
+https://github.api-emulator.localhost
+https://stripe.api-emulator.localhost
+https://resend.api-emulator.localhost
 ```
 
-The CLI reads `API_EMULATOR_PORT`, `API_EMULATOR_BASE_URL`, and `PORTLESS_URL`. It also accepts `EMULATE_PORT`, `EMULATE_BASE_URL`, and `emulate.config.*` names as migration compatibility aliases.
+Create starter config and list available services:
 
-## Canonical API
+```bash
+npx -p api-emulator api init
+npx -p api-emulator api list
+```
 
-Prefer the programmatic runtime when writing tests:
+## Use in tests
 
 ```ts
 import { createEmulator } from 'api-emulator'
 
 const github = await createEmulator({ service: 'github', port: 4001 })
-
 process.env.GITHUB_API_BASE = github.url
 
 afterEach(() => github.reset())
 afterAll(() => github.close())
 ```
 
-Each emulator instance exposes:
+Capture and replay a stable fixture after a stochastic or stateful run:
+
+```ts
+const fixture = github.exportFixture({ metadata: { name: 'pull-request-flow' } })
 
-- `url` for the advertised base URL
-- `reset()` to wipe state and replay seed data
-- `close()` to stop the local server
+github.resetToFixture(fixture)
+```
 
 ## Plugins
 
-api-emulator is designed around a small runtime spine and provider-shaped plugins. The default providers are loaded from `packages/emulate/src/default-plugin-catalog.ts`; external plugin modules are normalized by `packages/emulate/src/external-plugin-adapter.ts`.
+Install more providers from a public or internal plugin shelf:
 
-Public external plugins live at [`jsj/api-emulator-plugins`](https://github.com/jsj/api-emulator-plugins). Private teams can keep the same shape in internal repos.
+```bash
+npx -p api-emulator api install posthog
+npx -p api-emulator api install pepper --no-package-manager
+```
+
+Or load a plugin file directly:
 
 ```bash
-npx api-emulator --plugin ./api-emulator-plugins/@posthog/api-emulator.mjs --service posthog
-npx api-emulator --plugin ./api-emulator-plugins/@github/api-emulator.mjs,./api-emulator-plugins/@apple/api-emulator.mjs
+npx -p api-emulator api --plugin ./api-emulator-plugins/@posthog/api-emulator.mjs --service posthog
 ```
 
+The installer auto discovers sibling `api-emulator-plugins` and `api-emulator-internal` checkouts. Set `API_EMULATOR_PLUGIN_CATALOGS=/path/to/shelf,/path/to/internal` to add more shelves.
+
 A plugin exports a `ServicePlugin`:
 
 ```ts
-import type { ServicePlugin } from '@emulators/core'
+import type { ServicePlugin } from '@api-emulator/core'
 
 export const plugin: ServicePlugin = {
   name: 'internal-billing',
-  register(app, store, webhooks, baseUrl) {
+  register(app) {
     app.get('/v1/customers', (c) => c.json({ data: [] }))
   },
 }
 ```
 
-Plugins can also export `label`, `endpoints`, `initConfig`, `seedFromConfig`, and `defaultFallback`. The runtime keeps plugin lifecycle in one service-runtime module, so CLI and programmatic usage share the same seed, reset, token, and close behavior.
+## Next.js embedded mode
+
+```bash
+npm install @api-emulator/adapter-next @api-emulator/core
+```
+
+```ts
+import { createApiEmulatorHandler } from '@api-emulator/adapter-next'
+import type { ServicePlugin } from '@api-emulator/core'
+
+const internalPlugin: ServicePlugin = {
+  name: 'internal',
+  register(app) {
+    app.get('/health', (c) => c.json({ ok: true }))
+  },
+}
+
+export const { GET, POST, PUT, PATCH, DELETE } = createApiEmulatorHandler({
+  services: {
+    internal: { emulator: { plugin: internalPlugin } },
+  },
+})
+```
 
 ## Configuration
 
-`api-emulator init` creates `api-emulator.config.yaml`.
+`npx -p api-emulator api init` creates `api-emulator.config.yaml`.
 
 ```yaml
 tokens:
@@ -118,92 +136,19 @@ github:
   users:
     - login: octocat
       name: The Octocat
-      email: octocat@github.com
-  repos:
-    - owner: octocat
-      name: hello-world
-      auto_init: true
-
-stripe:
-  products:
-    - id: prod_tshirt
-      name: T-shirt
-  prices:
-    - id: price_tshirt
-      product: prod_tshirt
-      unit_amount: 2500
-      currency: usd
-
-resend:
-  apiKeys:
-    - re_test_key
-```
-
-The CLI auto-detects:
-
-- `api-emulator.config.yaml`
-- `api-emulator.config.yml`
-- `api-emulator.config.json`
-- `emulate.config.yaml`
-- `emulate.config.yml`
-- `emulate.config.json`
-- `service-emulator.config.yaml`
-- `service-emulator.config.yml`
-- `service-emulator.config.json`
-
-## Default plugin catalog
-
-api-emulator ships with a default plugin catalog so first run is useful, but these providers are catalog entries rather than hard-coded runtime behavior:
-
-- Vercel API
-- GitHub REST, OAuth, Apps, Actions, checks, statuses, and webhooks
-- Google OAuth, OIDC, Gmail, Calendar, and Drive
-- Slack Web API, OAuth, channels, messages, users, and webhooks
-- Apple Sign in with Apple and OIDC
-- Microsoft Entra ID OAuth and OIDC
-- Okta OAuth and OIDC
-- Clerk auth surfaces
-- AWS S3, SQS, IAM, and STS
-- MongoDB Atlas Admin and Data API
-- Resend email API with local inbox
-- Stripe Checkout, customers, products, prices, payment intents, and webhooks
-
-## Next.js embedded mode
-
-Use `@emulators/adapter-next` to mount emulators inside a Next.js app on the same origin.
-
-```ts
-// app/emulate/[...path]/route.ts
-import { createEmulateHandler } from '@emulators/adapter-next'
-import { githubPlugin } from '@emulators/github'
-import { stripePlugin } from '@emulators/stripe'
-
-export const { GET, POST, PUT, PATCH, DELETE } = createEmulateHandler({
-  plugins: [githubPlugin, stripePlugin],
-})
 ```
 
-This gives local routes like:
+The CLI auto-detects `api-emulator.config.yaml`, `.yml`, and `.json`.
 
-```text
-/emulate/github/login/oauth/authorize
-/emulate/stripe/v1/checkout/sessions
-```
-
-## Production guidance
+## Examples
 
-- Treat emulators as test infrastructure, not production dependencies.
-- Keep real provider credentials out of seed files.
-- Use fake tokens, fake webhook secrets, and local-only API keys.
-- Prefer provider-shaped resource modules over app-specific happy-path stubs.
-- Keep route handlers thin. Put depth in reusable Modules, Interfaces, and adapters.
-- Keep private team plugins outside the public runtime until the interface proves stable.
-- Use inspect and control endpoints for deterministic tests instead of sleeping or polling real systems.
+- [`examples/oauth`](./examples/oauth)
+- [`examples/nextjs-embedded`](./examples/nextjs-embedded)
+- [`examples/resend-magic-link`](./examples/resend-magic-link)
+- [`examples/stripe-checkout`](./examples/stripe-checkout)
 
 ## Development
 
-This monorepo uses Bun.
-
 ```bash
 bun install
 bun run build
@@ -213,61 +158,10 @@ bun run lint
 bun run test
 ```
 
-Release publishing also uses `bun pm pack` before `npm publish` so workspace dependencies resolve in package tarballs.
-
-## Examples
-These examples use the default plugin catalog. For examples of external provider plugins you can load with `--plugin`, see [jsj/api-emulator-plugins](https://github.com/jsj/api-emulator-plugins).
-
-See:
-
-- [`examples/oauth`](./examples/oauth)
-- [`examples/nextjs-embedded`](./examples/nextjs-embedded)
-- [`examples/resend-magic-link`](./examples/resend-magic-link)
-- [`examples/stripe-checkout`](./examples/stripe-checkout)
-
-## Features
-
-- Stateful local provider APIs for development and CI
-- One CLI that can start many providers at predictable ports
-- Trusted local HTTPS names through portless
-- External plugin loading from files or package names through a dedicated adapter seam
-- YAML and JSON seed data
-- Programmatic test API with reset and close hooks
-- Shared core store, auth, persistence, UI, webhooks, and inspect pages
-- Next.js embedded mode for same-origin OAuth and SDK flows
-- Public, shared, default-catalog, and private plugin workflows
-
-## FAQ
-
-<details>
-  <summary>Is this a fork of emulate?</summary>
-
-  Yes. api-emulator is a hard fork with a new identity and a stronger focus on the plugin-spine model: a small runtime plus many provider-shaped plugins.
-</details>
-
-<details>
-  <summary>Why not just mock fetch calls?</summary>
-
-  SDKs, OAuth redirects, webhooks, pagination, retries, XML wire formats, and provider state usually live below your app code. api-emulator runs those protocol surfaces locally so tests exercise the integration seam instead of a shallow stub.
-</details>
-
-<details>
-  <summary>Can teams keep private emulators?</summary>
-
-  Yes. Private and internal plugins are a first-class workflow. Load them with `--plugin`, keep them in a separate repo, and share only the runtime spine publicly.
-</details>
-
-<details>
-  <summary>Does api-emulator still support old emulate config names?</summary>
-
-  Yes. `emulate.config.*`, `EMULATE_PORT`, and `EMULATE_BASE_URL` still work as migration compatibility aliases.
-</details>
-
-<details>
-  <summary>What should a good plugin emulate?</summary>
+## Links
 
-  Provider concepts, not one app's current happy path. Model resources, state transitions, errors, inspect surfaces, and control hooks so multiple products can test against the same plugin.
-</details>
+- [`jsj/api-emulator-plugins`](https://github.com/jsj/api-emulator-plugins)
+- [`api-emulator` on npm](https://www.npmjs.com/package/api-emulator)
 
 ## License
 

package/dist/api.d.ts

@@ -1,5 +1,7 @@
-declare const DEFAULT_PLUGIN_NAME_LIST: readonly ["vercel", "github", "google", "slack", "apple", "microsoft", "okta", "aws", "resend", "stripe", "mongoatlas", "clerk"];
-type ServiceName = (typeof DEFAULT_PLUGIN_NAME_LIST)[number];
+import { StoreSnapshot, FixtureSource, StoreFixtureOptions, StoreFixture } from '@api-emulator/core';
+export { FixtureInteraction, FixtureSource, StoreFixture, StoreFixtureOptions, StoreSnapshot } from '@api-emulator/core';
+
+type ServiceName = string;
 
 interface SeedConfig {
     tokens?: Record<string, {
@@ -18,6 +20,10 @@ interface EmulatorOptions {
 }
 interface Emulator {
     url: string;
+    snapshot(): StoreSnapshot;
+    restore(fixture: FixtureSource): void;
+    exportFixture(options?: StoreFixtureOptions): StoreFixture;
+    resetToFixture(fixture: FixtureSource): void;
     reset(): void;
     close(): Promise<void>;
 }