yaxa-svelte 2.2.0 → 2.4.0

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.4.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",