yaxa-svelte 2.1.0 → 2.3.0

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