@websublime/vite-plugin-open-api-server 0.24.0-next.3 → 0.24.0-next.5

package/dist/index.d.ts

@@ -21,7 +21,7 @@ import { App } from 'vue';
  * Used across Tasks 1.2–1.4 for typed error handling.
  * Matches TECHNICAL-SPECIFICATION-V2.md Appendix B.
  */
-type ValidationErrorCode = 'SPEC_ID_MISSING' | 'SPEC_ID_DUPLICATE' | 'PROXY_PATH_MISSING' | 'PROXY_PATH_TOO_BROAD' | 'PROXY_PATH_DUPLICATE' | 'PROXY_PATH_OVERLAP' | 'SPEC_NOT_FOUND' | 'SPECS_EMPTY';
+type ValidationErrorCode = 'SPEC_ID_MISSING' | 'SPEC_ID_DUPLICATE' | 'PROXY_PATH_MISSING' | 'PROXY_PATH_TOO_BROAD' | 'PROXY_PATH_DUPLICATE' | 'PROXY_PATH_OVERLAP' | 'PROXY_PATH_PREFIX_COLLISION' | 'SPEC_NOT_FOUND' | 'SPECS_EMPTY';
 /**
  * Typed validation error for configuration issues.
  *
@@ -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;
 
 /**
@@ -379,21 +410,26 @@ declare function normalizeProxyPath(path: string, specId: string): string;
  *
  * Checks for:
  * 1. Duplicate paths — two specs with the same proxyPath
- * 2. Overlapping paths — one path is a prefix of another (e.g., "/api" and "/api/v1")
- *    which would cause routing ambiguity
+ * 2. Overlapping paths — one path is a prefix of another at a segment boundary
+ *    (e.g., "/api" and "/api/v1") which would cause routing ambiguity
+ * 3. String-prefix collisions — one path is a raw string prefix of another
+ *    without a segment boundary (e.g., "/api" and "/api2"). Vite's internal
+ *    proxy matching uses plain `url.startsWith(context)` with no segment
+ *    awareness, so "/api" would incorrectly capture "/api2/users" requests.
  *
  * @remarks
  * Entries with an empty or falsy `proxyPath` are silently skipped. These
  * represent specs whose proxy path has not yet been resolved (e.g., during
  * early option resolution before the OpenAPI document is processed). Callers
  * should expect unresolved entries to be excluded from uniqueness checks
- * rather than triggering false-positive PROXY_PATH_DUPLICATE or
- * PROXY_PATH_OVERLAP errors.
+ * rather than triggering false-positive errors.
  *
  * @param specs - Array of spec entries with id and proxyPath.
  *   Entries with empty/falsy proxyPath are skipped (unresolved).
  * @throws {ValidationError} PROXY_PATH_DUPLICATE if duplicate paths found
- * @throws {ValidationError} PROXY_PATH_OVERLAP if overlapping paths found
+ * @throws {ValidationError} PROXY_PATH_OVERLAP if overlapping paths found (segment boundary)
+ * @throws {ValidationError} PROXY_PATH_PREFIX_COLLISION if one path is a raw string prefix
+ *   of another without a segment boundary (e.g., "/api" and "/api2")
  *
  * @example
  * // Throws PROXY_PATH_DUPLICATE
@@ -408,6 +444,13 @@ declare function normalizeProxyPath(path: string, specId: string): string;
  *   { id: 'petstore', proxyPath: '/api' },
  *   { id: 'inventory', proxyPath: '/api/v1' },
  * ]);
+ *
+ * @example
+ * // Throws PROXY_PATH_PREFIX_COLLISION
+ * validateUniqueProxyPaths([
+ *   { id: 'petstore', proxyPath: '/api' },
+ *   { id: 'inventory', proxyPath: '/api2' },
+ * ]);
  */
 declare function validateUniqueProxyPaths(specs: Array<{
     id: string;
@@ -455,7 +498,13 @@ 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[];
@@ -479,9 +528,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)
@@ -490,6 +540,50 @@ interface OrchestratorResult {
  */
 declare function createOrchestrator(options: ResolvedOptions, vite: ViteDevServer, cwd: string): Promise<OrchestratorResult>;
 
+/**
+ * Multi-Path Proxy Configuration
+ *
+ * What: Configures Vite proxy for multiple OpenAPI spec instances
+ * How: Generates one proxy entry per spec with path rewriting and X-Spec-Id header,
+ *      plus shared service proxies for DevTools, Internal API, and WebSocket
+ * Why: Enables each spec's API requests to be routed through Vite to the shared server
+ *
+ * @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.
+ *
+ * Generates:
+ * 1. **Per-spec proxy entries** — one per spec, with path rewriting (prefix
+ *    stripping) and an `X-Spec-Id` header so the shared Hono server can
+ *    route to the correct spec instance.
+ * 2. **Shared service proxies** — spec-agnostic entries for `/_devtools`,
+ *    `/_api`, and `/_ws` that forward to the same server without path
+ *    rewriting or spec headers.
+ *
+ * Uses `startsWith`/`slice` for path rewriting instead of the regex approach
+ * described in the tech spec (Section 5.7). Literal prefix matching is safer
+ * because it correctly handles regex metacharacters in proxy paths (e.g.,
+ * `/api.v3` matches literally, not as `/api<any>v3`).
+ *
+ * @param vite - Vite dev server instance
+ * @param instances - Resolved spec instances from the orchestrator
+ * @param port - Shared server port
+ */
+declare function configureMultiProxy(vite: ViteDevServer, instances: SpecInstance[], port: number): void;
+
 /**
  * Handler Loading
  *
@@ -721,7 +815,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;
     /**
@@ -763,7 +857,7 @@ interface RegisterDevToolsOptions {
  *
  * // Register OpenAPI Server DevTools
  * if (import.meta.env.DEV) {
- *   await registerDevTools(app, { port: 3000 });
+ *   await registerDevTools(app);
  * }
  *
  * app.mount('#app');
@@ -779,11 +873,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, 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 };