api-emulator 0.5.1 → 0.6.0

package/dist/api.js

@@ -1,5 +1,23 @@
 // src/external-plugin-adapter.ts
 import { isAbsolute, resolve } from "path";
+
+// src/plugin-manifest.ts
+function readPluginManifest(mod) {
+  return mod.manifest ?? {};
+}
+function validatePluginManifest(manifest, pluginName) {
+  if (manifest.name && manifest.name !== pluginName) {
+    throw new Error(`Plugin manifest name "${manifest.name}" does not match plugin name "${pluginName}"`);
+  }
+  return {
+    ...manifest,
+    label: manifest.label ?? `${pluginName} (external plugin)`,
+    endpoints: manifest.endpoints ?? "",
+    initConfig: manifest.initConfig ?? {}
+  };
+}
+
+// src/external-plugin-adapter.ts
 async function loadExternalPluginModule(specifier) {
   const modulePath = specifier.startsWith(".") || isAbsolute(specifier) ? resolve(specifier) : specifier;
   const mod = await import(modulePath);
@@ -8,10 +26,12 @@ async function loadExternalPluginModule(specifier) {
     throw new Error(`Plugin "${specifier}" must export a ServicePlugin (as "plugin" or default export)`);
   }
   const name = plugin.name;
+  const manifest = validatePluginManifest(readPluginManifest(mod), name);
   return {
     name,
-    label: mod.label ?? `${name} (external plugin)`,
-    endpoints: mod.endpoints ?? "",
+    label: manifest.label,
+    endpoints: manifest.endpoints,
+    manifest,
     async load() {
       return {
         plugin,
@@ -19,428 +39,38 @@ async function loadExternalPluginModule(specifier) {
       };
     },
     defaultFallback: mod.defaultFallback ?? (() => ({ login: "admin", id: 1, scopes: [] })),
-    initConfig: mod.initConfig ?? {}
+    initConfig: manifest.initConfig
   };
 }
 
-// src/default-plugin-catalog.ts
-var DEFAULT_PLUGIN_REGISTRY = {
-  vercel: {
-    name: "vercel",
-    label: "Vercel REST API emulator",
-    endpoints: "projects, deployments, domains, env vars, users, teams, file uploads, protection bypass",
-    async load() {
-      const mod = await import("@emulators/vercel");
-      return { plugin: mod.vercelPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstLogin = cfg?.users?.[0]?.username ?? "admin";
-      return { login: firstLogin, id: 1, scopes: [] };
-    },
-    initConfig: {
-      vercel: {
-        users: [{ username: "developer", name: "Developer", email: "dev@example.com" }],
-        teams: [{ slug: "my-team", name: "My Team" }],
-        projects: [{ name: "my-app", team: "my-team", framework: "nextjs" }],
-        integrations: [
-          {
-            client_id: "oac_example_client_id",
-            client_secret: "example_client_secret",
-            name: "My Vercel App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/vercel"]
-          }
-        ]
-      }
-    }
-  },
-  github: {
-    name: "github",
-    label: "GitHub REST API emulator",
-    endpoints: "users, repos, issues, PRs, comments, reviews, labels, milestones, branches, git data, orgs, teams, releases, webhooks, search, actions, checks, rate limit",
-    async load() {
-      const mod = await import("@emulators/github");
-      return {
-        plugin: mod.githubPlugin,
-        seedFromConfig: mod.seedFromConfig,
-        createAppKeyResolver(store) {
-          return (appId) => {
-            try {
-              const gh = mod.getGitHubStore(store);
-              const ghApp = gh.apps.all().find((a) => a.app_id === appId);
-              if (!ghApp) return null;
-              return { privateKey: ghApp.private_key, slug: ghApp.slug, name: ghApp.name };
-            } catch {
-              return null;
-            }
-          };
-        }
-      };
-    },
-    defaultFallback(cfg) {
-      const firstLogin = cfg?.users?.[0]?.login ?? "admin";
-      return { login: firstLogin, id: 1, scopes: ["repo", "user", "admin:org", "admin:repo_hook"] };
-    },
-    initConfig: {
-      github: {
-        users: [
-          {
-            login: "octocat",
-            name: "The Octocat",
-            email: "octocat@github.com",
-            bio: "I am the Octocat",
-            company: "GitHub",
-            location: "San Francisco"
-          }
-        ],
-        orgs: [{ login: "my-org", name: "My Organization", description: "A test organization" }],
-        repos: [
-          {
-            owner: "octocat",
-            name: "hello-world",
-            description: "My first repository",
-            language: "JavaScript",
-            topics: ["hello", "world"],
-            auto_init: true
-          },
-          {
-            owner: "my-org",
-            name: "org-repo",
-            description: "An organization repository",
-            language: "TypeScript",
-            auto_init: true
-          }
-        ],
-        oauth_apps: [
-          {
-            client_id: "Iv1.example_client_id",
-            client_secret: "example_client_secret",
-            name: "My App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/github"]
-          }
-        ]
-      }
-    }
-  },
-  google: {
-    name: "google",
-    label: "Google OAuth 2.0 / OpenID Connect + Gmail, Calendar, and Drive emulator",
-    endpoints: "OAuth authorize, token exchange, userinfo, OIDC discovery, token revocation, Gmail messages/drafts/threads/labels/history/settings, Calendar lists/events/freebusy, Drive files/uploads",
-    async load() {
-      const mod = await import("@emulators/google");
-      return { plugin: mod.googlePlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstEmail = cfg?.users?.[0]?.email ?? "testuser@gmail.com";
-      return { login: firstEmail, id: 1, scopes: ["openid", "email", "profile"] };
-    },
-    initConfig: {
-      google: {
-        users: [
-          {
-            email: "testuser@example.com",
-            name: "Test User",
-            picture: "https://lh3.googleusercontent.com/a/default-user",
-            email_verified: true
-          }
-        ],
-        oauth_clients: [
-          {
-            client_id: "example-client-id.apps.googleusercontent.com",
-            client_secret: "GOCSPX-example_secret",
-            name: "Code App (Google)",
-            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"],
-            date: "2025-01-04T10:00:00.000Z"
-          }
-        ],
-        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"]
-          }
-        ]
-      }
-    }
-  },
-  slack: {
-    name: "slack",
-    label: "Slack API emulator",
-    endpoints: "auth, chat, conversations, users, reactions, team, OAuth, incoming webhooks",
-    async load() {
-      const mod = await import("@emulators/slack");
-      return { plugin: mod.slackPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "U000000001", id: 1, scopes: ["chat:write", "channels:read", "users:read", "reactions:write"] };
-    },
-    initConfig: {
-      slack: {
-        team: { name: "My Workspace", domain: "my-workspace" },
-        users: [{ name: "developer", real_name: "Developer", email: "dev@example.com" }],
-        channels: [
-          { name: "general", topic: "General discussion" },
-          { name: "random", topic: "Random stuff" }
-        ],
-        bots: [{ name: "my-bot" }],
-        oauth_apps: [
-          {
-            client_id: "12345.67890",
-            client_secret: "example_client_secret",
-            name: "My Slack App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/slack"]
-          }
-        ]
-      }
-    }
-  },
-  apple: {
-    name: "apple",
-    label: "Apple Sign In / OAuth emulator",
-    endpoints: "OAuth authorize, token exchange, JWKS",
-    async load() {
-      const mod = await import("@emulators/apple");
-      return { plugin: mod.applePlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstEmail = cfg?.users?.[0]?.email ?? "testuser@icloud.com";
-      return { login: firstEmail, id: 1, scopes: ["openid", "email", "name"] };
-    },
-    initConfig: {
-      apple: {
-        users: [{ email: "testuser@icloud.com", name: "Test User" }],
-        oauth_clients: [
-          {
-            client_id: "com.example.app",
-            team_id: "TEAM001",
-            name: "My Apple App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/apple"]
-          }
-        ]
-      }
-    }
-  },
-  microsoft: {
-    name: "microsoft",
-    label: "Microsoft Entra ID OAuth 2.0 / OpenID Connect emulator",
-    endpoints: "OAuth authorize, token exchange, userinfo, OIDC discovery, Graph /me, logout, token revocation",
-    async load() {
-      const mod = await import("@emulators/microsoft");
-      return { plugin: mod.microsoftPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstEmail = cfg?.users?.[0]?.email ?? "testuser@outlook.com";
-      return { login: firstEmail, id: 1, scopes: ["openid", "email", "profile", "User.Read"] };
-    },
-    initConfig: {
-      microsoft: {
-        users: [{ email: "testuser@outlook.com", name: "Test User" }],
-        oauth_clients: [
-          {
-            client_id: "example-client-id",
-            client_secret: "example-client-secret",
-            name: "My Microsoft App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/microsoft-entra-id"]
-          }
-        ]
-      }
-    }
-  },
-  okta: {
-    name: "okta",
-    label: "Okta OAuth 2.0 / OpenID Connect + management API emulator",
-    endpoints: "OIDC discovery, JWKS, OAuth authorize/token/userinfo/introspect/revoke/logout, users, groups, apps, authorization servers",
-    async load() {
-      const mod = await import("@emulators/okta");
-      return { plugin: mod.oktaPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstLogin = cfg?.users?.[0]?.login ?? cfg?.users?.[0]?.email ?? "testuser@okta.local";
-      return { login: firstLogin, id: 1, scopes: ["openid", "profile", "email", "groups"] };
-    },
-    initConfig: {
-      okta: {
-        users: [{ login: "testuser@okta.local", email: "testuser@okta.local", first_name: "Test", last_name: "User" }],
-        groups: [{ name: "Everyone", description: "All users", type: "BUILT_IN", okta_id: "00g_everyone" }],
-        authorization_servers: [{ id: "default", name: "default", audiences: ["api://default"] }],
-        oauth_clients: [
-          {
-            client_id: "okta-test-client",
-            client_secret: "okta-test-secret",
-            name: "Sample OIDC Client",
-            redirect_uris: ["http://localhost:3000/callback"],
-            auth_server_id: "default"
-          }
-        ]
-      }
-    }
-  },
-  aws: {
-    name: "aws",
-    label: "AWS cloud service emulator",
-    endpoints: "S3 (buckets, objects), SQS (queues, messages), IAM (users, roles, access keys), STS (assume role, caller identity)",
-    async load() {
-      const mod = await import("@emulators/aws");
-      return { plugin: mod.awsPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "admin", id: 1, scopes: ["s3:*", "sqs:*", "iam:*", "sts:*"] };
-    },
-    initConfig: {
-      aws: {
-        region: "us-east-1",
-        s3: { buckets: [{ name: "my-app-bucket" }, { name: "my-app-uploads" }] },
-        sqs: { queues: [{ name: "my-app-events" }, { name: "my-app-dlq" }] },
-        iam: {
-          users: [{ user_name: "developer", create_access_key: true }],
-          roles: [{ role_name: "lambda-execution-role", description: "Role for Lambda function execution" }]
-        }
-      }
-    }
-  },
-  resend: {
-    name: "resend",
-    label: "Resend email API emulator",
-    endpoints: "emails, domains, contacts, API keys, inbox UI",
-    async load() {
-      const mod = await import("@emulators/resend");
-      return { plugin: mod.resendPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "re_test_admin", id: 1, scopes: [] };
-    },
-    initConfig: {
-      resend: {
-        domains: [{ name: "example.com", region: "us-east-1" }],
-        contacts: [{ email: "test@example.com", first_name: "Test", last_name: "User" }]
-      }
-    }
-  },
-  stripe: {
-    name: "stripe",
-    label: "Stripe payments emulator",
-    endpoints: "customers, payment methods, customer sessions, payment intents, charges, products, prices, checkout sessions, webhooks",
-    async load() {
-      const mod = await import("@emulators/stripe");
-      return { plugin: mod.stripePlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "sk_test_admin", id: 1, scopes: [] };
-    },
-    initConfig: {
-      stripe: {
-        customers: [{ email: "test@example.com", name: "Test Customer" }],
-        products: [{ name: "Pro Plan", description: "Monthly pro subscription" }],
-        prices: [{ product_name: "Pro Plan", currency: "usd", unit_amount: 2e3 }]
-      }
-    }
-  },
-  mongoatlas: {
-    name: "mongoatlas",
-    label: "MongoDB Atlas service emulator",
-    endpoints: "Atlas Admin API v2 (projects, clusters, database users, databases, collections), Atlas Data API v1 (findOne, find, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, aggregate)",
-    async load() {
-      const mod = await import("@emulators/mongoatlas");
-      return { plugin: mod.mongoatlasPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "admin", id: 1, scopes: [] };
-    },
-    initConfig: {
-      mongoatlas: {
-        projects: [{ name: "Project0" }],
-        clusters: [{ name: "Cluster0", project: "Project0" }],
-        database_users: [{ username: "admin", project: "Project0" }],
-        databases: [{ cluster: "Cluster0", name: "test", collections: ["items"] }]
-      }
-    }
-  },
-  clerk: {
-    name: "clerk",
-    label: "Clerk authentication and user management emulator",
-    endpoints: "OIDC discovery, JWKS, OAuth authorize/token/userinfo, users, email addresses, organizations, memberships, invitations, sessions",
-    async load() {
-      const mod = await import("@emulators/clerk");
-      return { plugin: mod.clerkPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstEmail = cfg?.users?.[0]?.email_addresses?.[0] ?? "test@example.com";
-      return { login: firstEmail, id: 1, scopes: [] };
-    },
-    initConfig: {
-      clerk: {
-        users: [
-          {
-            first_name: "Test",
-            last_name: "User",
-            email_addresses: ["test@example.com"],
-            password: "clerk_test_password"
-          }
-        ],
-        organizations: [
-          {
-            name: "My Company",
-            slug: "my-company",
-            members: [{ email: "test@example.com", role: "admin" }]
-          }
-        ],
-        oauth_applications: [
-          {
-            client_id: "clerk_emulate_client",
-            client_secret: "clerk_emulate_secret",
-            name: "api-emulator App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/clerk"]
-          }
-        ]
-      }
-    }
+// src/plugin-lock.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+var PLUGIN_LOCK_FILE = "api-emulator.lock";
+function createEmptyPluginLock() {
+  return { version: 1, plugins: {} };
+}
+function readPluginLock(cwd = process.cwd()) {
+  const path = resolve2(cwd, PLUGIN_LOCK_FILE);
+  if (!existsSync(path)) return createEmptyPluginLock();
+  const parsed = JSON.parse(readFileSync(path, "utf-8"));
+  if (parsed.version !== 1 || typeof parsed.plugins !== "object" || parsed.plugins === null) {
+    throw new Error(`Invalid ${PLUGIN_LOCK_FILE}`);
   }
-};
+  return parsed;
+}
+function getLockedPluginSpecifiers(cwd = process.cwd()) {
+  return Object.values(readPluginLock(cwd).plugins).map((entry) => entry.specifier);
+}
+
+// src/default-plugin-catalog.ts
+var DEFAULT_PLUGIN_REGISTRY = {};
 
 // src/registry.ts
-async function resolvePluginModules(pluginSpecifiers = []) {
-  const results = await Promise.all(pluginSpecifiers.map(loadExternalPluginModule));
+async function resolvePluginModules(pluginSpecifiers = [], options = {}) {
+  const installedSpecifiers = options.includeInstalled ? getLockedPluginSpecifiers() : [];
+  const allSpecifiers = [...installedSpecifiers, ...pluginSpecifiers];
+  const results = await Promise.all(allSpecifiers.map(loadExternalPluginModule));
   const externalEntries = {};
   for (const pluginModule of results) {
     if (pluginModule.name in DEFAULT_PLUGIN_REGISTRY) {
@@ -462,7 +92,7 @@ function resolveBaseUrl(opts) {
   if (opts.baseUrl) {
     return opts.baseUrl.replace(/\{service\}/g, opts.service);
   }
-  const envBaseUrl = process.env.API_EMULATOR_BASE_URL ?? process.env.EMULATE_BASE_URL;
+  const envBaseUrl = process.env.API_EMULATOR_BASE_URL;
   if (envBaseUrl) {
     return envBaseUrl.replace(/\{service\}/g, opts.service);
   }
@@ -474,7 +104,11 @@ function resolveBaseUrl(opts) {
 }
 
 // src/service-runtime.ts
-import { createServer } from "@emulators/core";
+import {
+  createServer,
+  createStoreFixture,
+  fixtureStoreSnapshot
+} from "@api-emulator/core";
 import { serve } from "@hono/node-server";
 function createAuthTokens(seedConfig) {
   const tokens = {};
@@ -513,15 +147,32 @@ function createServiceRuntime(options) {
     service,
     url: baseUrl,
     store,
+    snapshot() {
+      return store.snapshot();
+    },
+    restore(fixture) {
+      store.restore(fixtureStoreSnapshot(fixture));
+    },
+    exportFixture(options2 = {}) {
+      const interactions = store.getData("api-emulator:interactions");
+      return createStoreFixture(service, store.snapshot(), {
+        ...options2,
+        interactions: options2.interactions ?? interactions
+      });
+    },
+    resetToFixture(fixture) {
+      store.reset();
+      store.restore(fixtureStoreSnapshot(fixture));
+    },
     reset() {
       store.reset();
       seed();
     },
     close() {
-      return new Promise((resolve2, reject) => {
+      return new Promise((resolve3, reject) => {
         httpServer.close((err) => {
           if (err) reject(err);
-          else resolve2();
+          else resolve3();
         });
       });
     }
@@ -551,6 +202,10 @@ async function createEmulator(options) {
   });
   return {
     url: running.url,
+    snapshot: running.snapshot,
+    restore: running.restore,
+    exportFixture: running.exportFixture,
+    resetToFixture: running.resetToFixture,
     reset: running.reset,
     close: running.close
   };