routesync 1.0.19 → 1.0.21

package/dist/core.d.mts

@@ -12,6 +12,14 @@ interface ServiceConfig {
     timeout?: number;
     retry?: RetryConfig;
     cache?: boolean;
+    validateResponse?: boolean;
+    onValidationError?: (error: unknown, context: {
+        endpoint: string;
+        method: string;
+        path: string;
+        request: unknown;
+        response: unknown;
+    }) => void;
 }
 interface RetryConfig {
     attempts: number;
@@ -27,6 +35,7 @@ interface AuthConfig {
 
 declare class HttpClient {
     private client;
+    readonly config: ServiceConfig;
     constructor(config: ServiceConfig);
     private setupInterceptors;
     setToken(token: string): void;
@@ -73,11 +82,15 @@ interface RequestOptions {
     timeout?: number;
     signal?: AbortSignal;
 }
-interface RouteDefinition {
+interface ResponseSchema<T> {
+    parse(input: unknown): T;
+}
+interface RouteDefinition<TResponse = unknown, TParams = unknown, TBody = unknown> {
     method: HttpMethod;
     path: string;
     auth?: boolean;
     schema?: RouteSchema;
+    responseSchema?: ResponseSchema<TResponse>;
     mapper?: RouteMapper;
     headers?: Record<string, string>;
     cache?: unknown;
@@ -85,10 +98,13 @@ interface RouteDefinition {
     body?: Record<string, any>;
     params?: Record<string, any>;
     query?: Record<string, any>;
+    _typeResponse?: TResponse;
+    _typeParams?: TParams;
+    _typeBody?: TBody;
 }
 interface ApiDefinition {
     [group: string]: {
-        [action: string]: RouteDefinition;
+        [action: string]: RouteDefinition<any, any, any>;
     };
 }
 
@@ -218,6 +234,10 @@ interface ParsedRoute {
     schema?: Record<string, any>;
     group?: string;
     action?: string;
+    response?: {
+        type: string;
+        collection: boolean;
+    };
 }
 interface ParsedColumn {
     name: string;
@@ -233,4 +253,4 @@ interface ParsedModel {
     casts?: Record<string, string>;
 }
 
-export { type ApiDefinition, ApiError, type ApiResponse, type AuthConfig, AuthMiddleware, ErrorHandler, HttpClient, type HttpMethod, Interceptor, type PaginationMeta, type ParsedChannel, type ParsedColumn, type ParsedModel, type ParsedRoute, PathResolver, QueryBuilder, Request, type RequestOptions, Response, type RetryConfig, type RouteDefinition, type RouteManifest, type RouteMapper, type RouteParserSchema, type RouteSchema, type RouteSchemaMap, type RouteSchemaValue, type RouteTransform, type RouteTransformMap, type ServiceConfig, TokenManager, camelCase, camelCaseKeys, snakeCase, snakeCaseKeys };
+export { type ApiDefinition, ApiError, type ApiResponse, type AuthConfig, AuthMiddleware, ErrorHandler, HttpClient, type HttpMethod, Interceptor, type PaginationMeta, type ParsedChannel, type ParsedColumn, type ParsedModel, type ParsedRoute, PathResolver, QueryBuilder, Request, type RequestOptions, Response, type ResponseSchema, type RetryConfig, type RouteDefinition, type RouteManifest, type RouteMapper, type RouteParserSchema, type RouteSchema, type RouteSchemaMap, type RouteSchemaValue, type RouteTransform, type RouteTransformMap, type ServiceConfig, TokenManager, camelCase, camelCaseKeys, snakeCase, snakeCaseKeys };

package/dist/core.d.ts

@@ -12,6 +12,14 @@ interface ServiceConfig {
     timeout?: number;
     retry?: RetryConfig;
     cache?: boolean;
+    validateResponse?: boolean;
+    onValidationError?: (error: unknown, context: {
+        endpoint: string;
+        method: string;
+        path: string;
+        request: unknown;
+        response: unknown;
+    }) => void;
 }
 interface RetryConfig {
     attempts: number;
@@ -27,6 +35,7 @@ interface AuthConfig {
 
 declare class HttpClient {
     private client;
+    readonly config: ServiceConfig;
     constructor(config: ServiceConfig);
     private setupInterceptors;
     setToken(token: string): void;
@@ -73,11 +82,15 @@ interface RequestOptions {
     timeout?: number;
     signal?: AbortSignal;
 }
-interface RouteDefinition {
+interface ResponseSchema<T> {
+    parse(input: unknown): T;
+}
+interface RouteDefinition<TResponse = unknown, TParams = unknown, TBody = unknown> {
     method: HttpMethod;
     path: string;
     auth?: boolean;
     schema?: RouteSchema;
+    responseSchema?: ResponseSchema<TResponse>;
     mapper?: RouteMapper;
     headers?: Record<string, string>;
     cache?: unknown;
@@ -85,10 +98,13 @@ interface RouteDefinition {
     body?: Record<string, any>;
     params?: Record<string, any>;
     query?: Record<string, any>;
+    _typeResponse?: TResponse;
+    _typeParams?: TParams;
+    _typeBody?: TBody;
 }
 interface ApiDefinition {
     [group: string]: {
-        [action: string]: RouteDefinition;
+        [action: string]: RouteDefinition<any, any, any>;
     };
 }
 
@@ -218,6 +234,10 @@ interface ParsedRoute {
     schema?: Record<string, any>;
     group?: string;
     action?: string;
+    response?: {
+        type: string;
+        collection: boolean;
+    };
 }
 interface ParsedColumn {
     name: string;
@@ -233,4 +253,4 @@ interface ParsedModel {
     casts?: Record<string, string>;
 }
 
-export { type ApiDefinition, ApiError, type ApiResponse, type AuthConfig, AuthMiddleware, ErrorHandler, HttpClient, type HttpMethod, Interceptor, type PaginationMeta, type ParsedChannel, type ParsedColumn, type ParsedModel, type ParsedRoute, PathResolver, QueryBuilder, Request, type RequestOptions, Response, type RetryConfig, type RouteDefinition, type RouteManifest, type RouteMapper, type RouteParserSchema, type RouteSchema, type RouteSchemaMap, type RouteSchemaValue, type RouteTransform, type RouteTransformMap, type ServiceConfig, TokenManager, camelCase, camelCaseKeys, snakeCase, snakeCaseKeys };
+export { type ApiDefinition, ApiError, type ApiResponse, type AuthConfig, AuthMiddleware, ErrorHandler, HttpClient, type HttpMethod, Interceptor, type PaginationMeta, type ParsedChannel, type ParsedColumn, type ParsedModel, type ParsedRoute, PathResolver, QueryBuilder, Request, type RequestOptions, Response, type ResponseSchema, type RetryConfig, type RouteDefinition, type RouteManifest, type RouteMapper, type RouteParserSchema, type RouteSchema, type RouteSchemaMap, type RouteSchemaValue, type RouteTransform, type RouteTransformMap, type ServiceConfig, TokenManager, camelCase, camelCaseKeys, snakeCase, snakeCaseKeys };

package/dist/core.js

@@ -87,6 +87,7 @@ function snakeCaseKeys(obj) {
 var import_axios = __toESM(require("axios"));
 var HttpClient = class {
   constructor(config) {
+    this.config = config;
     this.client = import_axios.default.create({
       baseURL: config.baseURL,
       timeout: config.timeout ?? 1e4,

package/dist/core.mjs

@@ -38,6 +38,7 @@ function snakeCaseKeys(obj) {
 import axios from "axios";
 var HttpClient = class {
   constructor(config) {
+    this.config = config;
     this.client = axios.create({
       baseURL: config.baseURL,
       timeout: config.timeout ?? 1e4,

package/dist/react.d.mts

@@ -1,5 +1,5 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+import { UseQueryOptions, InfiniteData, UseInfiniteQueryOptions, UseSuspenseQueryOptions, UseMutationOptions, QueryClient } from '@tanstack/react-query';
 
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 type RouteTransform = (value: unknown) => unknown;
@@ -24,11 +24,15 @@ interface RouteSchemaMap {
 }
 type RouteSchemaValue = RouteTransform | RouteParserSchema;
 type RouteSchema = RouteSchemaValue | RouteSchemaMap;
-interface RouteDefinition {
+interface ResponseSchema<T> {
+    parse(input: unknown): T;
+}
+interface RouteDefinition<TResponse = unknown, TParams = unknown, TBody = unknown> {
     method: HttpMethod;
     path: string;
     auth?: boolean;
     schema?: RouteSchema;
+    responseSchema?: ResponseSchema<TResponse>;
     mapper?: RouteMapper;
     headers?: Record<string, string>;
     cache?: unknown;
@@ -36,20 +40,33 @@ interface RouteDefinition {
     body?: Record<string, any>;
     params?: Record<string, any>;
     query?: Record<string, any>;
+    _typeResponse?: TResponse;
+    _typeParams?: TParams;
+    _typeBody?: TBody;
 }
 
-type CallOptions = {
-    params?: Record<string, any>;
+type EndpointCallableOptions<TParams, TBody> = (unknown extends TParams ? {} : {
+    params: TParams;
+}) & (unknown extends TBody ? {} : {
+    body: TBody;
+}) & {
     query?: Record<string, any>;
-    body?: Record<string, any>;
     headers?: Record<string, string>;
 };
-interface EndpointCallable {
-    <TResponse = unknown>(options?: CallOptions): Promise<TResponse>;
+type OptionalIfEmpty<T> = keyof Omit<T, 'query' | 'headers'> extends never ? [options?: T] : [options: T];
+interface ApiError {
+    message: string;
+    status?: number;
+    errors?: Record<string, string[]>;
+}
+interface EndpointCallable<TResponse = unknown, TParams = unknown, TBody = unknown> {
+    (...args: OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>): Promise<TResponse>;
     /** Original RouteDefinition — used by useApiQuery / useApiMutation */
-    $def: RouteDefinition;
+    $def: RouteDefinition<TResponse, TParams, TBody>;
     /** Stable TanStack query key: [group, action] */
     $key: string[];
+    /** Consistent query key builder that incorporates params/query if provided */
+    $queryKey: (...args: OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>) => unknown[];
 }
 
 /**
@@ -59,7 +76,24 @@ interface EndpointCallable {
  *   const { data, isLoading } = useApiQuery(api.produk.list)
  *   const { data } = useApiQuery(api.produk.detail, { params: { id: 10 } })
  */
-declare function useApiQuery<T = any>(endpoint: EndpointCallable, options?: CallOptions, queryOptions?: Omit<UseQueryOptions<T>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<NoInfer<T>, Error>;
+declare function useApiQuery<TResponse = unknown, TParams = unknown, TBody = unknown, TError = ApiError, TData = TResponse>(endpoint: EndpointCallable<TResponse, TParams, TBody>, ...args: [
+    ...OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>,
+    queryOptions?: Omit<UseQueryOptions<TResponse, TError, TData>, 'queryKey' | 'queryFn'>
+]): _tanstack_react_query.UseQueryResult<NoInfer<TData>, TError>;
+/**
+ * useApiSuspenseQuery — generic wrapper for Suspense-enabled data fetching (TanStack v5).
+ */
+declare function useApiSuspenseQuery<TResponse = unknown, TParams = unknown, TBody = unknown, TError = ApiError, TData = TResponse>(endpoint: EndpointCallable<TResponse, TParams, TBody>, ...args: [
+    ...OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>,
+    queryOptions?: Omit<UseSuspenseQueryOptions<TResponse, TError, TData>, 'queryKey' | 'queryFn'>
+]): _tanstack_react_query.UseSuspenseQueryResult<TData, TError>;
+/**
+ * useApiInfiniteQuery — framework agnostic paginated fetching.
+ */
+declare function useApiInfiniteQuery<TResponse = unknown, TParams = unknown, TBody = unknown, TError = ApiError, TData = InfiniteData<TResponse>, TPageParam = unknown>(endpoint: EndpointCallable<TResponse, TParams, TBody>, ...args: [
+    ...OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>,
+    queryOptions: Omit<UseInfiniteQueryOptions<TResponse, TError, TData, any, TPageParam>, 'queryKey' | 'queryFn'>
+]): _tanstack_react_query.UseInfiniteQueryResult<TData, TError>;
 
 /**
  * useApiMutation — accepts an endpoint callable directly.
@@ -74,11 +108,40 @@ declare function useApiQuery<T = any>(endpoint: EndpointCallable, options?: Call
  *     invalidate: [api.cart.list, api.orders.index],
  *   })
  */
-interface ApiMutationOptions<TData, TVariables> extends Omit<UseMutationOptions<TData, unknown, TVariables>, 'mutationFn'> {
+interface ApiMutationOptions<TData, TError, TVariables, TContext = unknown> extends Omit<UseMutationOptions<TData, TError, TVariables, TContext>, 'mutationFn'> {
     /** Extra endpoints to invalidate on success (in addition to the auto group invalidation). */
-    invalidate?: EndpointCallable[];
+    invalidate?: EndpointCallable<any, any, any>[];
 }
-declare function useApiMutation<TData = any, TVariables extends CallOptions = CallOptions>(endpoint: EndpointCallable, options?: ApiMutationOptions<TData, TVariables>): _tanstack_react_query.UseMutationResult<TData, unknown, TVariables, unknown>;
+declare function useApiMutation<TResponse = unknown, TParams = unknown, TBody = unknown, TError = ApiError, TContext = unknown>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options?: ApiMutationOptions<TResponse, TError, EndpointCallableOptions<TParams, TBody>, TContext>): _tanstack_react_query.UseMutationResult<TResponse, TError, EndpointCallableOptions<TParams, TBody>, TContext>;
+
+/**
+ * useApiQueryClient — a typed wrapper over TanStack's QueryClient
+ *
+ * Provides ergonomic helpers like invalidateEndpoint and prefetchEndpoint
+ * with strong typing based on the RouteSync SDK contracts.
+ */
+declare function useApiQueryClient(): {
+    queryClient: QueryClient;
+    /**
+     * Invalidate specific queries related to an endpoint.
+     * Optionally pass parameters to invalidate a more specific cache entry.
+     */
+    invalidateEndpoint: <TResponse, TParams, TBody>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options?: EndpointCallableOptions<TParams, TBody>) => Promise<void>;
+    /**
+     * Prefetch data for an endpoint into the cache.
+     * Useful for SSR, RSC hydration, or proactive prefetching.
+     */
+    prefetchEndpoint: <TResponse, TParams, TBody>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options?: EndpointCallableOptions<TParams, TBody>) => Promise<void>;
+    /**
+     * Manually update the cache for a specific endpoint.
+     * Often used for optimistic updates in mutations.
+     */
+    setEndpointData: <TResponse, TParams, TBody>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options: EndpointCallableOptions<TParams, TBody> | undefined, updater: TResponse | ((oldData: TResponse | undefined) => TResponse)) => unknown;
+    /**
+     * Retrieve the current cached data for a specific endpoint.
+     */
+    getEndpointData: <TResponse, TParams, TBody>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options?: EndpointCallableOptions<TParams, TBody>) => TResponse | undefined;
+};
 
 /**
  * createHooks — generate typed hooks from an api group.
@@ -93,4 +156,19 @@ declare function useApiMutation<TData = any, TVariables extends CallOptions = Ca
  */
 declare function createHooks<T extends Record<string, EndpointCallable>>(group: T): { [K in keyof T as `use${Capitalize<string & K>}`]: T[K] extends EndpointCallable ? T[K]["$def"]["method"] extends "GET" | "DELETE" ? (options?: any, queryOptions?: any) => ReturnType<typeof useApiQuery> : (options?: any) => ReturnType<typeof useApiMutation> : never; };
 
-export { type ApiMutationOptions, createHooks, useApiMutation, useApiQuery };
+interface UseFormSetError<TFieldValues extends Record<string, any>> {
+    (name: keyof TFieldValues | string, error: {
+        type: string;
+        message?: string;
+    }): void;
+}
+/**
+ * Parses an unknown error and safely pipes 422 Unprocessable Entity
+ * validation messages to react-hook-form's setError.
+ *
+ * @param error - The error thrown by a RouteSync mutation
+ * @param setError - The `setError` function destructured from `useForm()`
+ */
+declare function setFormErrors<TFieldValues extends Record<string, any>>(error: unknown, setError: UseFormSetError<TFieldValues>): void;
+
+export { type ApiMutationOptions, createHooks, setFormErrors, useApiInfiniteQuery, useApiMutation, useApiQuery, useApiQueryClient, useApiSuspenseQuery };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+import { UseQueryOptions, InfiniteData, UseInfiniteQueryOptions, UseSuspenseQueryOptions, UseMutationOptions, QueryClient } from '@tanstack/react-query';
 
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 type RouteTransform = (value: unknown) => unknown;
@@ -24,11 +24,15 @@ interface RouteSchemaMap {
 }
 type RouteSchemaValue = RouteTransform | RouteParserSchema;
 type RouteSchema = RouteSchemaValue | RouteSchemaMap;
-interface RouteDefinition {
+interface ResponseSchema<T> {
+    parse(input: unknown): T;
+}
+interface RouteDefinition<TResponse = unknown, TParams = unknown, TBody = unknown> {
     method: HttpMethod;
     path: string;
     auth?: boolean;
     schema?: RouteSchema;
+    responseSchema?: ResponseSchema<TResponse>;
     mapper?: RouteMapper;
     headers?: Record<string, string>;
     cache?: unknown;
@@ -36,20 +40,33 @@ interface RouteDefinition {
     body?: Record<string, any>;
     params?: Record<string, any>;
     query?: Record<string, any>;
+    _typeResponse?: TResponse;
+    _typeParams?: TParams;
+    _typeBody?: TBody;
 }
 
-type CallOptions = {
-    params?: Record<string, any>;
+type EndpointCallableOptions<TParams, TBody> = (unknown extends TParams ? {} : {
+    params: TParams;
+}) & (unknown extends TBody ? {} : {
+    body: TBody;
+}) & {
     query?: Record<string, any>;
-    body?: Record<string, any>;
     headers?: Record<string, string>;
 };
-interface EndpointCallable {
-    <TResponse = unknown>(options?: CallOptions): Promise<TResponse>;
+type OptionalIfEmpty<T> = keyof Omit<T, 'query' | 'headers'> extends never ? [options?: T] : [options: T];
+interface ApiError {
+    message: string;
+    status?: number;
+    errors?: Record<string, string[]>;
+}
+interface EndpointCallable<TResponse = unknown, TParams = unknown, TBody = unknown> {
+    (...args: OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>): Promise<TResponse>;
     /** Original RouteDefinition — used by useApiQuery / useApiMutation */
-    $def: RouteDefinition;
+    $def: RouteDefinition<TResponse, TParams, TBody>;
     /** Stable TanStack query key: [group, action] */
     $key: string[];
+    /** Consistent query key builder that incorporates params/query if provided */
+    $queryKey: (...args: OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>) => unknown[];
 }
 
 /**
@@ -59,7 +76,24 @@ interface EndpointCallable {
  *   const { data, isLoading } = useApiQuery(api.produk.list)
  *   const { data } = useApiQuery(api.produk.detail, { params: { id: 10 } })
  */
-declare function useApiQuery<T = any>(endpoint: EndpointCallable, options?: CallOptions, queryOptions?: Omit<UseQueryOptions<T>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<NoInfer<T>, Error>;
+declare function useApiQuery<TResponse = unknown, TParams = unknown, TBody = unknown, TError = ApiError, TData = TResponse>(endpoint: EndpointCallable<TResponse, TParams, TBody>, ...args: [
+    ...OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>,
+    queryOptions?: Omit<UseQueryOptions<TResponse, TError, TData>, 'queryKey' | 'queryFn'>
+]): _tanstack_react_query.UseQueryResult<NoInfer<TData>, TError>;
+/**
+ * useApiSuspenseQuery — generic wrapper for Suspense-enabled data fetching (TanStack v5).
+ */
+declare function useApiSuspenseQuery<TResponse = unknown, TParams = unknown, TBody = unknown, TError = ApiError, TData = TResponse>(endpoint: EndpointCallable<TResponse, TParams, TBody>, ...args: [
+    ...OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>,
+    queryOptions?: Omit<UseSuspenseQueryOptions<TResponse, TError, TData>, 'queryKey' | 'queryFn'>
+]): _tanstack_react_query.UseSuspenseQueryResult<TData, TError>;
+/**
+ * useApiInfiniteQuery — framework agnostic paginated fetching.
+ */
+declare function useApiInfiniteQuery<TResponse = unknown, TParams = unknown, TBody = unknown, TError = ApiError, TData = InfiniteData<TResponse>, TPageParam = unknown>(endpoint: EndpointCallable<TResponse, TParams, TBody>, ...args: [
+    ...OptionalIfEmpty<EndpointCallableOptions<TParams, TBody>>,
+    queryOptions: Omit<UseInfiniteQueryOptions<TResponse, TError, TData, any, TPageParam>, 'queryKey' | 'queryFn'>
+]): _tanstack_react_query.UseInfiniteQueryResult<TData, TError>;
 
 /**
  * useApiMutation — accepts an endpoint callable directly.
@@ -74,11 +108,40 @@ declare function useApiQuery<T = any>(endpoint: EndpointCallable, options?: Call
  *     invalidate: [api.cart.list, api.orders.index],
  *   })
  */
-interface ApiMutationOptions<TData, TVariables> extends Omit<UseMutationOptions<TData, unknown, TVariables>, 'mutationFn'> {
+interface ApiMutationOptions<TData, TError, TVariables, TContext = unknown> extends Omit<UseMutationOptions<TData, TError, TVariables, TContext>, 'mutationFn'> {
     /** Extra endpoints to invalidate on success (in addition to the auto group invalidation). */
-    invalidate?: EndpointCallable[];
+    invalidate?: EndpointCallable<any, any, any>[];
 }
-declare function useApiMutation<TData = any, TVariables extends CallOptions = CallOptions>(endpoint: EndpointCallable, options?: ApiMutationOptions<TData, TVariables>): _tanstack_react_query.UseMutationResult<TData, unknown, TVariables, unknown>;
+declare function useApiMutation<TResponse = unknown, TParams = unknown, TBody = unknown, TError = ApiError, TContext = unknown>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options?: ApiMutationOptions<TResponse, TError, EndpointCallableOptions<TParams, TBody>, TContext>): _tanstack_react_query.UseMutationResult<TResponse, TError, EndpointCallableOptions<TParams, TBody>, TContext>;
+
+/**
+ * useApiQueryClient — a typed wrapper over TanStack's QueryClient
+ *
+ * Provides ergonomic helpers like invalidateEndpoint and prefetchEndpoint
+ * with strong typing based on the RouteSync SDK contracts.
+ */
+declare function useApiQueryClient(): {
+    queryClient: QueryClient;
+    /**
+     * Invalidate specific queries related to an endpoint.
+     * Optionally pass parameters to invalidate a more specific cache entry.
+     */
+    invalidateEndpoint: <TResponse, TParams, TBody>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options?: EndpointCallableOptions<TParams, TBody>) => Promise<void>;
+    /**
+     * Prefetch data for an endpoint into the cache.
+     * Useful for SSR, RSC hydration, or proactive prefetching.
+     */
+    prefetchEndpoint: <TResponse, TParams, TBody>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options?: EndpointCallableOptions<TParams, TBody>) => Promise<void>;
+    /**
+     * Manually update the cache for a specific endpoint.
+     * Often used for optimistic updates in mutations.
+     */
+    setEndpointData: <TResponse, TParams, TBody>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options: EndpointCallableOptions<TParams, TBody> | undefined, updater: TResponse | ((oldData: TResponse | undefined) => TResponse)) => unknown;
+    /**
+     * Retrieve the current cached data for a specific endpoint.
+     */
+    getEndpointData: <TResponse, TParams, TBody>(endpoint: EndpointCallable<TResponse, TParams, TBody>, options?: EndpointCallableOptions<TParams, TBody>) => TResponse | undefined;
+};
 
 /**
  * createHooks — generate typed hooks from an api group.
@@ -93,4 +156,19 @@ declare function useApiMutation<TData = any, TVariables extends CallOptions = Ca
  */
 declare function createHooks<T extends Record<string, EndpointCallable>>(group: T): { [K in keyof T as `use${Capitalize<string & K>}`]: T[K] extends EndpointCallable ? T[K]["$def"]["method"] extends "GET" | "DELETE" ? (options?: any, queryOptions?: any) => ReturnType<typeof useApiQuery> : (options?: any) => ReturnType<typeof useApiMutation> : never; };
 
-export { type ApiMutationOptions, createHooks, useApiMutation, useApiQuery };
+interface UseFormSetError<TFieldValues extends Record<string, any>> {
+    (name: keyof TFieldValues | string, error: {
+        type: string;
+        message?: string;
+    }): void;
+}
+/**
+ * Parses an unknown error and safely pipes 422 Unprocessable Entity
+ * validation messages to react-hook-form's setError.
+ *
+ * @param error - The error thrown by a RouteSync mutation
+ * @param setError - The `setError` function destructured from `useForm()`
+ */
+declare function setFormErrors<TFieldValues extends Record<string, any>>(error: unknown, setError: UseFormSetError<TFieldValues>): void;
+
+export { type ApiMutationOptions, createHooks, setFormErrors, useApiInfiniteQuery, useApiMutation, useApiQuery, useApiQueryClient, useApiSuspenseQuery };

package/dist/react.js

@@ -21,21 +21,53 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   createHooks: () => createHooks,
+  setFormErrors: () => setFormErrors,
+  useApiInfiniteQuery: () => useApiInfiniteQuery,
   useApiMutation: () => useApiMutation,
-  useApiQuery: () => useApiQuery
+  useApiQuery: () => useApiQuery,
+  useApiQueryClient: () => useApiQueryClient,
+  useApiSuspenseQuery: () => useApiSuspenseQuery
 });
 module.exports = __toCommonJS(src_exports);
 
 // packages/react/src/hooks/useQuery.ts
 var import_react_query = require("@tanstack/react-query");
-function useApiQuery(endpoint, options, queryOptions) {
-  const queryKey = options ? [...endpoint.$key, options] : endpoint.$key;
+function useApiQuery(endpoint, ...args) {
+  const options = args[0];
+  const queryOptions = args[1];
+  const queryKey = endpoint.$queryKey(options);
   return (0, import_react_query.useQuery)({
     queryKey,
     queryFn: () => endpoint(options),
     ...queryOptions
   });
 }
+function useApiSuspenseQuery(endpoint, ...args) {
+  const options = args[0];
+  const queryOptions = args[1];
+  const queryKey = endpoint.$queryKey(options);
+  return (0, import_react_query.useSuspenseQuery)({
+    queryKey,
+    queryFn: () => endpoint(options),
+    ...queryOptions
+  });
+}
+function useApiInfiniteQuery(endpoint, ...args) {
+  const options = args[0];
+  const queryOptions = args.length > 1 ? args[1] : args[0];
+  const queryKey = endpoint.$queryKey(options);
+  return (0, import_react_query.useInfiniteQuery)({
+    queryKey,
+    queryFn: ({ pageParam }) => {
+      const fetchOptions = { ...options };
+      if (pageParam !== void 0) {
+        fetchOptions.query = { ...fetchOptions.query || {}, page: pageParam };
+      }
+      return endpoint(fetchOptions);
+    },
+    ...queryOptions
+  });
+}
 
 // packages/react/src/hooks/useMutation.ts
 var import_react_query2 = require("@tanstack/react-query");
@@ -55,6 +87,47 @@ function useApiMutation(endpoint, options) {
   });
 }
 
+// packages/react/src/hooks/useQueryClient.ts
+var import_react_query3 = require("@tanstack/react-query");
+function useApiQueryClient() {
+  const queryClient = (0, import_react_query3.useQueryClient)();
+  return {
+    queryClient,
+    /**
+     * Invalidate specific queries related to an endpoint.
+     * Optionally pass parameters to invalidate a more specific cache entry.
+     */
+    invalidateEndpoint: (endpoint, options) => {
+      return queryClient.invalidateQueries({
+        queryKey: endpoint.$queryKey(options)
+      });
+    },
+    /**
+     * Prefetch data for an endpoint into the cache.
+     * Useful for SSR, RSC hydration, or proactive prefetching.
+     */
+    prefetchEndpoint: (endpoint, options) => {
+      return queryClient.prefetchQuery({
+        queryKey: endpoint.$queryKey(options),
+        queryFn: () => endpoint(options)
+      });
+    },
+    /**
+     * Manually update the cache for a specific endpoint.
+     * Often used for optimistic updates in mutations.
+     */
+    setEndpointData: (endpoint, options, updater) => {
+      return queryClient.setQueryData(endpoint.$queryKey(options), updater);
+    },
+    /**
+     * Retrieve the current cached data for a specific endpoint.
+     */
+    getEndpointData: (endpoint, options) => {
+      return queryClient.getQueryData(endpoint.$queryKey(options));
+    }
+  };
+}
+
 // packages/react/src/hooks/createHooks.ts
 function createHooks(group) {
   const hooks = {};
@@ -69,9 +142,30 @@ function createHooks(group) {
   }
   return hooks;
 }
+
+// packages/react/src/utils/form.ts
+function setFormErrors(error, setError) {
+  if (error && typeof error === "object" && "status" in error && error.status === 422) {
+    const apiError = error;
+    const errors = apiError.errors;
+    if (errors && typeof errors === "object") {
+      for (const [field, messages] of Object.entries(errors)) {
+        if (Array.isArray(messages) && messages.length > 0) {
+          setError(field, { type: "server", message: String(messages[0]) });
+        } else if (typeof messages === "string") {
+          setError(field, { type: "server", message: messages });
+        }
+      }
+    }
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createHooks,
+  setFormErrors,
+  useApiInfiniteQuery,
   useApiMutation,
-  useApiQuery
+  useApiQuery,
+  useApiQueryClient,
+  useApiSuspenseQuery
 });