kitcn 0.23.0 → 0.24.0

package/dist/aggregate/index.d.ts

@@ -1,4 +1,4 @@
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial, dn as ConvexTableWithColumns, tr as ConvexTextBuilderInitial } from "../where-clause-compiler-B_H3oio5.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial, dn as ConvexTableWithColumns, tr as ConvexTextBuilderInitial } from "../where-clause-compiler-DW6jy2er.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";

package/dist/auth/nextjs/index.d.ts

@@ -1,4 +1,4 @@
-import { H as ConvexContext, W as LazyCaller } from "../../procedure-name-C55TynK3.js";
+import { H as ConvexContext, W as LazyCaller } from "../../procedure-name-C20pFZnk.js";
 import { t as GetTokenOptions } from "../../token-B9Bjcqug.js";
 
 //#region src/auth-nextjs/index.d.ts

package/dist/cli.mjs

@@ -2506,7 +2506,7 @@ function QueryProvider({ children }: { children: ReactNode }) {
 const FUNCTIONS_DIR_IMPORT_PLACEHOLDER$5 = "__KITCN_FUNCTIONS_DIR__";
 const PLUGIN_CONFIG_IMPORT_PLACEHOLDER$1 = "__KITCN_PLUGIN_CONFIG_IMPORT__";
 const PLUGIN_SCHEMA_IMPORT_PLACEHOLDER$1 = "__KITCN_PLUGIN_SCHEMA_IMPORT__";
-const PROJECT_CRPC_IMPORT_PLACEHOLDER$3 = "__KITCN_PROJECT_CRPC_IMPORT__";
+const PROJECT_CRPC_IMPORT_PLACEHOLDER$4 = "__KITCN_PROJECT_CRPC_IMPORT__";
 const PROJECT_SHARED_API_IMPORT_PLACEHOLDER = "__KITCN_PROJECT_SHARED_API_IMPORT__";
 const PROJECT_GET_ENV_IMPORT_PLACEHOLDER$2 = "__KITCN_PROJECT_GET_ENV_IMPORT__";
 
@@ -2536,7 +2536,7 @@ const INIT_HTTP_IMPORT_MARKER = "// __KITCN_HTTP_IMPORTS__";
 const INIT_HTTP_ROUTE_MARKER = "  // __KITCN_HTTP_ROUTES__";
 const INIT_HTTP_TEMPLATE = `import { createHttpRouter } from 'kitcn/server';
 import { Hono } from 'hono';
-import { router } from '${PROJECT_CRPC_IMPORT_PLACEHOLDER$3}';
+import { router } from '${PROJECT_CRPC_IMPORT_PLACEHOLDER$4}';
 ${INIT_HTTP_IMPORT_MARKER}
 
 const app = new Hono();
@@ -2849,7 +2849,7 @@ function resolveRelativeImportPath(filePath, targetFilePath) {
 	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
 }
 function renderInitTemplateContent(params) {
-	return params.template.replaceAll(FUNCTIONS_DIR_IMPORT_PLACEHOLDER$5, resolveRelativeImportPath(params.filePath, params.functionsDir)).replaceAll(PROJECT_CRPC_IMPORT_PLACEHOLDER$3, resolveRelativeImportPath(params.filePath, params.crpcFilePath));
+	return params.template.replaceAll(FUNCTIONS_DIR_IMPORT_PLACEHOLDER$5, resolveRelativeImportPath(params.filePath, params.functionsDir)).replaceAll(PROJECT_CRPC_IMPORT_PLACEHOLDER$4, resolveRelativeImportPath(params.filePath, params.crpcFilePath));
 }
 
 //#endregion
@@ -3424,7 +3424,7 @@ const resolvePluginScaffoldFiles = (templates, roots, functionsDir, existingTemp
 	const lockfilePath = normalizeLockfileScaffoldPath(mappedLockfilePath) ?? normalizePath$2(relative(process.cwd(), join(rootDir, template.path)));
 	const filePath = resolve(process.cwd(), lockfilePath);
 	const getEnvImportPath = resolveProjectGetEnvImportPrefix(filePath, roots.envFilePath);
-	const content = template.content.replaceAll(FUNCTIONS_DIR_IMPORT_PLACEHOLDER$5, resolveFunctionsDirImportPrefix(filePath, functionsDir)).replaceAll(PROJECT_CRPC_IMPORT_PLACEHOLDER$3, resolveProjectCrpcImportPrefix(filePath, roots.crpcFilePath)).replaceAll(PROJECT_SHARED_API_IMPORT_PLACEHOLDER, resolveProjectSharedApiImportPrefix(filePath, roots.sharedApiFilePath)).replaceAll(PROJECT_GET_ENV_IMPORT_PLACEHOLDER$2, `import { getEnv } from '${getEnvImportPath}';`).replaceAll(PLUGIN_CONFIG_IMPORT_PLACEHOLDER$1, resolvePluginConfigImportPrefix(filePath, roots.libRootDir)).replaceAll(PLUGIN_SCHEMA_IMPORT_PLACEHOLDER$1, resolvePluginSchemaImportPrefix(filePath, roots.libRootDir));
+	const content = template.content.replaceAll(FUNCTIONS_DIR_IMPORT_PLACEHOLDER$5, resolveFunctionsDirImportPrefix(filePath, functionsDir)).replaceAll(PROJECT_CRPC_IMPORT_PLACEHOLDER$4, resolveProjectCrpcImportPrefix(filePath, roots.crpcFilePath)).replaceAll(PROJECT_SHARED_API_IMPORT_PLACEHOLDER, resolveProjectSharedApiImportPrefix(filePath, roots.sharedApiFilePath)).replaceAll(PROJECT_GET_ENV_IMPORT_PLACEHOLDER$2, `import { getEnv } from '${getEnvImportPath}';`).replaceAll(PLUGIN_CONFIG_IMPORT_PLACEHOLDER$1, resolvePluginConfigImportPrefix(filePath, roots.libRootDir)).replaceAll(PLUGIN_SCHEMA_IMPORT_PLACEHOLDER$1, resolvePluginSchemaImportPrefix(filePath, roots.libRootDir));
 	if (!(descriptor.key === "auth" && preset === "convex") && (template.target === "functions" || template.target === "lib") && content.includes("process.env")) throw new Error(`Scaffold template "${descriptor.key}/${template.id}" contains process.env. Use getEnv() instead.`);
 	return {
 		templateId: template.id,
@@ -6776,10 +6776,46 @@ const authRegistryItem = defineInternalRegistryItem({
 	}
 });
 
+//#endregion
+//#region src/cli/registry/items/ratelimit/ratelimit-functions.template.ts
+const PROJECT_CRPC_IMPORT_PLACEHOLDER$3 = "__KITCN_PROJECT_CRPC_IMPORT__";
+const RATELIMIT_FUNCTIONS_TEMPLATE = `import { cleanupRatelimitState } from "kitcn/ratelimit";
+import { z } from "zod";
+import { privateMutation } from "${PROJECT_CRPC_IMPORT_PLACEHOLDER$3}";
+
+const DEFAULT_BATCH_SIZE = 500;
+
+export const cleanup = privateMutation
+  .input(
+    z.object({
+      olderThanMs: z.number().positive(),
+      limit: z.number().int().min(1).max(1000).optional(),
+    })
+  )
+  .output(
+    z.object({
+      deleted: z.number(),
+      hasMore: z.boolean(),
+    })
+  )
+  .mutation(async ({ ctx, input }) =>
+    cleanupRatelimitState(ctx.db, {
+      before: Date.now() - input.olderThanMs,
+      limit: input.limit ?? DEFAULT_BATCH_SIZE,
+    })
+  );
+`;
+
 //#endregion
 //#region src/cli/registry/items/ratelimit/ratelimit-plugin.template.ts
 const FUNCTIONS_DIR_IMPORT_PLACEHOLDER$4 = "__KITCN_FUNCTIONS_DIR__";
-const RATELIMIT_PLUGIN_TEMPLATE = `import { MINUTE, Ratelimit, RatelimitPlugin } from "kitcn/ratelimit";
+const RATELIMIT_PLUGIN_TEMPLATE = `import {
+  type LimitRequest,
+  MINUTE,
+  Ratelimit,
+  RatelimitPlugin,
+  SECOND,
+} from "kitcn/ratelimit";
 import type { MutationCtx } from "${FUNCTIONS_DIR_IMPORT_PLACEHOLDER$4}/generated/server";
 
 const fixed = (rate: number) => Ratelimit.fixedWindow(rate, MINUTE);
@@ -6790,6 +6826,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"];
@@ -6829,14 +6870,38 @@ async function getRequestSignals(ctx: RatelimitCtx) {
   };
 }
 
+/**
+ * The identifier is the rate-limit partition key: everything that resolves to
+ * the same string shares one budget and one \`ratelimitState\` document.
+ *
+ * Unauthenticated traffic is keyed by request IP so one visitor cannot spend
+ * every other visitor's budget. Calls without request metadata all fall back
+ * to one key.
+ */
+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,
@@ -6869,6 +6934,7 @@ export const ratelimitStateTable = convexTable(
   (t) => [
     index("by_name_key_shard").on(t.name, t.key, t.shard),
     index("by_name_key").on(t.name, t.key),
+    index("by_ts").on(t.ts),
   ],
 );
 
@@ -6909,18 +6975,28 @@ export function ratelimitExtension() {
 
 //#endregion
 //#region src/cli/registry/items/ratelimit/ratelimit-item.ts
-const RATELIMIT_FILES = [createRegistryFile({
-	id: "ratelimit-schema",
-	path: "schema.ts",
-	target: "lib",
-	content: RATELIMIT_SCHEMA_TEMPLATE
-}), createRegistryFile({
-	id: "ratelimit-plugin",
-	path: "plugin.ts",
-	target: "lib",
-	content: RATELIMIT_PLUGIN_TEMPLATE,
-	requires: ["ratelimit-schema"]
-})];
+const RATELIMIT_FILES = [
+	createRegistryFile({
+		id: "ratelimit-schema",
+		path: "schema.ts",
+		target: "lib",
+		content: RATELIMIT_SCHEMA_TEMPLATE
+	}),
+	createRegistryFile({
+		id: "ratelimit-functions",
+		path: "ratelimit.ts",
+		target: "functions",
+		content: RATELIMIT_FUNCTIONS_TEMPLATE,
+		requires: ["ratelimit-schema"]
+	}),
+	createRegistryFile({
+		id: "ratelimit-plugin",
+		path: "plugin.ts",
+		target: "lib",
+		content: RATELIMIT_PLUGIN_TEMPLATE,
+		requires: ["ratelimit-schema"]
+	})
+];
 function buildRatelimitCrpcRegistrationPlanFile(params) {
 	const crpcPath = getCrpcFilePath(params.config);
 	const baselineCrpcSource = renderInitTemplateContent({
@@ -6966,7 +7042,7 @@ const ratelimitRegistryItem = defineInternalRegistryItem({
 		presets: [{
 			name: "server-first",
 			description: "Scaffold a reusable ratelimit plugin and auto-register schema extension.",
-			registryDependencies: ["ratelimit-schema", "ratelimit-plugin"]
+			registryDependencies: RATELIMIT_FILES.map((file) => file.meta.id)
 		}, {
 			name: "schema-only",
 			description: "Only register ratelimit extension in schema.",

package/dist/crpc/index.d.ts

@@ -1,5 +1,5 @@
-import { A as DataTransformer, F as decodeWire, I as defaultCRPCTransformer, L as encodeWire, M as WireCodec, N as createTaggedTransformer, O as CombinedDataTransformer, P as dateWireCodec, R as getTransformer, a as HttpProcedureCall, c as InferHttpInput, i as HttpErrorCode, j as DataTransformerOptions, k as DATE_CODEC_TAG, l as InferHttpOutput, n as HttpClientError, o as HttpRouteInfo, r as HttpClientFromRouter, s as HttpRouteMap, t as HttpClient, u as isHttpClientError, z as identityTransformer } from "../http-types-BoSDAh4Y.js";
-import { A as HttpInputArgs, C as ReservedMutationOptions, D as VanillaMutation, E as VanillaAction, F as replaceUrlParam, M as RESERVED_KEYS, N as buildSearchParams, O as HttpClientOptions, P as executeHttpRequest, S as ReservedInfiniteQueryOptions, T as StaticQueryOptsParam, _ as IsPaginated, a as BaseInfiniteQueryOptsParam, b as PaginatedFnMeta, c as ConvexMutationKey, d as ConvexQueryMeta, f as EmptyObject, g as InfiniteQueryInput, h as FnMeta, i as BaseConvexQueryOptions, j as HttpProxyBaseOptions, k as HttpFormValue, l as ConvexQueryHookOptions, m as FUNC_REF_SYMBOL, n as BaseConvexActionOptions, o as ConvexActionKey, p as ExtractPaginatedItem, r as BaseConvexInfiniteQueryOptions, s as ConvexInfiniteQueryMeta, t as AuthType, u as ConvexQueryKey, v as Meta, w as ReservedQueryOptions, x as PaginationOpts, y as MutationVariables } from "../types-C0Xl7P8K.js";
+import { B as dateWireCodec, F as DATE_CODEC_TAG, G as identityTransformer, H as defaultCRPCTransformer, I as DataTransformer, L as DataTransformerOptions, P as CombinedDataTransformer, R as WireCodec, U as encodeWire, V as decodeWire, W as getTransformer, a as HttpErrorCode, c as HttpQueryKey, d as HttpRouteMap, f as InferHttpInput, g as isHttpClientError, h as buildHttpQueryPrefixKey, i as HttpClientFromRouter, l as HttpQueryPrefixKey, m as buildHttpQueryKey, n as HttpClient, o as HttpMutationKey, p as InferHttpOutput, r as HttpClientError, s as HttpProcedureCall, t as HTTP_DEFAULT_STALE_TIME, u as HttpRouteInfo, z as createTaggedTransformer } from "../http-types-DXOgaerG.js";
+import { A as HttpInputArgs, C as ReservedMutationOptions, D as VanillaMutation, E as VanillaAction, F as replaceUrlParam, M as RESERVED_KEYS, N as buildSearchParams, O as HttpClientOptions, P as executeHttpRequest, S as ReservedInfiniteQueryOptions, T as StaticQueryOptsParam, _ as IsPaginated, a as BaseInfiniteQueryOptsParam, b as PaginatedFnMeta, c as ConvexMutationKey, d as ConvexQueryMeta, f as EmptyObject, g as InfiniteQueryInput, h as FnMeta, i as BaseConvexQueryOptions, j as HttpProxyBaseOptions, k as HttpFormValue, l as ConvexQueryHookOptions, m as FUNC_REF_SYMBOL, n as BaseConvexActionOptions, o as ConvexActionKey, p as ExtractPaginatedItem, r as BaseConvexInfiniteQueryOptions, s as ConvexInfiniteQueryMeta, t as AuthType, u as ConvexQueryKey, v as Meta, w as ReservedQueryOptions, x as PaginationOpts, y as MutationVariables } from "../types-BHR7ZKKD.js";
 import { FunctionArgs, FunctionReference } from "convex/server";
 
 //#region src/crpc/auth-error.d.ts
@@ -102,4 +102,4 @@ declare function convexAction<T extends FunctionReference<'action'>>(funcRef: T,
  */
 declare function convexInfiniteQueryOptions<T extends FunctionReference<'query'>>(funcRef: T, args: Record<string, unknown> | 'skip', opts?: BaseInfiniteQueryOptsParam<T> & Record<string, unknown>, meta?: Meta): BaseConvexInfiniteQueryOptions<T> & Record<string, unknown>;
 //#endregion
-export { AuthMutationError, AuthType, BaseConvexActionOptions, BaseConvexInfiniteQueryOptions, BaseConvexQueryOptions, BaseInfiniteQueryOptsParam, CRPCClientError, CombinedDataTransformer, ConvexActionKey, ConvexInfiniteQueryMeta, ConvexMutationKey, ConvexQueryHookOptions, ConvexQueryKey, ConvexQueryMeta, DATE_CODEC_TAG, DataTransformer, DataTransformerOptions, EmptyObject, ExtractPaginatedItem, FUNC_REF_SYMBOL, FnMeta, HttpClient, HttpClientError, HttpClientFromRouter, HttpClientOptions, HttpErrorCode, HttpFormValue, HttpInputArgs, HttpProcedureCall, HttpProxyBaseOptions, HttpRouteInfo, HttpRouteMap, InferHttpInput, InferHttpOutput, InfiniteQueryInput, IsPaginated, Meta, MutationVariables, PaginatedFnMeta, PaginationOpts, RESERVED_KEYS, ReservedInfiniteQueryOptions, ReservedMutationOptions, ReservedQueryOptions, StaticQueryOptsParam, VanillaAction, VanillaMutation, WireCodec, buildSearchParams, convexAction, convexInfiniteQueryOptions, convexQuery, createTaggedTransformer, dateWireCodec, decodeWire, defaultCRPCTransformer, defaultIsUnauthorized, encodeWire, executeHttpRequest, getTransformer, identityTransformer, isAuthMutationError, isCRPCClientError, isCRPCError, isCRPCErrorCode, isHttpClientError, replaceUrlParam };
+export { AuthMutationError, AuthType, BaseConvexActionOptions, BaseConvexInfiniteQueryOptions, BaseConvexQueryOptions, BaseInfiniteQueryOptsParam, CRPCClientError, CombinedDataTransformer, ConvexActionKey, ConvexInfiniteQueryMeta, ConvexMutationKey, ConvexQueryHookOptions, ConvexQueryKey, ConvexQueryMeta, DATE_CODEC_TAG, DataTransformer, DataTransformerOptions, EmptyObject, ExtractPaginatedItem, FUNC_REF_SYMBOL, FnMeta, HTTP_DEFAULT_STALE_TIME, HttpClient, HttpClientError, HttpClientFromRouter, HttpClientOptions, HttpErrorCode, HttpFormValue, HttpInputArgs, HttpMutationKey, HttpProcedureCall, HttpProxyBaseOptions, HttpQueryKey, HttpQueryPrefixKey, HttpRouteInfo, HttpRouteMap, InferHttpInput, InferHttpOutput, InfiniteQueryInput, IsPaginated, Meta, MutationVariables, PaginatedFnMeta, PaginationOpts, RESERVED_KEYS, ReservedInfiniteQueryOptions, ReservedMutationOptions, ReservedQueryOptions, StaticQueryOptsParam, VanillaAction, VanillaMutation, WireCodec, buildHttpQueryKey, buildHttpQueryPrefixKey, buildSearchParams, convexAction, convexInfiniteQueryOptions, convexQuery, createTaggedTransformer, dateWireCodec, decodeWire, defaultCRPCTransformer, defaultIsUnauthorized, encodeWire, executeHttpRequest, getTransformer, identityTransformer, isAuthMutationError, isCRPCClientError, isCRPCError, isCRPCErrorCode, isHttpClientError, replaceUrlParam };

package/dist/crpc/index.js

@@ -1,6 +1,6 @@
 import { a as isCRPCErrorCode, i as isCRPCError, n as defaultIsUnauthorized, r as isCRPCClientError, t as CRPCClientError } from "../error-Bvo7YEhk.js";
 import { a as defaultCRPCTransformer, c as identityTransformer, i as decodeWire, n as createTaggedTransformer, o as encodeWire, r as dateWireCodec, s as getTransformer, t as DATE_CODEC_TAG } from "../transformer-yZuBWo8v.js";
-import { a as buildSearchParams, c as HttpClientError, i as RESERVED_KEYS, l as isHttpClientError, n as convexInfiniteQueryOptions, o as executeHttpRequest, r as convexQuery, s as replaceUrlParam, t as convexAction } from "../query-options-C_eBSIXG.js";
+import { a as buildSearchParams, c as HTTP_DEFAULT_STALE_TIME, d as buildHttpQueryPrefixKey, f as isHttpClientError, i as RESERVED_KEYS, l as HttpClientError, n as convexInfiniteQueryOptions, o as executeHttpRequest, r as convexQuery, s as replaceUrlParam, t as convexAction, u as buildHttpQueryKey } from "../query-options-CzRV4G4N.js";
 
 //#region src/crpc/auth-error.ts
 /**
@@ -40,4 +40,4 @@ function isAuthMutationError(error) {
 const FUNC_REF_SYMBOL = Symbol.for("convex.funcRef");
 
 //#endregion
-export { AuthMutationError, CRPCClientError, DATE_CODEC_TAG, FUNC_REF_SYMBOL, HttpClientError, RESERVED_KEYS, buildSearchParams, convexAction, convexInfiniteQueryOptions, convexQuery, createTaggedTransformer, dateWireCodec, decodeWire, defaultCRPCTransformer, defaultIsUnauthorized, encodeWire, executeHttpRequest, getTransformer, identityTransformer, isAuthMutationError, isCRPCClientError, isCRPCError, isCRPCErrorCode, isHttpClientError, replaceUrlParam };
+export { AuthMutationError, CRPCClientError, DATE_CODEC_TAG, FUNC_REF_SYMBOL, HTTP_DEFAULT_STALE_TIME, HttpClientError, RESERVED_KEYS, buildHttpQueryKey, buildHttpQueryPrefixKey, buildSearchParams, convexAction, convexInfiniteQueryOptions, convexQuery, createTaggedTransformer, dateWireCodec, decodeWire, defaultCRPCTransformer, defaultIsUnauthorized, encodeWire, executeHttpRequest, getTransformer, identityTransformer, isAuthMutationError, isCRPCClientError, isCRPCError, isCRPCErrorCode, isHttpClientError, replaceUrlParam };

package/dist/{http-types-BoSDAh4Y.d.ts → http-types-DXOgaerG.d.ts}

@@ -261,6 +261,36 @@ type HttpRouteInfo = {
 };
 /** Route map type - from codegen */
 type HttpRouteMap = Record<string, HttpRouteInfo>;
+/** 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];
+/**
+ * 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.
+ */
+declare function buildHttpQueryKey(routeKey: string, args?: unknown): HttpQueryKey;
+/**
+ * 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.
+ */
+declare function buildHttpQueryPrefixKey(routeKey: string): HttpQueryPrefixKey;
+/**
+ * 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.
+ */
+declare const HTTP_DEFAULT_STALE_TIME = 30000;
 /** Infer schema type or return empty object if UnsetMarker */
 type InferSchemaOrEmpty<T> = T extends UnsetMarker ? object : T extends z.ZodTypeAny ? z.infer<T> : object;
 /**
@@ -305,4 +335,4 @@ declare class HttpClientError extends Error {
 /** Type guard for HttpClientError */
 declare const isHttpClientError: (error: unknown) => error is HttpClientError;
 //#endregion
-export { DataTransformer as A, HttpProcedure as C, ProcedureMeta as D, InferHttpInput$1 as E, decodeWire as F, defaultCRPCTransformer as I, encodeWire as L, WireCodec as M, createTaggedTransformer as N, CombinedDataTransformer as O, dateWireCodec as P, getTransformer as R, HttpMethod as S, HttpRouteDefinition as T, extractRouteMap as _, HttpProcedureCall as a, HttpActionHandler as b, InferHttpInput as c, CRPCHttpRouter as d, HttpRouterDef as f, createHttpRouterFactory as g, createHttpRouter as h, HttpErrorCode as i, DataTransformerOptions as j, DATE_CODEC_TAG as k, InferHttpOutput as l, HttpRouterWithHono as m, HttpClientError as n, HttpRouteInfo as o, HttpRouterRecord as p, HttpClientFromRouter as r, HttpRouteMap as s, HttpClient as t, isHttpClientError as u, CRPCHonoHandler as v, HttpProcedureBuilderDef as w, HttpHandlerOpts as x, HttpActionConstructor as y, identityTransformer as z };
+export { HttpProcedureBuilderDef as A, dateWireCodec as B, extractRouteMap as C, HttpHandlerOpts as D, HttpActionHandler as E, DATE_CODEC_TAG as F, identityTransformer as G, defaultCRPCTransformer as H, DataTransformer as I, DataTransformerOptions as L, InferHttpInput$1 as M, ProcedureMeta as N, HttpMethod as O, CombinedDataTransformer as P, WireCodec as R, createHttpRouterFactory as S, HttpActionConstructor as T, encodeWire as U, decodeWire as V, getTransformer as W, CRPCHttpRouter as _, HttpErrorCode as a, HttpRouterWithHono as b, HttpQueryKey as c, HttpRouteMap as d, InferHttpInput as f, isHttpClientError as g, buildHttpQueryPrefixKey as h, HttpClientFromRouter as i, HttpRouteDefinition as j, HttpProcedure as k, HttpQueryPrefixKey as l, buildHttpQueryKey as m, HttpClient as n, HttpMutationKey as o, InferHttpOutput as p, HttpClientError as r, HttpProcedureCall as s, HTTP_DEFAULT_STALE_TIME as t, HttpRouteInfo as u, HttpRouterDef as v, CRPCHonoHandler as w, createHttpRouter as x, HttpRouterRecord as y, createTaggedTransformer as z };

package/dist/orm/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as GenericOrmCtx$1, $n as unique, $r as endsWith, $t as ManyConfig, A as ConvexDateMode, An as ConvexRankIndexBuilder, Ar as ReturningResult, At as MigrationManifestEntry, B as ConvexBytesBuilderInitial, Bn as rankIndex, Br as OrmSchemaRelations, Bt as defineMigration, C as ConvexNumberBuilderInitial, Ci as ColumnBuilderWithTableName, Cn as RlsRole, Cr as MutationReturning, Ct as MigrationStatusArgs, D as id, Di as IsPrimaryKey, Dn as ConvexAggregateIndexBuilderOn, Dr as PaginatedResult, Dt as MigrationDoc, E as ConvexIdBuilderInitial, Ei as HasDefault, En as ConvexAggregateIndexBuilder, Er as OrderDirection, Et as MigrationDirection, F as custom, Fn as ConvexVectorIndexBuilder, Fr as unsetToken, Ft as MigrationStateMap, G as ConvexBigIntBuilder, Gn as ConvexCheckConfig, Gr as ExpressionVisitor, Gt as OrmReader$1, H as ConvexBooleanBuilder, Hn as uniqueIndex, Hr as TableName, Ht as detectMigrationDrift, I as json, In as ConvexVectorIndexBuilderOn, Ir as Brand, It as MigrationStep, J as CountBackfillChunkArgs, Jn as ConvexUniqueConstraintBuilder, Jr as LogicalExpression, Jt as RlsMode, K as ConvexBigIntBuilderInitial, Kn as ConvexForeignKeyBuilder, Kr as FieldReference, Kt as OrmWriter$1, L as objectOf, Ln as ConvexVectorIndexConfig, Lr as Columns, Lt as MigrationTableName, M as ConvexCustomBuilder, Mn as ConvexSearchIndexBuilder, Mr as UpdateSet, Mt as MigrationPlan, N as ConvexCustomBuilderInitial, Nn as ConvexSearchIndexBuilderOn, Nr as VectorQueryConfig, Nt as MigrationRunStatus, O as ConvexDateBuilder, Oi as IsUnique, On as ConvexIndexBuilder, Or as PredicateWhereIndexConfig, Ot as MigrationDocContext, P as arrayOf, Pn as ConvexSearchIndexConfig, Pr as VectorSearchProvider, Pt as MigrationSet, Q as GenericOrm$1, Qn as foreignKey, Qr as contains, Qt as ExtractTablesWithRelations, R as unionOf, Rn as aggregateIndex, Rr as OrmSchemaExtensionTables, Rt as MigrationWriteMode, S as ConvexNumberBuilder, Si as ColumnBuilderTypeConfig, Sn as rlsPolicy, Sr as MutationResult, St as MigrationRunChunkArgs, T as ConvexIdBuilder, Ti as DrizzleEntity, Tn as rlsRole, Tr as OrderByClause, Tt as MigrationDefinition, U as ConvexBooleanBuilderInitial, Un as vectorIndex, Ur as SystemFields, Ut as DatabaseWithMutations, V as bytes, Vn as searchIndex, Vr as OrmSchemaTriggers, Vt as defineMigrationSet, W as boolean, Wn as ConvexCheckBuilder, Wr as BinaryExpression, Wt as DatabaseWithQuery, X as CountBackfillStatusArgs, Xn as ConvexUniqueConstraintConfig, Xr as and, Xt as extractRelationsConfig, Y as CountBackfillKickoffArgs, Yn as ConvexUniqueConstraintBuilderOn, Yr as UnaryExpression, Yt as EdgeMetadata, Z as CreateOrmOptions, Zn as check, Zr as between, Zt as ExtractTablesFromSchema, _ as ConvexTimestampMode, _i as startsWith, _n as deletion, _r as MutationExecuteConfig, _t as OrmTriggerContext, a as requireSchemaRelations, ai as inArray, an as TablesRelationalConfig, ar as AggregateResult, at as OrmWriterCtx, b as ConvexTextEnumBuilderInitial, bi as ColumnBuilderBaseConfig, bn as RlsPolicyConfig, br as MutationPaginateConfig, bt as MigrationCancelArgs, c as TableConfigResult, ci as isNull, cn as ConvexDeletionBuilder, cr as CountConfig, ct as ScheduledMutationBatchArgs, d as OrmNotFoundError, di as lte, dn as ConvexTableWithColumns, dr as FilterOperators, dt as scheduledDeleteFactory, ei as eq, en as OneConfig, er as ConvexTextBuilder, et as OrmApiResult, f as ConvexVectorBuilder, fi as ne, fn as DiscriminatorBuilderConfig, fr as GetColumnData, ft as SchemaExtension, g as ConvexTimestampBuilderInitial, gi as or, gn as convexTable, gr as InsertValue, gt as OrmTriggerChange, h as ConvexTimestampBuilder, hi as notInArray, hn as TableConfig, hr as InferSelectModel, ht as OrmTableTriggers, i as getSchemaTriggers, ii as ilike, in as TableRelationalConfig, ir as AggregateFieldValue, it as OrmReaderCtx, j as date, jn as ConvexRankIndexBuilderOn, jr as ReturningSelection, jt as MigrationMigrateOne, k as ConvexDateBuilderInitial, ki as NotNull, kn as ConvexIndexBuilderOn, kr as ReturningAll, kt as MigrationDriftIssue, l as getTableColumns, li as like, ln as ConvexDeletionConfig, lr as CountResult, lt as scheduledMutationBatchFactory, m as vector, mi as notBetween, mn as OrmLifecycleOperation, mr as InferModelFromColumns, mt as OrmBeforeResult, n as defineSchema, ni as gt, nn as RelationsBuilderColumnBase, nr as text, nt as OrmClientWithApi$1, o as asc, oi as isFieldReference, on as defineRelations, or as BuildQueryResult, ot as ResolveOrmSchema, p as ConvexVectorBuilderInitial, pi as not, pn as OrmLifecycleChange, pr as InferInsertModel, pt as defineSchemaExtension, q as bigint, qn as ConvexForeignKeyConfig, qr as FilterExpression, qt as RlsContext, r as getSchemaRelations, ri as gte, rn as RelationsBuilderColumnConfig, rr as AggregateConfig, rt as OrmFunctions, s as desc, si as isNotNull, sn as defineRelationsPart, sr as BuildRelationResult, st as createOrm, t as WhereClauseResult, ti as fieldRef, tn as RelationsBuilder, tr as ConvexTextBuilderInitial, tt as OrmClientBase$1, u as getTableConfig, ui as lt, un as ConvexTable, ur as DBQueryConfig, ut as ScheduledDeleteArgs, v as timestamp, vi as AnyColumn, vn as discriminator, vr as MutationExecuteResult, vt as OrmTriggers, w as integer, wi as ColumnDataType, wn as RlsRoleConfig, wr as MutationRunMode, wt as MigrationAppliedState, x as textEnum, xi as ColumnBuilderRuntimeConfig, xn as RlsPolicyToOption, xr as MutationPaginatedResult, xt as MigrationRunArgs, y as ConvexTextEnumBuilder, yi as ColumnBuilder, yn as RlsPolicy, yr as MutationExecutionMode, yt as defineTriggers, z as ConvexBytesBuilder, zn as index, zr as OrmSchemaExtensions, zt as buildMigrationPlan } from "../where-clause-compiler-B_H3oio5.js";
+import { $ as GenericOrmCtx$1, $n as unique, $r as endsWith, $t as ManyConfig, A as ConvexDateMode, An as ConvexRankIndexBuilder, Ar as ReturningResult, At as MigrationManifestEntry, B as ConvexBytesBuilderInitial, Bn as rankIndex, Br as OrmSchemaRelations, Bt as defineMigration, C as ConvexNumberBuilderInitial, Ci as ColumnBuilderWithTableName, Cn as RlsRole, Cr as MutationReturning, Ct as MigrationStatusArgs, D as id, Di as IsPrimaryKey, Dn as ConvexAggregateIndexBuilderOn, Dr as PaginatedResult, Dt as MigrationDoc, E as ConvexIdBuilderInitial, Ei as HasDefault, En as ConvexAggregateIndexBuilder, Er as OrderDirection, Et as MigrationDirection, F as custom, Fn as ConvexVectorIndexBuilder, Fr as unsetToken, Ft as MigrationStateMap, G as ConvexBigIntBuilder, Gn as ConvexCheckConfig, Gr as ExpressionVisitor, Gt as OrmReader$1, H as ConvexBooleanBuilder, Hn as uniqueIndex, Hr as TableName, Ht as detectMigrationDrift, I as json, In as ConvexVectorIndexBuilderOn, Ir as Brand, It as MigrationStep, J as CountBackfillChunkArgs, Jn as ConvexUniqueConstraintBuilder, Jr as LogicalExpression, Jt as RlsMode, K as ConvexBigIntBuilderInitial, Kn as ConvexForeignKeyBuilder, Kr as FieldReference, Kt as OrmWriter$1, L as objectOf, Ln as ConvexVectorIndexConfig, Lr as Columns, Lt as MigrationTableName, M as ConvexCustomBuilder, Mn as ConvexSearchIndexBuilder, Mr as UpdateSet, Mt as MigrationPlan, N as ConvexCustomBuilderInitial, Nn as ConvexSearchIndexBuilderOn, Nr as VectorQueryConfig, Nt as MigrationRunStatus, O as ConvexDateBuilder, Oi as IsUnique, On as ConvexIndexBuilder, Or as PredicateWhereIndexConfig, Ot as MigrationDocContext, P as arrayOf, Pn as ConvexSearchIndexConfig, Pr as VectorSearchProvider, Pt as MigrationSet, Q as GenericOrm$1, Qn as foreignKey, Qr as contains, Qt as ExtractTablesWithRelations, R as unionOf, Rn as aggregateIndex, Rr as OrmSchemaExtensionTables, Rt as MigrationWriteMode, S as ConvexNumberBuilder, Si as ColumnBuilderTypeConfig, Sn as rlsPolicy, Sr as MutationResult, St as MigrationRunChunkArgs, T as ConvexIdBuilder, Ti as DrizzleEntity, Tn as rlsRole, Tr as OrderByClause, Tt as MigrationDefinition, U as ConvexBooleanBuilderInitial, Un as vectorIndex, Ur as SystemFields, Ut as DatabaseWithMutations, V as bytes, Vn as searchIndex, Vr as OrmSchemaTriggers, Vt as defineMigrationSet, W as boolean, Wn as ConvexCheckBuilder, Wr as BinaryExpression, Wt as DatabaseWithQuery, X as CountBackfillStatusArgs, Xn as ConvexUniqueConstraintConfig, Xr as and, Xt as extractRelationsConfig, Y as CountBackfillKickoffArgs, Yn as ConvexUniqueConstraintBuilderOn, Yr as UnaryExpression, Yt as EdgeMetadata, Z as CreateOrmOptions, Zn as check, Zr as between, Zt as ExtractTablesFromSchema, _ as ConvexTimestampMode, _i as startsWith, _n as deletion, _r as MutationExecuteConfig, _t as OrmTriggerContext, a as requireSchemaRelations, ai as inArray, an as TablesRelationalConfig, ar as AggregateResult, at as OrmWriterCtx, b as ConvexTextEnumBuilderInitial, bi as ColumnBuilderBaseConfig, bn as RlsPolicyConfig, br as MutationPaginateConfig, bt as MigrationCancelArgs, c as TableConfigResult, ci as isNull, cn as ConvexDeletionBuilder, cr as CountConfig, ct as ScheduledMutationBatchArgs, d as OrmNotFoundError, di as lte, dn as ConvexTableWithColumns, dr as FilterOperators, dt as scheduledDeleteFactory, ei as eq, en as OneConfig, er as ConvexTextBuilder, et as OrmApiResult, f as ConvexVectorBuilder, fi as ne, fn as DiscriminatorBuilderConfig, fr as GetColumnData, ft as SchemaExtension, g as ConvexTimestampBuilderInitial, gi as or, gn as convexTable, gr as InsertValue, gt as OrmTriggerChange, h as ConvexTimestampBuilder, hi as notInArray, hn as TableConfig, hr as InferSelectModel, ht as OrmTableTriggers, i as getSchemaTriggers, ii as ilike, in as TableRelationalConfig, ir as AggregateFieldValue, it as OrmReaderCtx, j as date, jn as ConvexRankIndexBuilderOn, jr as ReturningSelection, jt as MigrationMigrateOne, k as ConvexDateBuilderInitial, ki as NotNull, kn as ConvexIndexBuilderOn, kr as ReturningAll, kt as MigrationDriftIssue, l as getTableColumns, li as like, ln as ConvexDeletionConfig, lr as CountResult, lt as scheduledMutationBatchFactory, m as vector, mi as notBetween, mn as OrmLifecycleOperation, mr as InferModelFromColumns, mt as OrmBeforeResult, n as defineSchema, ni as gt, nn as RelationsBuilderColumnBase, nr as text, nt as OrmClientWithApi$1, o as asc, oi as isFieldReference, on as defineRelations, or as BuildQueryResult, ot as ResolveOrmSchema, p as ConvexVectorBuilderInitial, pi as not, pn as OrmLifecycleChange, pr as InferInsertModel, pt as defineSchemaExtension, q as bigint, qn as ConvexForeignKeyConfig, qr as FilterExpression, qt as RlsContext, r as getSchemaRelations, ri as gte, rn as RelationsBuilderColumnConfig, rr as AggregateConfig, rt as OrmFunctions, s as desc, si as isNotNull, sn as defineRelationsPart, sr as BuildRelationResult, st as createOrm, t as WhereClauseResult, ti as fieldRef, tn as RelationsBuilder, tr as ConvexTextBuilderInitial, tt as OrmClientBase$1, u as getTableConfig, ui as lt, un as ConvexTable, ur as DBQueryConfig, ut as ScheduledDeleteArgs, v as timestamp, vi as AnyColumn, vn as discriminator, vr as MutationExecuteResult, vt as OrmTriggers, w as integer, wi as ColumnDataType, wn as RlsRoleConfig, wr as MutationRunMode, wt as MigrationAppliedState, x as textEnum, xi as ColumnBuilderRuntimeConfig, xn as RlsPolicyToOption, xr as MutationPaginatedResult, xt as MigrationRunArgs, y as ConvexTextEnumBuilder, yi as ColumnBuilder, yn as RlsPolicy, yr as MutationExecutionMode, yt as defineTriggers, z as ConvexBytesBuilder, zn as index, zr as OrmSchemaExtensions, zt as buildMigrationPlan } from "../where-clause-compiler-DW6jy2er.js";
 import { i as pretendRequired, n as deprecated, r as pretend } from "../validators-BhsByJeg.js";
 import { a as QueryCtxWithPreferredOrmQueryTable, i as QueryCtxWithOrmQueryTable, n as LookupByIdResultByCtx, o as getByIdWithOrmQueryFallback, r as QueryCtxWithOptionalOrmQueryTable, t as DocByCtx } from "../query-context-CNo9ffvI.js";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchemaDefinition } from "convex/server";

package/dist/{procedure-name-C55TynK3.d.ts → procedure-name-C20pFZnk.d.ts}

@@ -1,5 +1,5 @@
 import { t as VRequired } from "./validators-BhsByJeg.js";
-import { C as HttpProcedure, D as ProcedureMeta, R as getTransformer, S as HttpMethod, c as InferHttpInput, d as CRPCHttpRouter, j as DataTransformerOptions, l as InferHttpOutput, p as HttpRouterRecord, w as HttpProcedureBuilderDef, x as HttpHandlerOpts } from "./http-types-BoSDAh4Y.js";
+import { A as HttpProcedureBuilderDef, D as HttpHandlerOpts, L as DataTransformerOptions, N as ProcedureMeta, O as HttpMethod, W as getTransformer, _ as CRPCHttpRouter, f as InferHttpInput, k as HttpProcedure, p as InferHttpOutput, y as HttpRouterRecord } from "./http-types-DXOgaerG.js";
 import { g as UnsetMarker, i as IntersectIfDefined, o as MiddlewareBuilder, p as Overwrite$1, s as MiddlewareFunction, t as AnyMiddleware } from "./types-CnTpHR1F.js";
 import { ConvexError, GenericId, GenericValidator, ObjectType, OptionalProperty, PropertyValidators, VAny, VArray, VBoolean, VBytes, VFloat64, VId, VInt64, VLiteral, VNull, VObject, VOptional, VRecord, VString, VUnion, Validator, Value as Value$1 } from "convex/values";
 import { ActionBuilder, ArgsArrayToObject, DefaultFunctionArgs, FunctionReference, FunctionReturnType, FunctionVisibility, GenericActionCtx, GenericDataModel, GenericMutationCtx, GenericQueryCtx, MutationBuilder, QueryBuilder, RegisteredAction, RegisteredMutation, RegisteredQuery, TableNamesInDataModel } from "convex/server";

package/dist/{query-options-C_eBSIXG.js → query-options-CzRV4G4N.js}

@@ -1,6 +1,38 @@
 import { getFunctionName } from "convex/server";
 
 //#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";
@@ -244,4 +276,4 @@ function convexInfiniteQueryOptions(funcRef, args, opts = {}, meta) {
 }
 
 //#endregion
-export { buildSearchParams as a, HttpClientError as c, RESERVED_KEYS as i, isHttpClientError as l, convexInfiniteQueryOptions as n, executeHttpRequest as o, convexQuery as r, replaceUrlParam as s, convexAction as t };
+export { buildSearchParams as a, HTTP_DEFAULT_STALE_TIME as c, buildHttpQueryPrefixKey as d, isHttpClientError as f, RESERVED_KEYS as i, HttpClientError as l, convexInfiniteQueryOptions as n, executeHttpRequest as o, convexQuery as r, replaceUrlParam as s, convexAction as t, buildHttpQueryKey as u };

package/dist/ratelimit/index.d.ts

@@ -127,6 +127,7 @@ type ConvexQueryBuilder = {
   withIndex: (name: any, cb: any) => {
     unique: () => Promise<any>;
     collect: () => Promise<any[]>;
+    take: (limit: number) => Promise<any[]>;
   };
 };
 type ConvexRatelimitDbReader = {
@@ -176,17 +177,36 @@ declare function calculateRatelimit(state: RatelimitState | null, algorithm: Res
  */
 declare function snapshotToState(snapshot: RatelimitSnapshot): RatelimitState;
 //#endregion
+//#region src/ratelimit/maintenance.d.ts
+type CleanupRatelimitStateOptions = {
+  before: number;
+  limit?: number;
+};
+type CleanupRatelimitStateResult = {
+  deleted: number;
+  hasMore: boolean;
+};
+/** Deletes one on-demand batch of state older than the caller-owned cutoff. */
+declare function cleanupRatelimitState(db: ConvexRatelimitDbWriter, options: CleanupRatelimitStateOptions): Promise<CleanupRatelimitStateResult>;
+//#endregion
 //#region src/ratelimit/plugin.d.ts
 type MaybePromise<T> = T | Promise<T>;
 type RatelimitBuckets = Record<string, Record<string, ResolvedAlgorithm>>;
 type BucketName<TBuckets extends RatelimitBuckets> = Extract<keyof TBuckets, string>;
 type TierName<TBuckets extends RatelimitBuckets> = Extract<keyof TBuckets[BucketName<TBuckets>], string>;
-type RatelimitResolvedArgs<TCtx, TMeta extends object, TUser, TBuckets extends RatelimitBuckets> = {
+/** What is known before request signals are resolved. */
+type RatelimitRequestArgs<TCtx, TMeta extends object, TUser, TBuckets extends RatelimitBuckets> = {
   ctx: TCtx;
   meta: TMeta;
   user: TUser;
   bucket: BucketName<TBuckets>;
   tier: TierName<TBuckets>;
+};
+/** Signals are resolved once per request and reused as the identifier input. */
+type RatelimitIdentifierArgs<TCtx, TMeta extends object, TUser, TBuckets extends RatelimitBuckets> = RatelimitRequestArgs<TCtx, TMeta, TUser, TBuckets> & {
+  signals: LimitRequest | undefined;
+};
+type RatelimitResolvedArgs<TCtx, TMeta extends object, TUser, TBuckets extends RatelimitBuckets> = RatelimitIdentifierArgs<TCtx, TMeta, TUser, TBuckets> & {
   identifier: string;
 };
 type RatelimitPluginOptions<TCtx = unknown, TMeta extends object = object, TUser = unknown, TBuckets extends RatelimitBuckets = RatelimitBuckets> = {
@@ -199,18 +219,34 @@ type RatelimitPluginOptions<TCtx = unknown, TMeta extends object = object, TUser
     ctx: TCtx;
     meta: TMeta;
   }) => MaybePromise<TUser>;
-  getIdentifier: (args: {
-    ctx: TCtx;
-    meta: TMeta;
-    user: TUser;
-    bucket: BucketName<TBuckets>;
-  }) => MaybePromise<string>;
   getTier: (user: TUser) => MaybePromise<TierName<TBuckets>>;
-  getSignals: (args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<LimitRequest | undefined>;
+  /**
+   * Resolved once per request, before `getIdentifier`, and reused for the limit
+   * call. Read request metadata here rather than in `getIdentifier`, so a
+   * guarded mutation pays at most one `ctx.meta.getRequestMetadata()` syscall.
+   */
+  getSignals: (args: RatelimitRequestArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<LimitRequest | undefined>;
+  /**
+   * The rate-limit partition key. Everything sharing a value shares one budget
+   * and one `ratelimitState` document, so key unauthenticated traffic by
+   * `signals.ip` rather than a constant.
+   */
+  getIdentifier: (args: RatelimitIdentifierArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<string>;
   prefix?: string | ((args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<string>);
   failureMode?: 'closed' | 'open';
   enableProtection?: boolean;
   denyListThreshold?: number;
+  denyList?: RatelimitConfig['denyList'];
+  dynamicLimits?: boolean;
+  timeout?: number;
+  /**
+   * Block cache backing store. The plugin builds one `Ratelimit` per guarded
+   * mutation, so the default per-instance cache never outlives a request. Pass
+   * a longer-lived `Map` only if you accept that a stale block can deny a
+   * request a refilled shard could have served, and that a mutation replayed
+   * after an OCC conflict can observe entries its first attempt wrote.
+   */
+  ephemeralCache?: RatelimitConfig['ephemeralCache'];
   message?: string | ((args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<string>);
 };
 type AnyRatelimitPluginOptions = RatelimitPluginOptions<any, any, any, any>;
@@ -285,4 +321,4 @@ declare const HOUR: number;
 declare const DAY: number;
 declare const WEEK: number;
 //#endregion
-export { type CheckRequest, type ConvexQueryBuilder, type ConvexRatelimitDbReader, type ConvexRatelimitDbWriter, DAY, type Duration, type DurationString, type DurationUnit, type DynamicLimitResponse, type EvaluationResult, type FixedWindowAlgorithm, HOUR, type HookAPIOptions, type HookCheckValue, type LimitRequest, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, type RatelimitConfig, RatelimitPlugin, type RatelimitPluginOptions, type RatelimitReason, type RatelimitResponse, type RatelimitRow, type RatelimitShardState, type RatelimitSnapshot, type RatelimitState, type RatelimitStoredState, type RemainingResponse, type ResolvedAlgorithm, SECOND, type SlidingWindowAlgorithm, type TokenBucketAlgorithm, WEEK, applyDynamicLimit, calculateRatelimit, fixedWindow, slidingWindow, snapshotToState, toMs, tokenBucket };
+export { type CheckRequest, type CleanupRatelimitStateOptions, type CleanupRatelimitStateResult, type ConvexQueryBuilder, type ConvexRatelimitDbReader, type ConvexRatelimitDbWriter, DAY, type Duration, type DurationString, type DurationUnit, type DynamicLimitResponse, type EvaluationResult, type FixedWindowAlgorithm, HOUR, type HookAPIOptions, type HookCheckValue, type LimitRequest, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, type RatelimitConfig, RatelimitPlugin, type RatelimitPluginOptions, type RatelimitReason, type RatelimitResponse, type RatelimitRow, type RatelimitShardState, type RatelimitSnapshot, type RatelimitState, type RatelimitStoredState, type RemainingResponse, type ResolvedAlgorithm, SECOND, type SlidingWindowAlgorithm, type TokenBucketAlgorithm, WEEK, applyDynamicLimit, calculateRatelimit, cleanupRatelimitState, fixedWindow, slidingWindow, snapshotToState, toMs, tokenBucket };