yaxa-svelte 2.2.0 → 2.3.0

package/README.md

@@ -274,22 +274,48 @@ export const POST = yaxaEndpoint({
 
 ---
 
+## 📜 Auto-Generated OpenAPI 3.1 & Interactive Docs (`/api/docs`)
+
+Instantly generate an OpenAPI 3.1 specification and host interactive documentation ([Scalar](https://scalar.com/), Swagger UI, or Redoc) directly from your `yaxaEndpoint` routes:
+
+```ts
+// src/routes/api/docs/+server.ts
+import { createApiDocsHandler } from 'yaxa-svelte/server';
+import { POST as createProject } from '../projects/+server';
+
+export const GET = createApiDocsHandler({
+	title: 'Acme SaaS API',
+	version: '1.0.0',
+	theme: 'scalar', // 'scalar' (default) | 'swagger' | 'redoc'
+	endpoints: {
+		'/api/projects': {
+			POST: createProject
+		}
+	}
+});
+```
+
+- **Interactive Reference UI:** Open `/api/docs` in your browser.
+- **Raw OpenAPI 3.1 JSON:** Request `/api/docs?format=json` or send `Accept: application/json` for SDK generation.
+
+---
+
 ## 📦 Subpath Exports Architecture
 
-| Subpath                 | Description                                                                                                                               |
-| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
-| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useToast`, `useClipboard`, etc.)     |
-| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />` |
-| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, RFC 7807, Universal Server Hooks, SEO endpoints, Drizzle DB, Storage & Email                 |
-| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)              |
-| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                               |
-| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                   |
-| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                          |
-| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                  |
-| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                               |
-| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                            |
-| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                 |
-| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                          |
+| Subpath                 | Description                                                                                                                                                  |
+| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useToast`, `useClipboard`, etc.)                        |
+| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                    |
+| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, OpenAPI 3.1 & Scalar/Swagger Docs, RFC 7807, Universal Server Hooks, SEO endpoints, Drizzle DB, Storage & Email |
+| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                 |
+| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                                                  |
+| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                                      |
+| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                             |
+| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                     |
+| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                  |
+| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                               |
+| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                    |
+| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                             |
 
 ---
 

package/dist/server/endpoint/guards.d.ts

@@ -11,6 +11,11 @@ export interface RequireAuthOptions {
      */
     detail?: string;
 }
+export interface YaxaGuardMetadata {
+    type: 'auth' | 'role' | 'rateLimit' | string;
+    roles?: string[];
+    options?: any;
+}
 /**
  * Declarative Guard: Enforces that the request has an active authenticated user in `event.locals.user`.
  */

package/dist/server/endpoint/guards.js

@@ -4,7 +4,7 @@ import { problemResponse } from './problem';
  * Declarative Guard: Enforces that the request has an active authenticated user in `event.locals.user`.
  */
 export function requireAuth(options = {}) {
-    return (event) => {
+    const guard = (event) => {
         const user = event.locals?.user;
         if (!user) {
             if (options.redirect) {
@@ -22,6 +22,11 @@ export function requireAuth(options = {}) {
             });
         }
     };
+    guard._yaxaGuard = {
+        type: 'auth',
+        options
+    };
+    return guard;
 }
 /**
  * Declarative Guard: Enforces that the active user/member possesses one of the allowed roles.
@@ -29,7 +34,7 @@ export function requireAuth(options = {}) {
  */
 export function requireRole(roles, options = {}) {
     const allowedRoles = Array.isArray(roles) ? roles : [roles];
-    return (event) => {
+    const guard = (event) => {
         const locals = event.locals;
         const user = locals?.user;
         if (!user) {
@@ -54,6 +59,12 @@ export function requireRole(roles, options = {}) {
             });
         }
     };
+    guard._yaxaGuard = {
+        type: 'role',
+        roles: allowedRoles,
+        options
+    };
+    return guard;
 }
 const rateLimitStore = new Map();
 // Periodic cleanup of stale rate-limit buckets (every 5 minutes)
@@ -77,7 +88,7 @@ if (typeof setInterval !== 'undefined') {
 export function rateLimit(options = {}) {
     const points = options.points ?? 60;
     const windowMs = (options.windowSeconds ?? 60) * 1000;
-    return (event) => {
+    const guard = (event) => {
         let key;
         if (options.keyGenerator) {
             key = options.keyGenerator(event);
@@ -122,6 +133,11 @@ export function rateLimit(options = {}) {
         }
         bucket.tokens -= 1;
     };
+    guard._yaxaGuard = {
+        type: 'rateLimit',
+        options: { points, windowSeconds: options.windowSeconds ?? 60 }
+    };
+    return guard;
 }
 /**
  * Combines multiple guards into a single composite guard.

package/dist/server/endpoint/index.js

@@ -1,5 +1,6 @@
 import { isProblemDetails, problemResponse } from './problem';
 import { validateData } from './validate';
+import { globalApiRegistry } from '../openapi/registry';
 /**
  * Parses URLSearchParams into a plain key-value object.
  * Duplicate keys are parsed into arrays.
@@ -230,6 +231,9 @@ export function yaxaEndpoint(config) {
     };
     // Attach configuration metadata for runtime reflection and OpenAPI generation (Milestone 3)
     handler._yaxaConfig = config;
+    if (config.path && config.method) {
+        globalApiRegistry.register(config.path, { [config.method]: handler });
+    }
     return handler;
 }
 export * from './types';

package/dist/server/endpoint/types.d.ts

@@ -137,6 +137,13 @@ export interface YaxaEndpointConfig<TBodySchema = any, TQuerySchema = any, TPara
     description?: string;
     tags?: string[];
     deprecated?: boolean;
+    operationId?: string;
+    path?: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | string;
+    responses?: Record<number, {
+        description: string;
+        schema?: any;
+    }>;
     /**
      * Core business logic handler.
      */

package/dist/server/index.d.ts

@@ -24,3 +24,5 @@ export { getS3Client, createPresignedUploadUrl, createS3UploadHandler } from './
 export type { S3StorageConfig, PresignedUploadOptions, PresignedUploadResult, S3UploadHandlerOptions } from './storage/index';
 export { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails, requireAuth, requireRole, rateLimit, composeGuards, validateData } from './endpoint/index';
 export type { YaxaEndpointConfig, YaxaEndpointContext, YaxaEndpointSchemaConfig, YaxaInterceptor, Guard, GuardResult, ProblemDetails, CreateProblemOptions, RequireAuthOptions, RequireRoleOptions, RateLimitOptions, AnyValidator, InferValidatorOutput, ValidationOutcome, ValidationSuccess, ValidationFailure } from './endpoint/index';
+export { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './openapi/index';
+export type { OpenApiSpec31, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, GenerateOpenApiOptions, ApiDocsOptions, ApiDocsTheme, EndpointLike, EndpointMap } from './openapi/index';

package/dist/server/index.js

@@ -20,3 +20,5 @@ export { getResendClient, sendMagicLinkEmail, sendWelcomeEmail } from './email/i
 export { getS3Client, createPresignedUploadUrl, createS3UploadHandler } from './storage/index';
 // Endpoint Pipeline, Guards & RFC 7807 Validation (Milestone 1)
 export { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails, requireAuth, requireRole, rateLimit, composeGuards, validateData } from './endpoint/index';
+// Auto-Generated OpenAPI 3.1 & Interactive Docs (Milestone 3)
+export { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './openapi/index';

package/dist/server/openapi/generator.d.ts

@@ -0,0 +1,5 @@
+import type { GenerateOpenApiOptions, OpenApiSpec31 } from './types';
+/**
+ * Generates an OpenAPI 3.1.0 document from registered yaxaEndpoints.
+ */
+export declare function generateOpenApiSpec(options?: GenerateOpenApiOptions): OpenApiSpec31;

package/dist/server/openapi/generator.js

@@ -0,0 +1,317 @@
+import { convertToJsonSchema } from './schema';
+import { globalApiRegistry } from './registry';
+/**
+ * Standard RFC 7807 Problem Details Schema for OpenAPI Components.
+ */
+const PROBLEM_DETAILS_SCHEMA = {
+    type: 'object',
+    properties: {
+        type: { type: 'string', format: 'uri', example: 'https://yaxa.dev/errors/validation-failed' },
+        title: { type: 'string', example: 'Unprocessable Entity' },
+        status: { type: 'integer', example: 422 },
+        detail: { type: 'string', example: 'Validation failed for 1 parameter(s).' },
+        instance: { type: 'string' },
+        invalidParams: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', example: 'body.email' },
+                    reason: { type: 'string', example: 'Invalid email address' }
+                },
+                required: ['name', 'reason']
+            }
+        }
+    },
+    required: ['type', 'title', 'status']
+};
+/**
+ * Extracts parameter list from a converted JSON schema.
+ */
+function extractParametersFromSchema(jsonSchema, location) {
+    if (!jsonSchema || typeof jsonSchema !== 'object' || !jsonSchema.properties) {
+        return [];
+    }
+    const requiredList = Array.isArray(jsonSchema.required) ? jsonSchema.required : [];
+    const parameters = [];
+    for (const [key, propSchema] of Object.entries(jsonSchema.properties)) {
+        parameters.push({
+            name: key,
+            in: location,
+            required: location === 'path' ? true : requiredList.includes(key),
+            description: propSchema?.description,
+            deprecated: propSchema?.deprecated,
+            schema: propSchema
+        });
+    }
+    return parameters;
+}
+/**
+ * Resolves YaxaEndpointConfig from an endpoint function or config object.
+ */
+function resolveConfig(endpoint) {
+    if (!endpoint)
+        return null;
+    if (typeof endpoint === 'function' && '_yaxaConfig' in endpoint) {
+        return endpoint._yaxaConfig;
+    }
+    if (typeof endpoint === 'object' && 'handle' in endpoint) {
+        return endpoint;
+    }
+    return null;
+}
+/**
+ * Generates an OpenAPI 3.1.0 document from registered yaxaEndpoints.
+ */
+export function generateOpenApiSpec(options = {}) {
+    const title = options.title || 'Yaxa SvelteKit API';
+    const version = options.version || '1.0.0';
+    const description = options.description || 'Auto-generated OpenAPI 3.1 contract via yaxa-svelte.';
+    const registry = options.registry || globalApiRegistry;
+    const registeredEndpoints = registry.getEndpoints();
+    // Merge manual options.endpoints if provided
+    const mergedEndpoints = {
+        ...registeredEndpoints
+    };
+    if (options.endpoints) {
+        for (const [rawPath, methods] of Object.entries(options.endpoints)) {
+            const normalizedPath = registry.normalizePath(rawPath);
+            if (!mergedEndpoints[normalizedPath]) {
+                mergedEndpoints[normalizedPath] = {};
+            }
+            for (const [method, handler] of Object.entries(methods)) {
+                mergedEndpoints[normalizedPath][method.toUpperCase()] = handler;
+            }
+        }
+    }
+    const paths = {};
+    const securitySchemes = {};
+    let usesSecurity = false;
+    for (const [path, methods] of Object.entries(mergedEndpoints)) {
+        paths[path] = {};
+        for (const [method, endpoint] of Object.entries(methods)) {
+            const config = resolveConfig(endpoint);
+            const methodLower = method.toLowerCase();
+            if (!config) {
+                // Fallback for raw RequestHandler
+                paths[path][methodLower] = {
+                    summary: `${method.toUpperCase()} ${path}`,
+                    responses: {
+                        '200': { description: 'Successful response' }
+                    }
+                };
+                continue;
+            }
+            const parameters = [];
+            // 1. Path Params
+            if (config.schema?.params) {
+                const paramsSchema = convertToJsonSchema(config.schema.params);
+                parameters.push(...extractParametersFromSchema(paramsSchema, 'path'));
+            }
+            else {
+                // Detect {param} placeholders in path and add basic string parameters
+                const pathParamMatches = path.match(/\{(\w+)\}/g);
+                if (pathParamMatches) {
+                    for (const match of pathParamMatches) {
+                        const paramName = match.slice(1, -1);
+                        parameters.push({
+                            name: paramName,
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' }
+                        });
+                    }
+                }
+            }
+            // 2. Query Params
+            if (config.schema?.query) {
+                const querySchema = convertToJsonSchema(config.schema.query);
+                parameters.push(...extractParametersFromSchema(querySchema, 'query'));
+            }
+            // 3. Header Params
+            if (config.schema?.headers) {
+                const headersSchema = convertToJsonSchema(config.schema.headers);
+                parameters.push(...extractParametersFromSchema(headersSchema, 'header'));
+            }
+            // 4. Request Body
+            let requestBody = undefined;
+            if (config.schema?.body && method !== 'GET' && method !== 'HEAD') {
+                const bodySchema = convertToJsonSchema(config.schema.body);
+                requestBody = {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: bodySchema
+                        }
+                    }
+                };
+            }
+            // 5. Responses
+            const responses = {};
+            const successStatus = config.status
+                ? String(config.status)
+                : method === 'POST'
+                    ? '201'
+                    : '200';
+            if (config.responses) {
+                for (const [statusCode, resp] of Object.entries(config.responses)) {
+                    responses[String(statusCode)] = {
+                        description: resp.description,
+                        content: resp.schema
+                            ? {
+                                'application/json': {
+                                    schema: convertToJsonSchema(resp.schema)
+                                }
+                            }
+                            : undefined
+                    };
+                }
+            }
+            if (!responses[successStatus]) {
+                responses[successStatus] = {
+                    description: successStatus === '201'
+                        ? 'Created'
+                        : successStatus === '204'
+                            ? 'No Content'
+                            : 'Successful Operation',
+                    content: successStatus !== '204'
+                        ? {
+                            'application/json': {
+                                schema: { type: 'object' }
+                            }
+                        }
+                        : undefined
+                };
+            }
+            // 6. Guard Reflection (Security & Error Status Codes)
+            let hasAuthGuard = false;
+            let hasRoleGuard = false;
+            let roleGuardRoles = [];
+            let hasRateLimitGuard = false;
+            let rateLimitRetryAfter = 60;
+            if (config.guards && config.guards.length > 0) {
+                for (const guard of config.guards) {
+                    const meta = guard._yaxaGuard;
+                    if (meta) {
+                        if (meta.type === 'auth') {
+                            hasAuthGuard = true;
+                        }
+                        else if (meta.type === 'role') {
+                            hasRoleGuard = true;
+                            if (meta.roles)
+                                roleGuardRoles = meta.roles;
+                        }
+                        else if (meta.type === 'rateLimit') {
+                            hasRateLimitGuard = true;
+                            if (meta.options?.windowSeconds) {
+                                rateLimitRetryAfter = meta.options.windowSeconds;
+                            }
+                        }
+                    }
+                }
+            }
+            const operationSecurity = [];
+            if (hasAuthGuard || hasRoleGuard) {
+                usesSecurity = true;
+                securitySchemes['BearerAuth'] = {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT',
+                    description: 'Standard Bearer Token Header (`Authorization: Bearer <token>`)'
+                };
+                securitySchemes['CookieAuth'] = {
+                    type: 'apiKey',
+                    in: 'cookie',
+                    name: 'better-auth.session_token',
+                    description: 'Session cookie via Better-Auth'
+                };
+                operationSecurity.push({ BearerAuth: [] }, { CookieAuth: [] });
+                responses['401'] = {
+                    description: 'Unauthorized (RFC 7807 Problem Details)',
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            if (hasRoleGuard) {
+                responses['403'] = {
+                    description: `Forbidden — Insufficient role permissions. Requires: [${roleGuardRoles.join(', ')}]`,
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 7. Schema Validation Error (422)
+            if (config.schema &&
+                (config.schema.body || config.schema.query || config.schema.params || config.schema.headers)) {
+                responses['422'] = {
+                    description: 'Unprocessable Entity — Schema validation failed (RFC 7807)',
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 8. Rate Limit Error (429)
+            if (hasRateLimitGuard) {
+                responses['429'] = {
+                    description: 'Too Many Requests — Rate limit exceeded (RFC 7807)',
+                    headers: {
+                        'Retry-After': {
+                            description: 'Seconds to wait before retrying',
+                            schema: { type: 'integer', example: rateLimitRetryAfter }
+                        }
+                    },
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 9. Standard 500 Sanitized Error
+            responses['500'] = {
+                description: 'Internal Server Error — Sanitized exception (RFC 7807)',
+                content: {
+                    'application/problem+json': {
+                        schema: { $ref: '#/components/schemas/ProblemDetails' }
+                    }
+                }
+            };
+            const operation = {
+                summary: config.summary || `${method.toUpperCase()} ${path}`,
+                description: config.description,
+                operationId: config.operationId ||
+                    `${methodLower}_${path.replace(/[/{}]+/g, '_').replace(/^_+|_+$/g, '')}`,
+                tags: config.tags || (path.split('/')[2] ? [path.split('/')[2]] : ['Default']),
+                deprecated: config.deprecated,
+                parameters: parameters.length > 0 ? parameters : undefined,
+                requestBody,
+                responses,
+                security: operationSecurity.length > 0 ? operationSecurity : undefined
+            };
+            paths[path][methodLower] = operation;
+        }
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title,
+            version,
+            description
+        },
+        servers: options.servers || [{ url: '/', description: 'Current Environment' }],
+        paths,
+        components: {
+            schemas: {
+                ProblemDetails: PROBLEM_DETAILS_SCHEMA
+            },
+            securitySchemes: usesSecurity ? securitySchemes : undefined
+        }
+    };
+}

package/dist/server/openapi/handler.d.ts

@@ -0,0 +1,7 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { ApiDocsOptions } from './types';
+/**
+ * Creates a turnkey SvelteKit RequestHandler that generates an interactive OpenAPI 3.1 documentation
+ * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
+ */
+export declare function createApiDocsHandler(options?: ApiDocsOptions): RequestHandler;

package/dist/server/openapi/handler.js

@@ -0,0 +1,117 @@
+import { generateOpenApiSpec } from './generator';
+function renderScalarHtml(specJson, title) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <style>
+      body { margin: 0; background-color: #0f172a; }
+    </style>
+  </head>
+  <body>
+    <script id="api-reference" data-configuration='{"darkMode":true,"layout":"modern"}' type="application/json">
+      ${specJson}
+    </script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>`;
+}
+function renderSwaggerHtml(specJson, title) {
+    return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+    <style>
+      body { margin: 0; background: #fafafa; }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        spec: ${specJson},
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIBundle.SwaggerUIStandalonePreset
+        ],
+        layout: "BaseLayout"
+      });
+    </script>
+  </body>
+</html>`;
+}
+function renderRedocHtml(specJson, title) {
+    return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <style>
+      body { margin: 0; padding: 0; }
+    </style>
+  </head>
+  <body>
+    <div id="redoc-container"></div>
+    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+    <script>
+      Redoc.init(${specJson}, {
+        scrollYOffset: 50,
+        theme: {
+          colors: { primary: { main: '#3b82f6' } }
+        }
+      }, document.getElementById('redoc-container'));
+    </script>
+  </body>
+</html>`;
+}
+/**
+ * Creates a turnkey SvelteKit RequestHandler that generates an interactive OpenAPI 3.1 documentation
+ * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
+ */
+export function createApiDocsHandler(options = {}) {
+    const theme = options.theme || 'scalar';
+    return async (event) => {
+        const { url, request } = event;
+        const format = url.searchParams.get('format');
+        const acceptHeader = request.headers.get('accept') || '';
+        const spec = generateOpenApiSpec(options);
+        // If caller requests JSON via query param, accept header, or path ending in .json
+        if (format === 'json' ||
+            acceptHeader.includes('application/json') ||
+            url.pathname.endsWith('/openapi.json')) {
+            return Response.json(spec, {
+                headers: {
+                    'content-type': 'application/json; charset=utf-8',
+                    'cache-control': 'public, max-age=60'
+                }
+            });
+        }
+        // Render Interactive HTML Docs
+        const specJson = JSON.stringify(spec);
+        let html;
+        if (theme === 'swagger') {
+            html = renderSwaggerHtml(specJson, spec.info.title);
+        }
+        else if (theme === 'redoc') {
+            html = renderRedocHtml(specJson, spec.info.title);
+        }
+        else {
+            html = renderScalarHtml(specJson, spec.info.title);
+        }
+        return new Response(html, {
+            headers: {
+                'content-type': 'text/html; charset=utf-8',
+                'cache-control': 'public, max-age=300'
+            }
+        });
+    };
+}

package/dist/server/openapi/index.d.ts

@@ -0,0 +1,5 @@
+export { generateOpenApiSpec } from './generator';
+export { createApiDocsHandler } from './handler';
+export { ApiRegistry, createApiRegistry, globalApiRegistry } from './registry';
+export { convertToJsonSchema } from './schema';
+export type { OpenApiSpec31, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, GenerateOpenApiOptions, ApiDocsOptions, ApiDocsTheme, EndpointLike, EndpointMap } from './types';

package/dist/server/openapi/index.js

@@ -0,0 +1,4 @@
+export { generateOpenApiSpec } from './generator';
+export { createApiDocsHandler } from './handler';
+export { ApiRegistry, createApiRegistry, globalApiRegistry } from './registry';
+export { convertToJsonSchema } from './schema';

package/dist/server/openapi/openapi.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/openapi/openapi.test.js

@@ -0,0 +1,219 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { z } from 'zod';
+import { createMockRequestEvent } from '../../testing/index.js';
+import { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './index.js';
+import { yaxaEndpoint } from '../endpoint/index.js';
+import { requireAuth, requireRole, rateLimit } from '../endpoint/guards.js';
+describe('OpenAPI 3.1 Schema Engine', () => {
+    it('converts Zod schema into compliant JSON Schema', () => {
+        const schema = z.object({
+            title: z.string().min(3),
+            count: z.number().optional(),
+            role: z.enum(['admin', 'member'])
+        });
+        const jsonSchema = convertToJsonSchema(schema);
+        expect(jsonSchema.type).toBe('object');
+        expect(jsonSchema.properties.title.type).toBe('string');
+        expect(jsonSchema.properties.count.type).toBe('number');
+        expect(jsonSchema.required).toContain('title');
+        expect(jsonSchema.required).toContain('role');
+        expect(jsonSchema.required).not.toContain('count');
+    });
+});
+describe('API Route Registry', () => {
+    let registry;
+    beforeEach(() => {
+        registry = createApiRegistry();
+        globalApiRegistry.clear();
+    });
+    it('normalizes SvelteKit bracket path params to OpenAPI curly braces', () => {
+        expect(registry.normalizePath('/api/items/[id]')).toBe('/api/items/{id}');
+        expect(registry.normalizePath('/api/orgs/[orgSlug]/users/[userId]')).toBe('/api/orgs/{orgSlug}/users/{userId}');
+        expect(registry.normalizePath('/api/files/[...rest]')).toBe('/api/files/{rest}');
+    });
+    it('registers endpoints and retrieves them in normalized form', () => {
+        const getHandler = yaxaEndpoint({ handle: () => [] });
+        registry.register('/api/users/[id]', { GET: getHandler });
+        const endpoints = registry.getEndpoints();
+        expect(endpoints['/api/users/{id}']).toBeDefined();
+        expect(endpoints['/api/users/{id}']['GET']).toBe(getHandler);
+    });
+});
+describe('generateOpenApiSpec Engine', () => {
+    const ItemParamsSchema = z.object({
+        id: z.string()
+    });
+    const ItemQuerySchema = z.object({
+        filter: z.string().optional(),
+        limit: z.number().optional()
+    });
+    const CreateItemBodySchema = z.object({
+        name: z.string().min(2),
+        price: z.number().positive()
+    });
+    it('generates complete OpenAPI 3.1 document with parameters, body and tags', () => {
+        const registry = createApiRegistry();
+        const getEndpoint = yaxaEndpoint({
+            summary: 'Get Item By ID',
+            description: 'Retrieves an item record by its unique ID',
+            tags: ['Items'],
+            schema: {
+                params: ItemParamsSchema,
+                query: ItemQuerySchema
+            },
+            handle: ({ params }) => ({ id: params.id })
+        });
+        const postEndpoint = yaxaEndpoint({
+            summary: 'Create Item',
+            tags: ['Items'],
+            schema: {
+                body: CreateItemBodySchema
+            },
+            handle: ({ body }) => body
+        });
+        registry.register('/api/items/[id]', { GET: getEndpoint });
+        registry.register('/api/items', { POST: postEndpoint });
+        const spec = generateOpenApiSpec({
+            title: 'Inventory API',
+            version: '2.0.0',
+            description: 'Test Inventory System',
+            registry
+        });
+        expect(spec.openapi).toBe('3.1.0');
+        expect(spec.info.title).toBe('Inventory API');
+        expect(spec.info.version).toBe('2.0.0');
+        // Verify GET /api/items/{id}
+        const getOp = spec.paths['/api/items/{id}']['get'];
+        expect(getOp.summary).toBe('Get Item By ID');
+        expect(getOp.tags).toEqual(['Items']);
+        expect(getOp.parameters).toHaveLength(3); // id (path), filter (query), limit (query)
+        const idParam = getOp.parameters?.find((p) => p.name === 'id');
+        expect(idParam?.in).toBe('path');
+        expect(idParam?.required).toBe(true);
+        // Verify POST /api/items
+        const postOp = spec.paths['/api/items']['post'];
+        expect(postOp.summary).toBe('Create Item');
+        expect(postOp.requestBody).toBeDefined();
+        expect(postOp.requestBody?.content['application/json'].schema?.type).toBe('object');
+        expect(postOp.responses['201']).toBeDefined();
+        expect(postOp.responses['422']).toBeDefined(); // Schema validation failed
+    });
+    it('deduces security schemes and RFC 7807 responses from guards automatically', () => {
+        const registry = createApiRegistry();
+        const secureEndpoint = yaxaEndpoint({
+            guards: [
+                requireAuth(),
+                requireRole(['admin', 'billing_manager']),
+                rateLimit({ points: 15, windowSeconds: 60 })
+            ],
+            schema: {
+                body: CreateItemBodySchema
+            },
+            handle: () => ({ ok: true })
+        });
+        registry.register('/api/secure-action', { POST: secureEndpoint });
+        const spec = generateOpenApiSpec({ registry });
+        const op = spec.paths['/api/secure-action']['post'];
+        // Security schemes attached
+        expect(spec.components?.securitySchemes?.BearerAuth).toBeDefined();
+        expect(spec.components?.securitySchemes?.CookieAuth).toBeDefined();
+        expect(op.security).toBeDefined();
+        // Guard error responses generated
+        expect(op.responses['401']).toBeDefined();
+        expect(op.responses['403']).toBeDefined();
+        expect(op.responses['403'].description).toContain('admin, billing_manager');
+        expect(op.responses['422']).toBeDefined();
+        expect(op.responses['429']).toBeDefined();
+        expect(op.responses['429'].headers?.['Retry-After']).toBeDefined();
+        expect(op.responses['500']).toBeDefined();
+        // Components schema ProblemDetails registered
+        expect(spec.components?.schemas?.ProblemDetails).toBeDefined();
+    });
+    it('supports self-registration via yaxaEndpoint path and method metadata', () => {
+        globalApiRegistry.clear();
+        yaxaEndpoint({
+            path: '/api/v1/auto-registered',
+            method: 'GET',
+            summary: 'Auto Registered Route',
+            handle: () => 'ok'
+        });
+        const spec = generateOpenApiSpec();
+        expect(spec.paths['/api/v1/auto-registered']?.['get']?.summary).toBe('Auto Registered Route');
+    });
+});
+describe('createApiDocsHandler Endpoint', () => {
+    it('serves OpenAPI 3.1 JSON when format=json query parameter is present', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Store API',
+            version: '1.2.3'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs?format=json'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('application/json');
+        const json = await response.json();
+        expect(json.openapi).toBe('3.1.0');
+        expect(json.info.title).toBe('Store API');
+        expect(json.info.version).toBe('1.2.3');
+    });
+    it('serves OpenAPI 3.1 JSON when Accept header requests application/json', async () => {
+        const handler = createApiDocsHandler();
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs',
+            headers: { accept: 'application/json' }
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('application/json');
+    });
+    it('renders Scalar HTML documentation by default', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Scalar Docs Test',
+            theme: 'scalar'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('text/html');
+        const html = await response.text();
+        expect(html).toContain('<title>Scalar Docs Test</title>');
+        expect(html).toContain('@scalar/api-reference');
+        expect(html).toContain('id="api-reference"');
+    });
+    it('renders Swagger UI HTML when theme is swagger', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Swagger Docs Test',
+            theme: 'swagger'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('text/html');
+        const html = await response.text();
+        expect(html).toContain('<title>Swagger Docs Test</title>');
+        expect(html).toContain('swagger-ui-dist');
+        expect(html).toContain('SwaggerUIBundle');
+    });
+    it('renders Redoc HTML when theme is redoc', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Redoc Docs Test',
+            theme: 'redoc'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('text/html');
+        const html = await response.text();
+        expect(html).toContain('<title>Redoc Docs Test</title>');
+        expect(html).toContain('redoc.standalone.js');
+        expect(html).toContain('redoc-container');
+    });
+});

package/dist/server/openapi/registry.d.ts

@@ -0,0 +1,35 @@
+import type { EndpointLike, EndpointMap } from './types';
+/**
+ * Route & Endpoint Registry for OpenAPI discovery and introspection.
+ */
+export declare class ApiRegistry {
+    private endpoints;
+    /**
+     * Registers endpoints for a given path.
+     * @param path SvelteKit route path (e.g. '/api/projects' or '/api/projects/[id]')
+     * @param methods Map of HTTP methods to handlers or yaxaEndpoint configs
+     */
+    register(path: string, methods: Record<string, EndpointLike>): this;
+    /**
+     * Retrieves all registered endpoints.
+     */
+    getEndpoints(): EndpointMap;
+    /**
+     * Clears registered endpoints (useful in testing).
+     */
+    clear(): void;
+    /**
+     * Normalizes SvelteKit path parameters to OpenAPI format:
+     * '/api/projects/[id]' -> '/api/projects/{id}'
+     * '/api/teams/[orgSlug]/members/[userId]' -> '/api/teams/{orgSlug}/members/{userId}'
+     */
+    normalizePath(path: string): string;
+}
+/**
+ * Global singleton API registry for zero-config route registration.
+ */
+export declare const globalApiRegistry: ApiRegistry;
+/**
+ * Creates a new isolated API registry instance.
+ */
+export declare function createApiRegistry(): ApiRegistry;

package/dist/server/openapi/registry.js

@@ -0,0 +1,51 @@
+/**
+ * Route & Endpoint Registry for OpenAPI discovery and introspection.
+ */
+export class ApiRegistry {
+    endpoints = {};
+    /**
+     * Registers endpoints for a given path.
+     * @param path SvelteKit route path (e.g. '/api/projects' or '/api/projects/[id]')
+     * @param methods Map of HTTP methods to handlers or yaxaEndpoint configs
+     */
+    register(path, methods) {
+        const normalizedPath = this.normalizePath(path);
+        if (!this.endpoints[normalizedPath]) {
+            this.endpoints[normalizedPath] = {};
+        }
+        for (const [method, handler] of Object.entries(methods)) {
+            this.endpoints[normalizedPath][method.toUpperCase()] = handler;
+        }
+        return this;
+    }
+    /**
+     * Retrieves all registered endpoints.
+     */
+    getEndpoints() {
+        return this.endpoints;
+    }
+    /**
+     * Clears registered endpoints (useful in testing).
+     */
+    clear() {
+        this.endpoints = {};
+    }
+    /**
+     * Normalizes SvelteKit path parameters to OpenAPI format:
+     * '/api/projects/[id]' -> '/api/projects/{id}'
+     * '/api/teams/[orgSlug]/members/[userId]' -> '/api/teams/{orgSlug}/members/{userId}'
+     */
+    normalizePath(path) {
+        return path.replace(/\[\.\.\.(\w+)\]/g, '{$1}').replace(/\[(\w+)\]/g, '{$1}');
+    }
+}
+/**
+ * Global singleton API registry for zero-config route registration.
+ */
+export const globalApiRegistry = new ApiRegistry();
+/**
+ * Creates a new isolated API registry instance.
+ */
+export function createApiRegistry() {
+    return new ApiRegistry();
+}

package/dist/server/openapi/schema.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Converts a Zod or Standard Schema validator into a compliant OpenAPI 3.1 JSON Schema.
+ */
+export declare function convertToJsonSchema(validator: any): Record<string, any>;

package/dist/server/openapi/schema.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+/**
+ * Converts a Zod or Standard Schema validator into a compliant OpenAPI 3.1 JSON Schema.
+ */
+export function convertToJsonSchema(validator) {
+    if (!validator) {
+        return { type: 'object' };
+    }
+    // 1. Zod native JSON schema converter
+    if (typeof z?.toJSONSchema === 'function') {
+        try {
+            const jsonSchema = z.toJSONSchema(validator);
+            if (jsonSchema && typeof jsonSchema === 'object') {
+                const cleanSchema = { ...jsonSchema };
+                delete cleanSchema.$schema;
+                return cleanSchema;
+            }
+        }
+        catch {
+            // Fall through to other strategies
+        }
+    }
+    // 2. Check if validator has built-in jsonSchema method/property
+    if (typeof validator.jsonSchema === 'function') {
+        try {
+            const res = validator.jsonSchema();
+            const cleanSchema = { ...res };
+            delete cleanSchema.$schema;
+            return cleanSchema;
+        }
+        catch {
+            // Fall through
+        }
+    }
+    if (typeof validator.jsonSchema === 'object' && validator.jsonSchema !== null) {
+        const cleanSchema = { ...validator.jsonSchema };
+        delete cleanSchema.$schema;
+        return cleanSchema;
+    }
+    // 3. Heuristic for common object schema shapes
+    if (typeof validator === 'object' && validator !== null) {
+        if ('shape' in validator && typeof validator.shape === 'object') {
+            const properties = {};
+            const required = [];
+            for (const [key, val] of Object.entries(validator.shape)) {
+                properties[key] = convertToJsonSchema(val);
+                if (!val?.isOptional?.()) {
+                    required.push(key);
+                }
+            }
+            return {
+                type: 'object',
+                properties,
+                ...(required.length > 0 ? { required } : {})
+            };
+        }
+    }
+    return { type: 'string' };
+}

package/dist/server/openapi/types.d.ts

@@ -0,0 +1,127 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { YaxaEndpointConfig } from '../endpoint/types';
+/**
+ * OpenAPI 3.1 Parameter Object
+ */
+export interface OpenApiParameter {
+    name: string;
+    in: 'query' | 'header' | 'path' | 'cookie';
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: Record<string, any>;
+    example?: any;
+}
+/**
+ * OpenAPI 3.1 Request Body Object
+ */
+export interface OpenApiRequestBody {
+    description?: string;
+    required?: boolean;
+    content: {
+        [mediaType: string]: {
+            schema?: Record<string, any>;
+            example?: any;
+        };
+    };
+}
+/**
+ * OpenAPI 3.1 Response Object
+ */
+export interface OpenApiResponse {
+    description: string;
+    headers?: Record<string, any>;
+    content?: {
+        [mediaType: string]: {
+            schema?: Record<string, any>;
+            example?: any;
+        };
+    };
+}
+/**
+ * OpenAPI 3.1 Operation Object
+ */
+export interface OpenApiOperation {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    tags?: string[];
+    parameters?: OpenApiParameter[];
+    requestBody?: OpenApiRequestBody;
+    responses: Record<string, OpenApiResponse>;
+    deprecated?: boolean;
+    security?: Array<Record<string, string[]>>;
+}
+/**
+ * OpenAPI 3.1 Specification Object
+ */
+export interface OpenApiSpec31 {
+    openapi: '3.1.0';
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+        termsOfService?: string;
+        contact?: {
+            name?: string;
+            url?: string;
+            email?: string;
+        };
+        license?: {
+            name: string;
+            url?: string;
+        };
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: {
+        [path: string]: {
+            [method: string]: OpenApiOperation;
+        };
+    };
+    components?: {
+        schemas?: Record<string, any>;
+        securitySchemes?: Record<string, any>;
+        responses?: Record<string, OpenApiResponse>;
+        parameters?: Record<string, OpenApiParameter>;
+    };
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+export type EndpointLike = (RequestHandler & {
+    _yaxaConfig?: YaxaEndpointConfig;
+}) | YaxaEndpointConfig;
+export type EndpointMap = Record<string, Record<string, EndpointLike>>;
+export interface GenerateOpenApiOptions {
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    endpoints?: EndpointMap;
+    registry?: any;
+}
+export type ApiDocsTheme = 'scalar' | 'swagger' | 'redoc';
+export interface ApiDocsOptions extends GenerateOpenApiOptions {
+    /**
+     * Interactive UI theme:
+     * - 'scalar' (default): Modern, dark-mode native, high contrast developer reference.
+     * - 'swagger': Classic Swagger UI with interactive Try-It-Out console.
+     * - 'redoc': Clean 3-panel technical documentation format.
+     */
+    theme?: ApiDocsTheme;
+    /**
+     * Mount path of documentation endpoint (default: '/api/docs').
+     */
+    docsPath?: string;
+    /**
+     * CDN version/URL overrides if needed.
+     */
+    cdnUrl?: string;
+}

package/dist/server/openapi/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaxa-svelte",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "The Intuitive Svelte UI Library — Nuxt UI v4 equivalent for SvelteKit 2 & 3 & Svelte 5 with automated SEO, dynamic OpenGraph cards, sitemaps, robots.txt, and Tailwind CSS v4.",
   "license": "MIT",
   "homepage": "https://yaxa.vercel.app",