@classytic/arc-next 0.4.1 → 0.6.0

package/dist/hooks.d.ts

@@ -1,30 +1,73 @@
 import { ArcClient, UseRouterHook } from "./client.js";
-import { BaseApi, FilterOperator } from "./api.js";
+import { AggResult, AggRow, BaseApi } from "./api.js";
+import { CacheUtils, QueryKeys } from "./cache.js";
 import { MutationCallbacks, MutationMessages, TransitionMutationReturn } from "./mutation.js";
-import { CacheUtils, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, QueryKeys } from "./query.js";
-import { QueryKey } from "@tanstack/react-query";
+import { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, RequestPassthrough } from "./query.js";
+import { SoftDeleteMethods } from "./presets/soft-delete.js";
+import { BulkMethods } from "./presets/bulk.js";
+import { SlugLookupMethods } from "./presets/slug.js";
+import { TreeMethods } from "./presets/tree.js";
+import { SearchPresetMethods } from "./presets/search.js";
+import { QueryKey, UseQueryResult } from "@tanstack/react-query";
 
 //#region src/hooks.d.ts
 /**
  * CRUD API interface accepted by createCrudHooks.
  *
- * Derived from BaseApi via Pick so the types are always in sync.
- * BaseApi instances satisfy this exactly (same source of truth).
- * Custom implementations just need to match BaseApi's method signatures.
+ * Always-on surface (CRUD + universal helpers) is derived from BaseApi via Pick
+ * so types stay in sync. Preset surfaces are optional intersections of the
+ * corresponding `XxxMethods` interfaces, so a `withSearchPreset(api)` result
+ * satisfies CrudApi & gets `searchEngine`/`searchSimilar`/`embed` typed without
+ * any cast — yet a vanilla `createCrudApi('todos')` instance has none of them
+ * in autocomplete unless you opt in.
  */
 type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, 'getAll' | 'getById' | 'create' | 'update' | 'delete'> & {
   upload?: BaseApi<T, TCreate, TUpdate>['upload'];
-  search?: BaseApi<T, TCreate, TUpdate>['search'];
-  getDeleted?: BaseApi<T, TCreate, TUpdate>['getDeleted'];
-  restore?: BaseApi<T, TCreate, TUpdate>['restore'];
-  bulkCreate?: BaseApi<T, TCreate, TUpdate>['bulkCreate'];
-  bulkUpdate?: BaseApi<T, TCreate, TUpdate>['bulkUpdate'];
-  bulkDelete?: BaseApi<T, TCreate, TUpdate>['bulkDelete'];
-  getBySlug?: BaseApi<T, TCreate, TUpdate>['getBySlug'];
-  getTree?: BaseApi<T, TCreate, TUpdate>['getTree'];
-  getChildren?: BaseApi<T, TCreate, TUpdate>['getChildren'];
-  findBy?: BaseApi<T, TCreate, TUpdate>['findBy'];
-};
+  dispatchAction?: BaseApi<T, TCreate, TUpdate>['dispatchAction'];
+  invokeRoute?: BaseApi<T, TCreate, TUpdate>['invokeRoute']; /** Declared aggregations (arc 2.13+). Always available on BaseApi. */
+  aggregate?: BaseApi<T, TCreate, TUpdate>['aggregate'];
+} & Partial<SoftDeleteMethods<T>> & Partial<BulkMethods<T, TCreate, TUpdate>> & Partial<SlugLookupMethods<T>> & Partial<TreeMethods<T>> & Partial<SearchPresetMethods<T>>;
+/** Args + options for `useAggregation`. Mirrors `ListQueryOptions` for DX consistency. */
+interface AggregationQueryOptions<TRow extends AggRow = AggRow, TData = AggResult<TRow>> {
+  /** Bypass auth gate (for public dashboards behind `allowPublic` permissions). */
+  public?: boolean;
+  /** Skip the query (e.g. while a parent filter is being assembled). */
+  enabled?: boolean;
+  /** Per-call staleTime override. Defaults to factory's `defaults.staleTime`. */
+  staleTime?: number;
+  /** Per-call gcTime override. */
+  gcTime?: number;
+  /**
+   * Refetch on window focus. Aggregations / dashboards usually want this OFF —
+   * long-running compute. Defaults to `false` regardless of factory config.
+   */
+  refetchOnWindowFocus?: boolean;
+  /** Periodic refetch (ms or `false`). Set for live dashboards. */
+  refetchInterval?: number | false;
+  /** Continue polling while the tab is in the background. */
+  refetchIntervalInBackground?: boolean;
+  /**
+   * Transform `AggResult<TRow>` before exposing it. Common pattern is to
+   * pluck the rows array directly:
+   *   `select: (r) => r.rows`
+   * Or compute a derived value:
+   *   `select: (r) => r.rows.reduce((acc, x) => acc + x.total, 0)`
+   * Runs on each render after structural-sharing dedupe.
+   */
+  select?: (data: AggResult<TRow>) => TData;
+  /**
+   * Pass-through to the underlying fetch call. Use for Next.js ISR — pass
+   * `request: { revalidate: 60, tags: ['orders'] }` so the server-side fetch
+   * cache participates in `revalidateTag('orders')` invalidations alongside
+   * TanStack's client cache.
+   */
+  request?: RequestPassthrough;
+  /**
+   * Show this data while the real query is loading / re-fetching with
+   * different filters. Smooths fast filter switches on dashboards.
+   */
+  placeholderData?: AggResult<TRow> | ((prev: AggResult<TRow> | undefined) => AggResult<TRow> | undefined);
+}
 interface CrudHooksConfig<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
   api: CrudApi<T, TCreate, TUpdate>;
   entityKey: string;
@@ -147,9 +190,85 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
   useDetailBySlug: (slug: string | null, options?: DetailQueryOptions<T>) => DetailQueryResult<T>;
   useTree: (params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
   useChildren: (parentId: string | null, params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
-  useFindBy: (field: string, value: unknown, options?: ListQueryOptions<T> & {
-    operator?: FilterOperator;
-  }) => ListQueryResult<T>;
+  /**
+   * Mutation against arc's unified action router (`POST /:id/action`).
+   * Server discriminates on `body.action`. Use for state transitions
+   * (approve/cancel/dispatch) instead of bespoke routes.
+   */
+  useAction: <TResult = T, TBody extends Record<string, unknown> = Record<string, unknown>>(options?: {
+    invalidateQueries?: QueryKey[]; /** Default action name. Can be overridden per-call via `mutate({ action })`. */
+    action?: string;
+    messages?: MutationMessages;
+    onSuccess?: (data: TResult, variables: {
+      id: string;
+      action: string;
+      data?: TBody;
+    }) => void;
+    onError?: (error: Error, variables: {
+      id: string;
+      action: string;
+      data?: TBody;
+    }) => void;
+    onSettled?: (data: TResult | undefined, error: Error | null, variables: {
+      id: string;
+      action: string;
+      data?: TBody;
+    }) => void;
+  }) => TransitionMutationReturn<TResult, {
+    id: string;
+    action?: string;
+    data?: TBody;
+  }>;
+  /** Mutation against the search-preset POST `/search` route. */
+  useSearchEngine: <TResult = T, TBody extends Record<string, unknown> = Record<string, unknown>>(options?: {
+    path?: string;
+    messages?: MutationMessages;
+    invalidateQueries?: QueryKey[];
+  }) => TransitionMutationReturn<unknown, {
+    query?: string;
+    body?: TBody;
+  }>;
+  /** Mutation against the search-preset POST `/search-similar` route. */
+  useSearchSimilar: <TResult = T, TBody extends Record<string, unknown> = Record<string, unknown>>(options?: {
+    path?: string;
+    messages?: MutationMessages;
+    invalidateQueries?: QueryKey[];
+  }) => TransitionMutationReturn<unknown, {
+    query?: string;
+    vector?: number[];
+    body?: TBody;
+  }>;
+  /** Mutation against the search-preset POST `/embed` route. */
+  useEmbed: (options?: {
+    path?: string;
+    messages?: MutationMessages;
+    invalidateQueries?: QueryKey[];
+  }) => TransitionMutationReturn<unknown, {
+    input: string | string[];
+    body?: Record<string, unknown>;
+  }>;
+  /**
+   * Query against arc's declarative aggregations (arc v2.13+).
+   * `GET /:resource/aggregations/:name` — wire shape `{ rows: TRow[] }`.
+   *
+   * Cached under `KEYS.aggregation(name, filter)` so multiple call sites with
+   * the same args share one cache entry. Mutation hooks
+   * (`useActions`/`useBulkActions`) auto-invalidate `KEYS.aggregations()` so
+   * dashboards refresh after CRUD writes — opt out via the mutation's
+   * `invalidateQueries` override if you want stale-on-write.
+   *
+   * @example
+   * const { data } = useAggregation<{ day: string; total: number }>({
+   *   name: 'salesByDay',
+   *   filter: { from: '2025-01-01' },
+   *   refetchOnWindowFocus: false,
+   * });
+   * // data.rows: Array<{ day: string; total: number }>
+   */
+  useAggregation: <TRow extends AggRow = AggRow, TData = AggResult<TRow>>(args: {
+    name: string;
+    filter?: Record<string, unknown>;
+  } & AggregationQueryOptions<TRow, TData>) => UseQueryResult<TData>;
   useUpload: (options?: {
     invalidateQueries?: QueryKey[];
     messages?: MutationMessages;
@@ -161,7 +280,6 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
     id?: string;
     path?: string;
   }>;
-  useSearch: (query: string, params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
   useCustomMutation: <TData = unknown, TVariables = unknown>(config: {
     mutationFn: (variables: TVariables) => Promise<TData>;
     invalidateQueries?: QueryKey[];
@@ -170,6 +288,28 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
     onError?: (error: Error, variables: TVariables) => void;
     onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
   }) => TransitionMutationReturn<TData, TVariables>;
+  /**
+   * Subscribe to live CRUD broadcasts and auto-invalidate this resource's
+   * cache. Drop in alongside `createCrudHooks` and every `useList` /
+   * `useDetail` rerenders when the backend emits `<resource>.<op>`.
+   *
+   * `source: 'ws'` uses arc's `websocketPlugin` (`/ws`); `source: 'sse'` uses
+   * `ssePlugin` (`/events/stream`). Pass `enabled: false` to opt out.
+   */
+  useResourceSync: (options?: {
+    source?: 'ws' | 'sse'; /** Override resource name. Defaults to the factory's `entityKey`. */
+    resource?: string; /** Override path (default: `/ws` or `/events/stream`). */
+    path?: string; /** Whether the connection is active. Default: true. */
+    enabled?: boolean; /** Per-event hook fired AFTER cache invalidation. */
+    onEvent?: (event: {
+      operation: 'created' | 'updated' | 'deleted';
+      id?: string;
+      data: unknown;
+    }) => void; /** Connection-state listener. */
+    onConnectionChange?: (connected: boolean) => void;
+  }) => {
+    isConnected: boolean;
+  };
   useNavigation: () => NavigateFn<T>;
 }
 /**
@@ -193,4 +333,4 @@ declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>(
   client
 }: CrudHooksConfig<T, TCreate, TUpdate>): CrudHooksReturn<T, TCreate, TUpdate>;
 //#endregion
-export { BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };
+export { AggregationQueryOptions, BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };

package/dist/hooks.js

@@ -2,10 +2,13 @@
 
 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 { useQueryClient } from "@tanstack/react-query";
-import { useCallback, useRef } from "react";
+import { subscribeToEvents } from "./sse.js";
+import { connectWs } from "./ws.js";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef, useState } from "react";
 
 //#region src/hooks.ts
 let useRouterHook = null;
@@ -163,7 +166,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				data
 			}),
 			queryClient,
-			queryKeys: [KEYS.lists()],
+			queryKeys: [KEYS.lists(), KEYS.aggregations()],
 			shouldToast,
 			optimisticUpdate: (oldData, { data }) => {
 				const optimisticItem = {
@@ -196,7 +199,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				data
 			}),
 			queryClient,
-			queryKeys: [KEYS.lists(), KEYS.details()],
+			queryKeys: [
+				KEYS.lists(),
+				KEYS.details(),
+				KEYS.aggregations()
+			],
 			shouldToast,
 			optimisticUpdate: (oldData, { id, data }) => {
 				const updated = updateListCache(oldData, (arr) => (arr || []).map((item) => resolveItemId(item) === id ? {
@@ -247,7 +254,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				id
 			}),
 			queryClient,
-			queryKeys: [KEYS.lists()],
+			queryKeys: [KEYS.lists(), KEYS.aggregations()],
 			shouldToast,
 			optimisticUpdate: (oldData, { id }) => {
 				return updateListCache(oldData, (arr) => (arr || []).filter((item) => resolveItemId(item) !== id));
@@ -277,7 +284,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					id
 				});
 			},
-			invalidateQueries: [KEYS.lists(), KEYS.custom("deleted")],
+			invalidateQueries: [
+				KEYS.lists(),
+				KEYS.custom("deleted"),
+				KEYS.aggregations()
+			],
 			shouldToast,
 			messages: {
 				success: `${singular} restored successfully`,
@@ -452,46 +463,6 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			toastHandler: instanceToast
 		});
 	}
-	function useSearch(query, params, options) {
-		const auth = resolveAuth();
-		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(), hasStaticAuth),
-			options: {
-				staleTime: queryOpts.staleTime ?? config.staleTime,
-				gcTime: queryOpts.gcTime ?? config.gcTime
-			},
-			select: queryOpts.select
-		});
-	}
 	function useCustomMutation(mutationConfig) {
 		return useMutationWithTransition({
 			mutationFn: mutationConfig.mutationFn,
@@ -634,43 +605,6 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			select: queryOpts.select
 		});
 	}
-	function useFindBy(field, value, options) {
-		const auth = resolveAuth();
-		const token = auth.token;
-		const organizationId = auth.organizationId;
-		const { operator, request: requestOpts, ...queryOpts } = options ?? {};
-		return useListQuery({
-			queryKey: KEYS.custom("findBy", {
-				field,
-				value,
-				operator,
-				organizationId
-			}),
-			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(), hasStaticAuth),
-			options: {
-				staleTime: queryOpts.staleTime ?? config.staleTime,
-				gcTime: queryOpts.gcTime ?? config.gcTime
-			},
-			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
-			itemIdResolver: resolveItemId,
-			select: queryOpts.select
-		});
-	}
 	function useBulkActions() {
 		const bulkCreateMutation = useMutationWithTransition({
 			mutationFn: (vars) => {
@@ -682,7 +616,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					data: vars.data
 				});
 			},
-			invalidateQueries: [KEYS.lists()],
+			invalidateQueries: [KEYS.lists(), KEYS.aggregations()],
 			messages: {
 				success: `${pluralName} created successfully`,
 				error: `Failed to create ${pluralName.toLowerCase()}`
@@ -700,7 +634,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					data: vars.data
 				});
 			},
-			invalidateQueries: [KEYS.lists(), KEYS.details()],
+			invalidateQueries: [
+				KEYS.lists(),
+				KEYS.details(),
+				KEYS.aggregations()
+			],
 			messages: {
 				success: `${pluralName} updated successfully`,
 				error: `Failed to update ${pluralName.toLowerCase()}`
@@ -717,7 +655,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					filter: vars.filter
 				});
 			},
-			invalidateQueries: [KEYS.lists()],
+			invalidateQueries: [KEYS.lists(), KEYS.aggregations()],
 			messages: {
 				success: `${pluralName} deleted successfully`,
 				error: `Failed to delete ${pluralName.toLowerCase()}`
@@ -745,6 +683,224 @@ 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
+		});
+	}
+	function useAggregation(args) {
+		const { name, filter, public: isPublic, enabled = true, staleTime = config.staleTime, gcTime = config.gcTime, refetchOnWindowFocus = false, refetchInterval, refetchIntervalInBackground, select, request, placeholderData } = args;
+		const auth = resolveAuth();
+		const filterKey = auth.organizationId ? {
+			_org: auth.organizationId,
+			...filter ?? {}
+		} : filter ?? {};
+		return useQuery({
+			queryKey: KEYS.aggregation(name, filterKey),
+			queryFn: () => {
+				if (!api.aggregate) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define an aggregate method (requires arc 2.13+)`));
+				return api.aggregate({
+					name,
+					filter,
+					token: auth.token,
+					organizationId: auth.organizationId,
+					...request ? { options: request } : {}
+				});
+			},
+			enabled: !!name && !!api.aggregate && createEnabledRule(auth.token, {
+				public: isPublic,
+				enabled
+			}, resolveAuthMode(), hasStaticAuth),
+			staleTime,
+			gcTime,
+			refetchOnWindowFocus,
+			...select ? { select } : {},
+			...refetchInterval !== void 0 ? { refetchInterval } : {},
+			...refetchIntervalInBackground !== void 0 ? { refetchIntervalInBackground } : {},
+			...placeholderData !== void 0 ? { placeholderData } : {}
+		});
+	}
+	/**
+	* 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() });
+				queryClient.invalidateQueries({ queryKey: KEYS.aggregations() });
+				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: () => {}
@@ -777,10 +933,14 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		useDetailBySlug,
 		useTree,
 		useChildren,
-		useFindBy,
 		useUpload,
-		useSearch,
 		useCustomMutation,
+		useAction,
+		useSearchEngine,
+		useSearchSimilar,
+		useEmbed,
+		useAggregation,
+		useResourceSync,
 		useNavigation
 	};
 }

package/dist/mutation.d.ts

@@ -33,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,4 +124,4 @@ declare function useOptimisticMutation<TData, TVariables>(config: CreateOptimist
   }[];
 }>;
 //#endregion
-export { CreateOptimisticMutationConfig, MutationCallbacks, MutationMessages, OptimisticMutationConfig, TransitionMutationConfig, TransitionMutationReturn, configureToast, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };
+export { CreateOptimisticMutationConfig, MutationCallbacks, MutationMessages, OptimisticMutationConfig, TransitionMutationConfig, TransitionMutationReturn, configureToast, getToastHandler, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };