yaxa-svelte 2.4.0 → 2.6.0

package/README.md

@@ -295,7 +295,8 @@ export const GET = createApiDocsHandler({
 });
 ```
 
-- **Interactive Reference UI:** Open `/api/docs` in your browser.
+- **Interactive Reference UI:** Open `/api/docs` in your browser (supports `?theme=scalar` (default), `?theme=swagger`, or `?theme=redoc`).
+- **Live Demo:** Try it live on [yaxa.vercel.app/api/docs](https://yaxa.vercel.app/api/docs).
 - **Raw OpenAPI 3.1 JSON:** Request `/api/docs?format=json` or send `Accept: application/json` for SDK generation.
 
 ---
@@ -345,22 +346,117 @@ export const GET = async () => {
 
 ---
 
+## 📡 Real-Time Server-Sent Events (`yaxaSSE`, `broadcast`, & `useSSE`)
+
+Zero-infrastructure real-time communication across serverless and Node.js without third-party subscriptions. Features declarative SSE streaming, automatic keep-alive heartbeats, multi-channel pub/sub broadcasting, and a reactive Svelte 5 client rune with exponential reconnect backoff:
+
+```ts
+// 1. Server-Sent Events Endpoint (src/routes/api/events/+server.ts)
+import { yaxaSSE, requireAuth } from 'yaxa-svelte/server';
+
+export const GET = yaxaSSE({
+	guards: [requireAuth()],
+	channel: (event) => `org:${event.locals.orgId}`,
+	keepAliveIntervalMs: 15000, // Heartbeat ping prevents proxy & Vercel timeouts
+	onConnect: ({ send, user }) => {
+		send('connected', { userId: user.id });
+	}
+});
+
+// 2. Publish from anywhere (Endpoints, Webhooks, Background Workers)
+import { broadcast } from 'yaxa-svelte/server';
+
+await broadcast(`org:${orgId}`, 'invoice.settled', {
+	invoiceId: 'inv_4982',
+	amount: 29.0
+});
+```
+
+```svelte
+<!-- 3. Reactive Svelte 5 Client Rune -->
+<script lang="ts">
+	import { useSSE } from 'yaxa-svelte';
+
+	const stream = useSSE('/api/events');
+
+	// Typed event listeners with automatic cleanup
+	stream.on('invoice.settled', (data) => {
+		toast.success(`Payment settled: $${data.amount}`);
+	});
+</script>
+
+<Badge color={stream.connected ? 'success' : 'neutral'}>
+	{stream.connected ? 'Live Stream' : 'Connecting...'}
+</Badge>
+```
+
+---
+
+## 🔗 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`, `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, Background Jobs (`enqueueJob`, `createJobRunner`), `eventBus`, Server Hooks, 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                                                                                                                    |
-| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                                                           |
-| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                                                   |
-| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                                                |
-| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                                                             |
-| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                                                  |
-| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                                                           |
+| Subpath                 | Description                                                                                                                                                                                                                |
+| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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`)                                                                                               |
+| `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                                                                                                                                                    |
+| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                                                                                           |
+| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                                                                                   |
+| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                                                                                |
+| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                                                                                             |
+| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                                                                                  |
+| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                                                                                           |
 
 ---
 

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';