@classytic/arc-next 0.4.1 → 0.5.0

package/dist/client.js

@@ -1,5 +1,51 @@
 //#region src/client.ts
 /**
+* Top-level error codes arc's `errorHandlerPlugin` emits on the response root
+* (`json.code`). Mirrors `statusCodeToCode()` + the special `VALIDATION_ERROR`
+* / `DUPLICATE_KEY` / `INTERNAL_ERROR` branches.
+*
+* Open via intersection with `(string & {})` so unknown codes from custom
+* `errorMappers` / `errorMap` still satisfy the type.
+*/
+/**
+* Top-level HTTP-status error codes arc's `errorHandlerPlugin` emits on
+* `json.code`. Exported as a `const` array first so callers get both
+* compile-time exhaustiveness AND runtime iteration (e.g. building a
+* client-side i18n lookup, or whitelisting which codes get retried).
+*/
+const KNOWN_TOP_LEVEL_CODES = [
+	"BAD_REQUEST",
+	"UNAUTHORIZED",
+	"FORBIDDEN",
+	"NOT_FOUND",
+	"METHOD_NOT_ALLOWED",
+	"CONFLICT",
+	"UNPROCESSABLE_ENTITY",
+	"RATE_LIMITED",
+	"INTERNAL_ERROR",
+	"BAD_GATEWAY",
+	"SERVICE_UNAVAILABLE",
+	"GATEWAY_TIMEOUT",
+	"VALIDATION_ERROR",
+	"DUPLICATE_KEY",
+	"DOMAIN_ERROR"
+];
+/**
+* Nested business-logic codes arc's mixins / preset routes / org guards emit
+* on `json.details.code`. These are distinct from the HTTP-status code above —
+* `error.code` (top-level) vs `error.detailsCode` (nested). When a route
+* returns 403 with `details.code: 'ORG_CONTEXT_REQUIRED'`, hosts read
+* `detailsCode` to disambiguate "missing org context" from "permission denied".
+*/
+const KNOWN_DETAILS_CODES = [
+	"ORG_CONTEXT_REQUIRED",
+	"ORG_ROLE_REQUIRED",
+	"OWNERSHIP_DENIED",
+	"MIXED_UPDATE_SHAPE",
+	"ALL_FIELDS_STRIPPED",
+	"BEFORE_RESTORE_HOOK_ERROR"
+];
+/**
 * Rich API error with status code, response payload, and request metadata.
 * Extends Error so existing `catch (e) { if (e instanceof Error) }` still works.
 *
@@ -28,9 +74,63 @@ var ArcApiError = class extends Error {
 		this.endpoint = options.endpoint;
 		this.method = options.method;
 	}
-	/** Extract field-level validation errors if present (e.g. `{ field: "message" }`) */
+	/**
+	* Top-level error code from arc's response envelope (`json.code`).
+	*
+	* One of {@link ArcTopLevelErrorCode} — covers HTTP-status codes (`FORBIDDEN`,
+	* `CONFLICT`...) plus the dedicated `VALIDATION_ERROR` / `DUPLICATE_KEY`
+	* branches arc emits. Returns `null` if the response carries no envelope.
+	*
+	* @example
+	* if (error.code === 'DUPLICATE_KEY') showRetryAsAdmin();
+	*/
+	get code() {
+		const j = this.json;
+		return j && typeof j.code === "string" ? j.code : null;
+	}
+	/**
+	* Nested business-logic code from arc's `json.details.code` slot.
+	*
+	* Arc's preset mixins (bulk, softDelete) and org guards emit specific reason
+	* codes here — distinct from the HTTP-status `code` above. The most common
+	* is `ORG_CONTEXT_REQUIRED` (bulk operations + orgGuard reject when the
+	* caller's `request.scope.organizationId` is missing).
+	*
+	* @example
+	* if (error.detailsCode === 'ORG_CONTEXT_REQUIRED') {
+	*   alert('Configure auth before bulk operations: configureAuth({ getOrgId })');
+	* }
+	*/
+	get detailsCode() {
+		const c = this.json?.details?.code;
+		return typeof c === "string" ? c : null;
+	}
+	/**
+	* Extract field-level validation errors as `{ field: message }` map.
+	*
+	* Reads three response shapes used by Arc:
+	* 1. `{ errors: { email: 'invalid' } }` — record form (legacy / app-level handlers).
+	* 2. `{ details: { errors: [{ field, message }] } }` — Fastify AJV + Arc errorHandler emit this.
+	* 3. `{ details: { errors: [{ instancePath, message, params }] } }` — raw AJV passthrough.
+	*
+	* Returns null when none of the shapes match.
+	*/
 	get fieldErrors() {
-		return this.json?.errors ?? null;
+		const j = this.json;
+		if (!j) return null;
+		if (j.errors && !Array.isArray(j.errors) && typeof j.errors === "object") return j.errors;
+		const errorList = Array.isArray(j.errors) ? j.errors : Array.isArray(j.details?.errors) ? j.details.errors : null;
+		if (!errorList) return null;
+		const map = {};
+		for (const item of errorList) {
+			if (!item || typeof item !== "object") continue;
+			const e = item;
+			const key = typeof e.field === "string" && e.field || typeof e.instancePath === "string" && e.instancePath.replace(/^\//, "") || typeof e.path === "string" && e.path || typeof e.params?.missingProperty === "string" && e.params.missingProperty || "";
+			if (!key) continue;
+			const msg = typeof e.message === "string" ? e.message : "Invalid value";
+			if (!(key in map)) map[key] = msg;
+		}
+		return Object.keys(map).length > 0 ? map : null;
 	}
 };
 /**
@@ -39,6 +139,84 @@ var ArcApiError = class extends Error {
 function isArcApiError(error) {
 	return error instanceof ArcApiError;
 }
+/**
+* Detects request cancellation (AbortSignal triggered) regardless of runtime.
+*
+* Filtering out abort errors from real failures is a common need — without it,
+* unmounting a React component mid-fetch produces noisy logs and bogus error
+* toasts that look like API failures. Use this predicate to skip the catch
+* branch when the request was deliberately cancelled.
+*
+* Handles the three AbortError shapes you'll see in the wild:
+* 1. Browser `DOMException { name: 'AbortError' }`
+* 2. Node 18+ / undici `Error { name: 'AbortError' }` (no DOMException)
+* 3. Some polyfills / older runtimes where the error has `code: 'ERR_ABORTED'`
+*
+* @example
+* try {
+*   await api.getAll({ options: { signal } });
+* } catch (err) {
+*   if (isAbortError(err)) return; // user navigated away — silence
+*   showToast('Failed to load: ' + err.message);
+* }
+*/
+function isAbortError(error) {
+	if (!error) return false;
+	if (typeof error !== "object") return false;
+	const e = error;
+	if (e.name === "AbortError") return true;
+	if (e.code === "ERR_ABORTED") return true;
+	return false;
+}
+/**
+* Generic check: is this an `ArcApiError` carrying a specific top-level OR
+* nested `details.code`? Matches whichever slot the code lives in — saves
+* call sites from having to know whether arc emitted it at the root or under
+* `details`.
+*
+* @example
+* if (isArcErrorCode(error, 'DUPLICATE_KEY')) showRetryUI();
+* if (isArcErrorCode(error, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
+*/
+function isArcErrorCode(error, code) {
+	if (!isArcApiError(error)) return false;
+	return error.code === code || error.detailsCode === code;
+}
+/**
+* Specific predicate for arc's bulk-preset + orgGuard safety code.
+*
+* Arc's bulk endpoints (`POST/PATCH/DELETE /:resource/bulk`) reject any call
+* where `request.scope.organizationId` is missing — the wire signal is
+* `403 { details: { code: 'ORG_CONTEXT_REQUIRED' } }`. Hosts hitting this
+* need to call `configureAuth({ getOrgId })` before retrying.
+*
+* @example
+* try { await api.bulkCreate({ data: [...] }); }
+* catch (e) {
+*   if (isOrgContextRequiredError(e)) {
+*     console.warn('Bulk requires org context. Configure: configureAuth({ getOrgId })');
+*   } else throw e;
+* }
+*/
+function isOrgContextRequiredError(error) {
+	return isArcErrorCode(error, "ORG_CONTEXT_REQUIRED");
+}
+/**
+* Specific predicate for arc's `VALIDATION_ERROR` (Fastify AJV + Mongoose
+* ValidationError). When true, `error.fieldErrors` is populated with the
+* `{ field: message }` map.
+*/
+function isValidationError(error) {
+	return isArcErrorCode(error, "VALIDATION_ERROR");
+}
+/**
+* Specific predicate for arc's `DUPLICATE_KEY` (unique-constraint violation).
+* Arc's errorHandler classifies these uniformly across MongoDB E11000,
+* Postgres 23505, and Prisma P2002.
+*/
+function isDuplicateKeyError(error) {
+	return isArcErrorCode(error, "DUPLICATE_KEY");
+}
 let clientConfig = null;
 /**
 * Configure the API client. Call once at app init before any API requests.
@@ -73,17 +251,22 @@ function isAutoIdempotency() {
 	return clientConfig?.autoIdempotency ?? false;
 }
 let authConfig = null;
+let hasWarnedAsyncToken = false;
 /**
 * Configure auth context for automatic token/orgId injection.
 * When configured, hooks auto-inject these values so you don't need to pass them manually.
 *
 * **SSR safety:** This sets module-level state. Call only in client-side code.
 *
+* **Token resolution is synchronous.** `getToken` must return `string | null`
+* synchronously — never a Promise. See {@link AuthConfig.getToken} for guidance
+* on bridging async auth libraries via cached values.
+*
 * @example
 * // Cookie auth (no token needed)
 * configureAuth({ getOrgId: () => currentOrg.id });
 *
-* // Bearer auth
+* // Bearer auth — token is cached synchronously by the auth library
 * configureAuth({
 *   getToken: () => session?.accessToken ?? null,
 *   getOrgId: () => currentOrg?.id ?? null,
@@ -92,16 +275,58 @@ let authConfig = null;
 function configureAuth(config) {
 	if (typeof window === "undefined") console.warn("[arc-next] configureAuth() called on the server. This sets module-level state that persists across requests. Call only in client-side code (e.g., a 'use client' provider).");
 	authConfig = config;
+	hasWarnedAsyncToken = false;
+}
+function readToken(getToken) {
+	if (!getToken) return null;
+	const result = getToken();
+	if (result && typeof result.then === "function") {
+		if (!hasWarnedAsyncToken) {
+			hasWarnedAsyncToken = true;
+			console.warn("[arc-next] configureAuth({ getToken }) returned a Promise. Tokens MUST resolve synchronously — async returns are dropped and requests will be unauthenticated. Cache your token (localStorage, memory, signal) and have getToken() return the cached value.");
+		}
+		return null;
+	}
+	return result ?? null;
 }
 /**
 * Get the current auth context. Returns nulls when not configured.
 */
 function getAuthContext() {
 	return {
-		token: authConfig?.getToken?.() ?? null,
+		token: readToken(authConfig?.getToken),
 		organizationId: authConfig?.getOrgId?.() ?? null
 	};
 }
+/** @internal — exposed for tests; resets the dev-warn dedup flag. */
+function _resetAuthWarnings() {
+	hasWarnedAsyncToken = false;
+}
+/**
+* Build an auth-aware URL using the global client + auth singletons.
+*
+* Single source of truth for {@link import('./sse.js').buildSseUrl} (HTTP) and
+* {@link import('./ws.js').buildWsUrl} (WebSocket). Both delegate here so the
+* auth-injection rule (org always, token only when `authMode !== 'cookie'`)
+* stays in one place and can't drift.
+*
+* @param path Path appended to the base URL (leading slash recommended).
+* @param params Caller-supplied params; merged with auth params. Caller wins on key collision.
+* @param protocol `'http'` (default) or `'ws'` — controls the protocol rewrite.
+*/
+function buildStreamUrl(path, params = {}, protocol = "http") {
+	const auth = getAuthContext();
+	const qs = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) {
+		if (value === void 0 || value === null || value === "") continue;
+		qs.set(key, String(value));
+	}
+	if (auth.organizationId && !qs.has("organizationId")) qs.set("organizationId", auth.organizationId);
+	if (auth.token && getAuthMode() !== "cookie" && !qs.has("token")) qs.set("token", auth.token);
+	const origin = protocol === "ws" ? getBaseUrl().replace(/^http(s?):\/\//, "ws$1://") : getBaseUrl();
+	const suffix = qs.toString();
+	return `${origin}${path}${suffix ? `?${suffix}` : ""}`;
+}
 /**
 * Create an isolated API client for a specific backend.
 * Use this when your app needs to talk to multiple APIs with different auth.
@@ -132,7 +357,7 @@ function createClient(config) {
 		request: (method, endpoint, options) => {
 			if (clientAuth) {
 				const resolved = { ...options };
-				if (resolved.token === void 0 && clientAuth.getToken) resolved.token = clientAuth.getToken();
+				if (resolved.token === void 0 && clientAuth.getToken) resolved.token = readToken(clientAuth.getToken);
 				if (resolved.organizationId === void 0 && clientAuth.getOrgId) resolved.organizationId = clientAuth.getOrgId();
 				if (clientCfg.authMode === "header" && resolved.token) {
 					resolved.headerOptions = {
@@ -152,17 +377,115 @@ function createClient(config) {
 	};
 }
 /**
+* Create an `ArcClient` wired to the global `configureClient` + `configureAuth` setup.
+*
+* Removes the boilerplate every consumer SDK writes by hand (auth-injection adapter
+* + `BaseApi` constructor with `client: { request: handleApiRequest, config: ... }`).
+* The returned client reads `getToken` / `getOrgId` lazily on each request, so token
+* rotation in the global auth layer takes effect immediately.
+*
+* Equivalent to `createClient(...)` with `getToken`/`getOrgId` pulled from
+* `getAuthContext()`. Pass `overrides` to customize specific fields without
+* rebuilding the whole transport.
+*
+* @example
+* // App init (somewhere in a "use client" provider)
+* configureClient({ baseUrl: process.env.NEXT_PUBLIC_API_URL! });
+* configureAuth({
+*   getToken: () => session?.accessToken ?? null,
+*   getOrgId: () => currentOrg?.id ?? null,
+* });
+*
+* // SDK module
+* import { createAuthAwareClient } from '@classytic/arc-next/client';
+* import { createCrudApi } from '@classytic/arc-next/api';
+*
+* const client = createAuthAwareClient();
+* export const productsApi = createCrudApi('products', { client });
+*
+* // With per-call overrides
+* const analyticsClient = createAuthAwareClient({
+*   baseUrl: 'https://analytics.example.com',
+*   authMode: 'header',
+*   headerName: 'x-api-key',
+* });
+*/
+function createAuthAwareClient(overrides = {}) {
+	return createClient({
+		baseUrl: overrides.baseUrl ?? getBaseUrl(),
+		authMode: overrides.authMode ?? getAuthMode(),
+		autoIdempotency: overrides.autoIdempotency ?? isAutoIdempotency(),
+		elevated: overrides.elevated ?? clientConfig?.elevated,
+		...overrides,
+		getToken: overrides.getToken ?? (() => readToken(authConfig?.getToken)),
+		getOrgId: overrides.getOrgId ?? (() => authConfig?.getOrgId?.() ?? null),
+		headerName: overrides.headerName ?? authConfig?.headerName
+	});
+}
+/**
 * Get auth context for a specific client instance, falling back to global.
 */
 function getClientAuthContext(client) {
 	if (client?.auth) return {
-		token: client.auth.getToken?.() ?? authConfig?.getToken?.() ?? null,
+		token: readToken(client.auth.getToken) ?? readToken(authConfig?.getToken),
 		organizationId: client.auth.getOrgId?.() ?? authConfig?.getOrgId?.() ?? null
 	};
 	return getAuthContext();
 }
+/** Default retry predicate: retry on network failures and 5xx, never on Abort or 4xx. */
+function defaultShouldRetry(error) {
+	if (isAbortError(error)) return false;
+	if (isArcApiError(error)) return error.status >= 500 && error.status < 600;
+	return error instanceof Error;
+}
+/** Compute the delay in ms before the Nth retry. */
+function computeBackoff(retry, attempt) {
+	const strategy = retry.backoff ?? "exponential";
+	if (typeof strategy === "function") return Math.max(0, strategy(attempt));
+	if (strategy === "linear") return 300 * (attempt + 1);
+	return Math.min(300 * Math.pow(2, attempt), 1e4);
+}
 async function executeRequest(config, method, endpoint, options = {}) {
-	const { body, token, organizationId, revalidate, headerOptions, tags, cache, signal, idempotencyKey } = options;
+	const totalAttempts = Math.max(1, config.retry?.attempts ?? 1);
+	const shouldRetry = (() => {
+		const r = config.retry?.retryOn;
+		if (typeof r === "function") return r;
+		if (Array.isArray(r)) return (e) => isArcApiError(e) && r.includes(e.status);
+		return defaultShouldRetry;
+	})();
+	let lastError;
+	for (let attempt = 0; attempt < totalAttempts; attempt++) try {
+		return await executeAttempt(config, method, endpoint, options, attempt);
+	} catch (error) {
+		lastError = error;
+		if (attempt === totalAttempts - 1 || !shouldRetry(error)) throw error;
+		const delay = computeBackoff(config.retry ?? {}, attempt);
+		if (delay > 0) await sleepAbortable(delay, options.signal);
+	}
+	throw lastError;
+}
+/** Sleep that resolves early if the signal aborts. */
+function sleepAbortable(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(Object.assign(/* @__PURE__ */ new Error("Aborted"), { name: "AbortError" }));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(Object.assign(/* @__PURE__ */ new Error("Aborted"), { name: "AbortError" }));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** A single fetch attempt — used by executeRequest's retry loop. */
+async function executeAttempt(config, method, endpoint, options, attempt) {
+	const { body, token, organizationId, revalidate, headerOptions, tags, cache, signal, idempotencyKey, elevated } = options;
+	const startTime = Date.now();
 	try {
 		let headers = {
 			...organizationId ? { "x-organization-id": organizationId } : {},
@@ -175,19 +498,34 @@ async function executeRequest(config, method, endpoint, options = {}) {
 		} else headers["Authorization"] = `Bearer ${token}`;
 		if (config.apiVersion) headers["Accept-Version"] = config.apiVersion;
 		if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+		if (elevated ?? config.elevated ?? false) headers["x-arc-scope"] = "platform";
 		if (body !== void 0 && body !== null && !(body instanceof FormData)) headers["Content-Type"] = "application/json";
 		if (headerOptions) headers = {
 			...headers,
 			...headerOptions
 		};
 		const credentials = config.credentials ?? (config.authMode === "cookie" ? "include" : "same-origin");
+		let serializedBody = void 0;
+		if (body !== void 0 && body !== null) serializedBody = body instanceof FormData ? body : JSON.stringify(body);
+		if (config.beforeRequest) {
+			const ctx = await config.beforeRequest({
+				method,
+				endpoint,
+				headers,
+				body: serializedBody,
+				signal,
+				attempt
+			});
+			headers = ctx.headers;
+			serializedBody = ctx.body;
+		}
 		const fetchOptions = {
 			method,
 			headers,
 			credentials,
 			...signal ? { signal } : {}
 		};
-		if (body !== void 0 && body !== null) fetchOptions.body = body instanceof FormData ? body : JSON.stringify(body);
+		if (serializedBody !== void 0) fetchOptions.body = serializedBody;
 		if (cache) fetchOptions.cache = cache;
 		if (revalidate !== void 0) fetchOptions.next = {
 			...fetchOptions.next,
@@ -203,7 +541,8 @@ async function executeRequest(config, method, endpoint, options = {}) {
 			let errorMessage = response.statusText;
 			try {
 				json = await response.clone().json();
-				errorMessage = json?.message || response.statusText;
+				const j = json;
+				errorMessage = typeof j?.error === "string" && j.error || typeof j?.message === "string" && j.message || response.statusText;
 			} catch {
 				try {
 					const text = await response.text();
@@ -251,6 +590,14 @@ async function executeRequest(config, method, endpoint, options = {}) {
 				throw new Error(`Failed to parse response body from ${method} ${endpoint}: blob error: ${blobError instanceof Error ? blobError.message : String(blobError)}`);
 			}
 		}
+		if (config.afterResponse) data = (await config.afterResponse({
+			method,
+			endpoint,
+			status: response.status,
+			body: data,
+			durationMs: Date.now() - startTime,
+			response
+		})).body;
 		return data;
 	} catch (error) {
 		if (error instanceof Error) throw error;
@@ -314,4 +661,4 @@ function createQueryString(params = {}) {
 }
 
 //#endregion
-export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isArcApiError, isAutoIdempotency };
+export { ArcApiError, KNOWN_DETAILS_CODES, KNOWN_TOP_LEVEL_CODES, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };

package/dist/hooks.d.ts

@@ -1,30 +1,31 @@
 import { ArcClient, UseRouterHook } from "./client.js";
-import { BaseApi, FilterOperator } from "./api.js";
+import { ApiResponse, 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 { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult } 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 } 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'];
+} & Partial<SoftDeleteMethods<T>> & Partial<BulkMethods<T, TCreate, TUpdate>> & Partial<SlugLookupMethods<T>> & Partial<TreeMethods<T>> & Partial<SearchPresetMethods<T>>;
 interface CrudHooksConfig<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
   api: CrudApi<T, TCreate, TUpdate>;
   entityKey: string;
@@ -147,9 +148,63 @@ 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: ApiResponse<TResult>, variables: {
+      id: string;
+      action: string;
+      data?: TBody;
+    }) => void;
+    onError?: (error: Error, variables: {
+      id: string;
+      action: string;
+      data?: TBody;
+    }) => void;
+    onSettled?: (data: ApiResponse<TResult> | undefined, error: Error | null, variables: {
+      id: string;
+      action: string;
+      data?: TBody;
+    }) => void;
+  }) => TransitionMutationReturn<ApiResponse<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>;
+  }>;
   useUpload: (options?: {
     invalidateQueries?: QueryKey[];
     messages?: MutationMessages;
@@ -161,7 +216,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 +224,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>;
 }
 /**