@classytic/arc-next 0.2.1 → 0.4.0

package/dist/client.d.ts

@@ -55,11 +55,38 @@ 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).
+   * - 'same-origin': Only send cookies to same-origin requests (browser default).
+   * - 'omit': Never send cookies.
+   *
+   * When not set, derived from `authMode`:
+   * - `authMode: 'cookie'` → `'include'`
+   * - `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.
  *
+ * **SSR safety:** This sets module-level state. In Next.js, call this only in
+ * client-side code (e.g. a `"use client"` provider or `useEffect`).
+ * Calling on the server risks leaking state between requests.
+ *
  * @example
  * // Bearer token auth (default)
  * configureClient({ baseUrl: process.env.NEXT_PUBLIC_API_URL! });
@@ -71,15 +98,21 @@ 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.
  * 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.
+ *
  * @example
  * // Cookie auth (no token needed)
  * configureAuth({ getOrgId: () => currentOrg.id });
@@ -108,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;
@@ -168,5 +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 };
-//# sourceMappingURL=client.d.ts.map
+export { ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, AuthConfig, ClientConfig, HttpMethod, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError, isAutoIdempotency };

package/dist/client.js

@@ -43,6 +43,10 @@ let clientConfig = null;
 /**
 * Configure the API client. Call once at app init before any API requests.
 *
+* **SSR safety:** This sets module-level state. In Next.js, call this only in
+* client-side code (e.g. a `"use client"` provider or `useEffect`).
+* Calling on the server risks leaking state between requests.
+*
 * @example
 * // Bearer token auth (default)
 * configureClient({ baseUrl: process.env.NEXT_PUBLIC_API_URL! });
@@ -51,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;
 }
 /**
@@ -59,11 +64,17 @@ 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.
 * 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.
+*
 * @example
 * // Cookie auth (no token needed)
 * configureAuth({ getOrgId: () => currentOrg.id });
@@ -75,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;
 }
 /**
@@ -109,23 +121,29 @@ 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,
 			...headerOptions
 		};
+		const credentials = config.credentials ?? (config.authMode === "cookie" ? "include" : "same-origin");
 		const fetchOptions = {
 			method,
 			headers,
-			credentials: "include",
+			credentials,
 			...signal ? { signal } : {}
 		};
 		if (body !== void 0 && body !== null) fetchOptions.body = body instanceof FormData ? body : JSON.stringify(body);
@@ -177,8 +195,8 @@ async function executeRequest(config, method, endpoint, options = {}) {
 		}
 		return data;
 	} catch (error) {
-		if (error instanceof ArcApiError) throw error;
-		throw new Error(error instanceof Error ? error.message : "An error occurred while fetching data.");
+		if (error instanceof Error) throw error;
+		throw new Error("An error occurred while fetching data.");
 	}
 }
 /**
@@ -238,5 +256,4 @@ function createQueryString(params = {}) {
 }
 
 //#endregion
-export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError };
-//# sourceMappingURL=client.js.map
+export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError, isAutoIdempotency };

package/dist/hooks.d.ts

@@ -1,84 +1,46 @@
 import { ArcClient, UseRouterHook } from "./client.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
-interface CrudApi<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
-  /** Scope from BaseApi — used to auto-detect platformScoped */
-  scope?: 'tenant' | 'platform';
-  getAll: (options: {
-    token?: string | null;
-    organizationId?: string | null;
-    params?: Record<string, unknown>;
-    options?: {
-      signal?: AbortSignal;
-      [key: string]: unknown;
-    };
-  }) => Promise<unknown>;
-  getById: (options: {
-    id: string;
-    token?: string | null;
-    organizationId?: string | null;
-    params?: {
-      select?: string;
-      populate?: string | string[];
-    };
-    options?: {
-      signal?: AbortSignal;
-      [key: string]: unknown;
-    };
-  }) => Promise<unknown>;
-  create: (options: {
-    token?: string | null;
-    organizationId?: string | null;
-    data: TCreate;
-  }) => Promise<unknown>;
-  update: (options: {
-    token?: string | null;
-    organizationId?: string | null;
-    id: string;
-    data: TUpdate;
-  }) => Promise<unknown>;
-  delete: (options: {
-    token?: string | null;
-    organizationId?: string | null;
-    id: string;
-  }) => Promise<unknown>;
-  upload?: (options: {
-    token?: string | null;
-    organizationId?: string | null;
-    data: FormData;
-    id?: string;
-    path?: string;
-  }) => Promise<unknown>;
-  search?: (options: {
-    token?: string | null;
-    organizationId?: string | null;
-    params?: Record<string, unknown>;
-    options?: {
-      signal?: AbortSignal;
-      [key: string]: unknown;
-    };
-  }) => Promise<unknown>;
-}
+/**
+ * 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.
+ */
+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;
   /**
-   * Platform-scoped hooks skip automatic organizationId injection.
+   * Primary key field used to extract item IDs from response data.
+   * Used for cache key resolution, optimistic updates, and detail cache prefill.
    *
-   * Use this for admin/superadmin hooks that query across all orgs
-   * (e.g., APIs configured with `x-arc-scope: platform`).
+   * Default lookup order: `_id` → `id`.
+   * Set this when your resource uses a custom ID field (e.g., `'sku'`, `'slug'`, `'code'`).
    *
-   * When true, the hooks will NOT auto-inject the user's active
-   * organizationId into requests — the API's own headers control scoping.
-   *
-   * @default false
+   * @example
+   * createCrudHooks({ idField: 'sku', ... }) // GET /products/:sku
    */
-  platformScoped?: boolean;
+  idField?: string;
   defaults?: {
     staleTime?: number;
     gcTime?: number;
@@ -130,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;
@@ -156,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;
@@ -181,6 +175,8 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
 /**
  * Configure the router hook for useNavigation. Call once at app init.
  *
+ * **SSR safety:** This sets module-level state. Call only in client-side code.
+ *
  * @example
  * import { useRouter } from "next/navigation";
  * configureNavigation(useRouter);
@@ -190,11 +186,11 @@ declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>(
   api,
   entityKey,
   singular,
-  platformScoped,
+  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, type UseRouterHook, configureNavigation, createCrudHooks };
-//# sourceMappingURL=hooks.d.ts.map
+export { BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };