emulate 0.1.1 → 0.3.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`):
@@ -95,6 +154,40 @@ google:
       client_secret: GOCSPX-secret
       redirect_uris:
         - http://localhost:3000/api/auth/callback/google
+  labels:
+    - id: Label_ops
+      user_email: testuser@example.com
+      name: Ops/Review
+      color_background: "#DDEEFF"
+      color_text: "#111111"
+  messages:
+    - id: msg_welcome
+      user_email: testuser@example.com
+      from: welcome@example.com
+      to: testuser@example.com
+      subject: Welcome to the Gmail emulator
+      body_text: You can now test Gmail, Calendar, and Drive flows locally.
+      label_ids: [INBOX, UNREAD, CATEGORY_UPDATES]
+  calendars:
+    - id: primary
+      user_email: testuser@example.com
+      summary: testuser@example.com
+      primary: true
+      selected: true
+      time_zone: UTC
+  calendar_events:
+    - id: evt_kickoff
+      user_email: testuser@example.com
+      calendar_id: primary
+      summary: Project Kickoff
+      start_date_time: 2025-01-10T09:00:00.000Z
+      end_date_time: 2025-01-10T09:30:00.000Z
+  drive_items:
+    - id: drv_docs
+      user_email: testuser@example.com
+      name: Docs
+      mime_type: application/vnd.google-apps.folder
+      parent_ids: [root]
 ```
 
 ## OAuth & Integrations
@@ -145,6 +238,8 @@ github:
         contents: read
         issues: write
       events: [push, pull_request]
+      webhook_url: "http://localhost:3000/webhooks/github"
+      webhook_secret: "my-secret"
       installations:
         - installation_id: 100
           account: my-org
@@ -153,6 +248,10 @@ github:
 
 JWT authentication: sign a JWT with `{ iss: "<app_id>" }` using the app's private key (RS256). The emulator verifies the signature and resolves the app.
 
+**App webhook delivery**: When events occur on repos where a GitHub App is installed, the emulator mirrors real GitHub behavior:
+- All webhook payloads (including repo and org hooks) include an `installation` field with `{ id, node_id }`.
+- If the app has a `webhook_url`, the emulator delivers the event there with the `installation` field and (if configured) an `X-Hub-Signature-256` header signed with `webhook_secret`.
+
 ## Vercel API
 
 Every endpoint below is fully stateful with Vercel-style JSON responses and cursor-based pagination.
@@ -322,26 +421,47 @@ Every endpoint below is fully stateful. Creates, updates, and deletes persist in
 - `GET /zen` - random zen phrase
 - `GET /versions` - API versions
 
-## Google API
+## Google OAuth + Gmail, Calendar, and Drive APIs
 
-OAuth 2.0 and OpenID Connect emulation.
+OAuth 2.0, OpenID Connect, and mutable Google Workspace-style surfaces for local inbox, calendar, and drive flows.
+This stays under a single `google:` service because the Gmail API is used by both consumer Google accounts and Google Workspace accounts. A separate Workspace-specific service would only make sense once we add admin or tenant-level APIs that do not belong in the basic Google/Gmail emulator.
 
 - `GET /o/oauth2/v2/auth` - authorization endpoint
-- `POST /oauth2/v4/token` - token exchange
+- `POST /oauth2/token` - token exchange
 - `GET /oauth2/v2/userinfo` - get user info
 - `GET /.well-known/openid-configuration` - OIDC discovery document
 - `GET /oauth2/v3/certs` - JSON Web Key Set (JWKS)
+- `GET /gmail/v1/users/:userId/messages` - list messages with `q`, `labelIds`, `maxResults`, and `pageToken`
+- `GET /gmail/v1/users/:userId/messages/:id` - fetch a Gmail-style message payload in `full`, `metadata`, `minimal`, or `raw` formats
+- `GET /gmail/v1/users/:userId/messages/:messageId/attachments/:id` - fetch attachment bodies
+- `POST /gmail/v1/users/:userId/messages/send` - create sent mail from `raw` MIME or structured fields
+- `POST /gmail/v1/users/:userId/messages/import` - import inbox mail
+- `POST /gmail/v1/users/:userId/messages` - insert a message directly
+- `POST /gmail/v1/users/:userId/messages/:id/modify` - add/remove labels on one message
+- `POST /gmail/v1/users/:userId/messages/batchModify` - add/remove labels across many messages
+- `POST /gmail/v1/users/:userId/messages/:id/trash` and `POST /gmail/v1/users/:userId/messages/:id/untrash`
+- `GET /gmail/v1/users/:userId/drafts`, `POST /gmail/v1/users/:userId/drafts`, `GET /gmail/v1/users/:userId/drafts/:id`, `PUT /gmail/v1/users/:userId/drafts/:id`, `POST /gmail/v1/users/:userId/drafts/:id/send`, `DELETE /gmail/v1/users/:userId/drafts/:id`
+- `POST /gmail/v1/users/:userId/threads/:id/modify` - add/remove labels across a thread
+- `GET /gmail/v1/users/:userId/threads` and `GET /gmail/v1/users/:userId/threads/:id`
+- `GET /gmail/v1/users/:userId/labels`, `POST /gmail/v1/users/:userId/labels`, `PATCH /gmail/v1/users/:userId/labels/:id`, `DELETE /gmail/v1/users/:userId/labels/:id`
+- `GET /gmail/v1/users/:userId/history`, `POST /gmail/v1/users/:userId/watch`, `POST /gmail/v1/users/:userId/stop`
+- `GET /gmail/v1/users/:userId/settings/filters`, `POST /gmail/v1/users/:userId/settings/filters`, `DELETE /gmail/v1/users/:userId/settings/filters/:id`
+- `GET /gmail/v1/users/:userId/settings/forwardingAddresses`, `GET /gmail/v1/users/:userId/settings/sendAs`
+- `GET /calendar/v3/users/:userId/calendarList`, `GET /calendar/v3/calendars/:calendarId/events`, `POST /calendar/v3/calendars/:calendarId/events`, `DELETE /calendar/v3/calendars/:calendarId/events/:eventId`, `POST /calendar/v3/freeBusy`
+- `GET /drive/v3/files`, `GET /drive/v3/files/:fileId`, `POST /drive/v3/files`, `PATCH /drive/v3/files/:fileId`, `PUT /drive/v3/files/:fileId`, `POST /upload/drive/v3/files`
+
+The Google plugin still does not cover every Google API edge case, but Gmail, Calendar, and Drive now have enough mutable surface to support realistic local automation flows without stuffing everything into static seed config.
 
 ## Architecture
 
 ```
 packages/
   emulate/          # CLI entry point (commander)
-    @internal/
+    @emulators/
     core/           # HTTP server, in-memory store, plugin interface, middleware
     vercel/         # Vercel API service
     github/         # GitHub API service
-    google/         # Google OAuth 2.0 / OIDC
+    google/         # Google OAuth 2.0 / OIDC + Gmail, Calendar, and Drive APIs
 apps/
   web/              # Documentation site (Next.js)
 ```

package/dist/api.d.ts

@@ -0,0 +1,23 @@
+declare const SERVICE_NAME_LIST: readonly ["vercel", "github", "google", "slack", "apple", "microsoft", "aws"];
+type ServiceName = (typeof SERVICE_NAME_LIST)[number];
+
+interface SeedConfig {
+    tokens?: Record<string, {
+        login: string;
+        scopes?: string[];
+    }>;
+    [service: string]: unknown;
+}
+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 };