@beignet/react-query 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @beignet/react-query
 
+## 0.0.4
+
+### Patch Changes
+
+- 8bcb31f: Mark package READMEs with Beignet's experimental alpha status and 0.0.x stability expectations.
+- df4673f: Add TanStack Query filter helpers for Beignet contract cache invalidation and update generated UI examples to use them.
+- 8fd9cb3: Document React Query key scopes, invalidation recipes, pagination, filters, and optimistic update patterns.
+- d137044: Declare `@beignet/core` as a peer dependency with a lockstep version range in
+  every integration and provider package instead of a regular `"*"` dependency.
+  Installs now always resolve a single shared copy of core, so `instanceof`
+  checks such as `isContractError` and upload error identity keep working, and
+  mixed Beignet versions fail loudly at install time instead of at runtime.
+
+  If your package manager does not install peer dependencies automatically, add
+  `@beignet/core` to your app alongside these packages. `@beignet/nuqs` now also
+  declares `@beignet/react-query` as a peer dependency, and
+  `@beignet/provider-storage-s3` now expects you to install
+  `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` yourself, matching
+  how other providers treat their SDKs.
+
+- 1a79090: Emit Node-compatible ESM: all relative imports in published packages now carry explicit .js extensions, fixing ERR_MODULE_NOT_FOUND when running the CLI or importing package dist files under plain Node.
+- 493d23b: Accept observer-level TanStack Query options (`enabled`, `staleTime`, `select`, `refetchInterval`, `placeholderData`, `throwOnError`) in `queryOptions(...)` and `mutationOptions(...)`. The options were already passed through at runtime but were rejected at the type level. `@beignet/nuqs` `toQueryOptions(...)` inherits the same fix.
+- d6ad8bb: Standardize generated client helpers around `client/index.ts`, add a typed
+  React Query invalidation helper, and align package docs with the canonical app
+  client entrypoint.
+- 8063d38: Rename the contract front door to `defineContract`/`defineContractGroup`, rename operational commands to tasks (`@beignet/core/tasks`, `defineTasks`, `runTask`, `beignet task run`, `beignet make task`, `server/tasks.ts`, `features/<feature>/tasks/`, `paths.tasks`), and standardize context binding: context-free declarations stay top-level (`defineEvent`), while context-bound definitions come from per-capability factories (`createListeners`, `createJobs`, `createSchedules`, `createNotifications`, `createTasks`) called once in `lib/`. Top-level context-generic `defineListener`, `defineJob`, `defineSchedule`, and `defineNotification` are removed.
+- 192c6ad: Typed clients now attach idempotency keys automatically from contract metadata (override with `idempotencyKey`), React Query mutations keep the key stable across retry attempts, and the shared client error helpers `contractErrorMessage` and `rootFormError` are now exported by @beignet/core/client and @beignet/react-hook-form.
+- 89390fe: Add a contract route segment to generated query keys, an adapter-level `keyHeaders` opt-in, and body pagination for infinite queries.
+
+  - Query keys now include the contract route after the local name: `["beignet", namespace | null, localName, "GET /v1/todos", params?]`. Two un-namespaced contract groups with different prefixes but the same derived local name (for example `GET /v1/todos` and `GET /v2/todos`) no longer share a cache key. This changes every generated query key, so persisted caches and any hand-written keys that mirrored the old `["beignet", namespace, localName, params?]` shape are invalidated after upgrading.
+  - `createReactQuery(client, { keyHeaders })` opts specific header names into generated query keys as a normalized lowercased `headers` key component. Headers stay excluded from keys by default so persisted caches never store credentials such as `Authorization` tokens.
+  - `infiniteQueryOptions(...)` accepts a static `body` merged with `page(...).body` per page, includes the static body in the derived key, and sends the merged body on each page request, so body-paginated POST search/list contracts work without a custom `key`/`params` escape hatch.
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [3160184]
+- Updated dependencies [254ef6d]
+- Updated dependencies [4cb1784]
+- Updated dependencies [8bd9085]
+  - @beignet/core@0.0.3
+
 ## 0.0.2
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,10 @@
 
 > TanStack Query integration for Beignet
 
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
 This package provides **options-first** TanStack Query integration that's automatically typed based on your contracts. Generate `queryOptions`, `mutationOptions`, and `infiniteQueryOptions` that work with all TanStack Query primitives (`useQuery`, `useMutation`, `useInfiniteQuery`, `prefetchQuery`, `fetchQuery`, etc.) with full type inference.
 
 ## Installation
@@ -17,11 +21,12 @@ This package requires TypeScript 5.0 or higher for proper type inference.
 
 ## Setup
 
-### 1. Create your client
+### 1. Create your app client helpers
 
 ```ts
-// lib/api-client.ts
 import { createClient } from "@beignet/core/client";
+import { createReactQuery } from "@beignet/react-query";
+import { QueryClient } from "@tanstack/react-query";
 
 export const apiClient = createClient({
   baseUrl: "https://api.example.com",
@@ -29,27 +34,25 @@ export const apiClient = createClient({
     Authorization: `Bearer ${getToken()}`,
   }),
 });
-```
-
-### 2. Create the React Query adapter
-
-```ts
-// lib/rq.ts
-import { createReactQuery } from "@beignet/react-query";
-import { apiClient } from "./api-client";
 
 export const rq = createReactQuery(apiClient);
+
+export function makeQueryClient() {
+  return new QueryClient();
+}
 ```
 
-### 3. Set up QueryClientProvider
+### 2. Set up QueryClientProvider
 
 ```tsx
 // app/providers.tsx
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { type ReactNode, useState } from "react";
+import { makeQueryClient } from "@/client";
 
-const queryClient = new QueryClient();
+export function Providers({ children }: { children: ReactNode }) {
+  const [queryClient] = useState(() => makeQueryClient());
 
-export function Providers({ children }) {
   return (
     <QueryClientProvider client={queryClient}>
       {children}
@@ -68,7 +71,7 @@ The options-first API generates options objects that can be used with any TanSta
 
 ```tsx
 import { useQuery } from "@tanstack/react-query";
-import { rq } from "@/client/rq";
+import { rq } from "@/client";
 import { getTodo } from "@/features/todos/contracts";
 
 function TodoDetail({ id }: { id: string }) {
@@ -97,7 +100,7 @@ function TodoDetail({ id }: { id: string }) {
 
 ```tsx
 import { useQueryClient } from "@tanstack/react-query";
-import { rq } from "@/client/rq";
+import { rq } from "@/client";
 import { getTodo } from "@/features/todos/contracts";
 
 function TodoList() {
@@ -119,12 +122,12 @@ function TodoList() {
 #### Server-side data fetching
 
 ```tsx
-import { QueryClient, dehydrate, HydrationBoundary } from "@tanstack/react-query";
-import { rq } from "@/client/rq";
+import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
+import { makeQueryClient, rq } from "@/client";
 import { getTodo } from "@/features/todos/contracts";
 
 export async function TodoPage({ params }: { params: { id: string } }) {
-  const queryClient = new QueryClient();
+  const queryClient = makeQueryClient();
 
   // Fetch on the server
   const todoQuery = rq(getTodo).queryOptions({
@@ -145,7 +148,7 @@ export async function TodoPage({ params }: { params: { id: string } }) {
 
 ```tsx
 import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { rq } from "@/client/rq";
+import { rq } from "@/client";
 import { createTodo, listTodos } from "@/features/todos/contracts";
 
 function CreateTodoForm() {
@@ -154,8 +157,8 @@ function CreateTodoForm() {
   // Generate mutation options
   const createTodoMutation = rq(createTodo).mutationOptions({
     onSuccess: (data, vars, onMutateResult, context) => {
-      // Invalidate queries
-      queryClient.invalidateQueries({ queryKey: rq(listTodos).contractKey() });
+      // Invalidate every cached listTodos call.
+      rq(listTodos).invalidate(queryClient);
     },
   });
 
@@ -180,7 +183,7 @@ function CreateTodoForm() {
 
 ```tsx
 import { useInfiniteQuery } from "@tanstack/react-query";
-import { rq } from "@/client/rq";
+import { rq } from "@/client";
 import { listTodos } from "@/features/todos/contracts";
 
 function InfiniteTodoList() {
@@ -215,7 +218,7 @@ function InfiniteTodoList() {
 
 ## API reference
 
-### `createReactQuery(client)`
+### `createReactQuery(client, options?)`
 
 Creates a React Query adapter factory.
 
@@ -223,6 +226,28 @@ Creates a React Query adapter factory.
 const rq = createReactQuery(apiClient);
 ```
 
+Headers are **excluded from generated query keys by default** because persisted
+caches would otherwise store credentials such as `Authorization` tokens. When a
+header changes response data — a tenant or workspace header, for example — opt
+that specific header into keys with `keyHeaders`:
+
+```ts
+const rq = createReactQuery(apiClient, {
+  keyHeaders: ["X-Tenant-Id"],
+});
+
+rq(listTodos).queryOptions({
+  headers: { "X-Tenant-Id": "tenant-1", Authorization: "Bearer ..." },
+});
+// queryKey: ["beignet", "todos", "listTodos", "GET /todos",
+//   { headers: { "x-tenant-id": "tenant-1" } }]
+```
+
+Only whitelisted header names are included. Names are matched
+case-insensitively and stored lowercased in the key. Never whitelist
+credential headers; pass a per-call `key` when you need a fully custom key
+instead.
+
 ### `rq(contract)`
 
 Creates a contract helper with query/mutation options methods.
@@ -240,6 +265,7 @@ const queryOpts = helper.queryOptions({
   path: { ... },            // Required when the contract has required path params
   query?: { ... },          // Required when the contract has required query params
   body?: { ... },           // Required when the contract has a required body
+  headers?: { ... },        // Sent with the request; keyed only via keyHeaders
   key?: readonly unknown[], // Custom query key
   // ...any other TanStack Query options (staleTime, enabled, etc.)
 });
@@ -263,6 +289,21 @@ const mutationOpts = helper.mutationOptions({
 useMutation(mutationOpts);
 ```
 
+For contracts with idempotency metadata, the generated `mutationFn` derives
+one idempotency key per `mutate(...)` invocation and keeps it stable across
+TanStack retry attempts, so retried requests replay instead of re-executing.
+Separate `mutate(...)` calls get distinct keys — retry stability does not
+deduplicate double-clicks. Pass `idempotencyKey` in the mutation variables for
+retry-with-same-key flows:
+
+```ts
+mutation.mutate({ body: { title: "New todo" }, idempotencyKey: key });
+```
+
+Caveat: calling `mutate()` with no variables skips per-invocation key
+derivation and the client generates a fresh key per attempt. Pass a variables
+object when an idempotent mutation should keep its key across retries.
+
 ### `helper.infiniteQueryOptions(options)`
 
 **[Recommended]** Generate infinite query options for pagination.
@@ -271,9 +312,11 @@ useMutation(mutationOpts);
 const infiniteOpts = helper.infiniteQueryOptions({
   path?: { ... },          // Static path params included in the cache key
   query?: { ... },         // Static query params included in the cache key
+  body?: { ... },          // Static body fields included in the cache key
   page?: (ctx: { pageParam }) => ({
     path?: { ... },        // Page-specific path params
     query?: { ... },       // Page-specific query params (cursor, offset, etc.)
+    body?: { ... },        // Page-specific body fields (cursor, offset, etc.)
   }),
   initialPageParam: ...,
   getNextPageParam: (lastPage) => ...,
@@ -285,6 +328,21 @@ const infiniteOpts = helper.infiniteQueryOptions({
 useInfiniteQuery(infiniteOpts);
 ```
 
+For body-paginated contracts, such as a POST search endpoint, keep the stable
+filters in the static `body` and put the cursor in `page(...).body`. The static
+body is part of the cache key, and each page request sends the merged body:
+
+```ts
+const searchOpts = rq(searchTodos).infiniteQueryOptions({
+  body: { term: "beignet" },
+  page: ({ pageParam }) => ({
+    body: { cursor: pageParam ?? null },
+  }),
+  initialPageParam: null as string | null,
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+});
+```
+
 If you need fully dynamic params, pass a custom `key` and use `params(...)` instead:
 
 ```ts
@@ -301,7 +359,7 @@ const infiniteOpts = helper.infiniteQueryOptions({
 ### `helper.namespaceKey()`
 
 Generate a namespace-level key for broad cache operations. Contracts created
-from `createContractGroup().namespace("todos")` use that namespace.
+from `defineContractGroup().namespace("todos")` use that namespace.
 Non-namespaced contracts use `null` so they cannot collide with a real
 namespace string.
 
@@ -311,35 +369,115 @@ helper.namespaceKey(); // ["beignet", "todos"]
 
 ### `helper.contractKey()`
 
-Generate a contract-level key without path, query, or body params.
+Generate a contract-level key without path, query, or body params. The key
+includes the contract route (`"GET /todos/:id"`), so two contracts with the
+same derived local name but different routes — for example `/v1/todos` and
+`/v2/todos` list contracts — never share a cache key.
 
 ```ts
-helper.contractKey(); // ["beignet", "todos", "getTodo"]
+helper.contractKey(); // ["beignet", "todos", "getTodo", "GET /todos/:id"]
 ```
 
+The route segment is also exposed as `helper.route` (`"GET /todos/:id"`).
+
 ### `helper.key(params?)`
 
 Generate a stable query key for cache operations.
 
 ```ts
-helper.key();                      // ["beignet", "todos", "getTodo"]
-helper.key({ path: { id: "1" } }); // ["beignet", "todos", "getTodo", { path: { id: "1" } }]
+helper.key();
+// ["beignet", "todos", "getTodo", "GET /todos/:id"]
+helper.key({ path: { id: "1" } });
+// ["beignet", "todos", "getTodo", "GET /todos/:id", { path: { id: "1" } }]
 ```
 
 `key(...)` normalizes params the same way the client serializes them: `null`
 and `undefined` object entries are omitted, while meaningful values like `0`,
 `false`, and empty strings are preserved. Request bodies are included in query
-keys when passed to `queryOptions(...)`.
+keys when passed to `queryOptions(...)`. Headers are excluded unless the
+adapter opted in with `createReactQuery(client, { keyHeaders })`.
+
+### `helper.namespaceFilter(options?)`
 
-These keys are plain TanStack Query keys, so prefix invalidation works as
-expected:
+Generate TanStack Query filters for every contract in the helper's Beignet
+namespace.
 
 ```ts
-queryClient.invalidateQueries({ queryKey: rq(getTodo).namespaceKey() });
-queryClient.invalidateQueries({ queryKey: rq(getTodo).contractKey() });
-queryClient.invalidateQueries({
-  queryKey: rq(getTodo).key({ path: { id: "1" } }),
-});
+queryClient.invalidateQueries(helper.namespaceFilter());
+queryClient.invalidateQueries(helper.namespaceFilter({ stale: true }));
+```
+
+### `helper.contractFilter(options?)`
+
+Generate TanStack Query filters for every cached call to this contract.
+
+```ts
+queryClient.invalidateQueries(helper.contractFilter());
+```
+
+### `helper.filter(params?, options?)`
+
+Generate TanStack Query filters for one contract call or parameter prefix.
+
+```ts
+queryClient.invalidateQueries(
+  helper.filter({ path: { id: "1" } }, { exact: true }),
+);
+```
+
+These filters wrap plain TanStack Query keys, so prefix invalidation works as
+expected while TanStack Query still owns cache behavior:
+
+```ts
+queryClient.invalidateQueries(rq(getTodo).namespaceFilter());
+rq(getTodo).invalidate(queryClient);
+rq(getTodo).invalidate(queryClient, { path: { id: "1" } });
+```
+
+Use the smallest filter that matches the data you want to refresh:
+
+| Helper | Scope |
+| --- | --- |
+| `namespaceFilter()` | Every contract in one Beignet namespace. |
+| `contractFilter()` | Every cached call for one contract. |
+| `filter({ path, query, body })` | One parameter-scoped contract key. |
+
+### `helper.invalidate(queryClient, params?, options?)`
+
+Invalidate cached data for one contract using the helper's generated filters.
+With no params it invalidates every cached call to the contract. Pass params to
+target a detail key or parameter prefix.
+
+```ts
+await rq(listTodos).invalidate(queryClient);
+await rq(getTodo).invalidate(queryClient, { path: { id: "1" } });
+```
+
+For list writes, invalidate the contract key so every filtered or paginated list
+result refreshes:
+
+```ts
+const createTodoMutation = useMutation(
+  rq(createTodo).mutationOptions({
+    onSuccess: () => {
+      rq(listTodos).invalidate(queryClient);
+    },
+  }),
+);
+```
+
+For detail writes, update or invalidate the exact detail key and then invalidate
+affected list contracts:
+
+```ts
+const updateTodoMutation = useMutation(
+  rq(updateTodo).mutationOptions({
+    onSuccess: (_todo, vars) => {
+      rq(getTodo).invalidate(queryClient, { path: vars.path });
+      rq(listTodos).invalidate(queryClient);
+    },
+  }),
+);
 ```
 
 ### `helper.endpoint`

package/dist/index.d.ts

@@ -1,11 +1,15 @@
-import type { Client, Endpoint, EndpointCallArgs, InferEndpointContractError, InferSuccessResponse } from "@beignet/core/client";
+import type { Client, Endpoint, EndpointCallArgs, InferBody, InferEndpointContractError, InferPathParams, InferQuery, InferSuccessResponse } from "@beignet/core/client";
 import { type ContractLike, type HttpContractConfig, type ResolveContract } from "@beignet/core/contracts";
-import type { InfiniteQueryObserverOptions, MutationOptions, QueryKey, QueryOptions } from "@tanstack/react-query";
-type HasRequiredKeys<T> = {
-    [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
-}[keyof T];
-type EndpointQueryArgs<TContract extends HttpContractConfig, TProvidedHeaders extends string> = Omit<EndpointCallArgs<TContract, TProvidedHeaders>, "rawBody" | "signal">;
-type ContractQueryOptionsBase<TContract extends HttpContractConfig> = Omit<QueryOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, InferSuccessResponse<TContract>, QueryKey>, "queryKey" | "queryFn">;
+import type { InfiniteQueryObserverOptions, InvalidateQueryFilters, QueryClient, QueryFunction, QueryKey, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
+type EndpointQueryArgs<TContract extends HttpContractConfig, TProvidedHeaders extends string> = Omit<EndpointCallArgs<TContract, TProvidedHeaders>, "rawBody" | "signal" | "idempotencyKey">;
+type EndpointArgValue<TArgs, TKey extends "path" | "query" | "body" | "headers"> = TKey extends keyof TArgs ? TArgs[TKey] : undefined;
+type IsRequiredValue<T> = undefined extends T ? false : true;
+type RequiresQueryOptionsArgs<TContract extends HttpContractConfig, TProvidedHeaders extends string> = IsRequiredValue<InferPathParams<TContract>> extends true ? true : IsRequiredValue<InferQuery<TContract>> extends true ? true : IsRequiredValue<InferBody<TContract>> extends true ? true : IsRequiredValue<EndpointArgValue<EndpointCallArgs<TContract, TProvidedHeaders>, "headers">> extends true ? true : false;
+type ContractQueryOptionsBase<TContract extends HttpContractConfig> = Omit<UseQueryOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, InferSuccessResponse<TContract>, QueryKey>, "queryKey" | "queryFn">;
+type ContractQueryOptionsResult<TContract extends HttpContractConfig> = ContractQueryOptionsBase<TContract> & {
+    queryKey: QueryKey;
+    queryFn: QueryFunction<InferSuccessResponse<TContract>, QueryKey>;
+};
 /**
  * Options accepted by `ReactQueryContractHelper.queryOptions(...)`.
  *
@@ -16,22 +20,39 @@ type ContractQueryOptionsBase<TContract extends HttpContractConfig> = Omit<Query
 export type ContractUseQueryOptions<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> = EndpointQueryArgs<TContract, TProvidedHeaders> & {
     key?: readonly unknown[];
 } & ContractQueryOptionsBase<TContract>;
-type ContractQueryOptionsCallArgs<TContract extends HttpContractConfig, TProvidedHeaders extends string> = HasRequiredKeys<EndpointQueryArgs<TContract, TProvidedHeaders>> extends never ? [args?: ContractUseQueryOptions<TContract, TProvidedHeaders>] : [args: ContractUseQueryOptions<TContract, TProvidedHeaders>];
+type ContractQueryOptionsCallArgs<TContract extends HttpContractConfig, TProvidedHeaders extends string> = RequiresQueryOptionsArgs<TContract, TProvidedHeaders> extends true ? [args: ContractUseQueryOptions<TContract, TProvidedHeaders>] : [args?: ContractUseQueryOptions<TContract, TProvidedHeaders>];
+export type ContractQueryKeyParams<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> = {
+    path?: EndpointArgValue<EndpointQueryArgs<TContract, TProvidedHeaders>, "path">;
+    query?: EndpointArgValue<EndpointQueryArgs<TContract, TProvidedHeaders>, "query">;
+    body?: EndpointArgValue<EndpointQueryArgs<TContract, TProvidedHeaders>, "body">;
+    headers?: EndpointArgValue<EndpointQueryArgs<TContract, TProvidedHeaders>, "headers">;
+};
 /**
  * Options accepted by `ReactQueryContractHelper.mutationOptions(...)`.
  *
  * TanStack `mutationFn` is generated from the contract endpoint, so callers pass
  * the normal TanStack mutation lifecycle options.
  */
-export type ContractUseMutationOptions<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> = Omit<MutationOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, EndpointCallArgs<TContract, TProvidedHeaders>, unknown>, "mutationFn">;
+export type ContractUseMutationOptions<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> = Omit<UseMutationOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, EndpointCallArgs<TContract, TProvidedHeaders>, unknown>, "mutationFn">;
+/**
+ * Body input for infinite queries.
+ *
+ * Object bodies are shallow-partial because the full request body is the
+ * merge of the static `body` and each `page(...).body`, so neither side has
+ * to satisfy required body fields alone. The merged body is still validated
+ * by the endpoint call.
+ */
+type InfiniteQueryBody<TContract extends HttpContractConfig> = InferBody<TContract> extends Record<string, unknown> ? Partial<InferBody<TContract>> : EndpointCallArgs<TContract>["body"];
 type InfiniteQueryResolvedParams<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> = {
     path?: EndpointCallArgs<TContract>["path"];
     query?: EndpointCallArgs<TContract>["query"];
+    body?: InfiniteQueryBody<TContract>;
     headers?: EndpointCallArgs<TContract, TProvidedHeaders>["headers"];
 };
 type SafeInfiniteQueryArgs<TContract extends HttpContractConfig, TPageParam, TProvidedHeaders extends string> = {
     path?: EndpointCallArgs<TContract>["path"];
     query?: EndpointCallArgs<TContract>["query"];
+    body?: InfiniteQueryBody<TContract>;
     headers?: EndpointCallArgs<TContract, TProvidedHeaders>["headers"];
     page?: (ctx: {
         pageParam: TPageParam;
@@ -46,6 +67,7 @@ type DynamicInfiniteQueryArgs<TContract extends HttpContractConfig, TPageParam,
     key: readonly unknown[];
     path?: never;
     query?: never;
+    body?: never;
     page?: never;
 };
 type ContractInfiniteQueryOptions<TContract extends HttpContractConfig, TPageParam, TProvidedHeaders extends string> = (SafeInfiniteQueryArgs<TContract, TPageParam, TProvidedHeaders> | DynamicInfiniteQueryArgs<TContract, TPageParam, TProvidedHeaders>) & Omit<InfiniteQueryObserverOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, InferSuccessResponse<TContract>, QueryKey, TPageParam>, "queryKey" | "queryFn">;
@@ -59,10 +81,14 @@ export type ContractQueryNamespaceKey = readonly [
 ];
 /**
  * Query key for one contract without path/query/body params.
+ *
+ * The fourth element is the contract route (`"GET /todos"`), so contracts
+ * with the same derived local name but different routes never share a key.
  */
 export type ContractQueryContractKey = readonly [
     typeof BEIGNET_QUERY_KEY_SCOPE,
     string | null,
+    string,
     string
 ];
 /**
@@ -72,8 +98,28 @@ export type ContractQueryKey = readonly [
     typeof BEIGNET_QUERY_KEY_SCOPE,
     string | null,
     string,
+    string,
     unknown?
 ];
+export type ContractQueryFilterOptions = Omit<InvalidateQueryFilters<QueryKey>, "queryKey">;
+export type ContractQueryFilter<TKey extends QueryKey> = ContractQueryFilterOptions & {
+    queryKey: TKey;
+};
+/**
+ * Options accepted by `createReactQuery(client, options?)`.
+ */
+export type CreateReactQueryOptions = {
+    /**
+     * Header names to include in generated query keys.
+     *
+     * Headers are excluded from query keys by default because persisted caches
+     * would otherwise store credentials such as `Authorization` tokens. Opt in
+     * per adapter with the specific identity headers that change response data,
+     * such as a tenant header. Names are matched case-insensitively and stored
+     * lowercased in the key.
+     */
+    keyHeaders?: readonly string[];
+};
 /**
  * TanStack Query helper bound to one Beignet contract.
  *
@@ -84,11 +130,17 @@ export type ContractQueryKey = readonly [
 export declare class ReactQueryContractHelper<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> {
     private contract;
     private _endpoint;
-    constructor(contract: TContract, _endpoint: Endpoint<TContract, TProvidedHeaders>);
+    private options;
+    constructor(contract: TContract, _endpoint: Endpoint<TContract, TProvidedHeaders>, options?: CreateReactQueryOptions);
     /**
      * Fully qualified contract name.
      */
     get name(): string;
+    /**
+     * Contract route used as the key segment that disambiguates contracts with
+     * the same local name, such as `/v1/todos` and `/v2/todos` list contracts.
+     */
+    get route(): string;
     /**
      * Resource namespace used for query-key grouping.
      */
@@ -105,6 +157,22 @@ export declare class ReactQueryContractHelper<TContract extends HttpContractConf
      * Build a contract-level query key without path/query params.
      */
     contractKey(): ContractQueryContractKey;
+    /**
+     * Build TanStack Query filters for all contracts in this namespace.
+     */
+    namespaceFilter(options?: ContractQueryFilterOptions): ContractQueryFilter<ContractQueryNamespaceKey>;
+    /**
+     * Build TanStack Query filters for every cached call to this contract.
+     */
+    contractFilter(options?: ContractQueryFilterOptions): ContractQueryFilter<ContractQueryContractKey>;
+    /**
+     * Pick the adapter-whitelisted `keyHeaders` out of call headers.
+     *
+     * Returns `undefined` unless the adapter opted in with `keyHeaders` and the
+     * call provides at least one whitelisted header. Header names are matched
+     * case-insensitively and lowercased in the key component.
+     */
+    private pickKeyHeaders;
     /**
      * Build a stable query key for this contract
      *
@@ -112,28 +180,49 @@ export declare class ReactQueryContractHelper<TContract extends HttpContractConf
      * This ensures consistent serialization between server (dehydrate) and
      * client (hydrate), since undefined object values may serialize
      * differently across React's RSC boundary vs JSON.stringify.
+     *
+     * Headers are never included unless the adapter opted in with
+     * `createReactQuery(client, { keyHeaders })`, and then only the whitelisted
+     * header names are included.
      */
     key(params?: {
         path?: unknown;
         query?: unknown;
         body?: unknown;
+        headers?: unknown;
     }): ContractQueryKey;
+    /**
+     * Build TanStack Query filters for one contract call or parameter prefix.
+     */
+    filter(params?: ContractQueryKeyParams<TContract, TProvidedHeaders>, options?: ContractQueryFilterOptions): ContractQueryFilter<ContractQueryKey>;
+    /**
+     * Invalidate cached data for this contract.
+     *
+     * With no params this invalidates every cached call to the contract. Pass
+     * path/query/body params to target a single call or parameter prefix.
+     */
+    invalidate(queryClient: QueryClient, params?: ContractQueryKeyParams<TContract, TProvidedHeaders>, options?: ContractQueryFilterOptions): Promise<void>;
     /**
      * Create query options for TanStack Query.
      *
      * Pass the result to `useQuery`, `prefetchQuery`, `fetchQuery`, or any API
      * that accepts query options.
      */
-    queryOptions(...callArgs: ContractQueryOptionsCallArgs<TContract, TProvidedHeaders>): QueryOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, InferSuccessResponse<TContract>, QueryKey> & {
-        queryKey: QueryKey;
-    };
+    queryOptions(...callArgs: ContractQueryOptionsCallArgs<TContract, TProvidedHeaders>): ContractQueryOptionsResult<TContract>;
     /**
      * Create mutation options for TanStack Query.
      *
      * The generated `mutationFn` accepts the same variables shape as the
      * underlying contract endpoint call.
+     *
+     * For contracts with idempotency metadata, the generated `mutationFn`
+     * derives one idempotency key per `mutate(...)` invocation and keeps it
+     * stable across TanStack retry attempts, which re-invoke `mutationFn` with
+     * the same variables object. Pass `idempotencyKey` in the variables to
+     * control the key explicitly. Calling `mutate()` with no variables falls
+     * back to per-attempt key generation in the client.
      */
-    mutationOptions(args?: Omit<MutationOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, EndpointCallArgs<TContract, TProvidedHeaders>, unknown>, "mutationFn">): MutationOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, EndpointCallArgs<TContract, TProvidedHeaders>, unknown>;
+    mutationOptions(args?: ContractUseMutationOptions<TContract, TProvidedHeaders>): UseMutationOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, EndpointCallArgs<TContract, TProvidedHeaders>, unknown>;
     /**
      * Create infinite query options for TanStack Query.
      *
@@ -152,7 +241,11 @@ export declare class ReactQueryContractHelper<TContract extends HttpContractConf
  *
  * Create this once near client setup, then bind contracts with the returned
  * `rq(contract)` function.
+ *
+ * Pass `keyHeaders` to include specific identity headers, such as a tenant
+ * header, in generated query keys. Headers are excluded by default so
+ * persisted caches never store credentials.
  */
-export declare function createReactQuery<TProvidedHeaders extends string = never>(client: Client<TProvidedHeaders>): <TContractLike extends ContractLike>(contract: TContractLike) => ReactQueryContractHelper<ResolveContract<TContractLike>, TProvidedHeaders>;
+export declare function createReactQuery<TProvidedHeaders extends string = never>(client: Client<TProvidedHeaders>, options?: CreateReactQueryOptions): <TContractLike extends ContractLike>(contract: TContractLike) => ReactQueryContractHelper<ResolveContract<TContractLike>, TProvidedHeaders>;
 export {};
 //# sourceMappingURL=index.d.ts.map