kitcn 0.33.7 → 0.33.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # kitcn
 
+## 0.33.8
+
+### Patch Changes
+
+- [#478](https://github.com/udecode/kitcn/pull/478) [`03b1ad1`](https://github.com/udecode/kitcn/commit/03b1ad1bd72333ce3867f79d8f079193cf77c170) Thanks [@zbeyens](https://github.com/zbeyens)! - ## Patches
+
+  - Support app-owned synchronous or asynchronous JWT cache clocks for Next.js partial prefetching and private-cache rendering.
+
 ## 0.33.7
 
 ### 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-DAqhUREe.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-CTblNxLo.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/generated/index.d.ts

@@ -1,2 +1,2 @@
-import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, b as GenericAuthBeforeResult, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../../generated-contract-disabled-QZXEzUnd.js";
+import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, b as GenericAuthBeforeResult, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../../generated-contract-disabled-CFLQf8Wg.js";
 export { type AuthRuntime, BetterAuthOptionsWithoutDatabase, type GeneratedAuthDisabledReasonKind, GenericAuthBeforeResult, GenericAuthDefinition, GenericAuthTriggerChange, GenericAuthTriggerHandlers, GenericAuthTriggers, createDisabledAuthRuntime, defineAuth, getGeneratedAuthDisabledReason };

package/dist/auth/index.d.ts

@@ -1,7 +1,7 @@
 import { a as QueryCtxWithPreferredOrmQueryTable, n as LookupByIdResultByCtx, t as DocByCtx } from "../query-context-BkNjkDCk.js";
 import { t as GetAuth } from "../types-ex0-J-SC.js";
 import { t as GenericCtx } from "../context-utils-Cbv4r0AA.js";
-import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, _ as updateManyHandler, a as AuthFunctions, b as GenericAuthBeforeResult, c as consumeOneHandler, d as createHandler, f as deleteManyHandler, g as incrementOneHandler, h as findOneHandler, i as getGeneratedAuthDisabledReason, l as countHandler, m as findManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as deleteOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as createApi, v as updateOneHandler, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../generated-contract-disabled-QZXEzUnd.js";
+import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, _ as updateManyHandler, a as AuthFunctions, b as GenericAuthBeforeResult, c as consumeOneHandler, d as createHandler, f as deleteManyHandler, g as incrementOneHandler, h as findOneHandler, i as getGeneratedAuthDisabledReason, l as countHandler, m as findManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as deleteOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as createApi, v as updateOneHandler, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../generated-contract-disabled-CFLQf8Wg.js";
 import * as convex_values0 from "convex/values";
 import { Infer } from "convex/values";
 import { AuthConfig, DocumentByName, GenericDataModel, GenericMutationCtx, GenericQueryCtx, GenericSchema, PaginationOptions, PaginationResult, SchemaDefinition, TableNamesInDataModel } from "convex/server";
@@ -132,8 +132,8 @@ declare const adapterArgsValidator: convex_values0.VObject<{
   select?: string[] | undefined;
   offset?: number | undefined;
   sortBy?: {
-    direction: "asc" | "desc";
     field: string;
+    direction: "asc" | "desc";
   } | undefined;
   model: string;
 }, {
@@ -142,12 +142,12 @@ declare const adapterArgsValidator: convex_values0.VObject<{
   offset: convex_values0.VFloat64<number | undefined, "optional">;
   select: convex_values0.VArray<string[] | undefined, convex_values0.VString<string, "required">, "optional">;
   sortBy: convex_values0.VObject<{
-    direction: "asc" | "desc";
     field: string;
+    direction: "asc" | "desc";
   } | undefined, {
     direction: convex_values0.VUnion<"asc" | "desc", [convex_values0.VLiteral<"asc", "required">, convex_values0.VLiteral<"desc", "required">], "required", never>;
     field: convex_values0.VString<string, "required">;
-  }, "optional", "direction" | "field">;
+  }, "optional", "field" | "direction">;
   where: convex_values0.VArray<{
     mode?: "sensitive" | "insensitive" | undefined;
     operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
@@ -167,7 +167,7 @@ declare const adapterArgsValidator: convex_values0.VObject<{
     operator: convex_values0.VUnion<"eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
     value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
   }, "required", "mode" | "operator" | "value" | "field" | "connector">, "optional">;
-}, "required", "limit" | "where" | "model" | "select" | "offset" | "sortBy" | "sortBy.direction" | "sortBy.field">;
+}, "required", "limit" | "where" | "model" | "select" | "offset" | "sortBy" | "sortBy.field" | "sortBy.direction">;
 declare const hasUniqueFields: (betterAuthSchema: BetterAuthDBSchema, model: string, input: Record<string, any>) => boolean;
 declare const checkUniqueFields: <Schema extends SchemaDefinition<any, any>>(ctx: GenericQueryCtx<GenericDataModel>, schema: Schema, betterAuthSchema: BetterAuthDBSchema, table: string, input: Record<string, any>, doc?: Record<string, any>) => Promise<void>;
 declare const selectFields: <T extends TableNamesInDataModel<GenericDataModel>, D extends DocumentByName<GenericDataModel, T>>(doc: D | null, select?: string[]) => D | null;

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

@@ -1,11 +1,11 @@
 import { H as ConvexContext, W as LazyCaller } from "../../procedure-name-DRSOwAJY.js";
-import { t as GetTokenOptions } from "../../token-tlbNKQS0.js";
+import { t as GetTokenOptions } from "../../token-COZD00dG.js";
 
 //#region src/auth-nextjs/index.d.ts
 /** Auth options for server-side calls. */
 type AuthOptions = {
-  /** Better Auth auth route base path. Defaults to `/api/auth`. */basePath?: string; /** Enable/disable JWT caching. Default: true */
-  jwtCache?: boolean; /** Custom function to detect UNAUTHORIZED errors. Default checks code property. */
+  /** Better Auth auth route base path. Defaults to `/api/auth`. */basePath?: string; /** Enable/disable JWT caching or provide a Unix-seconds clock. Default: true. */
+  jwtCache?: boolean | Pick<NonNullable<GetTokenOptions['jwtCache']>, 'now'>; /** Custom function to detect UNAUTHORIZED errors. Default checks code property. */
   isUnauthorized?: (error: unknown) => boolean; /** Expiration tolerance in seconds. */
   expirationToleranceSeconds?: number;
 };

package/dist/auth/nextjs/index.js

@@ -1,4 +1,4 @@
-import { t as getToken } from "../../token-CgIvcEZX.js";
+import { t as getToken } from "../../token-CZbuEcTL.js";
 import { n as defaultIsUnauthorized } from "../../error-CLgc9khF.js";
 import { t as createCallerFactory } from "../../caller-factory-CEKbQdGY.js";
 
@@ -80,7 +80,8 @@ function convexBetterAuth(opts) {
 					jwtCache: {
 						enabled: jwtCacheEnabled,
 						expirationToleranceSeconds: auth.expirationToleranceSeconds,
-						isAuthError: auth.isUnauthorized ?? defaultIsUnauthorized
+						isAuthError: auth.isUnauthorized ?? defaultIsUnauthorized,
+						now: typeof auth.jwtCache === "object" ? auth.jwtCache.now : void 0
 					}
 				});
 			},

package/dist/auth/start/server/index.d.ts

@@ -1,5 +1,5 @@
 import { H as ConvexContext, W as LazyCaller } from "../../../procedure-name-DRSOwAJY.js";
-import { t as GetTokenOptions } from "../../../token-tlbNKQS0.js";
+import { t as GetTokenOptions } from "../../../token-COZD00dG.js";
 import { FunctionReference, FunctionReturnType, OptionalRestArgs } from "convex/server";
 
 //#region src/auth-start/server.d.ts

package/dist/auth/start/server/index.js

@@ -1,4 +1,4 @@
-import { t as getToken } from "../../../token-CgIvcEZX.js";
+import { t as getToken } from "../../../token-CZbuEcTL.js";
 import { n as defaultIsUnauthorized } from "../../../error-CLgc9khF.js";
 import { t as createCallerFactory } from "../../../caller-factory-CEKbQdGY.js";
 import { stripIndent } from "common-tags";

package/dist/{generated-contract-disabled-QZXEzUnd.d.ts → generated-contract-disabled-CFLQf8Wg.d.ts}

@@ -289,8 +289,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
     }[] | undefined;
     offset?: number | undefined;
     sortBy?: {
-      direction: "asc" | "desc";
       field: string;
+      direction: "asc" | "desc";
     } | undefined;
     paginationOpts: {
       id?: number;

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-DAqhUREe.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-CTblNxLo.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-DAqhUREe.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-CTblNxLo.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/{token-tlbNKQS0.d.ts → token-COZD00dG.d.ts}

@@ -6,7 +6,8 @@ type GetTokenOptions = {
   jwtCache?: {
     enabled: boolean;
     expirationToleranceSeconds?: number;
-    isAuthError: (error: unknown) => boolean;
+    isAuthError: (error: unknown) => boolean; /** Current Unix time in seconds. Defaults to the system clock. */
+    now?: () => number | Promise<number>;
   };
 };
 //#endregion

package/dist/{token-CgIvcEZX.js → token-CZbuEcTL.js}

@@ -32,14 +32,23 @@ const getToken = async (siteUrl, headers, opts) => {
 		cookiePrefix: opts?.cookiePrefix
 	});
 	if (!token) return await fetchToken();
+	let claims;
 	try {
-		if (!isTokenExpired(jose.decodeJwt(token)?.exp, opts?.jwtCache?.expirationToleranceSeconds ?? 60)) return {
-			isFresh: false,
-			token
-		};
+		claims = jose.decodeJwt(token);
 	} catch (error) {
 		console.error("Error decoding JWT", error);
+		return await fetchToken();
+	}
+	if (!claims.exp) return await fetchToken();
+	let now;
+	if (opts.jwtCache.now) {
+		now = await opts.jwtCache.now();
+		if (!Number.isFinite(now)) throw new RangeError("JWT cache now must return finite Unix time in seconds");
 	}
+	if (!isTokenExpired(claims.exp, opts.jwtCache.expirationToleranceSeconds ?? 60, now)) return {
+		isFresh: false,
+		token
+	};
 	return await fetchToken();
 };
 

package/dist/{where-clause-compiler-DAqhUREe.d.ts → where-clause-compiler-CTblNxLo.d.ts}

@@ -111,29 +111,29 @@ declare const migrationStorageTables: {
           fieldName: "cursor";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "processed";
+          fieldName: "direction";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      migrationId: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "migrationId";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      checksum: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -143,28 +143,32 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "checksum";
         };
       };
-      completedAt: ConvexNumberBuilderInitial<""> & {
+      applied: ConvexBooleanBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "completedAt";
+          fieldName: "applied";
         };
       };
-      lastError: ConvexTextBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "lastError";
+          fieldName: "runId";
         };
       };
-      migrationId: ConvexTextBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -174,23 +178,19 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "migrationId";
+          fieldName: "processed";
         };
       };
-      checksum: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "checksum";
+          fieldName: "startedAt";
         };
       };
-      applied: ConvexBooleanBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -200,25 +200,25 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "applied";
+          fieldName: "updatedAt";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "completedAt";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "lastError";
         };
       };
       writeMode: ConvexTextBuilderInitial<""> & {
@@ -256,7 +256,7 @@ declare const migrationStorageTables: {
           fieldName: "status";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -266,10 +266,10 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "direction";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -279,28 +279,23 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "runId";
         };
       };
-      completedAt: ConvexNumberBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
-          tableName: "migration_run";
+          notNull: true;
         };
       } & {
-        _: {
-          fieldName: "completedAt";
-        };
-      };
-      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_run";
         };
       } & {
         _: {
-          fieldName: "lastError";
+          fieldName: "startedAt";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -310,20 +305,25 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "updatedAt";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
-          notNull: true;
+          tableName: "migration_run";
         };
       } & {
+        _: {
+          fieldName: "completedAt";
+        };
+      };
+      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_run";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "lastError";
         };
       };
       dryRun: ConvexBooleanBuilderInitial<""> & {
@@ -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<""> & {
@@ -1326,7 +1326,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_extrema: ConvexTableWithColumns<{
     name: "aggregate_extrema";
     columns: {
-      indexName: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1336,10 +1336,14 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "count";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
+        _: {
+          $type: convex_values0.Value;
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -1349,10 +1353,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "value";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1362,10 +1366,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "updatedAt";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1375,14 +1379,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "indexName";
         };
       };
-      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
-        _: {
-          $type: convex_values0.Value;
-        };
-      } & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1392,7 +1392,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "value";
+          fieldName: "tableKey";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1596,6 +1596,15 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
+      cursor: ConvexTextBuilderInitial<""> & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "cursor";
+        };
+      };
       kind: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1609,7 +1618,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "kind";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1619,10 +1628,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "processed";
         };
       };
-      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1632,10 +1641,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyDefinitionHash";
+          fieldName: "startedAt";
         };
       };
-      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1645,32 +1654,28 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "metricDefinitionHash";
+          fieldName: "updatedAt";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "completedAt";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      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<""> & {
@@ -1760,29 +1760,29 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "processed";
+          fieldName: "direction";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      migrationId: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "migrationId";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      checksum: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1792,28 +1792,32 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "checksum";
         };
       };
-      completedAt: ConvexNumberBuilderInitial<""> & {
+      applied: ConvexBooleanBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "completedAt";
+          fieldName: "applied";
         };
       };
-      lastError: ConvexTextBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "lastError";
+          fieldName: "runId";
         };
       };
-      migrationId: ConvexTextBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1823,23 +1827,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "migrationId";
+          fieldName: "processed";
         };
       };
-      checksum: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "checksum";
+          fieldName: "startedAt";
         };
       };
-      applied: ConvexBooleanBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1849,25 +1849,25 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "applied";
+          fieldName: "updatedAt";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "completedAt";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "lastError";
         };
       };
       writeMode: ConvexTextBuilderInitial<""> & {
@@ -1905,7 +1905,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1915,10 +1915,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "direction";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1928,28 +1928,23 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "runId";
         };
       };
-      completedAt: ConvexNumberBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
-          tableName: "migration_run";
+          notNull: true;
         };
       } & {
-        _: {
-          fieldName: "completedAt";
-        };
-      };
-      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_run";
         };
       } & {
         _: {
-          fieldName: "lastError";
+          fieldName: "startedAt";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1959,20 +1954,25 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "updatedAt";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
-          notNull: true;
+          tableName: "migration_run";
         };
       } & {
+        _: {
+          fieldName: "completedAt";
+        };
+      };
+      lastError: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_run";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "lastError";
         };
       };
       dryRun: ConvexBooleanBuilderInitial<""> & {

package/package.json

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

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

@@ -539,7 +539,11 @@ export const { createContext, createCaller, handler } = convexBetterAuth({
 | `createCaller` | Server-side caller factory |
 | `handler` | Next.js API route handler (`export const { GET, POST, OPTIONS } = handler;`) |
 
-Options: `api`, `convexSiteUrl`, `auth.jwtCache` (default true), `auth.isUnauthorized`.
+Options: `api`, `convexSiteUrl`, `auth.jwtCache` (boolean or `{ now }`, default true),
+`auth.expirationToleranceSeconds` (default 60), `auth.isUnauthorized`.
+`now` returns finite Unix seconds or a promise of seconds. For Next partial
+prefetching and request-time versus private-cache clocks, follow
+[Next setup](../setup/next.md#8a4-jwt-cache-and-partial-prefetching).
 
 ### Client Provider with Auth
 

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

@@ -98,7 +98,54 @@ export function HydrateClient({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### 8.A.4 Pass server token to provider
+### 8.A.4 JWT cache and partial prefetching
+
+With Next 16 `cacheComponents` and `partialPrefetching`, the default JWT expiry
+clock can trigger a Blocking Route error even after `await headers()`. The
+app owns clock timing. For request-time contexts, configure the server factory:
+
+```ts
+import { connection } from 'next/server';
+
+export const { createContext, createCaller, handler } = convexBetterAuth({
+  api,
+  convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
+  auth: {
+    jwtCache: {
+      now: async () => {
+        await connection();
+        return Math.floor(Date.now() / 1000);
+      },
+    },
+  },
+});
+```
+
+`auth.jwtCache` accepts a boolean or `{ now?: () => number | Promise<number> }`.
+The clock returns finite **Unix seconds**, not milliseconds. The reader awaits
+it only for a decoded cached JWT with an expiry. Disabled caching, forced
+refresh, missing/malformed cookies, and absent expiry bypass the hook.
+`auth.expirationToleranceSeconds` remains a sibling option (default 60).
+Clock throws/rejections propagate unchanged; `NaN` and infinities are rejected.
+
+Keep `await headers()` in the RSC context creator. Put request-time token reads
+under `Suspense`, including a provider or route gate that awaits `caller.getToken()`.
+For `'use cache: private'`, use a separate factory with the default or a sync
+clock; **never call `connection()` inside private cache**. A private token helper
+can use `cacheLife({ stale: 30 })`, read headers, create that context, and return
+`context.token`. A token-blocking layout must defer its token-dependent subtree
+with `Suspense`, including when awaiting a private-cache helper. Private caching
+allows the clock read but does not make runtime auth data static.
+
+`auth: { jwtCache: false }` avoids the cookie expiry clock but fetches a token
+on every context creation. Kitcn does not import Next, detect render stages, or
+suppress render aborts. An app that runs a `connection()` clock through TanStack
+queries owns abort handling because recording a query failure can also read
+`Date.now()`. Do not suppress ordinary auth failures.
+
+Full examples: [Next.js JWT cache guidance](https://kitcn.dev/docs/nextjs#jwt-cache-and-partial-prefetching).
+
+### 8.A.5 Pass server token to provider
 
 ```tsx
 // app/(app)/layout.tsx