kitcn 0.25.6 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # kitcn
 
+## 0.26.0
+
+### Minor Changes
+
+- [#401](https://github.com/udecode/kitcn/pull/401) [`947cd11`](https://github.com/udecode/kitcn/commit/947cd11fe4e461caca9d7cc934ef34d62599e136) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Breaking changes
+
+  - Require `api` on `convexBetterAuthReactStart`, which now returns `createCaller`
+    and `createContext` alongside the auth helpers.
+
+  ```ts
+  // Before
+  export const { handler, getToken } = convexBetterAuthReactStart({
+    convexUrl: import.meta.env.VITE_CONVEX_URL!,
+    convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
+  });
+
+  // After
+  export const { handler, getToken, createCaller, createContext } =
+    convexBetterAuthReactStart({
+      api,
+      convexUrl: import.meta.env.VITE_CONVEX_URL!,
+      convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
+    });
+  ```
+
+  - Drop `runServerCall` from the TanStack Start scaffold. Call procedures on a
+    caller bound once with `createCaller()`.
+
+  ```ts
+  // Before
+  export function runServerCall<T>(
+    fn: (caller: ServerCaller) => Promise<T> | T
+  ) {
+    const caller = createServerCaller();
+    return fn(caller);
+  }
+  await runServerCall((caller) => caller.user.getSessionUser({}));
+
+  // After
+  export const caller = createCaller();
+  await caller.user.getSessionUser({});
+  ```
+
+  - Move TanStack Start JWT caching under `auth.jwtCache`, a boolean.
+
+  ```ts
+  // Before
+  convexBetterAuthReactStart({
+    jwtCache: { enabled: true, isAuthError },
+    // ...
+  });
+
+  // After
+  convexBetterAuthReactStart({
+    auth: { jwtCache: true, isUnauthorized: isAuthError },
+    // ...
+  });
+  ```
+
+  ## Patches
+
+  - Fetch the Convex auth token once per request on TanStack Start. Every
+    procedure call, `getToken()`, and `fetchAuthQuery`/`fetchAuthMutation`/
+    `fetchAuthAction` in a request now share one token, instead of each paying its
+    own round trip.
+  - Stop replaying a rejected auth token for the rest of a request. After a
+    refresh, the remaining calls sharing that context use the new token instead of
+    re-failing and re-running non-idempotent mutations and actions.
+  - Refresh expired TanStack Start tokens instead of failing. Forced refresh and
+    token freshness now reach the token layer, so a stale token retries once and a
+    fresh one is no longer replayed on an authorization error.
+
+  Existing TanStack Start apps: re-run `kitcn add auth --overwrite` to update
+  `src/lib/convex/auth-server.ts` and `src/lib/convex/server.ts`.
+
+## 0.25.7
+
+### Patch Changes
+
+- [#379](https://github.com/udecode/kitcn/pull/379) [`53fe88e`](https://github.com/udecode/kitcn/commit/53fe88e6911cdabdfcccba20337bfdadb7b6e5be) Thanks [@zbeyens](https://github.com/zbeyens)! - ## Patches
+
+  - Fix codegen schema loading with constrained required environment values.
+  - Fix first-run codegen when schema triggers import newly generated callers.
+
 ## 0.25.6
 
 ### Patch Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
 import { Bn as ConvexTextBuilderInitial, Xt as ConvexTableWithColumns } from "../capabilities-DtDfpdcH.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-eTewPUGq.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-AYna1fq8.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";

package/dist/auth/nextjs/index.js

@@ -1,6 +1,6 @@
 import { t as getToken } from "../../token-DcV_0fkF.js";
 import { n as defaultIsUnauthorized } from "../../error-CMLeCadS.js";
-import { t as createCallerFactory } from "../../caller-factory-Dd3H7j3V.js";
+import { t as createCallerFactory } from "../../caller-factory-D4pz5GcZ.js";
 
 //#region src/auth-nextjs/index.ts
 /** biome-ignore-all lint/suspicious/noExplicitAny: lib */

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

@@ -1,12 +1,66 @@
+import { H as ConvexContext, W as LazyCaller } from "../../../procedure-name-l2YusEZI.js";
 import { t as GetTokenOptions } from "../../../token-kQaqFby4.js";
 import { FunctionReference, FunctionReturnType, OptionalRestArgs } from "convex/server";
 
 //#region src/auth-start/server.d.ts
-type ConvexBetterAuthReactStartOptions = Omit<GetTokenOptions, 'forceRefresh'> & {
+/** Auth options for server-side calls. */
+type AuthOptions = {
+  /** Better Auth auth route base path. Defaults to `/api/auth`. */basePath?: string;
+  /**
+   * Read the Convex JWT from the session cookie instead of fetching it.
+   * Default: false.
+   *
+   * The token this saves a round trip on is also the token
+   * `syncConvexAuthForStartLoader` hands the browser Convex client, which
+   * captures it for the lifetime of the socket. A cookie JWT can be within
+   * seconds of expiry and cannot be renewed from that callback, so enable this
+   * only for apps that do not prime the browser client from `getToken()`.
+   */
+  jwtCache?: boolean; /** Custom function to detect UNAUTHORIZED errors. Default checks code property. */
+  isUnauthorized?: (error: unknown) => boolean; /** Expiration tolerance in seconds. */
+  expirationToleranceSeconds?: number;
+};
+type ConvexBetterAuthReactStartOptions<TApi> = Omit<GetTokenOptions, 'forceRefresh' | 'jwtCache'> & {
+  /** Your Convex API object. */api: TApi;
   convexSiteUrl: string;
-  convexUrl: string;
+  convexUrl: string; /** Auth options. */
+  auth?: AuthOptions;
 };
-declare const convexBetterAuthReactStart: (opts: ConvexBetterAuthReactStartOptions) => {
+/**
+ * Create Convex caller factory with Better Auth integration for TanStack Start.
+ *
+ * Every request resolves its Convex token once. TanStack Start runs each request
+ * inside an `AsyncLocalStorage` scope, so `getRequest()` returns an object whose
+ * identity is stable for that request and distinct across requests. Keying the
+ * memos on it makes them request-scoped by construction: nothing auth-related is
+ * ever held at module scope, and entries are collected with the request.
+ *
+ * @example
+ * ```ts
+ * // auth-server.ts
+ * export const { createCaller, handler, getToken } = convexBetterAuthReactStart({
+ *   api,
+ *   convexUrl: import.meta.env.VITE_CONVEX_URL!,
+ *   convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
+ * });
+ *
+ * // server.ts
+ * export const caller = createCaller();
+ *
+ * // any server function or server route - single token fetch per request
+ * const user = await caller.user.getSessionUser();
+ * const posts = await caller.posts.list();
+ * ```
+ */
+declare const convexBetterAuthReactStart: <TApi extends Record<string, unknown>>(opts: ConvexBetterAuthReactStartOptions<TApi>) => {
+  /**
+   * Bind a cRPC caller. Defaults to the request-scoped context, so every
+   * procedure call in a request shares one token fetch.
+   */
+  createCaller: (ctxFn?: () => Promise<ConvexContext<TApi>>) => LazyCaller<TApi>;
+  createContext: (reqOpts: {
+    headers: Headers;
+  }) => Promise<ConvexContext<TApi>>;
   getToken: () => Promise<string | undefined>;
   handler: (request: Request) => Promise<Response>;
   fetchAuthQuery: <Query extends FunctionReference<"query">>(query: Query, ...args: OptionalRestArgs<Query>) => Promise<FunctionReturnType<Query>>;

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

@@ -1,12 +1,11 @@
 import { t as getToken } from "../../../token-DcV_0fkF.js";
+import { n as defaultIsUnauthorized } from "../../../error-CMLeCadS.js";
+import { t as createCallerFactory } from "../../../caller-factory-D4pz5GcZ.js";
 import { stripIndent } from "common-tags";
-import { getRequestHeaders } from "@tanstack/react-start/server";
+import { getRequest } from "@tanstack/react-start/server";
 import { ConvexHttpClient } from "convex/browser";
-import React from "react";
 
 //#region src/auth-start/server.ts
-const fallbackCache = (fn) => fn;
-const cache = React.cache ?? fallbackCache;
 const TRAILING_COLON_RE = /:$/;
 const requestCanHaveBody = (method) => method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
 const stripHopByHopHeaders = (headers) => {
@@ -79,30 +78,134 @@ const handler = async (request, opts) => {
 		redirect: "manual"
 	});
 };
+/**
+* Create Convex caller factory with Better Auth integration for TanStack Start.
+*
+* Every request resolves its Convex token once. TanStack Start runs each request
+* inside an `AsyncLocalStorage` scope, so `getRequest()` returns an object whose
+* identity is stable for that request and distinct across requests. Keying the
+* memos on it makes them request-scoped by construction: nothing auth-related is
+* ever held at module scope, and entries are collected with the request.
+*
+* @example
+* ```ts
+* // auth-server.ts
+* export const { createCaller, handler, getToken } = convexBetterAuthReactStart({
+*   api,
+*   convexUrl: import.meta.env.VITE_CONVEX_URL!,
+*   convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
+* });
+*
+* // server.ts
+* export const caller = createCaller();
+*
+* // any server function or server route - single token fetch per request
+* const user = await caller.user.getSessionUser();
+* const posts = await caller.posts.list();
+* ```
+*/
 const convexBetterAuthReactStart = (opts) => {
 	const siteUrl = parseConvexSiteUrl(opts.convexSiteUrl);
-	const cachedGetToken = cache(async (opts) => {
-		const headers = getRequestHeaders();
+	const auth = opts.auth ?? {};
+	const jwtCacheEnabled = auth.jwtCache === true;
+	const fetchTokenFor = (headers, forceRefresh) => {
 		const mutableHeaders = new Headers(headers);
 		stripHopByHopHeaders(mutableHeaders);
 		mutableHeaders.set("accept-encoding", "identity");
-		return getToken(siteUrl, mutableHeaders, opts);
+		return getToken(siteUrl, mutableHeaders, {
+			basePath: auth.basePath ?? opts.basePath,
+			cookiePrefix: opts.cookiePrefix,
+			forceRefresh,
+			jwtCache: {
+				enabled: jwtCacheEnabled,
+				expirationToleranceSeconds: auth.expirationToleranceSeconds,
+				isAuthError: auth.isUnauthorized ?? defaultIsUnauthorized
+			}
+		});
+	};
+	const headersByRequest = /* @__PURE__ */ new WeakMap();
+	const tokenByRequest = /* @__PURE__ */ new WeakMap();
+	const contextByRequest = /* @__PURE__ */ new WeakMap();
+	/**
+	* Snapshot the current request's headers once.
+	*
+	* `getRequestHeaders()` is not identity-stable within a request: srvx serves a
+	* lazy header view until anything materializes the native Request (a server
+	* function reading `formData()`, for example), then swaps in that Request's
+	* own `Headers` and drops the old one. Header *values* survive the swap, so a
+	* snapshot taken at any point is correct, but comparing or keying on the live
+	* accessor would silently stop matching mid-request.
+	*/
+	const requestHeaders = (request) => {
+		const cached = headersByRequest.get(request);
+		if (cached) return cached;
+		const snapshot = new Headers(request.headers);
+		headersByRequest.set(request, snapshot);
+		return snapshot;
+	};
+	/**
+	* Memoize `create` for the lifetime of the current request. The pending
+	* promise is stored before it settles so concurrent callers share one
+	* in-flight fetch, and a rejection is evicted so the next caller can retry.
+	*/
+	const perRequest = (store, create) => {
+		const request = getRequest();
+		const cached = store.get(request);
+		if (cached) return cached;
+		const pending = create(request).catch((error) => {
+			if (store.get(request) === pending) store.delete(request);
+			throw error;
+		});
+		store.set(request, pending);
+		return pending;
+	};
+	/**
+	* The current request, or `undefined` outside a Start request scope.
+	* `getRequest()` throws there, and an explicit `createContext({ headers })`
+	* is allowed to run with no ambient request at all.
+	*/
+	const currentRequest = () => {
+		try {
+			return getRequest();
+		} catch {
+			return;
+		}
+	};
+	/** Ambient token for the current request, resolved at most once. */
+	const requestToken = () => perRequest(tokenByRequest, (request) => fetchTokenFor(requestHeaders(request)));
+	const { createContext, createCaller } = createCallerFactory({
+		api: opts.api,
+		auth: {
+			getToken: (_tokenSiteUrl, headers, getTokenOpts) => {
+				const forceRefresh = getTokenOpts?.forceRefresh;
+				const request = currentRequest();
+				if (!forceRefresh && request && headers === headersByRequest.get(request)) return requestToken();
+				return fetchTokenFor(headers, forceRefresh);
+			},
+			isUnauthorized: auth.isUnauthorized
+		},
+		convexSiteUrl: opts.convexSiteUrl,
+		convexUrl: opts.convexUrl
 	});
+	/** Request-scoped context. One context, one token, per request. */
+	const createRequestContext = () => perRequest(contextByRequest, (request) => createContext({ headers: requestHeaders(request) }));
 	const callWithToken = async (fn) => {
-		const token = await cachedGetToken(opts) ?? {};
+		const token = await requestToken();
 		try {
-			return await fn(token?.token);
+			return await fn(token.token);
 		} catch (error) {
-			if (!opts?.jwtCache?.enabled || token.isFresh || !opts.jwtCache?.isAuthError(error)) throw error;
-			return await fn((await cachedGetToken({
-				...opts,
-				forceRefresh: true
-			})).token);
+			if (token.isFresh || !(auth.isUnauthorized ?? defaultIsUnauthorized)(error)) throw error;
+			const refreshed = await fetchTokenFor(requestHeaders(getRequest()), true);
+			token.token = refreshed.token;
+			token.isFresh = refreshed.isFresh;
+			return await fn(refreshed.token);
 		}
 	};
 	return {
+		createCaller: (ctxFn = createRequestContext) => createCaller(ctxFn),
+		createContext,
 		getToken: async () => {
-			return (await cachedGetToken(opts)).token;
+			return (await requestToken()).token;
 		},
 		handler: async (request) => cloneAuthHandlerResponse(await handler(request, opts)),
 		fetchAuthQuery: async (query, ...args) => {

package/dist/{caller-factory-Dd3H7j3V.js → caller-factory-D4pz5GcZ.js}

@@ -164,6 +164,8 @@ function createCallerFactory(opts) {
 				...opts,
 				forceRefresh: true
 			});
+			tokenResult.token = newToken.token;
+			tokenResult.isFresh = newToken.isFresh;
 			try {
 				return await fn(newToken.token);
 			} catch (retryError) {

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as Columns, D as TableName, E as RlsPolicies, O as createSystemFields, S as getRankIndexes, T as OrmSchemaExtensions, _ as loadEsbuild, a as generateMeta, b as getAggregateIndexes, c as resolveSchemaDefaultExport, f as createProjectJiti, g as loadDotenv, h as loadClackPrompts, i as resolveConfiguredBackend, l as schemaDeclaresAggregateIndexes, m as loadBabelParser, n as withLocalCodegenEnv, o as getConvexConfig, p as CRPC_BUILDER_STUB_SOURCE, r as loadCliConfig, s as collectSchemaTables, t as getLocalBackendEnvVars, u as logger, v as highlighter, w as EnableRLS, x as getIndexes, y as isColorEnabled } from "./local-env-CiPqNKS_.mjs";
+import { C as Columns, D as TableName, E as RlsPolicies, O as createSystemFields, S as getRankIndexes, T as OrmSchemaExtensions, _ as loadEsbuild, a as generateMeta, b as getAggregateIndexes, c as resolveSchemaDefaultExport, f as createProjectJiti, g as loadDotenv, h as loadClackPrompts, i as resolveConfiguredBackend, l as schemaDeclaresAggregateIndexes, m as loadBabelParser, n as withLocalCodegenEnv, o as getConvexConfig, p as CRPC_BUILDER_STUB_SOURCE, r as loadCliConfig, s as collectSchemaTables, t as getLocalBackendEnvVars, u as logger, v as highlighter, w as EnableRLS, x as getIndexes, y as isColorEnabled } from "./local-env-9Qtfn3wR.mjs";
 import { createRequire } from "node:module";
 import fs, { existsSync, readFileSync } from "node:fs";
 import path, { basename, delimiter, dirname, extname, isAbsolute, join, posix, relative, resolve } from "node:path";
@@ -5636,15 +5636,19 @@ export const Route = createFileRoute('/api/auth/$')({
 
 //#endregion
 //#region src/cli/registry/items/auth/auth-start-server.template.ts
-const AUTH_START_SERVER_TEMPLATE = `import { convexBetterAuthReactStart } from 'kitcn/auth/start/server';
+const AUTH_START_SERVER_TEMPLATE = `import { api } from '@convex/api';
+import { convexBetterAuthReactStart } from 'kitcn/auth/start/server';
 
 export const {
   handler,
   getToken,
+  createCaller,
+  createContext,
   fetchAuthQuery,
   fetchAuthMutation,
   fetchAuthAction,
 } = convexBetterAuthReactStart({
+  api,
   convexUrl: import.meta.env.VITE_CONVEX_URL!,
   convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
 });
@@ -5652,41 +5656,9 @@ export const {
 
 //#endregion
 //#region src/cli/registry/items/auth/auth-start-server-call.template.ts
-const AUTH_START_SERVER_CALL_TEMPLATE = `import { api } from '@convex/api';
-import { getRequestHeaders } from '@tanstack/react-start/server';
-import { createCallerFactory } from 'kitcn/server';
-
-import { getToken } from '@/lib/convex/auth-server';
-
-const { createContext, createCaller } = createCallerFactory({
-  api,
-  convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
-  auth: {
-    getToken: async () => {
-      return {
-        token: await getToken(),
-      };
-    },
-  },
-});
-
-type ServerCaller = ReturnType<typeof createCaller>;
-
-async function makeContext() {
-  const headers = await getRequestHeaders();
-  return createContext({ headers });
-}
+const AUTH_START_SERVER_CALL_TEMPLATE = `import { createCaller } from '@/lib/convex/auth-server';
 
-function createServerCaller(): ServerCaller {
-  return createCaller(async () => {
-    return await makeContext();
-  });
-}
-
-export function runServerCall<T>(fn: (caller: ServerCaller) => Promise<T> | T) {
-  const caller = createServerCaller();
-  return fn(caller);
-}
+export const caller = createCaller();
 `;
 
 //#endregion

package/dist/{local-env-CiPqNKS_.mjs → local-env-9Qtfn3wR.mjs}

@@ -473,22 +473,71 @@ export class CRPCError extends Error {
   }
 }
 
+const parseEnvForCodegen = (schema) => {
+  if (typeof schema?.safeParse !== "function") {
+    return schema.parse(process.env);
+  }
+
+  const result = schema.safeParse(process.env);
+  if (result?.success === true) return result.data;
+
+  const issues = result?.error?.issues;
+  if (!Array.isArray(issues) || issues.length === 0) {
+    return schema.parse(process.env);
+  }
+
+  const missingFieldIssues = new Map();
+  for (const [key, field] of Object.entries(schema.shape)) {
+    if (
+      process.env[key] !== undefined ||
+      typeof field?.safeParse !== "function"
+    ) {
+      continue;
+    }
+    const fieldResult = field.safeParse(undefined);
+    if (
+      fieldResult?.success === false &&
+      Array.isArray(fieldResult.error?.issues)
+    ) {
+      missingFieldIssues.set(key, fieldResult.error.issues);
+    }
+  }
+
+  const isMissingFieldIssue = (issue) => {
+    if (!Array.isArray(issue?.path) || issue.path.length === 0) return false;
+    const [key, ...path] = issue.path;
+    const fieldIssues = missingFieldIssues.get(key);
+    return fieldIssues?.some(
+      (fieldIssue) =>
+        fieldIssue?.code === issue.code &&
+        JSON.stringify(fieldIssue.path ?? []) === JSON.stringify(path)
+    );
+  };
+  if (!issues.every(isMissingFieldIssue)) {
+    return schema.parse(process.env);
+  }
+
+  const data = {};
+  for (const [key, field] of Object.entries(schema.shape)) {
+    if (typeof field?.safeParse !== "function") {
+      return schema.parse(process.env);
+    }
+    const fieldResult = field.safeParse(process.env[key]);
+    if (fieldResult?.success === true) {
+      data[key] = fieldResult.data;
+    } else if (!missingFieldIssues.has(key)) {
+      return schema.parse(process.env);
+    }
+  }
+  return data;
+};
+
 export const createEnv = ({ schema }) => () => {
   if (typeof schema?.parse !== "function") return process.env;
   if (globalThis.__KITCN_CODEGEN__ !== true || !schema.shape) {
     return schema.parse(process.env);
   }
-  const fallback = Object.fromEntries(
-    Object.entries(schema.shape).map(([key, zodType]) => {
-      const result = zodType?.safeParse?.(undefined);
-      if (result?.success) return [key, result.data];
-      if (Array.isArray(zodType?.options) && zodType.options.length > 0) {
-        return [key, zodType.options[0]];
-      }
-      return [key, ""];
-    })
-  );
-  return schema.parse({ ...fallback, ...process.env });
+  return parseEnvForCodegen(schema);
 };
 export const createHttpRouter = (_app, httpRouter) => httpRouter ?? {};
 export const createCallerFactory = () => () => ({});
@@ -3911,7 +3960,15 @@ async function generateMeta(sharedDir, options) {
 	};
 	let sharedJitiInstance;
 	const getSharedJitiInstance = () => sharedJitiInstance ??= createProjectJiti();
-	const schemaMetadata = await withCodegenParseSentinel(() => resolveSchemaMetadataForCodegen(functionsDir, debug, getSharedJitiInstance));
+	const schemaRuntimeModules = listFilesRecursive(functionsDir).filter((file) => file.endsWith(".ts") && isValidConvexFile(file)).map((file) => file.replace(TS_EXTENSION_RE, ""));
+	const schemaRuntimePlaceholders = ensureGeneratedRuntimePlaceholders(functionsDir, schemaRuntimeModules, resolveModuleRuntimeExportNames(schemaRuntimeModules, normalizedTrimSegments));
+	const schemaMetadata = await (async () => {
+		try {
+			return await withCodegenParseSentinel(() => resolveSchemaMetadataForCodegen(functionsDir, debug, getSharedJitiInstance));
+		} finally {
+			for (const schemaRuntimePlaceholder of schemaRuntimePlaceholders) fs.rmSync(schemaRuntimePlaceholder, { force: true });
+		}
+	})();
 	const hasOrmSchemaMetadata = schemaMetadata.hasOrmSchema;
 	const hasRelationsMetadata = schemaMetadata.hasRelations;
 	const hasRelationsExport = hasNamedExport(path.join(functionsDir, "schema.ts"), "relations");

package/dist/orm/index.d.ts

@@ -1,5 +1,5 @@
 import { $n as BinaryExpression, $t as OrmLifecycleOperation, A as DatabaseWithMutations, An as ConvexCheckConfig, Ar as AnyColumn, At as VectorQueryConfig, B as RlsContext, Bn as ConvexTextBuilderInitial, Br as IsUnique, Bt as RelationsBuilderColumnConfig, C as MigrationTableName, Cn as aggregateIndex, Cr as notBetween, Ct as OrderDirection, D as defineMigrationSet, Dn as uniqueIndex, Dt as ReturningResult, E as defineMigration, En as searchIndex, Er as startsWith, Et as ReturningAll, Fn as ConvexUniqueConstraintConfig, Fr as ColumnBuilderWithTableName, Ft as ExtractTablesWithRelations, Gt as defineRelations, H as EdgeMetadata, In as check, Ir as ColumnDataType, It as ManyConfig, Jt as ConvexDeletionConfig, Kt as defineRelationsPart, Ln as foreignKey, Lr as DrizzleEntity, Lt as OneConfig, M as OrmReader$1, Mn as ConvexForeignKeyConfig, Mr as ColumnBuilderBaseConfig, Mt as unsetToken, N as OrmWriter$1, Nn as ConvexUniqueConstraintBuilder, Nr as ColumnBuilderRuntimeConfig, O as detectMigrationDrift, On as vectorIndex, Or as SystemFields, Ot as ReturningSelection, Pn as ConvexUniqueConstraintBuilderOn, Pr as ColumnBuilderTypeConfig, Pt as ExtractTablesFromSchema, Qn as TableName, Qt as OrmLifecycleChange, Rn as unique, Rr as HasDefault, Rt as RelationsBuilder, S as MigrationStep, Sn as ConvexVectorIndexConfig, Sr as not, St as OrderByClause, T as buildMigrationPlan, Tn as rankIndex, Tr as or, Tt as PredicateWhereIndexConfig, U as extractRelationsConfig, Un as Brand, Ut as TableRelationalConfig, V as RlsMode, Vn as text, Vr as NotNull, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yn as OrmSchemaExtensions, Yt as ConvexTable, Zn as OrmSchemaTriggers, Zt as DiscriminatorBuilderConfig, _ as MigrationMigrateOne, _n as ConvexSearchIndexBuilder, _r as isNull, _t as MutationPaginateConfig, an as RlsPolicyConfig, ar as and, at as CountConfig, b as MigrationSet, bn as ConvexVectorIndexBuilder, br as lte, bt as MutationReturning, cn as RlsRole, cr as endsWith, ct as FilterOperators, d as MigrationDefinition, dn as ConvexAggregateIndexBuilder, dr as gt, dt as InferModelFromColumns, en as TableConfig, er as ExpressionVisitor, et as AggregateConfig, f as MigrationDirection, fn as ConvexAggregateIndexBuilderOn, fr as gte, ft as InferSelectModel, g as MigrationManifestEntry, gn as ConvexRankIndexBuilderOn, gr as isNotNull, gt as MutationExecutionMode, h as MigrationDriftIssue, hn as ConvexRankIndexBuilder, hr as isFieldReference, ht as MutationExecuteResult, i as OrmMigrationCapability, in as RlsPolicy, ir as UnaryExpression, it as BuildRelationResult, j as DatabaseWithQuery, jn as ConvexForeignKeyBuilder, jr as ColumnBuilder, jt as VectorSearchProvider, kn as ConvexCheckBuilder, kt as UpdateSet, ln as RlsRoleConfig, lr as eq, lt as GetColumnData, m as MigrationDocContext, mn as ConvexIndexBuilderOn, mr as inArray, mt as MutationExecuteConfig, n as OrmCapabilities, nn as deletion, nr as FilterExpression, nt as AggregateResult, on as RlsPolicyToOption, or as between, ot as CountResult, p as MigrationDoc, pn as ConvexIndexBuilder, pr as ilike, pt as InsertValue, qn as OrmSchemaExtensionTables, qt as ConvexDeletionBuilder, r as OrmCapability, rn as discriminator, rr as LogicalExpression, rt as BuildQueryResult, sn as rlsPolicy, sr as contains, st as DBQueryConfig, t as OrmAggregateCapability, tn as convexTable, tr as FieldReference, tt as AggregateFieldValue, u as MigrationAppliedState, un as rlsRole, ur as fieldRef, ut as InferInsertModel, v as MigrationPlan, vn as ConvexSearchIndexBuilderOn, vr as like, vt as MutationPaginatedResult, w as MigrationWriteMode, wn as index, wr as notInArray, wt as PaginatedResult, x as MigrationStateMap, xn as ConvexVectorIndexBuilderOn, xr as ne, xt as MutationRunMode, y as MigrationRunStatus, yn as ConvexSearchIndexConfig, yr as lt, yt as MutationResult, zn as ConvexTextBuilder, zr as IsPrimaryKey, zt as RelationsBuilderColumnBase } from "../capabilities-DtDfpdcH.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-eTewPUGq.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-AYna1fq8.js";
 import { i as pretendRequired, n as deprecated, r as pretend } from "../validators-wOIjhkfN.js";
 import { a as QueryCtxWithPreferredOrmQueryTable, i as QueryCtxWithOrmQueryTable, n as LookupByIdResultByCtx, o as getByIdWithOrmQueryFallback, r as QueryCtxWithOptionalOrmQueryTable, t as DocByCtx } from "../query-context-DJONf8X5.js";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchemaDefinition } from "convex/server";

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

@@ -1,3 +1,3 @@
 import { C as MigrationTableName, D as defineMigrationSet, E as defineMigration, O as detectMigrationDrift, S as MigrationStep, T as buildMigrationPlan, _ as MigrationMigrateOne, a as MigrationCancelArgs, b as MigrationSet, c as MigrationStatusArgs, d as MigrationDefinition, f as MigrationDirection, g as MigrationManifestEntry, h as MigrationDriftIssue, l as createMigrationHandlers, m as MigrationDocContext, o as MigrationRunArgs, p as MigrationDoc, s as MigrationRunChunkArgs, u as MigrationAppliedState, v as MigrationPlan, w as MigrationWriteMode, x as MigrationStateMap, y as MigrationRunStatus } from "../../capabilities-DtDfpdcH.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-eTewPUGq.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-AYna1fq8.js";
 export { 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/server/index.js

@@ -1,5 +1,5 @@
 import { a as isMutationCtx, c as isSchedulerCtx, d as requireQueryCtx, f as requireRunMutationCtx, i as isActionCtx, l as requireActionCtx, n as createGeneratedFunctionReference, o as isQueryCtx, p as requireSchedulerCtx, r as getGeneratedValue, s as isRunMutationCtx, t as createApiLeaf, u as requireMutationCtx } from "../api-entry-CkDpGYVg.js";
-import { n as createLazyCaller, r as createServerCaller, t as createCallerFactory } from "../caller-factory-Dd3H7j3V.js";
+import { n as createLazyCaller, r as createServerCaller, t as createCallerFactory } from "../caller-factory-D4pz5GcZ.js";
 import { A as zid, C as toCRPCError, D as zCustomAction, E as withSystemFields, M as zodOutputToConvexFields, N as zodToConvex, O as zCustomMutation, P as zodToConvexFields, S as isCRPCError, T as convexToZodFields, _ as CRPCError, a as createMiddlewareFactory, b as getCRPCErrorFromUnknown, c as registerProcedureNameLookup, d as createHttpRouterFactory, f as extractRouteMap, g as matchPathParams, h as handleHttpError, i as QueryProcedureBuilder, j as zodOutputToConvex, k as zCustomQuery, l as HttpRouterWithHono, m as extractPathParams, n as MutationProcedureBuilder, o as initCRPC, p as createHttpProcedureBuilder, r as ProcedureBuilder, s as inferProcedureNameFromCallsite, t as ActionProcedureBuilder, u as createHttpRouter, v as CRPC_ERROR_CODES_BY_KEY, w as convexToZod, x as getHTTPStatusCodeFromError, y as CRPC_ERROR_CODE_TO_HTTP } from "../builder-CsAw-DK8.js";
 import { a as createProcedureHandlerFactory, c as typedProcedureResolver, i as createProcedureCallerFactory, l as createEnv, n as createGenericCallerFactory, o as defineProcedure, r as createGenericHandlerFactory, s as getGeneratedFunctionReference, t as createGeneratedRegistryRuntime } from "../procedure-caller-BR-Wb0si.js";
 

package/dist/watcher.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as generateMeta, d as PARSE_SNAPSHOT_SUFFIX, i as resolveConfiguredBackend, n as withLocalCodegenEnv, o as getConvexConfig, r as loadCliConfig, u as logger } from "./local-env-CiPqNKS_.mjs";
+import { a as generateMeta, d as PARSE_SNAPSHOT_SUFFIX, i as resolveConfiguredBackend, n as withLocalCodegenEnv, o as getConvexConfig, r as loadCliConfig, u as logger } from "./local-env-9Qtfn3wR.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 

package/dist/{where-clause-compiler-eTewPUGq.d.ts → where-clause-compiler-AYna1fq8.d.ts}

@@ -1008,7 +1008,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1018,10 +1018,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "count";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1031,10 +1031,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1044,10 +1044,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1057,7 +1057,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1159,7 +1159,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1169,10 +1169,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1182,7 +1182,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1340,7 +1340,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "value";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1350,10 +1350,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "count";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1363,10 +1363,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1376,10 +1376,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1389,7 +1389,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1668,7 +1668,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "lastError";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1678,10 +1678,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1691,10 +1691,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyDefinitionHash";
+          fieldName: "indexName";
         };
       };
-      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
+      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1704,10 +1704,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "metricDefinitionHash";
+          fieldName: "keyDefinitionHash";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1717,7 +1717,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "metricDefinitionHash";
         };
       };
     };

package/package.json

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

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

@@ -34,20 +34,28 @@ export const {
 **Create:** `src/lib/convex/auth-server.ts`
 
 ```ts
+import { api } from "@convex/api";
 import { convexBetterAuthReactStart } from "kitcn/auth/start/server";
 
 export const {
   handler,
   getToken,
+  createCaller,
+  createContext,
   fetchAuthQuery,
   fetchAuthMutation,
   fetchAuthAction,
 } = convexBetterAuthReactStart({
+  api,
   convexUrl: import.meta.env.VITE_CONVEX_URL!,
   convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
 });
 ```
 
+`getToken` fetches the Convex token from the auth route. `auth.jwtCache: true`
+reads it from the session cookie instead. Leave it off when the browser Convex
+client is primed from `getToken()`.
+
 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:
@@ -78,7 +86,7 @@ export const Route = createRootRouteWithContext<{
 });
 ```
 
-Use `runServerCall` or `fetchAuthQuery` for server-side loaders. Use
+Use the request-scoped `caller` or `fetchAuthQuery` for server-side loaders. Use
 `syncConvexAuthForStartLoader` only for client/router loaders that execute
 shared `ConvexQueryClient` queries before `ConvexAuthProvider` mounts.
 
@@ -105,42 +113,20 @@ export const Route = createFileRoute("/api/auth/$" as never)({
 **Create:** `src/lib/convex/server.ts`
 
 ```ts
-import { api } from "@convex/api";
-import { getRequestHeaders } from "@tanstack/react-start/server";
-import { createCallerFactory } from "kitcn/server";
+import { createCaller } from "@/lib/convex/auth-server";
 
-import { getToken } from "@/lib/convex/auth-server";
-
-const { createContext, createCaller } = createCallerFactory({
-  api,
-  convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
-  auth: {
-    getToken: async () => {
-      return {
-        token: await getToken(),
-      };
-    },
-  },
-});
-
-type ServerCaller = ReturnType<typeof createCaller>;
-
-async function makeContext() {
-  const headers = await getRequestHeaders();
-  return createContext({ headers });
-}
+export const caller = createCaller();
+```
 
-function createServerCaller(): ServerCaller {
-  return createCaller(async () => {
-    return await makeContext();
-  });
-}
+`createCaller()` binds to the current request, so every procedure call in a
+request shares one Convex auth token fetch. The module-scope `caller` holds no
+request state; it resolves the current request on each call. Pass a context
+factory (`createCaller(() => createContext({ headers }))`) only to call Convex
+with headers other than the current request's.
 
-export function runServerCall<T>(fn: (caller: ServerCaller) => Promise<T> | T) {
-  const caller = createServerCaller();
-  return fn(caller);
-}
-```
+Reach `caller` from a `createServerFn` handler or a server route. A route
+`loader` also runs in the browser on client-side navigation, where there is no
+request scope.
 
 Use the docs pattern from `tanstack-start.mdx` for: