emulate 0.1.1 → 0.2.0

package/README.md

@@ -49,6 +49,65 @@ emulate list
 
 The port can also be set via `EMULATE_PORT` or `PORT` environment variables.
 
+## Programmatic API
+
+```bash
+npm install emulate
+```
+
+Each call to `createEmulator` starts a single service:
+
+```typescript
+import { createEmulator } from 'emulate'
+
+const github = await createEmulator({ service: 'github', port: 4001 })
+const vercel = await createEmulator({ service: 'vercel', port: 4002 })
+
+github.url   // 'http://localhost:4001'
+vercel.url   // 'http://localhost:4002'
+
+await github.close()
+await vercel.close()
+```
+
+### Vitest / Jest setup
+
+```typescript
+// vitest.setup.ts
+import { createEmulator, type Emulator } from 'emulate'
+
+let github: Emulator
+let vercel: Emulator
+
+beforeAll(async () => {
+  ;[github, vercel] = await Promise.all([
+    createEmulator({ service: 'github', port: 4001 }),
+    createEmulator({ service: 'vercel', port: 4002 }),
+  ])
+  process.env.GITHUB_URL = github.url
+  process.env.VERCEL_URL = vercel.url
+})
+
+afterEach(() => { github.reset(); vercel.reset() })
+afterAll(() => Promise.all([github.close(), vercel.close()]))
+```
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `service` | *(required)* | Service to emulate: `'github'`, `'vercel'`, or `'google'` |
+| `port` | `4000` | Port for the HTTP server |
+| `seed` | none | Inline seed data (same shape as YAML config) |
+
+### Instance methods
+
+| Method | Description |
+|--------|-------------|
+| `url` | Base URL of the running server |
+| `reset()` | Wipe the store and replay seed data |
+| `close()` | Shut down the HTTP server, returns a Promise |
+
 ## Configuration
 
 Configuration is optional. To customize seed data, create `emulate.config.yaml` in your project root (or pass `--seed`):

package/dist/api.d.ts

@@ -0,0 +1,33 @@
+import * as _internal_core from '@internal/core';
+import { VercelSeedConfig } from '@internal/vercel';
+import { GitHubSeedConfig } from '@internal/github';
+import { GoogleSeedConfig } from '@internal/google';
+
+declare const SERVICE_PLUGINS: {
+    readonly vercel: _internal_core.ServicePlugin;
+    readonly github: _internal_core.ServicePlugin;
+    readonly google: _internal_core.ServicePlugin;
+};
+type ServiceName = keyof typeof SERVICE_PLUGINS;
+interface SeedConfig {
+    tokens?: Record<string, {
+        login: string;
+        scopes?: string[];
+    }>;
+    vercel?: VercelSeedConfig;
+    github?: GitHubSeedConfig;
+    google?: GoogleSeedConfig;
+}
+interface EmulatorOptions {
+    service: ServiceName;
+    port?: number;
+    seed?: SeedConfig;
+}
+interface Emulator {
+    url: string;
+    reset(): void;
+    close(): Promise<void>;
+}
+declare function createEmulator(options: EmulatorOptions): Promise<Emulator>;
+
+export { type Emulator, type EmulatorOptions, type SeedConfig, type ServiceName, createEmulator };