@classytic/arc-next 0.2.0 → 0.3.1

package/README.md

@@ -30,13 +30,13 @@ 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)
-  internalApiKey: process.env.NEXT_PUBLIC_INTERNAL_API_KEY, // optional
+  authMode: "cookie",   // 'cookie' for Better Auth, 'bearer' for token auth (default)
+  // credentials: 'omit', // override if you don't want cookies sent cross-origin
 });
 
-// Optional — auto-inject org context into queries/mutations
+// Optional — auto-inject tenant context into queries/mutations
 configureAuth({
-  getOrgId: () => activeOrgId, // return current org ID
+  getOrgId: () => activeTenantId, // return current tenant/org/workspace ID
   getToken: () => null, // null for cookie auth (token only for bearer)
 });
 
@@ -51,10 +51,11 @@ configureNavigation(useRouter);
 
 | Import                              | Purpose                                                                      | `"use client"` |
 | ----------------------------------- | ---------------------------------------------------------------------------- | :-------------: |
+| `@classytic/arc-next`               | Root — same as `/hooks` (`createCrudHooks`, `configureNavigation`)           |      Yes        |
 | `@classytic/arc-next/client`        | `configureClient`, `configureAuth`, `createClient`, `handleApiRequest`, `createQueryString`, `ArcApiError`, `isArcApiError`, `getAuthMode`, `getAuthContext` |       No        |
 | `@classytic/arc-next/api`           | `BaseApi`, `createCrudApi`, response types, type guards                      |       No        |
-| `@classytic/arc-next/query`         | `createQueryKeys`, `createCacheUtils`, `createListQuery`, `createDetailQuery`|      Yes        |
-| `@classytic/arc-next/mutation`      | `configureToast`, `useMutationWithTransition`, `createOptimisticMutation`    |      Yes        |
+| `@classytic/arc-next/query`         | `createQueryKeys`, `createCacheUtils`, `useListQuery`, `useDetailQuery`      |      Yes        |
+| `@classytic/arc-next/mutation`      | `configureToast`, `useMutationWithTransition`, `useOptimisticMutation`       |      Yes        |
 | `@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        |
@@ -148,13 +149,15 @@ export function ProductsPage() {
 configureClient({
   baseUrl: string;                          // Required — API base URL
   authMode?: 'cookie' | 'bearer';          // 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
 });
 ```
 
-- `authMode: 'bearer'` (default) — requires a token for authenticated requests; queries are disabled until a token is provided
-- `authMode: 'cookie'` — auth via HTTP-only cookies (e.g. Better Auth); queries are always enabled, no token needed
+- `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)
 
 Must be called before any API requests. Throws if not configured.
 
@@ -167,7 +170,7 @@ configureAuth({
 });
 ```
 
-Auto-injects `token` and `organizationId` into queries/mutations. Hooks use the new signature (no explicit token param) — legacy signature still works.
+Auto-injects `token` and tenant ID (sent as `x-organization-id` header) into queries/mutations. The header name is a convention — your backend controls how it's read and which field it maps to (`organizationId`, `workspaceId`, `teamId`, etc.). Hooks use the new signature (no explicit token param) — legacy signature still works.
 
 ### `handleApiRequest<T>(method, endpoint, options?)`
 
@@ -226,7 +229,7 @@ const api = createCrudApi<Product, CreateProduct>("products", {
 
 ### `createCrudHooks<T, TCreate, TUpdate>(config)`
 
-Factory that returns everything you need:
+Factory that returns everything you need. The `api` parameter accepts any `createCrudApi()` result directly — no casts needed. Types are derived from `BaseApi` via `Pick`, so generics thread through automatically:
 
 ```ts
 const {
@@ -235,7 +238,7 @@ const {
   useActions, useUpload, useSearch, useCustomMutation,
   useNavigation,
 } = createCrudHooks<Product, CreateProduct>({
-    api: productsApi,       // from createCrudApi()
+    api: productsApi,       // from createCrudApi() — types inferred, no cast
     entityKey: "products",  // TanStack Query key prefix
     singular: "Product",    // for toast messages
     defaults: {             // optional
@@ -263,7 +266,7 @@ const { items, pagination, isLoading, isFetching, refetch } = useList(
 );
 ```
 
-- Auto-scopes query keys by `organizationId` (tenant vs super-admin)
+- Auto-scopes list query keys by tenant context (when present → `tenant` scope, otherwise → `super-admin`)
 - Normalizes pagination from `docs`/`data`/`items`/`results` formats
 - Prefills detail cache from list results (skips re-fetch on navigate)
 - `options.public: true` — enables query without token
@@ -534,7 +537,7 @@ useProducts(token, {}, { ...QUERY_CONFIGS.realtime });
 
 ### `updateListCache(listData, updater)`
 
-Transforms list cache regardless of format (`docs[]`, `data[]`, `items[]`, `results[]`, or raw array).
+Transforms list cache regardless of format — well-known keys (`docs[]`, `data[]`, `items[]`, `results[]`), custom keys (`products[]`, `users[]`, etc.), or raw arrays.
 Automatically adjusts `total`/`totalDocs` counts when items are added or removed (optimistic add/delete).
 
 ```ts
@@ -551,11 +554,11 @@ Extracts `_id` or `id` from any item. Returns `string | null`.
 
 ### `normalizePagination(data)`
 
-Converts any pagination response format to a normalized `PaginationData` object. Handles `total`/`totalDocs`, `pages`/`totalPages`, `page`/`currentPage`, `hasNext`/`hasNextPage`/`hasMore`, `hasPrev`/`hasPrevPage`.
+Converts any pagination response format to a normalized `PaginationData` object. Detects pagination method (`offset`, `keyset`, `aggregate`) and normalizes all fields: `total`/`totalDocs`, `pages`/`totalPages`, `page`/`currentPage`, `hasNext`/`hasNextPage`/`hasMore`, `hasPrev`/`hasPrevPage`, `next` (keyset cursor).
 
 ### `extractItems<T>(data)`
 
-Extracts the items array from any response format — looks for `docs`, `data`, `items`, `results` fields, or returns the data directly if it's already an array.
+Extracts the items array from any response format. Checks well-known keys first (`docs`, `data`, `items`, `results`), then falls back to finding the first top-level array — so `{ products: [...] }` or `{ users: [...] }` works without configuration.
 
 ## Multi-Client (Multiple APIs)
 
@@ -654,8 +657,10 @@ try {
 ### Multi-tenant data fetching
 
 ```ts
-// organizationId in params → scoped query key → isolated cache per tenant
-const { items } = useProducts(token, { organizationId: currentOrg });
+// Tenant ID in params → scoped query key → isolated cache per tenant
+// The param name is up to you — arc-next sends it as x-organization-id header,
+// your backend maps it to whatever tenant field your schema uses.
+const { items } = useProducts(token, { organizationId: currentTenantId });
 ```
 
 ### Public endpoints (no auth)
@@ -704,11 +709,11 @@ const adminApi = createCrudApi("users", {
 
 - **CRUD Factory** — `createCrudApi` + `createCrudHooks` generates typed API clients and React Query hooks
 - **Optimistic Updates** — Create, update, delete with instant UI feedback and automatic rollback
-- **Multi-Tenant Scoping** — `organizationId` in headers + scoped query keys
-- **Pagination Normalization** — Handles `docs`/`data`/`items`/`results` response formats, offset/keyset/aggregate pagination
+- **Multi-Tenant Scoping** — Tenant ID sent via `x-organization-id` header + scoped list query keys. Backend controls the tenant field name and access enforcement.
+- **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
+- **Cookie & Bearer Auth** — `authMode: 'cookie'` for Better Auth, `'bearer'` for token auth, configurable `credentials` policy
 - **SSR Prefetch** — `createCrudPrefetcher` + `dehydrate` for server component data loading
 - **Multi-Client** — `createClient()` for multiple API backends side by side
 - **Pluggable Toast** — `configureToast()` — use sonner, react-hot-toast, or anything

package/dist/api.d.ts

@@ -225,5 +225,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 };
-//# sourceMappingURL=api.d.ts.map
+export { AggregatePaginationResponse, ApiResponse, BaseApi, BaseApiConfig, DeleteResponse, ExtractDoc, FilterOperator, KeysetPaginationResponse, OffsetPaginationResponse, PaginatedResponse, PopulateOption, QueryParams, RequestOptions, SortDirection, SortSpec, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };

package/dist/api.js

@@ -57,7 +57,11 @@ var BaseApi = class {
 		return result;
 	}
 	async getAll({ token = null, organizationId = null, params = {}, options = {} } = {}) {
-		const processedParams = this.prepareParams(params);
+		const mergedParams = {
+			...this.config.defaultParams,
+			...params
+		};
+		const processedParams = this.prepareParams(mergedParams);
 		const queryString = this.createQueryString(processedParams);
 		const requestOptions = {
 			cache: this.config.cache,
@@ -118,6 +122,7 @@ var BaseApi = class {
 	}
 	async search({ token = null, organizationId = null, searchParams = {}, params = {}, options = {} } = {}) {
 		const queryParams = {
+			...this.config.defaultParams,
 			...params,
 			...searchParams
 		};
@@ -133,7 +138,10 @@ var BaseApi = class {
 	}
 	async findBy({ token = null, organizationId = null, field, value, operator, params = {}, options = {} }) {
 		if (!field || value === void 0) throw new Error("Field and value are required");
-		const queryParams = { ...params };
+		const queryParams = {
+			...this.config.defaultParams,
+			...params
+		};
 		if (operator) queryParams[`${field}[${operator}]`] = Array.isArray(value) ? value.join(",") : value;
 		else queryParams[field] = value;
 		const processedParams = this.prepareParams(queryParams);
@@ -176,5 +184,4 @@ function isAggregatePagination(response) {
 }
 
 //#endregion
-export { BaseApi, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };
-//# sourceMappingURL=api.js.map
+export { BaseApi, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };

package/dist/client.d.ts

@@ -56,10 +56,25 @@ interface ClientConfig {
    * - 'cookie': Auth is handled via HTTP-only cookies (e.g. Better Auth). Queries are always enabled — no token needed.
    */
   authMode?: 'bearer' | 'cookie';
+  /**
+   * 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;
 }
 /**
  * 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! });
@@ -80,6 +95,8 @@ interface AuthConfig {
  * 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 });
@@ -168,5 +185,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, BlobResponse, ClientConfig, HttpMethod, TextResponse, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError };

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! });
@@ -64,6 +68,8 @@ 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 });
@@ -122,10 +128,11 @@ async function executeRequest(config, method, endpoint, options = {}) {
 			...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 +184,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 +245,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 };

package/dist/hooks.d.ts

@@ -1,65 +1,21 @@
 import { ArcClient, UseRouterHook } from "./client.js";
+import { BaseApi } 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";
 
 //#region src/hooks.d.ts
-interface CrudApi<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
-  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'];
+};
 interface CrudHooksConfig<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
   api: CrudApi<T, TCreate, TUpdate>;
   entityKey: string;
@@ -167,6 +123,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);
@@ -181,5 +139,4 @@ declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>(
   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 { CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };