yaxa-svelte 2.1.0 → 2.2.0

package/README.md

@@ -241,13 +241,46 @@ export const POST = createPolarWebhookHandler();
 
 ---
 
+## ⚡ Type-Safe Endpoint Pipeline (`yaxaEndpoint` & Declarative Guards)
+
+Eliminate endpoint boilerplate in `+server.ts` with declarative auth guards, sliding-window rate limiting, multi-engine validation (Zod, Valibot, Standard Schema), and RFC 7807 Problem Details:
+
+```ts
+// src/routes/api/projects/+server.ts
+import { yaxaEndpoint, requireAuth, requireRole, rateLimit } from 'yaxa-svelte/server';
+import { z } from 'zod';
+
+const CreateProjectSchema = z.object({
+	name: z.string().min(3),
+	description: z.string().optional()
+});
+
+export const POST = yaxaEndpoint({
+	status: 201,
+	guards: [
+		requireAuth(),
+		requireRole(['admin', 'owner']),
+		rateLimit({ points: 20, windowSeconds: 60 })
+	],
+	schema: {
+		body: CreateProjectSchema
+	},
+	handle: async ({ body, user, orgId }) => {
+		// Guaranteed type-safe body, authenticated user, and active orgId
+		return { id: 'proj_123', name: body.name, orgId };
+	}
+});
+```
+
+---
+
 ## 📦 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`    | Universal Server Hooks, SEO endpoints, Drizzle DB drivers, Cloud Storage handlers, and Email dispatch                                     |
+| `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                                                                   |

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

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

package/dist/server/endpoint/endpoint.test.js

@@ -0,0 +1,364 @@
+import { describe, it, expect, vi } from 'vitest';
+import { z } from 'zod';
+import { createMockRequestEvent } from '../../testing/index.js';
+import { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails, requireAuth, requireRole, rateLimit, composeGuards, validateData } from './index.js';
+describe('RFC 7807 Problem Details', () => {
+    it('creates structured problem details object with standard defaults', () => {
+        const problem = createProblemDetails({
+            status: 404,
+            detail: 'Project proj_999 does not exist.'
+        });
+        expect(problem.status).toBe(404);
+        expect(problem.title).toBe('Not Found');
+        expect(problem.type).toBe('https://httpstatuses.com/404');
+        expect(problem.detail).toBe('Project proj_999 does not exist.');
+        expect(isProblemDetails(problem)).toBe(true);
+    });
+    it('returns Response with application/problem+json content-type and custom fields', async () => {
+        const response = problemResponse({
+            status: 422,
+            title: 'Unprocessable Entity',
+            detail: 'Validation error',
+            invalidParams: [{ name: 'email', reason: 'Must be a valid email' }],
+            traceId: 'trace_abc123'
+        });
+        expect(response.status).toBe(422);
+        expect(response.headers.get('content-type')).toContain('application/problem+json');
+        const json = await response.json();
+        expect(json.status).toBe(422);
+        expect(json.invalidParams).toHaveLength(1);
+        expect(json.invalidParams[0].name).toBe('email');
+        expect(json.traceId).toBe('trace_abc123');
+    });
+});
+describe('Declarative Guards', () => {
+    describe('requireAuth', () => {
+        it('returns 401 Problem Details when user is unauthenticated', async () => {
+            const guard = requireAuth();
+            const event = createMockRequestEvent({ locals: { user: null } });
+            const result = await guard(event);
+            expect(result).toBeInstanceOf(Response);
+            if (result instanceof Response) {
+                expect(result.status).toBe(401);
+                const json = await result.json();
+                expect(json.title).toBe('Unauthorized');
+            }
+        });
+        it('throws 303 redirect when redirect option is set', async () => {
+            const guard = requireAuth({ redirect: '/login' });
+            const event = createMockRequestEvent({
+                url: 'http://localhost:5173/dashboard?tab=billing',
+                locals: { user: null }
+            });
+            try {
+                await guard(event);
+                expect.fail('Expected redirect to be thrown');
+            }
+            catch (err) {
+                expect(err.status).toBe(303);
+                expect(err.location).toContain('/login?returnTo=');
+                expect(err.location).toContain(encodeURIComponent('/dashboard?tab=billing'));
+            }
+        });
+        it('passes cleanly when user exists in locals', async () => {
+            const guard = requireAuth();
+            const event = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'admin' } }
+            });
+            const result = await guard(event);
+            expect(result).toBeUndefined();
+        });
+    });
+    describe('requireRole', () => {
+        it('returns 401 if user is not logged in', async () => {
+            const guard = requireRole(['admin']);
+            const event = createMockRequestEvent({ locals: { user: null } });
+            const result = (await guard(event));
+            expect(result.status).toBe(401);
+        });
+        it('returns 403 Forbidden when user role is not allowed', async () => {
+            const guard = requireRole(['admin', 'owner']);
+            const event = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'member' } }
+            });
+            const result = (await guard(event));
+            expect(result.status).toBe(403);
+            const json = await result.json();
+            expect(json.title).toBe('Forbidden');
+            expect(json.requiredRoles).toEqual(['admin', 'owner']);
+        });
+        it('passes when user has one of the allowed roles', async () => {
+            const guard = requireRole(['admin', 'owner']);
+            const event = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'owner' } }
+            });
+            const result = await guard(event);
+            expect(result).toBeUndefined();
+        });
+        it('passes when member role matches org role in multi-tenant setup', async () => {
+            const guard = requireRole(['billing_admin']);
+            const event = createMockRequestEvent({
+                locals: {
+                    user: { id: 'usr_1', role: 'member' },
+                    member: { role: 'billing_admin' }
+                }
+            });
+            const result = await guard(event);
+            expect(result).toBeUndefined();
+        });
+    });
+    describe('rateLimit', () => {
+        it('allows requests up to points threshold then returns 429', async () => {
+            const guard = rateLimit({
+                points: 3,
+                windowSeconds: 10,
+                keyGenerator: () => 'test_client_key'
+            });
+            const event = createMockRequestEvent();
+            // First 3 calls succeed
+            expect(await guard(event)).toBeUndefined();
+            expect(await guard(event)).toBeUndefined();
+            expect(await guard(event)).toBeUndefined();
+            // 4th call is rate-limited
+            const result = (await guard(event));
+            expect(result.status).toBe(429);
+            expect(result.headers.get('Retry-After')).toBeDefined();
+            expect(result.headers.get('X-RateLimit-Remaining')).toBe('0');
+            const json = await result.json();
+            expect(json.title).toBe('Too Many Requests');
+        });
+    });
+    describe('composeGuards', () => {
+        it('executes guards sequentially and halts on first failure', async () => {
+            const guard = composeGuards(requireAuth(), requireRole(['admin']));
+            // Unauthenticated -> fails on requireAuth with 401
+            const eventUnauth = createMockRequestEvent({ locals: { user: null } });
+            const res1 = (await guard(eventUnauth));
+            expect(res1.status).toBe(401);
+            // Authenticated but wrong role -> fails on requireRole with 403
+            const eventForbidden = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'viewer' } }
+            });
+            const res2 = (await guard(eventForbidden));
+            expect(res2.status).toBe(403);
+            // Both pass
+            const eventOk = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'admin' } }
+            });
+            const res3 = await guard(eventOk);
+            expect(res3).toBeUndefined();
+        });
+    });
+});
+describe('Multi-Engine Validation Engine', () => {
+    it('validates with Zod schema and extracts parsed data', async () => {
+        const schema = z.object({
+            email: z.string().email(),
+            age: z.number().min(18)
+        });
+        const valid = await validateData(schema, { email: 'test@example.com', age: 25 });
+        expect(valid.success).toBe(true);
+        if (valid.success) {
+            expect(valid.data.email).toBe('test@example.com');
+            expect(valid.data.age).toBe(25);
+        }
+        const invalid = await validateData(schema, { email: 'bad-email', age: 16 }, 'body');
+        expect(invalid.success).toBe(false);
+        if (!invalid.success) {
+            expect(invalid.invalidParams.length).toBeGreaterThanOrEqual(2);
+            expect(invalid.invalidParams[0].name).toContain('body.');
+        }
+    });
+    it('validates with Standard Schema v1 (~standard)', async () => {
+        // Mock Standard Schema specification
+        const mockStandardSchema = {
+            '~standard': {
+                version: 1,
+                vendor: 'custom',
+                validate: (val) => {
+                    if (typeof val === 'string' && val.length > 3) {
+                        return { value: val.toUpperCase() };
+                    }
+                    return {
+                        issues: [{ path: ['name'], message: 'Name must exceed 3 characters' }]
+                    };
+                }
+            }
+        };
+        const ok = await validateData(mockStandardSchema, 'alice');
+        expect(ok.success).toBe(true);
+        if (ok.success)
+            expect(ok.data).toBe('ALICE');
+        const bad = await validateData(mockStandardSchema, 'al', 'body');
+        expect(bad.success).toBe(false);
+        if (!bad.success) {
+            expect(bad.invalidParams[0].name).toBe('body.name');
+            expect(bad.invalidParams[0].reason).toContain('exceed 3 characters');
+        }
+    });
+    it('validates with custom function validator', async () => {
+        const validator = (val) => {
+            if (!val || val.length === 0) {
+                return { success: false, error: 'Cannot be empty' };
+            }
+            return { success: true, data: val };
+        };
+        const ok = await validateData(validator, 'hello');
+        expect(ok.success).toBe(true);
+        const bad = await validateData(validator, '');
+        expect(bad.success).toBe(false);
+    });
+});
+describe('yaxaEndpoint Higher-Order Pipeline', () => {
+    const ItemSchema = z.object({
+        title: z.string().min(2),
+        price: z.number().positive()
+    });
+    const QuerySchema = z.object({
+        search: z.string().optional()
+    });
+    it('enforces guards before executing handler', async () => {
+        const endpoint = yaxaEndpoint({
+            guards: [requireAuth()],
+            handle: () => ({ success: true })
+        });
+        const eventUnauth = createMockRequestEvent({ locals: { user: null } });
+        const response = await endpoint(eventUnauth);
+        expect(response.status).toBe(401);
+        const json = await response.json();
+        expect(json.title).toBe('Unauthorized');
+    });
+    it('returns 422 Problem Details on invalid request body', async () => {
+        const endpoint = yaxaEndpoint({
+            schema: { body: ItemSchema },
+            handle: ({ body }) => body
+        });
+        const event = createMockRequestEvent({
+            method: 'POST',
+            body: { title: 'a', price: -5 }
+        });
+        const response = await endpoint(event);
+        expect(response.status).toBe(422);
+        expect(response.headers.get('content-type')).toContain('application/problem+json');
+        const json = await response.json();
+        expect(json.status).toBe(422);
+        expect(json.title).toBe('Unprocessable Entity');
+        expect(json.invalidParams.length).toBeGreaterThanOrEqual(2);
+    });
+    it('handles malformed JSON body gracefully with 400 Bad Request', async () => {
+        const endpoint = yaxaEndpoint({
+            handle: ({ body }) => body
+        });
+        const event = createMockRequestEvent({
+            method: 'POST',
+            body: '{ broken json: ',
+            headers: { 'content-type': 'application/json' }
+        });
+        const response = await endpoint(event);
+        expect(response.status).toBe(400);
+        const json = await response.json();
+        expect(json.title).toBe('Bad Request');
+    });
+    it('executes handler and auto-serializes JSON with typed body, query, and params', async () => {
+        const endpoint = yaxaEndpoint({
+            status: 201,
+            schema: {
+                body: ItemSchema,
+                query: QuerySchema
+            },
+            handle: ({ body, query, params, user }) => {
+                return {
+                    created: true,
+                    item: body,
+                    q: query.search,
+                    id: params.id,
+                    userId: user?.id
+                };
+            }
+        });
+        const event = createMockRequestEvent({
+            method: 'POST',
+            url: 'http://localhost:5173/api/items/item_42?search=svelte',
+            params: { id: 'item_42' },
+            body: { title: 'Keyboard', price: 99 },
+            locals: { user: { id: 'usr_77', role: 'admin' } }
+        });
+        const response = await endpoint(event);
+        expect(response.status).toBe(201);
+        expect(response.headers.get('content-type')).toContain('application/json');
+        const json = await response.json();
+        expect(json.created).toBe(true);
+        expect(json.item.title).toBe('Keyboard');
+        expect(json.item.price).toBe(99);
+        expect(json.q).toBe('svelte');
+        expect(json.id).toBe('item_42');
+        expect(json.userId).toBe('usr_77');
+    });
+    it('supports string returns as text/plain and null/void as 204 No Content', async () => {
+        const stringEndpoint = yaxaEndpoint({
+            handle: () => 'PONG'
+        });
+        const res1 = await stringEndpoint(createMockRequestEvent());
+        expect(res1.status).toBe(200);
+        expect(await res1.text()).toBe('PONG');
+        expect(res1.headers.get('content-type')).toContain('text/plain');
+        const voidEndpoint = yaxaEndpoint({
+            handle: () => undefined
+        });
+        const res2 = await voidEndpoint(createMockRequestEvent());
+        expect(res2.status).toBe(204);
+    });
+    it('passes through custom Response instances without modification', async () => {
+        const customEndpoint = yaxaEndpoint({
+            handle: () => new Response('Custom CSV Content', {
+                status: 200,
+                headers: { 'content-type': 'text/csv' }
+            })
+        });
+        const response = await customEndpoint(createMockRequestEvent());
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toBe('text/csv');
+        expect(await response.text()).toBe('Custom CSV Content');
+    });
+    it('supports interceptors for request timing and header enrichment', async () => {
+        const endpoint = yaxaEndpoint({
+            interceptors: [
+                async (_ctx, next) => {
+                    const res = await next();
+                    res.headers.set('x-yaxa-intercepted', 'true');
+                    return res;
+                }
+            ],
+            handle: () => ({ ok: true })
+        });
+        const response = await endpoint(createMockRequestEvent());
+        expect(response.headers.get('x-yaxa-intercepted')).toBe('true');
+    });
+    it('sanitizes unexpected internal 500 errors without leaking stack traces or sensitive strings', async () => {
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const failingEndpoint = yaxaEndpoint({
+            handle: () => {
+                throw new Error('Database password leak: secret123456');
+            }
+        });
+        const response = await failingEndpoint(createMockRequestEvent());
+        expect(response.status).toBe(500);
+        expect(response.headers.get('content-type')).toContain('application/problem+json');
+        const json = await response.json();
+        expect(json.title).toBe('Internal Server Error');
+        expect(json.detail).not.toContain('secret123456');
+        errorSpy.mockRestore();
+    });
+    it('attaches _yaxaConfig metadata for runtime reflection and OpenAPI discovery', () => {
+        const config = {
+            summary: 'Create Project',
+            description: 'Creates a new user project',
+            tags: ['Projects'],
+            handle: () => ({})
+        };
+        const endpoint = yaxaEndpoint(config);
+        expect(endpoint._yaxaConfig).toBeDefined();
+        expect(endpoint._yaxaConfig.summary).toBe('Create Project');
+        expect(endpoint._yaxaConfig.tags).toEqual(['Projects']);
+    });
+});

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

@@ -0,0 +1,52 @@
+import type { RequestEvent } from '@sveltejs/kit';
+import type { Guard } from './types';
+export interface RequireAuthOptions {
+    /**
+     * If provided, unauthorized users are redirected with 303 instead of receiving 401 JSON.
+     * (Useful for dashboard/form routes).
+     */
+    redirect?: string;
+    /**
+     * Custom error message for the RFC 7807 detail.
+     */
+    detail?: string;
+}
+/**
+ * Declarative Guard: Enforces that the request has an active authenticated user in `event.locals.user`.
+ */
+export declare function requireAuth(options?: RequireAuthOptions): Guard;
+export interface RequireRoleOptions {
+    detail?: string;
+}
+/**
+ * Declarative Guard: Enforces that the active user/member possesses one of the allowed roles.
+ * Checks `event.locals.user.role`, `event.locals.member.role`, and `event.locals.orgRole`.
+ */
+export declare function requireRole(roles: string | string[], options?: RequireRoleOptions): Guard;
+export interface RateLimitOptions {
+    /**
+     * Maximum allowed requests within the time window. Default: 60.
+     */
+    points?: number;
+    /**
+     * Window duration in seconds. Default: 60.
+     */
+    windowSeconds?: number;
+    /**
+     * Custom cache key generator. Defaults to IP address or authenticated user ID.
+     */
+    keyGenerator?: (event: RequestEvent) => string;
+    /**
+     * Custom error message.
+     */
+    detail?: string;
+}
+/**
+ * Declarative Guard: In-memory sliding-window rate limiter.
+ * Returns 429 Too Many Requests with a `Retry-After` header when exceeded.
+ */
+export declare function rateLimit(options?: RateLimitOptions): Guard;
+/**
+ * Combines multiple guards into a single composite guard.
+ */
+export declare function composeGuards(...guards: Guard[]): Guard;

package/dist/server/endpoint/guards.js

@@ -0,0 +1,137 @@
+import { redirect } from '@sveltejs/kit';
+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 user = event.locals?.user;
+        if (!user) {
+            if (options.redirect) {
+                const returnTo = encodeURIComponent(event.url.pathname + event.url.search);
+                const target = options.redirect.includes('?')
+                    ? `${options.redirect}&returnTo=${returnTo}`
+                    : `${options.redirect}?returnTo=${returnTo}`;
+                throw redirect(303, target);
+            }
+            return problemResponse({
+                status: 401,
+                title: 'Unauthorized',
+                detail: options.detail || 'Authentication required to access this endpoint.',
+                type: 'https://yaxa.dev/errors/unauthorized'
+            });
+        }
+    };
+}
+/**
+ * Declarative Guard: Enforces that the active user/member possesses one of the allowed roles.
+ * Checks `event.locals.user.role`, `event.locals.member.role`, and `event.locals.orgRole`.
+ */
+export function requireRole(roles, options = {}) {
+    const allowedRoles = Array.isArray(roles) ? roles : [roles];
+    return (event) => {
+        const locals = event.locals;
+        const user = locals?.user;
+        if (!user) {
+            return problemResponse({
+                status: 401,
+                title: 'Unauthorized',
+                detail: 'Authentication required before role verification.'
+            });
+        }
+        const userRole = user.role;
+        const memberRole = locals.member?.role || locals.orgRole;
+        const hasRole = (userRole && allowedRoles.includes(userRole)) ||
+            (memberRole && allowedRoles.includes(memberRole));
+        if (!hasRole) {
+            return problemResponse({
+                status: 403,
+                title: 'Forbidden',
+                detail: options.detail ||
+                    `Insufficient permissions. Requires one of: [${allowedRoles.join(', ')}].`,
+                type: 'https://yaxa.dev/errors/forbidden',
+                requiredRoles: allowedRoles
+            });
+        }
+    };
+}
+const rateLimitStore = new Map();
+// Periodic cleanup of stale rate-limit buckets (every 5 minutes)
+if (typeof setInterval !== 'undefined') {
+    const timer = setInterval(() => {
+        const now = Date.now();
+        for (const [key, bucket] of rateLimitStore.entries()) {
+            if (bucket.resetAt <= now) {
+                rateLimitStore.delete(key);
+            }
+        }
+    }, 5 * 60 * 1000);
+    if (timer && typeof timer === 'object' && 'unref' in timer) {
+        timer.unref();
+    }
+}
+/**
+ * Declarative Guard: In-memory sliding-window rate limiter.
+ * Returns 429 Too Many Requests with a `Retry-After` header when exceeded.
+ */
+export function rateLimit(options = {}) {
+    const points = options.points ?? 60;
+    const windowMs = (options.windowSeconds ?? 60) * 1000;
+    return (event) => {
+        let key;
+        if (options.keyGenerator) {
+            key = options.keyGenerator(event);
+        }
+        else {
+            const userId = event.locals?.user?.id;
+            let clientIp = '127.0.0.1';
+            try {
+                if (typeof event.getClientAddress === 'function') {
+                    clientIp = event.getClientAddress();
+                }
+            }
+            catch {
+                // Fallback when running in environments without getClientAddress
+            }
+            const headerIp = event.request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+                event.request.headers.get('x-real-ip');
+            const ip = headerIp || clientIp;
+            key = userId ? `user:${userId}` : `ip:${ip}`;
+        }
+        const now = Date.now();
+        let bucket = rateLimitStore.get(key);
+        if (!bucket || bucket.resetAt <= now) {
+            bucket = { tokens: points - 1, resetAt: now + windowMs };
+            rateLimitStore.set(key, bucket);
+            return;
+        }
+        if (bucket.tokens <= 0) {
+            const retryAfterSeconds = Math.max(1, Math.ceil((bucket.resetAt - now) / 1000));
+            return problemResponse({
+                status: 429,
+                title: 'Too Many Requests',
+                detail: options.detail || `Rate limit exceeded. Try again in ${retryAfterSeconds} seconds.`,
+                type: 'https://yaxa.dev/errors/rate-limit-exceeded',
+                headers: {
+                    'Retry-After': String(retryAfterSeconds),
+                    'X-RateLimit-Limit': String(points),
+                    'X-RateLimit-Remaining': '0',
+                    'X-RateLimit-Reset': String(Math.ceil(bucket.resetAt / 1000))
+                }
+            });
+        }
+        bucket.tokens -= 1;
+    };
+}
+/**
+ * Combines multiple guards into a single composite guard.
+ */
+export function composeGuards(...guards) {
+    return async (event) => {
+        for (const guard of guards) {
+            const result = await guard(event);
+            if (result)
+                return result;
+        }
+    };
+}

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,238 @@
+import { isProblemDetails, problemResponse } from './problem';
+import { validateData } from './validate';
+/**
+ * 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;
+    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,144 @@
+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;
+    /**
+     * 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,5 @@ 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';

package/dist/server/index.js

@@ -18,3 +18,5 @@ 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaxa-svelte",
-  "version": "2.1.0",
+  "version": "2.2.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",