@classytic/arc-next 0.3.1 → 0.4.0

package/README.md

@@ -30,8 +30,9 @@ import { useRouter } from "next/navigation";
 // Required — sets the API base URL and auth mode
 configureClient({
   baseUrl: process.env.NEXT_PUBLIC_API_URL!,
-  authMode: "cookie",   // 'cookie' for Better Auth, 'bearer' for token auth (default)
-  // credentials: 'omit', // override if you don't want cookies sent cross-origin
+  authMode: "cookie",        // 'cookie' | 'bearer' (default) | 'header'
+  // apiVersion: '2',        // sends Accept-Version header
+  // autoIdempotency: true,  // auto Idempotency-Key on mutations (retry-safe)
 });
 
 // Optional — auto-inject tenant context into queries/mutations
@@ -59,6 +60,7 @@ configureNavigation(useRouter);
 | `@classytic/arc-next/hooks`         | `createCrudHooks`, `configureNavigation`                                     |      Yes        |
 | `@classytic/arc-next/query-client`  | `getQueryClient` (SSR-safe singleton)                                        |       No        |
 | `@classytic/arc-next/prefetch`      | `createCrudPrefetcher`, `dehydrate` (SSR prefetch)                           |       No        |
+| `@classytic/arc-next/sse`           | `useEventStream` (Server-Sent Events for real-time cache invalidation)       |      Yes        |
 
 No barrel index — every file is its own entry point. Tree-shakeable (`sideEffects: false`).
 
@@ -148,25 +150,28 @@ export function ProductsPage() {
 ```ts
 configureClient({
   baseUrl: string;                          // Required — API base URL
-  authMode?: 'cookie' | 'bearer';          // Default: 'bearer'
+  authMode?: 'bearer' | 'cookie' | 'header'; // Default: 'bearer'
   credentials?: RequestCredentials;         // Default: derived from authMode
-  internalApiKey?: string;                  // Optional — sent as x-internal-api-key header
-  defaultHeaders?: Record<string, string>; // Optional — merged into every request
+  internalApiKey?: string;                  // Sent as x-internal-api-key header
+  defaultHeaders?: Record<string, string>; // Merged into every request
+  apiVersion?: string;                     // Sent as Accept-Version header
+  autoIdempotency?: boolean;               // Auto Idempotency-Key on mutations (retry-safe)
 });
 ```
 
-- `authMode: 'bearer'` (default) — requires a token; queries disabled until token provided; `credentials: 'same-origin'`
-- `authMode: 'cookie'` — HTTP-only cookies (e.g. Better Auth); queries always enabled; `credentials: 'include'`
-- `credentials` — explicit override: `'include'` (send cookies cross-origin), `'same-origin'` (same-origin only), `'omit'` (never send cookies)
+- `authMode: 'bearer'` (default) — requires token; queries disabled until provided
+- `authMode: 'cookie'` — HTTP-only cookies (e.g. Better Auth); queries always enabled
+- `authMode: 'header'` — custom header auth (e.g. `x-api-key`); uses `headerName` from `configureAuth`
 
-Must be called before any API requests. Throws if not configured.
+Must be called before any API requests. Warns if called on the server (SSR safety).
 
 ### `configureAuth(config)`
 
 ```ts
 configureAuth({
-  getToken?: () => string | null;   // For bearer auth — return access token
+  getToken?: () => string | null;   // For bearer/header auth — return access token or API key
   getOrgId?: () => string | null;   // Return active organization ID
+  headerName?: string;              // Custom header name for authMode: 'header' (default: 'x-api-key')
 });
 ```
 
@@ -235,12 +240,15 @@ Factory that returns everything you need. The `api` parameter accepts any `creat
 const {
   KEYS, cache,
   useList, useDetail, useInfiniteList,
-  useActions, useUpload, useSearch, useCustomMutation,
+  useActions, useBulkActions,
+  useDeleted, useDetailBySlug, useTree, useChildren, useFindBy,
+  useUpload, useSearch, useCustomMutation,
   useNavigation,
 } = createCrudHooks<Product, CreateProduct>({
     api: productsApi,       // from createCrudApi() — types inferred, no cast
     entityKey: "products",  // TanStack Query key prefix
     singular: "Product",    // for toast messages
+    idField: "sku",         // optional — custom ID field for cache keys (default: _id → id)
     defaults: {             // optional
       staleTime: 60_000,
       messages: { createSuccess: "Product added!" },
@@ -393,6 +401,52 @@ const { mutateAsync: publish, isPending } = useCustomMutation({
 });
 ```
 
+#### `useDeleted(params?, options?)`
+
+List soft-deleted items. Requires `softDelete` preset on the Arc resource.
+
+#### `useDetailBySlug(slug, options?)`
+
+Fetch a single item by slug (`GET /slug/:slug`). Requires `slugLookup` preset.
+
+#### `useTree(params?, options?)`
+
+Fetch hierarchical tree data (`GET /tree`). Requires `tree` preset.
+
+#### `useChildren(parentId, params?, options?)`
+
+Fetch children of a parent node (`GET /:parentId/children`). Requires `tree` preset.
+
+#### `useFindBy(field, value, options?)`
+
+Query by a single field with optional operator:
+
+```ts
+const { items } = useFindBy("status", "active");
+const { items } = useFindBy("price", 50, { operator: "gte" });
+```
+
+#### `useBulkActions()`
+
+```ts
+const { bulkCreate, bulkUpdate, bulkRemove } = useBulkActions();
+await bulkCreate({ data: [{ name: "A" }, { name: "B" }] });
+```
+
+#### `useEventStream(options)` (from `./sse`)
+
+Subscribe to Arc SSE events with auto-reconnect and query invalidation:
+
+```ts
+import { useEventStream } from "@classytic/arc-next/sse";
+
+const { isConnected, lastEvent } = useEventStream({
+  resource: "agents",
+  patterns: ["agents.created", "agents.updated"],
+  invalidateQueries: [agentKeys.lists()],
+});
+```
+
 ### Query Keys (`KEYS`)
 
 ```ts
@@ -713,8 +767,15 @@ const adminApi = createCrudApi("users", {
 - **Pagination Normalization** — Handles `docs`/`data`/`items`/`results` + any custom key, offset/keyset/aggregate pagination
 - **Detail Cache Prefilling** — List results auto-populate detail query cache
 - **React 19 Transitions** — `useMutationWithTransition` wraps invalidation in `startTransition`
-- **Cookie & Bearer Auth** — `authMode: 'cookie'` for Better Auth, `'bearer'` for token auth, configurable `credentials` policy
-- **SSR Prefetch** — `createCrudPrefetcher` + `dehydrate` for server component data loading
+- **Cookie, Bearer & Header Auth** — `authMode: 'cookie'` / `'bearer'` / `'header'` (custom header like `x-api-key`)
+- **Custom ID Fields** — `idField` on `createCrudHooks` for resources keyed by `sku`, `slug`, `code`, etc.
+- **Preset Hooks** — `useDeleted`, `useBulkActions`, `useDetailBySlug`, `useTree`, `useChildren`, `useFindBy`
+- **SSE Real-Time** — `useEventStream` with auto-reconnect, pattern filtering, query invalidation
+- **Infinite Scroll** — `maxPages` for memory management with automatic scroll-back support
+- **Idempotency** — `autoIdempotency` generates retry-safe keys at mutation level
+- **API Versioning** — `apiVersion` sends `Accept-Version` header
+- **SSR Prefetch** — `createCrudPrefetcher` + `prefetchBySlug` / `prefetchDeleted` / `prefetchTree`
+- **SSR Safety** — warns when `configureClient`/`configureAuth` called on the server
 - **Multi-Client** — `createClient()` for multiple API backends side by side
 - **Pluggable Toast** — `configureToast()` — use sonner, react-hot-toast, or anything
 - **Pluggable Navigation** — `configureNavigation()` — use Next.js, React Router, or any router

package/dist/api.d.ts

@@ -52,9 +52,22 @@ interface DeleteResponse {
     soft?: boolean;
   };
 }
+interface BulkCreateResponse<T = unknown> {
+  success: boolean;
+  data?: T[];
+  count?: number;
+}
+interface BulkUpdateResponse {
+  success: boolean;
+  modifiedCount?: number;
+}
+interface BulkDeleteResponse {
+  success: boolean;
+  deletedCount?: number;
+}
 type SortDirection = 1 | -1 | 'asc' | 'desc';
 type SortSpec = Record<string, SortDirection> | string;
-type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'regex';
+type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'regex' | 'like' | 'exists' | 'size' | 'type';
 interface QueryParams {
   page?: number;
   limit?: number;
@@ -65,6 +78,13 @@ interface QueryParams {
   populate?: string | string[];
   populateOptions?: PopulateOption[];
   lean?: boolean | 'true' | 'false';
+  /** Database-agnostic joins. Maps alias → collection or full lookup config. */
+  lookup?: Record<string, string | {
+    from: string;
+    localField: string;
+    foreignField: string;
+    select?: string;
+  }>;
   [key: string]: unknown;
 }
 interface RequestOptions {
@@ -218,6 +238,103 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     params?: QueryParams;
     options?: Omit<RequestOptions, 'token' | 'organizationId'>;
   }): Promise<TResponse>;
+  getDeleted({
+    token,
+    organizationId,
+    params,
+    options
+  }?: {
+    token?: string | null;
+    organizationId?: string | null;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<PaginatedResponse<TDoc>>;
+  restore({
+    token,
+    organizationId,
+    id,
+    options
+  }: {
+    token?: string | null;
+    organizationId?: string | null;
+    id: string;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<ApiResponse<TDoc>>;
+  bulkCreate({
+    token,
+    organizationId,
+    data,
+    options
+  }: {
+    token?: string | null;
+    organizationId?: string | null;
+    data: TCreate[];
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<BulkCreateResponse<TDoc>>;
+  bulkUpdate({
+    token,
+    organizationId,
+    filter,
+    data,
+    options
+  }: {
+    token?: string | null;
+    organizationId?: string | null;
+    filter: Record<string, unknown>;
+    data: TUpdate;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<BulkUpdateResponse>;
+  bulkDelete({
+    token,
+    organizationId,
+    filter,
+    options
+  }: {
+    token?: string | null;
+    organizationId?: string | null;
+    filter: Record<string, unknown>;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<BulkDeleteResponse>;
+  getBySlug({
+    token,
+    organizationId,
+    slug,
+    params,
+    options
+  }: {
+    token?: string | null;
+    organizationId?: string | null;
+    slug: string;
+    params?: {
+      select?: string;
+      populate?: string | string[];
+    };
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<ApiResponse<TDoc>>;
+  getTree({
+    token,
+    organizationId,
+    params,
+    options
+  }?: {
+    token?: string | null;
+    organizationId?: string | null;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<ApiResponse<TDoc[]>>;
+  getChildren({
+    token,
+    organizationId,
+    parentId,
+    params,
+    options
+  }: {
+    token?: string | null;
+    organizationId?: string | null;
+    parentId: string;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<PaginatedResponse<TDoc>>;
 }
 declare function createCrudApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>>(entity: string, config?: BaseApiConfig): BaseApi<TDoc, TCreate, TUpdate>;
 type ExtractDoc<T> = T extends PaginatedResponse<infer D> ? D : never;
@@ -225,4 +342,4 @@ declare function isOffsetPagination<T>(response: PaginatedResponse<T>): response
 declare function isKeysetPagination<T>(response: PaginatedResponse<T>): response is KeysetPaginationResponse<T>;
 declare function isAggregatePagination<T>(response: PaginatedResponse<T>): response is AggregatePaginationResponse<T>;
 //#endregion
-export { AggregatePaginationResponse, ApiResponse, BaseApi, BaseApiConfig, DeleteResponse, ExtractDoc, FilterOperator, KeysetPaginationResponse, OffsetPaginationResponse, PaginatedResponse, PopulateOption, QueryParams, RequestOptions, SortDirection, SortSpec, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };
+export { AggregatePaginationResponse, ApiResponse, BaseApi, BaseApiConfig, BulkCreateResponse, BulkDeleteResponse, BulkUpdateResponse, DeleteResponse, ExtractDoc, FilterOperator, KeysetPaginationResponse, OffsetPaginationResponse, PaginatedResponse, PopulateOption, QueryParams, RequestOptions, SortDirection, SortSpec, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };

package/dist/api.js

@@ -48,6 +48,19 @@ var BaseApi = class {
 				if (Array.isArray(value) && value.length > 0) result[key] = value;
 				return;
 			}
+			if (key === "lookup") {
+				if (typeof value === "object" && value !== null) Object.entries(value).forEach(([alias, lv]) => {
+					if (typeof lv === "string") result[`lookup[${alias}]`] = lv;
+					else if (typeof lv === "object" && lv !== null) {
+						const cfg = lv;
+						result[`lookup[${alias}][from]`] = cfg.from;
+						result[`lookup[${alias}][localField]`] = cfg.localField;
+						result[`lookup[${alias}][foreignField]`] = cfg.foreignField;
+						if (cfg.select) result[`lookup[${alias}][select]`] = cfg.select;
+					}
+				});
+				return;
+			}
 			if (value !== void 0 && value !== "") if (["page", "limit"].includes(key)) result[key] = parseInt(String(value)) || (key === "page" ? 1 : 10);
 			else if (Array.isArray(value)) {
 				if (value.length > 1) result[`${key}[in]`] = value.join(",");
@@ -169,6 +182,97 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn(method, url, this.withHeaders(requestOptions));
 	}
+	async getDeleted({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+		const mergedParams = {
+			...this.config.defaultParams,
+			...params
+		};
+		const processedParams = this.prepareParams(mergedParams);
+		const queryString = this.createQueryString(processedParams);
+		const requestOptions = {
+			cache: this.config.cache,
+			...options
+		};
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("GET", `${this.baseUrl}/deleted?${queryString}`, this.withHeaders(requestOptions));
+	}
+	async restore({ token, organizationId = null, id, options = {} }) {
+		if (!id) throw new Error("ID is required");
+		const requestOptions = { ...options };
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("POST", `${this.baseUrl}/${id}/restore`, this.withHeaders(requestOptions));
+	}
+	async bulkCreate({ token, organizationId = null, data, options = {} }) {
+		const requestOptions = {
+			body: data,
+			...options
+		};
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("POST", `${this.baseUrl}/bulk`, this.withHeaders(requestOptions));
+	}
+	async bulkUpdate({ token, organizationId = null, filter, data, options = {} }) {
+		const requestOptions = {
+			body: {
+				filter,
+				data
+			},
+			...options
+		};
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("PATCH", `${this.baseUrl}/bulk`, this.withHeaders(requestOptions));
+	}
+	async bulkDelete({ token, organizationId = null, filter, options = {} }) {
+		const requestOptions = {
+			body: { filter },
+			...options
+		};
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("DELETE", `${this.baseUrl}/bulk`, this.withHeaders(requestOptions));
+	}
+	async getBySlug({ token = null, organizationId = null, slug, params = {}, options = {} }) {
+		if (!slug) throw new Error("Slug is required");
+		const queryString = this.createQueryString(params);
+		const url = queryString ? `${this.baseUrl}/slug/${slug}?${queryString}` : `${this.baseUrl}/slug/${slug}`;
+		const requestOptions = {
+			cache: this.config.cache,
+			...options
+		};
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("GET", url, this.withHeaders(requestOptions));
+	}
+	async getTree({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+		const processedParams = this.prepareParams(params);
+		const queryString = this.createQueryString(processedParams);
+		const requestOptions = {
+			cache: this.config.cache,
+			...options
+		};
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("GET", `${this.baseUrl}/tree?${queryString}`, this.withHeaders(requestOptions));
+	}
+	async getChildren({ token = null, organizationId = null, parentId, params = {}, options = {} }) {
+		if (!parentId) throw new Error("Parent ID is required");
+		const mergedParams = {
+			...this.config.defaultParams,
+			...params
+		};
+		const processedParams = this.prepareParams(mergedParams);
+		const queryString = this.createQueryString(processedParams);
+		const requestOptions = {
+			cache: this.config.cache,
+			...options
+		};
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("GET", `${this.baseUrl}/${parentId}/children?${queryString}`, this.withHeaders(requestOptions));
+	}
 };
 function createCrudApi(entity, config = {}) {
 	return new BaseApi(entity, config);

package/dist/client.d.ts

@@ -55,7 +55,7 @@ interface ClientConfig {
    * - 'bearer' (default): Requires a token for authenticated requests. Queries are disabled until a token is provided.
    * - 'cookie': Auth is handled via HTTP-only cookies (e.g. Better Auth). Queries are always enabled — no token needed.
    */
-  authMode?: 'bearer' | 'cookie';
+  authMode?: 'bearer' | 'cookie' | 'header';
   /**
    * Fetch credentials policy.
    * - 'include': Always send cookies cross-origin (required for cookie-based auth).
@@ -67,6 +67,18 @@ interface ClientConfig {
    * - `authMode: 'bearer'` (default) → `'same-origin'`
    */
   credentials?: RequestCredentials;
+  /**
+   * API version sent as `Accept-Version` header.
+   * Use when the Arc backend has versioning enabled.
+   * @example '2' // sends Accept-Version: 2
+   */
+  apiVersion?: string;
+  /**
+   * Auto-generate `Idempotency-Key` header for POST/PUT/PATCH requests.
+   * Prevents duplicate mutations on network retries.
+   * Default: false — opt-in per-request via `idempotencyKey` option.
+   */
+  autoIdempotency?: boolean;
 }
 /**
  * Configure the API client. Call once at app init before any API requests.
@@ -86,10 +98,14 @@ declare function configureClient(config: ClientConfig): void;
 /**
  * Get the configured auth mode. Returns 'bearer' if not configured.
  */
-declare function getAuthMode(): 'bearer' | 'cookie';
+declare function getAuthMode(): 'bearer' | 'cookie' | 'header';
+/** Whether auto-idempotency is enabled on the global client. */
+declare function isAutoIdempotency(): boolean;
 interface AuthConfig {
   getToken?: () => string | null;
   getOrgId?: () => string | null;
+  /** Custom auth header name. Used when authMode is 'header'. Default: 'x-api-key' */
+  headerName?: string;
 }
 /**
  * Configure auth context for automatic token/orgId injection.
@@ -125,14 +141,8 @@ interface ApiRequestOptions {
   tags?: string[];
   cache?: RequestCache;
   signal?: AbortSignal;
-}
-interface BlobResponse {
-  data: Blob;
-  response: Response;
-}
-interface TextResponse {
-  data: string;
-  response: Response;
+  /** Explicit idempotency key for this request. Sent as `Idempotency-Key` header. */
+  idempotencyKey?: string;
 }
 interface ArcClientConfig extends ClientConfig {
   toast?: ToastHandler;
@@ -185,4 +195,4 @@ declare function handleApiRequest<T = unknown>(method: HttpMethod, endpoint: str
  */
 declare function createQueryString<T extends Record<string, unknown>>(params?: T): string;
 //#endregion
-export { ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, AuthConfig, BlobResponse, ClientConfig, HttpMethod, TextResponse, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError };
+export { ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, AuthConfig, ClientConfig, HttpMethod, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError, isAutoIdempotency };

package/dist/client.js

@@ -55,6 +55,7 @@ let clientConfig = null;
 * configureClient({ baseUrl: process.env.NEXT_PUBLIC_API_URL!, authMode: 'cookie' });
 */
 function configureClient(config) {
+	if (typeof window === "undefined") console.warn("[arc-next] configureClient() 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).");
 	clientConfig = config;
 }
 /**
@@ -63,6 +64,10 @@ function configureClient(config) {
 function getAuthMode() {
 	return clientConfig?.authMode ?? "bearer";
 }
+/** Whether auto-idempotency is enabled on the global client. */
+function isAutoIdempotency() {
+	return clientConfig?.autoIdempotency ?? false;
+}
 let authConfig = null;
 /**
 * Configure auth context for automatic token/orgId injection.
@@ -81,6 +86,7 @@ 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;
 }
 /**
@@ -115,14 +121,19 @@ function createClient(config) {
 	};
 }
 async function executeRequest(config, method, endpoint, options = {}) {
-	const { body, token, organizationId, revalidate, headerOptions, tags, cache, signal } = options;
+	const { body, token, organizationId, revalidate, headerOptions, tags, cache, signal, idempotencyKey } = options;
 	try {
 		let headers = {
 			...organizationId ? { "x-organization-id": organizationId } : {},
 			...config.defaultHeaders ?? {}
 		};
 		if (config.internalApiKey) headers["x-internal-api-key"] = config.internalApiKey;
-		if (token) headers["Authorization"] = `Bearer ${token}`;
+		if (token) if (config.authMode === "header") {
+			const headerName = authConfig?.headerName ?? "x-api-key";
+			headers[headerName] = token;
+		} else headers["Authorization"] = `Bearer ${token}`;
+		if (config.apiVersion) headers["Accept-Version"] = config.apiVersion;
+		if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
 		if (body !== void 0 && body !== null && !(body instanceof FormData)) headers["Content-Type"] = "application/json";
 		if (headerOptions) headers = {
 			...headers,
@@ -245,4 +256,4 @@ function createQueryString(params = {}) {
 }
 
 //#endregion
-export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError };
+export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError, isAutoIdempotency };

package/dist/hooks.d.ts

@@ -1,7 +1,7 @@
 import { ArcClient, UseRouterHook } from "./client.js";
-import { BaseApi } from "./api.js";
-import { MutationCallbacks, MutationMessages, TransitionMutationReturn } from "./mutation.js";
+import { BaseApi, FilterOperator } from "./api.js";
 import { CacheUtils, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, QueryKeys } from "./query.js";
+import { MutationCallbacks, MutationMessages, TransitionMutationReturn } from "./mutation.js";
 import { QueryKey } from "@tanstack/react-query";
 
 //#region src/hooks.d.ts
@@ -15,12 +15,32 @@ import { QueryKey } from "@tanstack/react-query";
 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'];
 };
 interface CrudHooksConfig<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
   api: CrudApi<T, TCreate, TUpdate>;
   entityKey: string;
   singular: string;
   plural?: string;
+  /**
+   * Primary key field used to extract item IDs from response data.
+   * Used for cache key resolution, optimistic updates, and detail cache prefill.
+   *
+   * Default lookup order: `_id` → `id`.
+   * Set this when your resource uses a custom ID field (e.g., `'sku'`, `'slug'`, `'code'`).
+   *
+   * @example
+   * createCrudHooks({ idField: 'sku', ... }) // GET /products/:sku
+   */
+  idField?: string;
   defaults?: {
     staleTime?: number;
     gcTime?: number;
@@ -72,11 +92,35 @@ interface CrudActions<T, TCreate, TUpdate> {
   create: (params: MutationParams<TCreate>, options?: CallOptions<T>) => Promise<T>;
   update: (params: UpdateParams<TUpdate>, options?: CallOptions<T>) => Promise<T>;
   remove: (params: DeleteParams, options?: CallOptions) => Promise<unknown>;
+  /** Restore a soft-deleted item. Only available when backend has softDelete preset. */
+  restore: (params: DeleteParams, options?: CallOptions<T>) => Promise<T>;
   isCreating: boolean;
   isUpdating: boolean;
   isDeleting: boolean;
+  isRestoring: boolean;
   isMutating: boolean;
 }
+interface BulkActions<T, TCreate> {
+  bulkCreate: (params: {
+    data: TCreate[];
+    token?: string | null;
+    organizationId?: string | null;
+  }, options?: CallOptions<T[]>) => Promise<T[]>;
+  bulkUpdate: (params: {
+    filter: Record<string, unknown>;
+    data: Partial<T>;
+    token?: string | null;
+    organizationId?: string | null;
+  }, options?: CallOptions) => Promise<unknown>;
+  bulkRemove: (params: {
+    filter: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+  }, options?: CallOptions) => Promise<unknown>;
+  isBulkCreating: boolean;
+  isBulkUpdating: boolean;
+  isBulkDeleting: boolean;
+}
 interface NavigationOptions {
   scroll?: boolean;
   replace?: boolean;
@@ -98,6 +142,14 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
     (token: string | null, params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>;
   };
   useActions: () => CrudActions<T, TCreate, TUpdate>;
+  useBulkActions: () => BulkActions<T, TCreate>;
+  useDeleted: (params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
+  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>;
   useUpload: (options?: {
     invalidateQueries?: QueryKey[];
     messages?: MutationMessages;
@@ -134,9 +186,11 @@ declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>(
   api,
   entityKey,
   singular,
+  plural,
+  idField,
   defaults,
   callbacks,
   client
 }: CrudHooksConfig<T, TCreate, TUpdate>): CrudHooksReturn<T, TCreate, TUpdate>;
 //#endregion
-export { CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };
+export { BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };