kitcn 0.23.0 → 0.24.0

package/dist/solid/index.d.ts

@@ -580,6 +580,12 @@ interface CRPCHttpRouter<TRecord extends HttpRouterRecord> {
 }
 //#endregion
 //#region src/crpc/http-types.d.ts
+/** Exact cache key for one route + args, as stored in the QueryClient */
+type HttpQueryKey = readonly ['httpQuery', string, unknown];
+/** Route-wide prefix key that matches every args variant of one route */
+type HttpQueryPrefixKey = readonly ['httpQuery', string];
+/** Mutation key for HTTP endpoints */
+type HttpMutationKey = readonly ['httpMutation', string];
 /** Error codes that can be returned from HTTP endpoints */
 type HttpErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'METHOD_NOT_SUPPORTED' | 'CONFLICT' | 'UNPROCESSABLE_CONTENT' | 'TOO_MANY_REQUESTS' | 'INTERNAL_SERVER_ERROR' | 'UNKNOWN';
 /** HTTP client error */
@@ -782,9 +788,6 @@ type InferHttpClientArgs<T> = T extends HttpProcedure<infer TInput, infer _TOutp
 }> : HttpInputArgs;
 /** Infer output type from HttpProcedure */
 type InferHttpOutput<T> = T extends HttpProcedure<infer _TInput, infer TOutput, infer _TParams, infer _TQuery> ? TOutput extends UnsetMarker ? unknown : TOutput extends z.ZodTypeAny ? z.infer<TOutput> : unknown : unknown;
-/** Query key with args (3-element) or prefix key without args (2-element) for invalidation */
-type HttpQueryKey = readonly ['httpQuery', string, unknown] | readonly ['httpQuery', string];
-type HttpMutationKey = readonly ['httpMutation', string];
 type ReservedQueryOptions$1 = 'queryKey' | 'queryFn';
 type ReservedMutationOptions$1 = 'mutationFn';
 /** Query options for GET HTTP endpoints - compatible with both createQuery and createSuspenseQuery */
@@ -803,8 +806,8 @@ type HttpMutationOptions<T extends HttpProcedure> = DistributiveOmit<HttpMutatio
  * - mutationOptions: For one-time actions like exports (createMutation)
  */
 type DecorateHttpQuery<T extends HttpProcedure> = {
-  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get query key for QueryClient methods (with args = exact match, without = prefix) */
-  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter for QueryClient methods (e.g., invalidateQueries) */
+  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get the exact cache key these args are stored under (getQueryData/setQueryData) */
+  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter matching every args variant (e.g., invalidateQueries) */
   queryFilter: (args?: InferHttpClientArgs<T>, filters?: DistributiveOmit<QueryFilters, 'queryKey'>) => QueryFilters; /** Mutation options for GET endpoints (exports, downloads - no caching) */
   mutationOptions: (opts?: HttpMutationOptions<T>) => HttpMutationOptsReturn<T>; /** Get mutation key for QueryClient methods */
   mutationKey: () => HttpMutationKey;
@@ -1609,4 +1612,4 @@ declare function useUploadMutationOptions<TGenerateUrlMutation extends FunctionR
  */
 declare function createVanillaCRPCProxy<TApi extends Record<string, unknown>>(api: TApi, meta: CallerMeta, convexClient: ConvexClient, transformer?: DataTransformerOptions): VanillaCRPCClient<TApi>;
 //#endregion
-export { AuthMutationError, AuthProvider, AuthStore, AuthStoreState, AuthType, Authenticated, CRPCClient, CRPCHttpOptions, ConvexActionOptions, ConvexAuthBridge, ConvexAuthProvider, ConvexAuthProviderProps, ConvexInfiniteQueryOptions, ConvexInfiniteQueryOptionsWithRef, ConvexProvider, ConvexProviderWithAuth, ConvexQueryClient, ConvexQueryClientOptions, ConvexQueryClientSingletonOptions, ConvexQueryOptions, CreateCRPCContextOptions, DecorateAction, DecorateInfiniteQuery, DecorateMutation, DecorateQuery, FetchAccessTokenContext, FetchAccessTokenFn, HttpCRPCClient, HttpCRPCClientFromRouter, type HttpClientOptions, type HttpFormValue, type HttpInputArgs, HttpMutationKey, HttpProxyOptions, HttpQueryKey, HttpRouteInfo, HttpRouteMap, InfiniteQueryOptsParam, MaybeAuthenticated, MaybeUnauthenticated, MetaContext, PaginationState, PaginationStatus, SolidAuthClient, SolidAuthProviderClient, Unauthenticated, Unsubscribe, UseInfiniteQueryResult, VanillaCRPCClient, VanillaHttpCRPCClient, VanillaHttpCRPCClientFromRouter, VanillaQuery, createAuthMutations, createCRPCContext, createCRPCOptionsProxy, createHttpProxy, createVanillaCRPCProxy, decodeJwtExp, getAuthType, getConvexQueryClientSingleton, getQueryClientSingleton, isAuthMutationError, useAuth, useAuthGuard, useAuthSkip, useAuthStore, useAuthValue, useConvex, useConvexActionOptions, useConvexActionQueryOptions, useConvexAuth, useConvexAuthBridge, useConvexInfiniteQueryOptions, useConvexMutationOptions, useConvexQueryClient, useConvexQueryOptions, useFetchAccessToken, useFnMeta, useInfiniteQuery, useIsAuth, useMaybeAuth, useMeta, useSafeConvexAuth, useUploadMutationOptions };
+export { AuthMutationError, AuthProvider, AuthStore, AuthStoreState, AuthType, Authenticated, CRPCClient, CRPCHttpOptions, ConvexActionOptions, ConvexAuthBridge, ConvexAuthProvider, ConvexAuthProviderProps, ConvexInfiniteQueryOptions, ConvexInfiniteQueryOptionsWithRef, ConvexProvider, ConvexProviderWithAuth, ConvexQueryClient, ConvexQueryClientOptions, ConvexQueryClientSingletonOptions, ConvexQueryOptions, CreateCRPCContextOptions, DecorateAction, DecorateInfiniteQuery, DecorateMutation, DecorateQuery, FetchAccessTokenContext, FetchAccessTokenFn, HttpCRPCClient, HttpCRPCClientFromRouter, type HttpClientOptions, type HttpFormValue, type HttpInputArgs, type HttpMutationKey, HttpProxyOptions, type HttpQueryKey, type HttpQueryPrefixKey, HttpRouteInfo, HttpRouteMap, InfiniteQueryOptsParam, MaybeAuthenticated, MaybeUnauthenticated, MetaContext, PaginationState, PaginationStatus, SolidAuthClient, SolidAuthProviderClient, Unauthenticated, Unsubscribe, UseInfiniteQueryResult, VanillaCRPCClient, VanillaHttpCRPCClient, VanillaHttpCRPCClientFromRouter, VanillaQuery, createAuthMutations, createCRPCContext, createCRPCOptionsProxy, createHttpProxy, createVanillaCRPCProxy, decodeJwtExp, getAuthType, getConvexQueryClientSingleton, getQueryClientSingleton, isAuthMutationError, useAuth, useAuthGuard, useAuthSkip, useAuthStore, useAuthValue, useConvex, useConvexActionOptions, useConvexActionQueryOptions, useConvexAuth, useConvexAuthBridge, useConvexInfiniteQueryOptions, useConvexMutationOptions, useConvexQueryClient, useConvexQueryOptions, useFetchAccessToken, useFnMeta, useInfiniteQuery, useIsAuth, useMaybeAuth, useMeta, useSafeConvexAuth, useUploadMutationOptions };

package/dist/solid/index.js

@@ -427,6 +427,38 @@ function getFunctionMeta(path, source) {
 
 //#endregion
 //#region src/crpc/http-types.ts
+/**
+* Build the exact cache key for an HTTP route.
+*
+* Missing args normalize to `{}` so the RSC prefetch, the browser observer, and
+* a hand-written `getQueryData` call all hash to the same key. Every producer
+* of an `httpQuery` cache key goes through here.
+*/
+function buildHttpQueryKey(routeKey, args) {
+	return [
+		"httpQuery",
+		routeKey,
+		args ?? {}
+	];
+}
+/**
+* Build the route-wide prefix key.
+*
+* Filters match on prefix, so this matches every args variant of the route.
+* Not a cache key: nothing is ever stored under it.
+*/
+function buildHttpQueryPrefixKey(routeKey) {
+	return ["httpQuery", routeKey];
+}
+/**
+* Freshness window for `crpc.http.*` routes, in milliseconds.
+*
+* HTTP routes are a pull model with no push channel, so hydrated data needs a
+* real freshness window or the browser refetches it on mount. The RSC
+* QueryClient reads the same constant, so the server dedupe window and the
+* client freshness window cannot drift apart.
+*/
+const HTTP_DEFAULT_STALE_TIME = 3e4;
 /** HTTP client error */
 var HttpClientError = class extends Error {
 	name = "HttpClientError";
@@ -825,12 +857,9 @@ function createRecursiveHttpProxy(opts, path = []) {
 			if (!route) throw new Error(`Unknown HTTP procedure: ${routeKey}`);
 			if (route.method !== "GET") throw new Error(`queryOptions is only available for GET endpoints, got ${route.method} for ${routeKey}`);
 			return (args, queryOpts) => ({
+				staleTime: HTTP_DEFAULT_STALE_TIME,
 				...queryOpts,
-				queryKey: [
-					"httpQuery",
-					routeKey,
-					args
-				],
+				queryKey: buildHttpQueryKey(routeKey, args),
 				queryFn: async () => {
 					try {
 						return await executeHttpRequest({
@@ -849,22 +878,12 @@ function createRecursiveHttpProxy(opts, path = []) {
 				}
 			});
 		}
-		if (prop === "queryKey") return (args) => {
-			return args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0) ? [
-				"httpQuery",
-				routeKey,
-				args
-			] : ["httpQuery", routeKey];
-		};
+		if (prop === "queryKey") return (args) => buildHttpQueryKey(routeKey, args);
 		if (prop === "queryFilter") return (args, filters) => {
 			const hasArgs = args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0);
 			return {
 				...filters,
-				queryKey: hasArgs ? [
-					"httpQuery",
-					routeKey,
-					args
-				] : ["httpQuery", routeKey]
+				queryKey: hasArgs ? buildHttpQueryKey(routeKey, args) : buildHttpQueryPrefixKey(routeKey)
 			};
 		};
 		if (prop === "mutationOptions") {

package/dist/{types-C0Xl7P8K.d.ts → types-BHR7ZKKD.d.ts}

@@ -1,4 +1,4 @@
-import { O as CombinedDataTransformer, n as HttpClientError } from "./http-types-BoSDAh4Y.js";
+import { P as CombinedDataTransformer, r as HttpClientError } from "./http-types-DXOgaerG.js";
 import { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
 
 //#region src/crpc/http-client.d.ts

package/dist/{where-clause-compiler-B_H3oio5.d.ts → where-clause-compiler-DW6jy2er.d.ts}

@@ -3850,7 +3850,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      count: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3860,10 +3860,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "tableKey";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3873,10 +3873,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "indexName";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3886,10 +3886,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      keyHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3899,10 +3899,14 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "keyHash";
         };
       };
-      keyHash: ConvexTextBuilderInitial<""> & {
+      keyParts: ConvexCustomBuilderInitial<"", convex_values0.VArray<any[], convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>, "required">> & {
+        _: {
+          $type: convex_values0.Value[];
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -3912,14 +3916,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyHash";
+          fieldName: "keyParts";
         };
       };
-      keyParts: ConvexCustomBuilderInitial<"", convex_values0.VArray<any[], convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>, "required">> & {
-        _: {
-          $type: convex_values0.Value[];
-        };
-      } & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3929,7 +3929,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyParts";
+          fieldName: "count";
         };
       };
       sumValues: (NotNull<$Type<ConvexCustomBuilderInitial<"", convex_values0.VRecord<Record<string, any>, convex_values0.VString<string, "required">, convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>, "required", string>>, Record<string, number>>> | NotNull<$Type<ConvexCustomBuilderInitial<"", convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>>, Record<string, number>>>) & {
@@ -3972,7 +3972,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "kind";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3982,10 +3982,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3995,10 +3995,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4008,7 +4008,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "updatedAt";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -4142,7 +4142,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "value";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4152,10 +4152,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "tableKey";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4165,10 +4165,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "indexName";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4178,10 +4178,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      keyHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4191,10 +4191,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "keyHash";
         };
       };
-      keyHash: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4204,7 +4204,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyHash";
+          fieldName: "count";
         };
       };
       fieldName: ConvexTextBuilderInitial<""> & {
@@ -4412,19 +4412,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_state";
-        };
-      } & {
-        _: {
-          fieldName: "updatedAt";
-        };
-      };
       tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -4503,6 +4490,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "startedAt";
         };
       };
+      updatedAt: ConvexNumberBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "updatedAt";
+        };
+      };
       completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
@@ -4563,7 +4563,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "direction";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4573,29 +4573,29 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "processed";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "processed";
+          fieldName: "startedAt";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "updatedAt";
         };
       };
       completedAt: ConvexNumberBuilderInitial<""> & {
@@ -4712,7 +4712,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "direction";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4722,10 +4722,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "startedAt";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4735,7 +4735,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "updatedAt";
         };
       };
       completedAt: ConvexNumberBuilderInitial<""> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",

package/skills/kitcn/references/features/http.md

@@ -495,8 +495,18 @@ crpc.http.todos.list.queryOptions({
   searchParams: { limit: "10" },
   headers: { "X-Custom": "value" },
 });
+
+// Override the default 30s staleTime
+crpc.http.todos.list.queryOptions(
+  { searchParams: { limit: "10" } },
+  { staleTime: 0 }
+);
 ```
 
+`queryOptions` defaults to a 30 second `staleTime` so RSC-prefetched entries hydrate
+without an immediate refetch. `refetchOnMount` keeps TanStack's default, so a route
+invalidated while unmounted still refetches.
+
 ### One-Time Fetch
 
 ```ts
@@ -558,6 +568,20 @@ const updateTodo = useMutation(
 );
 ```
 
+### Cache Keys
+
+```ts
+const queryKey = crpc.http.todos.list.queryKey();
+// => ['httpQuery', 'todos.list', {}]
+queryClient.getQueryData(queryKey);
+
+crpc.http.todos.get.queryKey({ params: { id: '123' } });
+// => ['httpQuery', 'todos.get', { params: { id: '123' } }]
+```
+
+`queryKey()` is the exact key `queryOptions()` and RSC prefetching store under, so
+`getQueryData`/`setQueryData` hit. Use `queryFilter()` to match every args variant.
+
 See [Client Methods](#client-methods) in API Reference.
 
 ## RSC Prefetching
@@ -645,4 +669,5 @@ Client args can include `params`, `searchParams`, `form`, custom `fetch`,
 ### Client Methods
 
 Generated clients expose `queryOptions`, `staticQueryOptions`,
-`mutationOptions`, `queryKey`, and `queryFilter`.
+`mutationOptions`, `queryKey` (exact cache key), and `queryFilter` (matches every
+args variant when called without args).

package/skills/kitcn/references/features/ratelimit.md

@@ -81,6 +81,17 @@ For denied reserved fixed-window and token-bucket requests, `reset` is when the
 
 A request larger than every shard's capacity plus finite reservation headroom can never succeed. It returns `reason: 'requestTooLarge'` and `reset: 0` without reading shard state. When only smaller shards cannot serve a request, they are excluded from retry calculations. Fresh, full, and partial snapshot projections preserve permanent denial as `retryAfter: Infinity`, and the React hook reports `ok: false` without scheduling a retry timer. Reduce `count`, reduce `shards`, or raise the configured capacity.
 
+## Protection / deny list — delta from parity
+
+With `enableProtection: true`, failures are counted per identifier, ip, userAgent, and country.
+
+- A value's block is cached for up to 24 h once it reaches `denyListThreshold` **within a rolling 10 minute window**. Failures paced wider than that window decay, so a shared NAT/carrier IP is not blocked by unrelated failures accumulated over days.
+- Protection state is a bounded in-memory LRU. Failure histories are evicted before blocks, active blocks refresh on use, and the coldest block can be evicted above 4,096 simultaneous blocked values per prefix. Evicted values fall through to the database-backed limiter.
+- A success clears the **identifier** counter only. ip/userAgent counters are attacker-supplied; clearing them on success would let a caller loop `threshold - 1` failures plus one success indefinitely, or reset a victim's counter by forging their user-agent.
+- State is module-scope memory: at most 4096 tracked values per prefix with least-recently-hit eviction, and values over 128 characters stored truncated. It is per-isolate, so it does not survive a cold start and is not shared across function entries.
+- Increments are not rolled back when Convex retries a mutation after a write conflict, so a value can count slightly more failures than it was served.
+- `pickDeniedValue` runs before any database read, so a blocked value is rejected without touching `ratelimitState`.
+
 ## Convex constraints
 
 - `blockUntilReady()` needs `setTimeout`, so it only runs in actions or non-Convex runtimes. It throws with that guidance inside queries and mutations. `limit()` and `check()` never touch timers.

package/skills/kitcn/references/features/react.md

@@ -28,7 +28,7 @@ export const { CRPCProvider, useCRPC, useCRPCClient } = createCRPCContext({
 
 ### QueryClient
 
-cRPC auto-sets `staleTime: Infinity`, `refetch*: false` per query (Convex pushes via WebSocket — never stale).
+cRPC auto-sets `staleTime: Infinity`, `refetch*: false` per query (Convex pushes via WebSocket — never stale). `crpc.http.*` routes are pull-model instead: `staleTime: 30_000` with `refetchOnMount` left at TanStack's default, so RSC-prefetched data hydrates but an invalidated route still refetches.
 
 ```ts
 // src/lib/convex/query-client.ts

package/skills/kitcn/references/setup/server.md

@@ -356,7 +356,7 @@ Rate limiting is opt-in: scaffold the full starter once.
 bunx kitcn add ratelimit
 ```
 
-This creates `convex/lib/plugins/ratelimit/schema.ts`, `convex/lib/plugins/ratelimit/plugin.ts`, and registers `ratelimitExtension()` in `convex/functions/schema.ts`.
+This creates `convex/lib/plugins/ratelimit/schema.ts`, `convex/lib/plugins/ratelimit/plugin.ts`, `convex/functions/plugins/ratelimit.ts`, and registers `ratelimitExtension()` in `convex/functions/schema.ts`.
 
 ```ts
 import { defineSchema } from "kitcn/orm";
@@ -365,12 +365,18 @@ import { ratelimitExtension } from "../lib/plugins/ratelimit/schema";
 export default defineSchema(tables).extend(ratelimitExtension());
 ```
 
-Create `convex/lib/plugins/ratelimit/plugin.ts` and call `ratelimit.middleware()` from mutation builders. Use the default bucket for normal writes and reserve `.meta({ ratelimit: ... })` for named overrides. Runtime accounting (`shards`, `check()`, snapshots, read accuracy) lives in `features/ratelimit.md`.
+Create `convex/lib/plugins/ratelimit/plugin.ts` and call `ratelimit.middleware()` from mutation builders. Use the default bucket for normal writes; the starter's `interactive` bucket demonstrates a named `.meta({ ratelimit: ... })` override. Rename or remove it to match the application. Runtime accounting (`shards`, `check()`, snapshots, read accuracy) lives in `features/ratelimit.md`.
 
 Use `RatelimitPlugin` from `kitcn/ratelimit`:
 
 ```ts
-import { MINUTE, Ratelimit, RatelimitPlugin } from "kitcn/ratelimit";
+import {
+  type LimitRequest,
+  MINUTE,
+  Ratelimit,
+  RatelimitPlugin,
+  SECOND,
+} from "kitcn/ratelimit";
 import type { MutationCtx } from "../../../functions/generated/server";
 
 const fixed = (rate: number) => Ratelimit.fixedWindow(rate, MINUTE);
@@ -381,6 +387,11 @@ export const ratelimitBuckets = {
     free: fixed(60),
     premium: fixed(200),
   },
+  interactive: {
+    public: Ratelimit.fixedWindow(3, 30 * SECOND),
+    free: Ratelimit.fixedWindow(3, 30 * SECOND),
+    premium: Ratelimit.fixedWindow(3, 30 * SECOND),
+  },
 } as const;
 
 type RatelimitTier = keyof (typeof ratelimitBuckets)["default"];
@@ -415,14 +426,27 @@ async function getRequestSignals(ctx: RatelimitCtx) {
   };
 }
 
+function getRequestIdentifier(
+  user: RatelimitUser | null,
+  signals: LimitRequest | undefined
+) {
+  if (user) return user.id;
+  return signals?.ip ? `ip:${signals.ip}` : "ip:unknown";
+}
+
 export const ratelimit = RatelimitPlugin.configure({
   buckets: ratelimitBuckets,
   getBucket: ({ meta }: { meta: RatelimitMeta }) => meta.ratelimit ?? "default",
   getUser: ({ ctx }: { ctx: RatelimitCtx }) => ctx.user ?? null,
-  getIdentifier: ({ user }: { user: RatelimitUser | null }) =>
-    user?.id ?? "anonymous",
   getTier: getUserTier,
   getSignals: ({ ctx }: { ctx: RatelimitCtx }) => getRequestSignals(ctx),
+  getIdentifier: ({
+    user,
+    signals,
+  }: {
+    user: RatelimitUser | null;
+    signals: LimitRequest | undefined;
+  }) => getRequestIdentifier(user, signals),
   prefix: ({ bucket, tier }) => `ratelimit:${bucket}:${tier}`,
   failureMode: "closed",
   enableProtection: true,
@@ -432,6 +456,12 @@ export const ratelimit = RatelimitPlugin.configure({
 
 Use `ctx.meta.getRequestMetadata()` on Convex 1.38.0+ for IP/user-agent signals in mutation rate limits. Convex also exposes this metadata in actions; route action-side enforcement through a mutation when database-backed ratelimit state is required.
 
+The identifier is the partition key: every request resolving to the same string shares one budget and one `ratelimitState` document. Never key unauthenticated traffic to a constant — `fixedWindow(30, MINUTE)` under a constant identifier is 30 req/min for the whole deployment, and 30 consecutive denials arm a 24 h deny-list block against that constant. `getSignals` runs once per request, before `getIdentifier`, so keying on `signals.ip` costs no extra syscall.
+
+Plan for the two consequences: shared NAT/CGNAT addresses share a budget, and calls without request metadata all land on `ip:unknown`. One `ratelimitState` row exists per identifier per `bucket:tier`; run the scaffolded `plugins/ratelimit:cleanup` private mutation on demand, with `olderThanMs` longer than every configured rate-limit window, and repeat while it returns `hasMore: true`.
+
+`RatelimitPlugin.configure` also forwards `failureMode`, `timeout`, `enableProtection`, `denyListThreshold`, `denyList`, `dynamicLimits`, and `ephemeralCache` to the limiter.
+
 ### 9.5 Scheduling gate
 
 Create `convex/functions/crons.ts` with `cronJobs()` and use `caller.schedule.now/after/at` in mutations/actions for delayed procedure jobs (`ctx.scheduler.*` only for raw `internal.*` functions).