@classytic/arc-next 0.4.1 → 0.5.0

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 { 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;
@@ -452,46 +455,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 +597,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) => {
@@ -745,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: () => {}
@@ -777,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

@@ -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 };

package/dist/mutation.js

@@ -21,6 +21,25 @@ let toastHandler = {
 function configureToast(handler) {
 	toastHandler = handler;
 }
+/**
+* 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`);
+* }
+*/
+function getToastHandler() {
+	return toastHandler;
+}
 function showToast(type, messages, data, variables, error, handler) {
 	const activeHandler = handler ?? toastHandler;
 	if (type === "success") {
@@ -163,4 +182,4 @@ function useOptimisticMutation(config) {
 }
 
 //#endregion
-export { configureToast, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };
+export { configureToast, getToastHandler, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };

package/dist/prefetch.d.ts

@@ -1,4 +1,4 @@
-import { QueryClient, dehydrate } from "@tanstack/react-query";
+import { HydrationBoundary, InfiniteData, QueryClient, dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.d.ts
 interface PrefetchAuthContext {
@@ -51,6 +51,17 @@ interface CrudPrefetcher {
    * Only available when the API has a `getTree` method (tree preset).
    */
   prefetchTree: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
+  /**
+   * Prefetch an infinite list query (cursor / page-based pagination). Uses the
+   * same query keys as `useInfiniteList` and seeds the `{ pages, pageParams }`
+   * shape TanStack Query expects for `useInfiniteQuery` — a flat
+   * `prefetchQuery` would NOT match the cache shape and the client hook would
+   * re-fetch from scratch, defeating the prefetch.
+   *
+   * @example
+   * await productsPrefetcher.prefetchInfiniteList(queryClient, { limit: 20 });
+   */
+  prefetchInfiniteList: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
 }
 /**
  * Create server-safe prefetch helpers for CRUD queries.
@@ -121,4 +132,4 @@ declare function createCrudPrefetcher(api: {
   }) => Promise<unknown>;
 }, entityKey: string): CrudPrefetcher;
 //#endregion
-export { CrudPrefetcher, PrefetchAuthContext, PrefetchDetailOptions, PrefetchOptions, createCrudPrefetcher, dehydrate };
+export { CrudPrefetcher, HydrationBoundary, type InfiniteData, PrefetchAuthContext, PrefetchDetailOptions, PrefetchOptions, createCrudPrefetcher, dehydrate };

package/dist/prefetch.js

@@ -1,5 +1,5 @@
-import { createQueryKeys } from "./query.js";
-import { dehydrate } from "@tanstack/react-query";
+import { createQueryKeys } from "./cache.js";
+import { HydrationBoundary, dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.ts
 /**
@@ -118,9 +118,33 @@ function createCrudPrefetcher(api, entityKey) {
 				}),
 				staleTime: options.staleTime
 			});
+		},
+		async prefetchInfiniteList(queryClient, params = {}, options = {}) {
+			const { organizationId: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
+			const scope = orgId ? "tenant" : "super-admin";
+			const queryKey = [...KEYS.scopedList(scope, {
+				...orgId ? { organizationId: orgId } : {},
+				...restParams
+			}), "infinite"];
+			await queryClient.prefetchInfiniteQuery({
+				queryKey,
+				queryFn: ({ pageParam }) => api.getAll({
+					params: {
+						...restParams,
+						...pageParam ? { page: pageParam } : {}
+					},
+					token: options.token ?? null,
+					organizationId: orgId,
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
+				}),
+				initialPageParam: 1,
+				getNextPageParam: () => void 0,
+				staleTime: options.staleTime
+			});
 		}
 	};
 }
 
 //#endregion
-export { createCrudPrefetcher, dehydrate };
+export { HydrationBoundary, createCrudPrefetcher, dehydrate };

package/dist/presets/bulk.d.ts

@@ -0,0 +1,42 @@
+import { BaseApi, BulkCreateResponse, BulkDeleteResponse, BulkUpdateResponse, ScopedArgs } from "../api.js";
+
+//#region src/presets/bulk.d.ts
+interface BulkMethods<TDoc, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
+  /** Insert many docs in one round-trip. Backend mounts `POST /:resource/bulk`. */
+  bulkCreate(args: ScopedArgs & {
+    data: TCreate[];
+  }): Promise<BulkCreateResponse<TDoc>>;
+  /**
+   * Update all docs matching `filter` with `data`.
+   * Backend mounts `PATCH /:resource/bulk`.
+   */
+  bulkUpdate(args: ScopedArgs & {
+    filter: Record<string, unknown>;
+    data: TUpdate;
+  }): Promise<BulkUpdateResponse>;
+  /**
+   * Delete all docs matching `filter`.
+   * Backend mounts `DELETE /:resource/bulk`.
+   */
+  bulkDelete(args: ScopedArgs & {
+    filter: Record<string, unknown>;
+  }): Promise<BulkDeleteResponse>;
+}
+/**
+ * Adds bulk preset methods to a BaseApi.
+ *
+ * Mirrors arc's `bulk` preset — three /bulk routes for batch ops. Bulk endpoints
+ * require explicit per-resource permissions on the backend (the standard CRUD
+ * `allowPublic()` doesn't cover them).
+ *
+ * @example
+ * import { withBulk } from '@classytic/arc-next/presets/bulk';
+ * const todos = withBulk(createCrudApi<Todo>('todos'));
+ *
+ * await todos.bulkCreate({ data: [{ title: 'A' }, { title: 'B' }] });
+ * await todos.bulkUpdate({ filter: { status: 'pending' }, data: { status: 'archived' } });
+ * await todos.bulkDelete({ filter: { archivedBefore: '2024-01-01' } });
+ */
+declare function withBulk<TDoc, TCreate, TUpdate>(api: BaseApi<TDoc, TCreate, TUpdate>): BaseApi<TDoc, TCreate, TUpdate> & BulkMethods<TDoc, TCreate, TUpdate>;
+//#endregion
+export { BulkMethods, withBulk };

package/dist/presets/bulk.js

@@ -0,0 +1,50 @@
+//#region src/presets/bulk.ts
+/**
+* Adds bulk preset methods to a BaseApi.
+*
+* Mirrors arc's `bulk` preset — three /bulk routes for batch ops. Bulk endpoints
+* require explicit per-resource permissions on the backend (the standard CRUD
+* `allowPublic()` doesn't cover them).
+*
+* @example
+* import { withBulk } from '@classytic/arc-next/presets/bulk';
+* const todos = withBulk(createCrudApi<Todo>('todos'));
+*
+* await todos.bulkCreate({ data: [{ title: 'A' }, { title: 'B' }] });
+* await todos.bulkUpdate({ filter: { status: 'pending' }, data: { status: 'archived' } });
+* await todos.bulkDelete({ filter: { archivedBefore: '2024-01-01' } });
+*/
+function withBulk(api) {
+	return Object.assign(api, {
+		async bulkCreate({ token = null, organizationId = null, data, options = {} }) {
+			return api.request("POST", `${api.baseUrl}/bulk`, {
+				token,
+				organizationId,
+				data: { items: data },
+				options
+			});
+		},
+		async bulkUpdate({ token = null, organizationId = null, filter, data, options = {} }) {
+			return api.request("PATCH", `${api.baseUrl}/bulk`, {
+				token,
+				organizationId,
+				data: {
+					filter,
+					data
+				},
+				options
+			});
+		},
+		async bulkDelete({ token = null, organizationId = null, filter, options = {} }) {
+			return api.request("DELETE", `${api.baseUrl}/bulk`, {
+				token,
+				organizationId,
+				data: { filter },
+				options
+			});
+		}
+	});
+}
+
+//#endregion
+export { withBulk };

package/dist/presets/search.d.ts

@@ -0,0 +1,55 @@
+import { ApiResponse, BaseApi, PaginatedResponse, ScopedArgs } from "../api.js";
+
+//#region src/presets/search.d.ts
+interface SearchPresetMethods<TDoc> {
+  /**
+   * Engine-backed full-text search (Elastic, Algolia, Typesense...).
+   * Backend mounts `POST /:resource/search` via `searchPreset()`.
+   */
+  searchEngine<TResult = TDoc, TBody extends Record<string, unknown> = Record<string, unknown>>(args?: ScopedArgs & {
+    /** Free-text query forwarded as `body.query`. */query?: string; /** Engine-specific options merged into the request body. */
+    body?: TBody; /** Override path (default `/search`). */
+    path?: string;
+  }): Promise<ApiResponse<TResult[]> | PaginatedResponse<TResult>>;
+  /**
+   * Vector / semantic similarity (Atlas, Pinecone, Qdrant...).
+   * Backend mounts `POST /:resource/search-similar`.
+   */
+  searchSimilar<TResult = TDoc, TBody extends Record<string, unknown> = Record<string, unknown>>(args?: ScopedArgs & {
+    /** Text query — backend embeds and searches for nearest neighbors. */query?: string; /** Pre-computed embedding vector — used directly for similarity search. */
+    vector?: number[]; /** Vector-engine options (`topK`, `filter`, `index`, ...). */
+    body?: TBody; /** Override path (default `/search-similar`). */
+    path?: string;
+  }): Promise<ApiResponse<TResult[]>>;
+  /**
+   * Convert text/media to a vector embedding via the engine the resource is wired to.
+   * Backend mounts `POST /:resource/embed`.
+   */
+  embed(args: ScopedArgs & {
+    /** Text or array of texts to embed. */input: string | string[]; /** Embed-engine options (`model`, `dimensions`, ...). */
+    body?: Record<string, unknown>; /** Override path (default `/embed`). */
+    path?: string;
+  }): Promise<ApiResponse<number[] | number[][]>>;
+}
+/**
+ * Adds search preset methods to a BaseApi.
+ *
+ * Mirrors arc's `searchPreset()` — three POST routes for engine-backed search,
+ * vector similarity, and embedding generation. Each route is independently
+ * permission-gated on the backend.
+ *
+ * Differs from {@link BaseApi.search} (a GET against the list endpoint with
+ * filter params) — that's the legacy filtered-list pattern. These methods hit
+ * the new POST routes the preset mounts.
+ *
+ * @example
+ * import { withSearchPreset } from '@classytic/arc-next/presets/search';
+ * const places = withSearchPreset(createCrudApi<Place>('places'));
+ *
+ * await places.searchEngine({ query: 'park', body: { filter: { category: 'park' } } });
+ * await places.searchSimilar({ vector: [0.1, 0.2, ...], body: { topK: 5 } });
+ * await places.embed({ input: 'hello world' });
+ */
+declare function withSearchPreset<TDoc, TCreate, TUpdate>(api: BaseApi<TDoc, TCreate, TUpdate>): BaseApi<TDoc, TCreate, TUpdate> & SearchPresetMethods<TDoc>;
+//#endregion
+export { SearchPresetMethods, withSearchPreset };

package/dist/presets/search.js

@@ -0,0 +1,60 @@
+//#region src/presets/search.ts
+/**
+* Adds search preset methods to a BaseApi.
+*
+* Mirrors arc's `searchPreset()` — three POST routes for engine-backed search,
+* vector similarity, and embedding generation. Each route is independently
+* permission-gated on the backend.
+*
+* Differs from {@link BaseApi.search} (a GET against the list endpoint with
+* filter params) — that's the legacy filtered-list pattern. These methods hit
+* the new POST routes the preset mounts.
+*
+* @example
+* import { withSearchPreset } from '@classytic/arc-next/presets/search';
+* const places = withSearchPreset(createCrudApi<Place>('places'));
+*
+* await places.searchEngine({ query: 'park', body: { filter: { category: 'park' } } });
+* await places.searchSimilar({ vector: [0.1, 0.2, ...], body: { topK: 5 } });
+* await places.embed({ input: 'hello world' });
+*/
+function withSearchPreset(api) {
+	return Object.assign(api, {
+		async searchEngine({ token = null, organizationId = null, query, body, path = "/search", options = {} } = {}) {
+			const requestBody = { ...body ?? {} };
+			if (query !== void 0) requestBody.query = query;
+			return api.request("POST", `${api.baseUrl}${path}`, {
+				token,
+				organizationId,
+				data: requestBody,
+				options
+			});
+		},
+		async searchSimilar({ token = null, organizationId = null, query, vector, body, path = "/search-similar", options = {} } = {}) {
+			const requestBody = { ...body ?? {} };
+			if (query !== void 0) requestBody.query = query;
+			if (vector !== void 0) requestBody.vector = vector;
+			return api.request("POST", `${api.baseUrl}${path}`, {
+				token,
+				organizationId,
+				data: requestBody,
+				options
+			});
+		},
+		async embed({ token = null, organizationId = null, input, body, path = "/embed", options = {} }) {
+			const requestBody = {
+				input,
+				...body ?? {}
+			};
+			return api.request("POST", `${api.baseUrl}${path}`, {
+				token,
+				organizationId,
+				data: requestBody,
+				options
+			});
+		}
+	});
+}
+
+//#endregion
+export { withSearchPreset };

package/dist/presets/slug.d.ts

@@ -0,0 +1,28 @@
+import { ApiResponse, BaseApi, ScopedArgs } from "../api.js";
+
+//#region src/presets/slug.d.ts
+interface SlugLookupMethods<TDoc> {
+  /** Fetch a single doc by slug. Backend mounts `GET /:resource/slug/:slug`. */
+  getBySlug(args: ScopedArgs & {
+    slug: string;
+    params?: {
+      select?: string;
+      populate?: string | string[];
+    };
+  }): Promise<ApiResponse<TDoc>>;
+}
+/**
+ * Adds slug-lookup preset methods to a BaseApi.
+ *
+ * Mirrors arc's `slugLookup` preset — exposes `getBySlug` for resources keyed
+ * by URL-friendly slugs alongside the canonical id.
+ *
+ * @example
+ * import { withSlugLookup } from '@classytic/arc-next/presets/slug';
+ * const categories = withSlugLookup(createCrudApi<Category>('categories'));
+ *
+ * const cat = await categories.getBySlug({ slug: 'engineering' });
+ */
+declare function withSlugLookup<TDoc, TCreate, TUpdate>(api: BaseApi<TDoc, TCreate, TUpdate>): BaseApi<TDoc, TCreate, TUpdate> & SlugLookupMethods<TDoc>;
+//#endregion
+export { SlugLookupMethods, withSlugLookup };