@emeryld/rrroutes-client 1.3.2 → 1.3.4

package/dist/index.cjs

@@ -0,0 +1,454 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createRouteClient: () => createRouteClient,
+  defaultFetcher: () => defaultFetcher
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/routesV3.client.fetch.ts
+var defaultFetcher = async (req) => {
+  const headers = { ...req.headers ?? {} };
+  const isFormData = typeof FormData !== "undefined" && req.body instanceof FormData;
+  if (!isFormData) {
+    headers["Content-Type"] || (headers["Content-Type"] = "application/json");
+    headers["Accept"] || (headers["Accept"] = "application/json");
+  }
+  const res = await fetch(req.url, {
+    method: req.method,
+    headers,
+    body: isFormData ? req.body : req.body == null ? void 0 : JSON.stringify(req.body)
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    const snippet = text.slice(0, 400);
+    throw new Error(`[${res.status}] ${res.statusText} \u2014 ${snippet}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+// src/routesV3.client.index.ts
+var import_react_query = require("@tanstack/react-query");
+var import_rrroutes_contract = require("@emeryld/rrroutes-contract");
+var toUpper = (m) => m.toUpperCase();
+function zParse(value, schema) {
+  return schema ? schema.parse(value) : value;
+}
+function toSearchString(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v == null) continue;
+    if (Array.isArray(v)) {
+      v.forEach((x) => {
+        if (x == null) return;
+        if (typeof x === "object") {
+          params.append(k, JSON.stringify(x));
+        } else {
+          params.append(k, String(x));
+        }
+      });
+      continue;
+    }
+    if (typeof v === "object") {
+      params.set(k, JSON.stringify(v));
+      continue;
+    }
+    params.set(k, String(v));
+  }
+  const s = params.toString();
+  return s ? `?${s}` : "";
+}
+function stripKey(obj, key) {
+  if (!obj) return obj;
+  const { [key]: _omit, ...rest } = obj;
+  return rest;
+}
+var defaultGetNextCursor = (p) => p && typeof p === "object" && "nextCursor" in p ? p.nextCursor : void 0;
+var defaultDebugLogger = (event) => {
+  if (typeof console === "undefined") return;
+  const fn = console.debug ?? console.log;
+  fn?.call(console, "[rrroutes-client]", event);
+};
+var debugEventTypes = [
+  "fetch",
+  "invalidate",
+  "setData",
+  "build",
+  "useEndpoint"
+];
+var noopEmit = () => {
+};
+function createDebugEmitter(option, environment) {
+  const disabled = { emit: noopEmit, mode: "minimal" };
+  if (environment && environment.toLowerCase() === "production") {
+    return disabled;
+  }
+  if (!option) {
+    return disabled;
+  }
+  if (option === true || option === "minimal") {
+    return {
+      emit: (event, name) => defaultDebugLogger(name ? { ...event, name } : event),
+      mode: "minimal"
+    };
+  }
+  if (option === "complete") {
+    return {
+      emit: (event, name) => defaultDebugLogger(name ? { ...event, name } : event),
+      mode: "complete"
+    };
+  }
+  if (typeof option === "function") {
+    return {
+      emit: (event, name) => option(name ? { ...event, name } : event),
+      mode: "minimal"
+    };
+  }
+  if (typeof option === "object") {
+    const toggles = option;
+    const verbose = Boolean(toggles.verbose);
+    const enabledTypes = debugEventTypes.filter((type) => toggles[type]);
+    if (enabledTypes.length === 0) {
+      return { emit: noopEmit, mode: verbose ? "complete" : "minimal" };
+    }
+    const whitelist = new Set(enabledTypes);
+    const onlySet = toggles.only && toggles.only.length > 0 ? new Set(toggles.only) : void 0;
+    const logger = toggles.logger ?? defaultDebugLogger;
+    const emit = (event, name) => {
+      if (!whitelist.has(event.type)) return;
+      if (onlySet) {
+        if (!name || !onlySet.has(name)) return;
+      }
+      logger(name ? { ...event, name } : event);
+    };
+    return { emit, mode: verbose ? "complete" : "minimal" };
+  }
+  return disabled;
+}
+function extractArgs(args) {
+  return args[0];
+}
+function buildUrl(leaf, baseUrl, params, query) {
+  const normalizedParams = zParse(params, leaf.cfg.paramsSchema);
+  const normalizedQuery = zParse(query, leaf.cfg.querySchema);
+  const path = (0, import_rrroutes_contract.compilePath)(leaf.path, normalizedParams ?? {});
+  const url = `${baseUrl ?? ""}${path}${toSearchString(normalizedQuery)}`;
+  return { url, normalizedQuery, normalizedParams };
+}
+function createRouteClient(opts) {
+  const queryClient = opts.queryClient;
+  const fetcher = opts.fetcher ?? defaultFetcher;
+  const baseUrl = opts.baseUrl;
+  const cursorParam = opts.cursorParam ?? "cursor";
+  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;
+  const environment = opts.environment ?? (typeof process !== "undefined" && process.env ? process.env.NODE_ENV : void 0);
+  const { emit: emitDebug, mode: debugMode } = createDebugEmitter(opts.debug, environment);
+  const isVerboseDebug = debugMode === "complete";
+  const decorateDebugEvent = (event, details) => {
+    if (!isVerboseDebug || !details) return event;
+    return { ...event, ...details };
+  };
+  async function invalidate(prefix, exact = false) {
+    const queryKey = prefix;
+    await queryClient.invalidateQueries({ queryKey, exact });
+    emitDebug({ type: "invalidate", key: queryKey, exact });
+  }
+  function buildInternal(leaf, rqOpts, meta) {
+    const isGet = leaf.method === "get";
+    const isFeed = !!leaf.cfg.feed;
+    const method = toUpper(leaf.method);
+    const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;
+    const debugName = meta?.name;
+    const emit = (event) => emitDebug(event, debugName);
+    emit({ type: "build", leaf: leafLabel });
+    const key = (...tuple) => {
+      const a = extractArgs(tuple);
+      const params = a?.params;
+      const query = a?.query;
+      const qForKey = isGet && isFeed ? stripKey(query, cursorParam) : query;
+      return (0, import_rrroutes_contract.buildCacheKey)({ leaf, params, query: qForKey });
+    };
+    const invalidateExact = async (...tuple) => {
+      const queryKey = key(...tuple);
+      await queryClient.invalidateQueries({ queryKey, exact: true });
+      emit({ type: "invalidate", key: queryKey, exact: true });
+    };
+    const setData = (...args) => {
+      const [updater, ...rest] = args;
+      const k = key(...rest);
+      if (isGet && isFeed) {
+        queryClient.setQueryData(
+          k,
+          (prev) => typeof updater === "function" ? updater(prev) : updater
+        );
+      } else {
+        queryClient.setQueryData(
+          k,
+          (prev) => typeof updater === "function" ? updater(prev) : updater
+        );
+      }
+      emit({ type: "setData", key: k });
+    };
+    if (isGet && isFeed) {
+      const useEndpoint2 = (...tuple) => {
+        emit({ type: "useEndpoint", leaf: leafLabel, variant: "infiniteGet" });
+        const a = extractArgs(tuple);
+        const params = a?.params;
+        const query = a?.query;
+        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
+        return (0, import_react_query.useInfiniteQuery)({
+          ...rqOpts,
+          queryKey: key(...tuple),
+          initialPageParam: void 0,
+          getNextPageParam: (lastPage) => getNextCursor(lastPage),
+          placeholderData: import_react_query.keepPreviousData,
+          queryFn: async ({ pageParam }) => {
+            const pageQuery = {
+              ...normalizedQuery,
+              ...pageParam ? { [cursorParam]: pageParam } : {}
+            };
+            const { url } = buildUrl(leaf, baseUrl, params, pageQuery);
+            const startedAt = Date.now();
+            const detail = isVerboseDebug ? { params: normalizedParams, query: pageQuery } : void 0;
+            emit(
+              decorateDebugEvent(
+                { type: "fetch", stage: "start", method, url, leaf: leafLabel },
+                detail
+              )
+            );
+            try {
+              const out = await fetcher({ url, method });
+              const parsed = zParse(out, leaf.cfg.outputSchema);
+              emit(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "success",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt
+                  },
+                  isVerboseDebug ? { params: normalizedParams, query: pageQuery, output: parsed } : void 0
+                )
+              );
+              return parsed;
+            } catch (error) {
+              emit(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "error",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt,
+                    error
+                  },
+                  detail
+                )
+              );
+              throw error;
+            }
+          }
+          // NOTE: TData is InfiniteData<T>, so we don't need a select here.
+        }, queryClient);
+      };
+      return {
+        key,
+        invalidate: invalidateExact,
+        setData,
+        useEndpoint: useEndpoint2
+      };
+    }
+    if (isGet) {
+      const useEndpoint2 = (...tuple) => {
+        emit({ type: "useEndpoint", leaf: leafLabel, variant: "get" });
+        const a = extractArgs(tuple);
+        const params = a?.params;
+        const query = a?.query;
+        const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
+        return (0, import_react_query.useQuery)({
+          ...rqOpts,
+          queryKey: key(...tuple),
+          placeholderData: import_react_query.keepPreviousData,
+          queryFn: async () => {
+            const startedAt = Date.now();
+            const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+            emit(
+              decorateDebugEvent(
+                { type: "fetch", stage: "start", method, url, leaf: leafLabel },
+                detail
+              )
+            );
+            try {
+              const out = await fetcher({ url, method });
+              const parsed = zParse(out, leaf.cfg.outputSchema);
+              emit(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "success",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt
+                  },
+                  isVerboseDebug ? { params: normalizedParams, query: normalizedQuery, output: parsed } : void 0
+                )
+              );
+              return parsed;
+            } catch (error) {
+              emit(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "error",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt,
+                    error
+                  },
+                  detail
+                )
+              );
+              throw error;
+            }
+          }
+        }, queryClient);
+      };
+      return {
+        key,
+        invalidate: invalidateExact,
+        setData,
+        useEndpoint: useEndpoint2
+      };
+    }
+    const fetchEndpoint = async (...tupleWithBody) => {
+      if (tupleWithBody.length === 0) {
+        throw new Error("Body is required when invoking a mutation fetch.");
+      }
+      const bodyIndex = tupleWithBody.length - 1;
+      const tuple = tupleWithBody.slice(0, bodyIndex);
+      const body = tupleWithBody[bodyIndex];
+      const args = extractArgs(tuple);
+      const params = args?.params;
+      const query = args?.query;
+      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
+      const normalizedBody = zParse(body, leaf.cfg.bodySchema);
+      const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;
+      const payload = isMultipart ? toFormData(normalizedBody) : normalizedBody;
+      const startedAt = Date.now();
+      const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+      emit(
+        decorateDebugEvent(
+          {
+            type: "fetch",
+            stage: "start",
+            method,
+            url,
+            leaf: leafLabel,
+            body: payload
+          },
+          detail
+        )
+      );
+      try {
+        const out = await fetcher({ url, method, body: payload });
+        const parsed = zParse(out, leaf.cfg.outputSchema);
+        emit(
+          decorateDebugEvent(
+            {
+              type: "fetch",
+              stage: "success",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt
+            },
+            isVerboseDebug ? { params: normalizedParams, query: normalizedQuery, output: parsed } : void 0
+          )
+        );
+        return parsed;
+      } catch (error) {
+        emit(
+          decorateDebugEvent(
+            {
+              type: "fetch",
+              stage: "error",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt,
+              body: payload,
+              error
+            },
+            detail
+          )
+        );
+        throw error;
+      }
+    };
+    const useEndpoint = (...tuple) => {
+      emit({ type: "useEndpoint", leaf: leafLabel, variant: "mutation" });
+      return (0, import_react_query.useMutation)({
+        ...rqOpts,
+        mutationKey: key(...tuple),
+        mutationFn: (body) => fetchEndpoint(...[...tuple, body])
+      }, queryClient);
+    };
+    return {
+      key,
+      invalidate: invalidateExact,
+      setData,
+      useEndpoint,
+      fetch: fetchEndpoint
+    };
+  }
+  return {
+    queryClient,
+    invalidate,
+    build: buildInternal
+  };
+}
+function toFormData(body) {
+  const fd = new FormData();
+  for (const [k, v] of Object.entries(body ?? {})) {
+    if (v == null) continue;
+    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item));
+    else fd.append(k, v);
+  }
+  return fd;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRouteClient,
+  defaultFetcher
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/routesV3.client.fetch.ts","../src/routesV3.client.index.ts"],"sourcesContent":["/**\n * This package exports React Query hooks, so we mark it as client-only to keep Next.js happy.\n */\n'use client';\n\nexport * from './routesV3.client.types';\nexport * from './routesV3.client.fetch';\nexport * from './routesV3.client.index';\n","// routesV3.client.fetch.ts\n\nimport { Fetcher, FetchInput } from './routesV3.client.types';\n\n/**\n * Default fetch implementation used by the route client helper.\n * @param req Normalized request information (URL, method, body, headers).\n * @returns Parsed JSON (or text fallback) from the server response.\n */\nexport const defaultFetcher: Fetcher = async <T>(req: FetchInput): Promise<T> => {\n  const headers: Record<string, string> = { ...(req.headers ?? {}) };\n  const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;\n  if (!isFormData) {\n    headers['Content-Type'] ||= 'application/json';\n    headers['Accept'] ||= 'application/json';\n  }\n\n  const res = await fetch(req.url, {\n    method: req.method,\n    headers,\n    body: isFormData ? (req.body as any) : req.body == null ? undefined : JSON.stringify(req.body),\n  });\n\n  const text = await res.text();\n  if (!res.ok) {\n    const snippet = text.slice(0, 400);\n    throw new Error(`[${res.status}] ${res.statusText} — ${snippet}`);\n  }\n\n  try {\n    return JSON.parse(text) as T;\n  } catch {\n    return text as unknown as T;\n  }\n};\n","// routesV3.client.ts\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  type InfiniteData,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport type { ZodType } from 'zod';\nimport {\n  HttpMethod,\n  buildCacheKey,\n  compilePath,\n} from '@emeryld/rrroutes-contract';\nimport type {\n  AnyLeaf,\n  InferBody,\n  InferOutput,\n  InferParams,\n  InferQuery,\n} from '@emeryld/rrroutes-contract';\nimport { defaultFetcher } from './routesV3.client.fetch';\nimport type {\n  ArgsFor,\n  ArgsTuple,\n  BuildMeta,\n  BuiltForLeaf,\n  BuiltInfinite,\n  BuiltMutation,\n  BuiltQuery,\n  Cursor,\n  DataShape,\n  InfiniteBuildOptionsFor,\n  MutationBuildOptionsFor,\n  QueryBuildOptionsFor,\n  RouteClient,\n  RouteClientOptions,\n  RouteClientDebugEvent,\n  RouteClientDebugLogger,\n  RouteClientDebugMode,\n  RouteClientDebugOptions,\n  RouteClientDebugToggleOptions,\n  Updater,\n} from './routesV3.client.types';\n\n// -------------------------------------------------------------------------------------\n// Tiny helpers\n// -------------------------------------------------------------------------------------\n/**\n * Convert an HTTP method to uppercase (as expected by fetch).\n * @param m Lowercase HTTP method.\n * @returns Uppercase method string.\n */\nconst toUpper = (m: HttpMethod): Uppercase<HttpMethod> => m.toUpperCase() as Uppercase<HttpMethod>;\n\n/**\n * Parse the given value with the supplied schema (if present).\n * @param value Raw value to validate.\n * @param schema Optional Zod schema used for validation/coercion.\n * @returns The validated or original value.\n */\nfunction zParse<T>(value: unknown, schema?: ZodType): T {\n  return schema ? (schema.parse(value) as T) : (value as T);\n}\n\n/**\n * Serialize a query object into a search string.\n * @param query Query params object (possibly undefined).\n * @returns Query string prefixed with `?`, or empty string.\n */\nfunction toSearchString(query: Record<string, unknown> | undefined) {\n  if (!query) return '';\n  const params = new URLSearchParams();\n  for (const [k, v] of Object.entries(query)) {\n    if (v == null) continue;\n    if (Array.isArray(v)) {\n      v.forEach((x) => {\n        if (x == null) return;\n        if (typeof x === 'object') {\n          params.append(k, JSON.stringify(x));\n        } else {\n          params.append(k, String(x));\n        }\n      });\n      continue;\n    }\n    if (typeof v === 'object') {\n      params.set(k, JSON.stringify(v));\n      continue;\n    }\n    params.set(k, String(v));\n  }\n  const s = params.toString();\n  return s ? `?${s}` : '';\n}\n\n/**\n * Remove the given key from an object (used to drop cursors from cache keys).\n * @param obj Source object.\n * @param key Property name to omit.\n * @returns Copy of the object without the specified key.\n */\nfunction stripKey<Q extends Record<string, unknown> | undefined>(obj: Q, key: string): Q {\n  if (!obj) return obj;\n  const { [key]: _omit, ...rest } = obj as any;\n  return rest as Q;\n}\n\n/**\n * Default cursor extractor used by infinite queries.\n * @param p Page result returned from the server.\n * @returns Next cursor string, if present.\n */\nconst defaultGetNextCursor = (p: unknown): Cursor =>\n  p && typeof p === 'object' && 'nextCursor' in p ? (p as any).nextCursor : undefined;\n\n// Debug logging --------------------------------------------------------------\nconst noopDebugLogger: RouteClientDebugLogger = () => {};\n\nconst defaultDebugLogger: RouteClientDebugLogger = (event: RouteClientDebugEvent) => {\n  if (typeof console === 'undefined') return;\n  const fn = console.debug ?? console.log;\n  fn?.call(console, '[rrroutes-client]', event);\n};\n\nconst debugEventTypes: RouteClientDebugEvent['type'][] = [\n  'fetch',\n  'invalidate',\n  'setData',\n  'build',\n  'useEndpoint',\n];\n\ntype DebugEmitter<Names extends string> = {\n  emit: (event: RouteClientDebugEvent, name?: Names) => void;\n  mode: RouteClientDebugMode;\n};\n\nconst noopEmit = () => {};\n\nfunction createDebugEmitter<Names extends string>(\n  option?: RouteClientDebugOptions<Names>,\n  environment?: string,\n): DebugEmitter<Names> {\n  const disabled: DebugEmitter<Names> = { emit: noopEmit, mode: 'minimal' };\n\n  if (environment && environment.toLowerCase() === 'production') {\n    return disabled;\n  }\n\n  if (!option) {\n    return disabled;\n  }\n  if (option === true || option === 'minimal') {\n    return {\n      emit: (event, name) => defaultDebugLogger(name ? { ...event, name } : event),\n      mode: 'minimal',\n    };\n  }\n  if (option === 'complete') {\n    return {\n      emit: (event, name) => defaultDebugLogger(name ? { ...event, name } : event),\n      mode: 'complete',\n    };\n  }\n  if (typeof option === 'function') {\n    return {\n      emit: (event, name) => option(name ? { ...event, name } : event),\n      mode: 'minimal',\n    };\n  }\n  if (typeof option === 'object') {\n    const toggles = option as RouteClientDebugToggleOptions<Names>;\n    const verbose = Boolean(toggles.verbose);\n    const enabledTypes = debugEventTypes.filter((type) => toggles[type]);\n    if (enabledTypes.length === 0) {\n      return { emit: noopEmit, mode: verbose ? 'complete' : 'minimal' };\n    }\n    const whitelist = new Set<RouteClientDebugEvent['type']>(enabledTypes);\n    const onlySet =\n      toggles.only && toggles.only.length > 0 ? new Set<Names>(toggles.only) : undefined;\n    const logger = toggles.logger ?? defaultDebugLogger;\n    const emit: DebugEmitter<Names>['emit'] = (event, name) => {\n      if (!whitelist.has(event.type)) return;\n      if (onlySet) {\n        if (!name || !onlySet.has(name)) return;\n      }\n      logger(name ? { ...event, name } : event);\n    };\n    return { emit, mode: verbose ? 'complete' : 'minimal' };\n  }\n\n  return disabled;\n}\n\n// Split the variadic tuple at runtime\n/**\n * Extract the optional argument object from a variadic tuple.\n * @param args Tuple passed to a built endpoint helper.\n * @returns The argument object if present.\n */\nfunction extractArgs<L extends AnyLeaf>(args: ArgsTuple<L>): ArgsFor<L> | undefined {\n  // At runtime ArgsTuple<L> is either [] or [obj]; we just pick the first if present.\n  return (args as unknown as any[])[0] as any;\n}\n\n/**\n * Normalize params and query values, then construct a request URL for the given leaf.\n * @param leaf Leaf describing the endpoint.\n * @param baseUrl Optional base URL prepended to the path.\n * @param params Route parameters supplied by the caller.\n * @param query Query parameters supplied by the caller.\n * @returns Object containing the composed URL plus normalized params/query payloads.\n */\nfunction buildUrl<L extends AnyLeaf>(\n  leaf: L,\n  baseUrl: string,\n  params: InferParams<L> | undefined,\n  query: InferQuery<L> | undefined,\n) {\n  const normalizedParams = zParse<InferParams<L>>(params, leaf.cfg.paramsSchema);\n  const normalizedQuery = zParse<InferQuery<L>>(query, leaf.cfg.querySchema);\n  const path = compilePath<L['path']>(leaf.path, (normalizedParams ?? {}) as any);\n  const url = `${baseUrl ?? ''}${path}${toSearchString(normalizedQuery as any)}`;\n  return { url, normalizedQuery, normalizedParams };\n}\n\n// -------------------------------------------------------------------------------------\n// Client factory\n// -------------------------------------------------------------------------------------\n/**\n * Construct typed React Query helpers backed by a routes-v3 registry leaf.\n * @param opts Route client configuration (query client, fetcher overrides, etc).\n * @returns Object that can build endpoint hooks/mutations from leaves.\n */\nexport function createRouteClient<Names extends string = string>(\n  opts: RouteClientOptions<Names>,\n): RouteClient<Names> {\n  const queryClient = opts.queryClient;\n  const fetcher = opts.fetcher ?? defaultFetcher;\n  const baseUrl = opts.baseUrl;\n  const cursorParam = opts.cursorParam ?? 'cursor';\n  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;\n  const environment =\n    opts.environment ??\n    (typeof process !== 'undefined' && process.env ? process.env.NODE_ENV : undefined);\n  const { emit: emitDebug, mode: debugMode } = createDebugEmitter<Names>(opts.debug, environment);\n  const isVerboseDebug = debugMode === 'complete';\n  const decorateDebugEvent = <T extends RouteClientDebugEvent>(\n    event: T,\n    details?: Partial<RouteClientDebugEvent>,\n  ): RouteClientDebugEvent => {\n    if (!isVerboseDebug || !details) return event;\n    return { ...event, ...details } as RouteClientDebugEvent;\n  };\n\n  /**\n   * Invalidate a set of queries sharing the given prefix.\n   * @param prefix Key parts shared by matching endpoints.\n   * @param exact When true, invalidate only exact key matches.\n   */\n  async function invalidate(prefix: string[], exact = false) {\n    const queryKey = prefix as unknown as QueryKey;\n    await queryClient.invalidateQueries({ queryKey, exact });\n    emitDebug({ type: 'invalidate', key: queryKey, exact });\n  }\n\n  /**\n   * Build the client surface for a single leaf (query/mutation/infinite query).\n   * @param leaf Leaf describing the endpoint.\n   * @param rqOpts Optional React Query configuration.\n   * @returns Helper object exposing key/invalidate/setData/useEndpoint.\n   */\n  function buildInternal<L extends AnyLeaf>(\n    leaf: L,\n    rqOpts?: QueryBuildOptionsFor<L> | InfiniteBuildOptionsFor<L> | MutationBuildOptionsFor<L>,\n    meta?: BuildMeta<Names>,\n  ): BuiltForLeaf<L> {\n    const isGet = leaf.method === 'get';\n    const isFeed = !!leaf.cfg.feed;\n    const method = toUpper(leaf.method);\n    const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;\n    const debugName = meta?.name;\n    const emit = (event: RouteClientDebugEvent) => emitDebug(event, debugName);\n    emit({ type: 'build', leaf: leafLabel });\n\n    // --- key/invalidate/setData shared helpers ---\n    const key = (...tuple: ArgsTuple<L>): QueryKey => {\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n      const qForKey = isGet && isFeed ? stripKey(query as any, cursorParam) : (query as any);\n      return buildCacheKey({ leaf, params: params as any, query: qForKey }) as unknown as QueryKey;\n    };\n\n    /**\n     * Invalidate the React Query cache for this exact leaf invocation.\n     * @param tuple Optional params/query tuple.\n     */\n    const invalidateExact = async (...tuple: ArgsTuple<L>) => {\n      const queryKey = key(...tuple);\n      await queryClient.invalidateQueries({ queryKey, exact: true });\n      emit({ type: 'invalidate', key: queryKey, exact: true });\n    };\n\n    /**\n     * Update the cache entries for this leaf.\n     * @param args Tuple whose first entry is the updater and optional params/query follow.\n     */\n    const setData = (...args: [Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => {\n      const [updater, ...rest] = args;\n      const k = key(...(rest as ArgsTuple<L>));\n      if (isGet && isFeed) {\n        queryClient.setQueryData<InfiniteData<InferOutput<L>> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      } else {\n        queryClient.setQueryData<InferOutput<L> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      }\n      emit({ type: 'setData', key: k });\n    };\n\n    // --- Infinite GET ---\n    if (isGet && isFeed) {\n      const useEndpoint: BuiltInfinite<L>['useEndpoint'] = (...tuple) => {\n        emit({ type: 'useEndpoint', leaf: leafLabel, variant: 'infiniteGet' });\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        // Normalize once; we’ll inject the cursor per page below.\n        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n        return useInfiniteQuery<\n          InferOutput<L>, // TQueryFnData (per page)\n          unknown, // TError\n          InfiniteData<InferOutput<L>>, // TData (returned by the hook)\n          QueryKey,\n          Cursor\n        >({\n          ...(rqOpts as InfiniteBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          initialPageParam: undefined,\n          getNextPageParam: (lastPage) => getNextCursor(lastPage),\n          placeholderData: keepPreviousData,\n          queryFn: async ({ pageParam }) => {\n            const pageQuery = {\n              ...(normalizedQuery as any),\n              ...(pageParam ? { [cursorParam]: pageParam } : {}),\n            };\n            const { url } = buildUrl(leaf, baseUrl, params, pageQuery);\n            const startedAt = Date.now();\n            const detail = isVerboseDebug ? { params: normalizedParams, query: pageQuery } : undefined;\n            emit(\n              decorateDebugEvent(\n                { type: 'fetch', stage: 'start', method, url, leaf: leafLabel },\n                detail,\n              ),\n            );\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n              emit(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'success',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                  },\n                  isVerboseDebug ? { params: normalizedParams, query: pageQuery, output: parsed } : undefined,\n                ),\n              );\n              return parsed;\n            } catch (error) {\n              emit(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'error',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                    error,\n                  },\n                  detail,\n                ),\n              );\n              throw error;\n            }\n          },\n          // NOTE: TData is InfiniteData<T>, so we don't need a select here.\n        }, queryClient);\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n    // --- Plain GET ---\n    if (isGet) {\n      const useEndpoint: BuiltQuery<L>['useEndpoint'] = (...tuple) => {\n        emit({ type: 'useEndpoint', leaf: leafLabel, variant: 'get' });\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n        return useQuery<InferOutput<L>, unknown, InferOutput<L>, QueryKey>({\n          ...(rqOpts as QueryBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          placeholderData: keepPreviousData,\n          queryFn: async () => {\n            const startedAt = Date.now();\n            const detail = isVerboseDebug\n              ? { params: normalizedParams, query: normalizedQuery }\n              : undefined;\n            emit(\n              decorateDebugEvent(\n                { type: 'fetch', stage: 'start', method, url, leaf: leafLabel },\n                detail,\n              ),\n            );\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n              emit(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'success',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                  },\n                  isVerboseDebug\n                    ? { params: normalizedParams, query: normalizedQuery, output: parsed }\n                    : undefined,\n                ),\n              );\n              return parsed;\n            } catch (error) {\n              emit(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'error',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                    error,\n                  },\n                  detail,\n                ),\n              );\n              throw error;\n            }\n          },\n        }, queryClient);\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n\n    // --- Mutation (POST/PUT/PATCH/DELETE) ---\n    const fetchEndpoint: BuiltMutation<L>['fetch'] = async (\n      ...tupleWithBody: [...ArgsTuple<L>, InferBody<L>]\n    ) => {\n      if (tupleWithBody.length === 0) {\n        throw new Error('Body is required when invoking a mutation fetch.');\n      }\n      const bodyIndex = tupleWithBody.length - 1;\n      const tuple = tupleWithBody.slice(0, bodyIndex) as ArgsTuple<L>;\n      const body = tupleWithBody[bodyIndex] as InferBody<L>;\n      const args = extractArgs<L>(tuple);\n      const params = (args as any)?.params as InferParams<L> | undefined;\n      const query = (args as any)?.query as InferQuery<L> | undefined;\n\n      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n      const normalizedBody = zParse<InferBody<L>>(body, leaf.cfg.bodySchema);\n\n      // Optional: switch to FormData if your method declares bodyFiles\n      const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;\n      const payload = isMultipart ? toFormData(normalizedBody as any) : normalizedBody;\n\n      const startedAt = Date.now();\n      const detail = isVerboseDebug\n        ? { params: normalizedParams, query: normalizedQuery }\n        : undefined;\n      emit(\n        decorateDebugEvent(\n          {\n            type: 'fetch',\n            stage: 'start',\n            method,\n            url,\n            leaf: leafLabel,\n            body: payload,\n          },\n          detail,\n        ),\n      );\n      try {\n        const out = await fetcher<unknown>({ url, method, body: payload });\n        const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n        emit(\n          decorateDebugEvent(\n            {\n              type: 'fetch',\n              stage: 'success',\n              method,\n              url,\n              leaf: leafLabel,\n              durationMs: Date.now() - startedAt,\n            },\n            isVerboseDebug\n              ? { params: normalizedParams, query: normalizedQuery, output: parsed }\n              : undefined,\n          ),\n        );\n        return parsed;\n      } catch (error) {\n        emit(\n          decorateDebugEvent(\n            {\n              type: 'fetch',\n              stage: 'error',\n              method,\n              url,\n              leaf: leafLabel,\n              durationMs: Date.now() - startedAt,\n              body: payload,\n              error,\n            },\n            detail,\n          ),\n        );\n        throw error;\n      }\n    };\n\n    const useEndpoint: BuiltMutation<L>['useEndpoint'] = (...tuple) => {\n      emit({ type: 'useEndpoint', leaf: leafLabel, variant: 'mutation' });\n      return useMutation<InferOutput<L>, unknown, InferBody<L>, unknown>({\n        ...(rqOpts as MutationBuildOptionsFor<L>),\n        mutationKey: key(...tuple),\n        mutationFn: (body: InferBody<L>) =>\n          fetchEndpoint(...([...tuple, body] as [...ArgsTuple<L>, InferBody<L>])),\n      }, queryClient);\n    };\n\n    return {\n      key,\n      invalidate: invalidateExact,\n      setData: setData as any,\n      useEndpoint,\n      fetch: fetchEndpoint,\n    } as BuiltForLeaf<L>;\n  }\n\n  return {\n    queryClient,\n    invalidate,\n    build: buildInternal as RouteClient<Names>['build'],\n  };\n}\n\n// -------------------------------------------------------------------------------------\n// Multipart helper\n// -------------------------------------------------------------------------------------\nfunction toFormData(body: Record<string, any>): FormData {\n  const fd = new FormData();\n  for (const [k, v] of Object.entries(body ?? {})) {\n    if (v == null) continue;\n    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item as any));\n    else fd.append(k, v as any);\n  }\n  return fd;\n}\n"],"mappings":"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","names":["useEndpoint"]}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './routesV3.client.types';
+export * from './routesV3.client.fetch';
+export * from './routesV3.client.index';

package/dist/index.mjs

@@ -0,0 +1,435 @@
+"use client";
+
+// src/routesV3.client.fetch.ts
+var defaultFetcher = async (req) => {
+  const headers = { ...req.headers ?? {} };
+  const isFormData = typeof FormData !== "undefined" && req.body instanceof FormData;
+  if (!isFormData) {
+    headers["Content-Type"] || (headers["Content-Type"] = "application/json");
+    headers["Accept"] || (headers["Accept"] = "application/json");
+  }
+  const res = await fetch(req.url, {
+    method: req.method,
+    headers,
+    body: isFormData ? req.body : req.body == null ? void 0 : JSON.stringify(req.body)
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    const snippet = text.slice(0, 400);
+    throw new Error(`[${res.status}] ${res.statusText} \u2014 ${snippet}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+// src/routesV3.client.index.ts
+import {
+  keepPreviousData,
+  useInfiniteQuery,
+  useMutation,
+  useQuery
+} from "@tanstack/react-query";
+import {
+  buildCacheKey,
+  compilePath
+} from "@emeryld/rrroutes-contract";
+var toUpper = (m) => m.toUpperCase();
+function zParse(value, schema) {
+  return schema ? schema.parse(value) : value;
+}
+function toSearchString(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v == null) continue;
+    if (Array.isArray(v)) {
+      v.forEach((x) => {
+        if (x == null) return;
+        if (typeof x === "object") {
+          params.append(k, JSON.stringify(x));
+        } else {
+          params.append(k, String(x));
+        }
+      });
+      continue;
+    }
+    if (typeof v === "object") {
+      params.set(k, JSON.stringify(v));
+      continue;
+    }
+    params.set(k, String(v));
+  }
+  const s = params.toString();
+  return s ? `?${s}` : "";
+}
+function stripKey(obj, key) {
+  if (!obj) return obj;
+  const { [key]: _omit, ...rest } = obj;
+  return rest;
+}
+var defaultGetNextCursor = (p) => p && typeof p === "object" && "nextCursor" in p ? p.nextCursor : void 0;
+var defaultDebugLogger = (event) => {
+  if (typeof console === "undefined") return;
+  const fn = console.debug ?? console.log;
+  fn?.call(console, "[rrroutes-client]", event);
+};
+var debugEventTypes = [
+  "fetch",
+  "invalidate",
+  "setData",
+  "build",
+  "useEndpoint"
+];
+var noopEmit = () => {
+};
+function createDebugEmitter(option, environment) {
+  const disabled = { emit: noopEmit, mode: "minimal" };
+  if (environment && environment.toLowerCase() === "production") {
+    return disabled;
+  }
+  if (!option) {
+    return disabled;
+  }
+  if (option === true || option === "minimal") {
+    return {
+      emit: (event, name) => defaultDebugLogger(name ? { ...event, name } : event),
+      mode: "minimal"
+    };
+  }
+  if (option === "complete") {
+    return {
+      emit: (event, name) => defaultDebugLogger(name ? { ...event, name } : event),
+      mode: "complete"
+    };
+  }
+  if (typeof option === "function") {
+    return {
+      emit: (event, name) => option(name ? { ...event, name } : event),
+      mode: "minimal"
+    };
+  }
+  if (typeof option === "object") {
+    const toggles = option;
+    const verbose = Boolean(toggles.verbose);
+    const enabledTypes = debugEventTypes.filter((type) => toggles[type]);
+    if (enabledTypes.length === 0) {
+      return { emit: noopEmit, mode: verbose ? "complete" : "minimal" };
+    }
+    const whitelist = new Set(enabledTypes);
+    const onlySet = toggles.only && toggles.only.length > 0 ? new Set(toggles.only) : void 0;
+    const logger = toggles.logger ?? defaultDebugLogger;
+    const emit = (event, name) => {
+      if (!whitelist.has(event.type)) return;
+      if (onlySet) {
+        if (!name || !onlySet.has(name)) return;
+      }
+      logger(name ? { ...event, name } : event);
+    };
+    return { emit, mode: verbose ? "complete" : "minimal" };
+  }
+  return disabled;
+}
+function extractArgs(args) {
+  return args[0];
+}
+function buildUrl(leaf, baseUrl, params, query) {
+  const normalizedParams = zParse(params, leaf.cfg.paramsSchema);
+  const normalizedQuery = zParse(query, leaf.cfg.querySchema);
+  const path = compilePath(leaf.path, normalizedParams ?? {});
+  const url = `${baseUrl ?? ""}${path}${toSearchString(normalizedQuery)}`;
+  return { url, normalizedQuery, normalizedParams };
+}
+function createRouteClient(opts) {
+  const queryClient = opts.queryClient;
+  const fetcher = opts.fetcher ?? defaultFetcher;
+  const baseUrl = opts.baseUrl;
+  const cursorParam = opts.cursorParam ?? "cursor";
+  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;
+  const environment = opts.environment ?? (typeof process !== "undefined" && process.env ? process.env.NODE_ENV : void 0);
+  const { emit: emitDebug, mode: debugMode } = createDebugEmitter(opts.debug, environment);
+  const isVerboseDebug = debugMode === "complete";
+  const decorateDebugEvent = (event, details) => {
+    if (!isVerboseDebug || !details) return event;
+    return { ...event, ...details };
+  };
+  async function invalidate(prefix, exact = false) {
+    const queryKey = prefix;
+    await queryClient.invalidateQueries({ queryKey, exact });
+    emitDebug({ type: "invalidate", key: queryKey, exact });
+  }
+  function buildInternal(leaf, rqOpts, meta) {
+    const isGet = leaf.method === "get";
+    const isFeed = !!leaf.cfg.feed;
+    const method = toUpper(leaf.method);
+    const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;
+    const debugName = meta?.name;
+    const emit = (event) => emitDebug(event, debugName);
+    emit({ type: "build", leaf: leafLabel });
+    const key = (...tuple) => {
+      const a = extractArgs(tuple);
+      const params = a?.params;
+      const query = a?.query;
+      const qForKey = isGet && isFeed ? stripKey(query, cursorParam) : query;
+      return buildCacheKey({ leaf, params, query: qForKey });
+    };
+    const invalidateExact = async (...tuple) => {
+      const queryKey = key(...tuple);
+      await queryClient.invalidateQueries({ queryKey, exact: true });
+      emit({ type: "invalidate", key: queryKey, exact: true });
+    };
+    const setData = (...args) => {
+      const [updater, ...rest] = args;
+      const k = key(...rest);
+      if (isGet && isFeed) {
+        queryClient.setQueryData(
+          k,
+          (prev) => typeof updater === "function" ? updater(prev) : updater
+        );
+      } else {
+        queryClient.setQueryData(
+          k,
+          (prev) => typeof updater === "function" ? updater(prev) : updater
+        );
+      }
+      emit({ type: "setData", key: k });
+    };
+    if (isGet && isFeed) {
+      const useEndpoint2 = (...tuple) => {
+        emit({ type: "useEndpoint", leaf: leafLabel, variant: "infiniteGet" });
+        const a = extractArgs(tuple);
+        const params = a?.params;
+        const query = a?.query;
+        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
+        return useInfiniteQuery({
+          ...rqOpts,
+          queryKey: key(...tuple),
+          initialPageParam: void 0,
+          getNextPageParam: (lastPage) => getNextCursor(lastPage),
+          placeholderData: keepPreviousData,
+          queryFn: async ({ pageParam }) => {
+            const pageQuery = {
+              ...normalizedQuery,
+              ...pageParam ? { [cursorParam]: pageParam } : {}
+            };
+            const { url } = buildUrl(leaf, baseUrl, params, pageQuery);
+            const startedAt = Date.now();
+            const detail = isVerboseDebug ? { params: normalizedParams, query: pageQuery } : void 0;
+            emit(
+              decorateDebugEvent(
+                { type: "fetch", stage: "start", method, url, leaf: leafLabel },
+                detail
+              )
+            );
+            try {
+              const out = await fetcher({ url, method });
+              const parsed = zParse(out, leaf.cfg.outputSchema);
+              emit(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "success",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt
+                  },
+                  isVerboseDebug ? { params: normalizedParams, query: pageQuery, output: parsed } : void 0
+                )
+              );
+              return parsed;
+            } catch (error) {
+              emit(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "error",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt,
+                    error
+                  },
+                  detail
+                )
+              );
+              throw error;
+            }
+          }
+          // NOTE: TData is InfiniteData<T>, so we don't need a select here.
+        }, queryClient);
+      };
+      return {
+        key,
+        invalidate: invalidateExact,
+        setData,
+        useEndpoint: useEndpoint2
+      };
+    }
+    if (isGet) {
+      const useEndpoint2 = (...tuple) => {
+        emit({ type: "useEndpoint", leaf: leafLabel, variant: "get" });
+        const a = extractArgs(tuple);
+        const params = a?.params;
+        const query = a?.query;
+        const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
+        return useQuery({
+          ...rqOpts,
+          queryKey: key(...tuple),
+          placeholderData: keepPreviousData,
+          queryFn: async () => {
+            const startedAt = Date.now();
+            const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+            emit(
+              decorateDebugEvent(
+                { type: "fetch", stage: "start", method, url, leaf: leafLabel },
+                detail
+              )
+            );
+            try {
+              const out = await fetcher({ url, method });
+              const parsed = zParse(out, leaf.cfg.outputSchema);
+              emit(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "success",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt
+                  },
+                  isVerboseDebug ? { params: normalizedParams, query: normalizedQuery, output: parsed } : void 0
+                )
+              );
+              return parsed;
+            } catch (error) {
+              emit(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "error",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt,
+                    error
+                  },
+                  detail
+                )
+              );
+              throw error;
+            }
+          }
+        }, queryClient);
+      };
+      return {
+        key,
+        invalidate: invalidateExact,
+        setData,
+        useEndpoint: useEndpoint2
+      };
+    }
+    const fetchEndpoint = async (...tupleWithBody) => {
+      if (tupleWithBody.length === 0) {
+        throw new Error("Body is required when invoking a mutation fetch.");
+      }
+      const bodyIndex = tupleWithBody.length - 1;
+      const tuple = tupleWithBody.slice(0, bodyIndex);
+      const body = tupleWithBody[bodyIndex];
+      const args = extractArgs(tuple);
+      const params = args?.params;
+      const query = args?.query;
+      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
+      const normalizedBody = zParse(body, leaf.cfg.bodySchema);
+      const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;
+      const payload = isMultipart ? toFormData(normalizedBody) : normalizedBody;
+      const startedAt = Date.now();
+      const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+      emit(
+        decorateDebugEvent(
+          {
+            type: "fetch",
+            stage: "start",
+            method,
+            url,
+            leaf: leafLabel,
+            body: payload
+          },
+          detail
+        )
+      );
+      try {
+        const out = await fetcher({ url, method, body: payload });
+        const parsed = zParse(out, leaf.cfg.outputSchema);
+        emit(
+          decorateDebugEvent(
+            {
+              type: "fetch",
+              stage: "success",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt
+            },
+            isVerboseDebug ? { params: normalizedParams, query: normalizedQuery, output: parsed } : void 0
+          )
+        );
+        return parsed;
+      } catch (error) {
+        emit(
+          decorateDebugEvent(
+            {
+              type: "fetch",
+              stage: "error",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt,
+              body: payload,
+              error
+            },
+            detail
+          )
+        );
+        throw error;
+      }
+    };
+    const useEndpoint = (...tuple) => {
+      emit({ type: "useEndpoint", leaf: leafLabel, variant: "mutation" });
+      return useMutation({
+        ...rqOpts,
+        mutationKey: key(...tuple),
+        mutationFn: (body) => fetchEndpoint(...[...tuple, body])
+      }, queryClient);
+    };
+    return {
+      key,
+      invalidate: invalidateExact,
+      setData,
+      useEndpoint,
+      fetch: fetchEndpoint
+    };
+  }
+  return {
+    queryClient,
+    invalidate,
+    build: buildInternal
+  };
+}
+function toFormData(body) {
+  const fd = new FormData();
+  for (const [k, v] of Object.entries(body ?? {})) {
+    if (v == null) continue;
+    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item));
+    else fd.append(k, v);
+  }
+  return fd;
+}
+export {
+  createRouteClient,
+  defaultFetcher
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/routesV3.client.fetch.ts","../src/routesV3.client.index.ts"],"sourcesContent":["// routesV3.client.fetch.ts\n\nimport { Fetcher, FetchInput } from './routesV3.client.types';\n\n/**\n * Default fetch implementation used by the route client helper.\n * @param req Normalized request information (URL, method, body, headers).\n * @returns Parsed JSON (or text fallback) from the server response.\n */\nexport const defaultFetcher: Fetcher = async <T>(req: FetchInput): Promise<T> => {\n  const headers: Record<string, string> = { ...(req.headers ?? {}) };\n  const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;\n  if (!isFormData) {\n    headers['Content-Type'] ||= 'application/json';\n    headers['Accept'] ||= 'application/json';\n  }\n\n  const res = await fetch(req.url, {\n    method: req.method,\n    headers,\n    body: isFormData ? (req.body as any) : req.body == null ? undefined : JSON.stringify(req.body),\n  });\n\n  const text = await res.text();\n  if (!res.ok) {\n    const snippet = text.slice(0, 400);\n    throw new Error(`[${res.status}] ${res.statusText} — ${snippet}`);\n  }\n\n  try {\n    return JSON.parse(text) as T;\n  } catch {\n    return text as unknown as T;\n  }\n};\n","// routesV3.client.ts\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  type InfiniteData,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport type { ZodType } from 'zod';\nimport {\n  HttpMethod,\n  buildCacheKey,\n  compilePath,\n} from '@emeryld/rrroutes-contract';\nimport type {\n  AnyLeaf,\n  InferBody,\n  InferOutput,\n  InferParams,\n  InferQuery,\n} from '@emeryld/rrroutes-contract';\nimport { defaultFetcher } from './routesV3.client.fetch';\nimport type {\n  ArgsFor,\n  ArgsTuple,\n  BuildMeta,\n  BuiltForLeaf,\n  BuiltInfinite,\n  BuiltMutation,\n  BuiltQuery,\n  Cursor,\n  DataShape,\n  InfiniteBuildOptionsFor,\n  MutationBuildOptionsFor,\n  QueryBuildOptionsFor,\n  RouteClient,\n  RouteClientOptions,\n  RouteClientDebugEvent,\n  RouteClientDebugLogger,\n  RouteClientDebugMode,\n  RouteClientDebugOptions,\n  RouteClientDebugToggleOptions,\n  Updater,\n} from './routesV3.client.types';\n\n// -------------------------------------------------------------------------------------\n// Tiny helpers\n// -------------------------------------------------------------------------------------\n/**\n * Convert an HTTP method to uppercase (as expected by fetch).\n * @param m Lowercase HTTP method.\n * @returns Uppercase method string.\n */\nconst toUpper = (m: HttpMethod): Uppercase<HttpMethod> => m.toUpperCase() as Uppercase<HttpMethod>;\n\n/**\n * Parse the given value with the supplied schema (if present).\n * @param value Raw value to validate.\n * @param schema Optional Zod schema used for validation/coercion.\n * @returns The validated or original value.\n */\nfunction zParse<T>(value: unknown, schema?: ZodType): T {\n  return schema ? (schema.parse(value) as T) : (value as T);\n}\n\n/**\n * Serialize a query object into a search string.\n * @param query Query params object (possibly undefined).\n * @returns Query string prefixed with `?`, or empty string.\n */\nfunction toSearchString(query: Record<string, unknown> | undefined) {\n  if (!query) return '';\n  const params = new URLSearchParams();\n  for (const [k, v] of Object.entries(query)) {\n    if (v == null) continue;\n    if (Array.isArray(v)) {\n      v.forEach((x) => {\n        if (x == null) return;\n        if (typeof x === 'object') {\n          params.append(k, JSON.stringify(x));\n        } else {\n          params.append(k, String(x));\n        }\n      });\n      continue;\n    }\n    if (typeof v === 'object') {\n      params.set(k, JSON.stringify(v));\n      continue;\n    }\n    params.set(k, String(v));\n  }\n  const s = params.toString();\n  return s ? `?${s}` : '';\n}\n\n/**\n * Remove the given key from an object (used to drop cursors from cache keys).\n * @param obj Source object.\n * @param key Property name to omit.\n * @returns Copy of the object without the specified key.\n */\nfunction stripKey<Q extends Record<string, unknown> | undefined>(obj: Q, key: string): Q {\n  if (!obj) return obj;\n  const { [key]: _omit, ...rest } = obj as any;\n  return rest as Q;\n}\n\n/**\n * Default cursor extractor used by infinite queries.\n * @param p Page result returned from the server.\n * @returns Next cursor string, if present.\n */\nconst defaultGetNextCursor = (p: unknown): Cursor =>\n  p && typeof p === 'object' && 'nextCursor' in p ? (p as any).nextCursor : undefined;\n\n// Debug logging --------------------------------------------------------------\nconst noopDebugLogger: RouteClientDebugLogger = () => {};\n\nconst defaultDebugLogger: RouteClientDebugLogger = (event: RouteClientDebugEvent) => {\n  if (typeof console === 'undefined') return;\n  const fn = console.debug ?? console.log;\n  fn?.call(console, '[rrroutes-client]', event);\n};\n\nconst debugEventTypes: RouteClientDebugEvent['type'][] = [\n  'fetch',\n  'invalidate',\n  'setData',\n  'build',\n  'useEndpoint',\n];\n\ntype DebugEmitter<Names extends string> = {\n  emit: (event: RouteClientDebugEvent, name?: Names) => void;\n  mode: RouteClientDebugMode;\n};\n\nconst noopEmit = () => {};\n\nfunction createDebugEmitter<Names extends string>(\n  option?: RouteClientDebugOptions<Names>,\n  environment?: string,\n): DebugEmitter<Names> {\n  const disabled: DebugEmitter<Names> = { emit: noopEmit, mode: 'minimal' };\n\n  if (environment && environment.toLowerCase() === 'production') {\n    return disabled;\n  }\n\n  if (!option) {\n    return disabled;\n  }\n  if (option === true || option === 'minimal') {\n    return {\n      emit: (event, name) => defaultDebugLogger(name ? { ...event, name } : event),\n      mode: 'minimal',\n    };\n  }\n  if (option === 'complete') {\n    return {\n      emit: (event, name) => defaultDebugLogger(name ? { ...event, name } : event),\n      mode: 'complete',\n    };\n  }\n  if (typeof option === 'function') {\n    return {\n      emit: (event, name) => option(name ? { ...event, name } : event),\n      mode: 'minimal',\n    };\n  }\n  if (typeof option === 'object') {\n    const toggles = option as RouteClientDebugToggleOptions<Names>;\n    const verbose = Boolean(toggles.verbose);\n    const enabledTypes = debugEventTypes.filter((type) => toggles[type]);\n    if (enabledTypes.length === 0) {\n      return { emit: noopEmit, mode: verbose ? 'complete' : 'minimal' };\n    }\n    const whitelist = new Set<RouteClientDebugEvent['type']>(enabledTypes);\n    const onlySet =\n      toggles.only && toggles.only.length > 0 ? new Set<Names>(toggles.only) : undefined;\n    const logger = toggles.logger ?? defaultDebugLogger;\n    const emit: DebugEmitter<Names>['emit'] = (event, name) => {\n      if (!whitelist.has(event.type)) return;\n      if (onlySet) {\n        if (!name || !onlySet.has(name)) return;\n      }\n      logger(name ? { ...event, name } : event);\n    };\n    return { emit, mode: verbose ? 'complete' : 'minimal' };\n  }\n\n  return disabled;\n}\n\n// Split the variadic tuple at runtime\n/**\n * Extract the optional argument object from a variadic tuple.\n * @param args Tuple passed to a built endpoint helper.\n * @returns The argument object if present.\n */\nfunction extractArgs<L extends AnyLeaf>(args: ArgsTuple<L>): ArgsFor<L> | undefined {\n  // At runtime ArgsTuple<L> is either [] or [obj]; we just pick the first if present.\n  return (args as unknown as any[])[0] as any;\n}\n\n/**\n * Normalize params and query values, then construct a request URL for the given leaf.\n * @param leaf Leaf describing the endpoint.\n * @param baseUrl Optional base URL prepended to the path.\n * @param params Route parameters supplied by the caller.\n * @param query Query parameters supplied by the caller.\n * @returns Object containing the composed URL plus normalized params/query payloads.\n */\nfunction buildUrl<L extends AnyLeaf>(\n  leaf: L,\n  baseUrl: string,\n  params: InferParams<L> | undefined,\n  query: InferQuery<L> | undefined,\n) {\n  const normalizedParams = zParse<InferParams<L>>(params, leaf.cfg.paramsSchema);\n  const normalizedQuery = zParse<InferQuery<L>>(query, leaf.cfg.querySchema);\n  const path = compilePath<L['path']>(leaf.path, (normalizedParams ?? {}) as any);\n  const url = `${baseUrl ?? ''}${path}${toSearchString(normalizedQuery as any)}`;\n  return { url, normalizedQuery, normalizedParams };\n}\n\n// -------------------------------------------------------------------------------------\n// Client factory\n// -------------------------------------------------------------------------------------\n/**\n * Construct typed React Query helpers backed by a routes-v3 registry leaf.\n * @param opts Route client configuration (query client, fetcher overrides, etc).\n * @returns Object that can build endpoint hooks/mutations from leaves.\n */\nexport function createRouteClient<Names extends string = string>(\n  opts: RouteClientOptions<Names>,\n): RouteClient<Names> {\n  const queryClient = opts.queryClient;\n  const fetcher = opts.fetcher ?? defaultFetcher;\n  const baseUrl = opts.baseUrl;\n  const cursorParam = opts.cursorParam ?? 'cursor';\n  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;\n  const environment =\n    opts.environment ??\n    (typeof process !== 'undefined' && process.env ? process.env.NODE_ENV : undefined);\n  const { emit: emitDebug, mode: debugMode } = createDebugEmitter<Names>(opts.debug, environment);\n  const isVerboseDebug = debugMode === 'complete';\n  const decorateDebugEvent = <T extends RouteClientDebugEvent>(\n    event: T,\n    details?: Partial<RouteClientDebugEvent>,\n  ): RouteClientDebugEvent => {\n    if (!isVerboseDebug || !details) return event;\n    return { ...event, ...details } as RouteClientDebugEvent;\n  };\n\n  /**\n   * Invalidate a set of queries sharing the given prefix.\n   * @param prefix Key parts shared by matching endpoints.\n   * @param exact When true, invalidate only exact key matches.\n   */\n  async function invalidate(prefix: string[], exact = false) {\n    const queryKey = prefix as unknown as QueryKey;\n    await queryClient.invalidateQueries({ queryKey, exact });\n    emitDebug({ type: 'invalidate', key: queryKey, exact });\n  }\n\n  /**\n   * Build the client surface for a single leaf (query/mutation/infinite query).\n   * @param leaf Leaf describing the endpoint.\n   * @param rqOpts Optional React Query configuration.\n   * @returns Helper object exposing key/invalidate/setData/useEndpoint.\n   */\n  function buildInternal<L extends AnyLeaf>(\n    leaf: L,\n    rqOpts?: QueryBuildOptionsFor<L> | InfiniteBuildOptionsFor<L> | MutationBuildOptionsFor<L>,\n    meta?: BuildMeta<Names>,\n  ): BuiltForLeaf<L> {\n    const isGet = leaf.method === 'get';\n    const isFeed = !!leaf.cfg.feed;\n    const method = toUpper(leaf.method);\n    const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;\n    const debugName = meta?.name;\n    const emit = (event: RouteClientDebugEvent) => emitDebug(event, debugName);\n    emit({ type: 'build', leaf: leafLabel });\n\n    // --- key/invalidate/setData shared helpers ---\n    const key = (...tuple: ArgsTuple<L>): QueryKey => {\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n      const qForKey = isGet && isFeed ? stripKey(query as any, cursorParam) : (query as any);\n      return buildCacheKey({ leaf, params: params as any, query: qForKey }) as unknown as QueryKey;\n    };\n\n    /**\n     * Invalidate the React Query cache for this exact leaf invocation.\n     * @param tuple Optional params/query tuple.\n     */\n    const invalidateExact = async (...tuple: ArgsTuple<L>) => {\n      const queryKey = key(...tuple);\n      await queryClient.invalidateQueries({ queryKey, exact: true });\n      emit({ type: 'invalidate', key: queryKey, exact: true });\n    };\n\n    /**\n     * Update the cache entries for this leaf.\n     * @param args Tuple whose first entry is the updater and optional params/query follow.\n     */\n    const setData = (...args: [Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => {\n      const [updater, ...rest] = args;\n      const k = key(...(rest as ArgsTuple<L>));\n      if (isGet && isFeed) {\n        queryClient.setQueryData<InfiniteData<InferOutput<L>> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      } else {\n        queryClient.setQueryData<InferOutput<L> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      }\n      emit({ type: 'setData', key: k });\n    };\n\n    // --- Infinite GET ---\n    if (isGet && isFeed) {\n      const useEndpoint: BuiltInfinite<L>['useEndpoint'] = (...tuple) => {\n        emit({ type: 'useEndpoint', leaf: leafLabel, variant: 'infiniteGet' });\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        // Normalize once; we’ll inject the cursor per page below.\n        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n        return useInfiniteQuery<\n          InferOutput<L>, // TQueryFnData (per page)\n          unknown, // TError\n          InfiniteData<InferOutput<L>>, // TData (returned by the hook)\n          QueryKey,\n          Cursor\n        >({\n          ...(rqOpts as InfiniteBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          initialPageParam: undefined,\n          getNextPageParam: (lastPage) => getNextCursor(lastPage),\n          placeholderData: keepPreviousData,\n          queryFn: async ({ pageParam }) => {\n            const pageQuery = {\n              ...(normalizedQuery as any),\n              ...(pageParam ? { [cursorParam]: pageParam } : {}),\n            };\n            const { url } = buildUrl(leaf, baseUrl, params, pageQuery);\n            const startedAt = Date.now();\n            const detail = isVerboseDebug ? { params: normalizedParams, query: pageQuery } : undefined;\n            emit(\n              decorateDebugEvent(\n                { type: 'fetch', stage: 'start', method, url, leaf: leafLabel },\n                detail,\n              ),\n            );\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n              emit(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'success',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                  },\n                  isVerboseDebug ? { params: normalizedParams, query: pageQuery, output: parsed } : undefined,\n                ),\n              );\n              return parsed;\n            } catch (error) {\n              emit(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'error',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                    error,\n                  },\n                  detail,\n                ),\n              );\n              throw error;\n            }\n          },\n          // NOTE: TData is InfiniteData<T>, so we don't need a select here.\n        }, queryClient);\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n    // --- Plain GET ---\n    if (isGet) {\n      const useEndpoint: BuiltQuery<L>['useEndpoint'] = (...tuple) => {\n        emit({ type: 'useEndpoint', leaf: leafLabel, variant: 'get' });\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n        return useQuery<InferOutput<L>, unknown, InferOutput<L>, QueryKey>({\n          ...(rqOpts as QueryBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          placeholderData: keepPreviousData,\n          queryFn: async () => {\n            const startedAt = Date.now();\n            const detail = isVerboseDebug\n              ? { params: normalizedParams, query: normalizedQuery }\n              : undefined;\n            emit(\n              decorateDebugEvent(\n                { type: 'fetch', stage: 'start', method, url, leaf: leafLabel },\n                detail,\n              ),\n            );\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n              emit(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'success',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                  },\n                  isVerboseDebug\n                    ? { params: normalizedParams, query: normalizedQuery, output: parsed }\n                    : undefined,\n                ),\n              );\n              return parsed;\n            } catch (error) {\n              emit(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'error',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                    error,\n                  },\n                  detail,\n                ),\n              );\n              throw error;\n            }\n          },\n        }, queryClient);\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n\n    // --- Mutation (POST/PUT/PATCH/DELETE) ---\n    const fetchEndpoint: BuiltMutation<L>['fetch'] = async (\n      ...tupleWithBody: [...ArgsTuple<L>, InferBody<L>]\n    ) => {\n      if (tupleWithBody.length === 0) {\n        throw new Error('Body is required when invoking a mutation fetch.');\n      }\n      const bodyIndex = tupleWithBody.length - 1;\n      const tuple = tupleWithBody.slice(0, bodyIndex) as ArgsTuple<L>;\n      const body = tupleWithBody[bodyIndex] as InferBody<L>;\n      const args = extractArgs<L>(tuple);\n      const params = (args as any)?.params as InferParams<L> | undefined;\n      const query = (args as any)?.query as InferQuery<L> | undefined;\n\n      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n      const normalizedBody = zParse<InferBody<L>>(body, leaf.cfg.bodySchema);\n\n      // Optional: switch to FormData if your method declares bodyFiles\n      const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;\n      const payload = isMultipart ? toFormData(normalizedBody as any) : normalizedBody;\n\n      const startedAt = Date.now();\n      const detail = isVerboseDebug\n        ? { params: normalizedParams, query: normalizedQuery }\n        : undefined;\n      emit(\n        decorateDebugEvent(\n          {\n            type: 'fetch',\n            stage: 'start',\n            method,\n            url,\n            leaf: leafLabel,\n            body: payload,\n          },\n          detail,\n        ),\n      );\n      try {\n        const out = await fetcher<unknown>({ url, method, body: payload });\n        const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n        emit(\n          decorateDebugEvent(\n            {\n              type: 'fetch',\n              stage: 'success',\n              method,\n              url,\n              leaf: leafLabel,\n              durationMs: Date.now() - startedAt,\n            },\n            isVerboseDebug\n              ? { params: normalizedParams, query: normalizedQuery, output: parsed }\n              : undefined,\n          ),\n        );\n        return parsed;\n      } catch (error) {\n        emit(\n          decorateDebugEvent(\n            {\n              type: 'fetch',\n              stage: 'error',\n              method,\n              url,\n              leaf: leafLabel,\n              durationMs: Date.now() - startedAt,\n              body: payload,\n              error,\n            },\n            detail,\n          ),\n        );\n        throw error;\n      }\n    };\n\n    const useEndpoint: BuiltMutation<L>['useEndpoint'] = (...tuple) => {\n      emit({ type: 'useEndpoint', leaf: leafLabel, variant: 'mutation' });\n      return useMutation<InferOutput<L>, unknown, InferBody<L>, unknown>({\n        ...(rqOpts as MutationBuildOptionsFor<L>),\n        mutationKey: key(...tuple),\n        mutationFn: (body: InferBody<L>) =>\n          fetchEndpoint(...([...tuple, body] as [...ArgsTuple<L>, InferBody<L>])),\n      }, queryClient);\n    };\n\n    return {\n      key,\n      invalidate: invalidateExact,\n      setData: setData as any,\n      useEndpoint,\n      fetch: fetchEndpoint,\n    } as BuiltForLeaf<L>;\n  }\n\n  return {\n    queryClient,\n    invalidate,\n    build: buildInternal as RouteClient<Names>['build'],\n  };\n}\n\n// -------------------------------------------------------------------------------------\n// Multipart helper\n// -------------------------------------------------------------------------------------\nfunction toFormData(body: Record<string, any>): FormData {\n  const fd = new FormData();\n  for (const [k, v] of Object.entries(body ?? {})) {\n    if (v == null) continue;\n    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item as any));\n    else fd.append(k, v as any);\n  }\n  return fd;\n}\n"],"mappings":"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","names":["useEndpoint"]}

package/dist/routesV3.client.fetch.d.ts

@@ -0,0 +1,7 @@
+import { Fetcher } from './routesV3.client.types';
+/**
+ * Default fetch implementation used by the route client helper.
+ * @param req Normalized request information (URL, method, body, headers).
+ * @returns Parsed JSON (or text fallback) from the server response.
+ */
+export declare const defaultFetcher: Fetcher;

package/dist/routesV3.client.index.d.ts

@@ -0,0 +1,7 @@
+import type { RouteClient, RouteClientOptions } from './routesV3.client.types';
+/**
+ * Construct typed React Query helpers backed by a routes-v3 registry leaf.
+ * @param opts Route client configuration (query client, fetcher overrides, etc).
+ * @returns Object that can build endpoint hooks/mutations from leaves.
+ */
+export declare function createRouteClient<Names extends string = string>(opts: RouteClientOptions<Names>): RouteClient<Names>;

package/dist/routesV3.client.types.d.ts

@@ -0,0 +1,218 @@
+import type { InfiniteData, QueryClient, QueryKey, UseInfiniteQueryOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import type { AnyLeaf, HttpMethod, InferBody, InferOutput, InferParams, InferQuery } from '@emeryld/rrroutes-contract';
+/** Helper type used when setting React Query cache data. */
+export type Updater<T> = T | ((prev: T | undefined) => T);
+/** Cursor string extracted from paginated endpoints. */
+export type Cursor = string | undefined;
+/** Runtime request details consumed by a `Fetcher` implementation. */
+export type FetchInput = {
+    /** Fully qualified URL that will be requested. */
+    url: string;
+    /** HTTP method (always uppercase). */
+    method: Uppercase<HttpMethod>;
+    /** Optional request body (already normalized by the client). */
+    body?: unknown;
+    /** Additional headers merged into the request. */
+    headers?: Record<string, string>;
+};
+/** Default signature for HTTP fetch implementations. */
+export type Fetcher = <T>(req: FetchInput) => Promise<T>;
+/** Debug verbosity levels supported by the client. */
+export type RouteClientDebugMode = 'minimal' | 'complete';
+type RouteClientDebugEventBase = {
+    /** Optional logical name supplied when building this endpoint. */
+    name?: string;
+};
+/** Discrete debug events emitted by the client internals. */
+export type RouteClientDebugEvent = (RouteClientDebugEventBase & {
+    type: 'fetch';
+    stage: 'start' | 'success' | 'error';
+    method: Uppercase<HttpMethod>;
+    url: string;
+    leaf: string;
+    durationMs?: number;
+    body?: unknown;
+    params?: unknown;
+    query?: unknown;
+    output?: unknown;
+    error?: unknown;
+}) | (RouteClientDebugEventBase & {
+    type: 'invalidate';
+    key: QueryKey;
+    exact: boolean;
+}) | (RouteClientDebugEventBase & {
+    type: 'setData';
+    key: QueryKey;
+}) | (RouteClientDebugEventBase & {
+    type: 'build';
+    leaf: string;
+}) | (RouteClientDebugEventBase & {
+    type: 'useEndpoint';
+    leaf: string;
+    variant: 'get' | 'infiniteGet' | 'mutation';
+});
+/** Logger signature invoked when debug logging is enabled. */
+export type RouteClientDebugLogger = (event: RouteClientDebugEvent) => void;
+/**
+ * Toggle-specific configuration controlling which debug events log, whether verbose details
+ * are emitted, and which named endpoints are allowed to log.
+ */
+export type RouteClientDebugToggleOptions<Names extends string = string> = Partial<Record<RouteClientDebugEvent['type'], boolean>> & {
+    /** When true, include verbose metadata (same as `mode === 'complete'`). */
+    verbose?: boolean;
+    /** Optional logger override used instead of the default console logger. */
+    logger?: RouteClientDebugLogger;
+    /**
+     * Limit logs to endpoints whose debug name is contained in this allow-list.
+     * Provide the counterpart by passing `meta: { name: '<value>' }` as the third argument to `client.build`.
+     */
+    only?: Names[];
+};
+/**
+ * Toggle or customize debug logging produced by the client.
+ * - Pass `true`/`'minimal'`/`'complete'` for simple modes.
+ * - Provide a custom logger function to redirect events.
+ * - Supply an object to enable individual event types, flip verbose mode, and/or limit logs via `only`.
+ */
+export type RouteClientDebugOptions<Names extends string = string> = boolean | RouteClientDebugLogger | RouteClientDebugMode | RouteClientDebugToggleOptions<Names>;
+/** Optional runtime environment; when set to 'production' logging is disabled. */
+export type RouteClientEnvironment = 'development' | 'production' | (string & {});
+/** Configuration passed to `createRouteClient`. */
+export type RouteClientOptions<Names extends string = string> = {
+    /** Base URL prepended to every route (optional). */
+    baseUrl: string;
+    /** Custom fetch implementation; defaults to `defaultFetcher`. */
+    fetcher?: Fetcher;
+    /** Shared React Query client used for caching/invalidation. */
+    queryClient: QueryClient;
+    /** Query string key used for pagination cursors (default: "cursor"). */
+    cursorParam?: string;
+    /** Function that extracts the next cursor from an infinite query page. */
+    getNextCursor?: (page: unknown) => Cursor;
+    /** Optional debug logger for verbose insights (supports minimal/complete modes). */
+    debug?: RouteClientDebugOptions<Names>;
+    /**
+     * Optional environment hint used to silence logging in production.
+     * When set to `'production'`, all debug logging is disabled regardless of the `debug` option.
+     */
+    environment?: RouteClientEnvironment;
+};
+type OutputOf<L extends AnyLeaf> = InferOutput<L>;
+type ParamsOf<L extends AnyLeaf> = InferParams<L>;
+type QueryOf<L extends AnyLeaf> = InferQuery<L>;
+type BodyOf<L extends AnyLeaf> = InferBody<L>;
+/** Variadic args consumed by the direct fetch helper: optional args + body. */
+export type MutationFetchArgs<L extends AnyLeaf> = [...ArgsTuple<L>, BodyOf<L>];
+/** Signature for the fetch helper returned by mutation builds. */
+export type MutationFetcher<L extends AnyLeaf> = (...args: MutationFetchArgs<L>) => Promise<OutputOf<L>>;
+/** Optional metadata provided when building a helper (used for debug filtering). */
+export type BuildMeta<Names extends string = string> = {
+    /**
+     * Logical name assigned to the built endpoint (e.g., the screen or feature name).
+     * Combine with `debug.only` to limit which endpoints emit logs.
+     */
+    name?: Names;
+};
+/** Object shape the user passes to hooks and helpers (params/query are optional). */
+export type ArgsFor<L extends AnyLeaf> = (ParamsOf<L> extends never ? {} : {
+    params: ParamsOf<L>;
+}) & (QueryOf<L> extends never ? {} : {
+    query: QueryOf<L>;
+});
+/** Variadic tuple representation that omits the argument entirely when not needed. */
+export type ArgsTuple<L extends AnyLeaf> = keyof ArgsFor<L> extends never ? [] : [args: ArgsFor<L>];
+/** Cache data shape for setData(...) */
+export type DataShape<L extends AnyLeaf> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteData<OutputOf<L>> : OutputOf<L> : OutputOf<L>;
+/** React Query build options specialized for a plain GET leaf. */
+export type QueryBuildOptionsFor<L extends AnyLeaf> = Omit<UseQueryOptions<OutputOf<L>, unknown, OutputOf<L>, QueryKey>, 'queryKey' | 'queryFn'>;
+/** Build options for feed-style GET leaves (`cfg.feed === true`). */
+export type InfiniteBuildOptionsFor<L extends AnyLeaf> = Omit<UseInfiniteQueryOptions<OutputOf<L>, unknown, InfiniteData<OutputOf<L>>, QueryKey, Cursor>, 'queryKey' | 'queryFn' | 'initialPageParam' | 'getNextPageParam'>;
+/** Build options for mutation leaves (non-GET). */
+export type MutationBuildOptionsFor<L extends AnyLeaf> = Omit<UseMutationOptions<OutputOf<L>, unknown, BodyOf<L>, unknown>, 'mutationFn' | 'mutationKey'>;
+/** Shared capabilities exposed by every built endpoint helper. */
+export type BuiltCommon<L extends AnyLeaf> = {
+    /**
+     * Deterministic key (infinite keys omit the cursor by design).
+     * @param args Optional params/query tuple for the leaf.
+     * @returns Query key tuple.
+     */
+    key: (...args: ArgsTuple<L>) => QueryKey;
+    /**
+     * Invalidate exactly this endpoint instance.
+     * @param args Optional params/query tuple for the leaf.
+     */
+    invalidate: (...args: ArgsTuple<L>) => Promise<void>;
+    /**
+     * Directly update the cache for this endpoint. Handles infinite vs regular.
+     * @param updater New value or function applied to existing cache data.
+     * @param rest Optional params/query tuple for the leaf.
+     */
+    setData: (...args: [updater: Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => void;
+};
+/** Hook+helpers for a standard GET endpoint. */
+export type BuiltQuery<L extends AnyLeaf> = BuiltCommon<L> & {
+    /**
+     * React hook bound to the GET leaf.
+     * @param args Optional params/query tuple for the leaf.
+     */
+    useEndpoint: (...args: ArgsTuple<L>) => UseQueryResult<OutputOf<L>, unknown>;
+};
+/** Hook+helpers for a cursor-paginated GET endpoint. */
+export type BuiltInfinite<L extends AnyLeaf> = BuiltCommon<L> & {
+    /**
+     * React hook bound to an infinite GET leaf.
+     * @param args Optional params/query tuple for the leaf.
+     */
+    useEndpoint: (...args: ArgsTuple<L>) => UseInfiniteQueryResult<InfiniteData<OutputOf<L>>, unknown>;
+};
+/** Hook+helpers for non-GET endpoints (mutations). */
+export type BuiltMutation<L extends AnyLeaf> = BuiltCommon<L> & {
+    /**
+     * React hook bound to a mutation leaf.
+     * @param args Optional params/query tuple for the leaf.
+     */
+    useEndpoint: (...args: ArgsTuple<L>) => UseMutationResult<OutputOf<L>, unknown, BodyOf<L>, unknown>;
+    /**
+     * Direct fetch helper that bypasses React Query, useful for server actions or scripts.
+     * Pass params/query first (if required), followed by the body payload.
+     */
+    fetch: MutationFetcher<L>;
+};
+/** Type-safe union that resolves to the correct built helper for a leaf. */
+export type BuiltForLeaf<L extends AnyLeaf> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? BuiltInfinite<L> : BuiltQuery<L> : BuiltMutation<L>;
+/** Public surface returned by `createRouteClient`. */
+export type RouteClient<Names extends string = string> = {
+    /**
+     * Invalidate by a key prefix (e.g., ['get','api','users']).
+     * @param prefix Key parts shared by matching endpoints.
+     * @param exact When true, invalidate only exact key matches.
+     */
+    invalidate: (prefix: string[], exact?: boolean) => Promise<void>;
+    /** Build a typed endpoint from a leaf. */
+    build: {
+        <L extends AnyLeaf & {
+            method: 'get';
+            cfg: {
+                feed: true;
+            };
+        }>(leaf: L, opts?: InfiniteBuildOptionsFor<L>, 
+        /** Optional metadata (third arg) to assign a debug name for filtering via `debug.only`. */
+        meta?: BuildMeta<Names>): BuiltInfinite<L>;
+        <L extends AnyLeaf & {
+            method: 'get';
+            cfg: {
+                feed?: false | undefined;
+            };
+        }>(leaf: L, opts?: QueryBuildOptionsFor<L>, 
+        /** Optional metadata (third arg) to assign a debug name for filtering via `debug.only`. */
+        meta?: BuildMeta<Names>): BuiltQuery<L>;
+        <L extends AnyLeaf & {
+            method: Exclude<HttpMethod, 'get'>;
+        }>(leaf: L, opts?: MutationBuildOptionsFor<L>, 
+        /** Optional metadata (third arg) to assign a debug name for filtering via `debug.only`. */
+        meta?: BuildMeta<Names>): BuiltMutation<L>;
+    };
+    /** Underlying React Query client (exposed for advanced scenarios). */
+    queryClient: QueryClient;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/rrroutes-client",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",
@@ -19,8 +19,8 @@
     "dist"
   ],
   "dependencies": {
-    "@emeryld/rrroutes-contract": "^1.3.0",
-    "zod": "^4.1.8"
+    "@emeryld/rrroutes-contract": "^1.3.5",
+    "zod": "^4.1.12"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.87.4"