kitcn 0.14.3 → 0.15.1

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-TMppDl9g.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial, dn as ConvexTableWithColumns, tr as ConvexTextBuilderInitial } from "../where-clause-compiler-DcEhkJ12.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/start/index.d.ts

@@ -2,10 +2,36 @@ import { t as GetTokenOptions } from "../../token-B9Bjcqug.js";
 import { FunctionReference, FunctionReturnType, OptionalRestArgs } from "convex/server";
 
 //#region src/auth-start/index.d.ts
+type MaybePromise<T> = Promise<T> | T;
+type StartLoaderAuthClient = {
+  clearAuth: () => void;
+  setAuth: (fetchToken: () => Promise<string | null>) => void;
+};
+type StartLoaderServerHttpClient = {
+  clearAuth?: () => void;
+  setAuth: (token: string) => void;
+};
+type StartLoaderConvexQueryClient = {
+  convexClient: StartLoaderAuthClient;
+  serverHttpClient?: StartLoaderServerHttpClient;
+};
+type StartLoaderAuthTarget = StartLoaderAuthClient | StartLoaderConvexQueryClient;
+type SyncConvexAuthForStartLoaderOptions = {
+  convex: StartLoaderAuthTarget;
+  getToken: () => MaybePromise<null | string | undefined>;
+};
+type StartLoaderAuthState = {
+  isAuthenticated: boolean;
+  token: null | string;
+};
 type ConvexBetterAuthReactStartOptions = Omit<GetTokenOptions, 'forceRefresh'> & {
   convexSiteUrl: string;
   convexUrl: string;
 };
+declare const syncConvexAuthForStartLoader: ({
+  convex,
+  getToken
+}: SyncConvexAuthForStartLoaderOptions) => Promise<StartLoaderAuthState>;
 declare const convexBetterAuthReactStart: (opts: ConvexBetterAuthReactStartOptions) => {
   getToken: () => Promise<string | undefined>;
   handler: (request: Request) => Promise<Response>;
@@ -14,4 +40,4 @@ declare const convexBetterAuthReactStart: (opts: ConvexBetterAuthReactStartOptio
   fetchAuthAction: <Action extends FunctionReference<"action">>(action: Action, ...args: OptionalRestArgs<Action>) => Promise<FunctionReturnType<Action>>;
 };
 //#endregion
-export { convexBetterAuthReactStart };
+export { MaybePromise, StartLoaderAuthClient, StartLoaderAuthState, StartLoaderAuthTarget, StartLoaderConvexQueryClient, StartLoaderServerHttpClient, SyncConvexAuthForStartLoaderOptions, convexBetterAuthReactStart, syncConvexAuthForStartLoader };

package/dist/auth/start/index.js

@@ -8,6 +8,32 @@ const fallbackCache = (fn) => fn;
 const cache = React.cache ?? fallbackCache;
 const TANSTACK_REACT_START_SERVER = "@tanstack/react-start/server";
 const TRAILING_COLON_RE = /:$/;
+const startLoaderAuthTokens = /* @__PURE__ */ new WeakMap();
+const isStartLoaderConvexQueryClient = (target) => "convexClient" in target;
+const syncConvexAuthForStartLoader = async ({ convex, getToken }) => {
+	const authClient = isStartLoaderConvexQueryClient(convex) ? convex.convexClient : convex;
+	const serverHttpClient = isStartLoaderConvexQueryClient(convex) ? convex.serverHttpClient : void 0;
+	const token = await getToken() ?? null;
+	if (startLoaderAuthTokens.get(convex) === token) return {
+		isAuthenticated: token !== null,
+		token
+	};
+	startLoaderAuthTokens.set(convex, token);
+	if (token === null) {
+		authClient.clearAuth();
+		serverHttpClient?.clearAuth?.();
+		return {
+			isAuthenticated: false,
+			token
+		};
+	}
+	authClient.setAuth(async () => token);
+	serverHttpClient?.setAuth(token);
+	return {
+		isAuthenticated: true,
+		token
+	};
+};
 function setupClient(options) {
 	const client = new ConvexHttpClient(options.convexUrl);
 	if (options.token !== void 0) client.setAuth(options.token);
@@ -124,4 +150,4 @@ const convexBetterAuthReactStart = (opts) => {
 };
 
 //#endregion
-export { convexBetterAuthReactStart };
+export { convexBetterAuthReactStart, syncConvexAuthForStartLoader };

package/dist/{backend-core-cwf87w_T.mjs → backend-core-B091CyHN.mjs}

@@ -5966,7 +5966,16 @@ const syncEnv = pushEnv;
 
 //#endregion
 //#region src/cli/package-manager.ts
-function detectPackageManager(projectDir) {
+function detectPackageManagerFromUserAgent(env = process.env) {
+	const userAgent = env.npm_config_user_agent?.trim().toLowerCase();
+	if (!userAgent) return null;
+	if (userAgent.startsWith("bun/")) return "bun";
+	if (userAgent.startsWith("pnpm/")) return "pnpm";
+	if (userAgent.startsWith("yarn/")) return "yarn";
+	if (userAgent.startsWith("npm/")) return "npm";
+	return null;
+}
+function detectPackageManager(projectDir, env = process.env) {
 	let current = resolve(projectDir);
 	while (true) {
 		const packageJsonPath = join(current, "package.json");
@@ -5987,7 +5996,7 @@ function detectPackageManager(projectDir) {
 		if (parent === current) break;
 		current = parent;
 	}
-	return "bun";
+	return detectPackageManagerFromUserAgent(env) ?? "bun";
 }
 function resolveDependencyInstallCommand(packageManager, packageSpecs) {
 	return {
@@ -6224,7 +6233,7 @@ const EXACT_VERSION_RE = /^(\d+)\.(\d+)\.\d+$/;
 const VERSION_IN_SPEC_RE = /(\d+)\.(\d+)(?:\.\d+)?/;
 const PLAIN_VERSION_SPEC_RE = /^[\^~]?v?\d+\.\d+(?:\.\d+)?$/;
 const UPPER_BOUND_RE = /(?:^|\s)<={0,1}\s*v?(\d+)\.(\d+)(?:\.\d+)?/g;
-const SUPPORTED_CONVEX_VERSION = "1.36.1";
+const SUPPORTED_CONVEX_VERSION = "1.38.0";
 const SUPPORTED_BETTER_AUTH_VERSION = "1.6.9";
 const SUPPORTED_HONO_VERSION = "4.12.9";
 const SUPPORTED_OPENTELEMETRY_API_VERSION = "1.9.0";
@@ -10669,8 +10678,7 @@ const authRegistryItem = defineInternalRegistryItem({
 //#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 { getSessionNetworkSignals } from "kitcn/auth";
-import { MINUTE, Ratelimit, RatelimitPlugin } from "kitcn/ratelimit";
+const RATELIMIT_PLUGIN_TEMPLATE = `import { MINUTE, Ratelimit, RatelimitPlugin } from "kitcn/ratelimit";
 import type { MutationCtx } from "${FUNCTIONS_DIR_IMPORT_PLACEHOLDER$4}/generated/server";
 
 const fixed = (rate: number) => Ratelimit.fixedWindow(rate, MINUTE);
@@ -10711,6 +10719,15 @@ export function getUserTier(user: RatelimitUser | null): RatelimitTier {
   return "free";
 }
 
+async function getRequestSignals(ctx: RatelimitCtx) {
+  const { ip, userAgent } = await ctx.meta.getRequestMetadata();
+
+  return {
+    ...(ip ? { ip } : {}),
+    ...(userAgent ? { userAgent } : {}),
+  };
+}
+
 export const ratelimit = RatelimitPlugin.configure({
   buckets: ratelimitBuckets,
   getBucket: ({ meta }: { meta: RatelimitMeta }) => meta.ratelimit ?? "default",
@@ -10718,7 +10735,7 @@ export const ratelimit = RatelimitPlugin.configure({
   getIdentifier: ({ user }: { user: RatelimitUser | null }) =>
     user?.id ?? "anonymous",
   getTier: getUserTier,
-  getSignals: ({ ctx }: { ctx: RatelimitCtx }) => getSessionNetworkSignals(ctx),
+  getSignals: ({ ctx }: { ctx: RatelimitCtx }) => getRequestSignals(ctx),
   prefix: ({ bucket, tier }) => \`ratelimit:\${bucket}:\${tier}\`,
   failureMode: "closed",
   enableProtection: true,
@@ -15153,7 +15170,6 @@ async function runInitCommandFlow(params) {
 			realConcavePath: params.realConcavePath
 		});
 	}
-	if (existingProjectContext?.framework === "expo") throw new Error("Expo adoption is not supported yet. Start with `kitcn init -t expo --yes`.");
 	if (!existingProjectContext) throw new Error("Could not detect a supported app scaffold. Use `kitcn init -t <next|expo|start|vite>` for a fresh app.");
 	return runScaffoldCommandFlow({
 		allowCodegenBootstrapFallback: !params.initArgs.json,

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as promptForScaffoldTemplateSelection, A as resolveCodegenTrimSegments, At as highlighter, B as runConfiguredCodegen, C as isEntryPoint, Ct as formatDependencyInstallCommand, D as parseInitCommandArgs, E as parseBackendRunJson, Et as stripConvexCommandNoise, F as resolveRunDeps, G as runMigrationFlow, H as runDevSchemaBackfillIfNeeded, I as runAfterScaffoldScript, J as withWorkingDirectory, K as trackProcess, L as runAggregateBackfillFlow, M as resolveDocTopic, N as resolveInitProjectDir, O as readPackageVersions, P as resolveMigrationConfig, Q as promptForPluginSelection, R as runAggregatePruneFlow, S as isConvexDevPreRunConflictFlag, St as detectPackageManager, T as parseArgs, Tt as serializeEnvValue, U as runInitCommandFlow, V as runConvexInitIfNeeded, W as runMigrationCreate, X as collectPluginScaffoldTemplates, Y as createSpinner, Z as filterScaffoldTemplatePathMap, _ as formatInfoOutput, _t as applyPlanningDependencyInstall, a as cleanup, at as getPluginCatalogEntry, b as getDevAggregateBackfillStatePath, bt as resolveSupportedDependencyWarnings, c as createCommandEnv, ct as buildPluginInstallPlan, d as extractBackfillCliOptions, dt as collectInstalledPluginKeys, et as resolveAddTemplateDefaults, f as extractConcaveRunTargetArgs, ft as getPluginLockfilePath, g as formatDocsOutput, gt as applyDependencyHintsInstall, h as extractResetCliOptions, ht as resolveSchemaInstalledPlugins, i as buildInitializationPlan, it as resolveTemplatesByIdOrThrow, j as resolveConfiguredBackend, k as resolveBackfillConfig, kt as logger, l as ensureConvexGitignoreEntry, lt as resolvePluginScaffoldRoots, m as extractMigrationDownOptions, mt as readPluginLockfile, n as applyPluginInstallPlanFiles, nt as resolvePresetScaffoldTemplates, o as createBackendAdapter, ot as getSupportedPluginKeys, p as extractMigrationCliOptions, pt as getSchemaFilePath, q as withLocalCodegenEnv, r as assertNoRemovedDevPreRunFlag, rt as resolveTemplateSelectionSource, s as createBackendCommandEnv, st as isSupportedPluginKey, t as applyDependencyInstallPlan, tt as resolvePluginPreset, u as extractBackendRunTargetArgs, ut as assertSchemaFileExists, v as getAggregateBackfillDeploymentKey, vt as applyPluginDependencyInstall, w as isInitialized, wt as resolveAuthEnvState, x as hasRemoteConvexDeploymentEnv, xt as resolveProjectScaffoldContext, y as getConvexDeploymentCommandEnv, yt as inspectPluginDependencyInstall, z as runBackendFunction } from "./backend-core-cwf87w_T.mjs";
+import { $ as promptForScaffoldTemplateSelection, A as resolveCodegenTrimSegments, At as highlighter, B as runConfiguredCodegen, C as isEntryPoint, Ct as formatDependencyInstallCommand, D as parseInitCommandArgs, E as parseBackendRunJson, Et as stripConvexCommandNoise, F as resolveRunDeps, G as runMigrationFlow, H as runDevSchemaBackfillIfNeeded, I as runAfterScaffoldScript, J as withWorkingDirectory, K as trackProcess, L as runAggregateBackfillFlow, M as resolveDocTopic, N as resolveInitProjectDir, O as readPackageVersions, P as resolveMigrationConfig, Q as promptForPluginSelection, R as runAggregatePruneFlow, S as isConvexDevPreRunConflictFlag, St as detectPackageManager, T as parseArgs, Tt as serializeEnvValue, U as runInitCommandFlow, V as runConvexInitIfNeeded, W as runMigrationCreate, X as collectPluginScaffoldTemplates, Y as createSpinner, Z as filterScaffoldTemplatePathMap, _ as formatInfoOutput, _t as applyPlanningDependencyInstall, a as cleanup, at as getPluginCatalogEntry, b as getDevAggregateBackfillStatePath, bt as resolveSupportedDependencyWarnings, c as createCommandEnv, ct as buildPluginInstallPlan, d as extractBackfillCliOptions, dt as collectInstalledPluginKeys, et as resolveAddTemplateDefaults, f as extractConcaveRunTargetArgs, ft as getPluginLockfilePath, g as formatDocsOutput, gt as applyDependencyHintsInstall, h as extractResetCliOptions, ht as resolveSchemaInstalledPlugins, i as buildInitializationPlan, it as resolveTemplatesByIdOrThrow, j as resolveConfiguredBackend, k as resolveBackfillConfig, kt as logger, l as ensureConvexGitignoreEntry, lt as resolvePluginScaffoldRoots, m as extractMigrationDownOptions, mt as readPluginLockfile, n as applyPluginInstallPlanFiles, nt as resolvePresetScaffoldTemplates, o as createBackendAdapter, ot as getSupportedPluginKeys, p as extractMigrationCliOptions, pt as getSchemaFilePath, q as withLocalCodegenEnv, r as assertNoRemovedDevPreRunFlag, rt as resolveTemplateSelectionSource, s as createBackendCommandEnv, st as isSupportedPluginKey, t as applyDependencyInstallPlan, tt as resolvePluginPreset, u as extractBackendRunTargetArgs, ut as assertSchemaFileExists, v as getAggregateBackfillDeploymentKey, vt as applyPluginDependencyInstall, w as isInitialized, wt as resolveAuthEnvState, x as hasRemoteConvexDeploymentEnv, xt as resolveProjectScaffoldContext, y as getConvexDeploymentCommandEnv, yt as inspectPluginDependencyInstall, z as runBackendFunction } from "./backend-core-B091CyHN.mjs";
 import fs, { existsSync, readFileSync } from "node:fs";
 import path, { delimiter, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

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-TMppDl9g.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-DcEhkJ12.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/watcher.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Dt as generateMeta, F as resolveRunDeps, Ot as getConvexConfig, j as resolveConfiguredBackend, kt as logger, q as withLocalCodegenEnv } from "./backend-core-cwf87w_T.mjs";
+import { Dt as generateMeta, F as resolveRunDeps, Ot as getConvexConfig, j as resolveConfiguredBackend, kt as logger, q as withLocalCodegenEnv } from "./backend-core-B091CyHN.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 

package/dist/{where-clause-compiler-TMppDl9g.d.ts → where-clause-compiler-DcEhkJ12.d.ts}

@@ -3717,7 +3717,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      tableKey: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3727,10 +3727,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "count";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3740,10 +3740,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3753,10 +3753,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "tableKey";
         };
       };
-      keyHash: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3766,14 +3766,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyHash";
+          fieldName: "indexName";
         };
       };
-      keyParts: ConvexCustomBuilderInitial<"", convex_values0.VArray<any[], convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>, "required">> & {
-        _: {
-          $type: convex_values0.Value[];
-        };
-      } & {
+      keyHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3783,10 +3779,14 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyParts";
+          fieldName: "keyHash";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      keyParts: ConvexCustomBuilderInitial<"", convex_values0.VArray<any[], convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>, "required">> & {
+        _: {
+          $type: convex_values0.Value[];
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -3796,7 +3796,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "keyParts";
         };
       };
       sumValues: (NotNull<$Type<ConvexCustomBuilderInitial<"", convex_values0.VRecord<Record<string, any>, convex_values0.VString<string, "required">, convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>, "required", string>>, Record<string, number>>> | NotNull<$Type<ConvexCustomBuilderInitial<"", convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>>, Record<string, number>>>) & {
@@ -3839,7 +3839,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "kind";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3849,10 +3849,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3862,10 +3862,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -3875,7 +3875,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "indexName";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -4009,7 +4009,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "value";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4019,10 +4019,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "count";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4032,10 +4032,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4045,10 +4045,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "tableKey";
         };
       };
-      keyHash: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4058,10 +4058,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyHash";
+          fieldName: "indexName";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      keyHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4071,7 +4071,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "keyHash";
         };
       };
       fieldName: ConvexTextBuilderInitial<""> & {
@@ -4279,6 +4279,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
+      updatedAt: ConvexNumberBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "updatedAt";
+        };
+      };
       tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -4357,19 +4370,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "startedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_state";
-        };
-      } & {
-        _: {
-          fieldName: "updatedAt";
-        };
-      };
       completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
@@ -4429,7 +4429,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "direction";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4439,29 +4439,29 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "processed";
+          fieldName: "updatedAt";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
-          tableName: "migration_state";
+          notNull: true;
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          tableName: "migration_state";
         };
-      };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      } & {
         _: {
-          notNull: true;
+          fieldName: "processed";
         };
-      } & {
+      };
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "startedAt";
         };
       };
       completedAt: ConvexNumberBuilderInitial<""> & {
@@ -4578,7 +4578,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "direction";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4588,10 +4588,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4601,7 +4601,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "startedAt";
         };
       };
       completedAt: ConvexNumberBuilderInitial<""> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.14.3",
+  "version": "0.15.1",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",
@@ -90,7 +90,7 @@
     "@tanstack/react-query": ">=5",
     "@tanstack/solid-query": ">=5",
     "better-auth": "1.6.9",
-    "convex": ">=1.36",
+    "convex": ">=1.38",
     "hono": "4.12.9",
     "next": ">=14",
     "react": ">=18",

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

@@ -370,10 +370,8 @@ Create `convex/lib/plugins/ratelimit/plugin.ts` and call `ratelimit.middleware()
 Use `RatelimitPlugin` from `kitcn/ratelimit`:
 
 ```ts
-import { getSessionNetworkSignals } from "kitcn/auth";
 import { MINUTE, Ratelimit, RatelimitPlugin } from "kitcn/ratelimit";
 import type { MutationCtx } from "../../../functions/generated/server";
-import type { Select } from "../../../shared/api";
 
 const fixed = (rate: number) => Ratelimit.fixedWindow(rate, MINUTE);
 
@@ -392,7 +390,6 @@ type RatelimitUser = {
   id: string;
   isAdmin?: boolean;
   plan?: "premium" | "team" | null;
-  session?: Select<"session"> | null;
 };
 
 type RatelimitCtx = MutationCtx & {
@@ -409,6 +406,15 @@ export function getUserTier(user: RatelimitUser | null): RatelimitTier {
   return "free";
 }
 
+async function getRequestSignals(ctx: RatelimitCtx) {
+  const { ip, userAgent } = await ctx.meta.getRequestMetadata();
+
+  return {
+    ...(ip ? { ip } : {}),
+    ...(userAgent ? { userAgent } : {}),
+  };
+}
+
 export const ratelimit = RatelimitPlugin.configure({
   buckets: ratelimitBuckets,
   getBucket: ({ meta }: { meta: RatelimitMeta }) => meta.ratelimit ?? "default",
@@ -416,13 +422,7 @@ export const ratelimit = RatelimitPlugin.configure({
   getIdentifier: ({ user }: { user: RatelimitUser | null }) =>
     user?.id ?? "anonymous",
   getTier: getUserTier,
-  getSignals: ({
-    ctx,
-    user,
-  }: {
-    ctx: RatelimitCtx;
-    user: RatelimitUser | null;
-  }) => getSessionNetworkSignals(ctx, user?.session ?? null),
+  getSignals: ({ ctx }: { ctx: RatelimitCtx }) => getRequestSignals(ctx),
   prefix: ({ bucket, tier }) => `ratelimit:${bucket}:${tier}`,
   failureMode: "closed",
   enableProtection: true,
@@ -430,6 +430,8 @@ export const ratelimit = RatelimitPlugin.configure({
 });
 ```
 
+Use `ctx.meta.getRequestMetadata()` on Convex 1.38.0+ for IP/user-agent signals in mutation rate limits. Convex also exposes this metadata in actions; route action-side enforcement through a mutation when database-backed ratelimit state is required.
+
 ### 9.5 Scheduling gate
 
 Create `convex/functions/crons.ts` with `cronJobs()` and use `caller.schedule.now/after/at` in mutations/actions for delayed procedure jobs (`ctx.scheduler.*` only for raw `internal.*` functions).

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

@@ -48,6 +48,40 @@ export const {
 });
 ```
 
+For client-side route loaders that fetch protected Convex queries through the
+router `queryClient`, prime the shared Convex client in the root `beforeLoad`
+before child loaders run:
+
+```tsx
+import type { QueryClient } from "@tanstack/react-query";
+import { createRootRouteWithContext } from "@tanstack/react-router";
+import { createServerFn } from "@tanstack/react-start";
+import { syncConvexAuthForStartLoader } from "kitcn/auth/start";
+import type { ConvexQueryClient } from "kitcn/react";
+
+import { getToken } from "@/lib/convex/auth-server";
+
+const getLoaderToken = createServerFn({ method: "GET" }).handler(async () => {
+  return await getToken();
+});
+
+export const Route = createRootRouteWithContext<{
+  convexQueryClient: ConvexQueryClient;
+  queryClient: QueryClient;
+}>()({
+  beforeLoad: async ({ context }) => {
+    return await syncConvexAuthForStartLoader({
+      convex: context.convexQueryClient,
+      getToken: getLoaderToken,
+    });
+  },
+});
+```
+
+Use `runServerCall` or `fetchAuthQuery` for server-side loaders. Use
+`syncConvexAuthForStartLoader` only for client/router loaders that execute
+shared `ConvexQueryClient` queries before `ConvexAuthProvider` mounts.
+
 ### 8.B.2 Auth API endpoint
 
 **Create:** `src/routes/api/auth/$.ts`