appflare 0.2.25 → 0.2.27

package/cli/templates/core/client/handlers/index.ts

@@ -1,748 +1,748 @@
-import type { DiscoveredHandlerOperation } from "../../../../utils/handler-discovery";
-
-type HttpOperation = {
-	kind: "query" | "mutation";
-	routePath: string;
-	queryName: string;
-	segments: string[];
-	importPath: string;
-	exportName: string;
-	alias: string;
-	schemaConst: string;
-	typeBase: string;
-};
-
-type TreeNode = {
-	children: Map<string, TreeNode>;
-	operation?: HttpOperation;
-};
-
-function toSafeIdentifier(value: string): string {
-	const sanitized = value.replace(/[^A-Za-z0-9_]/g, "_");
-	if (/^[0-9]/.test(sanitized)) {
-		return `_${sanitized}`;
-	}
-	return sanitized || "_route";
-}
-
-function toPascalCase(value: string): string {
-	return value
-		.split(/[^A-Za-z0-9]+/)
-		.filter(Boolean)
-		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-		.join("");
-}
-
-function toObjectKey(value: string): string {
-	if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value)) {
-		return value;
-	}
-
-	return JSON.stringify(value);
-}
-
-function createTree(operations: HttpOperation[]): TreeNode {
-	const root: TreeNode = {
-		children: new Map<string, TreeNode>(),
-	};
-
-	for (const operation of operations) {
-		let cursor = root;
-		for (const segment of operation.segments) {
-			let child = cursor.children.get(segment);
-			if (!child) {
-				child = { children: new Map<string, TreeNode>() };
-				cursor.children.set(segment, child);
-			}
-			cursor = child;
-		}
-		cursor.operation = operation;
-	}
-
-	return root;
-}
-
-function renderTreeObject(node: TreeNode, indentLevel = 1): string {
-	const indent = "\t".repeat(indentLevel);
-	const childIndent = "\t".repeat(indentLevel + 1);
-	const entries = Array.from(node.children.entries()).sort(([a], [b]) =>
-		a.localeCompare(b),
-	);
-
-	if (entries.length === 0) {
-		return node.operation ? `${node.operation.alias}Route(runtime)` : "{}";
-	}
-
-	const lines: string[] = ["{"];
-	for (const [segment, childNode] of entries) {
-		lines.push(
-			`${childIndent}${toObjectKey(segment)}: ${renderTreeObject(childNode, indentLevel + 1)},`,
-		);
-	}
-	if (node.operation) {
-		lines.push(`${childIndent}run: ${node.operation.alias}Route(runtime).run,`);
-		lines.push(
-			`${childIndent}schema: ${node.operation.alias}Route(runtime).schema,`,
-		);
-		if (node.operation.kind === "query") {
-			lines.push(
-				`${childIndent}subscribe: ${node.operation.alias}Route(runtime).subscribe,`,
-			);
-		}
-	}
-	lines.push(`${indent}}`);
-	return lines.join("\n");
-}
-
-function normalizeOperation(
-	operation: DiscoveredHandlerOperation,
-	index: number,
-): HttpOperation | null {
-	if (operation.kind !== "query" && operation.kind !== "mutation") {
-		return null;
-	}
-
-	const segments =
-		operation.clientSegments && operation.clientSegments.length > 0
-			? operation.clientSegments
-			: operation.routePath
-					.replace(/^\//, "")
-					.split("/")
-					.filter(Boolean)
-					.slice(1);
-
-	if (segments.length === 0) {
-		return null;
-	}
-
-	const alias = toSafeIdentifier(
-		`op_${index}_${operation.kind}_${segments.join("_")}`,
-	);
-
-	return {
-		kind: operation.kind,
-		routePath: operation.routePath,
-		queryName: operation.handlerName ?? segments.join("/"),
-		segments,
-		importPath: operation.clientImportPath,
-		exportName: operation.exportName,
-		alias,
-		schemaConst: `${alias}Schema`,
-		typeBase: `${toPascalCase(operation.kind)}${toPascalCase(segments.join("_"))}`,
-	};
-}
-
-function renderRouteFactory(operation: HttpOperation): string {
-	const inputType = `${operation.typeBase}Input`;
-	const outputType = `${operation.typeBase}Output`;
-	const schemaType = `${operation.typeBase}Schema`;
-	const method = operation.kind === "query" ? "GET" : "POST";
-	if (operation.kind === "query") {
-		return `const ${operation.alias}Route = (
-	runtime: RequestRuntime,
-): AppflareQueryRouteClient<typeof ${operation.schemaConst}, ${outputType}> => {
-	const run: AppflareQueryRouteClient<typeof ${operation.schemaConst}, ${outputType}>["run"] = async (
-		...params: AppflareRunParams<${inputType}>
-	) => {
-		const { args, options } = resolveRunParams<${inputType}>(params);
-		const mergedOptions = mergeRouteOptions(runtime.options, options);
-		const resultOptions: AppflareRouteCallOptions<"return"> = {
-			...(mergedOptions ?? {}),
-			errorMode: "return",
-		};
-		const parsed = ${operation.schemaConst}.parse(args);
-		return requestRoute<${outputType}>(runtime.endpoint, {
-			route: ${JSON.stringify(operation.routePath)},
-			method: ${JSON.stringify(method)},
-			input: parsed,
-			options: resultOptions,
-			getAuthToken: runtime.getAuthToken,
-		});
-	};
-	const subscribe = ({
-		onChange,
-		onError,
-		authToken,
-		args,
-		requestOptions,
-		signal,
-	}: AppflareQuerySubscribeOptions<${inputType}, ${outputType}>): AppflareRealtimeSubscription => {
-		const mergedOptions = mergeRouteOptions(runtime.options, requestOptions);
-		const parsedArgs = ${operation.schemaConst}.parse(normalizeRouteInput(args));
-		const requestAuthToken = resolveRealtimeAuthToken(authToken, mergedOptions?.headers);
-
-		let removed = false;
-		let socket: WebSocket | null = null;
-		let token: string | null = null;
-		let resolvedAuthToken = requestAuthToken;
-
-		const remove = () => {
-			if (removed) {
-				return;
-			}
-			removed = true;
-
-			if (socket && (socket.readyState === WebSocket.CONNECTING || socket.readyState === WebSocket.OPEN)) {
-				socket.close();
-			}
-
-			if (token) {
-				void requestRoute<{ ok: boolean }>(runtime.endpoint, {
-					route: "/realtime/unsubscribe",
-					method: "POST",
-					input: {
-						token,
-						authToken: resolvedAuthToken,
-					},
-					options: mergedOptions,
-					getAuthToken: runtime.getAuthToken,
-				}).catch((error) => {
-					onError?.(error);
-				});
-			}
-		};
-
-		if (signal) {
-			if (signal.aborted) {
-				remove();
-				return { remove };
-			}
-			signal.addEventListener("abort", remove, { once: true });
-		}
-
-		void (async () => {
-			try {
-				if (!resolvedAuthToken && runtime.getAuthToken) {
-					const runtimeAuthToken = await runtime.getAuthToken();
-					if (
-						typeof runtimeAuthToken === "string" &&
-						runtimeAuthToken.trim().length > 0
-					) {
-						resolvedAuthToken = runtimeAuthToken.trim();
-					}
-				}
-
-
-				const subscription = (await requestRoute<RealtimeSubscriptionResponse>(runtime.endpoint, {
-					route: "/realtime/subscribe",
-					method: "POST",
-					input: {
-						queryName: ${JSON.stringify(operation.queryName)},
-						args: parsedArgs,
-						authToken: resolvedAuthToken,
-					},
-					options: mergedOptions,
-					getAuthToken: runtime.getAuthToken,
-				})) as RealtimeSubscriptionResponse;
-
-				if (removed) {
-					return;
-				}
-
-				token = subscription.token;
-				const websocketUrl = createRealtimeWebsocketUrl(
-					subscription.websocket.url,
-					runtime.wsEndpoint,
-				);
-				websocketUrl.searchParams.set(subscription.websocket.params.tokenParam, subscription.token);
-				websocketUrl.searchParams.set(subscription.websocket.params.authTokenParam, resolvedAuthToken);
-
-				socket = new WebSocket(websocketUrl.toString(), subscription.websocket.protocol);
-				socket.addEventListener("message", (event) => {
-					if (removed) {
-						return;
-					}
-
-					const text = typeof event.data === "string" ? event.data : String(event.data ?? "");
-					let message: unknown;
-					try {
-						message = JSON.parse(text);
-					} catch {
-						return;
-					}
-
-					if (
-						typeof message === "object" &&
-						message !== null &&
-						"event" in message &&
-						(message as { event?: unknown }).event === "query:update"
-					) {
-						const payload = (message as { payload?: unknown }).payload;
-						if (typeof payload === "object" && payload !== null && "data" in payload) {
-							onChange(
-								(payload as { data: ${outputType} }).data,
-								message as AppflareRealtimeQueryUpdate<${outputType}>,
-							);
-						}
-					}
-				});
-				socket.addEventListener("error", () => {
-					onError?.(new Error("Realtime websocket error"));
-				});
-			} catch (error) {
-				if (onError) {
-					onError(error);
-				} else {
-					console.warn("[appflare:subscribe] Subscription failed:", error);
-				}
-			}
-		})();
-
-		return {
-			remove,
-		};
-	};
-
-	return {
-		schema: ${schemaType},
-		run,
-		subscribe,
-	};
-};`;
-	}
-
-	return `const ${operation.alias}Route = (
-	runtime: RequestRuntime,
-): AppflareRouteClient<typeof ${operation.schemaConst}, ${outputType}> => {
-	const run: AppflareRouteClient<typeof ${operation.schemaConst}, ${outputType}>["run"] = async (
-		...params: AppflareRunParams<${inputType}>
-	) => {
-		const { args, options } = resolveRunParams<${inputType}>(params);
-		const mergedOptions = mergeRouteOptions(runtime.options, options);
-		const resultOptions: AppflareRouteCallOptions<"return"> = {
-			...(mergedOptions ?? {}),
-			errorMode: "return",
-		};
-		const parsed = ${operation.schemaConst}.parse(args);
-		return requestRoute<${outputType}>(runtime.endpoint, {
-			route: ${JSON.stringify(operation.routePath)},
-			method: ${JSON.stringify(method)},
-			input: parsed,
-			options: resultOptions,
-			getAuthToken: runtime.getAuthToken,
-		});
-	};
-
-	return {
-		schema: ${schemaType},
-		run,
-	};
-};`;
-}
-
-export function generateClientHandlersSource(
-	operations: DiscoveredHandlerOperation[],
-): string {
-	const normalizedOperations = operations
-		.map((operation, index) => normalizeOperation(operation, index))
-		.filter((operation): operation is HttpOperation => operation !== null);
-
-	const queryOperations = normalizedOperations.filter(
-		(operation) => operation.kind === "query",
-	);
-	const mutationOperations = normalizedOperations.filter(
-		(operation) => operation.kind === "mutation",
-	);
-
-	const imports = normalizedOperations
-		.map((operation) => {
-			return `import { ${operation.exportName} as ${operation.alias} } from "${operation.importPath}";`;
-		})
-		.join("\n");
-
-	const schemaDeclarations = normalizedOperations
-		.map((operation) => {
-			const inputType = `${operation.typeBase}Input`;
-			const outputType = `${operation.typeBase}Output`;
-			const schemaType = `${operation.typeBase}Schema`;
-			return `const ${operation.schemaConst} = z.object(${operation.alias}.definition.args);
-export type ${inputType} = z.input<typeof ${operation.schemaConst}>;
-export type ${outputType} = Awaited<ReturnType<typeof ${operation.alias}.definition.handler>>;
-export const ${schemaType} = ${operation.schemaConst};`;
-		})
-		.join("\n\n");
-
-	const routeFactories = normalizedOperations
-		.map((operation) => renderRouteFactory(operation))
-		.join("\n\n");
-
-	const queryTree = renderTreeObject(createTree(queryOperations));
-	const mutationTree = renderTreeObject(createTree(mutationOperations));
-
-	return `import { z } from "zod";
-import type {
-	AppflareErrorMode,
-	AppflareRequestError,
-	AppflareRequestResult,
-	AppflareQueryRouteClient,
-	AppflareQuerySubscribeOptions,
-	AppflareRealtimeQueryUpdate,
-	AppflareRealtimeSubscription,
-	RealtimeSubscriptionResponse,
-	AppflareResultRouteCallOptions,
-	AppflareRouteCallOptions,
-	AppflareRouteClient,
-	AppflareRunParams,
-} from "./types";
-${imports ? `\n${imports}` : ""}
-
-${schemaDeclarations}
-
-type RequestRuntime = {
-	endpoint: string;
-	wsEndpoint?: string;
-	getAuthToken?: () => string | Promise<string>;
-	options?: AppflareResultRouteCallOptions;
-};
-
-type AnyRouteCallOptions = AppflareRouteCallOptions<AppflareErrorMode>;
-
-type RequestRouteInit = {
-	route: string;
-	method: "GET" | "POST";
-	input: unknown;
-	options?: AnyRouteCallOptions;
-	getAuthToken?: () => string | Promise<string>;
-};
-
-type RequestRouteReturnInit = Omit<RequestRouteInit, "options"> & {
-	options: AppflareRouteCallOptions<"return">;
-};
-
-function mergeRouteOptions(
-	base?: AppflareResultRouteCallOptions,
-	override?: AnyRouteCallOptions,
-): AnyRouteCallOptions | undefined {
-	if (!base && !override) {
-		return undefined;
-	}
-
-	return {
-		...base,
-		...override,
-		headers: {
-			...(base?.headers ?? {}),
-			...(override?.headers ?? {}),
-		},
-	};
-}
-
-function normalizeRouteInput<TInput extends Record<string, unknown>>(
-	input: TInput | undefined,
-): TInput {
-	return (input ?? {}) as TInput;
-}
-
-function resolveRunParams<TInput extends Record<string, unknown>>(
-	params: AppflareRunParams<TInput>,
-): {
-	args: TInput;
-	options?: AppflareResultRouteCallOptions;
-} {
-	const [args, options] = params;
-	return {
-		args: normalizeRouteInput(args),
-		options,
-	};
-}
-
-function readHeaderCaseInsensitive(
-	headers: HeadersInit | undefined,
-	headerName: string,
-): string {
-	if (!headers) {
-		return "";
-	}
-
-	const normalizedHeaderName = headerName.toLowerCase();
-	if (Array.isArray(headers)) {
-		for (const entry of headers) {
-			if (!Array.isArray(entry) || entry.length < 2) {
-				continue;
-			}
-
-			const key = String(entry[0]).toLowerCase();
-			if (key === normalizedHeaderName) {
-				return String(entry[1]);
-			}
-		}
-
-		return "";
-	}
-
-	if (typeof (headers as { forEach?: unknown }).forEach === "function") {
-		let value = "";
-		(headers as Headers).forEach((headerValue, key) => {
-			if (!value && key.toLowerCase() === normalizedHeaderName) {
-				value = String(headerValue);
-			}
-		});
-		return value;
-	}
-
-	for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {
-		if (key.toLowerCase() === normalizedHeaderName) {
-			return String(value ?? "");
-		}
-	}
-
-	return "";
-}
-
-function resolveRealtimeAuthToken(
-	provided: string | undefined,
-	headers: HeadersInit | undefined,
-): string {
-	if (typeof provided === "string" && provided.trim().length > 0) {
-		return provided.trim();
-	}
-
-	const authorization = readHeaderCaseInsensitive(headers, "authorization");
-	const bearerMatch = authorization.match(/^Bearer\\s+(.+)$/i);
-	if (bearerMatch && bearerMatch[1]) {
-		return bearerMatch[1].trim();
-	}
-
-	return "";
-}
-
-function hasAuthorizationHeader(headers: HeadersInit | undefined): boolean {
-	if (!headers) {
-		return false;
-	}
-
-	if (Array.isArray(headers)) {
-		return headers.some(
-			(entry) =>
-				Array.isArray(entry) &&
-				String(entry[0]).toLowerCase() === "authorization",
-		);
-	}
-
-	if (typeof (headers as { forEach?: unknown }).forEach === "function") {
-		return (headers as Headers).has("authorization");
-	}
-
-	for (const key of Object.keys(headers as Record<string, unknown>)) {
-		if (key.toLowerCase() === "authorization") {
-			return true;
-		}
-	}
-
-	return false;
-}
-
-async function resolveRequestAuthToken(
-	headers: HeadersInit | undefined,
-	getAuthToken: (() => string | Promise<string>) | undefined,
-): Promise<string> {
-	if (!getAuthToken || hasAuthorizationHeader(headers)) {
-		return "";
-	}
-
-	const token = await getAuthToken();
-	if (typeof token === "string" && token.trim().length > 0) {
-		return token.trim();
-	}
-
-	return "";
-}
-
-function createRealtimeWebsocketUrl(
-	serverUrl: string,
-	wsEndpoint: string | undefined,
-): URL {
-	const websocketUrl = new URL(serverUrl);
-	if (!wsEndpoint) {
-		return websocketUrl;
-	}
-
-	const wsBase = new URL(wsEndpoint);
-	websocketUrl.protocol = wsBase.protocol;
-	websocketUrl.host = wsBase.host;
-	if (wsBase.pathname && wsBase.pathname !== "/") {
-		websocketUrl.pathname = wsBase.pathname;
-	}
-
-	return websocketUrl;
-}
-
-function appendQueryParamValue(
-	query: URLSearchParams,
-	key: string,
-	value: unknown,
-): void {
-	if (value === undefined || value === null) {
-		return;
-	}
-
-	if (Array.isArray(value)) {
-		for (const entry of value) {
-			appendQueryParamValue(query, key, entry);
-		}
-		return;
-	}
-
-	if (value instanceof Date) {
-		query.append(key, value.toISOString());
-		return;
-	}
-
-	if (typeof value === "object") {
-		query.append(key, JSON.stringify(value));
-		return;
-	}
-
-	query.append(key, String(value));
-}
-
-function createQuery(input: unknown): string {
-	if (!input || typeof input !== "object") {
-		return "";
-	}
-
-	const query = new URLSearchParams();
-	for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
-		appendQueryParamValue(query, key, value);
-	}
-
-	const encoded = query.toString();
-	return encoded.length > 0 ? "?" + encoded : "";
-}
-
-function createRequestError(
-	init: RequestRouteInit,
-	response: Response,
-	body: unknown,
-	responseText: string,
-): AppflareRequestError {
-	const fallbackMessage =
-		responseText.trim().length > 0
-			? responseText
-			: "Request failed with status " + response.status;
-	const message =
-		typeof body === "object" &&
-		body !== null &&
-		"message" in body &&
-		typeof (body as { message?: unknown }).message === "string"
-			? ((body as { message: string }).message ?? fallbackMessage)
-			: fallbackMessage;
-
-	return {
-		route: init.route,
-		method: init.method,
-		status: response.status,
-		message,
-		body,
-		responseText,
-	};
-}
-
-async function requestRoute<TOutput>(
-	endpoint: string,
-	init: RequestRouteReturnInit,
-): Promise<AppflareRequestResult<TOutput>>;
-async function requestRoute<TOutput>(
-	endpoint: string,
-	init: RequestRouteInit,
-): Promise<TOutput | AppflareRequestResult<TOutput>>;
-async function requestRoute<TOutput>(
-	endpoint: string,
-	init: RequestRouteInit,
-): Promise<TOutput | AppflareRequestResult<TOutput>> {
-	const requestAuthToken = await resolveRequestAuthToken(
-		init.options?.headers,
-		init.getAuthToken,
-	);
-	const requestUrl =
-		init.method === "GET"
-			? endpoint + init.route + createQuery(init.input)
-			: endpoint + init.route;
-	const headers: HeadersInit = {
-		...(init.options?.headers ?? {}),
-		...(requestAuthToken
-			? { authorization: "Bearer " + requestAuthToken }
-			: {}),
-		...(init.method === "POST" ? { "content-type": "application/json" } : {}),
-	};
-
-	const response = await fetch(requestUrl, {
-		method: init.method,
-		headers,
-		body: init.method === "POST" ? JSON.stringify(init.input ?? {}) : undefined,
-		signal: init.options?.signal,
-	});
-
-	const responseText = await response.text();
-	let body: unknown = undefined;
-	if (responseText.length > 0) {
-		try {
-			body = JSON.parse(responseText);
-		} catch {
-			body = responseText;
-		}
-	}
-
-	if (!response.ok) {
-		const requestError = createRequestError(init, response, body, responseText);
-		init.options?.onError?.(requestError);
-		if (init.options?.errorMode === "return") {
-			return {
-				data: null,
-				error: requestError,
-			};
-		}
-
-		const error = new Error(requestError.message) as Error & {
-			cause?: AppflareRequestError;
-		};
-		error.cause = requestError;
-		throw error;
-	}
-
-	if (init.options?.errorMode === "return") {
-		return {
-			data: body as TOutput,
-			error: null,
-		};
-	}
-
-	return body as TOutput;
-}
-
-${routeFactories}
-
-export function createQueriesClient(
-	endpoint: string,
-	options?: AppflareResultRouteCallOptions,
-	wsEndpoint?: string,
-	getAuthToken?: () => string | Promise<string>,
-) {
-	const runtime: RequestRuntime = {
-		endpoint: endpoint.replace(/\\/$/, ""),
-		wsEndpoint: wsEndpoint?.replace(/\\/$/, ""),
-		getAuthToken,
-		options,
-	};
-
-	return ${queryTree} as const;
-}
-
-export function createMutationsClient(
-	endpoint: string,
-	options?: AppflareResultRouteCallOptions,
-	getAuthToken?: () => string | Promise<string>,
-) {
-	const runtime: RequestRuntime = {
-		endpoint: endpoint.replace(/\\/$/, ""),
-		getAuthToken,
-		options,
-	};
-
-	return ${mutationTree} as const;
-}
-
-export type QueriesClient = ReturnType<typeof createQueriesClient>;
-export type MutationsClient = ReturnType<typeof createMutationsClient>;
-`;
-}
+import type { DiscoveredHandlerOperation } from "../../../../utils/handler-discovery";
+
+type HttpOperation = {
+	kind: "query" | "mutation";
+	routePath: string;
+	queryName: string;
+	segments: string[];
+	importPath: string;
+	exportName: string;
+	alias: string;
+	schemaConst: string;
+	typeBase: string;
+};
+
+type TreeNode = {
+	children: Map<string, TreeNode>;
+	operation?: HttpOperation;
+};
+
+function toSafeIdentifier(value: string): string {
+	const sanitized = value.replace(/[^A-Za-z0-9_]/g, "_");
+	if (/^[0-9]/.test(sanitized)) {
+		return `_${sanitized}`;
+	}
+	return sanitized || "_route";
+}
+
+function toPascalCase(value: string): string {
+	return value
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean)
+		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+		.join("");
+}
+
+function toObjectKey(value: string): string {
+	if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value)) {
+		return value;
+	}
+
+	return JSON.stringify(value);
+}
+
+function createTree(operations: HttpOperation[]): TreeNode {
+	const root: TreeNode = {
+		children: new Map<string, TreeNode>(),
+	};
+
+	for (const operation of operations) {
+		let cursor = root;
+		for (const segment of operation.segments) {
+			let child = cursor.children.get(segment);
+			if (!child) {
+				child = { children: new Map<string, TreeNode>() };
+				cursor.children.set(segment, child);
+			}
+			cursor = child;
+		}
+		cursor.operation = operation;
+	}
+
+	return root;
+}
+
+function renderTreeObject(node: TreeNode, indentLevel = 1): string {
+	const indent = "\t".repeat(indentLevel);
+	const childIndent = "\t".repeat(indentLevel + 1);
+	const entries = Array.from(node.children.entries()).sort(([a], [b]) =>
+		a.localeCompare(b),
+	);
+
+	if (entries.length === 0) {
+		return node.operation ? `${node.operation.alias}Route(runtime)` : "{}";
+	}
+
+	const lines: string[] = ["{"];
+	for (const [segment, childNode] of entries) {
+		lines.push(
+			`${childIndent}${toObjectKey(segment)}: ${renderTreeObject(childNode, indentLevel + 1)},`,
+		);
+	}
+	if (node.operation) {
+		lines.push(`${childIndent}run: ${node.operation.alias}Route(runtime).run,`);
+		lines.push(
+			`${childIndent}schema: ${node.operation.alias}Route(runtime).schema,`,
+		);
+		if (node.operation.kind === "query") {
+			lines.push(
+				`${childIndent}subscribe: ${node.operation.alias}Route(runtime).subscribe,`,
+			);
+		}
+	}
+	lines.push(`${indent}}`);
+	return lines.join("\n");
+}
+
+function normalizeOperation(
+	operation: DiscoveredHandlerOperation,
+	index: number,
+): HttpOperation | null {
+	if (operation.kind !== "query" && operation.kind !== "mutation") {
+		return null;
+	}
+
+	const segments =
+		operation.clientSegments && operation.clientSegments.length > 0
+			? operation.clientSegments
+			: operation.routePath
+					.replace(/^\//, "")
+					.split("/")
+					.filter(Boolean)
+					.slice(1);
+
+	if (segments.length === 0) {
+		return null;
+	}
+
+	const alias = toSafeIdentifier(
+		`op_${index}_${operation.kind}_${segments.join("_")}`,
+	);
+
+	return {
+		kind: operation.kind,
+		routePath: operation.routePath,
+		queryName: operation.handlerName ?? segments.join("/"),
+		segments,
+		importPath: operation.clientImportPath,
+		exportName: operation.exportName,
+		alias,
+		schemaConst: `${alias}Schema`,
+		typeBase: `${toPascalCase(operation.kind)}${toPascalCase(segments.join("_"))}`,
+	};
+}
+
+function renderRouteFactory(operation: HttpOperation): string {
+	const inputType = `${operation.typeBase}Input`;
+	const outputType = `${operation.typeBase}Output`;
+	const schemaType = `${operation.typeBase}Schema`;
+	const method = operation.kind === "query" ? "GET" : "POST";
+	if (operation.kind === "query") {
+		return `const ${operation.alias}Route = (
+	runtime: RequestRuntime,
+): AppflareQueryRouteClient<typeof ${operation.schemaConst}, ${outputType}> => {
+	const run: AppflareQueryRouteClient<typeof ${operation.schemaConst}, ${outputType}>["run"] = async (
+		...params: AppflareRunParams<${inputType}>
+	) => {
+		const { args, options } = resolveRunParams<${inputType}>(params);
+		const mergedOptions = mergeRouteOptions(runtime.options, options);
+		const resultOptions: AppflareRouteCallOptions<"return"> = {
+			...(mergedOptions ?? {}),
+			errorMode: "return",
+		};
+		const parsed = ${operation.schemaConst}.parse(args);
+		return requestRoute<${outputType}>(runtime.endpoint, {
+			route: ${JSON.stringify(operation.routePath)},
+			method: ${JSON.stringify(method)},
+			input: parsed,
+			options: resultOptions,
+			getAuthToken: runtime.getAuthToken,
+		});
+	};
+	const subscribe = ({
+		onChange,
+		onError,
+		authToken,
+		args,
+		requestOptions,
+		signal,
+	}: AppflareQuerySubscribeOptions<${inputType}, ${outputType}>): AppflareRealtimeSubscription => {
+		const mergedOptions = mergeRouteOptions(runtime.options, requestOptions);
+		const parsedArgs = ${operation.schemaConst}.parse(normalizeRouteInput(args));
+		const requestAuthToken = resolveRealtimeAuthToken(authToken, mergedOptions?.headers);
+
+		let removed = false;
+		let socket: WebSocket | null = null;
+		let token: string | null = null;
+		let resolvedAuthToken = requestAuthToken;
+
+		const remove = () => {
+			if (removed) {
+				return;
+			}
+			removed = true;
+
+			if (socket && (socket.readyState === WebSocket.CONNECTING || socket.readyState === WebSocket.OPEN)) {
+				socket.close();
+			}
+
+			if (token) {
+				void requestRoute<{ ok: boolean }>(runtime.endpoint, {
+					route: "/realtime/unsubscribe",
+					method: "POST",
+					input: {
+						token,
+						authToken: resolvedAuthToken,
+					},
+					options: mergedOptions,
+					getAuthToken: runtime.getAuthToken,
+				}).catch((error) => {
+					onError?.(error);
+				});
+			}
+		};
+
+		if (signal) {
+			if (signal.aborted) {
+				remove();
+				return { remove };
+			}
+			signal.addEventListener("abort", remove, { once: true });
+		}
+
+		void (async () => {
+			try {
+				if (!resolvedAuthToken && runtime.getAuthToken) {
+					const runtimeAuthToken = await runtime.getAuthToken();
+					if (
+						typeof runtimeAuthToken === "string" &&
+						runtimeAuthToken.trim().length > 0
+					) {
+						resolvedAuthToken = runtimeAuthToken.trim();
+					}
+				}
+
+
+				const subscription = (await requestRoute<RealtimeSubscriptionResponse>(runtime.endpoint, {
+					route: "/realtime/subscribe",
+					method: "POST",
+					input: {
+						queryName: ${JSON.stringify(operation.queryName)},
+						args: parsedArgs,
+						authToken: resolvedAuthToken,
+					},
+					options: mergedOptions,
+					getAuthToken: runtime.getAuthToken,
+				})) as RealtimeSubscriptionResponse;
+
+				if (removed) {
+					return;
+				}
+
+				token = subscription.token;
+				const websocketUrl = createRealtimeWebsocketUrl(
+					subscription.websocket.url,
+					runtime.wsEndpoint,
+				);
+				websocketUrl.searchParams.set(subscription.websocket.params.tokenParam, subscription.token);
+				websocketUrl.searchParams.set(subscription.websocket.params.authTokenParam, resolvedAuthToken);
+
+				socket = new WebSocket(websocketUrl.toString(), subscription.websocket.protocol);
+				socket.addEventListener("message", (event) => {
+					if (removed) {
+						return;
+					}
+
+					const text = typeof event.data === "string" ? event.data : String(event.data ?? "");
+					let message: unknown;
+					try {
+						message = JSON.parse(text);
+					} catch {
+						return;
+					}
+
+					if (
+						typeof message === "object" &&
+						message !== null &&
+						"event" in message &&
+						(message as { event?: unknown }).event === "query:update"
+					) {
+						const payload = (message as { payload?: unknown }).payload;
+						if (typeof payload === "object" && payload !== null && "data" in payload) {
+							onChange(
+								(payload as { data: ${outputType} }).data,
+								message as AppflareRealtimeQueryUpdate<${outputType}>,
+							);
+						}
+					}
+				});
+				socket.addEventListener("error", () => {
+					onError?.(new Error("Realtime websocket error"));
+				});
+			} catch (error) {
+				if (onError) {
+					onError(error);
+				} else {
+					console.warn("[appflare:subscribe] Subscription failed:", error);
+				}
+			}
+		})();
+
+		return {
+			remove,
+		};
+	};
+
+	return {
+		schema: ${schemaType},
+		run,
+		subscribe,
+	};
+};`;
+	}
+
+	return `const ${operation.alias}Route = (
+	runtime: RequestRuntime,
+): AppflareRouteClient<typeof ${operation.schemaConst}, ${outputType}> => {
+	const run: AppflareRouteClient<typeof ${operation.schemaConst}, ${outputType}>["run"] = async (
+		...params: AppflareRunParams<${inputType}>
+	) => {
+		const { args, options } = resolveRunParams<${inputType}>(params);
+		const mergedOptions = mergeRouteOptions(runtime.options, options);
+		const resultOptions: AppflareRouteCallOptions<"return"> = {
+			...(mergedOptions ?? {}),
+			errorMode: "return",
+		};
+		const parsed = ${operation.schemaConst}.parse(args);
+		return requestRoute<${outputType}>(runtime.endpoint, {
+			route: ${JSON.stringify(operation.routePath)},
+			method: ${JSON.stringify(method)},
+			input: parsed,
+			options: resultOptions,
+			getAuthToken: runtime.getAuthToken,
+		});
+	};
+
+	return {
+		schema: ${schemaType},
+		run,
+	};
+};`;
+}
+
+export function generateClientHandlersSource(
+	operations: DiscoveredHandlerOperation[],
+): string {
+	const normalizedOperations = operations
+		.map((operation, index) => normalizeOperation(operation, index))
+		.filter((operation): operation is HttpOperation => operation !== null);
+
+	const queryOperations = normalizedOperations.filter(
+		(operation) => operation.kind === "query",
+	);
+	const mutationOperations = normalizedOperations.filter(
+		(operation) => operation.kind === "mutation",
+	);
+
+	const imports = normalizedOperations
+		.map((operation) => {
+			return `import { ${operation.exportName} as ${operation.alias} } from "${operation.importPath}";`;
+		})
+		.join("\n");
+
+	const schemaDeclarations = normalizedOperations
+		.map((operation) => {
+			const inputType = `${operation.typeBase}Input`;
+			const outputType = `${operation.typeBase}Output`;
+			const schemaType = `${operation.typeBase}Schema`;
+			return `const ${operation.schemaConst} = z.object(${operation.alias}.definition.args);
+export type ${inputType} = z.input<typeof ${operation.schemaConst}>;
+export type ${outputType} = Awaited<ReturnType<typeof ${operation.alias}.definition.handler>>;
+export const ${schemaType} = ${operation.schemaConst};`;
+		})
+		.join("\n\n");
+
+	const routeFactories = normalizedOperations
+		.map((operation) => renderRouteFactory(operation))
+		.join("\n\n");
+
+	const queryTree = renderTreeObject(createTree(queryOperations));
+	const mutationTree = renderTreeObject(createTree(mutationOperations));
+
+	return `import { z } from "zod";
+import type {
+	AppflareErrorMode,
+	AppflareRequestError,
+	AppflareRequestResult,
+	AppflareQueryRouteClient,
+	AppflareQuerySubscribeOptions,
+	AppflareRealtimeQueryUpdate,
+	AppflareRealtimeSubscription,
+	RealtimeSubscriptionResponse,
+	AppflareResultRouteCallOptions,
+	AppflareRouteCallOptions,
+	AppflareRouteClient,
+	AppflareRunParams,
+} from "./types";
+${imports ? `\n${imports}` : ""}
+
+${schemaDeclarations}
+
+type RequestRuntime = {
+	endpoint: string;
+	wsEndpoint?: string;
+	getAuthToken?: () => string | Promise<string>;
+	options?: AppflareResultRouteCallOptions;
+};
+
+type AnyRouteCallOptions = AppflareRouteCallOptions<AppflareErrorMode>;
+
+type RequestRouteInit = {
+	route: string;
+	method: "GET" | "POST";
+	input: unknown;
+	options?: AnyRouteCallOptions;
+	getAuthToken?: () => string | Promise<string>;
+};
+
+type RequestRouteReturnInit = Omit<RequestRouteInit, "options"> & {
+	options: AppflareRouteCallOptions<"return">;
+};
+
+function mergeRouteOptions(
+	base?: AppflareResultRouteCallOptions,
+	override?: AnyRouteCallOptions,
+): AnyRouteCallOptions | undefined {
+	if (!base && !override) {
+		return undefined;
+	}
+
+	return {
+		...base,
+		...override,
+		headers: {
+			...(base?.headers ?? {}),
+			...(override?.headers ?? {}),
+		},
+	};
+}
+
+function normalizeRouteInput<TInput extends Record<string, unknown>>(
+	input: TInput | undefined,
+): TInput {
+	return (input ?? {}) as TInput;
+}
+
+function resolveRunParams<TInput extends Record<string, unknown>>(
+	params: AppflareRunParams<TInput>,
+): {
+	args: TInput;
+	options?: AppflareResultRouteCallOptions;
+} {
+	const [args, options] = params;
+	return {
+		args: normalizeRouteInput(args),
+		options,
+	};
+}
+
+function readHeaderCaseInsensitive(
+	headers: HeadersInit | undefined,
+	headerName: string,
+): string {
+	if (!headers) {
+		return "";
+	}
+
+	const normalizedHeaderName = headerName.toLowerCase();
+	if (Array.isArray(headers)) {
+		for (const entry of headers) {
+			if (!Array.isArray(entry) || entry.length < 2) {
+				continue;
+			}
+
+			const key = String(entry[0]).toLowerCase();
+			if (key === normalizedHeaderName) {
+				return String(entry[1]);
+			}
+		}
+
+		return "";
+	}
+
+	if (typeof (headers as { forEach?: unknown }).forEach === "function") {
+		let value = "";
+		(headers as Headers).forEach((headerValue, key) => {
+			if (!value && key.toLowerCase() === normalizedHeaderName) {
+				value = String(headerValue);
+			}
+		});
+		return value;
+	}
+
+	for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {
+		if (key.toLowerCase() === normalizedHeaderName) {
+			return String(value ?? "");
+		}
+	}
+
+	return "";
+}
+
+function resolveRealtimeAuthToken(
+	provided: string | undefined,
+	headers: HeadersInit | undefined,
+): string {
+	if (typeof provided === "string" && provided.trim().length > 0) {
+		return provided.trim();
+	}
+
+	const authorization = readHeaderCaseInsensitive(headers, "authorization");
+	const bearerMatch = authorization.match(/^Bearer\\s+(.+)$/i);
+	if (bearerMatch && bearerMatch[1]) {
+		return bearerMatch[1].trim();
+	}
+
+	return "";
+}
+
+function hasAuthorizationHeader(headers: HeadersInit | undefined): boolean {
+	if (!headers) {
+		return false;
+	}
+
+	if (Array.isArray(headers)) {
+		return headers.some(
+			(entry) =>
+				Array.isArray(entry) &&
+				String(entry[0]).toLowerCase() === "authorization",
+		);
+	}
+
+	if (typeof (headers as { forEach?: unknown }).forEach === "function") {
+		return (headers as Headers).has("authorization");
+	}
+
+	for (const key of Object.keys(headers as Record<string, unknown>)) {
+		if (key.toLowerCase() === "authorization") {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+async function resolveRequestAuthToken(
+	headers: HeadersInit | undefined,
+	getAuthToken: (() => string | Promise<string>) | undefined,
+): Promise<string> {
+	if (!getAuthToken || hasAuthorizationHeader(headers)) {
+		return "";
+	}
+
+	const token = await getAuthToken();
+	if (typeof token === "string" && token.trim().length > 0) {
+		return token.trim();
+	}
+
+	return "";
+}
+
+function createRealtimeWebsocketUrl(
+	serverUrl: string,
+	wsEndpoint: string | undefined,
+): URL {
+	const websocketUrl = new URL(serverUrl);
+	if (!wsEndpoint) {
+		return websocketUrl;
+	}
+
+	const wsBase = new URL(wsEndpoint);
+	websocketUrl.protocol = wsBase.protocol;
+	websocketUrl.host = wsBase.host;
+	if (wsBase.pathname && wsBase.pathname !== "/") {
+		websocketUrl.pathname = wsBase.pathname;
+	}
+
+	return websocketUrl;
+}
+
+function appendQueryParamValue(
+	query: URLSearchParams,
+	key: string,
+	value: unknown,
+): void {
+	if (value === undefined || value === null) {
+		return;
+	}
+
+	if (Array.isArray(value)) {
+		for (const entry of value) {
+			appendQueryParamValue(query, key, entry);
+		}
+		return;
+	}
+
+	if (value instanceof Date) {
+		query.append(key, value.toISOString());
+		return;
+	}
+
+	if (typeof value === "object") {
+		query.append(key, JSON.stringify(value));
+		return;
+	}
+
+	query.append(key, String(value));
+}
+
+function createQuery(input: unknown): string {
+	if (!input || typeof input !== "object") {
+		return "";
+	}
+
+	const query = new URLSearchParams();
+	for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+		appendQueryParamValue(query, key, value);
+	}
+
+	const encoded = query.toString();
+	return encoded.length > 0 ? "?" + encoded : "";
+}
+
+function createRequestError(
+	init: RequestRouteInit,
+	response: Response,
+	body: unknown,
+	responseText: string,
+): AppflareRequestError {
+	const fallbackMessage =
+		responseText.trim().length > 0
+			? responseText
+			: "Request failed with status " + response.status;
+	const message =
+		typeof body === "object" &&
+		body !== null &&
+		"message" in body &&
+		typeof (body as { message?: unknown }).message === "string"
+			? ((body as { message: string }).message ?? fallbackMessage)
+			: fallbackMessage;
+
+	return {
+		route: init.route,
+		method: init.method,
+		status: response.status,
+		message,
+		body,
+		responseText,
+	};
+}
+
+async function requestRoute<TOutput>(
+	endpoint: string,
+	init: RequestRouteReturnInit,
+): Promise<AppflareRequestResult<TOutput>>;
+async function requestRoute<TOutput>(
+	endpoint: string,
+	init: RequestRouteInit,
+): Promise<TOutput | AppflareRequestResult<TOutput>>;
+async function requestRoute<TOutput>(
+	endpoint: string,
+	init: RequestRouteInit,
+): Promise<TOutput | AppflareRequestResult<TOutput>> {
+	const requestAuthToken = await resolveRequestAuthToken(
+		init.options?.headers,
+		init.getAuthToken,
+	);
+	const requestUrl =
+		init.method === "GET"
+			? endpoint + init.route + createQuery(init.input)
+			: endpoint + init.route;
+	const headers: HeadersInit = {
+		...(init.options?.headers ?? {}),
+		...(requestAuthToken
+			? { authorization: "Bearer " + requestAuthToken }
+			: {}),
+		...(init.method === "POST" ? { "content-type": "application/json" } : {}),
+	};
+
+	const response = await fetch(requestUrl, {
+		method: init.method,
+		headers,
+		body: init.method === "POST" ? JSON.stringify(init.input ?? {}) : undefined,
+		signal: init.options?.signal,
+	});
+
+	const responseText = await response.text();
+	let body: unknown = undefined;
+	if (responseText.length > 0) {
+		try {
+			body = JSON.parse(responseText);
+		} catch {
+			body = responseText;
+		}
+	}
+
+	if (!response.ok) {
+		const requestError = createRequestError(init, response, body, responseText);
+		init.options?.onError?.(requestError);
+		if (init.options?.errorMode === "return") {
+			return {
+				data: null,
+				error: requestError,
+			};
+		}
+
+		const error = new Error(requestError.message) as Error & {
+			cause?: AppflareRequestError;
+		};
+		error.cause = requestError;
+		throw error;
+	}
+
+	if (init.options?.errorMode === "return") {
+		return {
+			data: body as TOutput,
+			error: null,
+		};
+	}
+
+	return body as TOutput;
+}
+
+${routeFactories}
+
+export function createQueriesClient(
+	endpoint: string,
+	options?: AppflareResultRouteCallOptions,
+	wsEndpoint?: string,
+	getAuthToken?: () => string | Promise<string>,
+) {
+	const runtime: RequestRuntime = {
+		endpoint: endpoint.replace(/\\/$/, ""),
+		wsEndpoint: wsEndpoint?.replace(/\\/$/, ""),
+		getAuthToken,
+		options,
+	};
+
+	return ${queryTree} as const;
+}
+
+export function createMutationsClient(
+	endpoint: string,
+	options?: AppflareResultRouteCallOptions,
+	getAuthToken?: () => string | Promise<string>,
+) {
+	const runtime: RequestRuntime = {
+		endpoint: endpoint.replace(/\\/$/, ""),
+		getAuthToken,
+		options,
+	};
+
+	return ${mutationTree} as const;
+}
+
+export type QueriesClient = ReturnType<typeof createQueriesClient>;
+export type MutationsClient = ReturnType<typeof createMutationsClient>;
+`;
+}