@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/src/plugins/client/index.ts

@@ -10,12 +10,59 @@
  * - Client: import type { ClientPlugin } from "@btst/stack/plugins/client"
  */
 
-import type { ClientPlugin } from "../../types";
+import type { ClientPluginDefinition } from "../../types";
 import type { Route } from "@btst/yar";
 
+type IdentifiedClientPluginDefinition<
+	TId extends string,
+	TOverrides,
+	TRoutes extends Record<string, Route>,
+	TProviderConfig extends Readonly<Record<string, unknown>> = Readonly<
+		Record<string, never>
+	>,
+	TApiRuntimeFrom extends string = never,
+> = ClientPluginDefinition<
+	TOverrides,
+	TRoutes,
+	TId,
+	TProviderConfig,
+	TApiRuntimeFrom
+> &
+	([TApiRuntimeFrom] extends [never]
+		? unknown
+		: { readonly apiRuntimeFrom: TApiRuntimeFrom });
+
+interface DefineClientPluginWithOverrides<TOverrides> {
+	<
+		const TId extends string,
+		TRoutes extends Record<string, Route>,
+		const TProviderConfig extends Readonly<Record<string, unknown>> = Readonly<
+			Record<string, never>
+		>,
+		const TApiRuntimeFrom extends string = never,
+	>(
+		plugin: IdentifiedClientPluginDefinition<
+			TId,
+			TOverrides,
+			TRoutes,
+			TProviderConfig,
+			TApiRuntimeFrom
+		>,
+	): IdentifiedClientPluginDefinition<
+		TId,
+		TOverrides,
+		TRoutes,
+		TProviderConfig,
+		TApiRuntimeFrom
+	>;
+}
+
 export type {
 	ClientPlugin,
+	ClientPluginDefinition,
+	ClientPluginRegistration,
 	PluginOverrides,
+	ResolvedClientPluginRuntime,
 } from "../../types";
 
 export {
@@ -74,22 +121,76 @@ export { createClient } from "better-call/client";
  * @example
  * ```ts
  * const messagesPlugin = defineClientPlugin({
- *   name: "messages",
- *   routes: () => ({
- *     messagesList: createRoute("/messages", () => ({ ... }))
+ *   id: "messages",
+ *   resolve: (runtime) => ({
+ *     routes: () => ({
+ *       messagesList: createRoute("/messages", () => ({ ... }))
+ *     }),
+ *     sitemap: () => [{
+ *       url: `${runtime.site.baseURL}${runtime.site.basePath}/messages`,
+ *     }],
  *   }),
- *   sitemap: () => [{ url: "/messages", lastModified: new Date(), priority: 0.8 }]
  * });
  * ```
  *
  * @template TOverrides - The shape of overridable components/functions this plugin requires
  * @template TRoutes - The exact shape of routes this plugin provides (preserves keys and route types)
  */
+export function defineClientPlugin<
+	TOverrides,
+>(): DefineClientPluginWithOverrides<TOverrides>;
+export function defineClientPlugin<
+	const TId extends string,
+	TRoutes extends Record<string, Route>,
+	const TProviderConfig extends Readonly<Record<string, unknown>> = Readonly<
+		Record<string, never>
+	>,
+	const TApiRuntimeFrom extends string = never,
+>(
+	plugin: IdentifiedClientPluginDefinition<
+		TId,
+		Record<string, never>,
+		TRoutes,
+		TProviderConfig,
+		TApiRuntimeFrom
+	>,
+): IdentifiedClientPluginDefinition<
+	TId,
+	Record<string, never>,
+	TRoutes,
+	TProviderConfig,
+	TApiRuntimeFrom
+>;
 export function defineClientPlugin<
 	TOverrides = Record<string, never>,
 	TRoutes extends Record<string, Route> = Record<string, Route>,
+	TProviderConfig extends Readonly<Record<string, unknown>> = Readonly<
+		Record<string, unknown>
+	>,
+	TApiRuntimeFrom extends string = never,
 >(
-	plugin: ClientPlugin<TOverrides, TRoutes>,
-): ClientPlugin<TOverrides, TRoutes> {
+	plugin: ClientPluginDefinition<
+		TOverrides,
+		TRoutes,
+		string,
+		TProviderConfig,
+		TApiRuntimeFrom
+	>,
+): ClientPluginDefinition<
+	TOverrides,
+	TRoutes,
+	string,
+	TProviderConfig,
+	TApiRuntimeFrom
+>;
+export function defineClientPlugin(
+	plugin?: ClientPluginDefinition<any, any, any, any, any>,
+):
+	| ClientPluginDefinition<any, any, any, any, any>
+	| DefineClientPluginWithOverrides<any> {
+	if (plugin === undefined) {
+		return ((definition: any) =>
+			definition) as DefineClientPluginWithOverrides<any>;
+	}
 	return plugin;
 }

package/src/plugins/client/resource/hooks.tsx

@@ -45,7 +45,11 @@ import {
 	type ResourceQueryDef,
 	type ResourcesDeclaration,
 } from "./queries";
-import { useResourceContext, useResourceMutationForDef } from "./internal";
+import {
+	useResourceContext,
+	useResourceMutationForDef,
+	type ResourceContext,
+} from "./internal";
 import {
 	createUseForm,
 	type ResourceFormConfig,
@@ -134,7 +138,7 @@ export type Resource<TResources extends ResourcesDeclaration> = {
 };
 
 export interface CreateResourceConfig<TResources extends ResourcesDeclaration> {
-	/** Plugin name used to resolve plugin-specific request headers. */
+	/** Plugin ID used to resolve plugin-specific request headers. */
 	plugin: string;
 	resources: TResources;
 }
@@ -145,8 +149,7 @@ function createQueryHooks(
 	queryName: string,
 	def: ResourceQueryDef<any, any>,
 ) {
-	const useQueryConfig = (args: readonly unknown[]) => {
-		const context = useResourceContext(plugin);
+	const queryConfig = (args: readonly unknown[], context: ResourceContext) => {
 		return {
 			queryKey: buildQueryKey(resourceName, queryName, def, args),
 			queryFn: (queryContext?: { pageParam?: unknown }) =>
@@ -178,13 +181,23 @@ function createQueryHooks(
 
 	return {
 		use(args: readonly unknown[] = [], options?: ResourceQueryOptions) {
-			return useQuery({
-				...useQueryConfig(args),
-				...(options?.enabled !== undefined ? { enabled: options.enabled } : {}),
-			});
+			const context = useResourceContext(plugin);
+			return useQuery(
+				{
+					...queryConfig(args, context),
+					...(options?.enabled !== undefined
+						? { enabled: options.enabled }
+						: {}),
+				},
+				context.queryClient,
+			);
 		},
 		useSuspense(args: readonly unknown[] = []) {
-			const result = useSuspenseQuery(useQueryConfig(args));
+			const context = useResourceContext(plugin);
+			const result = useSuspenseQuery(
+				queryConfig(args, context),
+				context.queryClient,
+			);
 			// useSuspenseQuery only throws on initial fetch — manually re-throw
 			// refetch errors so Error Boundaries catch them
 			if (result.error && !result.isFetching) {
@@ -193,17 +206,27 @@ function createQueryHooks(
 			return result;
 		},
 		useInfinite(args: readonly unknown[] = [], options?: ResourceQueryOptions) {
-			return useInfiniteQuery({
-				...useQueryConfig(args),
-				...infiniteExtras(args),
-				...(options?.enabled !== undefined ? { enabled: options.enabled } : {}),
-			});
+			const context = useResourceContext(plugin);
+			return useInfiniteQuery(
+				{
+					...queryConfig(args, context),
+					...infiniteExtras(args),
+					...(options?.enabled !== undefined
+						? { enabled: options.enabled }
+						: {}),
+				},
+				context.queryClient,
+			);
 		},
 		useSuspenseInfinite(args: readonly unknown[] = []) {
-			const result = useSuspenseInfiniteQuery({
-				...useQueryConfig(args),
-				...infiniteExtras(args),
-			});
+			const context = useResourceContext(plugin);
+			const result = useSuspenseInfiniteQuery(
+				{
+					...queryConfig(args, context),
+					...infiniteExtras(args),
+				},
+				context.queryClient,
+			);
 			if (result.error && !result.isFetching) {
 				throw result.error;
 			}

package/src/plugins/client/resource/internal.ts

@@ -1,7 +1,7 @@
 "use client";
 
 import { useMutation, useQueryClient } from "@tanstack/react-query";
-import type { UseMutationResult } from "@tanstack/react-query";
+import type { QueryClient, UseMutationResult } from "@tanstack/react-query";
 import { usePluginOverrides, useStack } from "../../../context";
 import { createApiClient } from "../../utils";
 import {
@@ -22,21 +22,34 @@ export interface ResourceOverrides {
 export interface ResourceContext {
 	client: ResourceClient;
 	headers?: HeadersInit;
+	queryClient?: QueryClient;
 	navigate?: (path: string) => void | Promise<void>;
 	refresh?: () => void | Promise<void>;
 }
 
 /** Resolves the plugin overrides and builds the better-call client. */
 export function useResourceContext(plugin: string): ResourceContext {
-	const { api, router } = useStack();
-	const { headers } = usePluginOverrides<ResourceOverrides>(plugin);
+	const { api, plugins, queryClient, router } = useStack();
+	const { headers: overrideHeaders } =
+		usePluginOverrides<ResourceOverrides>(plugin);
+	const pluginApi = plugins?.[plugin]?.api;
+	const mergedHeaders = new Headers(pluginApi?.browserHeaders);
+	if (overrideHeaders !== undefined) {
+		for (const [name, value] of new Headers(overrideHeaders)) {
+			mergedHeaders.set(name, value);
+		}
+	}
+	const headers = mergedHeaders.keys().next().done ? undefined : mergedHeaders;
 	const client = createApiClient({
-		baseURL: api?.baseURL,
-		basePath: api?.basePath,
+		baseURL: pluginApi?.baseURL ?? api?.baseURL,
+		basePath: pluginApi?.basePath ?? api?.basePath,
+		headers,
+		credentials: pluginApi?.credentials,
 	});
 	return {
 		client,
 		headers,
+		queryClient,
 		navigate: router?.navigate,
 		refresh: router?.refresh,
 	};
@@ -64,73 +77,76 @@ export function useResourceMutationForDef(
 	resource: ResourceDef,
 	def: ResourceMutationDef<any, any> | undefined,
 ): UseMutationResult<unknown, Error, unknown> {
-	const queryClient = useQueryClient();
+	const queryClient = useQueryClient(context.queryClient);
 	const { client, headers, refresh } = context;
 
-	return useMutation<unknown, Error, unknown>({
-		mutationKey: [resourceName, mutationName],
-		mutationFn: (vars: unknown) => {
-			if (!def) {
-				throw new Error(
-					`Resource "${resourceName}" has no "${mutationName}" mutation declared`,
-				);
-			}
-			return runResourceMutation(client, def, vars, headers);
-		},
-		onSuccess: async (result, variables) => {
-			if (!def) return;
-
-			// Seed a query cache entry (e.g. detail) from the mutation result
-			if (def.setData) {
-				const keyArgs = def.setData.args(result);
-				const targetName = def.setData.query ?? "detail";
-				const targetDef = resource.queries[targetName];
-				if (keyArgs && targetDef) {
-					const key = buildQueryKey(
-						resourceName,
-						targetName,
-						targetDef,
-						keyArgs,
-					);
-					queryClient.setQueryData(key, (previous) =>
-						def.setData?.updater
-							? def.setData.updater(previous, result)
-							: result,
+	return useMutation<unknown, Error, unknown>(
+		{
+			mutationKey: [resourceName, mutationName],
+			mutationFn: (vars: unknown) => {
+				if (!def) {
+					throw new Error(
+						`Resource "${resourceName}" has no "${mutationName}" mutation declared`,
 					);
 				}
-			}
+				return runResourceMutation(client, def, vars, headers);
+			},
+			onSuccess: async (result, variables) => {
+				if (!def) return;
 
-			// Remove a cache entry tied to the successful mutation variables
-			if (def.removeData) {
-				const keyArgs = def.removeData.args(result, variables);
-				const targetName = def.removeData.query ?? "detail";
-				const targetDef = resource.queries[targetName];
-				if (keyArgs && targetDef) {
-					queryClient.removeQueries({
-						queryKey: buildQueryKey(
+				// Seed a query cache entry (e.g. detail) from the mutation result
+				if (def.setData) {
+					const keyArgs = def.setData.args(result);
+					const targetName = def.setData.query ?? "detail";
+					const targetDef = resource.queries[targetName];
+					if (keyArgs && targetDef) {
+						const key = buildQueryKey(
 							resourceName,
 							targetName,
 							targetDef,
 							keyArgs,
-						),
-						exact: true,
-					});
+						);
+						queryClient.setQueryData(key, (previous) =>
+							def.setData?.updater
+								? def.setData.updater(previous, result)
+								: result,
+						);
+					}
 				}
-			}
 
-			// Invalidate declared key prefixes — awaited, in declaration order
-			for (const target of def.invalidates ?? []) {
-				await queryClient.invalidateQueries({
-					queryKey: invalidateTargetToKey(target),
-					refetchType: def.refetchType,
-				});
-			}
+				// Remove a cache entry tied to the successful mutation variables
+				if (def.removeData) {
+					const keyArgs = def.removeData.args(result, variables);
+					const targetName = def.removeData.query ?? "detail";
+					const targetDef = resource.queries[targetName];
+					if (keyArgs && targetDef) {
+						queryClient.removeQueries({
+							queryKey: buildQueryKey(
+								resourceName,
+								targetName,
+								targetDef,
+								keyArgs,
+							),
+							exact: true,
+						});
+					}
+				}
 
-			// Refresh server-side cache (e.g. Next.js router cache) unless the
-			// mutation opts out (public mutations whose success UI is client state)
-			if (refresh && def.refresh !== false) {
-				await refresh();
-			}
+				// Invalidate declared key prefixes — awaited, in declaration order
+				for (const target of def.invalidates ?? []) {
+					await queryClient.invalidateQueries({
+						queryKey: invalidateTargetToKey(target),
+						refetchType: def.refetchType,
+					});
+				}
+
+				// Refresh server-side cache (e.g. Next.js router cache) unless the
+				// mutation opts out (public mutations whose success UI is client state)
+				if (refresh && def.refresh !== false) {
+					await refresh();
+				}
+			},
 		},
-	});
+		queryClient,
+	);
 }

package/src/plugins/client/resource/queries.ts

@@ -259,10 +259,9 @@ export async function runResourceQuery(
 /**
  * Executes a mutation declaration: fetch → error-check → unwrap.
  *
- * `headers` supports plugins whose public hooks take an explicit client
- * config (e.g. embeddable components) instead of resolving it from
- * `usePluginOverrides` — same as the `headers` parameter on
- * `createResourceQueryKeys`.
+ * `headers` forwards already-resolved request headers to the resource client,
+ * matching the `headers` parameter on `createResourceQueryKeys`. Header
+ * resolution belongs to the caller's runtime.
  */
 export async function runResourceMutation(
 	client: ResourceClient,

package/src/plugins/client/resource/use-form.ts

@@ -108,28 +108,31 @@ export function createUseForm(
 			config.id !== undefined &&
 			!!detailDef;
 
-		const recordQuery = useQuery<unknown, Error>({
-			queryKey: detailDef
-				? buildQueryKey(resourceName, detailName, detailDef, detailArgs)
-				: [resourceName, detailName],
-			queryFn: () => {
-				if (!detailDef) {
-					// Unreachable: the query is disabled when detailDef is missing
-					throw new Error(
-						`Resource "${resourceName}" has no "${detailName}" query declared`,
+		const recordQuery = useQuery<unknown, Error>(
+			{
+				queryKey: detailDef
+					? buildQueryKey(resourceName, detailName, detailDef, detailArgs)
+					: [resourceName, detailName],
+				queryFn: () => {
+					if (!detailDef) {
+						// Unreachable: the query is disabled when detailDef is missing
+						throw new Error(
+							`Resource "${resourceName}" has no "${detailName}" query declared`,
+						);
+					}
+					return runResourceQuery(
+						context.client,
+						detailDef,
+						detailArgs,
+						undefined,
+						context.headers,
 					);
-				}
-				return runResourceQuery(
-					context.client,
-					detailDef,
-					detailArgs,
-					undefined,
-					context.headers,
-				);
+				},
+				...SHARED_QUERY_CONFIG,
+				enabled: detailEnabled,
 			},
-			...SHARED_QUERY_CONFIG,
-			enabled: detailEnabled,
-		});
+			context.queryClient,
+		);
 
 		const record = hasExternalRecord
 			? (config.record ?? null)

package/src/plugins/client/resource/use-select.ts

@@ -89,19 +89,22 @@ export function createUseSelect(
 		}
 
 		const listArgs = config.searchArgs(debouncedSearch);
-		const listQuery = useQuery<unknown, Error>({
-			queryKey: buildQueryKey(resourceName, listName, listDef, listArgs),
-			queryFn: () =>
-				runResourceQuery(
-					context.client,
-					listDef,
-					listArgs,
-					undefined,
-					context.headers,
-				),
-			...SHARED_QUERY_CONFIG,
-			enabled,
-		});
+		const listQuery = useQuery<unknown, Error>(
+			{
+				queryKey: buildQueryKey(resourceName, listName, listDef, listArgs),
+				queryFn: () =>
+					runResourceQuery(
+						context.client,
+						listDef,
+						listArgs,
+						undefined,
+						context.headers,
+					),
+				...SHARED_QUERY_CONFIG,
+				enabled,
+			},
+			context.queryClient,
+		);
 
 		const items = (listQuery.data as TItem[] | null | undefined) ?? [];
 
@@ -126,30 +129,33 @@ export function createUseSelect(
 				? values.filter((value) => !fetchedValues.has(value))
 				: [];
 
-		const preloadQueries = useQueries({
-			queries: missingValues.map((value) => {
-				const args = (
-					config.preload as NonNullable<typeof config.preload>
-				).args(value);
-				return {
-					queryKey: buildQueryKey(
-						resourceName,
-						preloadName,
-						preloadDef as NonNullable<typeof preloadDef>,
-						args,
-					),
-					queryFn: () =>
-						runResourceQuery(
-							context.client,
+		const preloadQueries = useQueries(
+			{
+				queries: missingValues.map((value) => {
+					const args = (
+						config.preload as NonNullable<typeof config.preload>
+					).args(value);
+					return {
+						queryKey: buildQueryKey(
+							resourceName,
+							preloadName,
 							preloadDef as NonNullable<typeof preloadDef>,
 							args,
-							undefined,
-							context.headers,
 						),
-					...SHARED_QUERY_CONFIG,
-				};
-			}),
-		});
+						queryFn: () =>
+							runResourceQuery(
+								context.client,
+								preloadDef as NonNullable<typeof preloadDef>,
+								args,
+								undefined,
+								context.headers,
+							),
+						...SHARED_QUERY_CONFIG,
+					};
+				}),
+			},
+			context.queryClient,
+		);
 
 		const preloadedItems = preloadQueries
 			.map((query) => query.data as TItem | null | undefined)