yaxa-svelte 2.5.0 → 2.6.0

package/README.md

@@ -392,11 +392,60 @@ await broadcast(`org:${orgId}`, 'invoice.settled', {
 
 ---
 
+## 🔗 End-to-End Type-Safe Client RPC (`createApiClient`)
+
+Zero-codegen end-to-end type safety bridging your server `yaxaEndpoint` routes directly into Svelte 5 components and universal `load` functions. Adds less than 500 bytes gzipped to your client bundle:
+
+```ts
+// 1. Define Route Type Map (src/lib/api.ts)
+export type AppApi = {
+	'/api/projects': typeof import('../routes/api/projects/+server');
+	'/api/projects/[id]': typeof import('../routes/api/projects/[id]/+server');
+};
+```
+
+```svelte
+<!-- 2. Type-Safe Client in Svelte 5 (+page.svelte) -->
+<script lang="ts">
+	import { createApiClient } from 'yaxa-svelte';
+	import type { AppApi } from '$lib/api';
+
+	const api = createApiClient<AppApi>();
+
+	async function createProject() {
+		// ✨ Autocompleted URL, body, query, and response!
+		const { data, error, ok } = await api['/api/projects'].post({
+			body: { name: 'Apollo SaaS' },
+			query: { notify: true }
+		});
+
+		if (error) {
+			// 🛡️ Strongly typed RFC 7807 ProblemDetails
+			toast.error(error.title, error.detail);
+			return;
+		}
+
+		toast.success(`Created ${data.name} (#${data.id})`);
+	}
+</script>
+```
+
+```ts
+// 3. Universal SSR Load Function with SvelteKit fetch (src/routes/projects/+page.ts)
+export const load = async ({ fetch }) => {
+	const api = createApiClient<AppApi>({ fetch });
+	const { data: projects } = await api['/api/projects'].get();
+	return { projects: projects ?? [] };
+};
+```
+
+---
+
 ## 📦 Subpath Exports Architecture
 
 | Subpath                 | Description                                                                                                                                                                                                                |
 | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useSSE`, `useToast`, `useClipboard`, etc.)                                                                            |
+| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Type-Safe Client RPC (`createApiClient`), Theme System & Composables (`useGate`, `useUpload`, `useSSE`, `useToast`, `useClipboard`, etc.)                                  |
 | `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                                                                                  |
 | `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, OpenAPI 3.1 & Scalar Docs, RFC 7807, Real-Time SSE (`yaxaSSE`, `broadcast`), Background Jobs (`enqueueJob`, `createJobRunner`), `eventBus`, Server Hooks, DB, Storage & Email |
 | `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                                                                               |

package/dist/client/client.d.ts

@@ -0,0 +1,27 @@
+import type { ApiClient, ApiClientConfig } from './types';
+/**
+ * Serializes a query object into a URL search string.
+ * Handles arrays, booleans, numbers, and strings while ignoring undefined/null.
+ */
+export declare function serializeQueryParams(query?: Record<string, any>): string;
+/**
+ * Interpolates dynamic path segments (e.g. `[id]`, `[...slug]`, or `:id`).
+ */
+export declare function interpolatePath(path: string, params?: Record<string, any>): string;
+/**
+ * Creates an end-to-end type-safe API client for yaxaEndpoint routes.
+ *
+ * @example
+ * ```ts
+ * import { createApiClient } from 'yaxa-svelte';
+ * import type { AppApi } from '$lib/api';
+ *
+ * const api = createApiClient<AppApi>();
+ *
+ * // Strong autocompletion and type-safety
+ * const { data, error } = await api['/api/projects'].post({
+ *   body: { name: 'Apollo SaaS' }
+ * });
+ * ```
+ */
+export declare function createApiClient<TRoutes = Record<string, any>>(config?: ApiClientConfig): ApiClient<TRoutes>;

package/dist/client/client.js

@@ -0,0 +1,239 @@
+/**
+ * Serializes a query object into a URL search string.
+ * Handles arrays, booleans, numbers, and strings while ignoring undefined/null.
+ */
+export function serializeQueryParams(query) {
+    if (!query || typeof query !== 'object')
+        return '';
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item !== undefined && item !== null) {
+                    searchParams.append(key, String(item));
+                }
+            }
+        }
+        else {
+            searchParams.set(key, String(value));
+        }
+    }
+    const queryString = searchParams.toString();
+    return queryString ? `?${queryString}` : '';
+}
+/**
+ * Interpolates dynamic path segments (e.g. `[id]`, `[...slug]`, or `:id`).
+ */
+export function interpolatePath(path, params) {
+    if (!params || typeof params !== 'object')
+        return path;
+    let result = path;
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        const encoded = encodeURIComponent(String(value));
+        // SvelteKit bracket syntax: [id] and [...rest]
+        result = result.replace(new RegExp(`\\[\\.\\.\\.${key}\\]`, 'g'), String(value));
+        result = result.replace(new RegExp(`\\[${key}\\]`, 'g'), encoded);
+        // Colon syntax: :id
+        result = result.replace(new RegExp(`:${key}\\b`, 'g'), encoded);
+    }
+    return result;
+}
+/**
+ * Core HTTP execution pipeline for apiClient.
+ */
+async function executeRequest(config, method, rawPath, options) {
+    const params = options?.params;
+    const interpolated = interpolatePath(rawPath, params);
+    const queryString = serializeQueryParams(options?.query);
+    const baseUrl = config.baseUrl ? config.baseUrl.replace(/\/+$/, '') : '';
+    const cleanPath = interpolated.startsWith('/') ? interpolated : `/${interpolated}`;
+    const fullUrl = `${baseUrl}${cleanPath}${queryString}`;
+    // Resolve default headers
+    let defaultHeaders = {};
+    if (typeof config.headers === 'function') {
+        const resolved = await config.headers();
+        defaultHeaders = new Headers(resolved);
+    }
+    else if (config.headers) {
+        defaultHeaders = new Headers(config.headers);
+    }
+    const headers = new Headers(defaultHeaders);
+    if (options?.headers) {
+        const reqHeaders = new Headers(options.headers);
+        reqHeaders.forEach((val, key) => headers.set(key, val));
+    }
+    // Body serialization
+    let bodyPayload;
+    if (options?.body !== undefined && options?.body !== null) {
+        const rawBody = options.body;
+        if (typeof rawBody === 'string' ||
+            rawBody instanceof FormData ||
+            rawBody instanceof Blob ||
+            rawBody instanceof URLSearchParams ||
+            rawBody instanceof ArrayBuffer) {
+            bodyPayload = rawBody;
+        }
+        else {
+            if (!headers.has('content-type')) {
+                headers.set('content-type', 'application/json');
+            }
+            bodyPayload = JSON.stringify(rawBody);
+        }
+    }
+    const fetchFn = options?.fetch || config.fetch || globalThis.fetch;
+    const requestInit = {
+        method: method.toUpperCase(),
+        headers,
+        body: bodyPayload,
+        signal: options?.signal
+    };
+    if (config.onRequest) {
+        await config.onRequest({ url: fullUrl, options: requestInit });
+    }
+    let response;
+    try {
+        response = await fetchFn(fullUrl, requestInit);
+    }
+    catch (err) {
+        const networkProblem = {
+            type: 'https://yaxa.dev/errors/network-error',
+            title: 'Network Request Failed',
+            status: 0,
+            detail: err?.message || 'Could not connect to server.'
+        };
+        const fallbackResponse = typeof Response.error === 'function'
+            ? Response.error()
+            : new Response(null, { status: 503, statusText: 'Network Error' });
+        return {
+            data: null,
+            error: networkProblem,
+            response: fallbackResponse,
+            status: 0,
+            ok: false
+        };
+    }
+    // Parse response payload
+    let parsedData = null;
+    const contentType = response.headers.get('content-type') || '';
+    if (response.status !== 204) {
+        if (contentType.includes('application/json') || contentType.includes('problem+json')) {
+            try {
+                parsedData = await response.json();
+            }
+            catch {
+                parsedData = null;
+            }
+        }
+        else {
+            try {
+                parsedData = await response.text();
+            }
+            catch {
+                parsedData = null;
+            }
+        }
+    }
+    if (response.ok) {
+        if (config.onResponse) {
+            await config.onResponse({ response, data: parsedData, error: null });
+        }
+        return {
+            data: parsedData,
+            error: null,
+            response,
+            status: response.status,
+            ok: true
+        };
+    }
+    // Format RFC 7807 problem details
+    let errorProblem;
+    if (parsedData &&
+        typeof parsedData === 'object' &&
+        (parsedData.title || parsedData.type || parsedData.status)) {
+        errorProblem = {
+            type: parsedData.type || `https://yaxa.dev/errors/http-${response.status}`,
+            title: parsedData.title || response.statusText || 'Request Error',
+            status: parsedData.status || response.status,
+            detail: parsedData.detail,
+            instance: parsedData.instance,
+            invalidParams: parsedData.invalidParams,
+            ...parsedData
+        };
+    }
+    else {
+        errorProblem = {
+            type: `https://yaxa.dev/errors/http-${response.status}`,
+            title: response.statusText || 'HTTP Error',
+            status: response.status,
+            detail: typeof parsedData === 'string' ? parsedData : undefined
+        };
+    }
+    if (config.onResponse) {
+        await config.onResponse({ response, data: null, error: errorProblem });
+    }
+    return {
+        data: null,
+        error: errorProblem,
+        response,
+        status: response.status,
+        ok: false
+    };
+}
+/**
+ * Creates a route-level proxy that exposes HTTP method callers (`get`, `post`, etc.).
+ */
+function createRouteProxy(config, path) {
+    const methods = ['get', 'post', 'put', 'delete', 'patch'];
+    const routeHandler = {};
+    for (const method of methods) {
+        routeHandler[method] = (options) => executeRequest(config, method, path, options);
+    }
+    // Allows calling the route proxy directly as a function to interpolate params:
+    // e.g. api['/api/projects/[id]']({ id: '123' }).get()
+    const callableProxy = Object.assign((params) => {
+        const interpolated = interpolatePath(path, params);
+        return createRouteProxy(config, interpolated);
+    }, routeHandler);
+    return callableProxy;
+}
+/**
+ * Creates an end-to-end type-safe API client for yaxaEndpoint routes.
+ *
+ * @example
+ * ```ts
+ * import { createApiClient } from 'yaxa-svelte';
+ * import type { AppApi } from '$lib/api';
+ *
+ * const api = createApiClient<AppApi>();
+ *
+ * // Strong autocompletion and type-safety
+ * const { data, error } = await api['/api/projects'].post({
+ *   body: { name: 'Apollo SaaS' }
+ * });
+ * ```
+ */
+export function createApiClient(config = {}) {
+    const rootTarget = {
+        get: (path, options) => executeRequest(config, 'get', path, options),
+        post: (path, options) => executeRequest(config, 'post', path, options),
+        put: (path, options) => executeRequest(config, 'put', path, options),
+        delete: (path, options) => executeRequest(config, 'delete', path, options),
+        patch: (path, options) => executeRequest(config, 'patch', path, options)
+    };
+    return new Proxy(rootTarget, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string') {
+                if (prop in target) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                // Route path access, e.g. api['/api/projects']
+                return createRouteProxy(config, prop);
+            }
+            return Reflect.get(target, prop, receiver);
+        }
+    });
+}

package/dist/client/client.test.d.ts

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

package/dist/client/client.test.js

@@ -0,0 +1,197 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createApiClient, serializeQueryParams, interpolatePath } from './client';
+describe('serializeQueryParams', () => {
+    it('returns empty string for null or empty object', () => {
+        expect(serializeQueryParams()).toBe('');
+        expect(serializeQueryParams({})).toBe('');
+        expect(serializeQueryParams(null)).toBe('');
+    });
+    it('serializes primitives correctly', () => {
+        const res = serializeQueryParams({
+            page: 1,
+            search: 'hello world',
+            active: true
+        });
+        expect(res).toBe('?page=1&search=hello+world&active=true');
+    });
+    it('ignores undefined and null values', () => {
+        const res = serializeQueryParams({
+            query: 'test',
+            filter: undefined,
+            extra: null
+        });
+        expect(res).toBe('?query=test');
+    });
+    it('serializes array parameters into multi-keys', () => {
+        const res = serializeQueryParams({
+            tags: ['svelte', 'tailwind']
+        });
+        expect(res).toBe('?tags=svelte&tags=tailwind');
+    });
+});
+describe('interpolatePath', () => {
+    it('leaves static paths unchanged', () => {
+        expect(interpolatePath('/api/projects')).toBe('/api/projects');
+    });
+    it('interpolates SvelteKit bracket syntax [param]', () => {
+        expect(interpolatePath('/api/projects/[id]', { id: 'proj_123' })).toBe('/api/projects/proj_123');
+    });
+    it('interpolates colon syntax :param', () => {
+        expect(interpolatePath('/api/orgs/:orgId/users/:userId', { orgId: 'org_1', userId: 'usr_2' })).toBe('/api/orgs/org_1/users/usr_2');
+    });
+    it('interpolates rest parameters [...rest]', () => {
+        expect(interpolatePath('/api/docs/[...slug]', { slug: 'getting-started/install' })).toBe('/api/docs/getting-started/install');
+    });
+    it('url-encodes special characters', () => {
+        expect(interpolatePath('/api/search/[query]', { query: 'svelte & kit' })).toBe('/api/search/svelte%20%26%20kit');
+    });
+});
+describe('createApiClient', () => {
+    it('performs successful GET request and returns data', async () => {
+        const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify([{ id: '1', name: 'Project 1' }]), {
+            status: 200,
+            headers: { 'content-type': 'application/json' }
+        }));
+        const api = createApiClient({ fetch: mockFetch });
+        const { data, error, status, ok } = await api['/api/projects'].get({
+            query: { limit: 10 }
+        });
+        expect(mockFetch).toHaveBeenCalledWith('/api/projects?limit=10', expect.objectContaining({
+            method: 'GET'
+        }));
+        expect(ok).toBe(true);
+        expect(status).toBe(200);
+        expect(error).toBeNull();
+        expect(data).toEqual([{ id: '1', name: 'Project 1' }]);
+    });
+    it('performs POST request with JSON body serialization', async () => {
+        const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: 'proj_new', name: 'New Team' }), {
+            status: 201,
+            headers: { 'content-type': 'application/json' }
+        }));
+        const api = createApiClient({ baseUrl: 'https://api.yaxa.dev', fetch: mockFetch });
+        const result = await api['/api/projects'].post({
+            body: { name: 'New Team' }
+        });
+        expect(mockFetch).toHaveBeenCalledWith('https://api.yaxa.dev/api/projects', expect.objectContaining({
+            method: 'POST',
+            body: JSON.stringify({ name: 'New Team' })
+        }));
+        expect(result.ok).toBe(true);
+        expect(result.status).toBe(201);
+        expect(result.data).toEqual({ id: 'proj_new', name: 'New Team' });
+    });
+    it('interpolates path parameters via options or callable route', async () => {
+        const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: '42' }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' }
+        }));
+        const api = createApiClient({ fetch: mockFetch });
+        // Pattern 1: via params option
+        await api['/api/projects/[id]'].get({
+            params: { id: '42' }
+        });
+        expect(mockFetch).toHaveBeenLastCalledWith('/api/projects/42', expect.objectContaining({ method: 'GET' }));
+        // Pattern 2: callable route
+        await api['/api/projects/[id]']({ id: '99' }).get();
+        expect(mockFetch).toHaveBeenLastCalledWith('/api/projects/99', expect.objectContaining({ method: 'GET' }));
+    });
+    it('handles 204 No Content successfully with null data', async () => {
+        const mockFetch = vi.fn().mockResolvedValue(new Response(null, { status: 204 }));
+        const api = createApiClient({ fetch: mockFetch });
+        const result = await api['/api/projects/[id]'].delete({ params: { id: '1' } });
+        expect(result.ok).toBe(true);
+        expect(result.status).toBe(204);
+        expect(result.data).toBeNull();
+        expect(result.error).toBeNull();
+    });
+    it('parses and discriminates RFC 7807 problem details on error', async () => {
+        const problem = {
+            type: 'https://yaxa.dev/errors/validation-failed',
+            title: 'Validation Failed',
+            status: 422,
+            detail: 'Field "name" is required',
+            invalidParams: [{ name: 'name', reason: 'Required' }]
+        };
+        const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify(problem), {
+            status: 422,
+            headers: { 'content-type': 'application/problem+json' }
+        }));
+        const api = createApiClient({ fetch: mockFetch });
+        const { data, error, ok, status } = await api['/api/projects'].post({
+            body: {}
+        });
+        expect(ok).toBe(false);
+        expect(status).toBe(422);
+        expect(data).toBeNull();
+        expect(error).toBeDefined();
+        expect(error?.title).toBe('Validation Failed');
+        expect(error?.invalidParams?.[0].name).toBe('name');
+    });
+    it('generates fallback RFC 7807 ProblemDetails for generic 500 error', async () => {
+        const mockFetch = vi.fn().mockResolvedValue(new Response('Internal Server Crash', {
+            status: 500,
+            statusText: 'Internal Error',
+            headers: { 'content-type': 'text/plain' }
+        }));
+        const api = createApiClient({ fetch: mockFetch });
+        const result = await api['/api/broken'].get();
+        expect(result.ok).toBe(false);
+        expect(result.status).toBe(500);
+        expect(result.error?.status).toBe(500);
+        expect(result.error?.title).toBe('Internal Error');
+        expect(result.error?.detail).toBe('Internal Server Crash');
+    });
+    it('gracefully handles network failures with status 0 RFC 7807 problem', async () => {
+        const mockFetch = vi.fn().mockRejectedValue(new Error('Failed to fetch'));
+        const api = createApiClient({ fetch: mockFetch });
+        const result = await api['/api/offline'].get();
+        expect(result.ok).toBe(false);
+        expect(result.status).toBe(0);
+        expect(result.error?.type).toBe('https://yaxa.dev/errors/network-error');
+        expect(result.error?.detail).toBe('Failed to fetch');
+    });
+    it('executes onRequest and onResponse interceptor lifecycle hooks', async () => {
+        const onRequest = vi.fn();
+        const onResponse = vi.fn();
+        const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ ok: true }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' }
+        }));
+        const api = createApiClient({
+            fetch: mockFetch,
+            onRequest,
+            onResponse
+        });
+        await api['/api/hooked'].get();
+        expect(onRequest).toHaveBeenCalledWith(expect.objectContaining({ url: '/api/hooked' }));
+        expect(onResponse).toHaveBeenCalledWith(expect.objectContaining({ error: null }));
+    });
+    it('supports top-level direct methods: api.get, api.post, etc.', async () => {
+        const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ ping: 'pong' }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' }
+        }));
+        const api = createApiClient({ fetch: mockFetch });
+        const res = await api.get('/api/health');
+        expect(mockFetch).toHaveBeenCalledWith('/api/health', expect.objectContaining({ method: 'GET' }));
+        expect(res.data).toEqual({ ping: 'pong' });
+    });
+    it('integrates with yaxaEndpoint route types seamlessly', async () => {
+        const mockFetch = vi.fn().mockImplementation(async (url, init) => {
+            const body = JSON.parse(init.body);
+            return new Response(JSON.stringify({ id: 'proj_abc', name: body.name, count: 1 }), {
+                status: 201,
+                headers: { 'content-type': 'application/json' }
+            });
+        });
+        const api = createApiClient({ fetch: mockFetch });
+        const { data, ok, status } = await api['/api/projects'].post({
+            body: { name: 'Apollo SaaS' }
+        });
+        expect(ok).toBe(true);
+        expect(status).toBe(201);
+        expect(data?.name).toBe('Apollo SaaS');
+        expect(data?.id).toBe('proj_abc');
+    });
+});

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './client';

package/dist/client/index.js

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './client';

package/dist/client/types.d.ts

@@ -0,0 +1,222 @@
+/**
+ * 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;
+}
+/**
+ * Standard Schema or validator representation.
+ */
+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 schema 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;
+/**
+ * Infer request payload and response types from a yaxaEndpoint handler or config.
+ */
+export type InferEndpoint<T> = T extends {
+    _yaxaConfig: {
+        schema?: {
+            body?: infer B;
+            query?: infer Q;
+            params?: infer P;
+            headers?: infer H;
+        };
+        handle: (...args: any[]) => infer R;
+    };
+} ? {
+    body: [B] extends [never] ? undefined : InferValidatorOutput<B>;
+    query: [Q] extends [never] ? undefined : InferValidatorOutput<Q>;
+    params: [P] extends [never] ? undefined : InferValidatorOutput<P>;
+    headers: [H] extends [never] ? undefined : InferValidatorOutput<H>;
+    response: Awaited<R> extends Response ? unknown : Awaited<R>;
+} : T extends (...args: any[]) => Promise<infer R> | infer R ? {
+    body: any;
+    query: any;
+    params: any;
+    headers: any;
+    response: Awaited<R> extends Response ? unknown : Awaited<R>;
+} : {
+    body: any;
+    query: any;
+    params: any;
+    headers: any;
+    response: any;
+};
+/**
+ * Strong discriminated union result returned by apiClient calls.
+ */
+export type ClientResponse<TData> = {
+    data: TData;
+    error: null;
+    response: Response;
+    status: number;
+    ok: true;
+} | {
+    data: null;
+    error: ProblemDetails;
+    response: Response;
+    status: number;
+    ok: false;
+};
+/**
+ * Client request options passed to an endpoint method.
+ */
+export interface ClientRequestOptions<TBody = unknown, TQuery = Record<string, any>, TParams = Record<string, any>> {
+    body?: TBody;
+    query?: TQuery;
+    params?: TParams;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}
+/**
+ * Helper to determine if an option object is required based on schema properties.
+ */
+export type RequiredKeys<T> = {
+    [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
+}[keyof T];
+export type ClientMethodFn<TEndpoint> = TEndpoint extends never ? (options?: ClientRequestOptions) => Promise<ClientResponse<any>> : InferEndpoint<TEndpoint> extends infer Inferred ? Inferred extends {
+    body: infer B;
+    query: infer Q;
+    params: infer P;
+    response: infer R;
+} ? (options?: {
+    body?: B;
+    query?: Q;
+    params?: P;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}) => Promise<ClientResponse<R>> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+/**
+ * HTTP methods supported by a route definition.
+ */
+export type RouteMethods<TRoute> = {
+    get: TRoute extends {
+        GET: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+    post: TRoute extends {
+        POST: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+    put: TRoute extends {
+        PUT: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+    delete: TRoute extends {
+        DELETE: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+    patch: TRoute extends {
+        PATCH: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+};
+/**
+ * Callable route proxy supporting path parameter interpolation.
+ * e.g. api['/api/projects/[id]']({ id: '123' }).get()
+ */
+export type RouteProxy<TRoute> = RouteMethods<TRoute> & {
+    (params: Record<string, any>): RouteMethods<TRoute>;
+};
+/**
+ * Global configuration options for creating an API client.
+ */
+export interface ApiClientConfig {
+    /**
+     * Base URL prefix for all requests (e.g. 'https://api.example.com' or '').
+     * Defaults to empty string (relative to current origin).
+     */
+    baseUrl?: string;
+    /**
+     * Custom fetch implementation (e.g. SvelteKit's event.fetch in load functions).
+     * Defaults to globalThis.fetch.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Default headers to attach to every request.
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /**
+     * Interceptor hook called before every request.
+     */
+    onRequest?: (context: {
+        url: string;
+        options: RequestInit;
+    }) => void | Promise<void>;
+    /**
+     * Interceptor hook called on every response.
+     */
+    onResponse?: (context: {
+        response: Response;
+        data: any;
+        error: ProblemDetails | null;
+    }) => void | Promise<void>;
+}
+/**
+ * Dynamic Proxy type mapping paths to methods.
+ */
+export type ApiClient<TRoutes = Record<string, any>> = {
+    [K in keyof TRoutes]: RouteProxy<TRoutes[K]>;
+} & {
+    [path: string]: RouteProxy<any>;
+} & {
+    get: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+    post: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+    put: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+    delete: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+    patch: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+};

package/dist/client/types.js

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

package/dist/index.d.ts

@@ -207,5 +207,7 @@ export { default as FeatureGrid, featureGridVariants } from './components/blocks
 export type { FeatureGridProps, FeatureItem } from './components/blocks/FeatureGrid.svelte';
 export { createMockSiteConfig, createMockUser, createTestWrapperProps } from './testing';
 export type { YaxaTestOptions } from './testing';
+export { createApiClient, interpolatePath, serializeQueryParams } from './client';
+export type { ApiClient, ApiClientConfig, ClientRequestOptions, ClientResponse, InferEndpoint, RouteMethods, ProblemDetails as ClientProblemDetails } from './client';
 export { cn, tv } from './utils/cn';
 export type { VariantProps } from './utils/cn';

package/dist/index.js

@@ -138,5 +138,7 @@ export { default as FAQ, faqVariants } from './components/blocks/FAQ.svelte';
 export { default as FeatureGrid, featureGridVariants } from './components/blocks/FeatureGrid.svelte';
 // Testing Utilities
 export { createMockSiteConfig, createMockUser, createTestWrapperProps } from './testing';
+// Type-Safe Client RPC
+export { createApiClient, interpolatePath, serializeQueryParams } from './client';
 // Utilities
 export { cn, tv } from './utils/cn';

package/package.json

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