@classytic/arc-next 0.3.1 → 0.4.1

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,16 @@ 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';
+/** Get the configured base URL. Returns empty string if not configured. */
+declare function getBaseUrl(): string;
+/** 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.
@@ -116,6 +134,16 @@ declare function getAuthContext(): {
   organizationId: string | null;
 };
 type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+/** Returned by `handleApiRequest` for PDF, image, and CSV responses. */
+interface BlobResponse {
+  data: Blob;
+  response: Response;
+}
+/** Returned by `handleApiRequest` for text/plain and text/html responses. */
+interface TextResponse {
+  data: string;
+  response: Response;
+}
 interface ApiRequestOptions {
   body?: unknown;
   token?: string | null;
@@ -125,39 +153,58 @@ 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;
   navigation?: UseRouterHook;
+  /** Per-client token provider. Overrides global configureAuth().getToken. */
+  getToken?: () => string | null;
+  /** Per-client org ID provider. Overrides global configureAuth().getOrgId. */
+  getOrgId?: () => string | null;
+  /** Per-client custom auth header name. Used when authMode is 'header'. */
+  headerName?: string;
 }
 interface ArcClient {
   request: <T = unknown>(method: HttpMethod, endpoint: string, options?: ApiRequestOptions) => Promise<T>;
   config: ClientConfig;
   toast?: ToastHandler;
   navigation?: UseRouterHook;
+  /** Per-client auth context. Falls back to global configureAuth() when not set. */
+  auth?: {
+    getToken?: () => string | null;
+    getOrgId?: () => string | null;
+    headerName?: string;
+  };
 }
 /**
  * Create an isolated API client for a specific backend.
- * Use this when your app needs to talk to multiple APIs.
+ * Use this when your app needs to talk to multiple APIs with different auth.
  *
  * @example
+ * // Bearer auth for main API
+ * const mainClient = createClient({
+ *   baseUrl: 'https://api.example.com',
+ *   getToken: () => session.accessToken,
+ * });
+ *
+ * // API key auth for analytics
  * const analyticsClient = createClient({
  *   baseUrl: 'https://analytics.example.com',
- *   toast: { success: toast.success, error: toast.error },
- *   navigation: useRouter,
+ *   authMode: 'header',
+ *   getToken: () => env.ANALYTICS_KEY,
+ *   headerName: 'x-api-key',
  * });
- *
- * const eventsApi = createCrudApi('events', { client: analyticsClient });
  */
 declare function createClient(config: ArcClientConfig): ArcClient;
+/**
+ * Get auth context for a specific client instance, falling back to global.
+ */
+declare function getClientAuthContext(client?: ArcClient): {
+  token: string | null;
+  organizationId: string | null;
+};
 /**
  * Universal API request handler.
  * Handles JSON, binary (PDF, images), CSV, and text responses.
@@ -185,4 +232,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, BlobResponse, ClientConfig, HttpMethod, TextResponse, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, 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,14 @@ function configureClient(config) {
 function getAuthMode() {
 	return clientConfig?.authMode ?? "bearer";
 }
+/** Get the configured base URL. Returns empty string if not configured. */
+function getBaseUrl() {
+	return clientConfig?.baseUrl ?? "";
+}
+/** 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 +90,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;
 }
 /**
@@ -94,35 +104,77 @@ function getAuthContext() {
 }
 /**
 * Create an isolated API client for a specific backend.
-* Use this when your app needs to talk to multiple APIs.
+* Use this when your app needs to talk to multiple APIs with different auth.
 *
 * @example
+* // Bearer auth for main API
+* const mainClient = createClient({
+*   baseUrl: 'https://api.example.com',
+*   getToken: () => session.accessToken,
+* });
+*
+* // API key auth for analytics
 * const analyticsClient = createClient({
 *   baseUrl: 'https://analytics.example.com',
-*   toast: { success: toast.success, error: toast.error },
-*   navigation: useRouter,
+*   authMode: 'header',
+*   getToken: () => env.ANALYTICS_KEY,
+*   headerName: 'x-api-key',
 * });
-*
-* const eventsApi = createCrudApi('events', { client: analyticsClient });
 */
 function createClient(config) {
-	const { toast, navigation, ...clientCfg } = config;
+	const { toast, navigation, getToken, getOrgId, headerName, ...clientCfg } = config;
+	const clientAuth = getToken || getOrgId || headerName ? {
+		getToken,
+		getOrgId,
+		headerName
+	} : void 0;
 	return {
-		request: (method, endpoint, options) => executeRequest(clientCfg, method, endpoint, options),
+		request: (method, endpoint, options) => {
+			if (clientAuth) {
+				const resolved = { ...options };
+				if (resolved.token === void 0 && clientAuth.getToken) resolved.token = clientAuth.getToken();
+				if (resolved.organizationId === void 0 && clientAuth.getOrgId) resolved.organizationId = clientAuth.getOrgId();
+				if (clientCfg.authMode === "header" && resolved.token) {
+					resolved.headerOptions = {
+						[clientAuth.headerName ?? "x-api-key"]: resolved.token,
+						...resolved.headerOptions ?? {}
+					};
+					resolved.token = void 0;
+				}
+				return executeRequest(clientCfg, method, endpoint, resolved);
+			}
+			return executeRequest(clientCfg, method, endpoint, options);
+		},
 		config: clientCfg,
 		toast,
-		navigation
+		navigation,
+		auth: clientAuth
 	};
 }
+/**
+* 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,
+		organizationId: client.auth.getOrgId?.() ?? authConfig?.getOrgId?.() ?? null
+	};
+	return getAuthContext();
+}
 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,
@@ -147,8 +199,21 @@ async function executeRequest(config, method, endpoint, options = {}) {
 		};
 		const response = await fetch(`${config.baseUrl}${endpoint}`, fetchOptions);
 		if (!response.ok) {
-			const json = await response.json().catch(() => null);
-			throw new ArcApiError(json?.message || response.statusText, {
+			let json = null;
+			let errorMessage = response.statusText;
+			try {
+				json = await response.clone().json();
+				errorMessage = json?.message || response.statusText;
+			} catch {
+				try {
+					const text = await response.text();
+					if (text) {
+						json = { rawBody: text };
+						errorMessage = text.slice(0, 200) || response.statusText;
+					}
+				} catch {}
+			}
+			throw new ArcApiError(errorMessage, {
 				status: response.status,
 				statusText: response.statusText,
 				json,
@@ -176,11 +241,15 @@ async function executeRequest(config, method, endpoint, options = {}) {
 				data: await response.clone().blob(),
 				response
 			};
-		} catch {
-			data = {
-				data: await response.text(),
-				response
-			};
+		} catch (blobError) {
+			try {
+				data = {
+					data: await response.text(),
+					response
+				};
+			} catch {
+				throw new Error(`Failed to parse response body from ${method} ${endpoint}: blob error: ${blobError instanceof Error ? blobError.message : String(blobError)}`);
+			}
 		}
 		return data;
 	} catch (error) {
@@ -245,4 +314,4 @@ function createQueryString(params = {}) {
 }
 
 //#endregion
-export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError };
+export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isArcApiError, isAutoIdempotency };

package/dist/hooks.d.ts

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