@websublime/vite-plugin-open-api-server 0.24.0-next.4 → 0.24.0-next.6

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Plugin, ViteDevServer } from 'vite';
-import { Logger, SpecInfo, OpenApiServer, HandlerFn, AnySeedFn } from '@websublime/vite-plugin-open-api-core';
+import { Logger, SpecInfo, OpenApiServer, WebSocketHub, HandlerFn, AnySeedFn } from '@websublime/vite-plugin-open-api-core';
 export { HandlerContext, HandlerDefinition, HandlerFn, HandlerReturn, SecurityContext, SeedContext, SeedDefinition, SeedFn, SeedHelper, defineHandlers, defineSeeds } from '@websublime/vite-plugin-open-api-core';
 import { OpenAPIV3_1 } from '@scalar/openapi-types';
 import { Hono } from 'hono';
@@ -243,13 +243,44 @@ declare function resolveOptions(options: OpenApiServerOptions): ResolvedOptions;
 /**
  * Vite Plugin Implementation
  *
- * What: Main Vite plugin for OpenAPI mock server
- * How: Uses configureServer hook to start mock server and configure proxy
- * Why: Integrates OpenAPI mock server seamlessly into Vite dev workflow
+ * What: Main Vite plugin for OpenAPI mock server (multi-spec)
+ * How: Uses orchestrator to create N spec instances, configures multi-proxy
+ * Why: Integrates multiple OpenAPI mock servers seamlessly into Vite dev workflow
  *
  * @module plugin
  */
 
+/**
+ * Create the OpenAPI Server Vite plugin
+ *
+ * This plugin starts mock servers based on OpenAPI specifications
+ * and configures Vite to proxy API requests to them. Supports
+ * multiple specs via the orchestrator pattern.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import vue from '@vitejs/plugin-vue';
+ * import { openApiServer } from '@websublime/vite-plugin-open-api-server';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     vue(),
+ *     openApiServer({
+ *       specs: [
+ *         { spec: './openapi/petstore.yaml', proxyPath: '/api/pets' },
+ *         { spec: './openapi/inventory.yaml', proxyPath: '/api/inventory' },
+ *       ],
+ *       port: 4000,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @param options - Plugin configuration options
+ * @returns Vite plugin
+ */
 declare function openApiServer(options: OpenApiServerOptions): Plugin;
 
 /**
@@ -467,12 +498,31 @@ interface SpecInstance {
  * individual spec instances, aggregated metadata, and lifecycle methods.
  */
 interface OrchestratorResult {
-    /** Main Hono app with all specs mounted via X-Spec-Id dispatch */
+    /**
+     * Main Hono app with all specs mounted via X-Spec-Id dispatch.
+     *
+     * **Note**: Consumers using this property directly must have `hono`
+     * as a dependency. The `start()`/`stop()` lifecycle methods do not
+     * require direct interaction with this Hono instance.
+     */
     app: Hono;
     /** All spec instances (in config order) */
     instances: SpecInstance[];
     /** Spec metadata array for WebSocket `connected` event */
     specsInfo: SpecInfo[];
+    /**
+     * Shared WebSocket hub for the orchestrator.
+     *
+     * Created with `autoConnect: false` so the orchestrator controls
+     * the `connected` event (enhanced with `specs` metadata).
+     *
+     * In multi-spec mode (Epic 3, Task 3.1), this hub will be replaced by
+     * `createMultiSpecWebSocketHub()` which also wires broadcast interception
+     * and multi-spec command routing.
+     *
+     * @experimental Will be replaced by `createMultiSpecWebSocketHub()` in Epic 3.
+     */
+    wsHub: WebSocketHub;
     /** Start the shared HTTP server on the configured port */
     start(): Promise<void>;
     /** Stop the HTTP server and clean up resources */
@@ -491,9 +541,10 @@ interface OrchestratorResult {
  * 3. **Phase 3 — Build main app**: Create a single Hono app with CORS,
  *    DevTools, Internal API, and X-Spec-Id dispatch middleware.
  *
- * **Note**: This function mutates `options.specs[i]` to write back resolved
- * values (id, proxyPath, proxyPathSource, handlersDir, seedsDir) so that
- * downstream consumers (banner, file watcher, plugin.ts) see the final values.
+ * **Note**: This function populates the resolved values (id, proxyPath,
+ * proxyPathSource, handlersDir, seedsDir) on each `options.specs[i]` object.
+ * Since `instances[i].config` is the same object reference, consumers should
+ * access resolved values through `instances[i].config` (the authoritative view).
  *
  * @param options - Resolved plugin options (from `resolveOptions()`)
  * @param vite - Vite dev server instance (for ssrLoadModule)
@@ -513,6 +564,17 @@ declare function createOrchestrator(options: ResolvedOptions, vite: ViteDevServe
  * @module multi-proxy
  */
 
+/**
+ * Shared service proxy path prefixes.
+ *
+ * These constants are the single source of truth for the reserved proxy paths
+ * used by the DevTools iframe, internal API, and WebSocket connections.
+ * Both `configureMultiProxy()` and the virtual DevTools tab module in
+ * `plugin.ts` reference these to prevent divergence.
+ */
+declare const DEVTOOLS_PROXY_PATH = "/_devtools";
+declare const API_PROXY_PATH = "/_api";
+declare const WS_PROXY_PATH = "/_ws";
 /**
  * Configure Vite proxy for multiple spec instances and shared services.
  *
@@ -766,7 +828,7 @@ declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, dela
 interface RegisterDevToolsOptions {
     /**
      * The port where the OpenAPI server is running
-     * @default 3000
+     * @default 4000
      */
     port?: number;
     /**
@@ -808,7 +870,7 @@ interface RegisterDevToolsOptions {
  *
  * // Register OpenAPI Server DevTools
  * if (import.meta.env.DEV) {
- *   await registerDevTools(app, { port: 3000 });
+ *   await registerDevTools(app);
  * }
  *
  * app.mount('#app');
@@ -824,11 +886,11 @@ declare function registerDevTools(app: App, options?: RegisterDevToolsOptions):
  * When running in a browser, protocol and host are automatically derived from
  * window.location if not explicitly provided.
  *
- * @param port - Server port (default: 3000)
+ * @param port - Server port (default: 4000, matching OpenApiServerOptions.port)
  * @param host - Server host (default: 'localhost' or window.location.hostname)
  * @param protocol - Protocol to use (default: 'http' or window.location.protocol)
  * @returns DevTools SPA URL
  */
 declare function getDevToolsUrl(port?: number, host?: string, protocol?: 'http' | 'https'): string;
 
-export { type DeriveProxyPathResult, type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type OrchestratorResult, type ProxyPathSource, type RegisterDevToolsOptions, type ResolvedOptions, type ResolvedSpecConfig, SPEC_COLORS, type SpecConfig, type SpecInstance, ValidationError, type ValidationErrorCode, configureMultiProxy, createFileWatcher, createOrchestrator, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };
+export { API_PROXY_PATH, DEVTOOLS_PROXY_PATH, type DeriveProxyPathResult, type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type OrchestratorResult, type ProxyPathSource, type RegisterDevToolsOptions, type ResolvedOptions, type ResolvedSpecConfig, SPEC_COLORS, type SpecConfig, type SpecInstance, ValidationError, type ValidationErrorCode, WS_PROXY_PATH, configureMultiProxy, createFileWatcher, createOrchestrator, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };