kitcn 0.33.5 → 0.33.6

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # kitcn
 
+## 0.33.6
+
+### Patch Changes
+
+- [#473](https://github.com/udecode/kitcn/pull/473) [`16e0bb4`](https://github.com/udecode/kitcn/commit/16e0bb46d66a4d7166d577793fcb47f8161efa5d) Thanks [@EfficiencyCorp](https://github.com/EfficiencyCorp)! - - Add opt-in optimistic auth and document identity admission to
+  `ConvexAuthProvider`, with the same guarded token source for Convex and cRPC
+  HTTP requests.
+  - Add Convex-native `optimisticUpdate` support to cRPC `mutationOptions`.
+  - Reuse the Convex client's logger for server HTTP clients so construction is
+    deterministic during prerendering.
+
 ## 0.33.5
 
 ### Patch Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
 import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-Bxzoofl4.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-qH6-NCM9.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-BzAJnWt4.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/client/index.d.ts

@@ -398,6 +398,51 @@ type ConvexAuthProviderProps = {
     queryName: string;
   }) => void; /** Custom function to detect UNAUTHORIZED errors. Default checks code property. */
   isUnauthorized?: (error: unknown) => boolean;
+  /**
+   * Run auth-bound queries as soon as an unexpired JWT is held instead of
+   * after Convex confirms it. Convex sends them after Authenticate on the same
+   * socket and evaluates none of them if the token is refused; a refused token
+   * sets `isAuthenticated` back to false, which resets auth-bound queries, and
+   * never opens the gate again. Default `false`.
+   */
+  optimisticAuth?: boolean;
+  /**
+   * Fix the identity (JWT `sub` and `sessionId`) the document speaks for: the
+   * one it holds when it mounts (`initialToken`), or, with none, the first
+   * token it obtains. A token for another user or session is refused before
+   * it is cached, so neither Convex, the optimistic gate nor HTTP headers ever
+   * see it: the Convex client is closed (dropping queued requests and
+   * optimistic updates), every later token request answers null, and this is
+   * called, typically to reload the page. Same-session refreshes pass
+   * through. Off when not set.
+   */
+  onTokenIdentityChange?: () => void;
+  /**
+   * The identity (`sub|sessionId`, as the guard decodes it from a JWT) the
+   * document already speaks for when this provider mounts, for an app that
+   * mounts the provider more than once in one document (for example one per
+   * route group, over a shared Convex client). The guard starts from it
+   * instead of from `initialToken` or the first token obtained, so a remount
+   * without a token still refuses another user's or session's token.
+   *
+   * A fixed value is read on the first render only. A getter is read at
+   * every admission, cached tokens included, and a token must match both the
+   * identity it returns and the one this guard already admitted; any
+   * mismatch trips the guard. So a provider kept mounted but hidden (React
+   * `<Activity>`) cannot resume under an identity the document has since
+   * moved away from. A getter returning null does not constrain. Needs
+   * `onTokenIdentityChange`.
+   */
+  tokenIdentityBaseline?: string | null | (() => string | null);
+  /**
+   * Called synchronously with every token the identity guard admits as it is
+   * handed to Convex or HTTP headers, cached tokens included, so the document
+   * can claim the identity at that moment (for example the first token a
+   * document without one obtains). Never called for a refused token. Read
+   * from a ref, so passing a new function does not re-run effects. Needs
+   * `onTokenIdentityChange`.
+   */
+  onTokenIdentityAdmitted?: (token: string) => void;
 };
 /**
  * Unified auth provider for Convex + Better Auth.
@@ -414,7 +459,11 @@ declare function ConvexAuthProvider({
   initialToken,
   onMutationUnauthorized,
   onQueryUnauthorized,
-  isUnauthorized
+  isUnauthorized,
+  optimisticAuth,
+  onTokenIdentityChange,
+  onTokenIdentityAdmitted,
+  tokenIdentityBaseline
 }: ConvexAuthProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { type AuthClient, type AuthClientWithPlugins, ConvexAuthProvider, type ConvexAuthProviderClient, ConvexAuthProviderProps, ConvexAuthProviderQueryClient, type PluginsWithCrossDomain, type PluginsWithoutCrossDomain, convexClient };

package/dist/auth/client/index.js

@@ -134,7 +134,7 @@ const clearSessionAtom = (authClient) => {
 * Structure: AuthProvider wraps ConvexAuthProviderInner so that
 * useAuthStore() is available when creating fetchAccessToken.
 */
-function ConvexAuthProvider({ children, client, authClient, convexQueryClient, initialToken, onMutationUnauthorized, onQueryUnauthorized, isUnauthorized }) {
+function ConvexAuthProvider({ children, client, authClient, convexQueryClient, initialToken, onMutationUnauthorized, onQueryUnauthorized, isUnauthorized, optimisticAuth = false, onTokenIdentityChange, onTokenIdentityAdmitted, tokenIdentityBaseline }) {
 	useOTTHandler(authClient);
 	return /* @__PURE__ */ jsx(AuthProvider, {
 		initialValues: useMemo(() => ({
@@ -148,6 +148,10 @@ function ConvexAuthProvider({ children, client, authClient, convexQueryClient, i
 			authClient,
 			client,
 			convexQueryClient,
+			onTokenIdentityAdmitted,
+			onTokenIdentityChange,
+			optimisticAuth,
+			tokenIdentityBaseline,
 			children
 		})
 	});
@@ -156,7 +160,7 @@ function ConvexAuthProvider({ children, client, authClient, convexQueryClient, i
 * Inner provider that has access to AuthStore via useAuthStore().
 * Creates fetchAccessToken and passes it through context (no race condition).
 */
-function ConvexAuthProviderInner({ children, client, authClient, convexQueryClient }) {
+function ConvexAuthProviderInner({ children, client, authClient, convexQueryClient, optimisticAuth, onTokenIdentityChange, onTokenIdentityAdmitted, tokenIdentityBaseline }) {
 	const authStore = useAuthStore();
 	convexQueryClient?.updateAuthStore(authStore);
 	const { data: session, isPending } = authClient.useSession();
@@ -239,6 +243,25 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 		authStore,
 		authClient
 	]);
+	const onTokenIdentityChangeRef = useRef(onTokenIdentityChange);
+	onTokenIdentityChangeRef.current = onTokenIdentityChange;
+	const onTokenIdentityAdmittedRef = useRef(onTokenIdentityAdmitted);
+	onTokenIdentityAdmittedRef.current = onTokenIdentityAdmitted;
+	const tokenIdentityBaselineRef = useRef(tokenIdentityBaseline);
+	tokenIdentityBaselineRef.current = tokenIdentityBaseline;
+	const identityGuardRef = useRef(null);
+	identityGuardRef.current ??= {
+		identity: (typeof tokenIdentityBaseline === "function" ? null : resolveTokenIdentityBaseline(tokenIdentityBaseline)) ?? decodeTokenSubjectSessionIdentity(authStore.get("token")),
+		currentDocumentIdentity: typeof tokenIdentityBaseline === "function" ? () => resolveTokenIdentityBaseline(tokenIdentityBaselineRef.current) : null,
+		tripped: false
+	};
+	const admitToken = useCallback((token, onAdmitted) => guardTokenIdentity({
+		client,
+		guard: identityGuardRef.current,
+		onAdmitted,
+		onIdentityChange: onTokenIdentityChangeRef.current,
+		token
+	}), [client]);
 	const fetchAccessToken = useCallback(async ({ forceRefreshToken = false } = {}) => {
 		const fetchFreshToken = () => {
 			if (pendingTokenRef.current) return pendingTokenRef.current;
@@ -250,6 +273,7 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 			}
 			pendingTokenRef.current = authClient.convex.token({ fetchOptions }).then((result) => {
 				const jwt = result.data?.token || null;
+				if (jwt && !admitToken(jwt)) return null;
 				if (jwt) {
 					const exp = decodeJwtExp(jwt);
 					authStore.set("token", jwt);
@@ -326,8 +350,15 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 	}, [
 		authStore,
 		authClient,
-		getCachedJwt
+		getCachedJwt,
+		admitToken
 	]);
+	const guardedFetchAccessToken = useCallback(async (args = {}) => {
+		if (identityGuardRef.current?.tripped) return null;
+		const token = await fetchAccessToken(args);
+		if (!token || !admitToken(token, onTokenIdentityAdmittedRef.current)) return null;
+		return token;
+	}, [fetchAccessToken, admitToken]);
 	const useAuth = useCallback(function useConvexAuthHook() {
 		const token = authStore.get("token");
 		const hasSession = hasActiveSessionData(sessionRef.current);
@@ -335,15 +366,18 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 		return {
 			isLoading: isPendingRef.current && !token,
 			isAuthenticated: sessionMissing ? false : hasSession || token !== null,
-			fetchAccessToken
+			fetchAccessToken: guardedFetchAccessToken
 		};
-	}, [fetchAccessToken, authStore]);
+	}, [guardedFetchAccessToken, authStore]);
 	return /* @__PURE__ */ jsx(FetchAccessTokenContext.Provider, {
-		value: fetchAccessToken,
+		value: guardedFetchAccessToken,
 		children: /* @__PURE__ */ jsx(ConvexProviderWithAuth$1, {
 			client,
 			useAuth,
-			children: /* @__PURE__ */ jsx(AuthStateSync, { children })
+			children: /* @__PURE__ */ jsx(AuthStateSync, {
+				optimisticAuth,
+				children
+			})
 		})
 	});
 }
@@ -359,22 +393,102 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 * 5. Without defensive check, we'd sync { isLoading: false, isAuthenticated: false }
 * 6. Queries would throw UNAUTHORIZED before token is validated
 */
-function AuthStateSync({ children }) {
+function AuthStateSync({ children, optimisticAuth = false }) {
 	const { isLoading: convexIsLoading, isAuthenticated } = useConvexAuth();
 	const authStore = useAuthStore();
 	const token = useAuthValue("token");
+	const rejectedTokenRef = useRef(null);
 	useEffect(() => {
-		const isLoading = convexIsLoading || !!token && !isAuthenticated;
-		authStore.set("isLoading", isLoading);
-		authStore.set("isAuthenticated", isAuthenticated);
+		const gate = resolveAuthGate({
+			convexIsLoading,
+			isAuthenticated,
+			optimisticAuth,
+			rejectedToken: rejectedTokenRef.current,
+			token
+		});
+		if (optimisticAuth && isTokenRejectedByConvex({
+			convexIsLoading,
+			isAuthenticated,
+			token
+		})) rejectedTokenRef.current = token;
+		authStore.set("isLoading", gate.isLoading);
+		authStore.set("isAuthenticated", gate.isAuthenticated);
 	}, [
 		convexIsLoading,
 		isAuthenticated,
+		optimisticAuth,
 		token,
 		authStore
 	]);
 	return children;
 }
+function decodeTokenSubjectSessionIdentity(token) {
+	if (!token) return null;
+	try {
+		const segment = token.split(".")[1];
+		if (!segment) return null;
+		const payload = JSON.parse(atob(segment.replaceAll("-", "+").replaceAll("_", "/")));
+		if (typeof payload !== "object" || payload === null) return null;
+		const sub = "sub" in payload ? payload.sub : null;
+		const sessionId = "sessionId" in payload ? payload.sessionId : null;
+		if (typeof sub !== "string") return null;
+		return `${sub}|${typeof sessionId === "string" ? sessionId : ""}`;
+	} catch {
+		return null;
+	}
+}
+function resolveTokenIdentityBaseline(baseline) {
+	return typeof baseline === "function" ? baseline() : baseline ?? null;
+}
+function guardTokenIdentity({ client, guard, onAdmitted, onIdentityChange, token }) {
+	if (!onIdentityChange) return true;
+	if (guard.tripped) return false;
+	const identity = decodeTokenSubjectSessionIdentity(token);
+	if (identity === null) return true;
+	const current = guard.currentDocumentIdentity?.() ?? null;
+	if ((guard.identity === null || guard.identity === identity) && (current === null || current === identity)) {
+		guard.identity = identity;
+		onAdmitted?.(token);
+		return true;
+	}
+	guard.tripped = true;
+	client.close();
+	onIdentityChange();
+	return false;
+}
+/**
+* Convex has settled on "not authenticated" while a token is still held: the
+* server refused it (or refused its refresh).
+*/
+function isTokenRejectedByConvex({ convexIsLoading, isAuthenticated, token }) {
+	return !!token && !convexIsLoading && !isAuthenticated;
+}
+/**
+* The auth state published to the store, which is what every query gate reads.
+*
+* Without `optimisticAuth` this is the confirmed state: queries wait until
+* Convex has confirmed the token. With it, a held, unexpired JWT that Convex
+* has not refused yet counts as authenticated while Convex confirms it, so
+* auth-bound queries subscribe at once; Convex sends them after Authenticate on
+* the same socket, and a refused token closes the socket before any of them is
+* evaluated. When Convex refuses the token, `isAuthenticated` falls back to
+* false, which resets auth-bound queries (see `CRPCProviderInner`).
+*/
+function resolveAuthGate({ convexIsLoading, isAuthenticated, optimisticAuth, rejectedToken, token }) {
+	if (optimisticAuth && convexIsLoading && isOptimisticToken(token, rejectedToken)) return {
+		isAuthenticated: true,
+		isLoading: false
+	};
+	return {
+		isAuthenticated,
+		isLoading: convexIsLoading || !!token && !isAuthenticated
+	};
+}
+function isOptimisticToken(token, rejectedToken) {
+	if (!token || token === rejectedToken) return false;
+	const expiresAt = decodeJwtExp(token);
+	return expiresAt !== null && expiresAt > Date.now();
+}
 /**
 * Handles cross-domain one-time token (OTT) verification.
 */

package/dist/orm/index.d.ts

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

package/dist/orm/migrations/index.d.ts

@@ -1,3 +1,3 @@
 import { C as MigrationStep, D as defineMigration, E as buildMigrationPlan, O as defineMigrationSet, S as MigrationStateMap, T as MigrationWriteMode, _ as MigrationManifestEntry, a as MAX_STATUS_RUN_LIMIT, b as MigrationRunStatus, c as MigrationRunChunkArgs, d as MigrationAppliedState, f as MigrationDefinition, g as MigrationDriftIssue, h as MigrationDocContext, k as detectMigrationDrift, l as MigrationStatusArgs, m as MigrationDoc, o as MigrationCancelArgs, p as MigrationDirection, s as MigrationRunArgs, u as createMigrationHandlers, v as MigrationMigrateOne, w as MigrationTableName, x as MigrationSet, y as MigrationPlan } from "../../capabilities-Bxzoofl4.js";
-import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-qH6-NCM9.js";
+import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-BzAJnWt4.js";
 export { MAX_STATUS_RUN_LIMIT, MIGRATION_RUN_TABLE, MIGRATION_STATE_TABLE, MIGRATION_STORAGE_TABLE_NAMES, type MigrationAppliedState, type MigrationCancelArgs, type MigrationDefinition, type MigrationDirection, type MigrationDoc, type MigrationDocContext, type MigrationDriftIssue, type MigrationManifestEntry, type MigrationMigrateOne, type MigrationPlan, type MigrationRunArgs, type MigrationRunChunkArgs, type MigrationRunStatus, type MigrationSet, type MigrationStateMap, type MigrationStatusArgs, type MigrationStep, type MigrationTableName, type MigrationWriteMode, buildMigrationPlan, createMigrationHandlers, defineMigration, defineMigrationSet, detectMigrationDrift, injectMigrationStorageTables, migrationCapability, migrationExtension, migrationStorageTables };

package/dist/react/index.d.ts

@@ -5,7 +5,8 @@ import { ReactNode } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
 import { DefaultError, QueryCache, QueryClient, QueryFilters, QueryFunction, QueryFunctionContext, QueryKey, SkipToken, UseMutationOptions, UseQueryOptions, UseQueryResult } from "@tanstack/react-query";
-import { ConvexHttpClient } from "convex/browser";
+import { Value } from "convex/values";
+import { ConvexHttpClient, OptimisticUpdate } from "convex/browser";
 import { z } from "zod";
 
 //#region src/crpc/auth-error.d.ts
@@ -582,11 +583,19 @@ type DecorateInfiniteQuery<T extends FunctionReference<'query'>> = {
   infiniteQueryKey: (args?: DeepPartial<InfiniteQueryInput<FunctionArgs<T>>>) => ConvexQueryKey<T>; /** Function metadata from server (auth, limit, rateLimit, role, type) */
   meta: PaginatedFnMeta;
 };
+/**
+ * Convex-native optimistic update for a cRPC mutation. It edits Convex's local
+ * query store, which the query client reads, so Convex rolls it back when the
+ * mutation fails. Args and query values are in their wire shape.
+ */
+type ConvexOptimisticUpdateOption<Args extends Record<string, Value>> = {
+  optimisticUpdate?: OptimisticUpdate<Args>;
+};
 /**
  * Decorated mutation procedure with mutationOptions and mutationKey methods.
  */
 type DecorateMutation<T extends FunctionReference<'mutation'>> = {
-  mutationOptions: (opts?: DistributiveOmit<UseMutationOptions<FunctionReturnType<T>, DefaultError, MutationVariables<T>>, ReservedMutationOptions$2>) => UseMutationOptions<FunctionReturnType<T>, DefaultError, MutationVariables<T>>; /** Get mutation key for QueryClient methods */
+  mutationOptions: (opts?: DistributiveOmit<UseMutationOptions<FunctionReturnType<T>, DefaultError, MutationVariables<T>>, ReservedMutationOptions$2> & ConvexOptimisticUpdateOption<FunctionArgs<T>>) => UseMutationOptions<FunctionReturnType<T>, DefaultError, MutationVariables<T>>; /** Get mutation key for QueryClient methods */
   mutationKey: () => ConvexMutationKey;
 };
 /**
@@ -1087,7 +1096,7 @@ declare function useConvexActionQueryOptions<Action extends FunctionReference<'a
  * }));
  * ```
  */
-declare function useConvexMutationOptions<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, options?: DistributiveOmit<UseMutationOptions<FunctionReturnType<Mutation>, DefaultError, FunctionArgs<Mutation>>, ReservedMutationOptions>, transformer?: DataTransformerOptions): UseMutationOptions<FunctionReturnType<Mutation>, DefaultError, FunctionArgs<Mutation>>;
+declare function useConvexMutationOptions<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, options?: DistributiveOmit<UseMutationOptions<FunctionReturnType<Mutation>, DefaultError, FunctionArgs<Mutation>>, ReservedMutationOptions> & ConvexOptimisticUpdateOption<FunctionArgs<Mutation>>, transformer?: DataTransformerOptions): UseMutationOptions<FunctionReturnType<Mutation>, DefaultError, FunctionArgs<Mutation>>;
 /**
  * Hook that returns action options for use with useMutation.
  * Wraps the Convex action with auth guard logic.

package/dist/react/index.js

@@ -1155,10 +1155,12 @@ function useConvexMutationOptions(mutation, options, transformer) {
 	const name = getFunctionName(mutation);
 	const [namespace, fnName] = name.split(":");
 	const authType = getMeta(namespace, fnName)?.auth;
-	const convexMutation = useMutation(mutation);
+	const { optimisticUpdate, ...mutationOptions } = options ?? {};
+	const reactMutation = useMutation(mutation);
+	const convexMutation = optimisticUpdate ? reactMutation.withOptimisticUpdate(optimisticUpdate) : reactMutation;
 	const resolvedTransformer = getTransformer(transformer);
 	return {
-		...options,
+		...mutationOptions,
 		mutationFn: async (args) => {
 			if (authType === "required" && guard()) throw new CRPCClientError({
 				code: "UNAUTHORIZED",
@@ -1496,6 +1498,16 @@ function createCRPCContext(options) {
 				convexSiteUrl: httpOptions.convexSiteUrl,
 				routes: meta._http,
 				headers: async () => {
+					if (fetchAccessToken) {
+						const expiresAt = authStore.get("expiresAt");
+						const timeRemaining = expiresAt ? expiresAt - Date.now() : 0;
+						const guardedToken = await fetchAccessToken({ forceRefreshToken: !!expiresAt && timeRemaining < 6e4 });
+						const userHeaders = typeof httpOptions.headers === "function" ? await httpOptions.headers() : httpOptions.headers;
+						return guardedToken ? {
+							...userHeaders,
+							Authorization: `Bearer ${guardedToken}`
+						} : { ...userHeaders };
+					}
 					const token = authStore.get("token");
 					const expiresAt = authStore.get("expiresAt");
 					const timeRemaining = expiresAt ? expiresAt - Date.now() : 0;
@@ -1503,13 +1515,6 @@ function createCRPCContext(options) {
 						...typeof httpOptions.headers === "function" ? await httpOptions.headers() : httpOptions.headers,
 						Authorization: `Bearer ${token}`
 					};
-					if (fetchAccessToken) {
-						const newToken = await fetchAccessToken({ forceRefreshToken: !!expiresAt });
-						if (newToken) return {
-							...typeof httpOptions.headers === "function" ? await httpOptions.headers() : httpOptions.headers,
-							Authorization: `Bearer ${newToken}`
-						};
-					}
 					return { ...typeof httpOptions.headers === "function" ? await httpOptions.headers() : httpOptions.headers };
 				},
 				fetch: httpOptions.fetch,
@@ -2105,7 +2110,10 @@ var ConvexQueryClient = class {
 			this._queryClient = options.queryClient;
 			this.unsubscribe = this.subscribeInner(options.queryClient.getQueryCache());
 		}
-		if (isServer) this.serverHttpClient = new ConvexHttpClient(this.convexClient.url, { fetch: options.serverFetch });
+		if (isServer) this.serverHttpClient = new ConvexHttpClient(this.convexClient.url, {
+			fetch: options.serverFetch,
+			logger: this.convexClient.logger
+		});
 	}
 	/**
 	* Connect to TanStack QueryClient.

package/dist/rsc/index.d.ts

@@ -2,7 +2,9 @@ import { n as DeepPartial, o as Simplify, r as DistributiveOmit } from "../types
 import { L as DataTransformerOptions, _ as CRPCHttpRouter, c as HttpQueryKey, k as HttpProcedure, o as HttpMutationKey, y as HttpRouterRecord } from "../http-types-BhhPZtwa.js";
 import { g as UnsetMarker } from "../types-Bkeicpo6.js";
 import { A as HttpInputArgs, C as ReservedMutationOptions$1, S as ReservedInfiniteQueryOptions, T as StaticQueryOptsParam, _ as IsPaginated, b as PaginatedFnMeta, c as ConvexMutationKey, d as ConvexQueryMeta, f as EmptyObject, g as InfiniteQueryInput, l as ConvexQueryHookOptions, m as FUNC_REF_SYMBOL, o as ConvexActionKey, p as ExtractPaginatedItem, s as ConvexInfiniteQueryMeta, u as ConvexQueryKey, w as ReservedQueryOptions$1, y as MutationVariables } from "../types-C7JkpfeY.js";
+import { Value } from "convex/values";
 import { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
+import { OptimisticUpdate } from "convex/browser";
 import { z } from "zod";
 import { DefaultError, QueryFilters, SkipToken, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
 
@@ -70,11 +72,19 @@ type DecorateInfiniteQuery<T extends FunctionReference<'query'>> = {
   infiniteQueryKey: (args?: DeepPartial<InfiniteQueryInput<FunctionArgs<T>>>) => ConvexQueryKey<T>; /** Function metadata from server (auth, limit, rateLimit, role, type) */
   meta: PaginatedFnMeta;
 };
+/**
+ * Convex-native optimistic update for a cRPC mutation. It edits Convex's local
+ * query store, which the query client reads, so Convex rolls it back when the
+ * mutation fails. Args and query values are in their wire shape.
+ */
+type ConvexOptimisticUpdateOption<Args extends Record<string, Value>> = {
+  optimisticUpdate?: OptimisticUpdate<Args>;
+};
 /**
  * Decorated mutation procedure with mutationOptions and mutationKey methods.
  */
 type DecorateMutation<T extends FunctionReference<'mutation'>> = {
-  mutationOptions: (opts?: DistributiveOmit<UseMutationOptions<FunctionReturnType<T>, DefaultError, MutationVariables<T>>, ReservedMutationOptions$1>) => UseMutationOptions<FunctionReturnType<T>, DefaultError, MutationVariables<T>>; /** Get mutation key for QueryClient methods */
+  mutationOptions: (opts?: DistributiveOmit<UseMutationOptions<FunctionReturnType<T>, DefaultError, MutationVariables<T>>, ReservedMutationOptions$1> & ConvexOptimisticUpdateOption<FunctionArgs<T>>) => UseMutationOptions<FunctionReturnType<T>, DefaultError, MutationVariables<T>>; /** Get mutation key for QueryClient methods */
   mutationKey: () => ConvexMutationKey;
 };
 /**

package/dist/{where-clause-compiler-qH6-NCM9.d.ts → where-clause-compiler-BzAJnWt4.d.ts}

@@ -120,7 +120,7 @@ declare const migrationStorageTables: {
           fieldName: "cursor";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
+      migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -130,19 +130,23 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "processed";
+          fieldName: "migrationId";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      checksum: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "checksum";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      applied: ConvexBooleanBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -152,41 +156,41 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "applied";
         };
       };
-      completedAt: ConvexNumberBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "completedAt";
+          fieldName: "runId";
         };
       };
-      lastError: ConvexTextBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
-          tableName: "migration_state";
+          notNull: true;
         };
       } & {
         _: {
-          fieldName: "lastError";
+          tableName: "migration_state";
         };
-      };
-      migrationId: ConvexTextBuilderInitial<""> & {
+      } & {
         _: {
-          notNull: true;
+          fieldName: "processed";
         };
-      } & {
+      };
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "migrationId";
+          fieldName: "startedAt";
         };
       };
-      checksum: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -196,29 +200,25 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "checksum";
+          fieldName: "updatedAt";
         };
       };
-      applied: ConvexBooleanBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "applied";
+          fieldName: "completedAt";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "lastError";
         };
       };
       writeMode: ConvexTextBuilderInitial<""> & {
@@ -269,6 +269,19 @@ declare const migrationStorageTables: {
           fieldName: "direction";
         };
       };
+      runId: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "migration_run";
+        };
+      } & {
+        _: {
+          fieldName: "runId";
+        };
+      };
       startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -313,19 +326,6 @@ declare const migrationStorageTables: {
           fieldName: "lastError";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "migration_run";
-        };
-      } & {
-        _: {
-          fieldName: "runId";
-        };
-      };
       dryRun: ConvexBooleanBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1011,7 +1011,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      indexName: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1021,7 +1021,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "count";
         };
       };
       updatedAt: ConvexNumberBuilderInitial<""> & {
@@ -1037,7 +1037,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1047,10 +1047,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1060,7 +1060,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "tableKey";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1149,7 +1149,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "kind";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1159,10 +1159,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1172,7 +1172,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "indexName";
         };
       };
       tableKey: ConvexTextBuilderInitial<""> & {
@@ -1343,7 +1343,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "value";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1353,7 +1353,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "count";
         };
       };
       updatedAt: ConvexNumberBuilderInitial<""> & {
@@ -1369,7 +1369,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1379,10 +1379,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1392,7 +1392,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "tableKey";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1618,7 +1618,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1628,10 +1628,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "processed";
         };
       };
-      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1641,10 +1641,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyDefinitionHash";
+          fieldName: "startedAt";
         };
       };
-      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1654,23 +1654,28 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "metricDefinitionHash";
+          fieldName: "updatedAt";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
+      completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
-          notNull: true;
+          tableName: "aggregate_state";
         };
       } & {
+        _: {
+          fieldName: "completedAt";
+        };
+      };
+      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
         };
       } & {
         _: {
-          fieldName: "processed";
+          fieldName: "lastError";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1680,10 +1685,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "indexName";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1693,25 +1698,20 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "keyDefinitionHash";
         };
       };
-      completedAt: ConvexNumberBuilderInitial<""> & {
+      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
-          tableName: "aggregate_state";
+          notNull: true;
         };
       } & {
-        _: {
-          fieldName: "completedAt";
-        };
-      };
-      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
         };
       } & {
         _: {
-          fieldName: "lastError";
+          fieldName: "metricDefinitionHash";
         };
       };
       tableKey: ConvexTextBuilderInitial<""> & {
@@ -1769,7 +1769,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
+      migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1779,19 +1779,23 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "processed";
+          fieldName: "migrationId";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      checksum: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "checksum";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      applied: ConvexBooleanBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1801,41 +1805,41 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "applied";
         };
       };
-      completedAt: ConvexNumberBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "completedAt";
+          fieldName: "runId";
         };
       };
-      lastError: ConvexTextBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
-          tableName: "migration_state";
+          notNull: true;
         };
       } & {
         _: {
-          fieldName: "lastError";
+          tableName: "migration_state";
         };
-      };
-      migrationId: ConvexTextBuilderInitial<""> & {
+      } & {
         _: {
-          notNull: true;
+          fieldName: "processed";
         };
-      } & {
+      };
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "migrationId";
+          fieldName: "startedAt";
         };
       };
-      checksum: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1845,29 +1849,25 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "checksum";
+          fieldName: "updatedAt";
         };
       };
-      applied: ConvexBooleanBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "applied";
+          fieldName: "completedAt";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "lastError";
         };
       };
       writeMode: ConvexTextBuilderInitial<""> & {
@@ -1918,6 +1918,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "direction";
         };
       };
+      runId: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "migration_run";
+        };
+      } & {
+        _: {
+          fieldName: "runId";
+        };
+      };
       startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1962,19 +1975,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "lastError";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "migration_run";
-        };
-      } & {
-        _: {
-          fieldName: "runId";
-        };
-      };
       dryRun: ConvexBooleanBuilderInitial<""> & {
         _: {
           notNull: true;

package/package.json

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

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

@@ -406,11 +406,26 @@ All from `kitcn/react`:
   authClient={authClient}
   convexQueryClient={convexQueryClient} // when using TanStack Query
   initialToken={token}           // from SSR (caller.getToken())
+  optimisticAuth                 // opt in: open gates while Convex confirms a held JWT
+  onTokenIdentityChange={() => window.location.reload()}
   onMutationUnauthorized={() => router.push('/login')}
   onQueryUnauthorized={({ queryName }) => console.log(`Unauth: ${queryName}`)}
 >
 ```
 
+`optimisticAuth` only opens auth-bound query gates for a held, unexpired JWT;
+expired, opaque, and refused tokens stay closed. Enable
+`onTokenIdentityChange` to refuse a JWT whose `sub` or `sessionId` differs from
+the document identity before Convex or HTTP sees it. The client closes before
+the callback runs, so reload the document there.
+
+For multiple provider mounts, pass `tokenIdentityBaseline` as
+`sub|sessionId`, or a getter returning the document's current identity. The
+getter is checked for every admission, cached tokens included.
+`onTokenIdentityAdmitted(token)` observes admitted JWTs so the app can update
+that shared baseline. All three identity options require
+`onTokenIdentityChange`.
+
 For `@convex-dev/auth` (React Native):
 ```tsx
 import { ConvexProviderWithAuth } from 'kitcn/react';

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

@@ -298,6 +298,22 @@ const mutation = useMutation(crpc.user.update.mutationOptions({
 
 Signature: `crpc.path.mutationOptions(options?)` — standard TanStack mutation options except `mutationFn`.
 
+Pass `optimisticUpdate(localStore, args)` to use Convex's optimistic local
+query store. This option is removed before the TanStack options are returned;
+Convex replays it as query data changes and owns rollback when the mutation
+completes.
+
+```ts
+const mutation = useMutation(crpc.todos.rename.mutationOptions({
+  optimisticUpdate: (store, args) => {
+    const todos = store.getQuery(api.todos.list, {});
+    if (todos) store.setQuery(api.todos.list, {}, todos.map((todo) =>
+      todo._id === args.id ? { ...todo, title: args.title } : todo
+    ));
+  },
+}));
+```
+
 ### Mutation Keys
 
 ```ts