@classytic/arc-next 0.4.0 → 0.5.0

package/dist/hooks.d.ts

@@ -1,30 +1,31 @@
 import { ArcClient, UseRouterHook } from "./client.js";
-import { BaseApi, FilterOperator } from "./api.js";
-import { CacheUtils, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, QueryKeys } from "./query.js";
+import { ApiResponse, BaseApi } from "./api.js";
+import { CacheUtils, QueryKeys } from "./cache.js";
 import { MutationCallbacks, MutationMessages, TransitionMutationReturn } from "./mutation.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>;
 }
 /**