@classytic/arc-next 0.9.0 → 0.10.0

package/dist/cache.d.ts

@@ -110,6 +110,20 @@ interface QueryKeys {
  * is identical between server (prefetch) and client (hooks), so RSC SSR
  * hydration matches what client-side `useList`/`useDetail` produce.
  */
+/**
+ * Org-normalized key params — the ONE way hooks AND prefetchers merge
+ * `organizationId` into a query-key params object.
+ *
+ * Why this exists: TanStack's key hash (`hashKey`) drops `undefined` object
+ * values but KEEPS `null` — so `{ organizationId: null }` and `{}` are
+ * DIFFERENT cache entries. Auth resolution returns `organizationId: null`
+ * for org-less callers (public storefronts), while server prefetchers
+ * conditionally omitted the field — producing keys that never matched and
+ * silently defeating SSR hydration (the client refetched everything).
+ * Normalizing here (omit when nullish) makes hook and prefetch keys equal
+ * by construction. Covered by tests/key-parity.test.ts.
+ */
+declare function withOrgParams(organizationId: string | null | undefined, params?: Record<string, unknown>): Record<string, unknown>;
 declare function createQueryKeys(entityKey: string): QueryKeys;
 interface CacheUtils<T> {
   invalidateAll: (client: QueryClient) => Promise<void>;
@@ -149,4 +163,4 @@ interface CacheUtils<T> {
  */
 declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
 //#endregion
-export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache };
+export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache, withOrgParams };

package/dist/cache.js

@@ -221,6 +221,26 @@ function mergeItemIntoListPage(page, targetId, item, idField) {
 * is identical between server (prefetch) and client (hooks), so RSC SSR
 * hydration matches what client-side `useList`/`useDetail` produce.
 */
+/**
+* Org-normalized key params — the ONE way hooks AND prefetchers merge
+* `organizationId` into a query-key params object.
+*
+* Why this exists: TanStack's key hash (`hashKey`) drops `undefined` object
+* values but KEEPS `null` — so `{ organizationId: null }` and `{}` are
+* DIFFERENT cache entries. Auth resolution returns `organizationId: null`
+* for org-less callers (public storefronts), while server prefetchers
+* conditionally omitted the field — producing keys that never matched and
+* silently defeating SSR hydration (the client refetched everything).
+* Normalizing here (omit when nullish) makes hook and prefetch keys equal
+* by construction. Covered by tests/key-parity.test.ts.
+*/
+function withOrgParams(organizationId, params = {}) {
+	const { organizationId: _drop, ...rest } = params;
+	return organizationId ? {
+		organizationId,
+		...rest
+	} : rest;
+}
 function createQueryKeys(entityKey) {
 	return {
 		all: [entityKey],
@@ -300,4 +320,4 @@ function createCacheUtils(KEYS) {
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache, withOrgParams };

package/dist/field-encryption.d.ts

@@ -0,0 +1,86 @@
+//#region src/field-encryption.d.ts
+/**
+ * `@classytic/arc-next/field-encryption` — client decrypt for arc's
+ * FIELD-mode ALE (`@classytic/arc/encryption` with `mode: 'fields'`).
+ *
+ * Field-mode responses stay `application/json`; only the configured field
+ * VALUES arrive as authenticated `arc.v1` envelopes
+ * (`arc.v1.<b64url(kid)>.<b64url(iv)>.<b64url(ct)>.<b64url(tag)>`,
+ * AES-256-GCM). This helper parses and decrypts those envelopes with the
+ * shared symmetric key, via Web Crypto — zero dependencies, works in Node
+ * 22+, Bun, Deno, and React Native (with a Web Crypto polyfill).
+ *
+ * ── SECURITY: trusted runtimes ONLY ─────────────────────────────────────
+ * Field mode is SYMMETRIC — whoever holds the key can decrypt every
+ * envelope ever produced under it. That key belongs in a Node BFF, a
+ * server component, or a native app's secure storage. It must NEVER ship
+ * in a browser bundle: anything readable by browser JavaScript is readable
+ * by every visitor. For payloads a browser must decrypt, use the
+ * asymmetric JWE path (`@classytic/arc-next/encryption`) instead — that is
+ * exactly why this lives in its own subpath the web bundle never imports.
+ * ────────────────────────────────────────────────────────────────────────
+ *
+ * Fail-closed: unknown `kid`, tampered ciphertext, or a malformed
+ * `arc.v1.*` token throws — an encrypted field is never silently passed
+ * through as ciphertext or dropped.
+ *
+ * @example Node BFF / server component
+ * ```ts
+ * import { createFieldDecryption } from '@classytic/arc-next/field-encryption';
+ *
+ * const ale = createFieldDecryption({
+ *   // 32-byte AES-256 keys by kid — keep the previous kid during rotation.
+ *   keys: { 'k-2026-07': keyBytes },
+ * });
+ *
+ * configureClient({
+ *   baseUrl: env.ARC_URL,
+ *   afterResponse: async (ctx) => {
+ *     // arc stamps `x-encrypted: true` on field-mode responses — only
+ *     // those are scanned; every other response passes through untouched.
+ *     if (ctx.response.headers.get('x-encrypted') === 'true') {
+ *       ctx.body = await ale.decryptFieldsDeep(ctx.body);
+ *     }
+ *     return ctx;
+ *   },
+ * });
+ * ```
+ */
+/** Version prefix shared with `@classytic/arc/encryption`'s field cipher. */
+declare const FIELD_ENVELOPE_PREFIX = "arc.v1";
+/** Parsed `arc.v1` envelope — `kid` exposed for key resolution. */
+interface ParsedFieldEnvelope {
+  readonly kid: string;
+  readonly iv: Uint8Array;
+  readonly ciphertext: Uint8Array;
+  readonly tag: Uint8Array;
+}
+interface FieldDecryptionOptions {
+  /**
+   * 32-byte AES-256 keys indexed by `kid`. Keep 2–3 entries across a key
+   * rotation so envelopes minted under the previous `kid` still decrypt.
+   */
+  keys: Record<string, Uint8Array>;
+}
+interface FieldDecryption {
+  /** Decrypt one `arc.v1` envelope → plaintext string. Throws on tamper/unknown kid. */
+  decryptField(token: string): Promise<string>;
+  /**
+   * Walk a parsed JSON value and decrypt every `arc.v1.*` string in place
+   * (arrays and plain objects recursed; other types untouched). Returns the
+   * same reference for pipeline ergonomics.
+   */
+  decryptFieldsDeep<T>(data: T): Promise<T>;
+}
+/** Parse an `arc.v1` envelope, or `null` when the token isn't one. */
+declare function parseFieldEnvelope(token: string): ParsedFieldEnvelope | null;
+/** True when a value is a well-formed `arc.v1` envelope. */
+declare function isFieldEnvelope(value: unknown): value is string;
+/**
+ * Build the field-mode decryptor. Keys are validated eagerly (fail-fast at
+ * boot, not on the first sensitive response) and imported into Web Crypto
+ * once per `kid`, then cached.
+ */
+declare function createFieldDecryption(options: FieldDecryptionOptions): FieldDecryption;
+//#endregion
+export { FIELD_ENVELOPE_PREFIX, FieldDecryption, FieldDecryptionOptions, ParsedFieldEnvelope, createFieldDecryption, isFieldEnvelope, parseFieldEnvelope };

package/dist/field-encryption.js

@@ -0,0 +1,159 @@
+//#region src/field-encryption.ts
+/**
+* `@classytic/arc-next/field-encryption` — client decrypt for arc's
+* FIELD-mode ALE (`@classytic/arc/encryption` with `mode: 'fields'`).
+*
+* Field-mode responses stay `application/json`; only the configured field
+* VALUES arrive as authenticated `arc.v1` envelopes
+* (`arc.v1.<b64url(kid)>.<b64url(iv)>.<b64url(ct)>.<b64url(tag)>`,
+* AES-256-GCM). This helper parses and decrypts those envelopes with the
+* shared symmetric key, via Web Crypto — zero dependencies, works in Node
+* 22+, Bun, Deno, and React Native (with a Web Crypto polyfill).
+*
+* ── SECURITY: trusted runtimes ONLY ─────────────────────────────────────
+* Field mode is SYMMETRIC — whoever holds the key can decrypt every
+* envelope ever produced under it. That key belongs in a Node BFF, a
+* server component, or a native app's secure storage. It must NEVER ship
+* in a browser bundle: anything readable by browser JavaScript is readable
+* by every visitor. For payloads a browser must decrypt, use the
+* asymmetric JWE path (`@classytic/arc-next/encryption`) instead — that is
+* exactly why this lives in its own subpath the web bundle never imports.
+* ────────────────────────────────────────────────────────────────────────
+*
+* Fail-closed: unknown `kid`, tampered ciphertext, or a malformed
+* `arc.v1.*` token throws — an encrypted field is never silently passed
+* through as ciphertext or dropped.
+*
+* @example Node BFF / server component
+* ```ts
+* import { createFieldDecryption } from '@classytic/arc-next/field-encryption';
+*
+* const ale = createFieldDecryption({
+*   // 32-byte AES-256 keys by kid — keep the previous kid during rotation.
+*   keys: { 'k-2026-07': keyBytes },
+* });
+*
+* configureClient({
+*   baseUrl: env.ARC_URL,
+*   afterResponse: async (ctx) => {
+*     // arc stamps `x-encrypted: true` on field-mode responses — only
+*     // those are scanned; every other response passes through untouched.
+*     if (ctx.response.headers.get('x-encrypted') === 'true') {
+*       ctx.body = await ale.decryptFieldsDeep(ctx.body);
+*     }
+*     return ctx;
+*   },
+* });
+* ```
+*/
+/** Version prefix shared with `@classytic/arc/encryption`'s field cipher. */
+const FIELD_ENVELOPE_PREFIX = "arc.v1";
+const ENVELOPE_PARTS = 6;
+const KEY_BYTES = 32;
+const decoder = new TextDecoder();
+function b64urlToBytes(part) {
+	const b64 = part.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, "=");
+	const bin = atob(padded);
+	const out = new Uint8Array(bin.length);
+	for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+	return out;
+}
+/** Parse an `arc.v1` envelope, or `null` when the token isn't one. */
+function parseFieldEnvelope(token) {
+	if (typeof token !== "string") return null;
+	const parts = token.split(".");
+	if (parts.length !== ENVELOPE_PARTS) return null;
+	const [v0, v1, kidPart, ivPart, ctPart, tagPart] = parts;
+	if (`${v0}.${v1}` !== "arc.v1") return null;
+	if (!kidPart || !ivPart || !ctPart || !tagPart) return null;
+	try {
+		return {
+			kid: decoder.decode(b64urlToBytes(kidPart)),
+			iv: b64urlToBytes(ivPart),
+			ciphertext: b64urlToBytes(ctPart),
+			tag: b64urlToBytes(tagPart)
+		};
+	} catch {
+		return null;
+	}
+}
+/** True when a value LOOKS like an envelope (prefix match — cheap scan gate). */
+function hasEnvelopePrefix(value) {
+	return typeof value === "string" && value.startsWith(`${"arc.v1"}.`);
+}
+/** True when a value is a well-formed `arc.v1` envelope. */
+function isFieldEnvelope(value) {
+	return hasEnvelopePrefix(value) && parseFieldEnvelope(value) !== null;
+}
+/**
+* Build the field-mode decryptor. Keys are validated eagerly (fail-fast at
+* boot, not on the first sensitive response) and imported into Web Crypto
+* once per `kid`, then cached.
+*/
+function createFieldDecryption(options) {
+	const kids = Object.keys(options.keys);
+	if (kids.length === 0) throw new Error("[arc-next/field-encryption] at least one key is required.");
+	for (const kid of kids) {
+		const key = options.keys[kid];
+		if (!(key instanceof Uint8Array) || key.length !== KEY_BYTES) throw new Error(`[arc-next/field-encryption] key '${kid}' must be a ${KEY_BYTES}-byte Uint8Array (AES-256).`);
+	}
+	const imported = /* @__PURE__ */ new Map();
+	function keyFor(kid) {
+		let p = imported.get(kid);
+		if (!p) {
+			const raw = options.keys[kid];
+			if (!raw) throw new Error(`[arc-next/field-encryption] no key for kid '${kid}' — keep the previous kid configured during rotation so in-flight envelopes still decrypt.`);
+			p = crypto.subtle.importKey("raw", raw, { name: "AES-GCM" }, false, ["decrypt"]);
+			imported.set(kid, p);
+		}
+		return p;
+	}
+	async function decryptField(token) {
+		const envelope = parseFieldEnvelope(token);
+		if (!envelope) throw new Error("[arc-next/field-encryption] malformed arc.v1 envelope.");
+		const key = await keyFor(envelope.kid);
+		const combined = new Uint8Array(envelope.ciphertext.length + envelope.tag.length);
+		combined.set(envelope.ciphertext);
+		combined.set(envelope.tag, envelope.ciphertext.length);
+		try {
+			const plaintext = await crypto.subtle.decrypt({
+				name: "AES-GCM",
+				iv: envelope.iv
+			}, key, combined);
+			return decoder.decode(plaintext);
+		} catch {
+			throw new Error(`[arc-next/field-encryption] decryption failed for kid '${envelope.kid}' — tampered ciphertext or wrong key.`);
+		}
+	}
+	async function walk(node) {
+		if (Array.isArray(node)) {
+			for (let i = 0; i < node.length; i++) {
+				const value = node[i];
+				if (hasEnvelopePrefix(value)) node[i] = await decryptField(value);
+				else await walk(value);
+			}
+			return;
+		}
+		if (node !== null && typeof node === "object") {
+			const record = node;
+			for (const prop of Object.keys(record)) {
+				const value = record[prop];
+				if (hasEnvelopePrefix(value)) record[prop] = await decryptField(value);
+				else await walk(value);
+			}
+		}
+	}
+	async function decryptFieldsDeep(data) {
+		if (hasEnvelopePrefix(data)) return await decryptField(data);
+		await walk(data);
+		return data;
+	}
+	return {
+		decryptField,
+		decryptFieldsDeep
+	};
+}
+
+//#endregion
+export { FIELD_ENVELOPE_PREFIX, createFieldDecryption, isFieldEnvelope, parseFieldEnvelope };

package/dist/hooks.d.ts

@@ -89,6 +89,14 @@ interface CrudHooksConfig<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
     gcTime?: number;
     refetchOnWindowFocus?: boolean;
     structuralSharing?: boolean;
+    /**
+     * Declare this resource's read endpoints PUBLIC (`allowPublic` on the
+     * server — e.g. a storefront catalog). Read hooks then enable token-less
+     * requests by default, so callers never have to pass `{ public: true }`
+     * per hook. Leave unset for auth-gated resources (cart, orders, account) —
+     * they keep the bearer token-gate. An explicit per-call `public` wins.
+     */
+    defaultPublic?: boolean;
     messages?: {
       createSuccess?: string;
       createError?: string;

package/dist/hooks.js

@@ -2,7 +2,7 @@
 
 import { getAuthMode, getClientAuthContext, hasGlobalStaticAuth } from "./client.js";
 import { isKeysetPagination, isOffsetPagination } from "./api.js";
-import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, syncDetailToLists, updateListCache } from "./cache.js";
+import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, syncDetailToLists, updateListCache, withOrgParams } from "./cache.js";
 import { findItemInListCache, useDetailQuery, useInfiniteListQuery, useListQuery, useSuspenseDetailQuery, useSuspenseListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
 import { subscribeToEvents } from "./sse.js";
@@ -75,6 +75,13 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			...defaults.messages
 		}
 	};
+	const computeEnabled = (token, options, extraGate = true) => {
+		const merged = options.public === void 0 && config.defaultPublic ? {
+			...options,
+			public: true
+		} : options;
+		return extraGate && createEnabledRule(token, merged, resolveAuthMode(), resolveHasStaticAuth());
+	};
 	function useList(tokenOrParams, paramsOrOptions, maybeOptions) {
 		let token;
 		let params;
@@ -97,10 +104,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const scope = options._scope || (organizationId ? "tenant" : "super-admin");
 		const { request: requestOpts, ...queryOpts } = options;
 		return useListQuery({
-			queryKey: KEYS.scopedList(scope, {
-				organizationId,
-				...restParams
-			}),
+			queryKey: KEYS.scopedList(scope, withOrgParams(organizationId, restParams)),
 			queryFn: ({ signal }) => api.getAll({
 				token,
 				organizationId,
@@ -110,7 +114,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime,
@@ -154,7 +158,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, restOptions, !!id),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -491,10 +495,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const scope = options._scope || (organizationId ? "tenant" : "super-admin");
 		const { request: requestOpts, ...queryOpts } = options;
 		return useInfiniteListQuery({
-			queryKey: [...KEYS.scopedList(scope, {
-				organizationId,
-				...restParams
-			}), "infinite"],
+			queryKey: [...KEYS.scopedList(scope, withOrgParams(organizationId, restParams)), "infinite"],
 			queryFn: ({ pageParam, signal }) => {
 				const paginationParams = typeof pageParam === "string" ? { after: pageParam } : { page: pageParam };
 				return api.getAll({
@@ -510,7 +511,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts),
 			initialPageParam: restParams.after ? restParams.after : 1,
 			getNextPageParam: (lastPage) => {
 				const page = lastPage;
@@ -579,10 +580,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const { organizationId: _, ...restParams } = mergedParams;
 		const { request: requestOpts, ...queryOpts } = options ?? {};
 		return useListQuery({
-			queryKey: KEYS.custom("deleted", {
-				organizationId,
-				...restParams
-			}),
+			queryKey: KEYS.custom("deleted", withOrgParams(organizationId, restParams)),
 			queryFn: ({ signal }) => {
 				if (!api.getDeleted) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getDeleted method`));
 				return api.getDeleted({
@@ -595,7 +593,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts, !!api.getDeleted),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -626,7 +624,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, restOptions, !!api.getBySlug && !!slug),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -654,10 +652,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const { organizationId: _, ...restParams } = mergedParams;
 		const { request: requestOpts, ...queryOpts } = options ?? {};
 		return useListQuery({
-			queryKey: KEYS.custom("tree", {
-				organizationId,
-				...restParams
-			}),
+			queryKey: KEYS.custom("tree", withOrgParams(organizationId, restParams)),
 			queryFn: ({ signal }) => {
 				if (!api.getTree) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getTree method`));
 				return api.getTree({
@@ -670,7 +665,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts, !!api.getTree),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -686,10 +681,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const { organizationId: _, ...restParams } = mergedParams;
 		const { request: requestOpts, ...queryOpts } = options ?? {};
 		return useListQuery({
-			queryKey: KEYS.custom("children", parentId, {
-				organizationId,
-				...restParams
-			}),
+			queryKey: KEYS.custom("children", parentId, withOrgParams(organizationId, restParams)),
 			queryFn: ({ signal }) => {
 				if (!api.getChildren) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getChildren method`));
 				return api.getChildren({
@@ -703,7 +695,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts, !!api.getChildren && !!parentId),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime

package/dist/prefetch.d.ts

@@ -1,3 +1,4 @@
+import { EntityReadApi } from "./query-options.js";
 import { HydrationBoundary, InfiniteData, QueryClient, dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.d.ts
@@ -22,13 +23,6 @@ interface PrefetchOptions extends PrefetchAuthContext {
   revalidate?: number | false;
   tags?: string[];
 }
-/** Per-call API `options` the prefetcher forwards (caching + custom headers). */
-type ForwardedApiOptions = {
-  headerOptions?: Record<string, string>;
-  cache?: RequestCache;
-  revalidate?: number | false;
-  tags?: string[];
-};
 interface PrefetchDetailOptions extends PrefetchOptions {
   /** Query params (select, populate) — key must match useDetail's params to share cache */
   params?: {
@@ -46,11 +40,8 @@ interface CrudPrefetcher {
    */
   prefetchList: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
   /**
-   * Prefetch a detail query on the server. Uses the same query keys as useDetail.
-   *
-   * @example
-   * const queryClient = getQueryClient();
-   * await productsPrefetcher.prefetchDetail(queryClient, productId);
+   * Prefetch a detail query on the server. Uses the same query keys as useDetail
+   * (tenant-scoped when `organizationId` is provided).
    */
   prefetchDetail: (queryClient: QueryClient, id: string, options?: PrefetchDetailOptions) => Promise<void>;
   /**
@@ -68,16 +59,6 @@ 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 });
-   */
   /**
    * Prefetch a declared aggregation (arc 2.13+). Uses the same query key as
    * `useAggregation` so RSC-pre-rendered dashboard rows hydrate without a
@@ -92,12 +73,31 @@ interface CrudPrefetcher {
    * );
    */
   prefetchAggregation: (queryClient: QueryClient, name: string, filter?: 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.
  * Use in Next.js server components to pre-populate the query cache before rendering.
  *
+ * Since 0.10 this is a thin layer over `createEntityQueries`
+ * (@classytic/arc-next/query-options) — the queryOptions factories are the
+ * single source of key + queryFn, shared with the client CRUD hooks, so
+ * prefetch keys can never drift from hook keys. Prefer the factories directly
+ * for new code that also needs `ensureQueryData` / router-loader integration:
+ *
+ *   const products = createEntityQueries(productApi, 'products');
+ *   await queryClient.prefetchQuery({ ...products.list({ limit: 20 }, { token }), staleTime: 60_000 });
+ *
  * @example
  * // products-prefetch.ts
  * import { productsApi } from '@/api/products-api';
@@ -119,45 +119,6 @@ interface CrudPrefetcher {
  *   );
  * }
  */
-declare function createCrudPrefetcher(api: {
-  getAll: (opts: {
-    params?: Record<string, unknown>;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  getById: (opts: {
-    id: string;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  getBySlug?: (opts: {
-    slug: string;
-    token?: string | null;
-    organizationId?: string | null;
-    params?: Record<string, unknown>;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  getDeleted?: (opts: {
-    params?: Record<string, unknown>;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  aggregate?: (opts: {
-    name: string;
-    filter?: Record<string, unknown>;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  getTree?: (opts: {
-    params?: Record<string, unknown>;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-}, entityKey: string): CrudPrefetcher;
+declare function createCrudPrefetcher(api: EntityReadApi, entityKey: string): CrudPrefetcher;
 //#endregion
 export { CrudPrefetcher, HydrationBoundary, type InfiniteData, PrefetchAuthContext, PrefetchDetailOptions, PrefetchOptions, createCrudPrefetcher, dehydrate };