yaxa-svelte 2.1.0 → 2.3.0

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

@@ -0,0 +1,14 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { YaxaEndpointConfig } from './types';
+/**
+ * Wraps SvelteKit +server.ts request handlers into an opinionated,
+ * declarative, type-safe execution pipeline with Guards, Multi-Engine
+ * Validation, and RFC 7807 Problem Details.
+ */
+export declare function yaxaEndpoint<TBodySchema = any, TQuerySchema = any, TParamsSchema = any, THeadersSchema = any, TResult = any>(config: YaxaEndpointConfig<TBodySchema, TQuerySchema, TParamsSchema, THeadersSchema, TResult>): RequestHandler & {
+    _yaxaConfig: typeof config;
+};
+export * from './types';
+export * from './problem';
+export * from './guards';
+export * from './validate';

package/dist/server/endpoint/index.js

@@ -0,0 +1,242 @@
+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.
+ */
+function parseSearchParamsToObject(searchParams) {
+    const result = {};
+    for (const key of searchParams.keys()) {
+        const allValues = searchParams.getAll(key);
+        if (allValues.length > 1) {
+            result[key] = allValues;
+        }
+        else if (allValues.length === 1) {
+            result[key] = allValues[0];
+        }
+    }
+    return result;
+}
+/**
+ * Safely parses request body based on Content-Type.
+ */
+async function parseRequestBody(request) {
+    const contentType = request.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+        try {
+            const text = await request.text();
+            if (!text.trim()) {
+                return { ok: true, body: undefined };
+            }
+            return { ok: true, body: JSON.parse(text) };
+        }
+        catch {
+            return {
+                ok: false,
+                response: problemResponse({
+                    status: 400,
+                    title: 'Bad Request',
+                    detail: 'Malformed JSON payload in request body.',
+                    type: 'https://yaxa.dev/errors/malformed-json'
+                })
+            };
+        }
+    }
+    if (contentType.includes('application/x-www-form-urlencoded') ||
+        contentType.includes('multipart/form-data')) {
+        try {
+            const formData = await request.formData();
+            const formObj = {};
+            formData.forEach((val, key) => {
+                if (key in formObj) {
+                    if (Array.isArray(formObj[key])) {
+                        formObj[key].push(val);
+                    }
+                    else {
+                        formObj[key] = [formObj[key], val];
+                    }
+                }
+                else {
+                    formObj[key] = val;
+                }
+            });
+            return { ok: true, body: formObj };
+        }
+        catch {
+            return {
+                ok: false,
+                response: problemResponse({
+                    status: 400,
+                    title: 'Bad Request',
+                    detail: 'Malformed form-data in request body.'
+                })
+            };
+        }
+    }
+    // Plain text or other payloads
+    try {
+        const text = await request.text();
+        return { ok: true, body: text ? text : undefined };
+    }
+    catch {
+        return { ok: true, body: undefined };
+    }
+}
+/**
+ * Wraps SvelteKit +server.ts request handlers into an opinionated,
+ * declarative, type-safe execution pipeline with Guards, Multi-Engine
+ * Validation, and RFC 7807 Problem Details.
+ */
+export function yaxaEndpoint(config) {
+    const handler = async (event) => {
+        const { request, url, locals, params } = event;
+        // 1. Execute Declarative Guards in Series
+        if (config.guards && config.guards.length > 0) {
+            for (const guard of config.guards) {
+                const result = await guard(event);
+                if (result instanceof Response) {
+                    return result;
+                }
+                if (isProblemDetails(result)) {
+                    return problemResponse(result);
+                }
+                if (result === false) {
+                    return problemResponse({
+                        status: 403,
+                        title: 'Forbidden',
+                        detail: 'Access denied by endpoint guard.'
+                    });
+                }
+            }
+        }
+        // 2. Parse Raw Inputs
+        const rawParams = params || {};
+        const rawQuery = parseSearchParamsToObject(url.searchParams);
+        const rawHeaders = {};
+        request.headers.forEach((val, key) => {
+            rawHeaders[key.toLowerCase()] = val;
+        });
+        let rawBody;
+        if (request.method !== 'GET' && request.method !== 'HEAD') {
+            const parsed = await parseRequestBody(request);
+            if (!parsed.ok) {
+                return parsed.response;
+            }
+            rawBody = parsed.body;
+        }
+        // 3. Multi-Engine Schema Validation (Standard Schema, Zod, etc.)
+        const allInvalidParams = [];
+        let validatedBody = rawBody;
+        let validatedQuery = rawQuery;
+        let validatedParams = rawParams;
+        let validatedHeaders = rawHeaders;
+        if (config.schema) {
+            if (config.schema.params) {
+                const res = await validateData(config.schema.params, rawParams, 'params');
+                if (res.success)
+                    validatedParams = res.data;
+                else
+                    allInvalidParams.push(...res.invalidParams);
+            }
+            if (config.schema.query) {
+                const res = await validateData(config.schema.query, rawQuery, 'query');
+                if (res.success)
+                    validatedQuery = res.data;
+                else
+                    allInvalidParams.push(...res.invalidParams);
+            }
+            if (config.schema.headers) {
+                const res = await validateData(config.schema.headers, rawHeaders, 'headers');
+                if (res.success)
+                    validatedHeaders = res.data;
+                else
+                    allInvalidParams.push(...res.invalidParams);
+            }
+            if (config.schema.body && request.method !== 'GET' && request.method !== 'HEAD') {
+                const res = await validateData(config.schema.body, rawBody, 'body');
+                if (res.success)
+                    validatedBody = res.data;
+                else
+                    allInvalidParams.push(...res.invalidParams);
+            }
+        }
+        if (allInvalidParams.length > 0) {
+            return problemResponse({
+                status: 422,
+                title: 'Unprocessable Entity',
+                detail: `Validation failed for ${allInvalidParams.length} parameter(s).`,
+                type: 'https://yaxa.dev/errors/validation-failed',
+                invalidParams: allInvalidParams
+            });
+        }
+        // 4. Construct Rich Endpoint Context
+        const context = {
+            event,
+            request,
+            url,
+            locals,
+            body: validatedBody,
+            query: validatedQuery,
+            params: validatedParams,
+            headers: validatedHeaders,
+            user: locals?.user || null,
+            session: locals?.session || null,
+            orgId: locals?.orgId || null
+        };
+        // 5. Execute Handler wrapped in Interceptors & Error Boundary
+        const runHandler = async () => {
+            const defaultStatus = config.status || 200;
+            let result;
+            try {
+                result = await config.handle(context);
+            }
+            catch (err) {
+                // Allow SvelteKit redirects and HTTP errors to bubble up
+                if (err && typeof err === 'object' && ('status' in err || 'location' in err)) {
+                    throw err;
+                }
+                if (err instanceof Response) {
+                    return err;
+                }
+                console.error('[Yaxa Endpoint Error]', err);
+                return problemResponse({
+                    status: 500,
+                    title: 'Internal Server Error',
+                    detail: 'An unexpected internal error occurred.',
+                    type: 'https://yaxa.dev/errors/internal-server-error'
+                });
+            }
+            // 6. Response Auto-Serialization
+            if (result instanceof Response) {
+                return result;
+            }
+            if (result === undefined || result === null) {
+                return new Response(null, { status: 204 });
+            }
+            if (typeof result === 'string') {
+                return new Response(result, {
+                    status: defaultStatus,
+                    headers: { 'content-type': 'text/plain; charset=utf-8' }
+                });
+            }
+            return Response.json(result, { status: defaultStatus });
+        };
+        // 7. Apply Interceptors (if any)
+        if (config.interceptors && config.interceptors.length > 0) {
+            const pipeline = config.interceptors.reduceRight((next, interceptor) => () => interceptor(context, next), runHandler);
+            return pipeline();
+        }
+        return runHandler();
+    };
+    // 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';
+export * from './problem';
+export * from './guards';
+export * from './validate';

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

@@ -0,0 +1,26 @@
+import type { ProblemDetails } from './types';
+export interface CreateProblemOptions {
+    status: number;
+    title?: string;
+    detail?: string;
+    type?: string;
+    instance?: string;
+    invalidParams?: Array<{
+        name: string;
+        reason: string;
+    }>;
+    headers?: HeadersInit;
+    [key: string]: unknown;
+}
+/**
+ * Creates an RFC 7807 Problem Details object.
+ */
+export declare function createProblemDetails(options: CreateProblemOptions): ProblemDetails;
+/**
+ * Creates a standard SvelteKit Response formatted with application/problem+json.
+ */
+export declare function problemResponse(options: CreateProblemOptions): Response;
+/**
+ * Type-guard checking if an object conforms to ProblemDetails.
+ */
+export declare function isProblemDetails(value: unknown): value is ProblemDetails;

package/dist/server/endpoint/problem.js

@@ -0,0 +1,62 @@
+/**
+ * Standard HTTP error status code to human-readable RFC 7807 titles.
+ */
+const STATUS_TITLES = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    409: 'Conflict',
+    422: 'Unprocessable Entity',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout'
+};
+/**
+ * Creates an RFC 7807 Problem Details object.
+ */
+export function createProblemDetails(options) {
+    const status = options.status || 500;
+    const title = options.title || STATUS_TITLES[status] || 'Internal Error';
+    const type = options.type || `https://httpstatuses.com/${status}`;
+    const problem = {
+        type,
+        title,
+        status
+    };
+    for (const [key, value] of Object.entries(options)) {
+        if (key !== 'headers' && key !== 'status' && key !== 'title' && key !== 'type') {
+            problem[key] = value;
+        }
+    }
+    return problem;
+}
+/**
+ * Creates a standard SvelteKit Response formatted with application/problem+json.
+ */
+export function problemResponse(options) {
+    const status = options.status || 500;
+    const problem = createProblemDetails(options);
+    const customHeaders = new Headers(options.headers || {});
+    if (!customHeaders.has('content-type')) {
+        customHeaders.set('content-type', 'application/problem+json; charset=utf-8');
+    }
+    return new Response(JSON.stringify(problem), {
+        status,
+        headers: customHeaders
+    });
+}
+/**
+ * Type-guard checking if an object conforms to ProblemDetails.
+ */
+export function isProblemDetails(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'status' in value &&
+        typeof value.status === 'number' &&
+        'title' in value &&
+        'type' in value);
+}

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

@@ -0,0 +1,151 @@
+import type { RequestEvent } from '@sveltejs/kit';
+/**
+ * Standard RFC 7807 Problem Details representation.
+ * @see https://datatracker.ietf.org/doc/html/rfc7807
+ */
+export interface ProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    invalidParams?: Array<{
+        name: string;
+        reason: string;
+    }>;
+    [key: string]: unknown;
+}
+/**
+ * Generic guard return value.
+ * - Return `Response` or `ProblemDetails`: Immediately stops pipeline and sends HTTP response.
+ * - Return `void` or `undefined` or `true`: Guard passed; continues to next step.
+ */
+export type GuardResult = Response | ProblemDetails | void | undefined | boolean;
+/**
+ * Guard function signature.
+ */
+export type Guard = (event: RequestEvent) => Promise<GuardResult> | GuardResult;
+/**
+ * Standard Schema or validator representation.
+ * Supports:
+ * 1. Standard Schema v1 (`~standard` property, e.g. Zod v3.24+, Zod v4, Valibot, ArkType)
+ * 2. `.safeParse()` (Zod, Yup, etc.)
+ * 3. Functional validator: `(data: unknown) => { success: boolean; data?: T; error?: any }`
+ */
+export type AnyValidator<T = any> = {
+    '~standard': {
+        validate: (value: unknown) => Promise<{
+            value?: T;
+            issues?: ReadonlyArray<any>;
+        }> | {
+            value?: T;
+            issues?: ReadonlyArray<any>;
+        };
+    };
+} | {
+    safeParse: (value: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: any;
+    };
+} | {
+    parse: (value: unknown) => T;
+} | ((value: unknown) => {
+    success: boolean;
+    data?: T;
+    error?: any;
+});
+/**
+ * Infer output type from a validator.
+ */
+export type InferValidatorOutput<V> = V extends {
+    '~standard': {
+        validate: (...args: any[]) => Promise<{
+            value?: infer T;
+        }> | {
+            value?: infer T;
+        };
+    };
+} ? T : V extends {
+    safeParse: (...args: any[]) => {
+        success: true;
+        data: infer T;
+    } | {
+        success: false;
+        error: any;
+    };
+} ? T : V extends {
+    parse: (...args: any[]) => infer T;
+} ? T : V extends (value: unknown) => {
+    success: true;
+    data: infer T;
+} ? T : any;
+export interface YaxaEndpointSchemaConfig<TBody = any, TQuery = any, TParams = any, THeaders = any> {
+    body?: TBody;
+    query?: TQuery;
+    params?: TParams;
+    headers?: THeaders;
+}
+/**
+ * Rich context passed to business handler in yaxaEndpoint.
+ */
+export interface YaxaEndpointContext<TBody = any, TQuery = any, TParams = any, THeaders = any> {
+    event: RequestEvent;
+    request: Request;
+    url: URL;
+    locals: App.Locals;
+    body: TBody;
+    query: TQuery;
+    params: TParams;
+    headers: THeaders;
+    user: any;
+    session: any;
+    orgId: string | null;
+}
+/**
+ * Interceptor function wrapping handler execution.
+ */
+export type YaxaInterceptor = (context: YaxaEndpointContext, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Endpoint configuration passed to yaxaEndpoint().
+ */
+export interface YaxaEndpointConfig<TBodySchema = any, TQuerySchema = any, TParamsSchema = any, THeadersSchema = any, TResult = any> {
+    /**
+     * Sequence of declarative guards executed before handler body.
+     * (e.g. requireAuth(), requireRole(['admin']), rateLimit({ points: 10 }))
+     */
+    guards?: Guard[];
+    /**
+     * Schemas for input payload validation (body, query string, path params, headers).
+     */
+    schema?: YaxaEndpointSchemaConfig<TBodySchema, TQuerySchema, TParamsSchema, THeadersSchema>;
+    /**
+     * Optional status code to return for successful non-Response return values.
+     * Defaults to 200 (or 201 for POST when returning created object if desired).
+     */
+    status?: number;
+    /**
+     * Optional response interceptors (e.g. audit logging, timing headers).
+     */
+    interceptors?: YaxaInterceptor[];
+    /**
+     * OpenAPI metadata annotations (used by Milestone 3 auto-docs).
+     */
+    summary?: string;
+    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.
+     */
+    handle: (context: YaxaEndpointContext<InferValidatorOutput<TBodySchema>, InferValidatorOutput<TQuerySchema>, InferValidatorOutput<TParamsSchema>, InferValidatorOutput<THeadersSchema>>) => Promise<TResult> | TResult;
+}

package/dist/server/endpoint/types.js

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

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

@@ -0,0 +1,21 @@
+export interface ValidationSuccess<T> {
+    success: true;
+    data: T;
+}
+export interface ValidationFailure {
+    success: false;
+    invalidParams: Array<{
+        name: string;
+        reason: string;
+    }>;
+    rawError?: any;
+}
+export type ValidationOutcome<T> = ValidationSuccess<T> | ValidationFailure;
+/**
+ * Validates arbitrary input data against any supported validator:
+ * 1. Standard Schema v1 (`~standard` property, e.g. Zod v3.24+, Zod v4, Valibot, ArkType)
+ * 2. `.safeParse()` (Zod, Yup, etc.)
+ * 3. `.parse()`
+ * 4. Custom validation function: `(data) => { success, data, error }`
+ */
+export declare function validateData<T = any>(validator: any, input: unknown, scopePrefix?: string): Promise<ValidationOutcome<T>>;

package/dist/server/endpoint/validate.js

@@ -0,0 +1,128 @@
+/**
+ * Validates arbitrary input data against any supported validator:
+ * 1. Standard Schema v1 (`~standard` property, e.g. Zod v3.24+, Zod v4, Valibot, ArkType)
+ * 2. `.safeParse()` (Zod, Yup, etc.)
+ * 3. `.parse()`
+ * 4. Custom validation function: `(data) => { success, data, error }`
+ */
+export async function validateData(validator, input, scopePrefix = '') {
+    if (!validator) {
+        return { success: true, data: input };
+    }
+    // 1. Standard Schema v1 (~standard specification)
+    if (typeof validator === 'object' && validator !== null && '~standard' in validator) {
+        try {
+            const std = validator['~standard'];
+            const result = await std.validate(input);
+            if (result &&
+                'issues' in result &&
+                Array.isArray(result.issues) &&
+                result.issues.length > 0) {
+                const invalidParams = result.issues.map((issue) => {
+                    let pathStr = '';
+                    if (Array.isArray(issue.path)) {
+                        pathStr = issue.path
+                            .map((seg) => typeof seg === 'object' && seg !== null && 'key' in seg ? seg.key : String(seg))
+                            .join('.');
+                    }
+                    const name = scopePrefix
+                        ? pathStr
+                            ? `${scopePrefix}.${pathStr}`
+                            : scopePrefix
+                        : pathStr || 'value';
+                    return {
+                        name,
+                        reason: issue.message || 'Invalid value'
+                    };
+                });
+                return { success: false, invalidParams, rawError: result.issues };
+            }
+            return { success: true, data: result.value };
+        }
+        catch (err) {
+            return {
+                success: false,
+                invalidParams: [
+                    { name: scopePrefix || 'value', reason: err?.message || 'Validation failed' }
+                ],
+                rawError: err
+            };
+        }
+    }
+    // 2. Standard .safeParse() (Zod, etc.)
+    if (typeof validator === 'object' &&
+        validator !== null &&
+        typeof validator.safeParse === 'function') {
+        const parsed = validator.safeParse(input);
+        if (parsed.success) {
+            return { success: true, data: parsed.data };
+        }
+        // ZodError or similar
+        const issues = parsed.error?.issues || parsed.error?.errors || [];
+        const invalidParams = issues.length > 0
+            ? issues.map((issue) => {
+                const pathStr = Array.isArray(issue.path) ? issue.path.join('.') : '';
+                const name = scopePrefix
+                    ? pathStr
+                        ? `${scopePrefix}.${pathStr}`
+                        : scopePrefix
+                    : pathStr || 'value';
+                return {
+                    name,
+                    reason: issue.message || 'Validation failed'
+                };
+            })
+            : [{ name: scopePrefix || 'value', reason: parsed.error?.message || 'Validation failed' }];
+        return { success: false, invalidParams, rawError: parsed.error };
+    }
+    // 3. Functional Validator
+    if (typeof validator === 'function') {
+        try {
+            const res = validator(input);
+            if (res && typeof res === 'object' && 'success' in res) {
+                if (res.success) {
+                    return { success: true, data: (res.data !== undefined ? res.data : input) };
+                }
+                const reason = res.error?.message || (typeof res.error === 'string' ? res.error : 'Validation failed');
+                return {
+                    success: false,
+                    invalidParams: [{ name: scopePrefix || 'value', reason }],
+                    rawError: res.error
+                };
+            }
+            // If function returned parsed data without error
+            return { success: true, data: res };
+        }
+        catch (err) {
+            return {
+                success: false,
+                invalidParams: [
+                    { name: scopePrefix || 'value', reason: err?.message || 'Validation failed' }
+                ],
+                rawError: err
+            };
+        }
+    }
+    // 4. Standard .parse() throwing validator
+    if (typeof validator === 'object' &&
+        validator !== null &&
+        typeof validator.parse === 'function') {
+        try {
+            const data = validator.parse(input);
+            return { success: true, data: data };
+        }
+        catch (err) {
+            const issues = err?.issues || err?.errors || [];
+            const invalidParams = issues.length > 0
+                ? issues.map((issue) => ({
+                    name: scopePrefix
+                        ? `${scopePrefix}.${issue.path?.join('.')}`
+                        : issue.path?.join('.') || 'value',
+                    reason: issue.message || 'Validation failed'
+                }))
+                : [{ name: scopePrefix || 'value', reason: err?.message || 'Validation failed' }];
+            return { success: false, invalidParams, rawError: err };
+        }
+    }
+    return { success: true, data: input };
+}

package/dist/server/index.d.ts

@@ -22,3 +22,7 @@ export { getResendClient, sendMagicLinkEmail, sendWelcomeEmail } from './email/i
 export type { ResendEmailConfig, SendMagicLinkOptions, SendWelcomeEmailOptions } from './email/index';
 export { getS3Client, createPresignedUploadUrl, createS3UploadHandler } from './storage/index';
 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

@@ -18,3 +18,7 @@ export { getPolarClient, createPolarCheckout, createPolarCustomerPortalSession,
 export { getResendClient, sendMagicLinkEmail, sendWelcomeEmail } from './email/index';
 // Cloud Storage (AWS S3 & Cloudflare R2)
 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;