@fragno-dev/core 0.1.11 → 0.2.2

package/src/client/client.ts

@@ -1,12 +1,16 @@
+import { computed, task, type ReadableAtom, type Store } from "nanostores";
+
 import { nanoquery, type FetcherStore, type MutatorStore } from "@nanostores/query";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { computed, task, type ReadableAtom, type Store } from "nanostores";
+
 import type {
   FragnoRouteConfig,
   HTTPMethod,
   NonGetHTTPMethod,
   RequestThisContext,
+  RouteContentType,
 } from "../api/api";
+import type { FragmentDefinition } from "../api/fragment-definition-builder";
 import {
   buildPath,
   extractPathParams,
@@ -17,28 +21,28 @@ import {
 import { getMountRoute } from "../api/internal/route";
 import { RequestInputContext } from "../api/request-input-context";
 import { RequestOutputContext } from "../api/request-output-context";
+import {
+  type AnyFragnoRouteConfig,
+  type AnyRouteOrFactory,
+  type FlattenRouteFactories,
+  resolveRouteFactories,
+} from "../api/route";
 import type {
   FetcherConfig,
   FragnoFragmentSharedConfig,
   FragnoPublicClientConfig,
   FragnoPublicConfig,
 } from "../api/shared-types";
-import { FragnoClientApiError, FragnoClientError, FragnoClientFetchError } from "./client-error";
-import type { InferOr } from "../util/types-util";
 import { parseContentType } from "../util/content-type";
+import { unwrapObject } from "../util/nanostores";
+import { addStore, getInitialData, SSR_ENABLED } from "../util/ssr";
+import type { InferOr } from "../util/types-util";
+import { FragnoClientApiError, FragnoClientError, FragnoClientFetchError } from "./client-error";
+import { mergeFetcherConfigs } from "./internal/fetcher-merge";
 import {
   handleNdjsonStreamingFirstItem,
   type NdjsonStreamingStore,
 } from "./internal/ndjson-streaming";
-import { addStore, getInitialData, SSR_ENABLED } from "../util/ssr";
-import { unwrapObject } from "../util/nanostores";
-import type { FragmentDefinition } from "../api/fragment-definition-builder";
-import {
-  type AnyRouteOrFactory,
-  type FlattenRouteFactories,
-  resolveRouteFactories,
-} from "../api/route";
-import { mergeFetcherConfigs } from "./internal/fetcher-merge";
 
 /**
  * Symbols used to identify hook types
@@ -48,58 +52,294 @@ const MUTATOR_HOOK_SYMBOL = Symbol("fragno-mutator-hook");
 const STORE_SYMBOL = Symbol("fragno-store");
 
 /**
- * Extract only GET routes from a library config's routes array
+ * Check if a value contains files that should be sent as FormData.
  * @internal
  */
-export type ExtractGetRoutes<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
-> = {
+function containsFiles(value: unknown): boolean {
+  if (value instanceof File || value instanceof Blob) {
+    return true;
+  }
+
+  if (value instanceof FormData) {
+    return true;
+  }
+
+  if (typeof value === "object" && value !== null) {
+    return Object.values(value).some(
+      (v) => v instanceof File || v instanceof Blob || v instanceof FormData,
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Convert an object containing files to FormData.
+ * Handles nested File/Blob values by appending them directly.
+ * Other values are JSON-stringified.
+ * @internal
+ */
+function toFormData(value: object): FormData {
+  const formData = new FormData();
+
+  for (const [key, val] of Object.entries(value)) {
+    if (val instanceof File) {
+      formData.append(key, val, val.name);
+    } else if (val instanceof Blob) {
+      formData.append(key, val);
+    } else if (val !== undefined && val !== null) {
+      // For non-file values, stringify if needed
+      formData.append(key, typeof val === "string" ? val : JSON.stringify(val));
+    }
+  }
+
+  return formData;
+}
+
+/**
+ * Prepare request body and headers for sending.
+ * Handles FormData (file uploads) vs JSON data.
+ * @internal
+ */
+function prepareRequestBody(
+  body: unknown,
+  contentType?: RouteContentType,
+): { body: BodyInit | undefined; headers?: HeadersInit } {
+  if (body === undefined) {
+    return { body: undefined };
+  }
+
+  if (contentType === "application/octet-stream") {
+    if (
+      body instanceof ReadableStream ||
+      body instanceof Blob ||
+      body instanceof File ||
+      body instanceof ArrayBuffer ||
+      body instanceof Uint8Array
+    ) {
+      return { body: body as BodyInit, headers: { "Content-Type": "application/octet-stream" } };
+    }
+
+    throw new Error(
+      "Octet-stream routes only accept Blob, File, ArrayBuffer, Uint8Array, or ReadableStream bodies.",
+    );
+  }
+
+  // If already FormData, send as-is (browser sets Content-Type with boundary)
+  if (body instanceof FormData) {
+    return { body };
+  }
+
+  // If body is directly a File or Blob, wrap it in FormData
+  if (body instanceof File) {
+    const formData = new FormData();
+    formData.append("file", body, body.name);
+    return { body: formData };
+  }
+
+  if (body instanceof Blob) {
+    const formData = new FormData();
+    formData.append("file", body);
+    return { body: formData };
+  }
+
+  // If object contains files, convert to FormData
+  if (typeof body === "object" && body !== null && containsFiles(body)) {
+    return { body: toFormData(body) };
+  }
+
+  // Otherwise, JSON-stringify
+  return {
+    body: JSON.stringify(body),
+    headers: { "Content-Type": "application/json" },
+  };
+}
+
+async function schemaAllowsUndefined(schema: StandardSchemaV1): Promise<boolean> {
+  try {
+    const result = await schema["~standard"].validate(undefined);
+    return !result.issues;
+  } catch {
+    return false;
+  }
+}
+
+async function assertBodyProvided(
+  body: unknown,
+  inputSchema: StandardSchemaV1 | undefined,
+  errorMessage: string,
+): Promise<void> {
+  if (typeof body !== "undefined" || inputSchema === undefined) {
+    return;
+  }
+
+  if (await schemaAllowsUndefined(inputSchema)) {
+    return;
+  }
+
+  throw new Error(errorMessage);
+}
+
+/**
+ * Merge request headers from multiple sources.
+ * Returns undefined if there are no headers to merge.
+ * @internal
+ */
+function mergeRequestHeaders(
+  ...headerSources: (HeadersInit | undefined)[]
+): Record<string, string> | undefined {
+  const result: Record<string, string> = {};
+  let hasHeaders = false;
+
+  for (const source of headerSources) {
+    if (!source) {
+      continue;
+    }
+
+    if (source instanceof Headers) {
+      for (const [key, value] of source.entries()) {
+        result[key] = value;
+        hasHeaders = true;
+      }
+    } else if (Array.isArray(source)) {
+      for (const [key, value] of source) {
+        result[key] = value;
+        hasHeaders = true;
+      }
+    } else {
+      for (const [key, value] of Object.entries(source)) {
+        result[key] = value;
+        hasHeaders = true;
+      }
+    }
+  }
+
+  return hasHeaders ? result : undefined;
+}
+
+/**
+ * @internal
+ */
+type FilterRouteByMethod<TRoute, TExpectedMethod extends HTTPMethod> =
+  TRoute extends FragnoRouteConfig<
+    infer TMethod,
+    infer TPath,
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
+  >
+    ? [Extract<TMethod, TExpectedMethod>] extends [never]
+      ? [Extract<TExpectedMethod, TMethod>] extends [never]
+        ? never
+        : FragnoRouteConfig<
+            TMethod,
+            TPath,
+            TInputSchema,
+            TOutputSchema,
+            TErrorCode,
+            TQueryParameters,
+            TThisContext
+          >
+      : FragnoRouteConfig<
+          TMethod,
+          TPath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          TThisContext
+        >
+    : never;
+
+/**
+ * @internal
+ */
+type FilterRouteByPath<TRoute, TPath extends string> =
+  TRoute extends FragnoRouteConfig<
+    infer TMethod,
+    infer TRoutePath,
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
+  >
+    ? [Extract<TRoutePath, TPath>] extends [never]
+      ? [Extract<TPath, TRoutePath>] extends [never]
+        ? never
+        : FragnoRouteConfig<
+            TMethod,
+            TRoutePath,
+            TInputSchema,
+            TOutputSchema,
+            TErrorCode,
+            TQueryParameters,
+            TThisContext
+          >
+      : FragnoRouteConfig<
+          TMethod,
+          TRoutePath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          TThisContext
+        >
+    : never;
+
+/**
+ * @internal
+ */
+type ExtractGetRoutesExact<T extends readonly AnyFragnoRouteConfig[]> = {
   [K in keyof T]: T[K] extends FragnoRouteConfig<
-    infer Method,
-    infer Path,
-    infer Input,
-    infer Output,
-    infer ErrorCode,
-    infer QueryParams
+    infer TMethod,
+    infer TPath,
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
   >
-    ? Method extends "GET"
-      ? FragnoRouteConfig<Method, Path, Input, Output, ErrorCode, QueryParams>
+    ? TMethod extends "GET"
+      ? FragnoRouteConfig<
+          TMethod,
+          TPath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          TThisContext
+        >
       : never
     : never;
 }[number][];
 
 /**
- * Extract the path from a route configuration for a given method
+ * Extract only GET routes from a library config's routes array
  * @internal
  */
-export type ExtractRoutePath<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
+export type ExtractGetRoutes<T extends readonly AnyFragnoRouteConfig[]> = ExtractGetRoutesExact<T>;
+
+/**
+ * @internal
+ */
+type ExtractRoutePathExact<
+  T extends readonly AnyFragnoRouteConfig[],
   TExpectedMethod extends HTTPMethod = HTTPMethod,
 > = {
   [K in keyof T]: T[K] extends FragnoRouteConfig<
-    infer Method,
-    infer Path,
+    infer TMethod,
+    infer TPath,
     StandardSchemaV1 | undefined,
     StandardSchemaV1 | undefined,
     string,
-    string
+    string,
+    RequestThisContext
   >
-    ? Method extends TExpectedMethod
-      ? Path
+    ? TMethod extends TExpectedMethod
+      ? TPath
       : never
     : never;
 }[number];
@@ -107,103 +347,154 @@ export type ExtractRoutePath<
 /**
  * @internal
  */
-export type ExtractGetRoutePaths<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
+type ExtractRoutePathLoose<
+  T extends readonly AnyFragnoRouteConfig[],
+  TExpectedMethod extends HTTPMethod = HTTPMethod,
+> = {
+  [K in keyof T]: FilterRouteByMethod<T[K], TExpectedMethod> extends FragnoRouteConfig<
+    infer _TMethod,
+    infer TPath,
     StandardSchemaV1 | undefined,
     StandardSchemaV1 | undefined,
     string,
-    string
-  >[],
-> = ExtractRoutePath<T, "GET">;
+    string,
+    RequestThisContext
+  >
+    ? TPath
+    : never;
+}[number];
 
 /**
  * @internal
  */
-export type ExtractNonGetRoutePaths<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
-> = ExtractRoutePath<T, NonGetHTTPMethod>;
+type HasWidenedRouteShape<T extends readonly AnyFragnoRouteConfig[]> =
+  T[number] extends infer TRoute
+    ? TRoute extends FragnoRouteConfig<
+        infer TMethod,
+        infer TPath,
+        StandardSchemaV1 | undefined,
+        StandardSchemaV1 | undefined,
+        string,
+        string,
+        RequestThisContext
+      >
+      ? string extends TPath
+        ? true
+        : HTTPMethod extends TMethod
+          ? true
+          : false
+      : false
+    : false;
 
 /**
- * Extract the route configuration type(s) for a given path from a routes array.
- * Optionally narrow by HTTP method via the third type parameter.
- *
- * Defaults to extracting all methods for the matching path, producing a union
- * if multiple methods exist for the same path.
+ * Extract the path from a route configuration for a given method
  * @internal
  */
-export type ExtractRouteByPath<
-  TRoutes extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
+export type ExtractRoutePath<
+  T extends readonly AnyFragnoRouteConfig[],
+  TExpectedMethod extends HTTPMethod = HTTPMethod,
+> = [ExtractRoutePathExact<T, TExpectedMethod>] extends [never]
+  ? HasWidenedRouteShape<T> extends true
+    ? ExtractRoutePathLoose<T, TExpectedMethod> & string
+    : never
+  : ExtractRoutePathExact<T, TExpectedMethod>;
+
+/**
+ * @internal
+ */
+export type ExtractGetRoutePaths<T extends readonly AnyFragnoRouteConfig[]> = ExtractRoutePath<
+  T,
+  "GET"
+>;
+
+/**
+ * @internal
+ */
+export type ExtractNonGetRoutePaths<T extends readonly AnyFragnoRouteConfig[]> = ExtractRoutePath<
+  T,
+  NonGetHTTPMethod
+>;
+
+/**
+ * @internal
+ */
+type ExtractRouteByPathExact<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
   TPath extends string,
   TMethod extends HTTPMethod = HTTPMethod,
 > = {
   [K in keyof TRoutes]: TRoutes[K] extends FragnoRouteConfig<
-    infer M,
+    infer TRouteMethod,
     TPath,
-    infer Input,
-    infer Output,
-    infer ErrorCode,
-    infer QueryParams
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
   >
-    ? M extends TMethod
-      ? FragnoRouteConfig<M, TPath, Input, Output, ErrorCode, QueryParams>
+    ? TRouteMethod extends TMethod
+      ? FragnoRouteConfig<
+          TRouteMethod,
+          TPath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          TThisContext
+        >
       : never
     : never;
 }[number];
 
+/**
+ * @internal
+ */
+type ExtractRouteByPathLoose<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TPath extends string,
+  TMethod extends HTTPMethod = HTTPMethod,
+> = {
+  [K in keyof TRoutes]: FilterRouteByPath<FilterRouteByMethod<TRoutes[K], TMethod>, TPath>;
+}[number];
+
+/**
+ * Extract the route configuration type(s) for a given path from a routes array.
+ * Optionally narrow by HTTP method via the third type parameter.
+ *
+ * Defaults to extracting all methods for the matching path, producing a union
+ * if multiple methods exist for the same path.
+ * @internal
+ */
+export type ExtractRouteByPath<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TPath extends string,
+  TMethod extends HTTPMethod = HTTPMethod,
+> = [ExtractRouteByPathExact<TRoutes, TPath, TMethod>] extends [never]
+  ? HasWidenedRouteShape<TRoutes> extends true
+    ? ExtractRouteByPathLoose<TRoutes, TPath, TMethod>
+    : never
+  : ExtractRouteByPathExact<TRoutes, TPath, TMethod>;
+
 /**
  * Extract the output schema type for a specific route path from a routes array
  * @internal
  */
 export type ExtractOutputSchemaForPath<
-  TRoutes extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined
-  >[],
+  TRoutes extends readonly AnyFragnoRouteConfig[],
   TPath extends string,
-> = {
-  [K in keyof TRoutes]: TRoutes[K] extends FragnoRouteConfig<
-    infer Method,
-    TPath,
-    StandardSchemaV1 | undefined,
-    infer Output
-  >
-    ? Method extends "GET"
-      ? Output
-      : never
+> =
+  ExtractRouteByPath<TRoutes, TPath, "GET"> extends {
+    outputSchema?: infer TOutputSchema;
+  }
+    ? TOutputSchema
     : never;
-}[number];
 
 /**
  * Check if a path exists as a GET route in the routes array
  * @internal
  */
 export type IsValidGetRoutePath<
-  TRoutes extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
+  TRoutes extends readonly AnyFragnoRouteConfig[],
   TPath extends string,
 > = TPath extends ExtractGetRoutePaths<TRoutes> ? true : false;
 
@@ -212,14 +503,7 @@ export type IsValidGetRoutePath<
  * @internal
  */
 export type ValidateGetRoutePath<
-  TRoutes extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
+  TRoutes extends readonly AnyFragnoRouteConfig[],
   TPath extends string,
 > =
   TPath extends ExtractGetRoutePaths<TRoutes>
@@ -230,16 +514,8 @@ export type ValidateGetRoutePath<
  * Helper type to check if a routes array has any GET routes
  * @internal
  */
-export type HasGetRoutes<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
-> = ExtractGetRoutePaths<T> extends never ? false : true;
+export type HasGetRoutes<T extends readonly AnyFragnoRouteConfig[]> =
+  ExtractGetRoutePaths<T> extends never ? false : true;
 
 /**
  * @internal
@@ -255,11 +531,20 @@ export type ObjectContainingStoreField<T extends object> = T extends Store
 /**
  * @internal
  */
-export type FragnoStoreData<T extends object> = {
+export type FragnoStoreObjectData<T extends object> = {
   obj: T;
   [STORE_SYMBOL]: true;
 };
 
+export type FragnoStoreFactoryData<T extends object, TArgs extends unknown[] = []> = {
+  factory: (...args: TArgs) => T;
+  [STORE_SYMBOL]: true;
+};
+
+export type FragnoStoreData<T extends object, TArgs extends unknown[] = []> =
+  | FragnoStoreObjectData<T>
+  | FragnoStoreFactoryData<T, TArgs>;
+
 export type FragnoClientHookData<
   TMethod extends HTTPMethod,
   TPath extends string,
@@ -484,7 +769,9 @@ export function isMutatorHook<
 /**
  * @internal
  */
-export function isStore<TStore extends Store>(obj: unknown): obj is FragnoStoreData<TStore> {
+export function isStore<TStore extends object, TArgs extends unknown[] = []>(
+  obj: unknown,
+): obj is FragnoStoreData<TStore, TArgs> {
   return (
     typeof obj === "object" && obj !== null && STORE_SYMBOL in obj && obj[STORE_SYMBOL] === true
   );
@@ -569,8 +856,18 @@ export class ClientBuilder<
     return Object.fromEntries(this.#cache.entries());
   }
 
-  createStore<const T extends object>(obj: T): FragnoStoreData<T> {
-    return { obj: obj, [STORE_SYMBOL]: true };
+  createStore<const TArgs extends unknown[], const T extends object>(
+    factory: (...args: TArgs) => T,
+  ): FragnoStoreFactoryData<T, TArgs>;
+  createStore<const T extends object>(obj: T): FragnoStoreObjectData<T>;
+  createStore<const TArgs extends unknown[], const T extends object>(
+    input: T | ((...args: TArgs) => T),
+  ): FragnoStoreData<T, TArgs> {
+    if (typeof input === "function") {
+      return { factory: input as (...args: TArgs) => T, [STORE_SYMBOL]: true };
+    }
+
+    return { obj: input, [STORE_SYMBOL]: true };
   }
 
   /**
@@ -585,7 +882,10 @@ export class ClientBuilder<
     },
   ): string {
     const baseUrl = this.#publicConfig.baseUrl ?? "";
-    const mountRoute = getMountRoute(this.#fragmentConfig);
+    const mountRoute = getMountRoute({
+      name: this.#fragmentConfig.name,
+      mountRoute: this.#publicConfig.mountRoute,
+    });
 
     return buildUrl(
       { baseUrl, mountRoute, path },
@@ -611,7 +911,7 @@ export class ClientBuilder<
     if (this.#fetcherConfig?.type === "function") {
       return this.#fetcherConfig.fetcher;
     }
-    return fetch;
+    return globalThis.fetch.bind(globalThis);
   }
 
   #getFetcherOptions(): RequestInit | undefined {
@@ -627,9 +927,11 @@ export class ClientBuilder<
   ): FragnoClientHookData<
     "GET",
     TPath,
-    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath>["outputSchema"]>,
-    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath>["errorCodes"]>[number],
-    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath>["queryParameters"]>[number]
+    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath, "GET">["outputSchema"]>,
+    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath, "GET">["errorCodes"]>[number],
+    NonNullable<
+      ExtractRouteByPath<TFragmentConfig["routes"], TPath, "GET">["queryParameters"]
+    >[number]
   > {
     const route = this.#fragmentConfig.routes.find(
       (
@@ -717,7 +1019,10 @@ export class ClientBuilder<
     }
 
     const baseUrl = this.#publicConfig.baseUrl ?? "";
-    const mountRoute = getMountRoute(this.#fragmentConfig);
+    const mountRoute = getMountRoute({
+      name: this.#fragmentConfig.name,
+      mountRoute: this.#publicConfig.mountRoute,
+    });
     const fetcher = this.#getFetcher();
     const fetcherOptions = this.#getFetcherOptions();
 
@@ -908,7 +1213,10 @@ export class ClientBuilder<
     const method = route.method;
 
     const baseUrl = this.#publicConfig.baseUrl ?? "";
-    const mountRoute = getMountRoute(this.#fragmentConfig);
+    const mountRoute = getMountRoute({
+      name: this.#fragmentConfig.name,
+      mountRoute: this.#publicConfig.mountRoute,
+    });
     const fetcher = this.#getFetcher();
     const fetcherOptions = this.#getFetcherOptions();
 
@@ -944,11 +1252,27 @@ export class ClientBuilder<
 
       let response: Response;
       try {
-        const requestOptions: RequestInit = {
+        const { body: preparedBody, headers: bodyHeaders } = prepareRequestBody(
+          body,
+          route.contentType,
+        );
+
+        // Merge headers: fetcherOptions headers + body-specific headers (e.g., Content-Type for JSON)
+        // For FormData, bodyHeaders is undefined and browser sets Content-Type with boundary automatically
+        const mergedHeaders = mergeRequestHeaders(
+          fetcherOptions?.headers as HeadersInit | undefined,
+          bodyHeaders,
+        );
+
+        const requestOptions: RequestInit & { duplex?: "half" } = {
           ...fetcherOptions,
           method,
-          body: body !== undefined ? JSON.stringify(body) : undefined,
+          body: preparedBody,
+          ...(mergedHeaders ? { headers: mergedHeaders } : {}),
         };
+        if (preparedBody instanceof ReadableStream) {
+          requestOptions.duplex = "half";
+        }
         response = await fetcher(url, requestOptions);
       } catch (error) {
         throw FragnoClientFetchError.fromUnknownFetchError(error);
@@ -980,9 +1304,7 @@ export class ClientBuilder<
           query?: Record<string, string>;
         };
 
-        if (typeof body === "undefined" && route.inputSchema !== undefined) {
-          throw new Error("Body is required.");
-        }
+        await assertBodyProvided(body, route.inputSchema, "Body is required.");
 
         const response = await executeMutateQuery({ body, path, query });
 
@@ -1051,9 +1373,7 @@ export class ClientBuilder<
         query?: Record<string, string>;
       };
 
-      if (typeof body === "undefined" && route.inputSchema !== undefined) {
-        throw new Error("Body is required for mutateQuery");
-      }
+      await assertBodyProvided(body, route.inputSchema, "Body is required for mutateQuery");
 
       const response = await executeMutateQuery({ body, path, query });
 
@@ -1130,6 +1450,7 @@ export function createClientBuilder<
   THandlerThisContext extends RequestThisContext,
   TRequestStorage,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
+  TInternalRoutes extends readonly AnyRouteOrFactory[] = readonly [],
 >(
   definition: FragmentDefinition<
     TConfig,
@@ -1141,7 +1462,8 @@ export function createClientBuilder<
     TPrivateServices,
     TServiceThisContext,
     THandlerThisContext,
-    TRequestStorage
+    TRequestStorage,
+    TInternalRoutes
   >,
   publicConfig: FragnoPublicClientConfig,
   routesOrFactories: TRoutesOrFactories,
@@ -1166,7 +1488,10 @@ export function createClientBuilder<
     routes,
   };
 
-  const mountRoute = publicConfig.mountRoute ?? `/${definition.name}`;
+  const mountRoute = getMountRoute({
+    name: definition.name,
+    mountRoute: publicConfig.mountRoute,
+  });
   const mergedFetcherConfig = mergeFetcherConfigs(authorFetcherConfig, publicConfig.fetcherConfig);
   const fullPublicConfig = {
     ...publicConfig,