@classytic/arc-next 0.4.0 → 0.5.0

package/dist/mutation.js

@@ -1,7 +1,6 @@
 "use client";
 
 import { isArcApiError, isAutoIdempotency } from "./client.js";
-import { QUERY_CONFIGS } from "./query.js";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useRef, useTransition } from "react";
 
@@ -22,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") {
@@ -162,8 +180,6 @@ function useOptimisticMutation(config) {
 		}
 	});
 }
-/** @deprecated Use `useOptimisticMutation` */
-const createOptimisticMutation = useOptimisticMutation;
 
 //#endregion
-export { QUERY_CONFIGS, configureToast, createOptimisticMutation, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };
+export { configureToast, getToastHandler, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };

package/dist/prefetch.d.ts

@@ -1,7 +1,15 @@
-import { QueryClient, dehydrate } from "@tanstack/react-query";
+import { HydrationBoundary, InfiniteData, QueryClient, dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.d.ts
-interface PrefetchOptions {
+interface PrefetchAuthContext {
+  /** Auth token for protected endpoints. Required for bearer/header auth on server. */
+  token?: string | null;
+  /** Organization ID for multi-tenant prefetch. Sent as x-organization-id header. */
+  organizationId?: string | null;
+  /** Additional headers (e.g., x-api-key for header auth). */
+  headers?: Record<string, string>;
+}
+interface PrefetchOptions extends PrefetchAuthContext {
   staleTime?: number;
 }
 interface PrefetchDetailOptions extends PrefetchOptions {
@@ -43,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.
@@ -74,28 +93,43 @@ declare function createCrudPrefetcher(api: {
     params?: Record<string, unknown>;
     token?: string | null;
     organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
   getById: (opts: {
     id: string;
     token?: string | null;
     organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
   getBySlug?: (opts: {
     slug: string;
     token?: string | null;
     organizationId?: string | null;
     params?: Record<string, unknown>;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
   getDeleted?: (opts: {
     params?: Record<string, unknown>;
     token?: string | null;
     organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
   getTree?: (opts: {
     params?: Record<string, unknown>;
     token?: string | null;
     organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
 }, entityKey: string): CrudPrefetcher;
 //#endregion
-export { CrudPrefetcher, 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
 /**
@@ -31,81 +31,120 @@ function createCrudPrefetcher(api, entityKey) {
 	const KEYS = createQueryKeys(entityKey);
 	return {
 		async prefetchList(queryClient, params = {}, options = {}) {
-			const { organizationId, ...restParams } = params;
-			const scope = organizationId ? "tenant" : "super-admin";
+			const { organizationId: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
+			const scope = orgId ? "tenant" : "super-admin";
 			const queryKey = KEYS.scopedList(scope, {
-				organizationId,
+				...orgId ? { organizationId: orgId } : {},
 				...restParams
 			});
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getAll({
 					params: restParams,
-					organizationId: organizationId ?? null
+					token: options.token ?? null,
+					organizationId: orgId,
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchDetail(queryClient, id, options = {}) {
-			const { params, staleTime } = options;
+			const { params, staleTime, token, organizationId } = options;
 			const baseKey = KEYS.detail(id);
 			const queryKey = params ? [...baseKey, params] : baseKey;
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getById({
 					id,
-					...params ? { params } : {}
+					token: token ?? null,
+					organizationId: organizationId ?? null,
+					...params ? { params } : {},
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime
 			});
 		},
 		async prefetchBySlug(queryClient, slug, options = {}) {
 			if (!api.getBySlug) throw new Error(`[arc-next] prefetchBySlug requires an api with getBySlug (slugLookup preset)`);
-			const { params, staleTime } = options;
+			const { params, staleTime, token, organizationId } = options;
 			const queryKey = params ? KEYS.custom("slug", slug, params) : KEYS.custom("slug", slug);
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getBySlug({
 					slug,
-					...params ? { params } : {}
+					token: token ?? null,
+					organizationId: organizationId ?? null,
+					...params ? { params } : {},
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime
 			});
 		},
 		async prefetchDeleted(queryClient, params = {}, options = {}) {
 			if (!api.getDeleted) throw new Error(`[arc-next] prefetchDeleted requires an api with getDeleted (softDelete preset)`);
-			const { organizationId, ...restParams } = params;
+			const { organizationId: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
 			const queryKey = KEYS.custom("deleted", {
-				organizationId,
+				...orgId ? { organizationId: orgId } : {},
 				...restParams
 			});
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getDeleted({
 					params: restParams,
-					organizationId: organizationId ?? null
+					token: options.token ?? null,
+					organizationId: orgId,
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchTree(queryClient, params = {}, options = {}) {
 			if (!api.getTree) throw new Error(`[arc-next] prefetchTree requires an api with getTree (tree preset)`);
-			const { organizationId, ...restParams } = params;
+			const { organizationId: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
 			const queryKey = KEYS.custom("tree", {
-				organizationId,
+				...orgId ? { organizationId: orgId } : {},
 				...restParams
 			});
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getTree({
 					params: restParams,
-					organizationId: organizationId ?? null
+					token: options.token ?? null,
+					organizationId: orgId,
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				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 };

package/dist/presets/slug.js

@@ -0,0 +1,27 @@
+//#region src/presets/slug.ts
+/**
+* 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' });
+*/
+function withSlugLookup(api) {
+	return Object.assign(api, { async getBySlug({ token = null, organizationId = null, slug, params = {}, options = {} }) {
+		if (!slug) throw new Error("Slug is required");
+		return api.request("GET", `${api.baseUrl}/slug/${slug}`, {
+			token,
+			organizationId,
+			params,
+			options
+		});
+	} });
+}
+
+//#endregion
+export { withSlugLookup };

package/dist/presets/soft-delete.d.ts

@@ -0,0 +1,33 @@
+import { ApiResponse, BaseApi, PaginatedResponse, QueryParams, ScopedArgs } from "../api.js";
+
+//#region src/presets/soft-delete.d.ts
+interface SoftDeleteMethods<TDoc> {
+  /** List soft-deleted docs. Backend mounts `GET /:resource/deleted`. */
+  getDeleted(args?: ScopedArgs & {
+    params?: QueryParams;
+  }): Promise<PaginatedResponse<TDoc>>;
+  /** Undo a soft-delete. Backend mounts `POST /:resource/:id/restore`. */
+  restore(args: ScopedArgs & {
+    id: string;
+  }): Promise<ApiResponse<TDoc>>;
+}
+/**
+ * Adds soft-delete preset methods to a BaseApi.
+ *
+ * Mirrors arc's server-side `softDelete` preset routes. Use when your resource
+ * is registered with `presets: ['softDelete']`. With this preset, `delete()`
+ * becomes soft-delete on the backend and {@link SoftDeleteMethods.restore}
+ * undoes it; {@link SoftDeleteMethods.getDeleted} lists the tombstones.
+ *
+ * @example
+ * import { createCrudApi } from '@classytic/arc-next/api';
+ * import { withSoftDelete } from '@classytic/arc-next/presets/soft-delete';
+ *
+ * const todos = withSoftDelete(createCrudApi<Todo>('todos'));
+ * await todos.delete({ id });             // soft delete (backend)
+ * await todos.restore({ id });            // undo
+ * const trash = await todos.getDeleted();
+ */
+declare function withSoftDelete<TDoc, TCreate, TUpdate>(api: BaseApi<TDoc, TCreate, TUpdate>): BaseApi<TDoc, TCreate, TUpdate> & SoftDeleteMethods<TDoc>;
+//#endregion
+export { SoftDeleteMethods, withSoftDelete };

package/dist/presets/soft-delete.js

@@ -0,0 +1,45 @@
+//#region src/presets/soft-delete.ts
+/**
+* Adds soft-delete preset methods to a BaseApi.
+*
+* Mirrors arc's server-side `softDelete` preset routes. Use when your resource
+* is registered with `presets: ['softDelete']`. With this preset, `delete()`
+* becomes soft-delete on the backend and {@link SoftDeleteMethods.restore}
+* undoes it; {@link SoftDeleteMethods.getDeleted} lists the tombstones.
+*
+* @example
+* import { createCrudApi } from '@classytic/arc-next/api';
+* import { withSoftDelete } from '@classytic/arc-next/presets/soft-delete';
+*
+* const todos = withSoftDelete(createCrudApi<Todo>('todos'));
+* await todos.delete({ id });             // soft delete (backend)
+* await todos.restore({ id });            // undo
+* const trash = await todos.getDeleted();
+*/
+function withSoftDelete(api) {
+	return Object.assign(api, {
+		async getDeleted({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+			const merged = {
+				...api.config.defaultParams,
+				...params
+			};
+			return api.request("GET", `${api.baseUrl}/deleted`, {
+				token,
+				organizationId,
+				params: merged,
+				options
+			});
+		},
+		async restore({ token = null, organizationId = null, id, options = {} }) {
+			if (!id) throw new Error("ID is required");
+			return api.request("POST", `${api.baseUrl}/${id}/restore`, {
+				token,
+				organizationId,
+				options
+			});
+		}
+	});
+}
+
+//#endregion
+export { withSoftDelete };

package/dist/presets/tree.d.ts

@@ -0,0 +1,31 @@
+import { ApiResponse, BaseApi, PaginatedResponse, QueryParams, ScopedArgs } from "../api.js";
+
+//#region src/presets/tree.d.ts
+interface TreeMethods<TDoc> {
+  /** Fetch the full hierarchy. Backend mounts `GET /:resource/tree`. */
+  getTree(args?: ScopedArgs & {
+    params?: QueryParams;
+  }): Promise<ApiResponse<TDoc[]>>;
+  /** Fetch direct children of a node. Backend mounts `GET /:resource/:id/children`. */
+  getChildren(args: ScopedArgs & {
+    parentId: string;
+    params?: QueryParams;
+  }): Promise<PaginatedResponse<TDoc>>;
+}
+/**
+ * Adds tree preset methods to a BaseApi.
+ *
+ * Mirrors arc's `tree` preset — for resources with a `parentId` field, exposes
+ * `getTree` (full hierarchy) and `getChildren` (one level deep). Backend caps
+ * tree depth via the preset config.
+ *
+ * @example
+ * import { withTree } from '@classytic/arc-next/presets/tree';
+ * const categories = withTree(createCrudApi<Category>('categories'));
+ *
+ * const root = await categories.getTree();
+ * const kids = await categories.getChildren({ parentId: 'engineering' });
+ */
+declare function withTree<TDoc, TCreate, TUpdate>(api: BaseApi<TDoc, TCreate, TUpdate>): BaseApi<TDoc, TCreate, TUpdate> & TreeMethods<TDoc>;
+//#endregion
+export { TreeMethods, withTree };