kitcn 0.33.6 → 0.33.8

package/dist/{types-C7JkpfeY.d.ts → types-Bb0kwteA.d.ts}

@@ -64,6 +64,10 @@ declare function replaceUrlParam(url: string, params: Record<string, string>): s
  * Handles array values as multiple params with same key (like Hono).
  */
 declare function buildSearchParams(query: Record<string, string | string[]>): URLSearchParams;
+declare const RECHECK_AUTHORIZATION: unique symbol;
+declare const withAuthorizationRecheck: <T extends {
+  [key: string]: string | undefined;
+}>(headers: T, recheck: () => boolean) => T;
 /**
  * Hono-style HTTP request executor.
  * Processes args in the same way as Hono's ClientRequestImpl.fetch().
@@ -210,4 +214,4 @@ type VanillaAction<T extends FunctionReference<'action'>> = {
   mutate: keyof FunctionArgs<T> extends never ? (args?: EmptyObject) => Promise<FunctionReturnType<T>> : EmptyObject extends FunctionArgs<T> ? (args?: FunctionArgs<T>) => Promise<FunctionReturnType<T>> : (args: FunctionArgs<T>) => Promise<FunctionReturnType<T>>;
 };
 //#endregion
-export { HttpInputArgs as A, ReservedMutationOptions as C, VanillaMutation as D, VanillaAction as E, replaceUrlParam as F, RESERVED_KEYS as M, buildSearchParams as N, HttpClientOptions as O, executeHttpRequest as P, ReservedInfiniteQueryOptions as S, StaticQueryOptsParam as T, IsPaginated as _, BaseInfiniteQueryOptsParam as a, PaginatedFnMeta as b, ConvexMutationKey as c, ConvexQueryMeta as d, EmptyObject as f, InfiniteQueryInput as g, FnMeta as h, BaseConvexQueryOptions as i, HttpProxyBaseOptions as j, HttpFormValue as k, ConvexQueryHookOptions as l, FUNC_REF_SYMBOL as m, BaseConvexActionOptions as n, ConvexActionKey as o, ExtractPaginatedItem as p, BaseConvexInfiniteQueryOptions as r, ConvexInfiniteQueryMeta as s, AuthType as t, ConvexQueryKey as u, Meta as v, ReservedQueryOptions as w, PaginationOpts as x, MutationVariables as y };
+export { HttpInputArgs as A, ReservedMutationOptions as C, VanillaMutation as D, VanillaAction as E, executeHttpRequest as F, replaceUrlParam as I, withAuthorizationRecheck as L, RECHECK_AUTHORIZATION as M, RESERVED_KEYS as N, HttpClientOptions as O, buildSearchParams as P, ReservedInfiniteQueryOptions as S, StaticQueryOptsParam as T, IsPaginated as _, BaseInfiniteQueryOptsParam as a, PaginatedFnMeta as b, ConvexMutationKey as c, ConvexQueryMeta as d, EmptyObject as f, InfiniteQueryInput as g, FnMeta as h, BaseConvexQueryOptions as i, HttpProxyBaseOptions as j, HttpFormValue as k, ConvexQueryHookOptions as l, FUNC_REF_SYMBOL as m, BaseConvexActionOptions as n, ConvexActionKey as o, ExtractPaginatedItem as p, BaseConvexInfiniteQueryOptions as r, ConvexInfiniteQueryMeta as s, AuthType as t, ConvexQueryKey as u, Meta as v, ReservedQueryOptions as w, PaginationOpts as x, MutationVariables as y };

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

@@ -102,22 +102,22 @@ declare const migrationStorageTables: {
           fieldName: "status";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "cursor";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "direction";
         };
       };
       migrationId: ConvexTextBuilderInitial<""> & {
@@ -1326,11 +1326,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_extrema: ConvexTableWithColumns<{
     name: "aggregate_extrema";
     columns: {
-      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
-        _: {
-          $type: convex_values0.Value;
-        };
-      } & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1340,10 +1336,14 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "value";
+          fieldName: "count";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
+        _: {
+          $type: convex_values0.Value;
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -1353,7 +1353,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "value";
         };
       };
       updatedAt: ConvexNumberBuilderInitial<""> & {
@@ -1596,26 +1596,26 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
-      kind: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
         };
       } & {
         _: {
-          fieldName: "kind";
+          fieldName: "cursor";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      kind: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "aggregate_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "kind";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {
@@ -1751,22 +1751,22 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "cursor";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "direction";
         };
       };
       migrationId: ConvexTextBuilderInitial<""> & {

package/package.json

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

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

@@ -363,7 +363,7 @@ All from `kitcn/react`:
 |------|---------|-------------|
 | `useAuth()` | `{ hasSession, isAuthenticated, isLoading }` | Full auth state |
 | `useMaybeAuth()` | `boolean` | Has token (optimistic, may not be verified) |
-| `useIsAuth()` | `boolean` | Server-verified authentication |
+| `useIsAuth()` | `boolean` | Server-verified authentication (with `optimisticAuth`, also during the optimistic window) |
 | `useAuthGuard()` | `() => boolean` | Guard mutations, returns true if blocked |
 | `useConvexAuthRecovery()` | `{ recover, status, error }` | Rebind Convex auth after a transient token failure |
 
@@ -389,7 +389,7 @@ All from `kitcn/react`:
 | Component | Renders when |
 |-----------|-------------|
 | `MaybeAuthenticated` | Has session token (optimistic) |
-| `Authenticated` | Server-verified authenticated |
+| `Authenticated` | Server-verified authenticated (with `optimisticAuth`, also during the optimistic window) |
 | `MaybeUnauthenticated` | No session token (optimistic) |
 | `Unauthenticated` | Server-verified not authenticated |
 
@@ -414,16 +414,34 @@ All from `kitcn/react`:
 ```
 
 `optimisticAuth` only opens auth-bound query gates for a held, unexpired JWT;
-expired, opaque, and refused tokens stay closed. Enable
+expired, opaque, and refused tokens stay closed. The window ends at the Convex
+client's first auth result; use one `optimisticAuth` setting per client; no
+optimism over a client the Start loader authenticated. 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.
+the document identity (whatever its `exp`) before Convex, HTTP or the Start
+loader sees it. On a trip, every mounted provider hands out no token and
+publishes unauthenticated; each guarded one closes its client, then calls the
+callback once, so reload the document there. Browser only, page-wide: later
+providers start tripped, and a guarded one that mounts or shows again on a
+tripped page also closes its client and calls the callback once. Enabling the
+guard on a tripped page delivers that close and callback once too; sign-in
+mutations fail with `TOKEN_IDENTITY_CHANGED`.
 
 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.
+`sub|sessionId`, or a getter returning the document's current identity. Every
+admission (SSR, fresh and cached tokens, sign-in, HTTP, Start loader) binds a
+token to the page identity, the provider's own baseline and every mounted
+provider's current getter answer; an opaque session token is only exchanged,
+never handed to Convex. Held tokens are reconciled when a provider joins the
+page and at every admission. A page that never enables the guard is
+unchanged; once a guarded provider establishes the page identity it persists
+until reload, binding every provider and the Start loader, even after that
+provider unmounts. Two kitcn versions or revisions on one page (dev HMR
+across revisions included) are unsupported: no shared page identity until
+reload.
 `onTokenIdentityAdmitted(token)` observes admitted JWTs so the app can update
-that shared baseline. All three identity options require
+that shared baseline. Admission rechecks the baseline after the callback before
+publishing or handing out the token. All three identity options require
 `onTokenIdentityChange`.
 
 For `@convex-dev/auth` (React Native):

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