@executor-js/emulate 0.6.0 → 0.7.0

package/dist/api.d.ts

@@ -1,3 +1,310 @@
+interface Entity {
+    id: number;
+    created_at: string;
+    updated_at: string;
+}
+interface CollectionSnapshot<T extends Entity = Entity> {
+    items: T[];
+    autoId: number;
+    indexFields: string[];
+}
+interface StoreSnapshot {
+    collections: Record<string, CollectionSnapshot>;
+    data: Record<string, unknown>;
+}
+interface WebhookDelivery {
+    id: number;
+    hook_id: number;
+    event: string;
+    action?: string;
+    payload: unknown;
+    status_code: number | null;
+    delivered_at: string;
+    duration: number | null;
+    success: boolean;
+}
+
+interface LedgerIdentity {
+    user?: Pick<AuthUser, "login" | "id" | "scopes">;
+    app?: Pick<AuthApp, "appId" | "slug" | "name">;
+}
+interface LedgerSideEffect {
+    type: "create" | "update" | "delete" | "custom";
+    collection?: string;
+    id?: string | number;
+    summary?: string;
+}
+interface LedgerWebhookDelivery {
+    id: number;
+    hook_id: number;
+    event: string;
+    action?: string;
+    status_code: number | null;
+    success: boolean;
+}
+interface LedgerEntry {
+    id: string;
+    /** Correlation id: honored from X-Correlation-Id / X-Request-Id or generated. */
+    correlationId: string;
+    timestamp: string;
+    method: string;
+    host: string;
+    path: string;
+    query: string;
+    /** Matched route pattern, e.g. /repos/:owner/:repo/issues. */
+    route?: string;
+    /** Provider operation id, when the handler advertises one. */
+    operationId?: string;
+    request: {
+        headers: Record<string, string>;
+        body?: unknown;
+        bodyTruncated?: boolean;
+    };
+    identity: LedgerIdentity;
+    response: {
+        status: number;
+        headers: Record<string, string>;
+        body?: unknown;
+        bodyTruncated?: boolean;
+    };
+    /** Human/agent-readable one-liner, e.g. "POST /repos/:owner/:repo -> 201". */
+    summary: string;
+    sideEffects: LedgerSideEffect[];
+    webhookDeliveries: LedgerWebhookDelivery[];
+    durationMs: number;
+}
+
+interface AuthUser {
+    login: string;
+    id: number;
+    scopes: string[];
+}
+interface AuthApp {
+    appId: number;
+    slug: string;
+    name: string;
+}
+
+type SpecKind = "openapi" | "graphql" | "mcp" | "google-discovery" | "oauth-metadata" | "manual";
+type SpecCoverage = "generated" | "hand-authored" | "partial" | "unsupported";
+/**
+ * Per-operation coverage. The vision asks for honest, operation-level coverage
+ * boundaries (generated / hand-authored / partial / unsupported) instead of a
+ * single label stamped across an entire spec. A plugin declares the operations
+ * it actually implements; `GET /_emulate/coverage` reports them with a summary.
+ */
+interface OperationCoverage {
+    operationId: string;
+    method?: string;
+    path?: string;
+    status: SpecCoverage;
+    summary?: string;
+}
+interface SpecManifest {
+    kind: SpecKind;
+    title: string;
+    url?: string;
+    coverage: SpecCoverage;
+    operations?: OperationCoverage[];
+    notes?: string;
+}
+interface SurfaceManifest {
+    id: string;
+    kind: "rest" | "oauth" | "oidc" | "graphql" | "mcp" | "webhooks" | "ui" | "provider-specific";
+    title: string;
+    basePath?: string;
+    status: "supported" | "partial" | "unsupported";
+    notes?: string;
+}
+interface AuthCapabilityManifest {
+    id: string;
+    title: string;
+    type: "api-key" | "bearer-token" | "oauth-client-credentials" | "oauth-authorization-code" | "oidc" | "jwt-app" | "dynamic-client-registration" | "webhook-secret" | "provider-specific";
+    status: "supported" | "partial" | "unsupported";
+    notes?: string;
+}
+interface ScenarioManifest {
+    id: string;
+    title: string;
+    description?: string;
+}
+/** A seedable area of the instance, surfaced so agents can discover the seed shape. */
+interface SeedFieldManifest {
+    key: string;
+    title: string;
+    description?: string;
+    example?: unknown;
+}
+interface SeedSchemaManifest {
+    description?: string;
+    fields: SeedFieldManifest[];
+    /** A full example seed body that can be POSTed to /_emulate/seed. */
+    example?: unknown;
+}
+interface StateCollectionManifest {
+    name: string;
+    title?: string;
+    description?: string;
+}
+interface StateModelManifest {
+    description?: string;
+    collections: StateCollectionManifest[];
+}
+interface ResetBehaviorManifest {
+    description: string;
+    reseeds: boolean;
+    clearsLedger: boolean;
+    clearsWebhooks: boolean;
+}
+type InspectorTabKind = "landing" | "ledger" | "state" | "logs" | "credentials" | "seed" | "spec" | "custom";
+interface InspectorTabManifest {
+    id: string;
+    title: string;
+    kind: InspectorTabKind;
+    description?: string;
+}
+/** Describes what the request ledger records and how durable it is. */
+interface LedgerCapabilitiesManifest {
+    description?: string;
+    recordsFields: string[];
+    redactsSensitive: boolean;
+    correlationId: boolean;
+    webhookDeliveries: boolean;
+    sideEffects: boolean;
+    persistent: boolean;
+    maxEntries?: number;
+}
+type ConnectionKind = "sdk" | "cli" | "env" | "curl" | "config" | "mcp";
+/**
+ * A copyable connection snippet. The `template` uses {{placeholders}} that the
+ * control plane resolves against the live instance ({{baseUrl}}, {{controlBaseUrl}},
+ * {{service}}, {{instance}}, {{token}}, {{clientId}}, {{clientSecret}}). This is
+ * how a human or agent copies ready-to-run SDK / CLI / app config without repo
+ * context.
+ */
+interface ConnectionSnippet {
+    id: string;
+    title: string;
+    kind: ConnectionKind;
+    language?: string;
+    description?: string;
+    template: string;
+}
+interface ServiceManifest {
+    id: string;
+    name: string;
+    description: string;
+    surfaces: SurfaceManifest[];
+    auth: AuthCapabilityManifest[];
+    specs: SpecManifest[];
+    scenarios?: ScenarioManifest[];
+    seedSchema?: SeedSchemaManifest;
+    stateModel?: StateModelManifest;
+    resetBehavior?: ResetBehaviorManifest;
+    inspectorTabs?: InspectorTabManifest[];
+    ledger?: LedgerCapabilitiesManifest;
+    connections?: ConnectionSnippet[];
+    docsUrl?: string;
+}
+interface EmulatorInstanceInfo {
+    service: string;
+    instance?: string;
+    baseUrl: string;
+    controlBaseUrl: string;
+    providerBaseUrl: string;
+}
+interface ResolvedConnection extends ConnectionSnippet {
+    body: string;
+}
+
+interface CredentialRequest {
+    type?: string;
+    login?: string;
+    name?: string;
+    scopes?: string[];
+    client_id?: string;
+    client_secret?: string;
+    redirect_uris?: string[];
+    [key: string]: unknown;
+}
+interface IssuedCredential {
+    type: string;
+    token?: string;
+    login?: string;
+    scopes?: string[];
+    client_id?: string;
+    client_secret?: string;
+    redirect_uris?: string[];
+    token_url?: string;
+    authorization_url?: string;
+    notes?: string;
+    [key: string]: unknown;
+}
+
+interface ManifestResponse {
+    manifest: ServiceManifest;
+    instance: EmulatorInstanceInfo;
+    connections: ResolvedConnection[];
+}
+interface SpecsResponse {
+    specs: SpecManifest[];
+    surfaces: SurfaceManifest[];
+}
+interface CoverageResponse {
+    operations: OperationCoverage[];
+    summary: Record<SpecCoverage, number>;
+    specs: Array<{
+        kind: SpecKind;
+        title: string;
+        coverage: SpecCoverage;
+        operationCount: number;
+    }>;
+}
+interface LogsResponse {
+    webhooks: WebhookDelivery[];
+    requests: LedgerEntry[];
+}
+interface ConnectionsQuery {
+    token?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+declare class EmulatorControlError extends Error {
+    readonly method: string;
+    readonly url: string;
+    readonly status: number;
+    readonly body: string;
+    constructor(method: string, url: string, status: number, body: string);
+}
+/** fetch-compatible function, injectable for tests (e.g. a Hono app.request). */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+declare class EmulatorClient {
+    #private;
+    /** Provider base URL — what an SDK or app under test points at. */
+    readonly baseUrl: string;
+    constructor(baseUrl: string, options?: {
+        fetch?: FetchLike;
+    });
+    /** The /_emulate/openapi URL — feed it to anything that ingests a spec. */
+    get openapiUrl(): string;
+    manifest(): Promise<ManifestResponse>;
+    quickstart(): Promise<string>;
+    specs(): Promise<SpecsResponse>;
+    coverage(): Promise<CoverageResponse>;
+    connections(query?: ConnectionsQuery): Promise<ResolvedConnection[]>;
+    state(): Promise<StoreSnapshot>;
+    logs(): Promise<LogsResponse>;
+    readonly ledger: {
+        list: (limit?: number) => Promise<LedgerEntry[]>;
+        clear: () => Promise<void>;
+    };
+    readonly credentials: {
+        mint: (request?: CredentialRequest) => Promise<IssuedCredential>;
+    };
+    seed(seed: unknown): Promise<void>;
+    reset(): Promise<void>;
+}
+
 declare const SERVICE_NAME_LIST: readonly ["vercel", "github", "google", "slack", "apple", "microsoft", "okta", "aws", "resend", "stripe", "mongoatlas", "clerk", "spotify", "x", "workos", "autumn"];
 type ServiceName = (typeof SERVICE_NAME_LIST)[number];
 
@@ -14,11 +321,34 @@ interface EmulatorOptions {
     seed?: SeedConfig;
     baseUrl?: string;
 }
-interface Emulator {
+/**
+ * A handle on a running emulator. Extends the typed /_emulate control-plane
+ * client (credentials.mint, ledger.list/clear, seed, reset, manifest, ...)
+ * with lifecycle for the locally spawned process.
+ */
+interface Emulator extends EmulatorClient {
     url: string;
-    reset(): void;
     close(): Promise<void>;
 }
+interface ConnectOptions {
+    /** Provider base URL of a running emulator (local or hosted). */
+    baseUrl: string;
+    /**
+     * Expected service id; when given, the manifest is fetched on connect and a
+     * mismatch (or unreachable control plane) throws instead of failing later.
+     */
+    service?: ServiceName;
+    /** Override fetch (e.g. an in-process app.request) — mainly for tests. */
+    fetch?: FetchLike;
+}
+/**
+ * Attach to an already-running emulator — another local process or a hosted
+ * instance like `https://resend.<name>.emulators.dev` — and get the same
+ * typed control-plane client a locally spawned Emulator carries. Unlike
+ * createEmulator, nothing is spawned and close() is not available; lifecycle
+ * belongs to whoever started the instance.
+ */
+declare function connectEmulator(options: ConnectOptions): Promise<EmulatorClient>;
 declare function createEmulator(options: EmulatorOptions): Promise<Emulator>;
 
-export { type Emulator, type EmulatorOptions, type SeedConfig, type ServiceName, createEmulator };
+export { type ConnectOptions, type ConnectionsQuery, type CoverageResponse, type CredentialRequest, type Emulator, EmulatorClient, EmulatorControlError, type EmulatorOptions, type IssuedCredential, type LedgerEntry, type LedgerIdentity, type LedgerSideEffect, type LedgerWebhookDelivery, type LogsResponse, type ManifestResponse, type SeedConfig, type ServiceManifest, type ServiceName, type SpecsResponse, type StoreSnapshot, type WebhookDelivery, connectEmulator, createEmulator };

package/dist/api.js

@@ -1812,6 +1812,102 @@ function createServer(plugin, options = {}) {
   );
   return { app, store, webhooks, ledger, port, baseUrl, tokenMap };
 }
+var EmulatorControlError = class extends Error {
+  constructor(method, url, status, body) {
+    super(`${method} ${url} -> ${status}${body ? `: ${body.slice(0, 300)}` : ""}`);
+    this.method = method;
+    this.url = url;
+    this.status = status;
+    this.body = body;
+    this.name = "EmulatorControlError";
+  }
+};
+var EmulatorClient = class {
+  /** Provider base URL — what an SDK or app under test points at. */
+  baseUrl;
+  #fetch;
+  constructor(baseUrl, options) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.#fetch = options?.fetch ?? ((input, init) => fetch(input, init));
+  }
+  /** The /_emulate/openapi URL — feed it to anything that ingests a spec. */
+  get openapiUrl() {
+    return `${this.baseUrl}/_emulate/openapi`;
+  }
+  async manifest() {
+    return this.#json("GET", "/_emulate/manifest");
+  }
+  async quickstart() {
+    return this.#text("GET", "/_emulate/quickstart");
+  }
+  async specs() {
+    return this.#json("GET", "/_emulate/specs");
+  }
+  async coverage() {
+    return this.#json("GET", "/_emulate/coverage");
+  }
+  async connections(query) {
+    const params = new URLSearchParams();
+    if (query?.token) params.set("token", query.token);
+    if (query?.clientId) params.set("client_id", query.clientId);
+    if (query?.clientSecret) params.set("client_secret", query.clientSecret);
+    const qs = params.size > 0 ? `?${params}` : "";
+    const body = await this.#json(
+      "GET",
+      `/_emulate/connections${qs}`
+    );
+    return body.connections;
+  }
+  async state() {
+    return this.#json("GET", "/_emulate/state");
+  }
+  async logs() {
+    return this.#json("GET", "/_emulate/logs");
+  }
+  ledger = {
+    list: async (limit) => {
+      const qs = limit !== void 0 ? `?limit=${limit}` : "";
+      const body = await this.#json("GET", `/_emulate/ledger${qs}`);
+      return body.entries;
+    },
+    clear: async () => {
+      await this.#json("DELETE", "/_emulate/ledger");
+    }
+  };
+  credentials = {
+    mint: async (request = {}) => {
+      const body = await this.#json(
+        "POST",
+        "/_emulate/credentials",
+        request
+      );
+      return body.credential;
+    }
+  };
+  async seed(seed) {
+    await this.#json("POST", "/_emulate/seed", seed);
+  }
+  async reset() {
+    await this.#json("POST", "/_emulate/reset", {});
+  }
+  async #request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await this.#fetch(url, {
+      method,
+      ...body === void 0 ? {} : { headers: { "content-type": "application/json" }, body: JSON.stringify(body) }
+    });
+    if (!response.ok) {
+      throw new EmulatorControlError(method, url, response.status, await response.text());
+    }
+    return response;
+  }
+  async #json(method, path, body) {
+    return (await this.#request(method, path, body)).json();
+  }
+  async #text(method, path, body) {
+    return (await this.#request(method, path, body)).text();
+  }
+};
 
 // src/registry.ts
 function issueServiceCredential(service, loaded, store, baseUrl, tokenMap, request, webhooks) {
@@ -2163,7 +2259,7 @@ var SERVICE_REGISTRY = {
     label: "Slack API emulator",
     endpoints: "auth, chat, conversations, users, profiles, presence, files, pins, bookmarks, views, reactions, team, OAuth, incoming webhooks, inspector",
     async load() {
-      const mod = await import("./dist-YPRJYQHW.js");
+      const mod = await import("./dist-FE2JWST3.js");
       return { plugin: mod.slackPlugin, manifest: mod.manifest, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback() {
@@ -2294,7 +2390,7 @@ var SERVICE_REGISTRY = {
     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("./dist-BTEY33DJ.js");
+      const mod = await import("./dist-QXFWC3LV.js");
       return { plugin: mod.oktaPlugin, manifest: mod.manifest, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2363,7 +2459,7 @@ var SERVICE_REGISTRY = {
     label: "Resend email API emulator",
     endpoints: "emails, domains, contacts, API keys, inbox UI",
     async load() {
-      const mod = await import("./dist-XM5HSBDC.js");
+      const mod = await import("./dist-TWJXVA7X.js");
       return { plugin: mod.resendPlugin, manifest: mod.manifest, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback() {
@@ -2380,7 +2476,7 @@ var SERVICE_REGISTRY = {
     label: "Stripe payments emulator",
     endpoints: "customers, payment methods, customer sessions, payment intents, charges, products, prices, checkout sessions, webhooks",
     async load() {
-      const mod = await import("./dist-K4CVTD6K.js");
+      const mod = await import("./dist-KBZ6SM7D.js");
       return { plugin: mod.stripePlugin, manifest: mod.manifest, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback() {
@@ -2398,7 +2494,7 @@ var SERVICE_REGISTRY = {
     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("./dist-RMPDKZUA.js");
+      const mod = await import("./dist-OT6R2YO2.js");
       return { plugin: mod.mongoatlasPlugin, manifest: mod.manifest, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback() {
@@ -2417,7 +2513,7 @@ var SERVICE_REGISTRY = {
     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("./dist-WBKONLOE.js");
+      const mod = await import("./dist-OVTPVMMW.js");
       return { plugin: mod.clerkPlugin, manifest: mod.manifest, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2522,7 +2618,7 @@ var SERVICE_REGISTRY = {
     label: "WorkOS emulator",
     endpoints: "AuthKit user management (hosted login, code/refresh grants, sealed-session JWKS), organizations, memberships, invitations, API keys, Vault KV, OAuth authorization server",
     async load() {
-      const mod = await import("./dist-IYZPDKJW.js");
+      const mod = await import("./dist-S47YJ552.js");
       return {
         plugin: mod.workosPlugin,
         manifest: mod.manifest,
@@ -2547,7 +2643,7 @@ var SERVICE_REGISTRY = {
     label: "Autumn billing emulator",
     endpoints: "customers (get_or_create with seedable subscriptions), usage tracking, plans/features/events lists",
     async load() {
-      const mod = await import("./dist-JJ2ZRCAX.js");
+      const mod = await import("./dist-YXHZTLFR.js");
       return {
         plugin: mod.autumnPlugin,
         manifest: mod.manifest,
@@ -2585,6 +2681,18 @@ function resolveBaseUrl(opts) {
 }
 
 // src/api.ts
+async function connectEmulator(options) {
+  const client = new EmulatorClient(options.baseUrl, { fetch: options.fetch });
+  if (options.service) {
+    const { manifest } = await client.manifest();
+    if (manifest.id !== options.service) {
+      throw new Error(
+        `connectEmulator: ${options.baseUrl} is a "${manifest.id}" emulator, expected "${options.service}"`
+      );
+    }
+  }
+  return client;
+}
 async function createEmulator(options) {
   const { service, port = 4e3, seed: seedConfig } = options;
   const entry = SERVICE_REGISTRY[service];
@@ -2643,12 +2751,12 @@ async function createEmulator(options) {
   };
   seed();
   const httpServer = serve({ fetch: app.fetch, port });
-  return {
-    url: baseUrl,
-    reset() {
+  class LocalEmulator extends EmulatorClient {
+    url = baseUrl;
+    async reset() {
       store.reset();
       seed();
-    },
+    }
     close() {
       return new Promise((resolve, reject) => {
         httpServer.close((err) => {
@@ -2657,9 +2765,13 @@ async function createEmulator(options) {
         });
       });
     }
-  };
+  }
+  return new LocalEmulator(baseUrl, { fetch: (input, init) => app.request(input, init) });
 }
 export {
+  EmulatorClient,
+  EmulatorControlError,
+  connectEmulator,
   createEmulator
 };
 //# sourceMappingURL=api.js.map