@classytic/arc-next 0.7.0 → 0.8.0

package/dist/client.d.ts

@@ -171,6 +171,39 @@ declare function isValidationError(error: unknown): error is ArcApiError;
  * Prisma P2002 → `arc.conflict` (with `details[].code === 'duplicate_key'`).
  */
 declare function isDuplicateKeyError(error: unknown): error is ArcApiError;
+/**
+ * Application-Layer Encryption (ALE) config — the client half of
+ * `@classytic/arc/encryption`. Lets the SDK decrypt JWE response bodies and
+ * (optionally) encrypt JSON request bodies, transparently to callers and to
+ * the repo-core wire contracts (decryption happens BEFORE error / pagination
+ * parsing, so the parsed shape is identical to an unencrypted response).
+ *
+ * `decrypt` / `encrypt` are host-supplied so the core SDK pulls no crypto
+ * dependency. Use `createJoseEncryption()` from `@classytic/arc-next/encryption`
+ * for a ready-made JWE implementation, or wire your own (KMS proxy, WebCrypto).
+ */
+interface ClientEncryptionConfig {
+  /**
+   * Decrypt an encrypted response body (JWE compact string) → plaintext JSON
+   * string. Required — this is what makes encrypted responses readable.
+   */
+  decrypt: (payload: string) => string | Promise<string>;
+  /**
+   * Encrypt a serialized JSON request body string → JWE compact string.
+   * Required only when `encryptRequests` is true.
+   */
+  encrypt?: (json: string) => string | Promise<string>;
+  /**
+   * Encrypt outbound JSON request bodies. Default `false` — responses are
+   * still decrypted regardless (the common case: server encrypts responses,
+   * client posts plaintext over TLS).
+   */
+  encryptRequests?: boolean;
+  /** Response media type signalling an encrypted body. Default `'application/jose'`. */
+  responseContentType?: string;
+  /** Content-Type set on encrypted outbound requests. Default `'application/jose'`. */
+  requestContentType?: string;
+}
 interface ClientConfig {
   baseUrl: string;
   internalApiKey?: string;
@@ -253,6 +286,13 @@ interface ClientConfig {
    * });
    */
   afterResponse?: AfterResponseInterceptor;
+  /**
+   * Application-Layer Encryption. When set, the SDK decrypts `application/jose`
+   * response bodies (and, with `encryptRequests`, encrypts JSON request bodies)
+   * — the client counterpart to `@classytic/arc/encryption` on the backend.
+   * Transparent to repo-core wire contracts. See {@link ClientEncryptionConfig}.
+   */
+  encryption?: ClientEncryptionConfig;
 }
 interface RetryConfig {
   /** Total attempts including the first. `attempts: 3` means 1 try + 2 retries. Default: 0 (off). */
@@ -795,4 +835,4 @@ declare const arc: {
   delete: <T = unknown>(path: string, opts?: ArcFetchOptions) => Promise<T>;
 };
 //#endregion
-export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };

package/dist/client.js

@@ -585,16 +585,48 @@ function createClient(config) {
 * });
 */
 function createAuthAwareClient(overrides = {}) {
-	return createClient({
-		baseUrl: overrides.baseUrl ?? getBaseUrl(),
-		authMode: overrides.authMode ?? getAuthMode(),
-		autoIdempotency: overrides.autoIdempotency ?? isAutoIdempotency(),
-		elevated: overrides.elevated ?? clientConfig?.elevated,
-		...overrides,
-		getToken: overrides.getToken ?? (() => readToken(authConfig?.getToken)),
-		getOrgId: overrides.getOrgId ?? (() => authConfig?.getOrgId?.() ?? null),
-		headerName: overrides.headerName ?? authConfig?.headerName
+	const { toast, navigation, getToken, getOrgId, headerName, ...overrideCfg } = overrides;
+	const authGetToken = getToken ?? (() => readToken(authConfig?.getToken));
+	const authGetOrgId = getOrgId ?? (() => authConfig?.getOrgId?.() ?? null);
+	const authHeaderName = headerName ?? authConfig?.headerName;
+	const clientAuth = {
+		getToken: authGetToken,
+		getOrgId: authGetOrgId,
+		headerName: authHeaderName
+	};
+	const resolveClientCfg = () => ({
+		baseUrl: overrideCfg.baseUrl ?? getBaseUrl(),
+		authMode: overrideCfg.authMode ?? getAuthMode(),
+		autoIdempotency: overrideCfg.autoIdempotency ?? isAutoIdempotency(),
+		elevated: overrideCfg.elevated ?? clientConfig?.elevated,
+		internalApiKey: overrideCfg.internalApiKey ?? clientConfig?.internalApiKey,
+		defaultHeaders: overrideCfg.defaultHeaders ?? clientConfig?.defaultHeaders,
+		credentials: overrideCfg.credentials ?? clientConfig?.credentials,
+		apiVersion: overrideCfg.apiVersion ?? clientConfig?.apiVersion,
+		retry: overrideCfg.retry ?? clientConfig?.retry,
+		beforeRequest: overrideCfg.beforeRequest ?? clientConfig?.beforeRequest,
+		afterResponse: overrideCfg.afterResponse ?? clientConfig?.afterResponse
 	});
+	return {
+		request: (method, endpoint, options) => {
+			const cfg = resolveClientCfg();
+			const resolved = { ...options };
+			if (resolved.token === void 0) resolved.token = readToken(authGetToken);
+			if (resolved.organizationId === void 0) resolved.organizationId = authGetOrgId();
+			if (cfg.authMode === "header" && resolved.token) {
+				resolved.headerOptions = {
+					[authHeaderName ?? "x-api-key"]: resolved.token,
+					...resolved.headerOptions ?? {}
+				};
+				resolved.token = void 0;
+			}
+			return executeRequest(cfg, method, endpoint, resolved);
+		},
+		config: resolveClientCfg(),
+		toast,
+		navigation,
+		auth: clientAuth
+	};
 }
 /**
 * Get auth context for a specific client instance, falling back to global.
@@ -731,6 +763,11 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 		const credentials = config.credentials ?? (config.authMode === "cookie" ? "include" : "same-origin");
 		let serializedBody = void 0;
 		if (body !== void 0 && body !== null) serializedBody = isNonJsonBody(body) ? body : JSON.stringify(body);
+		const encryption = config.encryption;
+		if (encryption?.encryptRequests && encryption.encrypt && typeof serializedBody === "string") {
+			serializedBody = await encryption.encrypt(serializedBody);
+			headers["Content-Type"] = encryption.requestContentType ?? "application/jose";
+		}
 		if (config.beforeRequest) {
 			const ctx = await config.beforeRequest({
 				method,
@@ -759,6 +796,7 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			...fetchOptions.next,
 			tags
 		};
+		if (!/^https?:\/\//i.test(endpoint) && !config.baseUrl) throw new Error(`[arc-next] handleApiRequest(${method} ${endpoint}): baseUrl is empty. Call configureClient({ baseUrl: '...' }) BEFORE the first request. If you use createAuthAwareClient() at module top-level, make sure the Providers component runs configureClient() first (e.g. in a useState() initializer, before the children render).`);
 		const response = await fetch(`${config.baseUrl}${endpoint}`, fetchOptions);
 		if (!response.ok) {
 			let json = null;
@@ -766,7 +804,7 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			try {
 				json = await response.clone().json();
 				const j = json;
-				errorMessage = typeof j?.error === "string" && j.error || typeof j?.message === "string" && j.message || response.statusText;
+				errorMessage = typeof j?.error === "string" && j.error || typeof j?.meta?.message === "string" && j.meta.message || typeof j?.message === "string" && j.message || response.statusText;
 			} catch {
 				try {
 					const text = await response.text();
@@ -786,7 +824,12 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 		}
 		const contentType = response.headers.get("Content-Type");
 		let data;
-		if (contentType?.includes("application/json")) data = await response.json();
+		const decryptCt = encryption ? encryption.responseContentType ?? "application/jose" : void 0;
+		if (encryption && decryptCt && contentType?.includes(decryptCt)) {
+			const cipher = await response.text();
+			const plaintext = cipher.length > 0 ? await encryption.decrypt(cipher) : "";
+			data = plaintext.length > 0 ? JSON.parse(plaintext) : void 0;
+		} else if (contentType?.includes("application/json")) data = await response.json();
 		else if (contentType?.includes("application/pdf") || contentType?.includes("image/")) data = {
 			data: await response.blob(),
 			response

package/dist/encryption.d.ts

@@ -0,0 +1,36 @@
+import { ClientEncryptionConfig } from "./client.js";
+
+//#region src/encryption.d.ts
+/** Key material accepted by jose in browser + Node (Web Crypto). */
+type JoseKey = CryptoKey | Uint8Array;
+interface JoseEncryptionOptions {
+  /** Single decryption key (private/secret) used for every response. */
+  decryptionKey?: JoseKey;
+  /**
+   * Decryption keys indexed by `kid` (rotation). When set, the inbound JWE's
+   * `kid` header selects the key — keep 2–3 entries across a rotation so
+   * in-flight responses signed with the previous `kid` still decrypt.
+   */
+  decryptionKeys?: Record<string, JoseKey>;
+  /** Public/secret key + `kid` used to encrypt outbound requests. */
+  encryptionKey?: {
+    kid: string;
+    key: JoseKey;
+    alg?: string;
+  };
+  /** Key-management algorithm. Default `'RSA-OAEP-256'`. */
+  alg?: string;
+  /** Content-encryption algorithm. Default `'A256GCM'`. */
+  enc?: string;
+  /** Inbound-decryption allowlists (anti-downgrade). Default `[alg]` / `[enc]`. */
+  allowedAlgs?: string[];
+  allowedEncs?: string[];
+}
+/**
+ * Build the `encrypt` / `decrypt` half of a {@link ClientEncryptionConfig}
+ * using `jose`. Spread the result into `encryption` and add `encryptRequests`
+ * / content-type overrides as needed.
+ */
+declare function createJoseEncryption(options: JoseEncryptionOptions): Pick<ClientEncryptionConfig, 'encrypt' | 'decrypt'>;
+//#endregion
+export { JoseEncryptionOptions, createJoseEncryption };

package/dist/encryption.js

@@ -0,0 +1,75 @@
+import { CompactEncrypt, compactDecrypt } from "jose";
+
+//#region src/encryption.ts
+/**
+* `@classytic/arc-next/encryption` — JWE helper for the client SDK.
+*
+* A ready-made `ClientEncryptionConfig` backed by `jose` (panva) — the same
+* library `@classytic/arc/encryption` uses server-side. Works in the browser
+* and Node (jose runs on Web Crypto). `jose` is an OPTIONAL peer: import this
+* subpath only when you want JWE; the core SDK pulls no crypto dependency.
+*
+* Asymmetric key model (mirrors Visa MLE / the arc backend plugin):
+*   - Decrypt RESPONSES with the client's PRIVATE key (the recipient).
+*   - Encrypt REQUESTS with the SERVER's PUBLIC key, tagged by `kid`.
+*
+* @example
+* ```ts
+* import { configureClient } from "@classytic/arc-next/client";
+* import { createJoseEncryption } from "@classytic/arc-next/encryption";
+* import { importPKCS8, importSPKI } from "jose";
+*
+* configureClient({
+*   baseUrl: "https://api.example.com",
+*   encryption: {
+*     ...createJoseEncryption({
+*       decryptionKeys: { "client-1": await importPKCS8(clientPrivPem, "RSA-OAEP-256") },
+*       encryptionKey: { kid: "server-1", key: await importSPKI(serverPubPem, "RSA-OAEP-256") },
+*     }),
+*     encryptRequests: true,
+*   },
+* });
+* ```
+*/
+/**
+* Build the `encrypt` / `decrypt` half of a {@link ClientEncryptionConfig}
+* using `jose`. Spread the result into `encryption` and add `encryptRequests`
+* / content-type overrides as needed.
+*/
+function createJoseEncryption(options) {
+	const alg = options.alg ?? "RSA-OAEP-256";
+	const enc = options.enc ?? "A256GCM";
+	const allowedAlgs = options.allowedAlgs ?? [alg];
+	const allowedEncs = options.allowedEncs ?? [enc];
+	const decoder = new TextDecoder();
+	const encoder = new TextEncoder();
+	const decrypt = async (payload) => {
+		const { plaintext } = await compactDecrypt(payload, async (header) => {
+			if (options.decryptionKeys) {
+				const key = header.kid ? options.decryptionKeys[header.kid] : void 0;
+				if (!key) throw new Error(`[arc-next/encryption] no decryption key for kid '${header.kid ?? "<none>"}'`);
+				return key;
+			}
+			if (!options.decryptionKey) throw new Error("[arc-next/encryption] no decryption key configured");
+			return options.decryptionKey;
+		}, {
+			keyManagementAlgorithms: allowedAlgs,
+			contentEncryptionAlgorithms: allowedEncs
+		});
+		return decoder.decode(plaintext);
+	};
+	const encryptionKey = options.encryptionKey;
+	if (!encryptionKey) return { decrypt };
+	const encrypt = async (json) => new CompactEncrypt(encoder.encode(json)).setProtectedHeader({
+		alg: encryptionKey.alg ?? alg,
+		enc,
+		kid: encryptionKey.kid
+	}).encrypt(encryptionKey.key);
+	return {
+		encrypt,
+		decrypt
+	};
+}
+
+//#endregion
+export { createJoseEncryption };

package/dist/hooks.d.ts

@@ -180,6 +180,18 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
     /** New signature — auto-injects token from configureAuth() context */(id: string | null, options?: DetailQueryOptions<T>): DetailQueryResult<T>; /** Legacy signature — explicit token */
     (id: string | null, token: string | null, options?: DetailQueryOptions<T>): DetailQueryResult<T>;
   };
+  /**
+   * Suspense variant of `useList` for Suspense / streaming-SSR routes. Always
+   * fetches and SUSPENDS until resolved — wrap the subtree in `<Suspense>` and
+   * an error boundary. No `enabled` gate and no `keepPreviousData` preview
+   * (TanStack forbids both on suspense queries); `isLoading` is always `false`.
+   */
+  useSuspenseList: (params?: Record<string, unknown>, options?: Omit<ListQueryOptions<T>, "enabled">) => ListQueryResult<T>;
+  /**
+   * Suspense variant of `useDetail`. `id` must be present (it always fetches).
+   * Suspends until resolved; no list→detail `placeholderData` preview.
+   */
+  useSuspenseDetail: (id: string, options?: Omit<DetailQueryOptions<T>, "enabled">) => DetailQueryResult<T>;
   useInfiniteList: {
     /** New signature — auto-injects token/orgId from configureAuth() context */(params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>; /** Legacy signature — explicit token */
     (token: string | null, params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>;

package/dist/hooks.js

@@ -3,7 +3,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 { findItemInListCache, useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
+import { findItemInListCache, useDetailQuery, useInfiniteListQuery, useListQuery, useSuspenseDetailQuery, useSuspenseListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
 import { subscribeToEvents } from "./sse.js";
 import { connectWs } from "./ws.js";
@@ -176,6 +176,82 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		]);
 		return detailResult;
 	}
+	function useSuspenseList(params = {}, options = {}) {
+		const auth = resolveAuth();
+		const token = auth.token;
+		let resolvedParams = params;
+		if (auth.organizationId && !resolvedParams.organizationId) resolvedParams = {
+			...resolvedParams,
+			organizationId: auth.organizationId
+		};
+		const { organizationId, ...restParams } = resolvedParams;
+		const scope = options._scope || (organizationId ? "tenant" : "super-admin");
+		const { request: requestOpts, ...queryOpts } = options;
+		return useSuspenseListQuery({
+			queryKey: KEYS.scopedList(scope, {
+				organizationId,
+				...restParams
+			}),
+			queryFn: ({ signal }) => api.getAll({
+				token,
+				organizationId,
+				params: restParams,
+				options: {
+					signal,
+					...requestOpts
+				}
+			}),
+			options: {
+				staleTime: queryOpts.staleTime ?? config.staleTime,
+				gcTime: queryOpts.gcTime ?? config.gcTime,
+				refetchOnWindowFocus: queryOpts.refetchOnWindowFocus ?? config.refetchOnWindowFocus,
+				structuralSharing: queryOpts.structuralSharing ?? config.structuralSharing,
+				refetchInterval: queryOpts.refetchInterval,
+				refetchIntervalInBackground: queryOpts.refetchIntervalInBackground
+			},
+			select: queryOpts.select
+		});
+	}
+	function useSuspenseDetail(id, options = {}) {
+		const auth = resolveAuth();
+		const token = auth.token;
+		let opts = options;
+		if (auth.organizationId && !opts.organizationId) opts = {
+			...opts,
+			organizationId: auth.organizationId
+		};
+		const { organizationId, params: queryParams, request: requestOpts, ...restOptions } = opts;
+		const detailKey = KEYS.scopedDetail(id, organizationId ?? null);
+		const fullDetailKey = queryParams ? [...detailKey, queryParams] : detailKey;
+		const queryClient = useQueryClient();
+		const detailResult = useSuspenseDetailQuery({
+			queryKey: fullDetailKey,
+			queryFn: ({ signal }) => api.getById({
+				id,
+				token,
+				organizationId,
+				params: queryParams,
+				options: {
+					signal,
+					...requestOpts
+				}
+			}),
+			options: {
+				staleTime: restOptions.staleTime ?? config.staleTime,
+				gcTime: restOptions.gcTime ?? config.gcTime,
+				refetchOnWindowFocus: restOptions.refetchOnWindowFocus ?? config.refetchOnWindowFocus,
+				structuralSharing: restOptions.structuralSharing ?? config.structuralSharing,
+				refetchInterval: restOptions.refetchInterval,
+				refetchIntervalInBackground: restOptions.refetchIntervalInBackground
+			},
+			select: restOptions.select
+		});
+		useEffect(() => {
+			if (!detailResult.item) return;
+			syncDetailToLists(queryClient, KEYS.lists(), detailResult.item, idField ? { idField } : {});
+		}, [detailResult.item, queryClient]);
+		return detailResult;
+	}
 	function useActions() {
 		const queryClient = useQueryClient();
 		const silentRef = useRef(false);
@@ -956,6 +1032,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		cache,
 		useList,
 		useDetail,
+		useSuspenseList,
+		useSuspenseDetail,
 		useInfiniteList,
 		useActions,
 		useBulkActions,

package/dist/query.d.ts

@@ -57,8 +57,28 @@ interface DetailQueryOptions<TData = unknown> {
   /** Pass-through options for the underlying fetch request (cache, revalidate, tags, headers) */
   request?: RequestPassthrough;
 }
+/**
+ * Result of `useList` (and `useListQuery`). Matches the same typed-end-to-end
+ * shape `repo-core` uses for its server-side result interfaces (`AggResult`,
+ * `OffsetPaginationResult`, etc.) — no raw-cache escape hatch on the public
+ * surface, just the typed extracted view.
+ *
+ * Need the raw cache entry? Use `useQueryClient().getQueryData(KEYS.list(...))`
+ * — it's typed against whatever `setQueryData` last wrote, and it makes the
+ * "I'm reaching past the SDK" intent explicit.
+ */
 interface ListQueryResult<T> {
+  /**
+   * Extracted items array — `T[]`. Always typed, always flat (infinite-list
+   * pages are pre-flattened), always consistent across response-shape
+   * variants (`data` / `items` / `results` / any-array fallback).
+   */
   items: T[];
+  /**
+   * Normalized pagination snapshot — offset / keyset / aggregate all map
+   * onto the same `{ method, total, pages, page, limit, hasNext, hasPrev, next? }`
+   * shape. `null` when the response carries no pagination signal.
+   */
   pagination: PaginationData | null;
   isLoading: boolean;
   isFetching: boolean;
@@ -67,9 +87,22 @@ interface ListQueryResult<T> {
   isStale: boolean;
   error: Error | null;
   refetch: () => Promise<unknown>;
-  data: unknown;
 }
+/**
+ * Result of `useDetail` (and `useDetailQuery`). Matches the typed-end-to-end
+ * shape repo-core uses for its result interfaces — no raw-cache escape
+ * hatch on the public surface, just the typed extracted view.
+ *
+ * Need the raw cache entry? `useQueryClient().getQueryData(KEYS.detail(id))`
+ * — typed against whatever `setQueryData` last wrote, and the explicit
+ * `getQueryData` call signals "I'm reaching past the SDK" at the call site.
+ */
 interface DetailQueryResult<T> {
+  /**
+   * The extracted entity — `T | null`. Always typed, always the raw doc
+   * (not a wrapper), always consistent with what `prefetchDetail` /
+   * `cache.getDetail` / `useNavigation` write back.
+   */
   item: T | null;
   isLoading: boolean;
   isFetching: boolean;
@@ -85,7 +118,6 @@ interface DetailQueryResult<T> {
   isPlaceholderData: boolean;
   error: Error | null;
   refetch: () => Promise<unknown>;
-  data: unknown;
 }
 interface CreateListQueryConfig {
   queryKey: QueryKey;
@@ -163,6 +195,20 @@ declare function useDetailQuery<T>({
   select,
   placeholderData
 }: CreateDetailQueryConfig<T>): DetailQueryResult<T>;
+/** Suspense variant of {@link useListQuery}. Always enabled; suspends until resolved. */
+declare function useSuspenseListQuery<T>({
+  queryKey,
+  queryFn,
+  options,
+  select
+}: Omit<CreateListQueryConfig, "enabled">): ListQueryResult<T>;
+/** Suspense variant of {@link useDetailQuery}. Always enabled; suspends until resolved. */
+declare function useSuspenseDetailQuery<T>({
+  queryKey,
+  queryFn,
+  options,
+  select
+}: Omit<CreateDetailQueryConfig<T>, "enabled" | "placeholderData">): DetailQueryResult<T>;
 interface InfiniteListQueryOptions {
   public?: boolean;
   enabled?: boolean;
@@ -305,4 +351,4 @@ declare function useApiQuery<TResponse = unknown, TData = ExtractData<TResponse>
   options
 }: UseApiQueryConfig<TResponse, TData>): UseApiQueryResult<TData>;
 //#endregion
-export { type CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, ExtractData, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, type PaginationData, QUERY_CONFIGS, QueryFreshness, type QueryKeys, RequestPassthrough, UseApiQueryConfig, UseApiQueryOptions, UseApiQueryResult, createCacheUtils, createQueryKeys, extractItem, extractItems, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { type CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, ExtractData, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, type PaginationData, QUERY_CONFIGS, QueryFreshness, type QueryKeys, RequestPassthrough, UseApiQueryConfig, UseApiQueryOptions, UseApiQueryResult, createCacheUtils, createQueryKeys, extractItem, extractItems, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery, useSuspenseDetailQuery, useSuspenseListQuery };

package/dist/query.js

@@ -1,7 +1,7 @@
 "use client";
 
 import { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache } from "./cache.js";
-import { keepPreviousData, useInfiniteQuery, useQuery } from "@tanstack/react-query";
+import { keepPreviousData, useInfiniteQuery, useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { useCallback, useMemo, useRef } from "react";
 
 //#region src/query.ts
@@ -39,8 +39,7 @@ function useListQuery({ queryKey, queryFn, enabled = true, options = {}, select
 		isSuccess: query.isSuccess,
 		isStale: query.isStale,
 		error: query.error,
-		refetch: query.refetch,
-		data: query.data
+		refetch: query.refetch
 	};
 }
 /**
@@ -97,8 +96,49 @@ function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, selec
 		isStale: query.isStale,
 		isPlaceholderData: query.isPlaceholderData,
 		error: query.error,
-		refetch: query.refetch,
-		data: query.data
+		refetch: query.refetch
+	};
+}
+/** Suspense variant of {@link useListQuery}. Always enabled; suspends until resolved. */
+function useSuspenseListQuery({ queryKey, queryFn, options = {}, select }) {
+	const query = useSuspenseQuery({
+		queryKey,
+		queryFn: ({ signal }) => queryFn({ signal }),
+		...DEFAULT_QUERY_CONFIG,
+		...options,
+		...select ? { select } : {}
+	});
+	return {
+		items: useMemo(() => extractItems(query.data), [query.data]),
+		pagination: useMemo(() => normalizePagination(query.data), [query.data]),
+		isLoading: false,
+		isFetching: query.isFetching,
+		isError: query.isError,
+		isSuccess: query.isSuccess,
+		isStale: query.isStale,
+		error: query.error,
+		refetch: query.refetch
+	};
+}
+/** Suspense variant of {@link useDetailQuery}. Always enabled; suspends until resolved. */
+function useSuspenseDetailQuery({ queryKey, queryFn, options = {}, select }) {
+	const query = useSuspenseQuery({
+		queryKey,
+		queryFn: ({ signal }) => queryFn({ signal }),
+		...DEFAULT_QUERY_CONFIG,
+		...options,
+		...select ? { select } : {}
+	});
+	return {
+		item: extractItem(query.data),
+		isLoading: false,
+		isFetching: query.isFetching,
+		isError: query.isError,
+		isSuccess: query.isSuccess,
+		isStale: query.isStale,
+		isPlaceholderData: false,
+		error: query.error,
+		refetch: query.refetch
 	};
 }
 function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {}, initialPageParam = 1, getNextPageParam, getPreviousPageParam, maxPages }) {
@@ -191,4 +231,4 @@ function useApiQuery({ queryKey, queryFn, enabled = true, freshness, select, opt
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery, useSuspenseDetailQuery, useSuspenseListQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,
@@ -38,6 +38,10 @@
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
     },
+    "./encryption": {
+      "types": "./dist/encryption.d.ts",
+      "default": "./dist/encryption.js"
+    },
     "./api": {
       "types": "./dist/api.d.ts",
       "default": "./dist/api.js"
@@ -124,12 +128,14 @@
   "peerDependencies": {
     "@classytic/repo-core": ">=0.4.0",
     "@tanstack/react-query": ">=5.62.0",
+    "jose": ">=5.0.0",
     "react": ">=19.0.0"
   },
   "peerDependenciesMeta": {
     "react": { "optional": false },
     "@tanstack/react-query": { "optional": false },
-    "@classytic/repo-core": { "optional": false }
+    "@classytic/repo-core": { "optional": false },
+    "jose": { "optional": true }
   },
   "devDependencies": {
     "@classytic/dev-tools": "^0.2.0",
@@ -139,6 +145,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "jose": "^6.2.3",
     "jsdom": "^29.0.2",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",