@classytic/arc-next 0.4.0 → 0.5.0

package/dist/hooks.js

@@ -1,11 +1,14 @@
 "use client";
 
-import { getAuthContext, getAuthMode } from "./client.js";
+import { getAuthMode, getClientAuthContext } from "./client.js";
 import { isKeysetPagination, isOffsetPagination } from "./api.js";
-import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
+import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache } from "./cache.js";
+import { useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
+import { subscribeToEvents } from "./sse.js";
+import { connectWs } from "./ws.js";
 import { useQueryClient } from "@tanstack/react-query";
-import { useCallback, useRef } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 
 //#region src/hooks.ts
 let useRouterHook = null;
@@ -21,12 +24,17 @@ let useRouterHook = null;
 function configureNavigation(hook) {
 	useRouterHook = hook;
 }
-function createEnabledRule(token, options, authMode = getAuthMode()) {
+function createEnabledRule(token, options, authMode = getAuthMode(), hasStaticAuth = false) {
 	if (authMode === "cookie" || options.public) return options.enabled ?? true;
+	if (hasStaticAuth) return options.enabled ?? true;
 	return options.enabled !== void 0 ? options.enabled && !!token : !!token;
 }
 function createCrudHooks({ api, entityKey, singular, plural, idField, defaults = {}, callbacks = {}, client }) {
 	const pluralName = plural ?? `${singular}s`;
+	/** Resolve auth context — per-client auth takes priority over global */
+	const resolveAuth = () => getClientAuthContext(client);
+	/** Whether auth is provided via static config (headers, internalApiKey, per-client auth) — no token needed for enablement */
+	const hasStaticAuth = !!(client?.config?.defaultHeaders || client?.config?.internalApiKey || client?.auth);
 	/** Extract ID from an item using configured idField, falling back to _id → id */
 	function resolveItemId(item) {
 		if (!item || typeof item !== "object") return null;
@@ -60,12 +68,12 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		let token;
 		let params;
 		let options;
-		if (tokenOrParams === null || typeof tokenOrParams === "string") {
+		if (typeof tokenOrParams === "string" || tokenOrParams === null && maybeOptions !== void 0) {
 			token = tokenOrParams;
 			params = paramsOrOptions ?? {};
 			options = maybeOptions ?? {};
 		} else {
-			const auth = getAuthContext();
+			const auth = resolveAuth();
 			token = auth.token;
 			params = tokenOrParams ?? {};
 			options = paramsOrOptions ?? {};
@@ -91,7 +99,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime,
@@ -101,7 +109,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				refetchIntervalInBackground: queryOpts.refetchIntervalInBackground
 			},
 			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.detail(id),
+			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
 			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
@@ -109,11 +117,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 	function useDetail(id, tokenOrOptions, maybeOptions) {
 		let token;
 		let options;
-		if (tokenOrOptions === null || typeof tokenOrOptions === "string") {
+		if (typeof tokenOrOptions === "string" || tokenOrOptions === null && maybeOptions !== void 0) {
 			token = tokenOrOptions;
 			options = maybeOptions ?? {};
 		} else {
-			const auth = getAuthContext();
+			const auth = resolveAuth();
 			token = auth.token;
 			options = tokenOrOptions ?? {};
 			if (auth.organizationId && !options.organizationId) options = {
@@ -122,8 +130,9 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			};
 		}
 		const { organizationId, params: queryParams, request: requestOpts, ...restOptions } = options;
+		const detailKey = KEYS.scopedDetail(id || "", organizationId ?? null);
 		return useDetailQuery({
-			queryKey: queryParams ? [...KEYS.detail(id || ""), queryParams] : KEYS.detail(id || ""),
+			queryKey: queryParams ? [...detailKey, queryParams] : detailKey,
 			queryFn: ({ signal }) => api.getById({
 				id,
 				token,
@@ -134,7 +143,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode()),
+			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -197,13 +206,16 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...item,
 					...data
 				} : item));
-				queryClient.setQueryData(KEYS.detail(id), (current) => current ? {
+				const detailUpdater = (current) => current ? {
 					...current,
 					data: {
 						...current.data || {},
 						...data
 					}
-				} : current);
+				} : current;
+				queryClient.getQueriesData({ queryKey: KEYS.detail(id) }).forEach(([qKey, qData]) => {
+					if (qData) queryClient.setQueryData(qKey, detailUpdater);
+				});
 				return updated;
 			},
 			onSuccess: (raw, { id, data: updateData }) => {
@@ -276,8 +288,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			},
 			toastHandler: instanceToast
 		});
-		const resolveAuth = useCallback((params) => {
-			const auth = getAuthContext();
+		const resolveActionAuth = useCallback((params) => {
+			const auth = resolveAuth();
 			return {
 				...params,
 				token: params.token ?? auth.token,
@@ -288,7 +300,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			create: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await createMutation.mutateAsync(resolveAuth(params)));
+					const entity = extractItem(await createMutation.mutateAsync(resolveActionAuth(params)));
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -299,11 +311,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				} finally {
 					silentRef.current = false;
 				}
-			}, [createMutation, resolveAuth]),
+			}, [createMutation, resolveActionAuth]),
 			update: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await updateMutation.mutateAsync(resolveAuth(params)));
+					const entity = extractItem(await updateMutation.mutateAsync(resolveActionAuth(params)));
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -314,11 +326,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				} finally {
 					silentRef.current = false;
 				}
-			}, [updateMutation, resolveAuth]),
+			}, [updateMutation, resolveActionAuth]),
 			remove: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const result = await deleteMutation.mutateAsync(resolveAuth(params));
+					const result = await deleteMutation.mutateAsync(resolveActionAuth(params));
 					options?.onSuccess?.(result);
 					options?.onSettled?.(result, null);
 					return result;
@@ -329,11 +341,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				} finally {
 					silentRef.current = false;
 				}
-			}, [deleteMutation, resolveAuth]),
+			}, [deleteMutation, resolveActionAuth]),
 			restore: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await restoreMutation.mutateAsync(resolveAuth(params)));
+					const entity = extractItem(await restoreMutation.mutateAsync(resolveActionAuth(params)));
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -344,7 +356,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				} finally {
 					silentRef.current = false;
 				}
-			}, [restoreMutation, resolveAuth]),
+			}, [restoreMutation, resolveActionAuth]),
 			isCreating: createMutation.isPending,
 			isUpdating: updateMutation.isPending,
 			isDeleting: deleteMutation.isPending,
@@ -356,12 +368,12 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		let token;
 		let params;
 		let options;
-		if (tokenOrParams === null || typeof tokenOrParams === "string") {
+		if (typeof tokenOrParams === "string" || tokenOrParams === null && maybeOptions !== void 0) {
 			token = tokenOrParams;
 			params = paramsOrOptions ?? {};
 			options = maybeOptions ?? {};
 		} else {
-			const auth = getAuthContext();
+			const auth = resolveAuth();
 			token = auth.token;
 			params = tokenOrParams ?? {};
 			options = paramsOrOptions ?? {};
@@ -393,7 +405,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			initialPageParam: restParams.after ? restParams.after : 1,
 			getNextPageParam: (lastPage) => {
 				const page = lastPage;
@@ -423,7 +435,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		return useMutationWithTransition({
 			mutationFn: ({ data, id, path }) => {
 				if (!api.upload) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define an upload method`));
-				const auth = getAuthContext();
+				const auth = resolveAuth();
 				return api.upload({
 					token: auth.token,
 					organizationId: auth.organizationId,
@@ -443,46 +455,6 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			toastHandler: instanceToast
 		});
 	}
-	function useSearch(query, params, options) {
-		const auth = getAuthContext();
-		const token = params?.token ?? auth.token;
-		const organizationId = params?.organizationId ?? auth.organizationId;
-		const { organizationId: _, token: _t, ...restParams } = params ?? {};
-		const searchParams = {
-			q: query,
-			...restParams
-		};
-		const { request: requestOpts, ...queryOpts } = options ?? {};
-		const searchKeyParams = organizationId ? {
-			organizationId,
-			...searchParams
-		} : searchParams;
-		return useListQuery({
-			queryKey: [
-				...KEYS.lists(),
-				"search",
-				searchKeyParams
-			],
-			queryFn: ({ signal }) => {
-				if (!api.search) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a search method`));
-				return api.search({
-					token,
-					organizationId,
-					params: searchParams,
-					options: {
-						signal,
-						...requestOpts
-					}
-				});
-			},
-			enabled: !!api.search && query.length > 0 && createEnabledRule(token, queryOpts, resolveAuthMode()),
-			options: {
-				staleTime: queryOpts.staleTime ?? config.staleTime,
-				gcTime: queryOpts.gcTime ?? config.gcTime
-			},
-			select: queryOpts.select
-		});
-	}
 	function useCustomMutation(mutationConfig) {
 		return useMutationWithTransition({
 			mutationFn: mutationConfig.mutationFn,
@@ -495,7 +467,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useDeleted(params, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const mergedParams = params ?? {};
 		const organizationId = mergedParams.organizationId ?? auth.organizationId;
@@ -518,7 +490,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -527,7 +499,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useDetailBySlug(slug, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const resolvedOptions = options ?? {};
 		const organizationId = resolvedOptions.organizationId ?? auth.organizationId;
@@ -547,7 +519,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode()),
+			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -558,7 +530,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useTree(params, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const mergedParams = params ?? {};
 		const organizationId = mergedParams.organizationId ?? auth.organizationId;
@@ -581,7 +553,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -590,7 +562,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useChildren(parentId, params, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const mergedParams = params ?? {};
 		const organizationId = mergedParams.organizationId ?? auth.organizationId;
@@ -614,45 +586,13 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode()),
-			options: {
-				staleTime: queryOpts.staleTime ?? config.staleTime,
-				gcTime: queryOpts.gcTime ?? config.gcTime
-			},
-			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.detail(id),
-			itemIdResolver: resolveItemId,
-			select: queryOpts.select
-		});
-	}
-	function useFindBy(field, value, options) {
-		const auth = getAuthContext();
-		const token = auth.token;
-		const organizationId = auth.organizationId;
-		const { operator, request: requestOpts, ...queryOpts } = options ?? {};
-		return useListQuery({
-			queryKey: KEYS.custom("findBy", field, value, operator),
-			queryFn: ({ signal }) => {
-				if (!api.findBy) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a findBy method`));
-				return api.findBy({
-					token,
-					organizationId,
-					field,
-					value,
-					operator,
-					options: {
-						signal,
-						...requestOpts
-					}
-				});
-			},
-			enabled: !!api.findBy && value !== void 0 && value !== null && createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
 			},
 			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.detail(id),
+			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
 			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
@@ -661,7 +601,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const bulkCreateMutation = useMutationWithTransition({
 			mutationFn: (vars) => {
 				if (!api.bulkCreate) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a bulkCreate method`));
-				const auth = getAuthContext();
+				const auth = resolveAuth();
 				return api.bulkCreate({
 					token: vars.token ?? auth.token,
 					organizationId: vars.organizationId ?? auth.organizationId,
@@ -678,7 +618,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const bulkUpdateMutation = useMutationWithTransition({
 			mutationFn: (vars) => {
 				if (!api.bulkUpdate) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a bulkUpdate method`));
-				const auth = getAuthContext();
+				const auth = resolveAuth();
 				return api.bulkUpdate({
 					token: vars.token ?? auth.token,
 					organizationId: vars.organizationId ?? auth.organizationId,
@@ -696,7 +636,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const bulkDeleteMutation = useMutationWithTransition({
 			mutationFn: (vars) => {
 				if (!api.bulkDelete) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a bulkDelete method`));
-				const auth = getAuthContext();
+				const auth = resolveAuth();
 				return api.bulkDelete({
 					token: vars.token ?? auth.token,
 					organizationId: vars.organizationId ?? auth.organizationId,
@@ -731,6 +671,191 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			isBulkDeleting: bulkDeleteMutation.isPending
 		};
 	}
+	function useAction(options) {
+		const queryClient = useQueryClient();
+		return useMutationWithTransition({
+			mutationFn: (vars) => {
+				if (!api.dispatchAction) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a dispatchAction method`));
+				const action = vars.action ?? options?.action;
+				if (!action) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] useAction: action name required (pass via mutate({ action }) or factory options)`));
+				const auth = resolveAuth();
+				return api.dispatchAction({
+					token: auth.token,
+					organizationId: auth.organizationId,
+					id: vars.id,
+					action,
+					data: vars.data
+				});
+			},
+			invalidateQueries: options?.invalidateQueries ?? [KEYS.lists(), KEYS.details()],
+			onSuccess: (data, vars) => {
+				const action = vars.action ?? options?.action ?? "";
+				if (vars.id) queryClient.invalidateQueries({ queryKey: KEYS.detail(vars.id) });
+				options?.onSuccess?.(data, {
+					id: vars.id,
+					action,
+					data: vars.data
+				});
+			},
+			onError: (error, vars) => {
+				const action = vars.action ?? options?.action ?? "";
+				options?.onError?.(error, {
+					id: vars.id,
+					action,
+					data: vars.data
+				});
+			},
+			onSettled: (data, error, vars) => {
+				const action = vars.action ?? options?.action ?? "";
+				options?.onSettled?.(data, error, {
+					id: vars.id,
+					action,
+					data: vars.data
+				});
+			},
+			messages: options?.messages,
+			toastHandler: instanceToast
+		});
+	}
+	function useSearchEngine(options) {
+		return useMutationWithTransition({
+			mutationFn: (vars) => {
+				if (!api.searchEngine) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a searchEngine method`));
+				const auth = resolveAuth();
+				return api.searchEngine({
+					token: auth.token,
+					organizationId: auth.organizationId,
+					query: vars.query,
+					body: vars.body,
+					path: options?.path
+				});
+			},
+			invalidateQueries: options?.invalidateQueries ?? [],
+			messages: options?.messages,
+			toastHandler: instanceToast
+		});
+	}
+	function useSearchSimilar(options) {
+		return useMutationWithTransition({
+			mutationFn: (vars) => {
+				if (!api.searchSimilar) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a searchSimilar method`));
+				const auth = resolveAuth();
+				return api.searchSimilar({
+					token: auth.token,
+					organizationId: auth.organizationId,
+					query: vars.query,
+					vector: vars.vector,
+					body: vars.body,
+					path: options?.path
+				});
+			},
+			invalidateQueries: options?.invalidateQueries ?? [],
+			messages: options?.messages,
+			toastHandler: instanceToast
+		});
+	}
+	function useEmbed(options) {
+		return useMutationWithTransition({
+			mutationFn: (vars) => {
+				if (!api.embed) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define an embed method`));
+				const auth = resolveAuth();
+				return api.embed({
+					token: auth.token,
+					organizationId: auth.organizationId,
+					input: vars.input,
+					body: vars.body,
+					path: options?.path
+				});
+			},
+			invalidateQueries: options?.invalidateQueries ?? [],
+			messages: options?.messages,
+			toastHandler: instanceToast
+		});
+	}
+	/**
+	* Subscribe to live `<resource>.<operation>` broadcasts from arc and
+	* auto-invalidate this entity's TanStack Query cache.
+	*
+	* - `source: 'ws'` (default) → arc's `websocketPlugin` at `/ws`. Sends a
+	*   `{ type: 'subscribe', resource }` handshake on connect.
+	* - `source: 'sse'` → arc's `ssePlugin` at `/events/stream`. Auto-derives
+	*   patterns from the resource name.
+	*
+	* Both transports invalidate `KEYS.lists()` on `<resource>.created` and
+	* `<resource>.deleted`, and `KEYS.detail(id)` (prefix-matches scoped /
+	* parameterized variants) on `<resource>.updated` / `.deleted`.
+	*/
+	function useResourceSync(options) {
+		const queryClient = useQueryClient();
+		const [isConnected, setIsConnected] = useState(false);
+		const source = options?.source ?? "ws";
+		const resource = options?.resource ?? entityKey;
+		const enabled = options?.enabled ?? true;
+		const path = options?.path;
+		const onEventRef = useRef(options?.onEvent);
+		onEventRef.current = options?.onEvent;
+		const onConnRef = useRef(options?.onConnectionChange);
+		onConnRef.current = options?.onConnectionChange;
+		useEffect(() => {
+			if (!enabled) return;
+			const handleBroadcast = (incomingType, payload) => {
+				const dot = incomingType.lastIndexOf(".");
+				const operation = dot >= 0 ? incomingType.slice(dot + 1) : incomingType;
+				if (operation !== "created" && operation !== "updated" && operation !== "deleted") return;
+				let doc = payload;
+				if (payload && typeof payload === "object" && !Array.isArray(payload) && "data" in payload) {
+					const inner = payload.data;
+					if (inner !== void 0) doc = inner;
+				}
+				const id = typeof doc === "object" && doc !== null ? (() => {
+					const o = doc;
+					const raw = idField ? o[idField] : o._id ?? o.id;
+					return raw != null ? String(raw) : void 0;
+				})() : void 0;
+				queryClient.invalidateQueries({ queryKey: KEYS.lists() });
+				if (id && (operation === "updated" || operation === "deleted")) queryClient.invalidateQueries({ queryKey: KEYS.detail(id) });
+				onEventRef.current?.({
+					operation,
+					id,
+					data: doc
+				});
+			};
+			if (source === "sse") {
+				const handle = subscribeToEvents({
+					resource,
+					path,
+					onConnectionChange: (c) => {
+						setIsConnected(c);
+						onConnRef.current?.(c);
+					},
+					onEvent: (event) => {
+						handleBroadcast(event.type, event.data);
+					}
+				});
+				return () => handle.close();
+			}
+			const handle = connectWs({
+				path,
+				subscribe: [resource],
+				patterns: [`${resource}.`],
+				onConnectionChange: (c) => {
+					setIsConnected(c);
+					onConnRef.current?.(c);
+				},
+				onMessage: (message) => {
+					handleBroadcast(message.type, message.data);
+				}
+			});
+			return () => handle.close();
+		}, [
+			enabled,
+			source,
+			resource,
+			path,
+			queryClient
+		]);
+		return { isConnected };
+	}
 	const resolvedRouterHook = instanceNavigation ?? useRouterHook ?? (() => ({
 		push: () => {},
 		replace: () => {}
@@ -740,7 +865,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const router = resolvedRouterHook();
 		return useCallback((href, item, options = {}) => {
 			const id = resolveItemId(item);
-			if (id) queryClient.setQueryData(KEYS.detail(id), { data: item });
+			if (id) {
+				const orgId = resolveAuth().organizationId;
+				queryClient.setQueryData(KEYS.scopedDetail(id, orgId), { data: item });
+				if (orgId) queryClient.setQueryData(KEYS.detail(id), { data: item });
+			}
 			if (!router) return;
 			const { scroll = true, replace = false } = options;
 			if (replace) router.replace(href, { scroll });
@@ -759,10 +888,13 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		useDetailBySlug,
 		useTree,
 		useChildren,
-		useFindBy,
 		useUpload,
-		useSearch,
 		useCustomMutation,
+		useAction,
+		useSearchEngine,
+		useSearchSimilar,
+		useEmbed,
+		useResourceSync,
 		useNavigation
 	};
 }

package/dist/mutation.d.ts

@@ -1,5 +1,4 @@
 import { ToastHandler } from "./client.js";
-import { QUERY_CONFIGS } from "./query.js";
 import * as _$_tanstack_react_query0 from "@tanstack/react-query";
 import { QueryClient, QueryKey, UseMutateAsyncFunction, UseMutateFunction } from "@tanstack/react-query";
 
@@ -34,6 +33,23 @@ interface TransitionMutationReturn<TData, TVariables> {
  * configureToast({ success: toast.success, error: toast.error });
  */
 declare function configureToast(handler: ToastHandler): void;
+/**
+ * Get the configured toast handler. Returns the console-based default when
+ * no handler has been configured yet.
+ *
+ * Use this when domain code outside the react-query lifecycle needs to fire
+ * ad-hoc success/error toasts using the same handler the SDK uses internally
+ * — avoids the need for consumer SDKs to keep a parallel cache of the handler.
+ *
+ * @example
+ * // In a domain helper outside any mutation lifecycle:
+ * import { getToastHandler } from '@classytic/arc-next/mutation';
+ *
+ * function notifySaved(label: string) {
+ *   getToastHandler().success(`${label} saved`);
+ * }
+ */
+declare function getToastHandler(): ToastHandler;
 interface TransitionMutationConfig<TData, TVariables> {
   mutationFn: (variables: TVariables) => Promise<TData>;
   invalidateQueries?: QueryKey[];
@@ -107,7 +123,5 @@ declare function useOptimisticMutation<TData, TVariables>(config: CreateOptimist
     data: [readonly unknown[], unknown][];
   }[];
 }>;
-/** @deprecated Use `useOptimisticMutation` */
-declare const createOptimisticMutation: typeof useOptimisticMutation;
 //#endregion
-export { CreateOptimisticMutationConfig, MutationCallbacks, MutationMessages, OptimisticMutationConfig, QUERY_CONFIGS, TransitionMutationConfig, TransitionMutationReturn, configureToast, createOptimisticMutation, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };
+export { CreateOptimisticMutationConfig, MutationCallbacks, MutationMessages, OptimisticMutationConfig, TransitionMutationConfig, TransitionMutationReturn, configureToast, getToastHandler, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };